faberun 0.10.0 → 0.12.0

package/src/report/render.mjs

@@ -171,7 +171,7 @@ function formatElapsed(node, now) {
 }
 
 /** @param {number} ms @returns {string} */
-function formatDuration(ms) {
+export function formatDuration(ms) {
   const totalSeconds = Math.floor(ms / 1000);
   const hours = Math.floor(totalSeconds / 3600);
   const minutes = Math.floor((totalSeconds % 3600) / 60);
@@ -537,7 +537,7 @@ function readNodes(runDir, contract) {
  * @param {string} runDir
  * @returns {{inputTokens: number, outputTokens: number, cacheReadInputTokens: number, costUsd: number|null}}
  */
-function readRunUsage(runDir) {
+export function readRunUsage(runDir) {
   const totals = { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0, costUsd: /** @type {number|null} */ (null) };
   const path = join(runDir, "usage.jsonl");
   if (!existsSync(path)) return totals;
@@ -733,7 +733,7 @@ export function roleCosts(nodes) {
  * @param {RoleUsage} role
  * @returns {string}
  */
-function formatRole(role) {
+export function formatRole(role) {
   if (role.costUsd !== null) return compactCost(role.costUsd);
   if (role.costProvenance === "none") return "-";
   return `unpriced (in ${compactTokens(role.inputTokens)} · out ${compactTokens(role.outputTokens)} · cache ${compactTokens(role.cacheReadInputTokens)})`;

package/src/run/migrate.mjs

@@ -0,0 +1,278 @@
+/**
+ * `faberun migrate`: the one command that moves a repository's legacy
+ * in-tree runs root into the project's directory under the home (R7).
+ *
+ * Separate from `run/paths.mjs` because that module resolves where state is
+ * read from and must keep answering throughout a migration, while this module
+ * owns the move itself, whose entire safety story is ordering. The resolver
+ * answers the home side the moment `<home>/projects/<id>/runs` exists, so the
+ * copy is never written there: it is staged at the sibling `runs.incoming`,
+ * verified, and published by one rename within the project's directory —
+ * same filesystem, so atomic. A reader therefore sees either the complete
+ * legacy tree, which keeps answering with its warning until the instant the
+ * rename lands, or the complete home copy, never a partial authoritative
+ * tree; a process killed mid-copy leaves nothing resolvable under the home.
+ *
+ * The controller lock is keyed by pid and process-start token, not by path,
+ * so the check before the copy cannot promise anything about the moment of
+ * removal: a resume that begins after that check and before the removal
+ * would have its state pulled out from under it. The re-check between the
+ * verified copy and the publish is what turns that race into a refusal, and
+ * a refused migration leaves the complete original in the tree and nothing
+ * authoritative under the home. A kill between the publish and the removal —
+ * the only two adjacent calls that touch both trees — is finished, not
+ * redone, by the next run: it verifies the published copy still holds every
+ * byte the original holds and removes the original.
+ *
+ * Idempotent by the same shape. A second run after a completed migration
+ * finds no legacy root and reports nothing to move — the normal case for an
+ * operator rerunning the command to be sure. A re-run after an interrupted
+ * one discards the staging copy it finds and copies anew: staging is never
+ * merged with, so no combination of two half-copies can ever be published.
+ *
+ * The target shape `<home>/projects/<id>/runs` and its staging sibling are
+ * composed here from `projectsDir` plus names `run/paths.mjs` keeps private;
+ * widening that module's surface for one caller is worse than spelling the
+ * two literals here, next to this comment.
+ */
+import { cpSync, existsSync, lstatSync, readFileSync, readlinkSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { campaignsDir } from "../campaign/layout.mjs";
+import { readRemotes } from "../cli/project.mjs";
+import { faberunHome } from "../host/home.mjs";
+import { projectsDir, registerProject } from "../host/projects.mjs";
+import { lockStale, readLock } from "./lock.mjs";
+import { RUNS_DIR_NAME } from "./paths.mjs";
+import { errorCode } from "../util.mjs";
+
+/** @typedef {{runDir: string, pid: number|undefined}} LiveLease */
+/** @typedef {{moved: boolean, legacy: string, target: string|null, runs: number, campaigns: number}} MigrateResult */
+
+/**
+ * `rmSync`'s own retry knobs for a recursive removal, applied to every
+ * removal in this module: Node's own docs name a large recursive removal as
+ * the case `maxRetries`/`retryDelay` exist for, retrying on EBUSY, EMFILE,
+ * ENFILE, ENOTEMPTY and EPERM. Measured 2026-09-19: a bare
+ * `rmSync(legacy, { recursive: true })` raised ENOTEMPTY twice running
+ * against this repository's own `.runs` — thousands of files across many
+ * attempt worktrees and controller snapshots — with no concurrent writer of
+ * this module's own; a fresh copy had already verified byte for byte before
+ * either attempt, so this was the removal racing something transient
+ * (Spotlight, a `.DS_Store` write, an FS event listener), never a sign the
+ * data was unsafe to remove.
+ */
+const REMOVE_OPTIONS = { recursive: true, maxRetries: 5, retryDelay: 100 };
+
+/**
+ * Move the legacy runs root at `<cwd>/.runs` into the home layout:
+ * `<home>/projects/<project id>/runs` for the project `cwd` registers as,
+ * with its git remotes recorded so a later repository move can be
+ * reassociated by remote. Fully synchronous, like every reader of run state
+ * in this tree.
+ *
+ * The migration refuses — before anything is written — while any run under
+ * the legacy root holds a live controller lock, and refuses again after the
+ * copy has verified, before the copy is published and the original removed.
+ *
+ * `options.leasesOf` replaces the live-lease scan. It exists so the
+ * between-copy-and-removal re-check has a named test: a fully synchronous
+ * migration cannot be interrupted from outside, so the race is staged from
+ * the injected scan instead.
+ *
+ * @param {string} cwd
+ * @param {{home?: string, leasesOf?: (tree: string) => LiveLease[]}} [options]
+ * @returns {MigrateResult}
+ */
+export function migrateRunState(cwd, options = {}) {
+  const home = options.home ?? faberunHome();
+  const leasesOf = options.leasesOf ?? liveLeases;
+  const legacy = join(cwd, RUNS_DIR_NAME);
+  if (!existsSync(legacy)) return { moved: false, legacy, target: null, runs: 0, campaigns: 0 };
+  refuseLiveLeases(leasesOf(legacy));
+  const project = registerProject(home, cwd, readRemotes(cwd));
+  const projectDir = join(projectsDir(home), project.id);
+  const target = join(projectDir, "runs");
+  // A published copy beside an untouched original is the one kill this
+  // ordering cannot route through staging: the previous attempt got through
+  // the rename and died before the removal. The copy needs no re-copying —
+  // only proof that it still holds every byte the original holds, after
+  // which removing the original finishes the move. Paths under the published
+  // copy that the original lacks are runs controllers appended after it
+  // became authoritative; this branch never writes to the copy, so nothing
+  // of theirs is at risk.
+  if (existsSync(target)) {
+    verifyCopy(legacy, target);
+    const runs = countRunDirs(legacy);
+    const campaigns = countCampaigns(legacy);
+    refuseLiveLeases(leasesOf(legacy));
+    rmSync(legacy, REMOVE_OPTIONS);
+    return { moved: true, legacy, target, runs, campaigns };
+  }
+  const staging = join(projectDir, "runs.incoming");
+  // A staging left by an interrupted attempt is a partial copy of a tree
+  // that may have changed since; it is discarded, never merged with.
+  rmSync(staging, { ...REMOVE_OPTIONS, force: true });
+  // verbatimSymlinks: the default resolves a copied link's target to an
+  // absolute path back into the tree being removed, which would dangle the
+  // moment the removal ran; verbatim keeps the literal target, so relative
+  // links (the worktrees' dependency symlinks) survive the move.
+  cpSync(legacy, staging, { recursive: true, verbatimSymlinks: true });
+  verifyCopy(legacy, staging);
+  verifyNothingExtra(legacy, staging);
+  const runs = countRunDirs(legacy);
+  const campaigns = countCampaigns(legacy);
+  // A lease found here began after the first check: its controller is still
+  // resolving the legacy tree — the copy is not published yet, so there is
+  // nothing else to resolve — and the publish would strand it on a tree
+  // about to be removed. Refusing leaves the complete original answering and
+  // nothing authoritative under the home; the re-run once the holder exits
+  // discards the staging, copies anew, and publishes.
+  refuseLiveLeases(leasesOf(legacy));
+  // The publish is the rename, and the rename is the only thing that ever
+  // creates `runs`: from this instant the home side is authoritative and
+  // complete, and nothing reads the legacy tree again except this removal.
+  renameSync(staging, target);
+  rmSync(legacy, REMOVE_OPTIONS);
+  return { moved: true, legacy, target, runs, campaigns };
+}
+
+/**
+ * Every controller lock under `tree` whose holder is still alive. The lock
+ * file's name is spelled here because `run/lock.mjs` keeps the constant
+ * private and this scan reads a whole tree, not one run directory. Symlinked
+ * directories are not descended into: the locks that lease this tree are the
+ * ones inside it.
+ *
+ * @param {string} tree
+ * @returns {LiveLease[]}
+ */
+function liveLeases(tree) {
+  /** @type {LiveLease[]} */
+  const leases = [];
+  /** @param {string} dir @returns {void} */
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(path);
+      } else if (entry.name === "controller.lock") {
+        const lock = readLock(dir);
+        if (!lockStale(lock)) {
+          leases.push({ runDir: dir, pid: lock && !("invalid" in lock) ? lock.pid : undefined });
+        }
+      }
+    }
+  };
+  walk(tree);
+  return leases;
+}
+
+/** @param {LiveLease[]} leases @returns {void} */
+function refuseLiveLeases(leases) {
+  const lease = leases[0];
+  if (lease) {
+    throw new Error(`run ${lease.runDir} holds a live controller lock (pid ${lease.pid ?? "unknown"}); stop the run or wait for its controller to exit, then run migrate again`);
+  }
+}
+
+/**
+ * What verify means here: every path under `source` must exist under `copy`
+ * with the same content — directories recursively, symlinks by their literal
+ * target, everything else byte for byte. That comparison is exactly the
+ * guarantee removal needs: once the original is gone the copy is the only
+ * holder of this state, so "holds every byte the original held" is the whole
+ * of what must be true, and byte-for-byte equality is the strongest check
+ * that proves it without trusting the copy step's own bookkeeping.
+ *
+ * @param {string} source
+ * @param {string} copy
+ * @returns {void}
+ */
+function verifyCopy(source, copy) {
+  for (const entry of readdirSync(source, { withFileTypes: true })) {
+    const from = join(source, entry.name);
+    const to = join(copy, entry.name);
+    if (entry.isDirectory()) {
+      // lstat, not stat: a copied symlink to a directory must not pass as
+      // the directory it points at.
+      if (!lstatSync(to, { throwIfNoEntry: false })?.isDirectory()) throw verifyFailure(from, to);
+      verifyCopy(from, to);
+    } else if (entry.isSymbolicLink()) {
+      if (readLinkOrUndefined(to) !== readlinkSync(from)) throw verifyFailure(from, to);
+    } else if (readOrUndefined(to)?.equals(readFileSync(from)) !== true) throw verifyFailure(from, to);
+  }
+}
+
+/**
+ * The staging copy must also hold nothing the original lacks. It was created
+ * by discarding any earlier staging and copying in one step, so an extra
+ * path means the copy step wrote outside its instructions — and the publish
+ * would make that invented state authoritative.
+ *
+ * @param {string} source
+ * @param {string} copy
+ * @returns {void}
+ */
+function verifyNothingExtra(source, copy) {
+  for (const entry of readdirSync(copy, { withFileTypes: true })) {
+    const inSource = join(source, entry.name);
+    const inCopy = join(copy, entry.name);
+    if (entry.isDirectory()) {
+      if (!lstatSync(inSource, { throwIfNoEntry: false })?.isDirectory()) throw verifyExtraFailure(inCopy);
+      verifyNothingExtra(inSource, inCopy);
+    } else if (entry.isSymbolicLink()) {
+      // readlinkSync, never readFileSync: a worktree's node_modules symlink
+      // (prepareWorktreeEnvironment in repo/worktree.mjs) targets a
+      // directory, and readFileSync on a symlink dereferences it — measured
+      // 2026-09-19, this crashed migrate with EISDIR against this
+      // repository's own .runs tree before the branch below existed.
+      if (readLinkOrUndefined(inSource) === undefined) throw verifyExtraFailure(inCopy);
+    } else if (readOrUndefined(inSource) === undefined) {
+      throw verifyExtraFailure(inCopy);
+    }
+  }
+}
+
+/** @param {string} from @param {string} to @returns {Error} */
+function verifyFailure(from, to) {
+  return new Error(`migration copy does not verify: ${from} is missing or different at ${to}; nothing was published or removed`);
+}
+
+/** @param {string} path @returns {Error} */
+function verifyExtraFailure(path) {
+  return new Error(`migration copy does not verify: ${path} is not part of the original; nothing was published or removed`);
+}
+
+/** @param {string} path @returns {Buffer|undefined} */
+function readOrUndefined(path) {
+  try {
+    return readFileSync(path);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+/** @param {string} path @returns {string|undefined} */
+function readLinkOrUndefined(path) {
+  try {
+    return readlinkSync(path);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+/** @param {string} runsDir @returns {number} */
+function countRunDirs(runsDir) {
+  return readdirSync(runsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(runsDir, entry.name, "contract.json")))
+    .length;
+}
+
+/** @param {string} runsDir @returns {number} */
+function countCampaigns(runsDir) {
+  const campaigns = campaignsDir(runsDir);
+  if (!existsSync(campaigns)) return 0;
+  return readdirSync(campaigns, { withFileTypes: true }).filter((entry) => entry.isDirectory()).length;
+}

package/src/run/paths.mjs

@@ -0,0 +1,189 @@
+/**
+ * Where a run, a campaign and a worktree tree live on disk, and the name of
+ * the runs directory itself.
+ *
+ * Every one of these shapes used to be spelled out inline, independently, at
+ * each call site that needed it, all sharing the literal `".runs"`. A later
+ * move or rename of that directory had to find and change every one of them
+ * separately; this module is the one place such a change is made instead. It
+ * composes `campaign/layout.mjs`, which already owns the campaign directory
+ * shape given a runs root, rather than re-deriving it.
+ *
+ * Since R2 the runs root answers from the operator's home, not the
+ * repository: `runsRoot(cwd)` is `<home>/projects/<id>/runs` for the project
+ * `cwd` belongs to, so run state survives a repository move and never lands
+ * inside the target tree. A repository that still holds its own `.runs` from
+ * before the move keeps being answered there until the migration command has
+ * run, because answering the home side of a not-yet-migrated repository would
+ * split its state across two layouts.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { campaignDir, campaignsDir } from "../campaign/layout.mjs";
+import { faberunHome } from "../host/home.mjs";
+import { findProjectByPath, projectsDir, readProject, registerProject } from "../host/projects.mjs";
+
+/** The runs directory name, relative to the tree it lives under. */
+export const RUNS_DIR_NAME = ".runs";
+
+/** The runs directory name inside a project's directory under the home. */
+const PROJECT_RUNS_DIR_NAME = "runs";
+
+/**
+ * The runs directory for a working tree: the project's runs directory under
+ * `faberunHome()`, or — for a repository that still holds its own `.runs`
+ * and has nothing under the home yet — that directory, with a warning.
+ *
+ * Resolving registers a never-seen path on demand. The alternative is a
+ * separate init step before the first run of any repository, which no
+ * existing workflow performs; a resolve is how every consumer announces the
+ * repository it is working on, so it is also where the registration belongs.
+ * The registry write happens once per path: a known project resolves through
+ * two small read-only reads (the index, the record).
+ *
+ * When both layouts exist the home side wins. That is the mid-migration
+ * case: the migration command copies the repository's state into the home
+ * and removes the original afterwards, so a present home directory is the
+ * authoritative copy and the leftover `.runs` is the stale pre-copy one.
+ * Letting the repository side win would make a completed migration whose
+ * cleanup failed silently answer from state the migration already superseded.
+ *
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function runsRoot(cwd) {
+  const home = faberunHome();
+  const project = findProjectByPath(home, cwd);
+  const homeRuns = project ? projectRunsDir(home, project.id) : null;
+  if (homeRuns && existsSync(homeRuns)) return homeRuns;
+  const legacy = join(cwd, RUNS_DIR_NAME);
+  if (existsSync(legacy)) {
+    warnLegacyRuns(legacy);
+    return legacy;
+  }
+  const registered = project ?? registerProject(home, cwd);
+  return projectRunsDir(home, registered.id);
+}
+
+/** @param {string} home @param {string} id @returns {string} */
+function projectRunsDir(home, id) {
+  return join(projectsDir(home), id, PROJECT_RUNS_DIR_NAME);
+}
+
+let warnedLegacyRuns = false;
+
+/**
+ * One warning per process, not per resolve: the resolver sits under a hot
+ * path, and repeating the same stderr line at every call would bury whatever
+ * the command is actually printing.
+ *
+ * @param {string} legacyPath
+ * @returns {void}
+ */
+function warnLegacyRuns(legacyPath) {
+  if (warnedLegacyRuns) return;
+  warnedLegacyRuns = true;
+  process.stderr.write(`[warn] runs · ${legacyPath} still holds this repository's runs; move them under the home with \`faberun migrate\`\n`);
+}
+
+/**
+ * The project id a runs directory under the home layout carries, or null for
+ * any other shape — a legacy `<repo>/.runs` answers null because
+ * `RUNS_DIR_NAME` is dotted and `PROJECT_RUNS_DIR_NAME` is not.
+ *
+ * `<home>/projects/<id>/runs` is composed entirely by this module, so the id
+ * sits at a fixed position: between the `projects` segment and the runs
+ * directory itself. Readers that must name the repository a runs directory
+ * belongs to (the AGENTS.md signal block, campaign ledger preservation) parse
+ * it here instead of deriving a sibling path by directory arithmetic, which
+ * only held while runs lived inside the repository.
+ *
+ * @param {string} runsDir
+ * @returns {string|null}
+ */
+export function projectIdForRunsDir(runsDir) {
+  const parts = resolve(runsDir).split(sep);
+  const id = parts.at(-2);
+  if (parts.at(-3) !== "projects" || parts.at(-1) !== PROJECT_RUNS_DIR_NAME || !id) return null;
+  return id;
+}
+
+/**
+ * The repository path a runs directory belongs to, read live from the
+ * project registry, or null when the runs directory is not under the home
+ * layout or its project has no record. Live, never cached: a project
+ * reassociated to a new path must answer its current repository.
+ *
+ * @param {string} runsDir
+ * @returns {string|null}
+ */
+export function repositoryForRunsDir(runsDir) {
+  const id = projectIdForRunsDir(runsDir);
+  if (!id) return null;
+  return readProject(faberunHome(), id)?.path ?? null;
+}
+
+/**
+ * A single run's own directory.
+ *
+ * @param {string} cwd
+ * @param {string} runId
+ * @returns {string}
+ */
+export function runDirectory(cwd, runId) {
+  return join(runsRoot(cwd), runId);
+}
+
+/**
+ * The campaigns directory beneath a runs root: `<runs>/campaigns`.
+ * Composes `campaign/layout.mjs`'s `campaignsDir`, which owns the shape given
+ * a runs root.
+ *
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function campaignsRoot(cwd) {
+  return campaignsDir(runsRoot(cwd));
+}
+
+/**
+ * A single campaign's own directory: `<runs>/campaigns/<campaignId>`.
+ * Composes `campaign/layout.mjs`'s `campaignDir`, which owns the shape given
+ * a runs root.
+ *
+ * @param {string} cwd
+ * @param {string} campaignId
+ * @returns {string}
+ */
+export function campaignTree(cwd, campaignId) {
+  return campaignDir(runsRoot(cwd), campaignId);
+}
+
+/** @param {string} runDir @param {string} runId @returns {string} */
+function worktreeRoot(runDir, runId) {
+  return join(dirname(runDir), "worktrees", runId);
+}
+
+/**
+ * The isolated worktree for one attempt at one node.
+ *
+ * @param {string} runDir
+ * @param {string} runId
+ * @param {string} nodeId
+ * @param {number} attempt
+ * @returns {string}
+ */
+export function attemptWorktreePath(runDir, runId, nodeId, attempt) {
+  return join(worktreeRoot(runDir, runId), `${nodeId}.${attempt}`);
+}
+
+/**
+ * The detached worktree an integration candidate is verified in.
+ *
+ * @param {string} runDir
+ * @param {string} runId
+ * @returns {string}
+ */
+export function candidateWorktreePath(runDir, runId) {
+  return join(worktreeRoot(runDir, runId), ".candidate");
+}

package/src/seat/index.mjs

@@ -18,6 +18,7 @@ import { briefFromState, materializeBrief } from "../campaign/brief.mjs";
 import { readProjectionState } from "../campaign/projection.mjs";
 import { resolveCampaign } from "../campaign/index.mjs";
 import { errorMessage } from "../util.mjs";
+import { runsRoot } from "../run/paths.mjs";
 
 /** `seat status --json` payload version. */
 const SEAT_STATUS_SCHEMA_VERSION = 1;
@@ -117,7 +118,7 @@ export function stopSeat(options = {}) {
  */
 export function switchSeat(options) {
   const cwd = resolve(options.cwd ?? ".");
-  const runsDir = join(cwd, ".runs");
+  const runsDir = runsRoot(cwd);
   let resolved;
   try {
     resolved = resolveCampaign(runsDir, options.campaign);

package/src/web/app.css

@@ -0,0 +1,170 @@
+:root {
+  --fr-terra: #B5522A; --fr-terra-300: #E0875F;
+  --fr-argila: #D97B4F; --fr-argila-300: #ECAB86;
+  --fr-areia: #F4E9D8;
+  --fr-folha: #556B3F; --fr-folha-300: #93AA70;
+  --fr-carvao: #1F1F1F;
+
+  --bg: var(--fr-areia); --surface: #ffffff; --surface-2: #ece3d2; --border: #d8cbb0;
+  --text: var(--fr-carvao); --text-2: #4a4437; --text-3: #7a725e;
+  --ok: var(--fr-folha); --ok-soft: #e3ead9;
+  --warn: var(--fr-argila); --warn-soft: #f7e6da;
+  --fail: var(--fr-terra); --fail-soft: #f5ded6;
+  --muted: #8a8471; --muted-soft: #e9e4d5;
+  --edge: #b8ac8e;
+
+  --sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: var(--fr-carvao); --surface: #262620; --surface-2: #2e2d26; --border: #45433a;
+    --text: var(--fr-areia); --text-2: #cfc7b3; --text-3: #a39c88;
+    --ok: var(--fr-folha-300); --ok-soft: #33402766;
+    --warn: var(--fr-argila-300); --warn-soft: #4a352566;
+    --fail: var(--fr-terra-300); --fail-soft: #4a2a1e66;
+    --muted: #96906f; --muted-soft: #3a382d;
+    --edge: #55523f;
+  }
+}
+* { box-sizing: border-box; }
+[hidden] { display: none !important; }
+body { margin: 0; background: var(--bg); color: var(--text); font: 14px/1.5 var(--sans); }
+a { color: var(--fr-terra); }
+button { font: inherit; color: inherit; background: none; border: none; cursor: pointer; }
+:focus-visible { outline: 2px solid var(--fr-terra); outline-offset: 2px; }
+.mono { font-family: var(--mono); font-size: 12.5px; }
+.dim { color: var(--text-2); }
+.empty { color: var(--text-3); padding: 10px 0; }
+
+#top {
+  display: flex; align-items: center; gap: 16px; padding: 12px 20px;
+  background: var(--surface); border-bottom: 1px solid var(--border);
+}
+#top .brand { font-weight: 700; color: var(--fr-terra); }
+.field { display: flex; align-items: center; gap: 6px; font-size: 12px; color: var(--text-3); text-transform: uppercase; letter-spacing: 0.04em; }
+.field select { font: inherit; text-transform: none; background: var(--surface-2); color: var(--text); border: 1px solid var(--border); border-radius: 4px; padding: 4px 8px; }
+#top .spacer { flex: 1; }
+#conn { font-size: 12px; color: var(--text-2); display: inline-flex; align-items: center; gap: 6px; }
+.dot { width: 8px; height: 8px; border-radius: 50%; background: var(--muted); display: inline-block; }
+.dot.live { background: var(--ok); }
+.dot.lost { background: var(--fail); }
+
+#main { max-width: 1180px; margin: 0 auto; padding: 24px 20px 60px; }
+.band { margin-top: 26px; }
+.band > h2 { font-size: 12px; font-weight: 700; letter-spacing: 0.05em; text-transform: uppercase; color: var(--text-3); margin: 0 0 10px; }
+.card { background: var(--surface); border: 1px solid var(--border); border-radius: 8px; padding: 14px 16px; }
+.caveat { color: var(--text-2); font-size: 12.5px; margin: 0 0 12px; }
+
+/* The opening band: the owner's four questions, answered the way the
+   notification answers them. It leads the page at every width. */
+.summaryband { display: flex; flex-direction: column; gap: 10px; }
+.sumhead { display: flex; align-items: baseline; gap: 12px; flex-wrap: wrap; }
+.sumname { font-weight: 700; font-size: 15px; color: var(--fr-terra); }
+@media (prefers-color-scheme: dark) { .sumname { color: var(--fr-terra-300); } }
+.sumgoal { color: var(--text-2); font-size: 13px; }
+.sumrow { font-size: 13px; }
+.sumrow.progressline { display: flex; align-items: center; gap: 12px; }
+.progresstrack { flex: 1; min-width: 120px; height: 8px; border-radius: 4px; background: var(--surface-2); border: 1px solid var(--border); overflow: hidden; }
+.progressfill { height: 100%; background: var(--ok); }
+.sumcounts { white-space: nowrap; font-variant-numeric: tabular-nums; }
+
+/* The collapsed spec map: a reference table a reader opens, styled so the
+   closed summary reads as the band heading it replaced. */
+.specdetails > summary { font-size: 12px; font-weight: 700; letter-spacing: 0.05em; text-transform: uppercase; color: var(--text-3); cursor: pointer; margin: 0 0 10px; display: inline-block; list-style: revert; }
+.specdetails > summary:hover { color: var(--text-2); }
+
+.specmap { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 14px; }
+.specfront h3 { font-size: 12.5px; margin: 0 0 8px; color: var(--fr-terra); }
+.reqrow { border-top: 1px solid var(--border); padding: 8px 0; }
+.reqrow:first-of-type { border-top: none; }
+.reqid { color: var(--text-3); }
+.reqstatement { font-size: 12.5px; margin: 2px 0; }
+.reqphase { font-size: 12px; color: var(--text-2); }
+
+/* `display: block` on the svg is load-bearing: a replaced inline element
+   (the svg default) inside an `overflow-x: auto` block can be sized as
+   though it never overflows, so the container never grows a scrollbar and
+   the trailing box (measured: the chain band's Release box) is cut off at
+   the viewport edge instead of reachable by scroll. */
+.graphcard { overflow-x: auto; width: 100%; }
+.graphcard svg { display: block; }
+.phasehead { margin: 0 0 10px; font-size: 13px; }
+.phasehead .phasename { font-weight: 650; }
+.phasehead p { margin: 2px 0 0; }
+
+svg .edge { stroke: var(--edge); stroke-width: 2; fill: none; }
+svg .node rect, svg .stage rect { stroke: var(--border); stroke-width: 1; fill: var(--muted-soft); cursor: pointer; }
+svg .node text, svg .stage text { fill: var(--text); font-family: var(--sans); font-size: 12px; }
+svg .node text.mono, svg .stage text.mono { font-family: var(--mono); }
+svg .node text.node-status, svg .stage text.stage-state { fill: var(--text-2); font-size: 11px; }
+svg .node.ok rect, svg .stage.done rect { fill: var(--ok-soft); stroke: var(--ok); }
+svg .node.progress rect, svg .stage.active rect { fill: var(--warn-soft); stroke: var(--warn); }
+svg .node.fail rect { fill: var(--fail-soft); stroke: var(--fail); }
+svg .node.muted rect, svg .stage.not_started rect { fill: var(--muted-soft); stroke: var(--muted); }
+svg .stage.current rect { stroke-width: 2.5; }
+svg .node:focus-visible rect, svg .stage:focus-visible rect { outline: 2px solid var(--fr-terra); outline-offset: 1px; }
+
+.pill { display: inline-flex; align-items: center; gap: 5px; padding: 1px 8px; border-radius: 4px; font-size: 12px; font-weight: 650; }
+.pill::before { content: ""; width: 6px; height: 6px; border-radius: 50%; background: currentColor; }
+.pill.ok { color: var(--ok); background: var(--ok-soft); }
+.pill.progress { color: var(--warn); background: var(--warn-soft); }
+.pill.warn { color: var(--warn); background: var(--warn-soft); }
+.pill.fail { color: var(--fail); background: var(--fail-soft); }
+.pill.muted { color: var(--muted); background: var(--muted-soft); }
+
+.drilldown-head { display: flex; align-items: center; gap: 10px; margin: 0 0 12px; }
+.drilldown-head h3 { margin: 0; font-size: 15px; }
+.drows { display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 8px 16px; margin-bottom: 14px; }
+.drow { display: flex; justify-content: space-between; gap: 8px; border-bottom: 1px solid var(--border); padding: 4px 0; font-size: 13px; }
+.dlabel { color: var(--text-3); text-transform: uppercase; font-size: 11px; letter-spacing: 0.03em; }
+.dvalue { font-family: var(--mono); font-size: 12.5px; text-align: right; }
+
+.detailblock { margin-top: 14px; }
+.detailblock h4 { font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em; color: var(--text-3); margin: 0 0 6px; }
+.link { padding: 2px 0; word-break: break-all; }
+.finding { padding: 6px 0; border-bottom: 1px solid var(--border); }
+.finding:last-child { border-bottom: none; }
+
+/* The worker transcript, one step per line: what the worker did, not the
+   wire format it did it in. The raw file the On-disk block names stays the
+   place to read the JSONL itself. */
+.tstep { padding: 5px 0; border-bottom: 1px solid var(--border); font-size: 12.5px; display: flex; align-items: baseline; gap: 7px; flex-wrap: wrap; }
+.tstep:last-child { border-bottom: none; }
+.tstep .mono { word-break: break-all; }
+.tstep.error { color: var(--fail); }
+.tstep.message { color: var(--text); }
+.tstep.note { color: var(--text-2); }
+pre { white-space: pre-wrap; word-break: break-word; background: var(--surface-2); border-radius: 8px; padding: 10px 12px; font-family: var(--mono); font-size: 12px; max-height: 360px; overflow: auto; }
+
+.timelinelist { display: flex; flex-direction: column; gap: 6px; }
+.trow { display: grid; grid-template-columns: 130px 140px 1fr; gap: 8px; font-size: 12.5px; border-bottom: 1px solid var(--border); padding: 4px 0; }
+.trow .tat { color: var(--text-3); }
+.trow .ttype { color: var(--fr-terra); font-weight: 600; }
+
+/* Narrow viewport (phone widths, ~390px and up to a small tablet): the
+   header stacks instead of clipping, the spec map collapses to one column,
+   and the bands reorder so the summary — the four answers — leads and the
+   open phase follows, with the spec map (a static requirement reference)
+   last. The markup is the same document at every width; only this media
+   query moves things, via `order` on the `#main` flex container below,
+   never by emitting different HTML for the two cases. */
+@media (max-width: 600px) {
+  #top { flex-wrap: wrap; row-gap: 8px; }
+  #top .field { flex: 1 1 100%; }
+  #top .field select { width: 100%; }
+  #top .spacer { flex: 0 0 0; display: none; }
+  #conn { flex: 1 1 100%; justify-content: flex-end; }
+
+  #main { display: flex; flex-direction: column; }
+  #summary { order: 1; }
+  #phaseGraph { order: 2; }
+  #chain { order: 3; }
+  #drilldown { order: 4; }
+  #specMap { order: 5; }
+
+  .specmap { grid-template-columns: 1fr; }
+
+  .goalclamp { display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 3; line-clamp: 3; overflow: hidden; cursor: pointer; }
+  .goalclamp:focus { -webkit-line-clamp: unset; line-clamp: unset; overflow: visible; }
+}