@staix/agent-hub 0.12.35 → 0.12.36

package/src/cli/main.ts

@@ -40,7 +40,7 @@ import { OmniRoute } from "../omniroute/client.ts";
 import { MemoryClient } from "../memory/client.ts";
 import { init, planInit } from "./init.ts";
 import { launcherPreview } from "./preview.ts";
-import { instanceLaunchArguments, requirePeerInstances, cleanupStaleClaudeSettings, cleanupClaudeSettings, buildLaunch, buildKimiTuiLaunch, claudeObservationHooks, nativeLaunchEnv, recordClaudeLaunch, runClaudeLaunch, type ClaudeLaunchRecord, UNATTENDED_WARNING } from "./launch.ts";
+import { instanceLaunchArguments, requirePeerInstances, requireActiveInstance, cleanupStaleClaudeSettings, cleanupClaudeSettings, buildLaunch, buildKimiTuiLaunch, claudeObservationHooks, nativeLaunchEnv, recordClaudeLaunch, runClaudeLaunch, type ClaudeLaunchRecord, UNATTENDED_WARNING } from "./launch.ts";
 import { configureKimiMcp } from "./kimi-mcp.ts";
 import { nextStep, parseList, pluginState, type InstalledPlugin, type Marketplace } from "./setup.ts";
 import { CLASSES } from "../hub/board.ts";
@@ -848,14 +848,14 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (entry.lifecycleAdmission && !args.includes("--print-command") && !args.includes("--dry-run")) assertLifecycleAvailable();
     const nativeConnect = async () => {
       const hub = await connect();
-      try { if (selectedInstance) requirePeerInstances(hub.features); return hub; }
+      try { if (selectedInstance) { requirePeerInstances(hub.features); requireActiveInstance((await hub.request({ t: "status" })).status, selectedInstance); } return hub; }
       catch (error) { hub.close(); throw error; }
     };
     if (selectedInstance && !args.includes("--print-command") && !args.includes("--dry-run")) {
       const hub = await nativeConnect(); hub.close();
     }
     const context: NativeCliEntryContext = { args, cwd, stateDir, cliDir: import.meta.dir, unattendedEnv, definition: entry.definition,
-      ...(selectedInstance ? { instance: selectedInstance } : {}),
+      ...(selectedInstance ? { instance: selectedInstance } : {}), ...(nativeSelection.hubStarted ? { hubStarted: true as const } : {}),
       projectConfig, connect: nativeConnect, fail,
       exec: (bin, argv, tool) => exec(bin, argv, tool, context.executionCwd),
       execWithEnv: (bin, argv, env) => execWithEnv(bin, argv, env, context.executionCwd), takeFlags,
@@ -1032,6 +1032,10 @@ const commands: Record<string, () => Promise<void> | void> = {
   backlog: async () => {
     const [sub, id, revision, value, ...reason] = args;
     if (sub === "list" && args.length === 1) return console.log(await taskOp("hub_backlog_list", {}));
+    if (sub === "groom" && args.length === 1) return console.log(await taskOp("hub_planner_groom", {}));
+    if (["return", "return-untouched"].includes(sub ?? "") && /^[1-9]\d*$/.test(id ?? "") && /^\d+$/.test(revision ?? "") && args.length >= 4) {
+      return console.log(await taskOp("hub_backlog_return_untouched", { id: Number(id), revision: Number(revision), reason: args.slice(3).join(" ") }));
+    }
     if (sub === "add" && args.length >= 3) return console.log(await taskOp("hub_task_propose", { class: id, title: args.slice(2).join(" "), backlog: true }));
     if (!/^[1-9]\d*$/.test(id ?? "")) fail("usage: ahub backlog list|add <class> <title...>|pull|return <id>|plan|pin <id> <revision> <value> <reason...>|undo <id> <revision>");
     if (["pull", "return"].includes(sub ?? "") && args.length === 2) return console.log(await taskOp(sub === "pull" ? "backlog_pull" : "backlog_return", { id }));
@@ -1114,6 +1118,31 @@ const commands: Record<string, () => Promise<void> | void> = {
       finally { hub.close(); }
       return;
     }
+    if (sub === "costs") {
+      if (args.length > 2) fail("usage: ahub sdlc costs [owner/repository]");
+      return console.log(await taskOp("hub_sdlc_costs", { ...(args[1] ? { repo: args[1] } : {}) }));
+    }
+    if (sub === "plan-review") {
+      const revision = Number(args[2]);
+      if (!Number.isSafeInteger(id) || id! <= 0 || !Number.isSafeInteger(revision) || revision < 0 || args.length < 4) fail("usage: ahub sdlc plan-review <task> <revision> <reason...>");
+      const flags = takeFlags(args.slice(3), ["--review", "--reviewers", "--ci"], []);
+      const scope = flags.one["--review"], reviewers = flags.one["--reviewers"];
+      if (!flags.rest.length || (scope === undefined) !== (reviewers === undefined)) fail("plan-review needs a reason and both --review and --reviewers when supplying review scope");
+      return console.log(await taskOp("hub_plan_review", { id, revision, reason: flags.rest.join(" "), ...(scope !== undefined ? { review: { scope, reviewers: Number(reviewers) } } : {}), ...(flags.one["--ci"] !== undefined ? { ci: flags.one["--ci"] } : {}) }));
+    }
+    if (sub === "accept") {
+      // #481 S1: the person accepts the task's spec issue at its current body; agent shells are refused before this runs.
+      const flags = takeFlags(args.slice(2), ["--issue", "--repo"], []);
+      const issue = Number(flags.one["--issue"]), repo = flags.one["--repo"];
+      if (flags.rest.length || !Number.isSafeInteger(id) || id! <= 0 || !Number.isSafeInteger(issue) || issue <= 0) fail("usage: ahub sdlc accept <task> --issue <n> [--repo owner/repository]");
+      const hub = await connect();
+      try {
+        const reply = await hub.request({ t: "sdlc", op: "accept", id, issue, ...(repo ? { repo } : {}) }, 30_000);
+        if (!reply.ok) fail(reply.error);
+        console.log(`task #${id}: spec issue #${issue} accepted at body edit ${reply.acceptance?.lastEditedAt ?? "never"}`);
+      } finally { hub.close(); }
+      return;
+    }
     if (sub === "record") {
       if (args.length !== 3 || !Number.isSafeInteger(id) || id! <= 0 || Buffer.byteLength(args[2]!) > 32768) fail("usage: ahub sdlc record <task> '<receipt JSON>'");
       let receipt: unknown; try { receipt = JSON.parse(args[2]!); } catch { fail("receipt must be valid JSON"); }
@@ -1181,9 +1210,14 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   review: async () => {
+    // #520: the review brief a reviewer gets, for a person or an outside tool.
+    if (args[0] === "brief") {
+      if (args.length !== 2 || !/^\d+$/.test(args[1]!)) fail("usage: ahub review brief <task id>");
+      return console.log(await taskOp("review_brief", { id: Number(args[1]) }));
+    }
     const { one, many, rest } = takeFlags(args, ["--head"], ["--unmet"]);
     const [id, verdict, ...note] = rest;
-    if (!id || !verdict) fail("usage: ahub review <id> approved|changes_requested [note...] [--unmet <item>]...");
+    if (!id || !verdict) fail("usage: ahub review <id> approved|changes_requested [note...] [--unmet <item>]... | ahub review brief <id>");
     console.log(await taskOp("hub_review", { id: Number(id), verdict, ...(one["--head"] ? { head: one["--head"] } : {}), note: note.join(" "), ...(many["--unmet"]?.length ? { unmet: many["--unmet"] } : {}) }));
   },
 

package/src/cli/reset.ts

@@ -10,6 +10,8 @@ import { HUB_DB_BUSY_TIMEOUT_MS } from "../hub/db-timeout.ts";
 
 /** Agent session resume pointers. `pi-sessions/` holds Pi transcripts, history rather than pointers, and stays. */
 export const SESSION_POINTERS = ["sessions.json", "claude-session.json", "claude-context.json"];
+/** The fixed pointers plus each Claude instance's own session and context files (#450 I3). */
+const sessionPointers = (stateDir: string): string[] => [...SESSION_POINTERS, ...(existsSync(stateDir) ? readdirSync(stateDir).filter(name => /^claude-(session|context)\.[a-z][a-z0-9-]{0,31}\.json$/.test(name)) : [])];
 /** What a running daemon publishes; a daemon that did not stop cleanly (crash, SIGKILL, forced exit) leaves it. */
 export const MANIFEST = ["status.json", "control-token", "hub.pid"];
 
@@ -51,7 +53,7 @@ const shaped = (ok: boolean, what: string) => { if (!ok) throw new Error(`invali
 /** What a reset would act on, read from the state directory without changing it (hub.db opened read-only). */
 export function planReset(stateDir: string, projectId: string): ResetPlan {
   const plan: ResetPlan = { queued: [], needsReview: [], inFlight: [], manualHolds: [], budgetPauses: [], conductorHolds: [],
-    sessionPointers: SESSION_POINTERS.filter((name) => existsSync(join(stateDir, name))), entries: existsSync(stateDir) ? readdirSync(stateDir).length : 0 };
+    sessionPointers: sessionPointers(stateDir).filter((name) => existsSync(join(stateDir, name))), entries: existsSync(stateDir) ? readdirSync(stateDir).length : 0 };
   const file = join(stateDir, "hub.db");
   if (!existsSync(file)) return plan;
   // A read-only open of a WAL database creates hub.db-wal and -shm when the last writer's close removed them (Linux),
@@ -143,7 +145,7 @@ export function resetRuntime(stateDir: string, project: Project): { settled: str
       })();
     } finally { db.close(); }
   }
-  for (const name of SESSION_POINTERS) rmSync(join(stateDir, name), { force: true });
+  for (const name of sessionPointers(stateDir)) rmSync(join(stateDir, name), { force: true });
   // The caller has checked that no daemon behind these is alive or uncertain: they are a crashed run's leftovers.
   const stale = MANIFEST.filter((name) => existsSync(join(stateDir, name)));
   for (const name of stale) rmSync(join(stateDir, name), { force: true });

package/src/cli/statusline-tee.ts

@@ -6,6 +6,7 @@
 import { spawnSync } from "node:child_process";
 import { chmodSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { claudePeer, claudeStateFile } from "../hub/claude-state.ts";
 
 const input = await Bun.stdin.text();
 let own = "";
@@ -15,6 +16,8 @@ try {
   const pct = (w: any) => (typeof w?.used_percentage === "number" ? `${Math.round(w.used_percentage)}%` : "-");
   if (limits) own = `agent-hub  5h ${pct(limits.five_hour)}  wk ${pct(limits.seven_day)}`;
   const dir = process.env.AGENTHUB_STATE_DIR;
+  // Usage is per account and shared; context and session belong to this peer (#450 I3: a claude-<name> instance).
+  const peer = claudePeer(process.env.AGENTHUB_PEER_ID);
   if (limits && dir) {
     mkdirSync(dir, { recursive: true });
     const file = join(dir, "claude-usage.json");
@@ -25,7 +28,7 @@ try {
   if (sessionId && dir) {
     // Bind context to the launcher, daemon and native session. Persist no prompts or transcript text.
     mkdirSync(dir, { recursive: true });
-    const file = join(dir, "claude-context.json");
+    const file = join(dir, claudeStateFile("claude-context", peer));
     const c = parsed.context_window;
     const current = c?.current_usage;
     const numeric = (v: unknown) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null;
@@ -38,7 +41,7 @@ try {
   }
   if (sessionId && dir) {
     mkdirSync(dir, { recursive: true });
-    const file = join(dir, "claude-session.json");
+    const file = join(dir, claudeStateFile("claude-session", peer));
     // The transcript path lets the hub tell a zero-turn session (file not yet created, so
     // `claude --resume` can never work) from one whose conversation must be preserved (#64).
     const transcriptPath = typeof parsed.transcript_path === "string" && parsed.transcript_path ? parsed.transcript_path : undefined;

package/src/cli/terminal-recovery.ts

@@ -331,7 +331,12 @@ function executionRoot(peer: string, projectRoot: string, captured?: string): st
   const { instances: declarations, roles } = readInstanceRoleConfig(projectRoot);
   const definition = definitionOf(peer, declarations);
   if (!definition?.session.launchRecord) throw new Error(`${peer}: no managed terminal recovery adapter`);
-  if (definition.transport !== "codex-appserver" || !declarations?.[peer]) throw new Error(`${peer}: I2 extra instance has no managed terminal support`);
+  if (!declarations?.[peer] || definition.transport !== "codex-appserver" && definition.transport !== "claude-channel") throw new Error(`${peer}: extra instance has no managed terminal support`);
+  // #450 I3: a Claude instance reviews or plans in the canonical checkout; it never owns an execution worktree.
+  if (definition.transport === "claude-channel") {
+    if (captured !== undefined && captured !== projectRoot) throw new Error(`${peer}: recorded execution root changed; manual recovery required`);
+    return projectRoot;
+  }
   const expected = resolveInstanceExecutionCwd(projectRoot, peer, declarations, effectiveInstanceRoles(peer, declarations, roles));
   if (captured !== undefined && captured !== expected) throw new Error(`${peer}: declared execution worktree changed; manual recovery required`);
   return expected;
@@ -662,7 +667,7 @@ export async function inspectTerminals(projectRoot: string, sessions: Partial<Re
   for (const [peer, ref] of requested) {
     const sessionId = ref.sessionId;
     const adapter = definitionOf(peer, instances), extra = definitionOf(peer) === undefined;
-    if (!adapter?.session.launchRecord || extra && adapter.transport !== "codex-appserver") { blockers.push(blocker("ownership-unknown", `${peer}: no declared managed-terminal recovery adapter`, peer)); continue; }
+    if (!adapter?.session.launchRecord || extra && adapter.transport !== "codex-appserver" && adapter.transport !== "claude-channel") { blockers.push(blocker("ownership-unknown", `${peer}: no declared managed-terminal recovery adapter`, peer)); continue; }
     const ownRecord = records.find(item => item.peer === peer);
     let expectedRoot: string, expectedTerminalRoot: string;
     try {

package/src/cli/upgrade-runtime.ts

@@ -1,4 +1,5 @@
 import { resolveAcceptedBinding } from "./recovery-guidance.ts";
+import { claudeStateFile } from "../hub/claude-state.ts";
 import { ADAPTERS, definitionOf } from "../adapters/registry.ts";
 import { readInstanceConfig } from "../hub/instance-config.ts";
 import { isDatabaseBusy, isDatabaseBusyReply, RecoveryDatabaseBusy } from "../hub/recovery-error.ts";
@@ -265,21 +266,21 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
         if (recorded?.state === "unknown") {
           // An unreadable launcher is never gone (#215): whether the session is managed cannot be told.
           delete peer.sessionId;
-          blockers.push(`claude: ${recorded.record ? `the launcher recorded in terminal ${recorded.record.handle}` : recorded.invalidRow ? "a launch record in terminal-recovery.json that may be its launcher's" : "the launcher record (terminal-recovery.json)"} cannot be read, so whether the attached session is managed is unknown; manual-required; next action: make it readable (or end that session and close its terminal), then make a new plan`);
+          blockers.push(`${peer.id}: ${recorded.record ? `the launcher recorded in terminal ${recorded.record.handle}` : recorded.invalidRow ? "a launch record in terminal-recovery.json that may be its launcher's" : "the launcher record (terminal-recovery.json)"} cannot be read, so whether the attached session is managed is unknown; manual-required; next action: make it readable (or end that session and close its terminal), then make a new plan`);
           continue;
         }
         const launcher = recorded?.state === "live" ? recorded.record! : undefined;
         if (!launcher) {
           delete peer.sessionId;
           if (source.protocol === PROTOCOL) reconnectOnly.push(peer.id);
-          else blockers.push(`claude: unmanaged session (no live ahub claude launcher recorded) runs a protocol-${source.protocol} plugin and cannot reconnect to a protocol-${PROTOCOL} hub; next action: end that Claude session, or relaunch it with ahub claude in an Orca terminal, then make a new plan`);
+          else blockers.push(`${peer.id}: unmanaged session (no live ahub claude launcher recorded) runs a protocol-${source.protocol} plugin and cannot reconnect to a protocol-${PROTOCOL} hub; next action: end that Claude session, or relaunch it with ahub claude in an Orca terminal, then make a new plan`);
           continue;
         }
         let record: { instanceId?: unknown; launchId?: unknown; sessionId?: unknown } | undefined;
-        try { record = JSON.parse(readFileSync(join(project.stateDir, "claude-session.json"), "utf8")); } catch { /* no record: the id check below reports it */ }
+        try { record = JSON.parse(readFileSync(join(project.stateDir, claudeStateFile("claude-session", peer.id)), "utf8")); } catch { /* no record: the id check below reports it */ }
         if (peer.sessionId && (record?.instanceId !== source.instanceId || record?.launchId !== launcher.launchId || record?.sessionId !== peer.sessionId)) {
           delete peer.sessionId;
-          blockers.push(`claude: the recorded session was not written by the live launcher in terminal ${launcher.handle}; manual-required; next action: close any other Claude session in this project, send one message in that terminal, then make a new plan`);
+          blockers.push(`${peer.id}: the recorded session was not written by the live launcher in terminal ${launcher.handle}; manual-required; next action: close any other Claude session in this project, send one message in that terminal, then make a new plan`);
           continue;
         }
       }
@@ -340,7 +341,8 @@ export function preserveSource(plan: UpgradePlan, home = hubHome()): string {
 export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?: string, clock?: Pick<RecoveryDriver, "now" | "sleep">): RecoveryDriver {
   const now = clock?.now ?? (() => Date.now());
   const sleep = clock?.sleep ?? ((ms: number) => Bun.sleep(ms));
-  const env = (op: RecoveryOperation, project?: Project): NodeJS.ProcessEnv => {
+  /** `only`: one binding's native profile, for a command run once per profile (#450 I3: Claude instances may differ). */
+  const env = (op: RecoveryOperation, project?: Project, only?: TerminalBinding): NodeJS.ProcessEnv => {
     const value = { ...process.env };
     // Do not carry one project's gateway, auth overrides or unattended mode into another.
     for (const key of Object.keys(value)) if (key.startsWith("AGENTHUB_") || key.startsWith("OMNIROUTE_") || key.startsWith("CF_ACCESS_") ||
@@ -352,7 +354,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       value.AGENTHUB_PROJECT_DIR = project.root; value.AGENTHUB_STATE_DIR = project.stateDir;
       delete value.CODEX_HOME; delete value.CLAUDE_CONFIG_DIR;
       const bindings = op.plan.projects.find((p) => p.project.id === project.id)?.terminals as TerminalBinding[] | undefined;
-      for (const binding of bindings ?? []) {
+      for (const binding of only ? [only] : bindings ?? []) {
         // Preserve the captured legacy profile for terminal bindings without a dedicated native config variable.
         const key = projectDefinition(binding.peer, binding.projectRoot)?.session.configDirEnv ?? "CLAUDE_CONFIG_DIR";
         if (binding.launch.env[key]) value[key] = binding.launch.env[key];
@@ -360,9 +362,9 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
     }
     return value;
   };
-  const command = async (op: RecoveryOperation, args: string[], project?: Project) => {
+  const command = async (op: RecoveryOperation, args: string[], project?: Project, only?: TerminalBinding) => {
     const result = await run([process.execPath, join(op.targetRoot!, "src/cli/main.js"), ...(project ? ["--project", project.root] : []), ...(liveTestPeer ? ["--live-test"] : []), ...args],
-      { env: env(op, project), cwd: project?.root ?? op.plan.projects[0]!.project.root, timeoutMs: 180_000 });
+      { env: env(op, project, only), cwd: project?.root ?? op.plan.projects[0]!.project.root, timeoutMs: 180_000 });
     if (result.code !== 0) throw new Error(`target command ${args[0]} failed; inspect recovery state before retrying`);
     return result;
   };
@@ -927,12 +929,13 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
     installPlugin: async (op) => {
       const configured = new Set<string>();
       for (const planned of op.plan.projects) {
-        const binding = (planned.terminals as TerminalBinding[]).find((t) => projectDefinition(t.peer, t.projectRoot)?.transport === "claude-channel");
-        if (!binding) continue;
-        const profile = binding.launch.env.CLAUDE_CONFIG_DIR ?? "default";
-        if (configured.has(profile)) continue;
-        await command(op, ["setup", "--yes"], planned.project);
-        configured.add(profile);
+        // Every Claude binding (the builtin and each instance), once per distinct profile, each under its own profile.
+        for (const binding of (planned.terminals as TerminalBinding[]).filter((t) => projectDefinition(t.peer, t.projectRoot)?.transport === "claude-channel")) {
+          const profile = binding.launch.env.CLAUDE_CONFIG_DIR ?? "default";
+          if (configured.has(profile)) continue;
+          await command(op, ["setup", "--yes"], planned.project, binding);
+          configured.add(profile);
+        }
       }
       if (!configured.size) await command(op, ["setup", "--yes"]);
     },
@@ -1002,7 +1005,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
           // #64: the restore gate already accepted a fresh session when the original never
           // persisted a transcript. Re-derive persistence from the binding exactly like that
           // gate did, so a first turn landing after the plan was made keeps the check strict.
-          const binding = (planned.terminals as TerminalBinding[]).find((t) => projectDefinition(t.peer, t.projectRoot)?.transport === "claude-channel");
+          const binding = (planned.terminals as TerminalBinding[]).find((t) => t.peer === old.id && projectDefinition(t.peer, t.projectRoot)?.transport === "claude-channel");
           if (recordedOnly || !binding || binding.sessionId !== old.sessionId || !nativeZeroTurn(planned.project.stateDir, binding, "verify")) throw nativeFailure(planned, old.id, "session_changed", "Claude resumed a different conversation", { ...(old.sessionId ? { expectedSession: old.sessionId } : {}), ...(peer.sessionId ? { observedSession: peer.sessionId } : {}) });
         }
         if (projectDefinition(old.id, planned.project.root)?.session.launchRecord && projectDefinition(old.id, planned.project.root)?.session.crashIdentity && (peer.sessionId !== old.sessionId || (old.sessionFile && peer.sessionFile !== old.sessionFile))) throw nativeFailure(planned, old.id, "session_changed", "Pi resumed a different conversation", { ...(old.sessionId ? { expectedSession: old.sessionId } : {}), ...(peer.sessionId ? { observedSession: peer.sessionId } : {}) });

package/src/hub/board.ts

@@ -5,6 +5,7 @@ import { HUB, type PeerId } from "./envelope.ts";
 import type { SweepRecord } from "./task-sweep.ts";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 import type { SdlcReceipt } from "./sdlc.ts";
+import type { CostPlan, ReviewCost } from "./cost-governance.ts";
 
 export const CLASSES = ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] as const;
 export type TaskClass = (typeof CLASSES)[number];
@@ -27,7 +28,7 @@ export interface TaskRefs {
 export const PLAN_KEYS = ["paths", "symbols", "signatures", "insertion_points"] as const;
 export const DOCUMENT_PLAN_KEYS = ["paths", "sections", "sources", "claims"] as const;
 export const ALL_PLAN_KEYS = [...PLAN_KEYS, "sections", "sources", "claims"] as const;
-export type TaskPlan = Partial<Record<(typeof ALL_PLAN_KEYS)[number], string[]>>;
+export type TaskPlan = Partial<Record<(typeof ALL_PLAN_KEYS)[number], string[]>> & CostPlan;
 /** Task outcomes older than this are pruned: demotion (issue #36) reads one week, seven half-lives. */
 export const OUTCOMES_KEPT_MS = 7 * 24 * 3_600_000;
 
@@ -51,6 +52,10 @@ export interface HistoryEntry {
   sweep?: SweepRecord;
   /** The PII screen did not clear this entry's note (#198): only the console reads it. */
   withheld?: true;
+  /** Host-recorded expected cost and exact review head, never narrative. */
+  reviewCost?: ReviewCost;
+  /** #223 R4: on a verdict, whether the reviewer's context was new for it; set by the hub, never by the reviewer. */
+  reviewContext?: "fresh" | "continuing";
   planning?: { revision: number; fields: (keyof PlanningFields)[]; previous: PlanningFields; pull?: true; split?: { children: { id: number; revision: number; history: number }[] } };
 }
 export interface Task extends PlanningFields {
@@ -90,6 +95,19 @@ export interface Task extends PlanningFields {
 export function taskHasStarted(task: Pick<Task, "history">): boolean {
   return task.history.some(entry => ["accepted", "done", "done (checking)", "check passed", "check failed", "changes_requested", "approved", "reopened", "integration requested", "integrated"].includes(entry.event));
 }
+/** S9 return eligibility never erases the historical acceptance used by cancellation and undo. */
+export function taskHasWorkEvidence(task: Pick<Task, "history" | "refs" | "sdlc">): boolean {
+  return !!(task.refs.branch || task.refs.commit || task.sdlc?.localHead || task.sdlc?.localResult || task.sdlc?.reviewedHead || task.sdlc?.pr)
+    || task.history.some(entry => entry.event === "done" || entry.event.startsWith("done (") || entry.event.startsWith("check ")
+      || ["changes_requested", "approved", "reopened", "integration requested", "integration unresolved", "integrated"].includes(entry.event));
+}
+/** A successful untouched return permits replanning, without changing historical start evidence. */
+export function taskCanPlan(task: Pick<Task, "history" | "refs" | "sdlc">): boolean {
+  if (!taskHasStarted(task)) return true;
+  const returned = task.history.findLastIndex(entry => entry.event === "backlog returned untouched");
+  const accepted = task.history.findLastIndex(entry => entry.event === "accepted");
+  return returned > accepted && !taskHasWorkEvidence(task);
+}
 /** First offer boundary; staged work has none until it is pulled. */
 export function taskProposalAt(task: Pick<Task, "history">): number | undefined {
   return task.history.find(entry => entry.event === "proposed" || entry.event === "backlog pulled")?.at;
@@ -270,18 +288,22 @@ export class Board {
 
   /** The only way a task changes. Validates the move, records who did what, returns the new row. */
   /** A `plan` in the patch replaces the old one whole: a new plan is the owner's current intent, not an addition. */
-  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "reviewer" | "reserved" | "refs" | "plan" | "rejections" | "signals" | "sdlc" | "role" | "cancelled">>, note?: string, extra: Pick<HistoryEntry, "profile" | "sweep" | "reason" | "from" | "withheld"> = {}, expectedFlowRevision?: number): Task {
+  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "reviewer" | "reserved" | "refs" | "plan" | "rejections" | "signals" | "sdlc" | "role" | "cancelled">>, note?: string, extra: Pick<HistoryEntry, "profile" | "sweep" | "reason" | "from" | "withheld" | "reviewCost" | "reviewContext"> = {}, expectedFlowRevision?: number): Task {
     const task = this.get(id);
     if (!task) throw new Error(`no task #${id}`);
     if (expectedFlowRevision !== undefined && (!Number.isSafeInteger(expectedFlowRevision) || expectedFlowRevision < 0 || task.history.length !== expectedFlowRevision)) throw new Error("task flow revision changed");
-    if (patch.state && patch.state !== task.state && !MOVES[task.state].includes(patch.state)) {
+    const untouchedReturn = event === "backlog returned untouched" && patch.state === "backlog" && patch.owner === null && patch.reviewer === null
+      && ["proposed", "in_progress"].includes(task.state) && expectedFlowRevision !== undefined && !!note?.trim() && !taskHasWorkEvidence(task);
+    if (patch.state && patch.state !== task.state && !MOVES[task.state].includes(patch.state) && !untouchedReturn) {
       throw new Error(`task #${id} is ${task.state}: cannot move to ${patch.state}`);
     }
     const next = { ...task, ...patch, refs: { ...task.refs, ...patch.refs } };
     if (next.state === "backlog" && (next.owner || next.reviewer)) throw new Error(`task #${id}: backlog cannot have an owner or reviewer`);
-    if (patch.state === "backlog" && task.owner) throw new Error(`task #${id}: owned work cannot return to backlog`);
-    if (patch.state === "backlog" && taskHasStarted(task)) throw new Error(`task #${id}: started work cannot return to backlog`);
-    const history = [...task.history, { at: Date.now(), by, event, ...(note ? { note } : {}), ...(patch.cancelled?.supersededBy ? { supersededBy: patch.cancelled.supersededBy } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}), ...(extra.from ? { from: extra.from } : {}), ...(extra.withheld && note ? { withheld: true as const } : {}) }];
+    if (!untouchedReturn) {
+      if (patch.state === "backlog" && task.owner) throw new Error(`task #${id}: owned work cannot return to backlog`);
+    }
+    if (patch.state === "backlog" && taskHasStarted(task) && !untouchedReturn) throw new Error(`task #${id}: started work cannot return to backlog`);
+    const history = [...task.history, { at: Date.now(), by, event, ...(note ? { note } : {}), ...(patch.cancelled?.supersededBy ? { supersededBy: patch.cancelled.supersededBy } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}), ...(extra.from ? { from: extra.from } : {}), ...(extra.withheld && note ? { withheld: true as const } : {}), ...(extra.reviewContext === "fresh" || extra.reviewContext === "continuing" ? { reviewContext: extra.reviewContext } : {}), ...(extra.reviewCost ? { reviewCost: extra.reviewCost } : {}) }];
     this.taskWrite(() => this.db
       .query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, reserved = ?, refs = ?, plan = ?, rejections = ?, signals = ?, history = ?, sdlc = ?, task_role = ?, cancelled = ?, updated = ? WHERE id = ?")
       .run(next.state, next.owner, next.reviewer, next.reserved ?? null, JSON.stringify(next.refs), JSON.stringify(next.plan ?? {}), next.rejections, JSON.stringify(next.signals), JSON.stringify(history), next.sdlc ? JSON.stringify(next.sdlc) : null, next.role ?? null, next.cancelled ? JSON.stringify(next.cancelled) : null, Date.now(), id));
@@ -309,7 +331,7 @@ export class Board {
   /** A planner reserves a routing slot without claiming or dispatching the work. */
   pullPlanned(id: number, by: PeerId, reserved: PeerId, revision: number, note: string, withheld = false): Task {
     const task = this.get(id);
-    if (!task || (task.planningRevision ?? 0) !== revision || task.state !== "backlog" || task.owner || taskHasStarted(task)) throw new Error("planner pull changed or already started");
+    if (!task || (task.planningRevision ?? 0) !== revision || task.state !== "backlog" || task.owner || !taskCanPlan(task)) throw new Error("planner pull changed or already started");
     const now = Date.now(), entry: HistoryEntry = { at: now, by, event: "backlog pulled", planning: { revision: revision + 1, fields: ["reserved"], previous: { reserved: task.reserved ?? null }, pull: true }, note, ...(withheld ? { withheld: true as const } : {}) };
     const result = this.taskWrite(() => this.db.query("UPDATE tasks SET state='proposed',owner=NULL,reviewer=NULL,reserved=?,planning_revision=planning_revision+1,history=?,updated=? WHERE id=? AND planning_revision=? AND state='backlog' AND owner IS NULL")
       .run(reserved, JSON.stringify([...task.history, entry]), now, id, revision));

package/src/hub/bus.ts

@@ -40,9 +40,9 @@ export interface BusOptions {
   /**
    * Optional: does a queued envelope still matter to this recipient (issue #106)? Asked per recipient when a delivery is
    * built and again right before it is handed over, after condensation. False drops it unsent: the journal records it
-   * as discarded and taps see a `stale` event.
+   * as discarded and taps see a `stale` event. A string is false with its own reason (#223, a review-only peer).
    */
-  relevant?: (peer: PeerId, env: Envelope) => boolean;
+  relevant?: (peer: PeerId, env: Envelope) => boolean | string;
   /**
    * Optional: why this recipient does not get this envelope (issue #107, a turn-free cohort). Asked per recipient once
    * the audience is final (implicit replies and `digest` resolved), so the other recipients still get it, unchanged;
@@ -1088,7 +1088,13 @@ export class Bus {
   }
 
   private isRelevant(id: PeerId, env: Envelope): boolean {
-    return !this.withdrawn.has(env.id) && (this.opts.relevant?.(id, env) ?? true);
+    return this.irrelevance(id, env) === undefined;
+  }
+
+  /** Why a queued envelope no longer goes to `id`, or undefined when it still does. */
+  private irrelevance(id: PeerId, env: Envelope): string | undefined {
+    const verdict = this.withdrawn.has(env.id) ? false : this.opts.relevant?.(id, env) ?? true;
+    return verdict === true ? undefined : typeof verdict === "string" ? verdict : `stale: task #${env.refs?.task ?? "?"} is no longer open for ${id}`;
   }
 
   /**
@@ -1101,8 +1107,8 @@ export class Bus {
     let dropped = false;
     for (let i = queue.length - 1; i >= 0; i--) {
       const env = queue[i]!;
-      if (this.isRelevant(id, env)) continue;
-      const reason = `stale: task #${env.refs?.task ?? "?"} is no longer open for ${id}`;
+      const reason = this.irrelevance(id, env);
+      if (reason === undefined) continue;
       queue.splice(i, 1);
       dropped = true;
       if (this.journal) this.pendingOutcomes.push({ id: crypto.randomUUID(), peer: id, state: "discarded", createdAt: Date.now(), originals: [env], out: [], reason });

package/src/hub/claude-state.ts

@@ -0,0 +1,37 @@
+// No imports: the statusline tee and the CLI load this without the daemon (#450 I3).
+const PEER = /^[a-z][a-z0-9-]{0,31}$/;
+
+/** The peer a Claude process writes for: its AGENTHUB_PEER_ID when well formed, otherwise the builtin claude peer. */
+export function claudePeer(value: string | undefined): string {
+  return value !== undefined && PEER.test(value) ? value : "claude";
+}
+
+/** Per-peer Claude state file names. The builtin claude peer keeps its original names, so nothing migrates. */
+export function claudeStateFile(base: "claude-launch" | "claude-session" | "claude-context", peer: string): string {
+  // Instance ids are always <kind>-<name>; a builtin id has no hyphen.
+  return peer.includes("-") && PEER.test(peer) ? `${base}.${peer}.json` : `${base}.json`;
+}
+
+/** A Claude peer's own row in terminal-recovery.json for this daemon, never a sibling instance's (row order is arbitrary). */
+export function ownTerminalRow(records: unknown, peer: string, projectRoot: string, instanceId: string): { launchId?: unknown } | undefined {
+  if (!Array.isArray(records)) return undefined;
+  return records.find((row) => row?.peer === peer && row?.projectRoot === projectRoot && row?.instanceId === instanceId);
+}
+
+/**
+ * Whether a Claude session's transcript exists: the path the peer's own status line reported for that session, else
+ * the builtin's default location. An instance may run under its own CLAUDE_CONFIG_DIR, which the hub cannot see:
+ * without its reported path the answer is unknown, and unknown counts as persisted (it never waives session identity).
+ */
+export function transcriptPersisted(reported: { sessionId?: string; transcriptPath?: string }, sessionId: string, instance: boolean, fallbackPath: string, exists: (path: string) => boolean | "unknown"): boolean {
+  // Only a positive "missing" (ENOENT) is not persisted; an unreadable path is unknown and keeps the identity strict.
+  const found = (path: string) => exists(path) !== false;
+  if (reported.sessionId === sessionId && reported.transcriptPath) return found(reported.transcriptPath);
+  return instance || found(fallbackPath);
+}
+
+/** lstat evidence: true when present, false only on ENOENT/ENOTDIR, "unknown" for any other failure (EACCES included). */
+export function pathEvidence(path: string, lstat: (path: string) => unknown): boolean | "unknown" {
+  try { lstat(path); return true; }
+  catch (error) { const code = (error as { code?: string }).code; return code === "ENOENT" || code === "ENOTDIR" ? false : "unknown"; }
+}

package/src/hub/cost-governance.ts

@@ -0,0 +1,76 @@
+/** S10 cost evidence is metadata only. Legacy scope and incomplete readback remain unknown. */
+export interface ReviewScope { scope: "none" | "delta" | "full"; reviewers: number }
+export interface CostPlan { review?: ReviewScope; ci?: "focused" | "full" | "reuse" }
+export interface ReviewCost extends CostPlan { head?: string }
+export interface CostTask { repo: string; pr: number; private?: boolean; history: { event: string; at: number; reviewCost?: ReviewCost }[] }
+export interface CostPr { repo: string; pr: number; state: "OPEN" | "CLOSED" | "MERGED"; mergedAt?: number; complete: boolean; ciRuns?: { id: number; attempt: number }[]; reviews?: number }
+export interface CostRow { repo: string; pr: number; reviewRounds: number; ciRuns: number | null; ciReruns: number | null; fullReReviews: number; deltaReviews: number; reviewMs: number | null; unknownReviewScopes: number; githubReviews: number | null; complete: boolean }
+export interface CostReport { rows: CostRow[]; truncated: boolean }
+export function cleanCostPlan(input: unknown): CostPlan {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("invalid cost scope");
+  const value = input as Record<string, unknown>;
+  const result: CostPlan = {};
+  if (value.review !== undefined) {
+    const review = value.review as Record<string, unknown>;
+    if (!review || typeof review !== "object" || Array.isArray(review) || Object.keys(review).some(key => !["scope", "reviewers"].includes(key))
+      || !["none", "delta", "full"].includes(review.scope as string) || !Number.isSafeInteger(review.reviewers)
+      || (review.scope === "none" ? review.reviewers !== 0 : (review.reviewers as number) < 1 || (review.reviewers as number) > 8)) throw new Error("invalid review cost scope");
+    result.review = { scope: review.scope as ReviewScope["scope"], reviewers: review.reviewers as number };
+  }
+  if (value.ci !== undefined) {
+    if (!["focused", "full", "reuse"].includes(value.ci as string)) throw new Error("invalid CI cost scope");
+    result.ci = value.ci as CostPlan["ci"];
+  }
+  return result;
+}
+const validRepo = (repo: string) => /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) && !repo.startsWith("-");
+const key = (repo: string, pr: number) => `${repo.toLowerCase()}#${pr}`;
+/** One round is a board review handoff, not one reviewer in a multi-reviewer round. CI attempts share a run id. */
+export function costMetrics(tasks: CostTask[], prs: CostPr[]): CostReport {
+  const withheld = new Set(tasks.filter(task => task.private).map(task => key(task.repo, task.pr)));
+  const rows: CostRow[] = [];
+  let truncated = tasks.length > 500 || prs.length > 200, historyLeft = 10_000;
+  const seen = new Set<string>();
+  for (const pr of prs.slice(0, 200)) {
+    const identity = key(pr.repo, pr.pr);
+    if (!validRepo(pr.repo) || !Number.isSafeInteger(pr.pr) || pr.pr < 1 || pr.state !== "MERGED" || withheld.has(identity) || seen.has(identity)) continue;
+    if (!tasks.some(task => !task.private && key(task.repo, task.pr) === identity)) continue;
+    seen.add(identity);
+    const rounds: { at: number; scope?: ReviewScope["scope"]; elapsed?: number }[] = [];
+    let complete = pr.complete && Number.isFinite(pr.mergedAt);
+    for (const task of tasks.slice(0, 500).filter(task => key(task.repo, task.pr) === identity)) {
+      const history = task.history.slice(0, Math.max(0, historyLeft)); historyLeft -= history.length;
+      if (history.length < task.history.length) { complete = false; truncated = true; }
+      let pending: typeof rounds[number] | undefined;
+      for (const event of [...history].sort((a, b) => a.at - b.at)) {
+        if (!Number.isFinite(event.at) || event.at < 0 || !Number.isFinite(pr.mergedAt) || event.at > pr.mergedAt!) continue;
+        if (event.event === "done") {
+          pending = { at: event.at, scope: event.reviewCost?.review?.scope }; rounds.push(pending);
+        } else if (pending && ["approved", "changes_requested"].includes(event.event)) { pending.elapsed = event.at - pending.at; pending = undefined; }
+      }
+    }
+    rounds.sort((a, b) => a.at - b.at);
+    const attempts = new Map<number, number>();
+    if (pr.ciRuns) for (const run of pr.ciRuns.slice(0, 100)) {
+      if (!Number.isSafeInteger(run.id) || run.id < 1 || !Number.isSafeInteger(run.attempt) || run.attempt < 1 || run.attempt > 10_000) { complete = false; continue; }
+      attempts.set(run.id, Math.max(attempts.get(run.id) ?? 0, run.attempt));
+    }
+    if (pr.ciRuns && pr.ciRuns.length > 100) { complete = false; truncated = true; }
+    if (!pr.ciRuns || pr.reviews === undefined || rounds.some(round => round.elapsed === undefined || round.scope === undefined)) complete = false;
+    rows.push({ repo: pr.repo.toLowerCase(), pr: pr.pr, reviewRounds: rounds.length,
+      ciRuns: pr.ciRuns ? attempts.size : null, ciReruns: pr.ciRuns ? [...attempts.values()].reduce((sum, n) => sum + n - 1, 0) : null,
+      fullReReviews: rounds.filter((round, index) => index > 0 && round.scope === "full").length,
+      deltaReviews: rounds.filter(round => round.scope === "delta").length,
+      reviewMs: rounds.every(round => round.elapsed !== undefined) ? rounds.reduce((sum, round) => sum + round.elapsed!, 0) : null,
+      unknownReviewScopes: rounds.filter(round => round.scope === undefined).length, githubReviews: pr.reviews ?? null, complete });
+  }
+  return { rows: rows.sort((a, b) => a.repo.localeCompare(b.repo) || a.pr - b.pr), truncated };
+}
+export function costBandProposals(report: CostReport, upper: Partial<Record<"reviewRounds" | "ciRuns" | "ciReruns" | "fullReReviews" | "deltaReviews" | "reviewMs", number>>): { repo: string; pr: number; metric: string; observed: number; upper: number }[] {
+  if (report.truncated) return [];
+  return report.rows.filter(row => row.complete).flatMap(row => Object.entries(upper).flatMap(([metric, limit]) => {
+    if (!["reviewRounds", "ciRuns", "ciReruns", "fullReReviews", "deltaReviews", "reviewMs"].includes(metric) || !Number.isFinite(limit) || limit! < 0) return [];
+    const observed = row[metric as keyof CostRow];
+    return typeof observed === "number" && observed > limit! ? [{ repo: row.repo, pr: row.pr, metric, observed, upper: limit! }] : [];
+  }));
+}