@haiyangbg/buildbeat 2.0.0-beta.3 → 2.0.0-beta.4

package/src/v2/cli/run.js

@@ -2,11 +2,18 @@
 // M1 runtime CLI: run start / status / stop for a single foreground run.
 // Deliberately thin — all facts live in the event ledger; this file only
 // parses input, wires adapters, and renders derived state.
+//
+// Iteration 08 adds the human-facing layer the deploy campaign showed was
+// missing: elapsed/typical time and live output in `status`, next-reply
+// commands wherever a run waits, supersession of stale waits, `gc` for the
+// runtime plane, `watch` + outbound notifications so a stopped run reaches
+// its human.
 
-import { execFileSync, spawnSync } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { createShellAdapter } from "../adapters/shell.js";
 import { loadRiskPreset } from "../engine/risk-preset.js";
@@ -22,7 +29,24 @@ import {
   latestAdjudications,
   readFindingsAccount,
 } from "../runtime/findings.js";
+import { loadEnvelope, nextAttemptId } from "../runtime/envelope.js";
+import { applyGc, planGc } from "../runtime/gc.js";
+import { computeOverview, renderOverview } from "../runtime/overview.js";
+import {
+  DEFAULT_STALL_AFTER_MS,
+  describeLiveness,
+  formatMs,
+  tailLive,
+} from "../runtime/liveness.js";
 import { computeMetrics, renderMetrics } from "../runtime/metrics.js";
+import {
+  NOTIFY_CONFIG,
+  buildNotification,
+  dispatchNotification,
+  loadNotifyConfig,
+  nextReply,
+  subscribes,
+} from "../runtime/notify.js";
 import { writeRunRecord } from "../runtime/run-record.js";
 import { resumeRun, startRun } from "../runtime/orchestrator.js";
 import { toRepoRef } from "../runtime/repo-ref.js";
@@ -34,10 +58,11 @@ const KERNEL = { kind: "kernel", id: "cli" };
 const USAGE = `BuildBeat v2 runtime
 
 Usage:
-  run.js start --config <run-config.yaml>
+  run.js start --config <run-config.yaml> [--attempt new]
   run.js resume --config <run-config.yaml>
-  run.js status --repo <path> --run <RUN-ID>
+  run.js status --repo <path> --run <RUN-ID> [--stall-after <minutes>]
   run.js inbox --repo <path>
+  run.js overview --repo <path> [--work <WORK-ID>] [--json true]
   run.js approve --repo <path> --run <RUN-ID> --transition <t> [--by <name>] [--config <run-config.yaml>]
   run.js reject --repo <path> --run <RUN-ID> [--transition <t>] [--reason <text>] [--by <name>]
   run.js accept --repo <path> --work <WORK-ID> --artifact <plan|intent|spec> [--by <name>]
@@ -46,6 +71,8 @@ Usage:
   run.js replay --repo <path> --run <RUN-ID>
   run.js metrics --repo <path> [--json true]
   run.js stop --repo <path> --run <RUN-ID> --reason <text>
+  run.js gc --repo <path> [--apply true] [--force true]
+  run.js watch --repo <path> --run <RUN-ID> [--stall-after <minutes>] [--interval <seconds>] [--once true]
   run.js observe run --config <observe.yaml>
   run.js observe status --repo <path>
   run.js observe triage --repo <path> --intent <ref> --action <fix_now|schedule|dismiss> [--by <name>] [--note <text>]
@@ -71,7 +98,45 @@ function ledgerPathFor(repo, runId) {
   return join(resolve(repo), ".buildbeat", "runtime", "runs", runId, "events.jsonl");
 }
 
-function printState(state, ledger) {
+function stallAfterFromFlags(flags, fallbackMs = DEFAULT_STALL_AFTER_MS) {
+  if (flags["stall-after-ms"] !== undefined) {
+    return Number(flags["stall-after-ms"]);
+  }
+  if (flags["stall-after"] !== undefined) {
+    return Number(flags["stall-after"]) * 60 * 1000;
+  }
+  return fallbackMs;
+}
+
+// The --repo value to print in copyable commands. Inside the project it is
+// the relative path the user would type; outside it a placeholder — printing
+// a machine-local absolute path is exactly what the output must never do.
+function repoLabelFor(repoRoot, typed) {
+  if (typed && !isAbsolute(typed)) {
+    return typed;
+  }
+  const rel = relative(process.cwd(), repoRoot);
+  if (rel === "") {
+    return ".";
+  }
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    return "<repo-path>";
+  }
+  return rel;
+}
+
+function printNextReply(repoLabel, state) {
+  const lines = nextReply({ repoLabel, state });
+  if (lines.length === 0) {
+    return;
+  }
+  console.log("next (copy one):");
+  for (const line of lines) {
+    console.log(`  ${line}`);
+  }
+}
+
+function printState(state, ledger, view = {}) {
   if (ledger.corruption) {
     console.log(
       `WARNING: ledger corrupted after seq=${ledger.corruption.afterSeq} at line ${ledger.corruption.atLine}: ${ledger.corruption.reason}`,
@@ -81,6 +146,15 @@ function printState(state, ledger) {
     console.log("no run recorded");
     return;
   }
+  const liveness =
+    view.repoRoot && ledger.events
+      ? describeLiveness({
+          repoRoot: view.repoRoot,
+          runId: state.run.id,
+          ledger,
+          stallAfterMs: view.stallAfterMs ?? DEFAULT_STALL_AFTER_MS,
+        })
+      : { steps: {}, inFlight: null };
   console.log(`run: ${state.run.id} (work ${state.run.work})`);
   console.log(`status: ${state.run.status}`);
   console.log(`workflow: ${state.run.workflowRef} @ ${state.run.workflowDigest}`);
@@ -90,17 +164,62 @@ function printState(state, ledger) {
     );
   }
   for (const [step, info] of Object.entries(state.steps)) {
-    console.log(`step ${step}: ${info.status} (attempts ${info.attempts})`);
+    const timing = liveness.steps[step];
+    let suffix = "";
+    if (timing && info.status !== "RUNNING") {
+      const parts = [];
+      if (timing.lastMs !== null) {
+        parts.push(`last ${formatMs(timing.lastMs)}`);
+      }
+      if (timing.attempts > 1) {
+        parts.push(`total ${formatMs(timing.totalMs)}`);
+      }
+      if (timing.typicalMs !== null) {
+        parts.push(`typical ${formatMs(timing.typicalMs)} n=${timing.samples}`);
+      }
+      if (parts.length > 0) {
+        suffix = ` [${parts.join(", ")}]`;
+      }
+    }
+    console.log(`step ${step}: ${info.status} (attempts ${info.attempts})${suffix}`);
+  }
+  const live = liveness.inFlight;
+  if (live) {
+    const typical = live.typicalMs !== null ? `, typical ${formatMs(live.typicalMs)} n=${live.samples}` : "";
+    console.log(
+      `in flight: ${live.step} attempt ${live.attempt} since ${live.startedAt} (elapsed ${formatMs(live.elapsedMs)}${typical})`,
+    );
+    if (live.command) {
+      console.log(`  worker: ${live.command}`);
+    }
+    if (live.lastOutputAt) {
+      console.log(`  last output: ${live.lastOutputAt} (${formatMs(live.sinceOutputMs)} ago, ${live.bytes} bytes so far)`);
+    } else {
+      console.log(`  last output: (none yet, ${formatMs(live.sinceOutputMs)} since start)`);
+    }
+    if (live.stalled) {
+      console.log(
+        `  STALLED: no output for ${formatMs(live.sinceOutputMs)} (threshold ${formatMs(live.stallAfterMs)}); process not killed — inspect, then stop or wait`,
+      );
+    }
+    const tail = tailLive(view.repoRoot, state.run.id, 3);
+    for (const line of tail) {
+      console.log(`  | ${line.slice(0, 160)}`);
+    }
   }
   for (const item of state.evidence) {
     const ref = isAbsolute(item.ref) ? "<legacy-absolute-evidence-ref>" : item.ref;
-    console.log(`evidence [${item.status}/${item.grade}] ${item.kind} ${ref}`);
+    const reused = item.reused ? ` (reused from ${item.reused.run})` : "";
+    console.log(`evidence [${item.status}/${item.grade}] ${item.kind} ${ref}${reused}`);
   }
   if (state.pendingHuman) {
     console.log(`waiting on human: ${state.pendingHuman.transition}`);
     for (const reason of state.pendingHuman.reasons) {
       console.log(`  reason: ${reason}`);
     }
+    if (view.repoLabel) {
+      printNextReply(view.repoLabel, state);
+    }
   }
   if (state.terminal) {
     console.log(`terminal: ${state.terminal.status} (${state.terminal.reason})`);
@@ -156,8 +275,35 @@ function loadRunConfig(flags, command) {
   if (config.reviewTriage !== undefined && !["required", "off"].includes(config.reviewTriage)) {
     throw new Error(`reviewTriage must be "required" or "off", got: ${config.reviewTriage}`);
   }
+  if (config.supersede !== undefined && !["waiting", "off"].includes(config.supersede)) {
+    throw new Error(`supersede must be "waiting" or "off", got: ${config.supersede}`);
+  }
+  if (config.stallAfterMs !== undefined && !(Number(config.stallAfterMs) > 0)) {
+    throw new Error(`stallAfterMs must be a positive number, got: ${config.stallAfterMs}`);
+  }
+  const cache = {};
+  for (const [step, mode] of Object.entries(config.cache ?? {})) {
+    if (mode !== "tree") {
+      throw new Error(`cache.${step} must be "tree", got: ${mode}`);
+    }
+    if (!workflow.stepIds.has(step)) {
+      throw new Error(`cache.${step}: step not in workflow`);
+    }
+    cache[step] = mode;
+  }
+  const redact = (config.redact ?? []).map((pattern) => {
+    try {
+      return new RegExp(String(pattern), "g");
+    } catch {
+      throw new Error(`redact pattern is not a valid regular expression: ${pattern}`);
+    }
+  });
+  const envelope = loadEnvelope(config, configDir, Object.keys(config.workers ?? {}));
 
   return {
+    envelope,
+    cache,
+    redact,
     repoRoot,
     workflow,
     workflowDigest,
@@ -175,54 +321,178 @@ function loadRunConfig(flags, command) {
     allowedPaths: config.allowedPaths,
     requires: config.requires ?? [],
     reviewTriage: config.reviewTriage === "required" ? "required" : null,
+    supersede: config.supersede ?? "waiting",
+    stallAfterMs: config.stallAfterMs !== undefined ? Number(config.stallAfterMs) : DEFAULT_STALL_AFTER_MS,
     planDigest: digestOfWorkFile("plan.md"),
     intentDigest: digestOfWorkFile("intent.md"),
   };
 }
 
-function commandStart(flags) {
+// Notification config is optional and never fatal for a run: a broken file
+// is reported once and the run proceeds without outbound messages.
+function notifyConfigFor(repoRoot) {
+  try {
+    return { config: loadNotifyConfig(repoRoot), error: null };
+  } catch (error) {
+    return { config: null, error: error.message };
+  }
+}
+
+async function notifyForState(repoRoot, repoLabel, state) {
+  const { config, error } = notifyConfigFor(repoRoot);
+  if (error) {
+    console.log(`notify: config ignored (${error})`);
+    return;
+  }
+  if (!config || !state.run) {
+    return;
+  }
+  const kinds = [];
+  if (state.pendingHuman && state.run.status === "WAITING_HUMAN") {
+    kinds.push("HUMAN_REQUESTED");
+  }
+  if (state.terminal) {
+    kinds.push("RUN_TERMINAL");
+  }
+  for (const kind of kinds) {
+    if (!subscribes(config, kind)) {
+      continue;
+    }
+    const results = await dispatchNotification(config, buildNotification(kind, { repoLabel, state }), { repoRoot });
+    for (const row of results) {
+      const outcome = row.ok ? "sent" : row.skipped ? `skipped (${row.error})` : `FAILED (${row.error})`;
+      console.log(`notify ${kind} -> ${row.channel}: ${outcome}`);
+    }
+  }
+}
+
+// A stall watcher is a separate detached process: the orchestrator blocks in
+// spawnSync while a worker runs, so it cannot look at the clock itself. The
+// watcher exits on its own once the run is no longer RUNNING or the parent
+// process is gone.
+function spawnStallWatcher(repoRoot, runId, stallAfterMs) {
+  const { config } = notifyConfigFor(repoRoot);
+  if (!subscribes(config, "STALLED")) {
+    return false;
+  }
+  const child = spawn(
+    process.execPath,
+    [
+      fileURLToPath(import.meta.url),
+      "watch",
+      "--repo",
+      repoRoot,
+      "--run",
+      runId,
+      "--stall-after-ms",
+      String(stallAfterMs),
+      "--parent",
+      String(process.pid),
+    ],
+    { detached: true, stdio: "ignore" },
+  );
+  child.unref();
+  return true;
+}
+
+async function commandStart(flags) {
   const options = loadRunConfig(flags, "start");
+  if (flags.attempt !== undefined) {
+    if (flags.attempt !== "new") {
+      throw new Error(`--attempt must be "new" (auto-number the next run of this family), got: ${flags.attempt}`);
+    }
+    // The run config names the family; the kernel numbers the attempt. One
+    // config per work, not one per retry (the campaign hand-numbered -01..-30).
+    options.runId = nextAttemptId(options.repoRoot, options.workId, options.runId);
+    console.log(`attempt: ${options.runId}`);
+  }
+  if (options.envelope) {
+    console.log(`envelope: ${options.envelope.source} (${Object.keys(options.envelope.prompts).join(", ")}) ${options.envelope.digest}`);
+  }
   if (process.stdout.isTTY) {
     // Run launch discipline (real incident: a host-tool timeout killed a
     // verify worker mid-run): anything longer than minutes belongs in a
     // detached process, not an interactive foreground shell.
     console.log("tip: long runs should be started detached (nohup/setsid); interactive shells die with their host");
   }
+  const watching = spawnStallWatcher(options.repoRoot, options.runId, options.stallAfterMs);
+  if (watching) {
+    console.log(`stall watcher armed (no output for ${formatMs(options.stallAfterMs)} notifies STALLED)`);
+  }
   const result = startRun(options);
+  const repoLabel = repoLabelFor(options.repoRoot);
+  for (const run of result.superseded ?? []) {
+    console.log(`superseded ${run} (was waiting on a human for the same work; now SUPERSEDED)`);
+  }
+  for (const row of result.supersedeSkipped ?? []) {
+    console.log(`could not supersede ${row.run}: ${row.reason}`);
+  }
   console.log(`ledger: ${toRepoRef(options.repoRoot, result.ledgerPath)}`);
-  printState(result.state, { corruption: null });
+  const ledger = EventLedger.open(result.ledgerPath);
+  printState(ledger.state, ledger, {
+    repoRoot: options.repoRoot,
+    repoLabel,
+    stallAfterMs: options.stallAfterMs,
+  });
+  await notifyForState(options.repoRoot, repoLabel, ledger.state);
 }
 
-function commandResume(flags) {
+async function commandResume(flags) {
   const options = loadRunConfig(flags, "resume");
+  const watching = spawnStallWatcher(options.repoRoot, options.runId, options.stallAfterMs);
+  if (watching) {
+    console.log(`stall watcher armed (no output for ${formatMs(options.stallAfterMs)} notifies STALLED)`);
+  }
   const result = resumeRun(options);
+  const repoLabel = repoLabelFor(options.repoRoot);
   if (!result.resumed) {
     console.log(`nothing to resume: ${result.reason}`);
   }
   console.log(`ledger: ${toRepoRef(options.repoRoot, result.ledgerPath)}`);
-  printState(result.state, { corruption: null });
+  const ledger = EventLedger.open(result.ledgerPath);
+  printState(ledger.state, ledger, {
+    repoRoot: options.repoRoot,
+    repoLabel,
+    stallAfterMs: options.stallAfterMs,
+  });
+  if (result.resumed) {
+    await notifyForState(options.repoRoot, repoLabel, ledger.state);
+  }
 }
 
 function commandInbox(flags) {
   if (!flags.repo) {
     throw new Error("inbox requires --repo");
   }
-  const rows = listInbox(resolve(flags.repo));
+  const repoRoot = resolve(flags.repo);
+  const rows = listInbox(repoRoot);
   if (rows.length === 0) {
     console.log("inbox empty: no runs waiting on a human");
     return;
   }
-  for (const row of rows) {
+  const sorted = [...rows].sort((a, b) => `${a.work ?? ""}${a.run}`.localeCompare(`${b.work ?? ""}${b.run}`));
+  let lastWork = null;
+  for (const row of sorted) {
     if (row.corrupted) {
       console.log(`${row.run}: LEDGER CORRUPTED after seq=${row.corrupted.afterSeq} (${row.corrupted.reason})`);
       continue;
     }
-    console.log(`${row.run} (work ${row.work}) [${row.kind}] ${row.transition}`);
-    console.log(`  candidate: ${row.subject.candidate}`);
-    console.log(`  planDigest: ${row.subject.planDigest}`);
-    console.log(`  evidenceDigest: ${row.subject.evidenceDigest}`);
+    if (row.work !== lastWork) {
+      console.log(`work ${row.work}:`);
+      lastWork = row.work;
+    }
+    const ledger = EventLedger.open(ledgerPathFor(repoRoot, row.run));
+    const requested = [...ledger.events].reverse().find((event) => event.type === "HUMAN_REQUESTED");
+    const age = requested ? formatMs(Date.now() - Date.parse(requested.ts)) : "?";
+    console.log(`  ${row.run} [${row.kind}] ${row.transition} — waiting ${age}${requested ? ` (since ${requested.ts})` : ""}`);
+    console.log(`    candidate: ${row.subject.candidate}`);
+    console.log(`    planDigest: ${row.subject.planDigest}`);
+    console.log(`    evidenceDigest: ${row.subject.evidenceDigest}`);
     for (const reason of row.reasons) {
-      console.log(`  reason: ${reason}`);
+      console.log(`    reason: ${reason}`);
+    }
+    for (const line of nextReply({ repoLabel: repoLabelFor(repoRoot, flags.repo), state: ledger.state })) {
+      console.log(`    next: ${line}`);
     }
   }
 }
@@ -335,6 +605,20 @@ function commandDoctor(flags) {
   } else {
     console.log("environment contract: none declared (implicit PATH facts stay unchecked)");
   }
+  console.log(`supersede: ${options.supersede} (new run for the same work ${options.supersede === "off" ? "leaves" : "supersedes"} older WAITING_HUMAN runs)`);
+  console.log(`stall threshold: ${formatMs(options.stallAfterMs)} without worker output`);
+  const { config: notify, error: notifyError } = notifyConfigFor(options.repoRoot);
+  if (notifyError) {
+    console.log(`notify: PROBLEM ${notifyError}`);
+  } else if (!notify) {
+    console.log(`notify: none (${NOTIFY_CONFIG} absent; a waiting run reaches nobody until someone runs inbox)`);
+  } else {
+    console.log("notify channels:");
+    for (const channel of notify.channels) {
+      const urlState = process.env[channel.urlEnv] ? "url env set" : `WARNING env ${channel.urlEnv} not set in this shell`;
+      console.log(`  ${channel.id}: type=${channel.type} events=${channel.events.join(",")} (${urlState})`);
+    }
+  }
 }
 
 // Preflight: run one step's configured worker command directly in the main
@@ -469,7 +753,7 @@ function commandReplay(flags) {
   } else {
     console.log(`chain OK: ${ledger.events.length} events verified (digest/prev/seq)`);
   }
-  printState(ledger.state, { corruption: null });
+  printState(ledger.state, { corruption: null }, {});
 }
 
 function commandMetrics(flags) {
@@ -488,8 +772,13 @@ function commandStatus(flags) {
   if (!flags.repo || !flags.run) {
     throw new Error("status requires --repo and --run");
   }
-  const ledger = EventLedger.open(ledgerPathFor(flags.repo, flags.run));
-  printState(ledger.state, ledger);
+  const repoRoot = resolve(flags.repo);
+  const ledger = EventLedger.open(ledgerPathFor(repoRoot, flags.run));
+  printState(ledger.state, ledger, {
+    repoRoot,
+    repoLabel: repoLabelFor(repoRoot, flags.repo),
+    stallAfterMs: stallAfterFromFlags(flags),
+  });
 }
 
 function commandStop(flags) {
@@ -519,6 +808,147 @@ function commandStop(flags) {
   }
 }
 
+function commandOverview(flags) {
+  if (!flags.repo) {
+    throw new Error("overview requires --repo");
+  }
+  const repoRoot = resolve(flags.repo);
+  const rows = computeOverview(repoRoot, { work: flags.work ?? null, repoLabel: repoLabelFor(repoRoot, flags.repo) });
+  if (flags.json === "true") {
+    console.log(JSON.stringify(rows, null, 2));
+    return;
+  }
+  console.log(renderOverview(rows));
+}
+
+function commandGc(flags) {
+  if (!flags.repo) {
+    throw new Error("gc requires --repo");
+  }
+  const repoRoot = resolve(flags.repo);
+  const rows = planGc(repoRoot);
+  if (rows.length === 0) {
+    console.log("gc: no run ledgers found");
+    return;
+  }
+  let actionable = 0;
+  for (const row of rows) {
+    const summary = row.actions.map((action) => {
+      if (action.kind === "remove-worktree") {
+        return `remove worktree${action.dirty ? " (DIRTY, needs --force)" : ""}`;
+      }
+      if (action.kind === "delete-branch") {
+        return `delete branch ${action.branch} (${action.reason})`;
+      }
+      return "remove stale lock";
+    });
+    actionable += row.actions.length;
+    const keep = row.keep.map((reason) => `keep: ${reason}`);
+    const parts = [...summary, ...keep];
+    console.log(`${row.run} [${row.status}] ${parts.length > 0 ? parts.join("; ") : "nothing to do"}`);
+  }
+  if (flags.apply !== "true") {
+    console.log(
+      actionable > 0
+        ? `plan only: ${actionable} action(s); rerun with --apply true to execute (branches whose candidate lives only there are always kept)`
+        : "nothing to collect",
+    );
+    return;
+  }
+  const results = applyGc(repoRoot, rows, { force: flags.force === "true" });
+  let done = 0;
+  for (const result of results) {
+    const target = result.kind === "delete-branch" ? result.branch : result.path;
+    if (result.done) {
+      done += 1;
+      console.log(`  ${result.kind} ${target}: done`);
+    } else {
+      console.log(`  ${result.kind} ${target}: NOT done (${result.error})`);
+    }
+  }
+  console.log(`gc applied: ${done}/${results.length} action(s)`);
+}
+
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const sleep = (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+
+// Watches one RUNNING run and reports a stall once per step attempt. Exits
+// when the run leaves RUNNING, the parent process (if given) dies, or after a
+// single pass with --once true.
+async function commandWatch(flags) {
+  if (!flags.repo || !flags.run) {
+    throw new Error("watch requires --repo and --run");
+  }
+  const repoRoot = resolve(flags.repo);
+  const stallAfterMs = stallAfterFromFlags(flags);
+  const intervalMs = Number(flags.interval ?? 30) * 1000;
+  const parent = flags.parent ? Number(flags.parent) : null;
+  const repoLabel = repoLabelFor(repoRoot, flags.repo);
+  const { config } = notifyConfigFor(repoRoot);
+  const notified = new Set();
+  let notifiedThisPass = false;
+  for (;;) {
+    notifiedThisPass = false;
+    const ledger = EventLedger.open(ledgerPathFor(repoRoot, flags.run));
+    if (!ledger.state.run) {
+      console.log(`watch: no ledger for ${flags.run} yet`);
+    } else if (ledger.state.run.status !== "RUNNING") {
+      console.log(`watch: run is ${ledger.state.run.status}; done`);
+      return;
+    } else {
+      const liveness = describeLiveness({ repoRoot, runId: flags.run, ledger, stallAfterMs });
+      const live = liveness.inFlight;
+      if (live?.stalled) {
+        const key = `${live.step}#${live.attempt}`;
+        if (!notified.has(key)) {
+          notified.add(key);
+          notifiedThisPass = true;
+          console.log(
+            `watch: STALLED ${live.step} attempt ${live.attempt} — no output for ${formatMs(live.sinceOutputMs)} (threshold ${formatMs(stallAfterMs)})`,
+          );
+          if (subscribes(config, "STALLED")) {
+            const notification = buildNotification("STALLED", {
+              repoLabel,
+              state: ledger.state,
+              detail: {
+                step: live.step,
+                attempt: live.attempt,
+                startedAt: live.startedAt,
+                elapsed: formatMs(live.elapsedMs),
+                sinceOutput: formatMs(live.sinceOutputMs),
+                threshold: formatMs(stallAfterMs),
+                command: live.command,
+              },
+            });
+            const results = await dispatchNotification(config, notification, { repoRoot });
+            for (const row of results) {
+              console.log(`watch: notify -> ${row.channel}: ${row.ok ? "sent" : row.error}`);
+            }
+          }
+        }
+      } else if (live) {
+        console.log(`watch: ${live.step} attempt ${live.attempt} elapsed ${formatMs(live.elapsedMs)}, last output ${formatMs(live.sinceOutputMs)} ago`);
+      }
+    }
+    if (flags.once === "true") {
+      return notifiedThisPass;
+    }
+    if (parent !== null && !processAlive(parent)) {
+      console.log("watch: parent process gone; done");
+      return;
+    }
+    await sleep(intervalMs);
+  }
+}
+
 function commandObserve(rest) {
   const [sub, ...args] = rest;
   const flags = parseFlags(args);
@@ -577,7 +1007,7 @@ function commandObserve(rest) {
   }
 }
 
-function main() {
+async function main() {
   const [command, ...rest] = process.argv.slice(2);
   if (command === "observe" || command === "findings") {
     try {
@@ -591,9 +1021,9 @@ function main() {
   try {
     const flags = parseFlags(rest);
     if (command === "start") {
-      commandStart(flags);
+      await commandStart(flags);
     } else if (command === "resume") {
-      commandResume(flags);
+      await commandResume(flags);
     } else if (command === "inbox") {
       commandInbox(flags);
     } else if (command === "approve") {
@@ -614,6 +1044,12 @@ function main() {
       commandStatus(flags);
     } else if (command === "stop") {
       commandStop(flags);
+    } else if (command === "gc") {
+      commandGc(flags);
+    } else if (command === "overview") {
+      commandOverview(flags);
+    } else if (command === "watch") {
+      await commandWatch(flags);
     } else if (command === "preflight") {
       commandPreflight(flags);
     } else {
@@ -627,4 +1063,4 @@ function main() {
   }
 }
 
-main();
+await main();

package/src/v2/engine/reducer.js

@@ -143,6 +143,8 @@ export function applyEvent(state, event) {
         ...(data.suppressedFingerprints
           ? { suppressedFingerprints: data.suppressedFingerprints }
           : {}),
+        ...(data.cacheKey ? { cacheKey: data.cacheKey } : {}),
+        ...(data.reused ? { reused: data.reused } : {}),
       });
       break;
     }

package/src/v2/engine/workflow.js

@@ -27,7 +27,8 @@ const TOP_FIELDS = new Set([
   "policies",
   "budgets",
 ]);
-const STEP_FIELDS = new Set(["id", "worker", "optional", "requiredWhen", "readonly"]);
+const STEP_FIELDS = new Set(["id", "worker", "optional", "requiredWhen", "readonly", "grade"]);
+const EVIDENCE_GRADES = new Set(["L0", "L1", "L2", "L3", "L4"]);
 const TRANSITION_FIELDS = new Set(["from", "on", "to"]);
 
 function rejectUnknownFields(object, allowed, where) {
@@ -82,6 +83,11 @@ export function parseWorkflow(text) {
     if (raw.readonly !== undefined && typeof raw.readonly !== "boolean") {
       throw new WorkflowError(`step ${id} readonly must be a boolean`);
     }
+    // Evidence grade a step's command evidence is recorded at (iteration 08:
+    // release readbacks run against the real environment and are L4).
+    if (raw.grade !== undefined && !EVIDENCE_GRADES.has(raw.grade)) {
+      throw new WorkflowError(`step ${id} grade must be one of L0-L4`);
+    }
     stepIds.add(id);
     steps.push({
       id,
@@ -89,6 +95,7 @@ export function parseWorkflow(text) {
       optional: raw.optional ?? false,
       requiredWhen: raw.requiredWhen ?? null,
       readonly: raw.readonly ?? false,
+      grade: raw.grade ?? "L2",
     });
   }