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

package/src/v2/runtime/orchestrator.js

@@ -11,7 +11,7 @@
 // anything changed goes APPROVAL_STALE and back to WAITING_HUMAN.
 
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { nextStep } from "../engine/workflow.js";
@@ -26,6 +26,17 @@ import {
   releaseLock,
 } from "../workspace/workspace-manager.js";
 import { writeRunRecord } from "./run-record.js";
+import { assertRequires } from "./env-contract.js";
+import { materialisePrompt } from "./envelope.js";
+import { cacheKey, findReusableEvidence, lastReviewedCandidate, treeHash } from "./cache.js";
+import {
+  buildAnchor,
+  fingerprintFinding,
+  latestAdjudications,
+  readFindingsAccount,
+  recordReviewFindings,
+} from "./findings.js";
+import { resolveRepoRef, toRepoRef } from "./repo-ref.js";
 
 const KERNEL = { kind: "kernel", id: "orchestrator" };
 
@@ -135,6 +146,11 @@ function makeContext(options, ledger, workspace) {
     workflow.budgets?.maxAttempts?.[step] ?? maxAttemptsPerStep;
   context.policies = options.policies ?? [];
   context.allowedPaths = options.allowedPaths ?? null;
+  context.reviewTriage = options.reviewTriage ?? null;
+  context.envelope = options.envelope ?? null;
+  context.cache = options.cache ?? {};
+  context.redact = options.redact ?? [];
+  context.adapterConfigs = options.adapterConfigs ?? {};
   context.policyCtx = () => ({
     state: ledger.state,
     candidate: ledger.state.workspaces[workspace.workspaceId]?.candidate ?? null,
@@ -219,6 +235,14 @@ function settleOutcome(context, step, outcome, tree, exec) {
       ]);
       return null;
     }
+    // A step that failed its final attempt can never run again, so routing
+    // to fix would spend a worker on a candidate nothing can verify.
+    if ((ledger.state.steps[step]?.attempts ?? 0) >= context.maxAttemptsFor(step)) {
+      context.waitHuman(`resume-${step}`, [
+        `budget exhausted: ${step} failed its final attempt (maxAttempts=${context.maxAttemptsFor(step)}); not routing to fix`,
+      ]);
+      return null;
+    }
   }
   const to = nextStep(workflow, step, outcome);
   let result = "PASS";
@@ -337,14 +361,100 @@ function drive(context, startStep, { skipBoundaryOnce = false } = {}) {
     const outputsDir = join(context.runtimeDir, "runs", ledger.state.run.id, "outputs");
     mkdirSync(outputsDir, { recursive: true });
     const outputPath = join(outputsDir, `${step}-${attempt}.json`);
-    const exec = adapter.execute({
-      step,
+    // Anchored review: readonly (reviewer) steps receive the adjudicated
+    // findings history so a fresh reviewer inherits settled verdicts instead
+    // of re-litigating them; writing steps get the latest review findings
+    // with their adjudication status (the fixer's worklist).
+    const input = { workId: ledger.state.run.work, runId: ledger.state.run.id, step, attempt };
+    const anchor = buildAnchor(context.repoRoot, ledger.state.run.work);
+    if (anchor && stepDef.readonly) {
+      input.anchor = anchor;
+    } else if (anchor) {
+      const lastReview = [...ledger.state.evidence]
+        .reverse()
+        .find((item) => item.kind === "review");
+      if (lastReview?.findings?.length) {
+        const adjudicated = latestAdjudications(
+          readFindingsAccount(context.repoRoot, ledger.state.run.work),
+        );
+        input.findings = lastReview.findings.map((finding) => ({
+          severity: finding.severity,
+          summary: finding.summary,
+          fingerprint: fingerprintFinding(finding),
+          adjudication: adjudicated.get(fingerprintFinding(finding))?.action ?? "open",
+        }));
+      }
+    }
+    // Envelope (C6): the worker's prompt, materialised into the run
+    // directory and handed over as BUILDBEAT_PROMPT / input.envelope.
+    const prompt = materialisePrompt({
+      envelope: context.envelope,
       worker: stepDef.worker,
-      workspacePath: workspace.worktreePath,
-      input: { workId: ledger.state.run.work, runId: ledger.state.run.id, step, attempt },
-      timeoutMs: context.stepTimeoutMs,
-      outputPath,
+      runtimeDir: context.runtimeDir,
+      runId: ledger.state.run.id,
+      step,
+      attempt,
+      repoRoot: context.repoRoot,
     });
+    if (prompt) {
+      input.envelope = { promptRef: prompt.ref, file: prompt.file, digest: context.envelope.digest, vars: context.envelope.vars };
+    }
+    // Incremental review (C7): tell a reviewer which candidate the last
+    // review saw when it is an ancestor of this one.
+    if (stepDef.readonly) {
+      const head = before.head;
+      const lastReviewed = lastReviewedCandidate(context.repoRoot, ledger.state.run.work, workspace.worktreePath, head);
+      if (lastReviewed) {
+        input.lastReviewed = lastReviewed;
+      }
+    }
+    // Verification reuse (C7): same tree + same worker + same envelope that
+    // already passed is referenced, not re-run. Failures always re-run.
+    let stepCacheKey = null;
+    let reused = null;
+    if (context.cache[step] === "tree") {
+      const current = readback(workspace.worktreePath);
+      if (!current.dirty) {
+        stepCacheKey = cacheKey({
+          tree: treeHash(workspace.worktreePath),
+          worker: stepDef.worker,
+          adapterSpec: context.adapterConfigs[stepDef.worker] ?? null,
+          adapterName: adapter.name,
+          envelopeDigest: context.envelope?.digest ?? null,
+        });
+        reused = findReusableEvidence(context.repoRoot, stepCacheKey);
+      }
+    }
+    let exec;
+    if (reused) {
+      const at = now();
+      exec = {
+        adapter: "cache",
+        command: `reuse ${reused.run} ${reused.evidenceRef}`,
+        exitCode: 0,
+        signal: null,
+        stdout: `REUSED: identical tree/worker/envelope already passed in ${reused.run} (${reused.evidenceRef}, ${reused.digest}); not re-run`,
+        stderr: "",
+        timedOut: false,
+        spawnError: null,
+        startedAt: at,
+        finishedAt: at,
+      };
+    } else {
+      exec = adapter.execute({
+        step,
+        worker: stepDef.worker,
+        workspacePath: workspace.worktreePath,
+        input,
+        timeoutMs: context.stepTimeoutMs,
+        outputPath,
+        // Live output streams + marker land in the run directory so `status`
+        // can answer "is it still doing something" while the step runs.
+        liveDir: join(context.runtimeDir, "runs", ledger.state.run.id),
+        promptPath: prompt?.path ?? null,
+        vars: context.envelope?.vars ?? null,
+      });
+    }
     const tree = readback(workspace.worktreePath);
     const evidence = collectCommandEvidence({
       runtimeDir: context.runtimeDir,
@@ -353,18 +463,22 @@ function drive(context, startStep, { skipBoundaryOnce = false } = {}) {
       attempt,
       execResult: exec,
       subject: tree.head,
+      grade: reused ? reused.grade : stepDef.grade ?? "L2",
+      redact: context.redact,
     });
     ledger.append({
       type: "EVIDENCE_RECORDED",
       actor: KERNEL,
       ts: now(),
       data: {
-        evidenceRef: evidence.location,
+        evidenceRef: toRepoRef(context.repoRoot, evidence.location),
         kind: evidence.kind,
         subject: evidence.subject,
         digest: evidence.digest,
         status: evidence.status,
         grade: evidence.grade,
+        ...(stepCacheKey ? { cacheKey: stepCacheKey } : {}),
+        ...(reused ? { reused: { run: reused.run, evidenceRef: reused.evidenceRef, digest: reused.digest } } : {}),
       },
     });
 
@@ -432,21 +546,39 @@ function drive(context, startStep, { skipBoundaryOnce = false } = {}) {
 
     let blockingFindings = [];
     if (envelope?.findings) {
-      blockingFindings = envelope.findings.filter(
-        (finding) => finding.severity === "P0" || finding.severity === "P1",
+      recordReviewFindings(context.repoRoot, ledger.state.run.work, {
+        run: ledger.state.run.id,
+        step,
+        attempt,
+        findings: envelope.findings,
+        ts: now(),
+      });
+      // A fingerprint a human dismissed stays visible in the evidence but no
+      // longer blocks: settled verdicts do not reopen without a human.
+      const adjudicated = latestAdjudications(
+        readFindingsAccount(context.repoRoot, ledger.state.run.work),
       );
+      const suppressed = [];
+      blockingFindings = envelope.findings.filter((finding) => {
+        if (adjudicated.get(fingerprintFinding(finding))?.action === "dismiss") {
+          suppressed.push(fingerprintFinding(finding));
+          return false;
+        }
+        return finding.severity === "P0" || finding.severity === "P1";
+      });
       ledger.append({
         type: "EVIDENCE_RECORDED",
         actor: KERNEL,
         ts: now(),
         data: {
-          evidenceRef: outputPath,
+          evidenceRef: toRepoRef(context.repoRoot, outputPath),
           kind: "review",
           subject: tree.head,
           digest: sha256(canonicalJson(envelope)),
           status: blockingFindings.length > 0 ? "failed" : "passed",
           grade: "L2",
           findings: envelope.findings,
+          ...(suppressed.length > 0 ? { suppressedFingerprints: suppressed } : {}),
         },
       });
     }
@@ -531,8 +663,81 @@ function drive(context, startStep, { skipBoundaryOnce = false } = {}) {
     } else {
       outcome = "succeeded";
     }
-    step = settleOutcome(context, step, outcome, tree, exec);
+    const routed = settleOutcome(context, step, outcome, tree, exec);
+    // Finding triage gate (reviewTriage: required): blocking findings stop
+    // for a human verdict before any fixer runs. Findings are prescriptions,
+    // not facts — auto-routing them to a fixer burned four oscillation
+    // rounds in the deploy campaign before a human stopped the loop.
+    if (routed && outcome === "findings-blocking" && context.reviewTriage === "required") {
+      context.waitHuman(
+        `enter-${routed}`,
+        [
+          `review found ${blockingFindings.length} blocking finding(s); triage before ${routed} runs`,
+          ...blockingFindings
+            .slice(0, 5)
+            .map(
+              (finding) =>
+                `[${finding.severity} ${fingerprintFinding(finding)}] ${finding.summary.slice(0, 200)}`,
+            ),
+          `adjudicate fingerprints (findings adjudicate), then approve enter-${routed} or reject the run`,
+        ],
+        "finding-triage",
+      );
+      return;
+    }
+    step = routed;
+  }
+}
+
+// Supersede (iteration 08, C2): a new Run for the same Work makes any older
+// Run still waiting on a human moot — the human would be approving a
+// candidate nobody intends to merge. Real incident: two WAITING_HUMAN runs
+// sat in a pilot repo's inbox for a day after their successor had already
+// shipped. Only WAITING_HUMAN runs are touched; RUNNING ones are protected
+// by the active lock, terminal ones are already settled.
+function supersedeWaitingRuns(repoRoot, workId, newRunId, now) {
+  const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
+  const superseded = [];
+  const skipped = [];
+  if (!existsSync(runsDir)) {
+    return { superseded, skipped };
+  }
+  for (const entry of readdirSync(runsDir).sort()) {
+    if (entry === newRunId) {
+      continue;
+    }
+    const ledgerPath = join(runsDir, entry, "events.jsonl");
+    if (!existsSync(ledgerPath)) {
+      continue;
+    }
+    const ledger = EventLedger.open(ledgerPath);
+    const state = ledger.state;
+    if (ledger.corruption || !state.run || state.run.work !== workId) {
+      continue;
+    }
+    if (state.terminal || state.run.status !== "WAITING_HUMAN") {
+      continue;
+    }
+    try {
+      acquireLock(repoRoot, entry);
+    } catch {
+      skipped.push({ run: entry, reason: "locked by another process" });
+      continue;
+    }
+    try {
+      ledger.append({
+        type: "RUN_TERMINAL",
+        actor: KERNEL,
+        ts: now(),
+        data: { status: "SUPERSEDED", reason: `superseded by ${newRunId} (same work ${workId})` },
+      });
+      writeRunRecord({ repoRoot, ledger, ts: now() });
+      superseded.push(entry);
+    } finally {
+      releaseLock(repoRoot, entry);
+    }
   }
+  return { superseded, skipped };
 }
 
 function openLedgerFor(repoRoot, runId) {
@@ -568,6 +773,11 @@ export function startRun(options) {
   if (!workflowDigest) {
     throw new OrchestratorError("workflowDigest is required (pin what you run)");
   }
+  // Environment contract first: a missing or too-old binary fails the start
+  // with a readable cause instead of burning a run on an implicit PATH fact.
+  if (options.requires?.length) {
+    assertRequires(options.requires);
+  }
   const { ledger, ledgerPath } = openLedgerFor(repoRoot, runId);
   if (ledger.events.length > 0) {
     throw new OrchestratorError(`run ${runId} already has a ledger; use resumeRun`);
@@ -577,6 +787,10 @@ export function startRun(options) {
     const workspace = createWorkspace({ repoRoot, runId, base });
     const context = makeContext(options, ledger, workspace);
     const now = context.now;
+    const supersession =
+      options.supersede === "off"
+        ? { superseded: [], skipped: [] }
+        : supersedeWaitingRuns(repoRoot, workId, runId, now);
     ledger.append({
       type: "RUN_CREATED",
       actor: KERNEL,
@@ -591,6 +805,8 @@ export function startRun(options) {
         entry,
         planDigest: planDigest ?? "UNVERIFIED",
         intentDigest: intentDigest ?? "UNVERIFIED",
+        ...(supersession.superseded.length > 0 ? { supersedes: supersession.superseded } : {}),
+        ...(options.envelope ? { envelopeDigest: options.envelope.digest, envelopeSource: options.envelope.source } : {}),
       },
     });
     ledger.append({ type: "RUN_STARTED", actor: KERNEL, ts: now(), data: {} });
@@ -600,14 +816,22 @@ export function startRun(options) {
       ts: now(),
       data: {
         workspaceId: workspace.workspaceId,
-        repo: repoRoot,
+        repo: toRepoRef(repoRoot, repoRoot),
         branch: workspace.branch,
-        worktreePath: workspace.worktreePath,
+        worktreePath: toRepoRef(repoRoot, workspace.worktreePath),
         base: workspace.base,
       },
     });
     drive(context, entry);
-    return { runId, workId, ledgerPath, state: ledger.state, workspace };
+    return {
+      runId,
+      workId,
+      ledgerPath,
+      state: ledger.state,
+      workspace,
+      superseded: supersession.superseded,
+      supersedeSkipped: supersession.skipped,
+    };
   });
 }
 
@@ -626,6 +850,9 @@ export function resumeRun(options) {
   if (!repoRoot || !runId) {
     throw new OrchestratorError("repoRoot and runId are required");
   }
+  if (options.requires?.length) {
+    assertRequires(options.requires);
+  }
   const { ledger, ledgerPath } = openLedgerFor(repoRoot, runId);
   const state = ledger.state;
   if (!state.run) {
@@ -647,15 +874,16 @@ export function resumeRun(options) {
   if (!bound) {
     throw new OrchestratorError(`run ${runId} has no bound workspace; cannot resume`);
   }
-  if (!existsSync(bound.worktreePath)) {
+  const worktreePath = resolveRepoRef(repoRoot, bound.worktreePath);
+  if (!existsSync(worktreePath)) {
     throw new OrchestratorError(
-      `worktree missing: ${bound.worktreePath}; recovery requires a human decision`,
+      "worktree missing; recovery requires a human decision",
     );
   }
   const workspace = {
     workspaceId: runId,
     repoRoot,
-    worktreePath: bound.worktreePath,
+    worktreePath,
     branch: bound.branch,
     base: bound.base,
   };
@@ -727,12 +955,12 @@ export function resumeRun(options) {
         ]);
         return { runId, ledgerPath, state: ledger.state, resumed: true, reason: null };
       }
-      startStep = settleOutcome(context, step, "failed", tree, {
-        command: "(interrupted)",
-        exitCode: null,
-        stdout: "",
-        stderr: "process lost before completion",
-      });
+      // An interrupted attempt says nothing about the candidate, so the step
+      // itself reruns (the lost attempt still counts against its budget)
+      // instead of settling as a step failure — routing a crash through the
+      // failure edge dispatched a fixer with no verifier evidence (real
+      // incident: deploy-18's verify worker was killed by a host timeout).
+      startStep = step;
     } else if (tree.dirty) {
       context.waitHuman("resume-run", [
         "worktree is dirty at resume with no step in flight; human triage required",

package/src/v2/runtime/overview.js

@@ -0,0 +1,264 @@
+// Work-level overview (iteration 08, C5): "where is this thing, and who
+// moves next" — the question the owner opened three sessions with
+// ("X 上线了吗 / 离上线还差多远 / 从每个系统说待办") and that inbox,
+// which only knows about runs waiting on a human, cannot answer.
+//
+// Everything here is derived: work directories and decision ledgers in the
+// Git plane, run ledgers in the runtime plane (run-records fill in for runs
+// whose runtime was wiped), and git ancestry for "merged". Nothing is
+// written.
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { EventLedger } from "../storage/event-ledger.js";
+import { latestAdjudications, readFindingsAccount } from "./findings.js";
+import { nextReply } from "./notify.js";
+
+function sha256File(path) {
+  return `sha256:${createHash("sha256").update(readFileSync(path, "utf8"), "utf8").digest("hex")}`;
+}
+
+function readJsonl(path) {
+  if (!existsSync(path)) {
+    return [];
+  }
+  return readFileSync(path, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function artifactStatus(workDir, decisions, artifact) {
+  const path = join(workDir, `${artifact}.md`);
+  if (!existsSync(path)) {
+    return { exists: false, accepted: false, stale: false };
+  }
+  const digest = sha256File(path);
+  const accepts = decisions.filter((row) => row.transition === `accept-${artifact}` && row.decision === "approved");
+  const latest = accepts[accepts.length - 1];
+  if (!latest) {
+    return { exists: true, accepted: false, stale: false };
+  }
+  const stale = latest.subject?.digest !== digest;
+  return { exists: true, accepted: !stale, stale, by: latest.by, at: latest.ts };
+}
+
+function isAncestor(repoRoot, sha, ref) {
+  try {
+    execFileSync("git", ["-C", repoRoot, "merge-base", "--is-ancestor", sha, ref], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function headRef(repoRoot) {
+  try {
+    return execFileSync("git", ["-C", repoRoot, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "HEAD";
+  }
+}
+
+// Runs for a work: runtime ledgers first, run-records for the rest.
+function runsFor(repoRoot, workId) {
+  const runs = new Map();
+  const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
+  if (existsSync(runsDir)) {
+    for (const entry of readdirSync(runsDir)) {
+      const path = join(runsDir, entry, "events.jsonl");
+      if (!existsSync(path)) {
+        continue;
+      }
+      const ledger = EventLedger.open(path);
+      const state = ledger.state;
+      if (!state.run || state.run.work !== workId) {
+        continue;
+      }
+      runs.set(state.run.id, {
+        id: state.run.id,
+        status: state.run.status,
+        terminal: state.terminal,
+        pendingHuman: state.pendingHuman,
+        candidate: state.workspaces[state.run.id]?.candidate ?? null,
+        createdAt: ledger.events[0]?.ts ?? null,
+        lastAt: ledger.events[ledger.events.length - 1]?.ts ?? null,
+        state,
+        source: "runtime",
+      });
+    }
+  }
+  const recordsDir = join(repoRoot, "delivery", "work", workId, "runs");
+  if (existsSync(recordsDir)) {
+    for (const entry of readdirSync(recordsDir)) {
+      if (runs.has(entry)) {
+        continue;
+      }
+      const path = join(recordsDir, entry, "run-record.json");
+      if (!existsSync(path)) {
+        continue;
+      }
+      try {
+        const record = JSON.parse(readFileSync(path, "utf8"));
+        runs.set(entry, {
+          id: entry,
+          status: record.terminal?.status ?? "UNKNOWN",
+          terminal: record.terminal ?? null,
+          pendingHuman: null,
+          candidate: record.workspaces?.[entry]?.candidate ?? null,
+          createdAt: record.startedAt ?? null,
+          lastAt: record.finishedAt ?? null,
+          state: null,
+          source: "run-record",
+        });
+      } catch {
+        // an unreadable record is reported as absent, not guessed
+      }
+    }
+  }
+  return [...runs.values()].sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+}
+
+export function computeOverview(repoRoot, { work = null, repoLabel = "." } = {}) {
+  const workRoot = join(repoRoot, "delivery", "work");
+  const rows = [];
+  if (!existsSync(workRoot)) {
+    return rows;
+  }
+  const mainRef = headRef(repoRoot);
+  for (const workId of readdirSync(workRoot).sort()) {
+    if (work && workId !== work) {
+      continue;
+    }
+    const workDir = join(workRoot, workId);
+    if (!existsSync(join(workDir, "intent.md")) && !existsSync(join(workDir, "plan.md")) && !existsSync(join(workDir, "decisions.jsonl")) && !existsSync(join(workDir, "runs"))) {
+      continue;
+    }
+    const decisions = readJsonl(join(workDir, "decisions.jsonl"));
+    const intent = artifactStatus(workDir, decisions, "intent");
+    const plan = artifactStatus(workDir, decisions, "plan");
+    const envFacts = existsSync(join(workDir, "env-facts.md"));
+    const findingRows = readFindingsAccount(repoRoot, workId);
+    const adjudicated = latestAdjudications(findingRows);
+    const openFindings = findingRows.filter(
+      (row) => row.kind === "finding" && (row.severity === "P0" || row.severity === "P1") && !adjudicated.has(row.fingerprint),
+    ).length;
+    const runs = runsFor(repoRoot, workId);
+    const live = runs.filter((run) => run.status !== "SUPERSEDED");
+    const latest = live[live.length - 1] ?? null;
+    let merged = false;
+    if (latest?.candidate) {
+      merged = isAncestor(repoRoot, latest.candidate, mainRef);
+    }
+
+    let stage;
+    let next;
+    if (!intent.exists) {
+      stage = "NO_INTENT";
+      next = `write delivery/work/${workId}/intent.md (what and why), then plan.md`;
+    } else if (!latest) {
+      if (!plan.exists) {
+        stage = intent.accepted ? "INTENT_ACCEPTED" : "INTENT_DRAFT";
+        next = intent.accepted
+          ? `write delivery/work/${workId}/plan.md, then accept it`
+          : `buildbeat-v2 accept --repo ${repoLabel} --work ${workId} --artifact intent --by <you>`;
+      } else if (!plan.accepted) {
+        stage = plan.stale ? "PLAN_STALE" : "PLAN_DRAFT";
+        next = `buildbeat-v2 accept --repo ${repoLabel} --work ${workId} --artifact plan --by <you>${plan.stale ? "   # plan changed since acceptance" : ""}`;
+      } else {
+        stage = "READY_TO_RUN";
+        const configs = readdirSync(workDir).filter((name) => /^run-config.*\.ya?ml$/.test(name));
+        next =
+          configs.length > 0
+            ? `buildbeat-v2 start --config delivery/work/${workId}/${configs[0]} --attempt new`
+            : `no run-config in delivery/work/${workId}: write one, or record the work as closed in decisions.jsonl if it was doc-only`;
+      }
+    } else if (latest.status === "RUNNING") {
+      stage = "RUNNING";
+      next = `buildbeat-v2 status --repo ${repoLabel} --run ${latest.id}`;
+    } else if (latest.status === "WAITING_HUMAN") {
+      stage = latest.pendingHuman?.kind === "final-decision" ? "MERGE_DECISION" : "WAITING_HUMAN";
+      const replies = latest.state ? nextReply({ repoLabel, state: latest.state }) : [];
+      next = replies[0] ?? `buildbeat-v2 inbox --repo ${repoLabel}`;
+    } else if (latest.status === "SUCCEEDED") {
+      if (merged) {
+        stage = "MERGED";
+        next = `release/deploy stays a human action; then buildbeat-v2 gc --repo ${repoLabel}`;
+      } else {
+        stage = "MERGE_READY";
+        next = latest.candidate
+          ? `merge ${latest.candidate.slice(0, 7)} (run/${latest.id}) into ${mainRef} — manual, then push`
+          : "run succeeded without a candidate; nothing to merge";
+      }
+    } else {
+      stage = `STOPPED_${latest.status}`;
+      next = plan.accepted
+        ? `decide: retry (buildbeat-v2 start ... --attempt new) or close the work`
+        : `plan not accepted (${plan.exists ? "draft" : "missing"}); fix that before another run`;
+    }
+    rows.push({
+      work: workId,
+      stage,
+      intent,
+      plan,
+      envFacts,
+      openFindings,
+      runs: runs.length,
+      latest: latest
+        ? { id: latest.id, status: latest.status, candidate: latest.candidate, at: latest.lastAt, source: latest.source, terminalReason: latest.terminal?.reason ?? null, waiting: latest.pendingHuman?.transition ?? null }
+        : null,
+      merged,
+      next,
+    });
+  }
+  return rows;
+}
+
+function mark(status) {
+  if (!status.exists) {
+    return "–";
+  }
+  if (status.stale) {
+    return "stale";
+  }
+  return status.accepted ? "✓" : "draft";
+}
+
+export function renderOverview(rows) {
+  if (rows.length === 0) {
+    return "overview: no work items under delivery/work";
+  }
+  const lines = [];
+  for (const row of rows) {
+    lines.push(`${row.work}  ${row.stage}`);
+    const parts = [`intent ${mark(row.intent)}`, `plan ${mark(row.plan)}`, `runs ${row.runs}`];
+    if (row.openFindings > 0) {
+      // Unadjudicated, not necessarily unresolved: a fixer may have closed
+      // them without anyone recording a verdict. The number says "nobody
+      // ruled on these", which is exactly what a human should know.
+      parts.push(`unadjudicated P0/P1 findings ${row.openFindings}`);
+    }
+    if (row.envFacts) {
+      parts.push("env-facts ✓");
+    }
+    lines.push(`  ${parts.join(" · ")}`);
+    if (row.latest) {
+      const cand = row.latest.candidate ? ` candidate ${row.latest.candidate.slice(0, 7)}${row.merged ? " (merged)" : ""}` : "";
+      const wait = row.latest.waiting ? ` waiting ${row.latest.waiting}` : "";
+      const why = row.latest.terminalReason ? ` — ${row.latest.terminalReason.slice(0, 100)}` : "";
+      lines.push(`  latest ${row.latest.id} ${row.latest.status}${cand}${wait} @ ${row.latest.at ?? "?"}${why}`);
+    }
+    lines.push(`  next: ${row.next}`);
+  }
+  return lines.join("\n");
+}