@staix/agent-hub 0.26.0 → 0.28.0

package/src/cli/main.ts

@@ -19,7 +19,7 @@ import { parseConfiguredAcpArguments, runConfiguredAcpEntry, requireActiveConfig
 import type { NativeCliEntryContext } from "../adapters/definitions/native-cli-entry-types.ts";
 import { BUILTIN_CLI_ENTRIES, createProjectAdapterCatalog, definitionOf, DOCTOR_TOOL_PROBES, DOCTOR_MEMORY_CAPTURE_PEERS, DOCTOR_PLUGIN_PROBE, nativeDoctorCheck, nativeMemoryCaptureRow, type MemorySetupReading, nativeDoctorRecoveryIdentity, nativeDoctorOptionalProbes } from "../adapters/registry.ts";
 import { parsePiFlags } from "../adapters/definitions/native-cli-pi.ts";
-import { supportsBoardReleaseFilter, supportsBoardColumnMetadata } from "./board-read.ts";
+import { supportsBoardReleaseFilter, supportsBoardColumnMetadata, readAllTasks } from "./board-read.ts";
 import { matchesPolicy } from "../hub/path-policy.ts";
 import { projectedDiff } from "../hub/projected-diff.ts";
 import { TextProjections } from "../hub/text-projection.ts";
@@ -30,7 +30,7 @@ import { renderIntake, renderIntakeChange } from "./intake-output.ts";
 import { renderLearnChange, renderLearnList } from "./learn-output.ts";
 import { renderCapabilities } from "./capabilities-output.ts";
 import { parseStudyArgs } from "./study.ts";
-import { renderStudyList, renderStudyReceipt, renderStudyShow } from "./study-output.ts";
+import { renderExperiments, renderStudyList, renderStudyReceipt, renderStudyShow } from "./study-output.ts";
 import { renderHandoffReceipt, renderHandoffs } from "./handoff-output.ts";
 import { parseHandoffArgs } from "./handoff-args.ts";
 import { terminalText } from "./console-state.ts";
@@ -70,7 +70,10 @@ import { inspectProject, startProject, stopProject, runProjectDaemon } from "../
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 import { openManager, startManager, stopManager } from "../hub/manager.ts";
 import { OmniRoute } from "../omniroute/client.ts";
-import { init, planInit } from "./init.ts";
+import { autonomyInheritanceChange, init, initSettingRows, planInit } from "./init.ts";
+import { INIT_USAGE, parseInitSettings } from "./init-settings.ts";
+import { promptGate, runInitPrompt, settingLines, shadowOffered, type InitAnswers } from "./init-prompt.ts";
+import { loadPacks } from "../hub/packs.ts";
 import { launcherPreview } from "./preview.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";
@@ -101,6 +104,7 @@ import { armRuns, benchCompare, benchCsv, benchReport, formatCompare, formatRepo
 import { benchPreflight, defaultIo, runBench } from "./bench.ts";
 import { ADDONS, isAddon, type AddonName } from "../hub/tooling.ts";
 import { goalCommand, memoryCommand, memoryStaleAnchorsCommand } from "./memory.ts";
+import { runSpecs, runSpecsStamp } from "./specs.ts";
 import { formatMemoryStaleAnchors } from "../hub/memory-stale-anchors.ts";
 import { AGENT_MEM_VERSION, assertAgentMemVersion, selectedMemoryProfile } from "../hub/memory-profile.ts";
 import { checkMemoryProfiles, formatMemoryProfileCheck } from "../hub/memory-profile-check.ts";
@@ -1037,23 +1041,28 @@ const commands: Record<string, () => Promise<void> | void> = {
     const setupFlags = takeFlags(args.filter(arg => arg !== "--yes"), ["--agents"], []);
     if (setupFlags.rest.length) fail("usage: ahub setup [--yes] [--agents <a,b>]");
     const registry = new Registry(), rl = process.stdin.isTTY ? createInterface({ input: process.stdin, output: process.stdout }) : undefined;
+    let homesFailed = false, homesFailure: unknown;
     try {
       const found = recoveryLauncherCurrent || delegatedPeer ? await discoverClaudeHomes({ home: homedir(), env: process.env }) : await usedClaudeHomes(registry, homedir(), process.env);
       for (const notice of found.notices) console.log(terminalText(notice));
-      await setupClaudeHomes({ homes: found.homes, env: process.env, packageRoot: root, yes: args.includes("--yes"),
-        interactive: !!rl,
-        current: () => { recoveryLauncherCurrent?.(); assertLifecycleAvailable(cwd); },
-        print: line => console.log(terminalText(line)), ask: async prompt => rl ? rl.question(prompt) : null,
-        probe: (argv, options) => { recoveryLauncherCurrent?.(); const result = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8", env: options.env, timeout: options.timeoutMs, maxBuffer: 1024 * 1024 }); recoveryLauncherCurrent?.(); return { status: result.status ?? -1, stdout: result.stdout ?? "" }; },
-        run: async (argv, env) => { recoveryLauncherCurrent?.(); const result = spawnSync(argv[0]!, argv.slice(1), { stdio: "inherit", env, timeout: 30_000 }); recoveryLauncherCurrent?.(); return result.status ?? -1; },
-      });
+      try {
+        await setupClaudeHomes({ homes: found.homes, env: process.env, packageRoot: root, yes: args.includes("--yes"),
+          interactive: !!rl,
+          current: () => { recoveryLauncherCurrent?.(); assertLifecycleAvailable(cwd); },
+          print: line => console.log(terminalText(line)), ask: async prompt => rl ? rl.question(prompt) : null,
+          probe: (argv, options) => { recoveryLauncherCurrent?.(); const result = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8", env: options.env, timeout: options.timeoutMs, maxBuffer: 1024 * 1024 }); recoveryLauncherCurrent?.(); return { status: result.status ?? -1, stdout: result.stdout ?? "" }; },
+          run: async (argv, env) => { recoveryLauncherCurrent?.(); const result = spawnSync(argv[0]!, argv.slice(1), { stdio: "inherit", env, timeout: 30_000 }); recoveryLauncherCurrent?.(); return result.status ?? -1; },
+        });
+      } catch (error) { homesFailed = true; homesFailure = error; }
       // #608: the one question about the default agent set, after the Claude homes and before doctor.
       if (!recoveryLauncherCurrent && !delegatedPeer) {
+        assertLifecycleAvailable(cwd);
         const refused = await setupStartAgents({ home: hubHome(), roots: [...registry.list().map(row => row.root), cwd], ...(setupFlags.one["--agents"] !== undefined ? { flag: setupFlags.one["--agents"] } : {}), yes: args.includes("--yes"),
           ...(rl ? { ask: async (prompt: string) => { try { return await rl.question(prompt); } catch { return null; } } } : {}), print: line => console.log(terminalText(line)) });
         if (refused) fail(refused);
       }
     } finally { registry.close(); rl?.close(); }
+    if (homesFailed) fail(startupDiagnostic(homesFailure));
     // #935: register the acon console plugin (acon reads it at its next start; no acon install is needed for this).
     const acon = registerAconPlugin(hubHome(), join(root, "src", "ui", "plugin.ts"));
     console.log("error" in acon ? `acon plugin not registered: ${acon.error}` : acon.changed ? `acon plugin registered: ${acon.path}` : `acon plugin up to date: ${acon.path}`);
@@ -1062,28 +1071,69 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   init: async () => {
-    const flags = takeFlags(args.filter(arg => arg !== "--dry-run" && arg !== "--json" && arg !== "--shadow" && arg !== "--release-guard"), ["--profile"], []);
-    if (flags.rest.length) fail("usage: ahub init [--profile dev|research|writing|general|<pack>] [--shadow] [--release-guard] [--dry-run --json]");
+    // #1065 T1: the settings flags come out first (a value flag takes the next word), then the older flags as before.
+    let settings: ReturnType<typeof parseInitSettings>;
+    try { settings = parseInitSettings(args); } catch (error) { return fail((error as Error).message); }
+    const flags = takeFlags(settings.rest.filter(arg => arg !== "--dry-run" && arg !== "--json" && arg !== "--shadow" && arg !== "--release-guard" && arg !== "--yes"), ["--profile"], []);
+    if (flags.rest.length) fail(INIT_USAGE);
     // A pack is a project file in .agenthub/roles/<name>.pack.json (#513a); init resolves the name and refuses an unknown one with the profiles and packs it knows.
-    const requestedProfile = flags.one["--profile"];
+    let requestedProfile = flags.one["--profile"];
     const newProject = !existsSync(join(cwd, ".agenthub/config.json"));
+    let request = settings.request, asked = Object.keys(request.values).length > 0;
+    let shadow = args.includes("--shadow"), releaseGuard = args.includes("--release-guard");
+    // #1065 T2: a person at a terminal on a new project, with no flag that sets anything and no --yes, is asked each setting (init-prompt.ts). Every other run, including a delegated peer, a live test and any run
+    // without a terminal, is never asked and gets defaults plus its flags. The gate is checked here, before any file is read or written, and --dry-run never prompts.
+    const flagGiven = asked || settings.request.autonomy !== undefined || requestedProfile !== undefined || shadow || releaseGuard;
+    if (promptGate({ newProject, flagGiven, yes: args.includes("--yes"), dryRun: args.includes("--dry-run"), stdinIsTTY: !!process.stdin.isTTY, stdoutIsTTY: !!process.stdout.isTTY, role: identity.role, delegated: !!delegatedPeer, liveTest })) {
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      // Ctrl-C closes the readline interface, which settles a pending question as null: the prompt ends with nothing written.
+      const interrupted = new Promise<null>(done => rl.once("close", () => done(null)));
+      const ask = (question: string): Promise<string | null> => Promise.race([rl.question(question).catch(() => null), interrupted]);
+      const machine = readAutonomyDefaults(hubHome(), [cwd]);
+      const preview = (answers: InitAnswers): string[] => {
+        const rows = initSettingRows(cwd, answers.profile, answers.shadow, answers.releaseGuard, answers.request);
+        const plan = planInit(cwd, answers.profile, answers.shadow, answers.releaseGuard, answers.request);
+        // The same autonomy-inheritance row `--dry-run` shows, from the one helper: a new project inherits the trusted machine preset after the writes unless the answer was off.
+        const inherit = autonomyInheritanceChange(cwd, machine.enabled, answers.request.autonomy);
+        if (inherit) plan.push(inherit);
+        return [...plan.map(change => `${change.action} ${change.path}: ${change.reason}${change.managedBlock ? ` (managed block: ${change.managedBlock})` : ""}`), ...settingLines(rows)];
+      };
+      let result: Awaited<ReturnType<typeof runInitPrompt>>;
+      try {
+        result = await runInitPrompt({ ask, print: line => console.log(terminalText(line)) },
+          { ...(machine.startAgents ? { machineAgents: machine.startAgents } : {}), packs: [...loadPacks(cwd).packs.keys()], shadowAvailable: shadowOffered(repoOf(cwd)) }, preview);
+      } finally { rl.close(); }
+      if (!result.ok) { console.error(`ahub init: ${result.reason === "refused" ? result.message : result.reason === "interrupted" ? `interrupted; ${result.message}` : result.message}`); process.exitCode = result.reason === "refused" ? 1 : 0; return; }
+      requestedProfile = result.answers.profile; request = result.answers.request; asked = Object.keys(request.values).length > 0; shadow = result.answers.shadow; releaseGuard = result.answers.releaseGuard;
+    }
+    // `--autonomy off` skips the machine inheritance on a new project; `inherit` is today's behaviour. Neither changes an existing project.
+    const inheritAutonomy = newProject && request.autonomy !== "off";
+    if (!newProject && request.autonomy !== undefined) console.error("note: --autonomy applies to a new project only; this project already exists, so its autonomy settings are unchanged");
     if (args.includes("--dry-run")) {
-      const plan = planInit(cwd, requestedProfile, args.includes("--shadow"), args.includes("--release-guard"));
+      const plan = planInit(cwd, requestedProfile, shadow, releaseGuard, request);
+      const rows = initSettingRows(cwd, requestedProfile, shadow, releaseGuard, request);
       const defaults = readAutonomyDefaults(hubHome(), [cwd]);
-      if (newProject && defaults.enabled) plan.push({ action: existsSync(join(cwd, ".agenthub/config.local.json")) ? "modify" : "create", path: join(cwd, ".agenthub/config.local.json"), reason: "inherit the trusted machine autonomy preset; consent is checked at daemon startup" });
+      const inherit = inheritAutonomy ? autonomyInheritanceChange(cwd, defaults.enabled, request.autonomy) : undefined;
+      if (inherit) plan.push(inherit);
       if (defaults.notice) console.error(defaults.notice);
-      return console.log(args.includes("--json") ? JSON.stringify(plan, null, 2) : plan.map(change => `${change.action} ${change.path}: ${change.reason}${change.managedBlock ? ` (managed block: ${change.managedBlock})` : ""}`).join("\n") || "already up to date");
+      // Without a settings flag the preview is the bare list of file rows, as it always was; with one it is { changes, settings }.
+      if (args.includes("--json")) return console.log(JSON.stringify(asked ? { changes: plan, settings: rows } : plan, null, 2));
+      const settingLines = rows.map(row => `  ${row.key}: ${row.from === undefined ? "(not set)" : JSON.stringify(row.from)} -> ${JSON.stringify(row.to)} (${row.file})`);
+      return console.log([...plan.map(change => `${change.action} ${change.path}: ${change.reason}${change.managedBlock ? ` (managed block: ${change.managedBlock})` : ""}`), ...settingLines].join("\n") || "already up to date");
     }
     assertLifecycleAvailable(cwd);
-    if (newProject && delegatedPeer && readAutonomyDefaults(hubHome(), [cwd]).enabled) fail("machine autonomy inheritance is person-only; delegated live tests cannot apply it");
-    const changed = init(cwd, requestedProfile, args.includes("--shadow"), args.includes("--release-guard"));
+    if (inheritAutonomy && delegatedPeer && readAutonomyDefaults(hubHome(), [cwd]).enabled) fail("machine autonomy inheritance is person-only; delegated live tests cannot apply it (ahub init --autonomy off skips it)");
+    let changed: string[];
+    try { changed = init(cwd, requestedProfile, shadow, releaseGuard, request); } catch (error) { return fail((error as Error).message); }
     const project = registeredProject();
     console.log(changed.length ? changed.map((p) => `${existsSync(p) ? "wrote" : "removed"} ${p}`).join("\n") : "already up to date");
     if (newProject) {
-      const registry = new Registry();
-      try { for (const line of await inheritMachineAutonomy(project, hubHome(), autonomyEnvironment(process.env, !!process.stdin.isTTY), registry)) console.log(terminalText(line)); }
-      finally { registry.close(); }
-      // #608: the machine's default agent set, copied the same way (person-only: a delegated live test never inherits it).
+      if (inheritAutonomy) {
+        const registry = new Registry();
+        try { for (const line of await inheritMachineAutonomy(project, hubHome(), autonomyEnvironment(process.env, !!process.stdin.isTTY), registry)) console.log(terminalText(line)); }
+        finally { registry.close(); }
+      }
+      // #608: the machine's default agent set, copied the same way (person-only: a delegated live test never inherits it). An explicit --agents is already in config.local.json, so it wins.
       if (!delegatedPeer) { const roots = (() => { const r = new Registry(); try { return r.list().map(row => row.root); } finally { r.close(); } })(); for (const line of inheritMachineStart(cwd, hubHome(), [...roots, cwd])) console.log(terminalText(line)); }
     }
     const config = projectConfig(), examples = resolveProfile(config.profile, config.profile_overrides).example_checks;
@@ -1201,29 +1251,42 @@ const commands: Record<string, () => Promise<void> | void> = {
     const hub = await connect();
     try {
       if (operation === "list") {
-        const { one, rest: flags } = takeFlags(rest, ["--peer"], []);
-        if (flags.length) fail("usage: ahub queue list [--peer <id>] [--json] [--full] [--color=auto|always|never]");
-        const result = await hub.request({ t: "queue", op: "list", ...(one["--peer"] ? { peer: one["--peer"] } : {}) });
+        const all = rest.includes("--all");
+        const { one, rest: flags } = takeFlags(rest.filter((word) => word !== "--all"), ["--peer"], []);
+        if (flags.length) fail("usage: ahub queue list [--peer <id>] [--all] [--json] [--full] [--color=auto|always|never]");
+        const result = await hub.request({ t: "queue", op: "list", ...(one["--peer"] ? { peer: one["--peer"] } : {}), ...(all ? { all: true } : {}) });
         if (!result.ok) fail(result.error,result.refusalAudited===true,result.authorityRefused);
         if (options.json) return console.log(JSON.stringify(result.deliveries, null, 2));
         printOutput(renderQueue(result.deliveries, options.columns, Date.now()), options.color);
+        // #1096: rows a resolution already settled are history, hidden by default; say how many and how to see them, on stderr so a pipe of the table stays clean.
+        if (result.hiddenSettled) console.error(`${result.hiddenSettled} settled deliver${result.hiddenSettled === 1 ? "y" : "ies"} hidden (already resolved); ahub queue list --all shows them`);
         return;
       }
       if (operation === "discard") {
         // #713: the person's bulk clear of one peer's queue. Without --yes it only says how many it would discard.
         const yes = rest.includes("--yes");
         const { one, rest: others } = takeFlags(rest.filter((word) => word !== "--yes"), ["--peer", "--reason", "--state"], []);
-        if (others.length || !one["--peer"] || (one["--state"] !== undefined && !["queued", "needs_review"].includes(one["--state"]))) fail("usage: ahub queue discard --peer <id> --reason <text> [--state queued|needs_review] [--yes]");
+        if (others.length || !one["--peer"] || (one["--state"] !== undefined && !["queued", "needs_review", "failed"].includes(one["--state"]))) fail("usage: ahub queue discard --peer <id> --reason <text> [--state queued|needs_review|failed] [--yes]; without --state it clears the peer's queued and unsettled failed deliveries");
         if (yes && !one["--reason"]?.trim()) fail("ahub queue discard needs --reason <text> with --yes: it is recorded on every discarded delivery");
-        const result = await hub.request({ t: "queue", op: "discard", peer: one["--peer"], ...(one["--state"] ? { state: one["--state"] } : {}), ...(yes ? { confirmed: true, reason: one["--reason"] } : {}) }, 60_000);
+        // #1096: with no --state the bulk clear takes the peer's queued rows and its unsettled failed rows (needs_review rows still need an explicit --state, as before); an explicit --state names exactly one kind.
+        const states = one["--state"] === undefined ? ["queued", "failed"] : [one["--state"]];
+        // A hub from before `queue_discard_states` ignores `states` and discards queued rows whatever kind was asked for, so the new wire form is never sent to it. A single queued or needs_review kind still goes in the legacy `state` field that every hub reads.
+        const legacy = states.length === 1 && (states[0] === "queued" || states[0] === "needs_review");
+        if (!legacy && !hub.features.includes("queue_discard_states")) fail(`the running hub predates failed-row discard and would discard queued rows instead of ${one["--state"] === undefined ? "queued and failed rows" : `${one["--state"]} rows`}; nothing was sent. Upgrade and restart it first, or run ahub queue discard --peer ${one["--peer"]} --state queued to clear queued rows only`);
+        const result = await hub.request({ t: "queue", op: "discard", peer: one["--peer"], ...(legacy ? { state: states[0] } : { states }), ...(yes ? { confirmed: true, reason: one["--reason"] } : {}) }, 60_000);
         if (!result.ok) fail(result.error,result.refusalAudited===true,result.authorityRefused);
         if (options.json) return console.log(JSON.stringify(result, null, 2));
-        if (!yes) return console.log(`${result.count} ${result.state} deliver${result.count === 1 ? "y" : "ies"} for ${result.peer}; nothing discarded. Run again with --reason <text> --yes to discard them.`);
-        console.log(`discarded ${result.discarded} of ${result.count} ${result.state} deliver${result.count === 1 ? "y" : "ies"} for ${result.peer}${result.refused ? `; ${result.refused} refused (${Object.entries(result.refusedBy ?? {}).map(([why, n]) => `${why} ${n}`).join(", ")})` : ""}`);
+        // One kind keeps the sentence this command always printed ("12 queued deliveries for claude"); a mix of kinds names each ("3 queued and 2 failed deliveries for claude").
+        const present = Object.entries(result.byState ?? {}).filter(([, n]) => n) as [string, number][];
+        const noun = `deliver${result.count === 1 ? "y" : "ies"}`;
+        const what = present.length > 1 ? `${result.count} ${noun}` : `${result.count} ${present[0]?.[0] ?? states.join(" or ")} ${noun}`;
+        const split = present.length > 1 ? ` (${present.map(([kind, n]) => `${n} ${kind}`).join(" and ")})` : "";
+        if (!yes) return console.log(`${what} for ${result.peer}${split}; nothing discarded. Run again with --reason <text> --yes to discard them.`);
+        console.log(`discarded ${result.discarded} of ${what} for ${result.peer}${split}${result.refused ? `; ${result.refused} refused (${Object.entries(result.refusedBy ?? {}).map(([why, n]) => `${why} ${n}`).join(", ")})` : ""}`);
         return;
       }
       const [id, ...flags] = rest;
-      if (!id || !["show", "resolve"].includes(operation)) fail("usage: ahub queue show <id> | resolve <id> --action completed|retry|discard --reason <text> [--revision N] | discard --peer <id> --reason <text> [--state queued|needs_review] [--yes]");
+      if (!id || !["show", "resolve"].includes(operation)) fail("usage: ahub queue show <id> | resolve <id> --action completed|retry|discard --reason <text> [--revision N] | discard --peer <id> --reason <text> [--state queued|needs_review|failed] [--yes]");
       if (operation === "show") {
         if (flags.length) fail("usage: ahub queue show <id>");
         const shown = await hub.request({ t: "queue", op: "show", id });
@@ -1525,6 +1588,11 @@ const commands: Record<string, () => Promise<void> | void> = {
       catch { return fail("cannot read the contract file"); }
       try { return JSON.parse(text); } catch { return fail("the contract file is not valid JSON"); }
     };
+    if (parsed.op === "experiments") {
+      // A read of the records Tasks keeps (hub_experiment_show): it runs no command and reads no file, and the hub blanks a private record itself.
+      const args = parsed.attempt ? { attemptId: parsed.attempt, ...(parsed.eventsAfter === undefined ? {} : { eventAfter: parsed.eventsAfter }) } : parsed.plan ? { planHash: parsed.plan, baselineAttemptId: parsed.baseline, variantAttemptId: parsed.variant } : { campaignId: parsed.campaign, ...(parsed.after === undefined ? {} : { after: parsed.after }) };
+      return showToolText(data => renderExperiments(data, present.columns), await taskOp("hub_experiment_show", args), present);
+    }
     if (parsed.op === "show") return showToolText(data => parsed.id ? renderStudyShow(data, present.columns) : renderStudyList(data, present.columns), await taskOp("hub_study_show", parsed.id ? { id: parsed.id } : parsed.after ? { after: parsed.after } : {}), present);
     const request = parsed.op === "draft" ? { parentTaskId: parsed.parentTaskId, contract: contract(parsed.file) }
       : parsed.op === "revise" ? { id: parsed.id, revision: parsed.revision, contract: contract(parsed.file) }
@@ -1623,11 +1691,11 @@ const commands: Record<string, () => Promise<void> | void> = {
     const state = rest.find((a) => !a.startsWith("--"));
     if (byColumn && !boardStatus) boardStatus = (await boardHub.request({ t: "status" })).status;
     if (byColumn && !supportsBoardColumnMetadata(boardStatus)) fail("running hub does not support accurate board column metadata; use a compatible daemon");
-    const tasks = JSON.parse(await taskOp("hub_task_list", { ...(ready ? { ready: true } : state ? { state } : {}), ...(release ? { release } : {}), ...(byColumn ? { columnMetadata: true } : {}) }, false, boardHub)) as any[];
+    const tasks = await readAllTasks(args => taskOp("hub_task_list", args, false, boardHub), { ...(ready ? { ready: true } : state ? { state } : {}), ...(release ? { release } : {}), ...(byColumn ? { columnMetadata: true } : {}) }, identity.role === "tools");
     if (options.json && !byColumn) return console.log(JSON.stringify(tasks, null, 2));
     let allTasks: any[] | null = tasks;
     if (ready || state || release) {
-      try { allTasks = JSON.parse(await taskOp("hub_task_list", byColumn ? { columnMetadata: true } : {}, true, boardHub)) as any[]; }
+      try { allTasks = await readAllTasks(args => taskOp("hub_task_list", args, true, boardHub), byColumn ? { columnMetadata: true } : {}, identity.role === "tools"); }
       catch (error) {
         if (byColumn) fail("board column dependency context unavailable; retry with a complete snapshot");
         allTasks = null;
@@ -1866,13 +1934,13 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (sub !== "propose" || rest.length < 1) fail("usage: ahub task propose [<class>] <title...> | show <id> | assign <id> <peer> | unassign <id> | cancel <id> --reason <text> | escalate <id> | handoff --project <root|id> <title...>");
     // `--class` is the explicit form. A first word that is a class name is still taken as the class (the documented
     // short form), but said out loud: "review the auth module" would otherwise be filed as class review, silently.
-    const urgent = rest.includes("--urgent"), backlog = rest.includes("--backlog");
-    const flags = takeFlags(rest.filter((a) => a !== "--urgent" && a !== "--backlog"), ["--owner", "--detail", "--class"], ["--path", "--after"]);
+    const urgent = rest.includes("--urgent"), backlog = rest.includes("--backlog"), needsNetwork = rest.includes("--needs-network"), needsWorktree = rest.includes("--needs-worktree");
+    const flags = takeFlags(rest.filter((a) => a !== "--urgent" && a !== "--backlog" && a !== "--needs-network" && a !== "--needs-worktree"), ["--owner", "--detail", "--class"], ["--path", "--after"]);
     const positional = !flags.one["--class"] && ((CLASSES as readonly string[]).includes(flags.rest[0] ?? "") || Object.hasOwn((() => { const config = projectConfig(); return resolveProfile(config.profile, config.profile_overrides); })().classes, flags.rest[0] ?? "")) && flags.rest.length > 1;
     const cls = flags.one["--class"] ?? (positional ? flags.rest[0] : undefined);
     const title = (positional ? flags.rest.slice(1) : flags.rest).join(" ");
     if (positional) console.error(`note: "${cls}" was taken as the class and left out of the title; use --class <c> when the title itself starts with that word`);
-    console.log(await taskOp("hub_task_propose", { ...(cls ? { class: cls } : {}), title, owner: flags.one["--owner"], detail: flags.one["--detail"], ...(flags.many["--path"]?.length ? { refs: { paths: flags.many["--path"] } } : {}), ...(flags.many["--after"]?.length ? { after: flags.many["--after"].map(Number) } : {}), ...(urgent ? { urgent: true } : {}), ...(backlog ? { backlog: true } : {}) }));
+    console.log(await taskOp("hub_task_propose", { ...(cls ? { class: cls } : {}), title, owner: flags.one["--owner"], detail: flags.one["--detail"], ...(flags.many["--path"]?.length ? { refs: { paths: flags.many["--path"] } } : {}), ...(flags.many["--after"]?.length ? { after: flags.many["--after"].map(Number) } : {}), ...(urgent ? { urgent: true } : {}), ...(needsNetwork ? { needs_network: true } : {}), ...(needsWorktree ? { needs_worktree: true } : {}), ...(backlog ? { backlog: true } : {}) }));
   },
 
   review: async () => {
@@ -2215,7 +2283,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (args.includes("--all")) return printProjects(options);
     const hub = await connect();
     try {
-      const { status } = await hub.request({ t: "status" });
+      const { status } = await hub.request({ t: "status", specs: true });
       if (options.json) return console.log(JSON.stringify(status, null, 2));
       const quota = await hub.request({ t: "budget" });
       printOutput(renderStatus({ ...status, budget: quota.budget ?? {} }, options.columns, Date.now(), options.full), options.color);
@@ -2368,6 +2436,14 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (options.json) return console.log(JSON.stringify(data, null, 2));
     printOutput(renderReport(data, options.columns, Date.now(), by >= 0), options.color);
   },
+  specs: async () => {
+    if (args[0] !== "stamp") { process.exitCode = runSpecs(args, cwd, loadConfig(cwd).specs); return; }
+    // #1064 T3: person only. An agent identity never gets here (stamp is a `console` command in classifyPeerCommand); runSpecsStamp also refuses a run with no terminal.
+    const rl = process.stdin.isTTY && process.stdout.isTTY ? createInterface({ input: process.stdin, output: process.stdout }) : undefined;
+    try {
+      process.exitCode = await runSpecsStamp(args.slice(1), cwd, loadConfig(cwd).specs, { isTTY: !!rl, ask: async question => /^y(es)?$/i.test((await rl!.question(`${question} [y/N] `)).trim()) });
+    } finally { rl?.close(); }
+  },
   usage: async () => {
     const options = outputOptions();
     const rest = outputArguments();

package/src/cli/output.ts

@@ -10,9 +10,11 @@ import { ownerIsolationText } from "./role-holders.ts";
 import { schedulePeriodText, scheduleWhen } from "../hub/schedules.ts";
 import { formatReport, formatTaskReport, type Report, type TaskReport } from "../hub/report.ts";
 import type { Counter, LimitsResult, TotalResult, UsageResult } from "../hub/usage-rollup.ts";
+import type { SpecsStatus } from "../hub/specs-task.ts";
 
 export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" | "Memory"; level: "ok" | "warn" | "fail" | "unknown"; name: string; detail: string }
 export interface StatusOutput {
+  specs?: SpecsStatus & { missingBlockHint?: boolean };
   queueBackpressure?: QueueBackpressureStatus;
   pendingRestart?: readonly { key: string; reason: string }[];
   retainedConfig?: readonly { key: string; reason: string }[];
@@ -211,6 +213,13 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   if (data.roleInfo) data = { ...data, peers: Object.fromEntries(Object.entries(data.peers).map(([peer, value]) => [peer, { ...value, ...data.roleInfo?.[peer] }])) };
   const out = lines(`agent-hub${data.version ? ` ${data.version}` : ""}  pid ${data.pid ?? "unknown"}  control 127.0.0.1:${data.controlPort ?? "unknown"}`, columns, "info");
   if (data.cwd) out.push(...lines(data.cwd, columns));
+  const specs = data.specs;
+  if (specs && [specs.specCount, specs.documents, specs.errors, specs.stale].every(value => Number.isSafeInteger(value) && value >= 0)
+    && (specs.specCount > 0 || specs.documents > 0 || specs.errors > 0)) {
+    out.push(...lines(`specs: ${specs.specCount} (errors ${specs.errors}, stale ${specs.stale})`, columns, specs.errors || specs.stale ? "attention" : undefined));
+    if (specs.truncated) out.push(...lines("specs: report truncated; narrow specs.roots and run ahub specs check", columns, "attention"));
+    if (specs.missingBlockHint) out.push(...lines("specs: AGENTS.md has no specs instruction block; read the covering specs before changing their paths", columns, "attention"));
+  }
   for (const pending of data.pendingRestart ?? []) out.push(...detail("pending restart", `${pending.key}: ${pending.reason}`, columns, "attention"));
   if (data.mainCheckout) out.push(...detail("main checkout", data.mainCheckout, columns, "attention"));
   for (const drift of data.agentDrift ?? []) out.push(...detail("agent CLI drift", `${drift.id} ${drift.version} ${drift.state}; last receipt ${drift.receipt}`, columns, "attention"));
@@ -532,6 +541,11 @@ function fields(value: unknown, columns: number | undefined, now: number, prefix
 export function renderQueueShow(delivery: any, columns?: number, now = Date.now()): Span[][] {
   const out = [...lines("Delivery", columns, "strong"), ...fields(delivery, columns, now)];
   if (delivery?.state === "needs_review" && delivery.id) out.push([], ...detail("resolve", `ahub queue resolve ${delivery.id} --action completed|retry|discard --reason <text>`, columns, "failure"));
+  // #1096: a failed row that no one has settled can be cleared by the person or the conductor; one a resolution already settled says what is left (nothing).
+  else if (delivery?.state === "failed" && delivery.id) {
+    if (delivery.resolvedBy) out.push([], ...detail("resolve", `already resolved by ${delivery.resolvedBy}; nothing is left to do for this row${delivery.resolvedBy === "retry" ? " (its redelivery is a separate delivery: ahub queue list)" : ""}`, columns, "muted"));
+    else out.push([], ...detail("resolve", `ahub queue resolve ${delivery.id} --action discard|completed --reason <text>  (discard to drop it, completed to acknowledge it as handled; the person or the conductor)`, columns, "failure"));
+  }
   return out;
 }
 export function renderModelsStatus(status: unknown, columns?: number, now = Date.now()): Span[][] {

package/src/cli/setup-homes.ts

@@ -1,6 +1,8 @@
 import { checkClaudeHome, claudeHomeEnvironment, type ClaudeHome, type ClaudeHomeProbe } from "./claude-homes.ts";
 import { installClaudeProfileHook } from "./claude-profile-hook.ts";
 
+const marketplaceRemovalRefusal = (home: string) => new Error(`Claude setup refused marketplace removal in ${home}; non-user plugin rows were preserved`);
+
 export interface SetupHomesPorts {
   env: NodeJS.ProcessEnv;
   packageRoot: string;
@@ -21,9 +23,11 @@ export async function setupClaudeHomes(ports: SetupHomesPorts): Promise<void> {
   for (const home of ports.homes) initial.push(await checkClaudeHome(home, ports.packageRoot, ports.env, ports.probe, undefined, true));
   for (const check of initial) {
     ports.print(`Claude home ${check.home.path}: plugin ${check.plugin.state}; hook ${check.hook.state}.`);
+    for (const notice of ("notices" in check.plugin ? check.plugin.notices : undefined) ?? []) ports.print(`${check.home.path}: ${notice}.`);
     if (check.plugin.state === "unknown" || check.hook.state === "refused") throw new Error(`Claude setup cannot safely inspect ${check.home.path}; nothing was changed`);
+    if (check.next?.blocked) throw marketplaceRemovalRefusal(check.home.path);
   }
-  for (const check of initial) if (check.next) ports.print(`${check.home.path}: ${check.next.argv.join(" ")} (${check.next.why})`);
+  for (const check of initial) if (check.next) ports.print(`${check.home.path}: ${check.next.blocked ? "setup blocked" : check.next.argv.join(" ")} (${check.next.why})`);
   if (initial.every(check => !check.next && check.hook.state === "installed")) return;
   if (!ports.yes && ports.interactive === false) throw new Error("not a terminal: nothing was changed; rerun with --yes to apply");
   if (!ports.yes && !["y", "yes"].includes((await ports.ask("Install the hub plugin and project-neutral hook in these Claude homes? [y/N] "))?.trim().toLowerCase() ?? "")) { ports.print("Claude setup was not changed."); return; }
@@ -31,11 +35,22 @@ export async function setupClaudeHomes(ports: SetupHomesPorts): Promise<void> {
   for (const check of initial) {
     let current = check;
     for (let step = 0; current.next && step < 6; step++) {
-      ports.print(`${check.home.path}: ${current.next.argv.join(" ")} (${current.next.why})`);
+      const action = current.next;
+      if (action.blocked) throw marketplaceRemovalRefusal(check.home.path);
+      ports.print(`${check.home.path}: ${action.argv.join(" ")} (${action.why})`);
       ports.current?.();
-      if (await ports.run(current.next.argv, claudeHomeEnvironment(check.home, ports.env)) !== 0) throw new Error(`Claude plugin setup failed for ${check.home.path}; no later home was changed`);
+      if (action.argv[2] === "marketplace" && action.argv[3] === "remove") {
+        const fresh = await checkClaudeHome({ ...check.home, exists: true }, ports.packageRoot, ports.env, ports.probe, undefined, true);
+        if (fresh.plugin.state === "unknown") throw new Error(`Claude plugin inventory is unavailable for ${check.home.path}`);
+        if (fresh.next?.blocked) throw marketplaceRemovalRefusal(check.home.path);
+        if (JSON.stringify(fresh.next?.argv) !== JSON.stringify(action.argv)) { current = fresh; continue; }
+        current = fresh;
+        ports.current?.();
+      }
+      if (await ports.run(action.argv, claudeHomeEnvironment(check.home, ports.env)) !== 0) throw new Error(`Claude plugin setup failed for ${check.home.path}; no later home was changed`);
       current = await checkClaudeHome({ ...check.home, exists: true }, ports.packageRoot, ports.env, ports.probe, undefined, true);
       if (current.plugin.state === "unknown") throw new Error(`Claude plugin inventory is unavailable for ${check.home.path}`);
+      if (current.next?.blocked) throw marketplaceRemovalRefusal(check.home.path);
     }
     if (current.next) throw new Error(`Claude setup exceeded six plugin steps for ${check.home.path}`);
     ports.current?.();

package/src/cli/specs.ts

@@ -0,0 +1,150 @@
+import { chmodSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { SpecsEngine, stampFrontmatter, type SpecsConfig, type SpecsStampRow } from "../hub/specs.ts";
+import { terminalText } from "./console-state.ts";
+import { editJsonText } from "./init-settings.ts";
+
+export interface SpecsOutput { out(line: string): void; error(line: string): void }
+const output: SpecsOutput = { out: line => console.log(line), error: line => console.error(line) };
+
+/** Read-only repository inspection: no daemon connection or stamp mutation. */
+export function runSpecs(args: readonly string[], root: string, config: SpecsConfig, io: SpecsOutput = output): number {
+  const [command, ...rest] = args;
+  const usage = "usage: ahub specs list [--json] | check [--require-fresh] [--base <ref>] [--json] | covers <file...>";
+  if (!["list", "check", "covers"].includes(command ?? "")) { io.error(usage); return 1; }
+  let json = false, requireFresh = false, base: string | undefined;
+  const paths: string[] = [];
+  for (let index = 0; index < rest.length; index++) {
+    const arg = rest[index]!;
+    if (arg === "--json" && command !== "covers" && !json) json = true;
+    else if (arg === "--require-fresh" && command === "check" && !requireFresh) requireFresh = true;
+    else if (arg === "--base" && command === "check" && base === undefined) {
+      base = rest[++index];
+      if (!base || base.startsWith("-")) { io.error("specs: --base needs a Git reference; name a commit or branch"); return 1; }
+    } else if (command === "covers" && !arg.startsWith("-")) paths.push(arg);
+    else { io.error(usage); return 1; }
+  }
+  if (command === "covers" && !paths.length) { io.error(usage); return 1; }
+  try {
+    const engine = new SpecsEngine(root, config);
+    if (command === "list" || command === "covers") {
+      const report = command === "list" ? engine.list() : engine.covers(paths);
+      if (json) io.out(JSON.stringify(report));
+      else {
+        for (const spec of report.specs) io.out(terminalText(`${spec.id} (${spec.path}): ${spec.title}`));
+        for (const item of report.items) io.error(terminalText(`specs: ${item.severity} ${item.code}: ${item.message}; ${item.nextSteps}`));
+        if (report.truncated) io.error("specs: scan truncated; narrow specs.roots and run ahub specs check again");
+      }
+      return report.errors ? 1 : 0;
+    }
+    const report = engine.check({ ...(base === undefined ? {} : { base }), requireFresh });
+    if (json) io.out(JSON.stringify(report));
+    else if (report.specCount || report.freshness.length || report.items.length || report.truncated) {
+      for (const item of report.items) io.out(terminalText(`specs: ${item.severity} ${item.code}: ${item.message}; ${item.nextSteps}`));
+      for (const row of report.freshness) if (row.state === "stale") {
+        io.out(terminalText(`specs: ${row.path}: stale (${row.commitsSince ?? "unknown"} source commits${row.dirty ? "; uncommitted source changes" : ""})`));
+      }
+      if (report.truncated) io.out("specs: scan truncated; narrow specs.roots and run ahub specs check again");
+      io.out(`specs: ${report.specCount} specs, ${report.errors} errors, ${report.warnings} warnings, ${report.stale} stale`);
+    }
+    return report.errors || requireFresh && report.stale ? 1 : 0;
+  } catch (error) {
+    io.error(terminalText(`specs: ${error instanceof Error ? error.message : "inspection unavailable"}; check the repository and specs configuration, then run ahub specs check again`));
+    return 1;
+  }
+}
+
+interface PreparedStamp { path: string; absolute: string; original: Buffer; next: Buffer; mode: number }
+/** The new bytes for every file a stamp would change, made without writing; a string is the reason one could not be made. A stamps file takes all of its entries in one write. */
+function prepareStamps(root: string, rows: readonly SpecsStampRow[]): PreparedStamp[] | string {
+  const byFile = new Map<string, SpecsStampRow[]>();
+  for (const row of rows) byFile.set(row.path, [...(byFile.get(row.path) ?? []), row]);
+  const files: PreparedStamp[] = [];
+  for (const [path, group] of byFile) {
+    const absolute = resolve(root, path), original = readFileSync(absolute), mode = statSync(absolute).mode & 0o777; // the file keeps its own permissions
+    if (group[0]!.kind === "stamps-file") {
+      let text = original.toString("utf8");
+      for (const row of group) text = editJsonText(text, ["documents", row.document!, "verifiedAgainst"], row.to);
+      JSON.parse(text); // the edit must still be the JSON the engine reads
+      files.push({ path, absolute, original, next: Buffer.from(text, "utf8"), mode });
+    } else {
+      const done = stampFrontmatter(original.toString("latin1"), group[0]!.to);
+      if (!done.ok) return `${path}: ${done.error}`;
+      files.push({ path, absolute, original, next: Buffer.from(done.text, "latin1"), mode });
+    }
+  }
+  return files;
+}
+
+/** What `ahub specs stamp` needs from its surroundings: whether a person is at a terminal, and a yes/no question to ask them. Tests pass their own. */
+export interface SpecsStampTerminal { isTTY: boolean; ask(question: string): Promise<boolean> }
+
+const STAMP_USAGE = "usage: ahub specs stamp <id-or-document>... [--yes]";
+const writeAtomic = (path: string, bytes: Buffer, mode: number): void => {
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temporary, bytes, { mode, flag: "wx" });
+  chmodSync(temporary, mode);
+  renameSync(temporary, path);
+};
+
+/**
+ * #1064 T3: `ahub specs stamp <id-or-document>... [--yes]`, a person's record that they reviewed a spec or stamped document against HEAD.
+ * Person only, three ways: main.ts refuses any agent identity before this runs (the command is `console` class, and `--live-test` delegation is refused for it too), this refuses
+ * a run without a terminal even with --yes, and nothing here talks to the hub. It shows what it would write (the old and new stamp per document), asks, and then changes only the
+ * `verified-against` line of a spec, or the `verifiedAgainst` value of a stamps-file entry, keeping every other byte. It is refused, writing nothing, while a document's covered
+ * paths have uncommitted changes. The new stamp is the full HEAD SHA, so it is an ancestor of HEAD.
+ */
+export async function runSpecsStamp(args: readonly string[], root: string, config: SpecsConfig, terminal: SpecsStampTerminal, io: SpecsOutput = output): Promise<number> {
+  const targets: string[] = [];
+  let yes = false;
+  for (const arg of args) {
+    if (arg === "--yes" && !yes) yes = true;
+    else if (!arg.startsWith("-")) targets.push(arg);
+    else { io.error(STAMP_USAGE); return 1; }
+  }
+  if (!targets.length) { io.error(STAMP_USAGE); return 1; }
+  if (!terminal.isTTY) {
+    io.error("specs: stamping records a person's review and needs a terminal, even with --yes; run ahub specs stamp in your own terminal, or in ahub console; nothing was written");
+    return 1;
+  }
+  try {
+    const engine = new SpecsEngine(root, config);
+    const plan = engine.stampPlan(targets);
+    if (plan.refusals.length) {
+      for (const refusal of plan.refusals) io.error(terminalText(`specs: ${refusal}`));
+      io.error("specs: nothing was written");
+      return 1;
+    }
+    const short = (sha: string | null) => sha === null ? "none" : sha.slice(0, 12);
+    io.out(terminalText(`stamp against HEAD ${plan.head.slice(0, 12)}:`));
+    for (const row of plan.rows) io.out(terminalText(`  ${row.path}${row.document ? ` (${row.document})` : ""}: ${short(row.from)} -> ${short(row.to)}${row.from === row.to ? " (already this stamp)" : ""}`));
+    const changing = plan.rows.filter(row => row.from !== row.to);
+    if (!changing.length) { io.out("specs: every named document already holds this stamp; nothing to write"); return 0; }
+    // Every file's new bytes are made before anyone is asked, so a document that cannot be stamped is refused up front and no file is written for it, and what the person approves is
+    // exactly what is written. `original` is what the new bytes were made from.
+    const prepared = prepareStamps(engine.rootPath, changing);
+    if (typeof prepared === "string") { io.error(terminalText(`specs: ${prepared}; nothing was written`)); return 1; }
+    if (!yes && !await terminal.ask(`Record that you reviewed ${changing.length === 1 ? "this document" : `these ${changing.length} documents`} against HEAD ${plan.head.slice(0, 12)}?`)) {
+      io.out("specs: not stamped; nothing was written");
+      return 0;
+    }
+    // The answer may have taken minutes. Revalidate what the person was shown before any write: HEAD, every target's plan row (so a covered path that became dirty is refused), and each
+    // file's bytes. Any difference refuses the whole run.
+    const again = engine.stampPlan(targets);
+    const changed = again.refusals.length ? again.refusals.map(refusal => `specs: ${refusal}`)
+      : again.head !== plan.head || JSON.stringify(again.rows) !== JSON.stringify(plan.rows) ? ["specs: HEAD or a document's covered paths changed while you were deciding"]
+      : prepared.filter(file => !readFileSync(file.absolute).equals(file.original)).map(file => `specs: ${file.path} changed while you were deciding`);
+    if (changed.length) {
+      for (const line of changed) io.error(terminalText(line));
+      io.error("specs: nothing was written; review the current state and run ahub specs stamp again");
+      return 1;
+    }
+    // ponytail: a change in the instant between this recheck and the renames below is not seen; each rename is atomic and the diff is the person's to review before committing, so there is no lock. A lock file if two people stamp one checkout.
+    for (const file of prepared) writeAtomic(file.absolute, file.next, file.mode);
+    io.out(`specs: stamped ${changing.length} document${changing.length === 1 ? "" : "s"} at ${plan.head.slice(0, 12)}; review the diff and commit it`);
+    return 0;
+  } catch (error) {
+    io.error(terminalText(`specs: ${error instanceof Error ? error.message : "stamping unavailable"}; check the repository and specs configuration, then run ahub specs stamp again`));
+    return 1;
+  }
+}

package/src/cli/study-output.ts

@@ -69,3 +69,59 @@ export function renderStudyReceipt(op: string, receipt: unknown, columns?: numbe
   if (op === "draft" || op === "revise") out.push(blank, [s(`nothing is dispatched until you approve: ahub study approve ${r?.id} ${count(r?.revision)}`, "muted")]);
   return out;
 }
+
+const ATTEMPT_TONE: Record<string, Tone | undefined> = { succeeded: undefined, running: undefined, declared: "muted", failed: "attention", cancelled: "attention", unknown: "attention" };
+const PROVENANCE_TONE: Record<string, Tone | undefined> = { declared: "muted", unknown: "attention" };
+const clip = (text: string, max = 48) => text.length > max ? `${text.slice(0, max - 1)}…` : text;
+/** A value cell: the value and where it came from, so a declared number never reads as an observed one. Anything the hub withheld prints as the hub wrote it. */
+const sourced = (cell: any): [string, string] => {
+  if (cell === "[pii]") return ["[pii]", "withheld"];
+  if (!cell || typeof cell !== "object" || !("provenance" in cell)) return ["-", "unknown"];
+  const value = cell.value === null || cell.value === undefined ? "-" : typeof cell.value === "object" ? "(structured)" : String(cell.value);
+  return [clip(value), String(cell.provenance)];
+};
+
+/**
+ * `ahub study experiments`: the attempts of one campaign, one attempt, or one baseline/variant comparison, as the hub's `Tasks.experimentShow` returned them. Pure: it reads no file, runs
+ * no command and asks for no protocol text. Every row says whether it is approved, post-hoc or predeclared and that a repeat is not an independent reproduction; every value says where it
+ * came from; failed, cancelled and unknown attempts are in the counts. A private record arrives from the hub already as ids, counts and states.
+ */
+export function renderExperiments(view: unknown, columns?: number): Span[][] {
+  const v = view as any, attempts = list(v?.attempts), counts = v?.counts ?? {}, statuses = counts.statuses ?? {};
+  const out: Span[][] = [...heading(`Experiment attempts (${attempts.length} of ${count(counts.all)} in this campaign${v?.nextCursor !== undefined ? ", more follow" : ""})`, columns)];
+  const order = ["declared", "running", "succeeded", "failed", "cancelled", "unknown"];
+  out.push(...pair("all", order.map(name => `${name} ${count(statuses[name])}`).join(", "), columns, 8, "muted"));
+  if (v?.comparison) {
+    const c = v.comparison, compat = c.projection?.compatibility;
+    out.push(blank, ...heading("Comparison", columns));
+    if (c.projection === "[pii]") out.push(...pair("plan", `${String(c.planHash).slice(0, 12)}: withheld (a private source or record)`, columns, 8, "attention"));
+    else {
+      out.push(...pair("plan", String(c.planHash).slice(0, 12), columns, 8));
+      out.push(...pair("compatible", compat?.compatible ? "yes, under this plan" : `no: ${compat?.field ?? "unknown"} differs (${compat?.side ?? "pair"}); shown, not ranked together`, columns, 8, compat?.compatible ? undefined : "attention"));
+    }
+    out.push(...pair("approved", c.approved ? "both protocols bound to a person's approval" : "not both approved", columns, 8, c.approved ? undefined : "attention"));
+    out.push(...pair("pair", `${c.baselineAttemptId} (baseline) and ${c.variantAttemptId} (variant)`, columns, 8, "muted"));
+  }
+  if (!attempts.length) return [...out, blank, [s("no attempts recorded", "muted")]];
+  out.push(blank, ...grid(["ATTEMPT", "TASK", "PHASE", "STATUS", "APPROVAL", "POST-HOC", "NOTE"], attempts.map((row: any) => [
+    s(row.id, "issueRef"), s(`#${count(row.taskId)}`, "taskRef"), s(row.phase), s(row.status, ATTEMPT_TONE[row.status]), s(row.approval, row.approval === "approved" ? undefined : "attention"), s(row.postHoc, row.postHoc === "post-hoc" ? "attention" : "muted"),
+    s([row.private ? "private, details withheld" : "", row.retryOf ? `retry of ${row.retryOf}` : "", row.reproducesAttemptId ? `repeat of ${row.reproducesAttemptId}, not independent` : "", row.eventsComplete === false ? "events continue" : ""].filter(Boolean).join("; ") || "-", "muted"),
+  ]), columns));
+  for (const row of attempts) {
+    if (row.private) continue;
+    const declared = row.evidence?.declared, metrics = list(declared?.metrics), measured = list(row.evidence?.measured), runners = list(row.evidence?.runnerAttested);
+    const lines: [string, string, string][] = [];
+    for (const metric of metrics) { const [value, from] = sourced(metric.latest); lines.push([`${metric.name} (${metric.unit})`, value, from]); }
+    for (const field of ["exitStatus", "startedAt"]) { const [value, from] = sourced(declared?.[field]); if (value !== "-") lines.push([field, value, from]); }
+    for (const m of measured) for (const [field, cell] of Object.entries(m.values ?? {})) { const [value, from] = sourced(cell); lines.push([`${field} (${m.source})`, value, from]); }
+    for (const r of runners) { const [value, from] = sourced(r.sealing); lines.push([`sealed (runner ${clip(String(r.runner), 24)})`, value, from]); const [match, matchFrom] = sourced(r.codeMatch); lines.push(["code matches protocol", match, matchFrom]); }
+    const [sealed, sealedFrom] = sourced(declared?.sealed);
+    if (!runners.length) lines.push(["sealed", sealed, `${sealedFrom}; isolation unverified`]);
+    if (!lines.length) continue;
+    out.push(blank, ...heading(`Evidence of ${row.id}`, columns), ...grid(["FIELD", "VALUE", "SOURCE"], lines.map(([field, value, from]) => [s(field), s(value), s(from, PROVENANCE_TONE[from] ?? (from.startsWith("declared") ? "muted" : undefined))]), columns));
+  }
+  out.push(blank, [s(`declared values are an agent's own words; only host-observed, runner-attested or person-attested rows are evidence, and none of them proves the science. A repeat is never an independent reproduction.`, "muted")]);
+  if (v?.nextCursor !== undefined) out.push([s(`more attempts: ahub study experiments --campaign <id> --after ${v.nextCursor}`, "muted")]);
+  for (const row of attempts) if (row.eventsComplete === false && row.nextEventCursor !== undefined) out.push([s(`more events of ${row.id}: ahub study experiments --attempt ${row.id} --events-after ${row.nextEventCursor}; the values above come from the events shown so far`, "attention")]);
+  return out;
+}