bdc66a5 · c380fb1 · ed073d3 · 4385bdd · fc09698 · 52d4c35
@@ -0,0 +1,40 @@
# Disk readings per machine (#10465)
The forge keeps `smartctl --json` readings of NVMe disks per machine and
device, and shows the bytes written in the last 30 days and the date the
vendor's rated TBW is reached at that rate. The rating comes from
`src/machines/disk_catalog.ts` (vendor figures, not measured); the date is a
projection, never an alert. A model not in the catalog gets a rate and no date;
a drive behind a RAID controller is recorded as such and not assessed.
Who: the owner, a forge admin who is a person. A member, an agent account
(admin or not) and a stranger get 404 on both doors, and nothing is stored.
## File a reading
```
smartctl --json -a /dev/nvme0 | jq -n --slurpfile s /dev/stdin \
  '{smartctl: $s[0], cpu: "AMD EPYC 7302", memoryBytes: 64000000000}' |
  curl -X PUT -H "authorization: Bearer $ADMIN_TOKEN" -H 'content-type: application/json' \
    --data @- "$FORGE_URL/api/v1/admin/machines/rack1/disks/nvme0"
```
`cpu` and `memoryBytes` are optional and update the machine's inventory. A
reading that does not parse, a `cpu` with a control character, or a new
machine past 256 (a new device past 64 on one machine) answers 422 with the
reason and stores nothing. Each write prunes that device's readings older than
60 days, always keeping its newest two.
The token needs `admin` scope.
## Read
- `GET /api/v1/admin/machines/rack1/disks` (any scope of the owner's token):
  per device the latest reading, `bytesWrittenInWindow` over `spanDays` (≤ 30:
  from the oldest reading inside the 30 days before the latest, so a figure for
  30 days only once readings go back that far),
  `ratedReachedAt` and the assessment. A counter that went backwards gives no
  rate and no date.
- The terminal: `:` → "Disks", pick a machine.
Rate: latest reading against the oldest one inside the 30 days before it,
bytes per day = Δbytes ÷ Δdays; date = latest + (rated TBW − written) ÷ rate.
@@ -15,8 +15,6 @@
  "src/flow/review_rounds.ts",
  "src/flow/shared_red.ts",
  "src/flow/stale_fold.ts",
  "src/machines/disk_catalog.ts",
  "src/machines/disk_health.ts",
  "src/spawn/pod.ts",
  "src/tui/gallery.ts",
  "src/tui/ui/qr.ts",
@@ -0,0 +1,41 @@
/**
 * Who writes and who reads a machine's disk readings (#10465). Both are the
 * owner — a forge admin who is a person: a reading is a claim about hardware
 * that decides what the owner replaces, so an agent account neither files nor
 * reads one. Anyone else gets "not_found" here; over the API a signed-in
 * non-admin meets the admin gate's 403 first (`http/admin_gate.ts`).
 */
import type { App } from "../app.ts";
import type { User } from "../core/users.ts";
import { err, ok, type Result } from "../kernel/result.ts";
import { diskSummary, machineNames, recordReading, type Inventory, type MachineSummary } from "../machines/disk_readings.ts";
export const mayHandleDisks = (user: User | undefined): user is User => user !== undefined && user.isAdmin && user.kind !== "agent";
export type FileError = { code: "not_found" } | { code: "invalid"; says: string };
/** Store one reading from smartctl's JSON text for `machine` and `device`. */
export function fileReading(
  app: App,
  actor: User | undefined,
  machine: string,
  device: string,
  smartJsonText: unknown,
  inventory?: Inventory,
): Result<{ kind: "nvme" | "behind-controller"; takenAt: number }, FileError> {
  if (!mayHandleDisks(actor)) return err({ code: "not_found" });
  const r = recordReading(app.db, machine, device, smartJsonText, Date.now(), inventory);
  if (!r.ok) return err({ code: "invalid", says: `Reading refused: ${r.reason}${r.field ? ` (${r.field})` : ""}.` });
  return ok({ kind: r.kind, takenAt: r.takenAt });
}
/** What the readings of one machine say; nothing for anyone but the owner. */
export function readMachine(app: App, actor: User | undefined, machine: string): Result<MachineSummary, "not_found"> {
  if (!mayHandleDisks(actor)) return err("not_found");
  return ok(diskSummary(app.db, machine));
}
/** The machines with readings; nothing for anyone but the owner. */
export function readMachines(app: App, actor: User | undefined): Result<string[], "not_found"> {
  return mayHandleDisks(actor) ? ok(machineNames(app.db)) : err("not_found");
}
@@ -0,0 +1,10 @@
import type { Route } from "../shared.ts";
export const route: Route = {
  method: "get",
  path: "/api/v1/admin/machines/{machine}/disks",
  summary:
    "Read a machine's disk readings (a person admin's token, any scope): per device the latest reading, bytesWrittenInWindow over spanDays (the oldest reading within 30 days of the latest to the latest, so ≤ 30 days, not always 30), ratedReachedAt and the assessment",
  auth: true,
  refusals: { not_found: "the token is not a person who administers the forge, or the machine has no readings" },
};
@@ -41,6 +41,7 @@
export { route as getApiV1AdminDrills } from "./getApiV1AdminDrills.ts";
export { route as getApiV1AdminInvites } from "./getApiV1AdminInvites.ts";
export { route as getApiV1AdminKpisProbe } from "./getApiV1AdminKpisProbe.ts";
export { route as getApiV1AdminLimits } from "./getApiV1AdminLimits.ts";
export { route as getApiV1AdminMachinesMachineDisks } from "./getApiV1AdminMachinesMachineDisks.ts";
export { route as getApiV1AdminMaintenance } from "./getApiV1AdminMaintenance.ts";
export { route as getApiV1AdminPeople } from "./getApiV1AdminPeople.ts";
export { route as getApiV1AdminPinned } from "./getApiV1AdminPinned.ts";
@@ -359,6 +360,7 @@
export { route as postApiV1Users } from "./postApiV1Users.ts";
export { route as postMcp } from "./postMcp.ts";
export { route as putApiV1AdminCapacityKey } from "./putApiV1AdminCapacityKey.ts";
export { route as putApiV1AdminLimitsKey } from "./putApiV1AdminLimitsKey.ts";
export { route as putApiV1AdminMachinesMachineDisksDevice } from "./putApiV1AdminMachinesMachineDisksDevice.ts";
export { route as putApiV1AdminQuotasKey } from "./putApiV1AdminQuotasKey.ts";
export { route as putApiV1AdminShield } from "./putApiV1AdminShield.ts";
export { route as putApiV1AdminTeamsSlug } from "./putApiV1AdminTeamsSlug.ts";
@@ -0,0 +1,10 @@
import type { Route } from "../shared.ts";
export const route: Route = {
  method: "put",
  path: "/api/v1/admin/machines/{machine}/disks/{device}",
  summary: "File a smartctl reading for one disk of a machine (a person admin's token, admin scope); answers 201",
  auth: true,
  body: { smartctl: "smartctl JSON, as text or object", cpu: "string, optional", memoryBytes: "integer, optional" },
  refusals: { invalid: "the reading does not parse (422)", not_found: "the token is not a person who administers the forge" },
};
@@ -0,0 +1,1 @@
6424c1dd3f5515eb89c572a418072d0eefce8b4ea3a291d89cbb7514a2b87052
@@ -0,0 +1,20 @@
// Disk health readings, one row per machine and device and time (#10465), and
// the machine's own CPU and memory. A behind-controller device keeps a row with
// no reading. Additive.
export default `
  CREATE TABLE disk_reading (
    id       INTEGER PRIMARY KEY AUTOINCREMENT,
    machine  TEXT NOT NULL,
    device   TEXT NOT NULL,
    taken_at INTEGER NOT NULL,
    kind     TEXT NOT NULL CHECK (kind IN ('nvme','behind-controller')),
    reading  TEXT
  );
  CREATE INDEX disk_reading_by_device ON disk_reading (machine, device, taken_at);
  CREATE TABLE machine_inventory (
    machine      TEXT PRIMARY KEY,
    cpu          TEXT NOT NULL,
    memory_bytes INTEGER NOT NULL,
    updated_at   INTEGER NOT NULL
  );
  `;
@@ -360,6 +360,7 @@
import { businessPlanRoutes } from "./api/business_plan.ts";
import { tokenRoutes } from "./api/tokens.ts";
import { accountAdmin, adminRoutes } from "./api/admin.ts";
import { maintenanceRoutes } from "./api/maintenance.ts";
import { diskReadingRoutes } from "./api/disk_readings.ts";
import { TEMPLATE_ERRORS } from "../apps/template_tip.ts";
import { flagsRoutes } from "./api/flags.ts";
import { appTemplateRoutes } from "./api/app_templates.ts";
@@ -1247,6 +1248,7 @@
export function apiRoutes(router: Router<Handler>): void {
  forgeOriginRoutes(router);
  adminRoutes(router);
  maintenanceRoutes(router);
  diskReadingRoutes(router);
  flagsRoutes(router);
  appTemplateRoutes(router);
@@ -0,0 +1,42 @@
/**
 * Disk readings over the API (#10465): `PUT /api/v1/admin/machines/:machine/disks/:device`
 * files smartctl's JSON (body `{smartctl, cpu?, memoryBytes?}`, `smartctl` the
 * text or the object); `GET /api/v1/admin/machines/:machine/disks` reads the
 * summary. The owner's admin-scope credential writes, any scope of it reads.
 */
import { fileReading, readMachine } from "../../actions/disk_readings.ts";
import { crossOrigin, type Handler } from "../context.ts";
import { apiError, boundedBody, forbidden, json, notFound, requireScope, unauthorized } from "../respond.ts";
import type { Router } from "../router.ts";
/** smartctl's text is capped at 4 MB by the parser; room for the JSON wrapping it. */
const BODY_MAX = 4_300_000;
export function diskReadingRoutes(router: Router<Handler>): void {
  router.add("GET", "/api/v1/admin/machines/:machine/disks", (ctx) => {
    if (!ctx.auth.user) return unauthorized();
    if (!ctx.auth.user.isAdmin) return notFound();
    const denied = requireScope(ctx, "ro");
    if (denied) return denied;
    const r = readMachine(ctx.app, ctx.auth.user, ctx.params.machine ?? "");
    return r.ok ? json(r.value) : notFound();
  });
  router.add("PUT", "/api/v1/admin/machines/:machine/disks/:device", async (ctx) => {
    if (!ctx.auth.user) return unauthorized();
    if (!ctx.auth.user.isAdmin) return notFound();
    const denied = requireScope(ctx, "admin");
    if (denied) return denied;
    if (ctx.auth.via === "session" && crossOrigin(ctx.request, ctx.url, ctx.app.log)) return forbidden();
    const input = await boundedBody(ctx.request, BODY_MAX);
    if (input === "too_large") return apiError("too_large", 413, "The request is too large.");
    const smart = input["smartctl"];
    const text = typeof smart === "string" ? smart : smart !== null && typeof smart === "object" ? JSON.stringify(smart) : "";
    const inventory =
      input["cpu"] === undefined && input["memoryBytes"] === undefined
        ? undefined
        : { cpu: input["cpu"] as string, memoryBytes: input["memoryBytes"] as number };
    const r = fileReading(ctx.app, ctx.auth.user, ctx.params.machine ?? "", ctx.params.device ?? "", text, inventory);
    if (r.ok) return json(r.value, 201);
    return r.error.code === "invalid" ? apiError("invalid", 422, r.error.says) : notFound();
  });
}
@@ -0,0 +1,189 @@
/**
      
        junipercrew
        1d ago
        
      
      Unreached module: allow-listed instead of wired. Add the caller (intake with identity check, gated read, TUI screen, docs/features page) or hold this back until it exists.
    
 * Disk readings kept per machine and device (#10465), in the forge's own
 * database. A reading is stored only after `parseSmartJson` accepts it.
 *
 * Write rate: the latest reading against the oldest one inside the 30 days
 * before it; bytes per day = Δbytes written ÷ Δdays (a rate over the span
 * actually covered, not a guess beyond it). Projected date: the latest time +
 * (rated TBW × 10^12 B − bytes written) ÷ rate. Ratings are vendor figures
 * (see disk_catalog.ts); the date is a projection, never an alert.
 */
import type { Database } from "bun:sqlite";
import { diskSpec, type DiskSpec } from "./disk_catalog.ts";
import { assessDisk, parseSmartJson, type Assessment, type DiskReading } from "./disk_health.ts";
const DAY_MS = 86_400_000;
export const WINDOW_DAYS = 30;
const NAME = /^[A-Za-z0-9][A-Za-z0-9._:\/-]{0,99}$/;
/** A device keeps readings this many days back (twice the window), and always its newest two. */
export const KEEP_DAYS = 60;
const KEEP_NEWEST = 2;
/** At most this many machines per forge and devices per machine; a new name past either is refused. */
export const MAX_MACHINES = 256;
export const MAX_DEVICES = 64;
/** C0, DEL and C1 controls: any of them could steer the terminal that prints the text. */
const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
/** Text as a terminal may print it: every control character dropped. */
export const printable = (text: string): string => text.replace(new RegExp(CONTROL.source, "g"), "");
export type Inventory = { cpu: string; memoryBytes: number };
export type RecordResult =
  | { ok: true; kind: "nvme" | "behind-controller"; takenAt: number }
  | { ok: false; reason: string; field?: string };
/** Store a reading from smartctl's JSON text; a refusal names its reason and stores nothing. */
export function recordReading(
  db: Database,
  machine: string,
  device: string,
  smartJsonText: unknown,
  now: number = Date.now(),
  inventory?: Inventory,
): RecordResult {
  if (typeof machine !== "string" || !NAME.test(machine)) return { ok: false, reason: "bad-machine" };
  if (typeof device !== "string" || !NAME.test(device)) return { ok: false, reason: "bad-device" };
  if (!Number.isSafeInteger(now) || now < 0) return { ok: false, reason: "bad-time" };
  if (inventory !== undefined) {
    const okInv =
      typeof inventory.cpu === "string" && inventory.cpu.length > 0 && inventory.cpu.length <= 200 && !CONTROL.test(inventory.cpu) &&
      Number.isSafeInteger(inventory.memoryBytes) && inventory.memoryBytes > 0;
    if (!okInv) return { ok: false, reason: "bad-inventory" };
  }
  const parsed = parseSmartJson(smartJsonText);
  if (parsed.kind === "refused") return { ok: false, reason: parsed.reason, ...(parsed.field ? { field: parsed.field } : {}) };
  let refused: string | null = null;
  db.transaction(() => {
    const known = db.query("SELECT 1 FROM disk_reading WHERE machine = ? AND device = ? LIMIT 1").get(machine, device);
    if (!known) {
      const machineKnown = db.query("SELECT 1 FROM disk_reading WHERE machine = ? LIMIT 1").get(machine);
      if (!machineKnown) {
        const { n } = db.query("SELECT COUNT(DISTINCT machine) AS n FROM disk_reading").get() as { n: number };
        if (n >= MAX_MACHINES) return void (refused = "too-many-machines");
      } else {
        const { n } = db.query("SELECT COUNT(DISTINCT device) AS n FROM disk_reading WHERE machine = ?").get(machine) as { n: number };
        if (n >= MAX_DEVICES) return void (refused = "too-many-devices");
      }
    }
    db.query("INSERT INTO disk_reading (machine, device, taken_at, kind, reading) VALUES (?, ?, ?, ?, ?)").run(
      machine, device, now, parsed.kind, parsed.kind === "nvme" ? JSON.stringify(parsed) : null,
    );
    if (inventory)
      db.query(
        `INSERT INTO machine_inventory (machine, cpu, memory_bytes, updated_at) VALUES (?, ?, ?, ?)
         ON CONFLICT(machine) DO UPDATE SET cpu = excluded.cpu, memory_bytes = excluded.memory_bytes, updated_at = excluded.updated_at`,
      ).run(machine, inventory.cpu, inventory.memoryBytes, now);
    // Prune: the summary reads only the newest two and the oldest inside the window.
    db.query(
      `DELETE FROM disk_reading WHERE machine = ?1 AND device = ?2 AND taken_at < ?3
         AND id NOT IN (SELECT id FROM disk_reading WHERE machine = ?1 AND device = ?2 ORDER BY taken_at DESC, id DESC LIMIT ?4)`,
    ).run(machine, device, now - KEEP_DAYS * DAY_MS, KEEP_NEWEST);
  })();
  if (refused) return { ok: false, reason: refused };
  return { ok: true, kind: parsed.kind, takenAt: now };
}
export type DeviceSummary =
  | { device: string; kind: "behind-controller"; takenAt: number; reading: null; spec: null; assessment: null; bytesWrittenInWindow: null; ratedReachedAt: null }
  | {
      device: string;
      kind: "nvme";
      takenAt: number;
      reading: DiskReading;
      inventory: { model: string; firmware: string; capacityBytes: number };
      spec: DiskSpec | null;
      assessment: Assessment;
      /**
       * Bytes written between the oldest reading in the 30 days before the latest and the latest:
       * a 30-day figure only when spanDays is 30. Null with under two readings in the window.
       */
      bytesWrittenInWindow: number | null;
      /** Days that figure spans (≤ 30). */
      spanDays: number | null;
      /** ISO date (UTC) rated TBW is reached at that rate; null with no spec, under two readings, or no growth. */
      ratedReachedAt: string | null;
    };
export type MachineSummary = { machine: string; cpu: string | null; memoryBytes: number | null; devices: DeviceSummary[] };
type Row = { id: number; taken_at: number; kind: string; reading: string | null };
const COLS = "id, taken_at, kind, reading";
export function diskSummary(db: Database, machine: string): MachineSummary {
  const inv = db.query("SELECT cpu, memory_bytes FROM machine_inventory WHERE machine = ?").get(machine) as
    | { cpu: string; memory_bytes: number }
    | null;
  const devices = (db.query("SELECT DISTINCT device FROM disk_reading WHERE machine = ? ORDER BY device").all(machine) as { device: string }[]).map(
    (d) => d.device,
  );
  const out: DeviceSummary[] = [];
  for (const device of devices) {
    // Three bounded reads on (machine, device, taken_at): the latest row, the
    // newest two NVMe readings, and the oldest NVMe reading inside the window.
    const latest = db
      .query(`SELECT ${COLS} FROM disk_reading WHERE machine = ? AND device = ? ORDER BY taken_at DESC, id DESC LIMIT 1`)
      .get(machine, device) as Row;
    if (latest.kind !== "nvme" || latest.reading === null) {
      out.push({ device, kind: "behind-controller", takenAt: latest.taken_at, reading: null, spec: null, assessment: null, bytesWrittenInWindow: null, ratedReachedAt: null });
      continue;
    }
    const nvme = db
      .query(
        `SELECT ${COLS} FROM disk_reading WHERE machine = ? AND device = ? AND kind = 'nvme' AND reading IS NOT NULL
         ORDER BY taken_at DESC, id DESC LIMIT 2`,
      )
      .all(machine, device) as Row[];
    const reading = JSON.parse(nvme[0]!.reading!) as DiskReading;
    const previous = nvme[1] ? (JSON.parse(nvme[1].reading!) as DiskReading) : null;
    const spec = diskSpec(reading.model);
    const windowStart = latest.taken_at - WINDOW_DAYS * DAY_MS;
    const base = db
      .query(
        `SELECT ${COLS} FROM disk_reading WHERE machine = ? AND device = ? AND kind = 'nvme' AND reading IS NOT NULL
         AND taken_at >= ? AND id != ? ORDER BY taken_at ASC, id ASC LIMIT 1`,
      )
      .get(machine, device, windowStart, nvme[0]!.id) as Row | null;
    let bytes30: number | null = null;
    let spanDays: number | null = null;
    let reached: string | null = null;
    if (base && base.taken_at < latest.taken_at) {
      const baseReading = JSON.parse(base.reading!) as DiskReading;
      const delta = reading.bytesWritten - baseReading.bytesWritten;
      if (delta >= 0) {
        bytes30 = delta;
        spanDays = (latest.taken_at - base.taken_at) / DAY_MS;
        if (spec) {
          const remaining = spec.ratedTbw * 1e12 - reading.bytesWritten;
          if (remaining <= 0) reached = new Date(latest.taken_at).toISOString().slice(0, 10);
          else if (delta > 0) {
            const perDay = delta / spanDays;
            const at = new Date(latest.taken_at + (remaining / perDay) * DAY_MS);
            // A rate so small the date leaves the calendar is no projection.
            if (at.getUTCFullYear() <= 9999) reached = at.toISOString().slice(0, 10);
          }
        }
      }
    }
    out.push({
      device,
      kind: "nvme",
      takenAt: latest.taken_at,
      reading,
      inventory: { model: reading.model, firmware: reading.firmware, capacityBytes: reading.capacityBytes },
      spec,
      assessment: assessDisk(reading, previous, spec),
      bytesWrittenInWindow: bytes30,
      spanDays,
      ratedReachedAt: reached,
    });
  }
  return { machine, cpu: inv?.cpu ?? null, memoryBytes: inv?.memory_bytes ?? null, devices: out };
}
/** Machine names that have a reading or an inventory, A to Z. */
export function machineNames(db: Database): string[] {
  return (
    db.query("SELECT machine FROM disk_reading UNION SELECT machine FROM machine_inventory ORDER BY machine").all() as { machine: string }[]
  ).map((r) => r.machine);
}
@@ -0,0 +1,85 @@
/**
 * Disk readings in the terminal, the owner's (#10465): pick a machine, then a
 * row a device — model, bytes written in the last 30 days, the date rated TBW
 * is projected at that rate, and what the assessment says. Ratings are vendor
 * figures; the date is a projection, not an alert. Read-only; the gate is
 * `mayHandleDisks`.
 */
import { mayHandleDisks, readMachine, readMachines } from "../../actions/disk_readings.ts";
import { printable, type MachineSummary } from "../../machines/disk_readings.ts";
import type { Ctx, Screen } from "../app/app.ts";
import { binding } from "../app/keys.ts";
import type { Session } from "../session.ts";
import { style } from "../term/style.ts";
import { Scroll, blank, drawLines, hitScroll, pickerScreen } from "./common.ts";
import type { PaletteEntry } from "./entries.ts";
const tb = (bytes: number): string => `${(bytes / 1e12).toFixed(2)} TB`;
/**
 * Header lines, then one line per device with its reasons beneath; every line stripped of
 * control characters, since model, firmware and cpu are a machine's own text.
 */
export function diskLines(s: MachineSummary): string[] {
  const lines = [`${s.machine}: ${s.cpu ?? "cpu unknown"}, ${s.memoryBytes === null ? "memory unknown" : `${(s.memoryBytes / 1e9).toFixed(0)} GB`}`];
  if (s.devices.length === 0) lines.push("No readings yet.");
  for (const d of s.devices) {
    if (d.kind === "behind-controller") {
      lines.push(`${d.device}: behind a controller; not readable here`);
      continue;
    }
    const rate = d.bytesWrittenInWindow === null ? "no rate yet" : `${tb(d.bytesWrittenInWindow)} in ${d.spanDays!.toFixed(1)} d`;
    const date = d.ratedReachedAt === null ? "no projected date" : `rated TBW ${d.ratedReachedAt}`;
    lines.push(`${d.device}: ${d.inventory.model} ${d.inventory.firmware} · ${rate} · ${date} · ${d.assessment.level}`);
    for (const r of d.assessment.reasons) lines.push(`    ${r}`);
  }
  return lines.map(printable);
}
function readingScreen(session: Session, ctx: Ctx, machine: string): Screen {
  const scroll = new Scroll();
  const lines = (): string[] => {
    const r = readMachine(session.app, session.user, machine);
    return r.ok ? diskLines(r.value) : [];
  };
  return {
    title: `Disks: ${machine}`,
    keys: [binding(["j", "k"], "scroll"), binding(["esc", "q"], "back")],
    render(area, s) {
      const c = ctx.theme.c;
      const all = lines();
      drawLines(s, area, c, scroll, all.map((text, i) => [{ text, style: style(i === 0 ? c.fg : c.mutedFg, c.bg) }]));
      hitScroll(ctx, area, scroll, all.length);
    },
    key(e) {
      if (scroll.key(e, lines().length)) return true;
      if (e.key === "esc" || e.key === "q") {
        ctx.pop();
        return true;
      }
      return false;
    },
  };
}
export const entry: PaletteEntry = {
  id: "disks",
  title: "Disks",
  hint: "machines' disk readings: 30-day write rate and projected rated-TBW date",
  after: ["system"],
  offered: (session) => mayHandleDisks(session.user),
  run: (session, ctx) => {
    const names = readMachines(session.app, session.user);
    if (!names.ok || names.value.length === 0) return ctx.toast("No disk readings yet");
    ctx.push(
      pickerScreen(ctx, blank("Disks"), {
        title: "Disks: machine",
        items: names.value.map((m) => ({ id: m, label: m, hint: "" })),
        onPick: ([m]) => {
          if (m) ctx.push(readingScreen(session, ctx, m));
        },
      }),
    );
  },
};
@@ -25,6 +25,7 @@
import { entry as crewHandover } from "./crewhandover.ts";
import { entry as crewSplits } from "./crewsplits.ts";
import { entry as knobs } from "./knobs.ts";
import { entry as displays } from "./displays.ts";
import { entry as disks } from "./disks.ts";
import { entry as domains } from "./domains.ts";
import { entry as edgeOnly } from "./edgeonly.ts";
import { entry as traffic } from "./trafficview.ts";
@@ -148,6 +149,7 @@
export const ENTRIES: readonly PaletteEntry[] = [
  forgeView,
  repos,
  displays,
  disks,
  newIssue,
];
@@ -0,0 +1,139 @@
/** Disk readings reach the owner by API and terminal; nobody else files or reads them (#10465). */
import { afterAll, beforeAll, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createAgent } from "../src/actions/crew.ts";
import { createApp, type App } from "../src/app.ts";
import { createToken } from "../src/core/tokens.ts";
import { createUser, type User } from "../src/core/users.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { createForgeApp, forgeCommands } from "../src/tui/forge.ts";
import { diskLines } from "../src/tui/screens/disks.ts";
import { diskSummary } from "../src/machines/disk_readings.ts";
import { headlessTerminal } from "../src/tui/term/terminal.ts";
import { quietLogs } from "./helpers/globals.ts";
quietLogs();
const smart = (units: number) => ({
  smartctl: { version: [7, 4] },
  device: { name: "/dev/nvme0", type: "nvme", protocol: "NVMe" },
  model_name: "Samsung SSD 980 PRO 1TB",
  firmware_version: "5B2QGXA7",
  user_capacity: { bytes: 1_000_204_886_016 },
  nvme_smart_health_information_log: {
    critical_warning: 0, temperature: 40, available_spare: 100, available_spare_threshold: 10,
    percentage_used: 1, data_units_written: units, media_errors: 0, power_on_hours: 100,
    unsafe_shutdowns: 2, warning_temp_time: 0, critical_comp_time: 0,
  },
});
let dir: string;
let app: App;
let servers: Servers;
let admin: string;
let ro: string;
let member: string;
let alice: User;
let bob: User;
let bot: User;
let agentToken: string;
beforeAll(async () => {
  dir = await mkdtemp(join(tmpdir(), "disk-intake-"));
  app = createApp({ dataDir: dir, port: 0 });
  servers = await serve(app);
  const made = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
  if (!made.ok) throw new Error(made.error);
  alice = made.value;
  admin = createToken(app.db, alice.id, "a", "admin").token;
  ro = createToken(app.db, alice.id, "r", "ro").token;
  const m = await createUser(app.db, { origin: "seed", trusted: true, username: "bob", email: "[email protected]", password: "a-good-passphrase" });
  if (!m.ok) throw new Error(m.error);
  bob = m.value;
  member = createToken(app.db, bob.id, "m", "admin").token;
  const agent = await createAgent(app, alice, { username: "diskbot", brief: "x" });
  if (!agent.ok) throw new Error(String(agent.error));
  app.db.query("UPDATE user SET is_admin = 1 WHERE id = ?1").run(agent.value.user.id);
  bot = { ...agent.value.user, isAdmin: true };
  agentToken = createToken(app.db, bot.id, "bot", "admin").token;
}, 60_000);
afterAll(async () => {
  servers.stop();
  app.close();
  await rm(dir, { recursive: true, force: true });
});
const put = (token: string, machine: string, body: unknown) =>
  fetch(`${servers.url}/api/v1/admin/machines/${machine}/disks/nvme0`, {
    method: "PUT",
    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
    body: JSON.stringify(body),
  });
const get = (token: string, machine: string) =>
  fetch(`${servers.url}/api/v1/admin/machines/${machine}/disks`, { headers: { authorization: `Bearer ${token}` } });
test("the owner's admin token files a reading and reads the summary", async () => {
  const res = await put(admin, "rack1", { smartctl: smart(1_000), cpu: "AMD EPYC", memoryBytes: 64e9 });
  expect(res.status).toBe(201);
  expect(((await res.json()) as { kind: string }).kind).toBe("nvme");
  // The text form is accepted too.
  expect((await put(admin, "rack1", { smartctl: JSON.stringify(smart(2_000)) })).status).toBe(201);
  const read = await get(ro, "rack1");
  expect(read.status).toBe(200);
  const s = (await read.json()) as { cpu: string; devices: { device: string; bytesWrittenInWindow: number }[] };
  expect(s.cpu).toBe("AMD EPYC");
  expect(s.devices[0]!.device).toBe("nvme0");
  expect(s.devices[0]!.bytesWrittenInWindow).toBe(1_000 * 512_000);
});
test("a refused reading is a 422 and stores nothing; a read-only token cannot write", async () => {
  const before = app.db.query("SELECT COUNT(*) AS n FROM disk_reading").get();
  const bad = await put(admin, "rack2", { smartctl: "not json" });
  expect(bad.status).toBe(422);
  expect(((await bad.json()) as { error: { message?: string } | string }).error).toBeDefined();
  expect((await put(admin, "bad name", { smartctl: smart(1) })).status).toBe(422);
  expect((await put(admin, "rack2", { smartctl: smart(1), cpu: "", memoryBytes: 1 })).status).toBe(422);
  expect((await put(ro, "rack2", { smartctl: smart(1) })).status).toBe(403);
  expect(app.db.query("SELECT COUNT(*) AS n FROM disk_reading").get()).toEqual(before);
});
test("a member, an agent and no one at all file and read nothing", async () => {
  // A member is turned away by the admin gate (403, not_admin) before the handler; an agent admin passes it and the handler hides the route.
  expect((await put(member, "rack3", { smartctl: smart(1) })).status).toBe(403);
  expect((await get(member, "rack1")).status).toBe(403);
  expect((await put(agentToken, "rack3", { smartctl: smart(1) })).status).toBe(404);
  expect((await get(agentToken, "rack1")).status).toBe(404);
  expect((await fetch(`${servers.url}/api/v1/admin/machines/rack1/disks`)).status).toBe(401);
  expect((await fetch(`${servers.url}/api/v1/admin/machines/rack3/disks/nvme0`, { method: "PUT", body: "{}" })).status).toBe(401);
  expect(diskSummary(app.db, "rack3").devices).toEqual([]);
});
const identity = (user?: User) => ({ sshUsername: user?.username ?? "git", remoteAddress: "127.0.0.1", fingerprint: "SHA256:test", user });
const doors = (user?: User): string[] => {
  const { app: tui, session } = createForgeApp(app, identity(user), { terminal: headlessTerminal(80, 24), exitHooks: false });
  const ids = forgeCommands(session)(tui.ctx).map((c) => c.id);
  tui.stop?.();
  return ids;
};
test("the Disks screen is the owner's door, and says what the API stored", () => {
  expect(doors(alice)).toContain("disks");
  for (const who of [bob, bot, undefined]) expect(doors(who)).not.toContain("disks");
  const lines = diskLines(diskSummary(app.db, "rack1"));
  expect(lines[0]).toBe("rack1: AMD EPYC, 64 GB");
  expect(lines[1]).toContain("nvme0: Samsung SSD 980 PRO 1TB");
  expect(lines[1]).toContain("0.00 TB");
});
test("a cpu with a control character is refused; model and firmware reach the terminal without theirs", async () => {
  expect((await put(admin, "rack4", { smartctl: smart(1), cpu: "EPYC\u001b]0;pwned\u0007", memoryBytes: 1 })).status).toBe(422);
  expect((await put(admin, "rack4", { smartctl: smart(1), cpu: "EPYC\u009b2J", memoryBytes: 1 })).status).toBe(422);
  const evil = { ...smart(1), model_name: "Samsung\u001b[2J SSD", firmware_version: "5B2\u001b]52;c;eA==\u0007QGXA7" };
  expect((await put(admin, "rack4", { smartctl: evil })).status).toBe(201);
  const lines = diskLines(diskSummary(app.db, "rack4"));
  expect(lines.join("\n")).not.toMatch(/[\u0000-\u0009\u000b-\u001f\u007f-\u009f]/);
  expect(lines[1]).toContain("Samsung[2J SSD 5B2]52;c;eA==QGXA7");
});
@@ -0,0 +1,167 @@
/** Disk readings per machine (#10465): rate, projected date, refusals, alerts. Hand calculation in comments. */
import { expect, test } from "bun:test";
import { migrations } from "../src/core/schema.ts";
import { openDb } from "../src/kernel/db.ts";
import { diskSummary, MAX_DEVICES, MAX_MACHINES, recordReading } from "../src/machines/disk_readings.ts";
const DAY = 86_400_000;
const T0 = Date.parse("2026-10-01T00:00:00Z");
function smart(units: number, mediaErrors = 0, model = "Samsung SSD 980 PRO 1TB") {
  return JSON.stringify({
    smartctl: { version: [7, 4] },
    device: { name: "/dev/nvme0", type: "nvme", protocol: "NVMe" },
    model_name: model,
    firmware_version: "5B2QGXA7",
    user_capacity: { bytes: 1_000_204_886_016 },
    nvme_smart_health_information_log: {
      critical_warning: 0, temperature: 40, available_spare: 100, available_spare_threshold: 10,
      percentage_used: 1, data_units_written: units, media_errors: mediaErrors, power_on_hours: 100,
      unsafe_shutdowns: 2, warning_temp_time: 0, critical_comp_time: 0,
    },
  });
}
const db = () => openDb(":memory:", migrations);
test("two readings 30 days apart give the rate and the date", () => {
  const d = db();
  // 1e9 data units × 512 000 B = 5.12e14 B; 2e9 units = 1.024e15 B. Δ = 5.12e14 B over 30 d.
  recordReading(d, "m1", "nvme0", smart(1_000_000_000), T0, { cpu: "AMD EPYC", memoryBytes: 64e9 });
  recordReading(d, "m1", "nvme0", smart(2_000_000_000), T0 + 30 * DAY);
  const s = diskSummary(d, "m1");
  expect(s.cpu).toBe("AMD EPYC");
  expect(s.memoryBytes).toBe(64e9);
  const dev = s.devices[0]!;
  if (dev.kind !== "nvme") throw new Error("kind");
  expect(dev.bytesWrittenInWindow).toBe(512_000_000_000_000);
  expect(dev.inventory.model).toBe("Samsung SSD 980 PRO 1TB");
  // Remaining: 600e12 − 1.024e15 < 0 → already past rated: date is the latest reading, 2026-10-31.
  expect(dev.ratedReachedAt).toBe("2026-10-31");
});
test("projects forward: remaining ÷ rate", () => {
  const d = db();
  // 100e6 units = 5.12e13 B; 200e6 units = 1.024e14 B; Δ = 5.12e13 over 30 d.
  // Remaining = 6e14 − 1.024e14 = 4.976e14; ÷ (5.12e13/30 per day) = 291.5625 d after 2026-10-31.
  recordReading(d, "m1", "nvme0", smart(100_000_000), T0);
  recordReading(d, "m1", "nvme0", smart(200_000_000), T0 + 30 * DAY);
  const dev = diskSummary(d, "m1").devices[0]!;
  const expected = new Date(T0 + 30 * DAY + 291.5625 * DAY).toISOString().slice(0, 10);
  expect(dev.ratedReachedAt).toBe(expected);
});
test("one reading gives no projection; unknown model gives no date", () => {
  const d = db();
  recordReading(d, "m1", "nvme0", smart(5), T0);
  const one = diskSummary(d, "m1").devices[0]!;
  expect(one.bytesWrittenInWindow).toBeNull();
  expect(one.ratedReachedAt).toBeNull();
  recordReading(d, "m2", "nvme0", smart(5, 0, "Mystery"), T0);
  recordReading(d, "m2", "nvme0", smart(9, 0, "Mystery"), T0 + DAY);
  const two = diskSummary(d, "m2").devices[0]!;
  if (two.kind !== "nvme") throw new Error("kind");
  expect(two.spec).toBeNull();
  expect(two.bytesWrittenInWindow).toBe(4 * 512_000);
  expect(two.ratedReachedAt).toBeNull();
});
test("a refused reading stores nothing and names why", () => {
  const d = db();
  expect(recordReading(d, "m1", "nvme0", "nope", T0)).toEqual({ ok: false, reason: "not-json" });
  expect(recordReading(d, "m1", "nvme0", '{"a":1}', T0)).toEqual({ ok: false, reason: "not-smartctl-output" });
  expect(recordReading(d, "bad name", "nvme0", smart(1), T0)).toEqual({ ok: false, reason: "bad-machine" });
  expect(recordReading(d, "m1", "nvme0", smart(1), T0, { cpu: "", memoryBytes: 1 })).toEqual({ ok: false, reason: "bad-inventory" });
  expect(d.query("SELECT COUNT(*) AS n FROM disk_reading").get()).toEqual({ n: 0 });
  expect(d.query("SELECT COUNT(*) AS n FROM machine_inventory").get()).toEqual({ n: 0 });
  expect(diskSummary(d, "m1").devices).toEqual([]);
});
test("rising media errors between two stored readings alert", () => {
  const d = db();
  recordReading(d, "m1", "nvme0", smart(10, 0), T0);
  const first = diskSummary(d, "m1").devices[0]!;
  if (first.kind !== "nvme") throw new Error("kind");
  expect(first.assessment.level).toBe("ok");
  recordReading(d, "m1", "nvme0", smart(11, 3), T0 + DAY);
  const dev = diskSummary(d, "m1").devices[0]!;
  if (dev.kind !== "nvme") throw new Error("kind");
  expect(dev.assessment.level).toBe("alert");
  expect(dev.assessment.reasons[0]).toContain("media errors rose from 0 to 3");
});
test("a counter that goes backwards gives no rate and no date", () => {
  const d = db();
  recordReading(d, "m1", "nvme0", smart(200_000_000), T0);
  recordReading(d, "m1", "nvme0", smart(100_000_000), T0 + DAY); // a replaced or reset drive
  const dev = diskSummary(d, "m1").devices[0]!;
  if (dev.kind !== "nvme") throw new Error("kind");
  expect(dev.bytesWrittenInWindow).toBeNull();
  expect(dev.spanDays).toBeNull();
  expect(dev.ratedReachedAt).toBeNull();
});
test("readings older than 30 days are left out of the base", () => {
  const d = db();
  // Latest at T0+60 d. The reading at T0 is 60 d back: outside the window.
  // Base is the oldest inside it, T0+40 d (20 d back): Δ = 3e7 − 1e7 units = 2e7 × 512 000 B = 1.024e13 B over 20 d.
  recordReading(d, "m1", "nvme0", smart(1_000), T0);
  recordReading(d, "m1", "nvme0", smart(10_000_000), T0 + 40 * DAY);
  recordReading(d, "m1", "nvme0", smart(30_000_000), T0 + 60 * DAY);
  const dev = diskSummary(d, "m1").devices[0]!;
  if (dev.kind !== "nvme") throw new Error("kind");
  expect(dev.bytesWrittenInWindow).toBe(20_000_000 * 512_000);
  expect(dev.spanDays).toBe(20);
  // Only the old reading and the latest: nothing inside the window to compare with.
  const e = db();
  recordReading(e, "m1", "nvme0", smart(1_000), T0);
  recordReading(e, "m1", "nvme0", smart(30_000_000), T0 + 60 * DAY);
  const lone = diskSummary(e, "m1").devices[0]!;
  if (lone.kind !== "nvme") throw new Error("kind");
  expect(lone.bytesWrittenInWindow).toBeNull();
});
test("a device behind a controller comes back as such, with no projection", () => {
  const d = db();
  const raid = JSON.stringify({ smartctl: {}, device: { name: "/dev/sda", type: "megaraid,0", protocol: "SCSI" } });
  expect(recordReading(d, "m1", "sda", raid, T0)).toMatchObject({ ok: true, kind: "behind-controller" });
  const dev = diskSummary(d, "m1").devices[0]!;
  expect(dev.kind).toBe("behind-controller");
  expect(dev.ratedReachedAt).toBeNull();
  expect(dev.reading).toBeNull();
});
const count = (d: ReturnType<typeof db>, device = "nvme0"): number =>
  (d.query("SELECT COUNT(*) AS n FROM disk_reading WHERE device = ?").get(device) as { n: number }).n;
test("a write prunes the device's readings older than 60 days, keeping its newest two", () => {
  const d = db();
  // A reading a day for 100 days: the last write at T0+99 d keeps T0+39 d … T0+99 d (≥ T0+39 d), 61 rows.
  for (let i = 0; i < 100; i++) recordReading(d, "m1", "nvme0", smart(1_000 + i * 1_000), T0 + i * DAY);
  expect(count(d)).toBe(61);
  // The summary is unchanged by the prune: base T0+69 d, Δ = 30 × 1 000 units × 512 000 B over 30 d.
  const dev = diskSummary(d, "m1").devices[0]!;
  if (dev.kind !== "nvme") throw new Error("kind");
  expect(dev.bytesWrittenInWindow).toBe(30 * 1_000 * 512_000);
  expect(dev.spanDays).toBe(30);
  // A device read twice a year still keeps its newest two, so the alert has a previous reading.
  const e = db();
  recordReading(e, "m1", "nvme0", smart(1), T0);
  recordReading(e, "m1", "nvme0", smart(2), T0 + 200 * DAY);
  recordReading(e, "m1", "nvme0", smart(3), T0 + 400 * DAY);
  expect(count(e)).toBe(2);
  // Another device's old readings are not this write's to prune.
  recordReading(e, "m1", "nvme1", smart(1), T0);
  recordReading(e, "m1", "nvme0", smart(4), T0 + 600 * DAY);
  expect(count(e, "nvme1")).toBe(1);
});
test("a new machine past the cap, or a new device past the cap on one machine, is refused", () => {
  const d = db();
  for (let i = 0; i < MAX_MACHINES; i++) expect(recordReading(d, `m${i}`, "nvme0", smart(1), T0).ok).toBe(true);
  expect(recordReading(d, "one-more", "nvme0", smart(1), T0)).toEqual({ ok: false, reason: "too-many-machines" });
  for (let i = 1; i < MAX_DEVICES; i++) expect(recordReading(d, "m0", `nvme${i}`, smart(1), T0).ok).toBe(true);
  expect(recordReading(d, "m0", "one-more", smart(1), T0)).toEqual({ ok: false, reason: "too-many-devices" });
  // A known machine and device still file.
  expect(recordReading(d, "m0", "nvme0", smart(2), T0 + DAY).ok).toBe(true);
  expect((d.query("SELECT COUNT(*) AS n FROM disk_reading WHERE device = 'one-more'").get() as { n: number }).n).toBe(0);
});
@@ -53,6 +53,7 @@
const FIXTURE: Record<string, string> = {
  "/:owner/:name/issues/:number": "/alice/forge/issues/1",
  "/:owner/:name/pulls/:number": "/alice/forge/pulls/2",
  "/:owner/:name/display": "/alice/forge/display",
  "/api/v1/admin/machines/:machine/disks": "/api/v1/admin/machines/rack1/disks",
};
function registeredGets(): Set<string> {
@@ -106,6 +106,7 @@
test("a site-admin person is offered the whole roster", () => {
    ["system", "System", "the machine now: CPU, memory, disks, processes"],
    ["valves", "Valves", "the week's budget as a valve per repository; turn one and the crew obeys"],
    ["stalls", "Main-thread stalls", "the last hour's stall ms by route"],
    ["disks", "Disks", "machines' disk readings: 30-day write rate and projected rated-TBW date"],
    ["telemetry", "Telemetry", "which agents may read flow and system; enter flips the grant"],
    ["capacity", "Capacity", "concurrency and guards, live; e changes a settable one"],
    ["resilience", "Resilience", "where snapshots go and the mirror; each protection green, red or untested"],
@@ -20,6 +20,7 @@
import { seedAdmin } from "./helpers/admin.ts";
/** Routes that answer 200 without a `session` phase → why. */
const UNTIMED: Record<string, string> = {
  "/api/v1/conversations": "a person's conversation list, one indexed query; no page to phase",
  "/api/v1/admin/machines/:machine/disks": "an owner's per-machine disk summary, one indexed read; no page to phase",
  "/metrics": "Prometheus text exposition, scraped by token; not a page read",
};
@@ -51,6 +51,7 @@
const allowed: readonly { file: string; action: string; reason: string }[] = [
  { file: "src/tui/screens/deploys.ts", action: "stopEnv", reason: "in `act`, called from `go` after the Stop confirm" },
  { file: "src/tui/screens/boards.ts", action: "deleteBoard", reason: "in `remove`, called only on the y of the delete y/n" },
  { file: "src/tui/screens/about.ts", action: "detachFromParent", reason: "the first call is the dry run; the real one is in onChoose" },
  { file: "src/tui/screens/devices.ts", action: "revoke", reason: "passed to `askApp`, run only from the slug prompt's onSubmit" },
];
/** How many lines above a call a `y` key check still guards it. */
		@@ -0,0 +1,40 @@
	1	# Disk readings per machine (#10465)
	2
	3	The forge keeps `smartctl --json` readings of NVMe disks per machine and
	4	device, and shows the bytes written in the last 30 days and the date the
	5	vendor's rated TBW is reached at that rate. The rating comes from
	6	`src/machines/disk_catalog.ts` (vendor figures, not measured); the date is a
	7	projection, never an alert. A model not in the catalog gets a rate and no date;
	8	a drive behind a RAID controller is recorded as such and not assessed.
	9
	10	Who: the owner, a forge admin who is a person. A member, an agent account
	11	(admin or not) and a stranger get 404 on both doors, and nothing is stored.
	12
	13	## File a reading
	14
	15	```
	16	smartctl --json -a /dev/nvme0 \| jq -n --slurpfile s /dev/stdin \
	17	'{smartctl: $s[0], cpu: "AMD EPYC 7302", memoryBytes: 64000000000}' \|
	18	curl -X PUT -H "authorization: Bearer $ADMIN_TOKEN" -H 'content-type: application/json' \
	19	--data @- "$FORGE_URL/api/v1/admin/machines/rack1/disks/nvme0"
	20	```
	21
	22	`cpu` and `memoryBytes` are optional and update the machine's inventory. A
	23	reading that does not parse, a `cpu` with a control character, or a new
	24	machine past 256 (a new device past 64 on one machine) answers 422 with the
	25	reason and stores nothing. Each write prunes that device's readings older than
	26	60 days, always keeping its newest two.
	27	The token needs `admin` scope.
	28
	29	## Read
	30
	31	- `GET /api/v1/admin/machines/rack1/disks` (any scope of the owner's token):
	32	per device the latest reading, `bytesWrittenInWindow` over `spanDays` (≤ 30:
	33	from the oldest reading inside the 30 days before the latest, so a figure for
	34	30 days only once readings go back that far),
	35	`ratedReachedAt` and the assessment. A counter that went backwards gives no
	36	rate and no date.
	37	- The terminal: `:` → "Disks", pick a machine.
	38
	39	Rate: latest reading against the oldest one inside the 30 days before it,
	40	bytes per day = Δbytes ÷ Δdays; date = latest + (rated TBW − written) ÷ rate.
		@@ -15,8 +15,6 @@
15	15	"src/flow/review_rounds.ts",
16	16	"src/flow/shared_red.ts",
17	17	"src/flow/stale_fold.ts",
18		"src/machines/disk_catalog.ts",
19		"src/machines/disk_health.ts",
20	18	"src/spawn/pod.ts",
21	19	"src/tui/gallery.ts",
22	20	"src/tui/ui/qr.ts",
		@@ -0,0 +1,41 @@
	1	/**
	2	* Who writes and who reads a machine's disk readings (#10465). Both are the
	3	* owner — a forge admin who is a person: a reading is a claim about hardware
	4	* that decides what the owner replaces, so an agent account neither files nor
	5	* reads one. Anyone else gets "not_found" here; over the API a signed-in
	6	* non-admin meets the admin gate's 403 first (`http/admin_gate.ts`).
	7	*/
	8	import type { App } from "../app.ts";
	9	import type { User } from "../core/users.ts";
	10	import { err, ok, type Result } from "../kernel/result.ts";
	11	import { diskSummary, machineNames, recordReading, type Inventory, type MachineSummary } from "../machines/disk_readings.ts";
	12
	13	export const mayHandleDisks = (user: User \| undefined): user is User => user !== undefined && user.isAdmin && user.kind !== "agent";
	14
	15	export type FileError = { code: "not_found" } \| { code: "invalid"; says: string };
	16
	17	/** Store one reading from smartctl's JSON text for `machine` and `device`. */
	18	export function fileReading(
	19	app: App,
	20	actor: User \| undefined,
	21	machine: string,
	22	device: string,
	23	smartJsonText: unknown,
	24	inventory?: Inventory,
	25	): Result<{ kind: "nvme" \| "behind-controller"; takenAt: number }, FileError> {
	26	if (!mayHandleDisks(actor)) return err({ code: "not_found" });
	27	const r = recordReading(app.db, machine, device, smartJsonText, Date.now(), inventory);
	28	if (!r.ok) return err({ code: "invalid", says: `Reading refused: ${r.reason}${r.field ? ` (${r.field})` : ""}.` });
	29	return ok({ kind: r.kind, takenAt: r.takenAt });
	30	}
	31
	32	/** What the readings of one machine say; nothing for anyone but the owner. */
	33	export function readMachine(app: App, actor: User \| undefined, machine: string): Result<MachineSummary, "not_found"> {
	34	if (!mayHandleDisks(actor)) return err("not_found");
	35	return ok(diskSummary(app.db, machine));
	36	}
	37
	38	/** The machines with readings; nothing for anyone but the owner. */
	39	export function readMachines(app: App, actor: User \| undefined): Result<string[], "not_found"> {
	40	return mayHandleDisks(actor) ? ok(machineNames(app.db)) : err("not_found");
	41	}
		@@ -0,0 +1,10 @@
	1	import type { Route } from "../shared.ts";
	2
	3	export const route: Route = {
	4	method: "get",
	5	path: "/api/v1/admin/machines/{machine}/disks",
	6	summary:
	7	"Read a machine's disk readings (a person admin's token, any scope): per device the latest reading, bytesWrittenInWindow over spanDays (the oldest reading within 30 days of the latest to the latest, so ≤ 30 days, not always 30), ratedReachedAt and the assessment",
	8	auth: true,
	9	refusals: { not_found: "the token is not a person who administers the forge, or the machine has no readings" },
	10	};
		@@ -41,6 +41,7 @@ export { route as getApiV1AdminDrills } from "./getApiV1AdminDrills.ts";
41	41	export { route as getApiV1AdminInvites } from "./getApiV1AdminInvites.ts";
42	42	export { route as getApiV1AdminKpisProbe } from "./getApiV1AdminKpisProbe.ts";
43	43	export { route as getApiV1AdminLimits } from "./getApiV1AdminLimits.ts";
	44	export { route as getApiV1AdminMachinesMachineDisks } from "./getApiV1AdminMachinesMachineDisks.ts";
44	45	export { route as getApiV1AdminMaintenance } from "./getApiV1AdminMaintenance.ts";
45	46	export { route as getApiV1AdminPeople } from "./getApiV1AdminPeople.ts";
46	47	export { route as getApiV1AdminPinned } from "./getApiV1AdminPinned.ts";
		@@ -359,6 +360,7 @@ export { route as postApiV1Users } from "./postApiV1Users.ts";
359	360	export { route as postMcp } from "./postMcp.ts";
360	361	export { route as putApiV1AdminCapacityKey } from "./putApiV1AdminCapacityKey.ts";
361	362	export { route as putApiV1AdminLimitsKey } from "./putApiV1AdminLimitsKey.ts";
	363	export { route as putApiV1AdminMachinesMachineDisksDevice } from "./putApiV1AdminMachinesMachineDisksDevice.ts";
362	364	export { route as putApiV1AdminQuotasKey } from "./putApiV1AdminQuotasKey.ts";
363	365	export { route as putApiV1AdminShield } from "./putApiV1AdminShield.ts";
364	366	export { route as putApiV1AdminTeamsSlug } from "./putApiV1AdminTeamsSlug.ts";
		@@ -0,0 +1,1 @@
	1	6424c1dd3f5515eb89c572a418072d0eefce8b4ea3a291d89cbb7514a2b87052
		@@ -0,0 +1,20 @@
	1	// Disk health readings, one row per machine and device and time (#10465), and
	2	// the machine's own CPU and memory. A behind-controller device keeps a row with
	3	// no reading. Additive.
	4	export default `
	5	CREATE TABLE disk_reading (
	6	id INTEGER PRIMARY KEY AUTOINCREMENT,
	7	machine TEXT NOT NULL,
	8	device TEXT NOT NULL,
	9	taken_at INTEGER NOT NULL,
	10	kind TEXT NOT NULL CHECK (kind IN ('nvme','behind-controller')),
	11	reading TEXT
	12	);
	13	CREATE INDEX disk_reading_by_device ON disk_reading (machine, device, taken_at);
	14	CREATE TABLE machine_inventory (
	15	machine TEXT PRIMARY KEY,
	16	cpu TEXT NOT NULL,
	17	memory_bytes INTEGER NOT NULL,
	18	updated_at INTEGER NOT NULL
	19	);
	20	`;
		@@ -360,6 +360,7 @@ import { businessPlanRoutes } from "./api/business_plan.ts";
360	360	import { tokenRoutes } from "./api/tokens.ts";
361	361	import { accountAdmin, adminRoutes } from "./api/admin.ts";
362	362	import { maintenanceRoutes } from "./api/maintenance.ts";
	363	import { diskReadingRoutes } from "./api/disk_readings.ts";
363	364	import { TEMPLATE_ERRORS } from "../apps/template_tip.ts";
364	365	import { flagsRoutes } from "./api/flags.ts";
365	366	import { appTemplateRoutes } from "./api/app_templates.ts";
		@@ -1247,6 +1248,7 @@ export function apiRoutes(router: Router<Handler>): void {
1247	1248	forgeOriginRoutes(router);
1248	1249	adminRoutes(router);
1249	1250	maintenanceRoutes(router);
	1251	diskReadingRoutes(router);
1250	1252	flagsRoutes(router);
1251	1253	appTemplateRoutes(router);
1252	1254
		@@ -0,0 +1,42 @@
	1	/**
	2	* Disk readings over the API (#10465): `PUT /api/v1/admin/machines/:machine/disks/:device`
	3	* files smartctl's JSON (body `{smartctl, cpu?, memoryBytes?}`, `smartctl` the
	4	* text or the object); `GET /api/v1/admin/machines/:machine/disks` reads the
	5	* summary. The owner's admin-scope credential writes, any scope of it reads.
	6	*/
	7	import { fileReading, readMachine } from "../../actions/disk_readings.ts";
	8	import { crossOrigin, type Handler } from "../context.ts";
	9	import { apiError, boundedBody, forbidden, json, notFound, requireScope, unauthorized } from "../respond.ts";
	10	import type { Router } from "../router.ts";
	11
	12	/** smartctl's text is capped at 4 MB by the parser; room for the JSON wrapping it. */
	13	const BODY_MAX = 4_300_000;
	14
	15	export function diskReadingRoutes(router: Router<Handler>): void {
	16	router.add("GET", "/api/v1/admin/machines/:machine/disks", (ctx) => {
	17	if (!ctx.auth.user) return unauthorized();
	18	if (!ctx.auth.user.isAdmin) return notFound();
	19	const denied = requireScope(ctx, "ro");
	20	if (denied) return denied;
	21	const r = readMachine(ctx.app, ctx.auth.user, ctx.params.machine ?? "");
	22	return r.ok ? json(r.value) : notFound();
	23	});
	24	router.add("PUT", "/api/v1/admin/machines/:machine/disks/:device", async (ctx) => {
	25	if (!ctx.auth.user) return unauthorized();
	26	if (!ctx.auth.user.isAdmin) return notFound();
	27	const denied = requireScope(ctx, "admin");
	28	if (denied) return denied;
	29	if (ctx.auth.via === "session" && crossOrigin(ctx.request, ctx.url, ctx.app.log)) return forbidden();
	30	const input = await boundedBody(ctx.request, BODY_MAX);
	31	if (input === "too_large") return apiError("too_large", 413, "The request is too large.");
	32	const smart = input["smartctl"];
	33	const text = typeof smart === "string" ? smart : smart !== null && typeof smart === "object" ? JSON.stringify(smart) : "";
	34	const inventory =
	35	input["cpu"] === undefined && input["memoryBytes"] === undefined
	36	? undefined
	37	: { cpu: input["cpu"] as string, memoryBytes: input["memoryBytes"] as number };
	38	const r = fileReading(ctx.app, ctx.auth.user, ctx.params.machine ?? "", ctx.params.device ?? "", text, inventory);
	39	if (r.ok) return json(r.value, 201);
	40	return r.error.code === "invalid" ? apiError("invalid", 422, r.error.says) : notFound();
	41	});
	42	}
		@@ -0,0 +1,189 @@
	1	/**
		junipercrew 1d ago Unreached module: allow-listed instead of wired. Add the caller (intake with identity check, gated read, TUI screen, docs/features page) or hold this back until it exists.
	2	* Disk readings kept per machine and device (#10465), in the forge's own
	3	* database. A reading is stored only after `parseSmartJson` accepts it.
	4	*
	5	* Write rate: the latest reading against the oldest one inside the 30 days
	6	* before it; bytes per day = Δbytes written ÷ Δdays (a rate over the span
	7	* actually covered, not a guess beyond it). Projected date: the latest time +
	8	* (rated TBW × 10^12 B − bytes written) ÷ rate. Ratings are vendor figures
	9	* (see disk_catalog.ts); the date is a projection, never an alert.
	10	*/
	11
	12	import type { Database } from "bun:sqlite";
	13	import { diskSpec, type DiskSpec } from "./disk_catalog.ts";
	14	import { assessDisk, parseSmartJson, type Assessment, type DiskReading } from "./disk_health.ts";
	15
	16	const DAY_MS = 86_400_000;
	17	export const WINDOW_DAYS = 30;
	18	const NAME = /^[A-Za-z0-9][A-Za-z0-9._:\/-]{0,99}$/;
	19	/** A device keeps readings this many days back (twice the window), and always its newest two. */
	20	export const KEEP_DAYS = 60;
	21	const KEEP_NEWEST = 2;
	22	/** At most this many machines per forge and devices per machine; a new name past either is refused. */
	23	export const MAX_MACHINES = 256;
	24	export const MAX_DEVICES = 64;
	25	/** C0, DEL and C1 controls: any of them could steer the terminal that prints the text. */
	26	const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
	27	/** Text as a terminal may print it: every control character dropped. */
	28	export const printable = (text: string): string => text.replace(new RegExp(CONTROL.source, "g"), "");
	29
	30	export type Inventory = { cpu: string; memoryBytes: number };
	31	export type RecordResult =
	32	\| { ok: true; kind: "nvme" \| "behind-controller"; takenAt: number }
	33	\| { ok: false; reason: string; field?: string };
	34
	35	/** Store a reading from smartctl's JSON text; a refusal names its reason and stores nothing. */
	36	export function recordReading(
	37	db: Database,
	38	machine: string,
	39	device: string,
	40	smartJsonText: unknown,
	41	now: number = Date.now(),
	42	inventory?: Inventory,
	43	): RecordResult {
	44	if (typeof machine !== "string" \|\| !NAME.test(machine)) return { ok: false, reason: "bad-machine" };
	45	if (typeof device !== "string" \|\| !NAME.test(device)) return { ok: false, reason: "bad-device" };
	46	if (!Number.isSafeInteger(now) \|\| now < 0) return { ok: false, reason: "bad-time" };
	47	if (inventory !== undefined) {
	48	const okInv =
	49	typeof inventory.cpu === "string" && inventory.cpu.length > 0 && inventory.cpu.length <= 200 && !CONTROL.test(inventory.cpu) &&
	50	Number.isSafeInteger(inventory.memoryBytes) && inventory.memoryBytes > 0;
	51	if (!okInv) return { ok: false, reason: "bad-inventory" };
	52	}
	53	const parsed = parseSmartJson(smartJsonText);
	54	if (parsed.kind === "refused") return { ok: false, reason: parsed.reason, ...(parsed.field ? { field: parsed.field } : {}) };
	55	let refused: string \| null = null;
	56	db.transaction(() => {
	57	const known = db.query("SELECT 1 FROM disk_reading WHERE machine = ? AND device = ? LIMIT 1").get(machine, device);
	58	if (!known) {
	59	const machineKnown = db.query("SELECT 1 FROM disk_reading WHERE machine = ? LIMIT 1").get(machine);
	60	if (!machineKnown) {
	61	const { n } = db.query("SELECT COUNT(DISTINCT machine) AS n FROM disk_reading").get() as { n: number };
	62	if (n >= MAX_MACHINES) return void (refused = "too-many-machines");
	63	} else {
	64	const { n } = db.query("SELECT COUNT(DISTINCT device) AS n FROM disk_reading WHERE machine = ?").get(machine) as { n: number };
	65	if (n >= MAX_DEVICES) return void (refused = "too-many-devices");
	66	}
	67	}
	68	db.query("INSERT INTO disk_reading (machine, device, taken_at, kind, reading) VALUES (?, ?, ?, ?, ?)").run(
	69	machine, device, now, parsed.kind, parsed.kind === "nvme" ? JSON.stringify(parsed) : null,
	70	);
	71	if (inventory)
	72	db.query(
	73	`INSERT INTO machine_inventory (machine, cpu, memory_bytes, updated_at) VALUES (?, ?, ?, ?)
	74	ON CONFLICT(machine) DO UPDATE SET cpu = excluded.cpu, memory_bytes = excluded.memory_bytes, updated_at = excluded.updated_at`,
	75	).run(machine, inventory.cpu, inventory.memoryBytes, now);
	76	// Prune: the summary reads only the newest two and the oldest inside the window.
	77	db.query(
	78	`DELETE FROM disk_reading WHERE machine = ?1 AND device = ?2 AND taken_at < ?3
	79	AND id NOT IN (SELECT id FROM disk_reading WHERE machine = ?1 AND device = ?2 ORDER BY taken_at DESC, id DESC LIMIT ?4)`,
	80	).run(machine, device, now - KEEP_DAYS * DAY_MS, KEEP_NEWEST);
	81	})();
	82	if (refused) return { ok: false, reason: refused };
	83	return { ok: true, kind: parsed.kind, takenAt: now };
	84	}
	85
	86	export type DeviceSummary =
	87	\| { device: string; kind: "behind-controller"; takenAt: number; reading: null; spec: null; assessment: null; bytesWrittenInWindow: null; ratedReachedAt: null }
	88	\| {
	89	device: string;
	90	kind: "nvme";
	91	takenAt: number;
	92	reading: DiskReading;
	93	inventory: { model: string; firmware: string; capacityBytes: number };
	94	spec: DiskSpec \| null;
	95	assessment: Assessment;
	96	/**
	97	* Bytes written between the oldest reading in the 30 days before the latest and the latest:
	98	* a 30-day figure only when spanDays is 30. Null with under two readings in the window.
	99	*/
	100	bytesWrittenInWindow: number \| null;
	101	/** Days that figure spans (≤ 30). */
	102	spanDays: number \| null;
	103	/** ISO date (UTC) rated TBW is reached at that rate; null with no spec, under two readings, or no growth. */
	104	ratedReachedAt: string \| null;
	105	};
	106
	107	export type MachineSummary = { machine: string; cpu: string \| null; memoryBytes: number \| null; devices: DeviceSummary[] };
	108
	109	type Row = { id: number; taken_at: number; kind: string; reading: string \| null };
	110	const COLS = "id, taken_at, kind, reading";
	111
	112	export function diskSummary(db: Database, machine: string): MachineSummary {
	113	const inv = db.query("SELECT cpu, memory_bytes FROM machine_inventory WHERE machine = ?").get(machine) as
	114	\| { cpu: string; memory_bytes: number }
	115	\| null;
	116	const devices = (db.query("SELECT DISTINCT device FROM disk_reading WHERE machine = ? ORDER BY device").all(machine) as { device: string }[]).map(
	117	(d) => d.device,
	118	);
	119	const out: DeviceSummary[] = [];
	120	for (const device of devices) {
	121	// Three bounded reads on (machine, device, taken_at): the latest row, the
	122	// newest two NVMe readings, and the oldest NVMe reading inside the window.
	123	const latest = db
	124	.query(`SELECT ${COLS} FROM disk_reading WHERE machine = ? AND device = ? ORDER BY taken_at DESC, id DESC LIMIT 1`)
	125	.get(machine, device) as Row;
	126	if (latest.kind !== "nvme" \|\| latest.reading === null) {
	127	out.push({ device, kind: "behind-controller", takenAt: latest.taken_at, reading: null, spec: null, assessment: null, bytesWrittenInWindow: null, ratedReachedAt: null });
	128	continue;
	129	}
	130	const nvme = db
	131	.query(
	132	`SELECT ${COLS} FROM disk_reading WHERE machine = ? AND device = ? AND kind = 'nvme' AND reading IS NOT NULL
	133	ORDER BY taken_at DESC, id DESC LIMIT 2`,
	134	)
	135	.all(machine, device) as Row[];
	136	const reading = JSON.parse(nvme[0]!.reading!) as DiskReading;
	137	const previous = nvme[1] ? (JSON.parse(nvme[1].reading!) as DiskReading) : null;
	138	const spec = diskSpec(reading.model);
	139
	140	const windowStart = latest.taken_at - WINDOW_DAYS * DAY_MS;
	141	const base = db
	142	.query(
	143	`SELECT ${COLS} FROM disk_reading WHERE machine = ? AND device = ? AND kind = 'nvme' AND reading IS NOT NULL
	144	AND taken_at >= ? AND id != ? ORDER BY taken_at ASC, id ASC LIMIT 1`,
	145	)
	146	.get(machine, device, windowStart, nvme[0]!.id) as Row \| null;
	147	let bytes30: number \| null = null;
	148	let spanDays: number \| null = null;
	149	let reached: string \| null = null;
	150	if (base && base.taken_at < latest.taken_at) {
	151	const baseReading = JSON.parse(base.reading!) as DiskReading;
	152	const delta = reading.bytesWritten - baseReading.bytesWritten;
	153	if (delta >= 0) {
	154	bytes30 = delta;
	155	spanDays = (latest.taken_at - base.taken_at) / DAY_MS;
	156	if (spec) {
	157	const remaining = spec.ratedTbw * 1e12 - reading.bytesWritten;
	158	if (remaining <= 0) reached = new Date(latest.taken_at).toISOString().slice(0, 10);
	159	else if (delta > 0) {
	160	const perDay = delta / spanDays;
	161	const at = new Date(latest.taken_at + (remaining / perDay) * DAY_MS);
	162	// A rate so small the date leaves the calendar is no projection.
	163	if (at.getUTCFullYear() <= 9999) reached = at.toISOString().slice(0, 10);
	164	}
	165	}
	166	}
	167	}
	168	out.push({
	169	device,
	170	kind: "nvme",
	171	takenAt: latest.taken_at,
	172	reading,
	173	inventory: { model: reading.model, firmware: reading.firmware, capacityBytes: reading.capacityBytes },
	174	spec,
	175	assessment: assessDisk(reading, previous, spec),
	176	bytesWrittenInWindow: bytes30,
	177	spanDays,
	178	ratedReachedAt: reached,
	179	});
	180	}
	181	return { machine, cpu: inv?.cpu ?? null, memoryBytes: inv?.memory_bytes ?? null, devices: out };
	182	}
	183
	184	/** Machine names that have a reading or an inventory, A to Z. */
	185	export function machineNames(db: Database): string[] {
	186	return (
	187	db.query("SELECT machine FROM disk_reading UNION SELECT machine FROM machine_inventory ORDER BY machine").all() as { machine: string }[]
	188	).map((r) => r.machine);
	189	}