@staix/agent-hub 0.25.0 → 0.27.0

package/src/cli/recovery-package.ts

@@ -1,9 +1,10 @@
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { createRequire } from "node:module";
 import { hubHome, realPath } from "../hub/project.ts";
+import { Registry } from "../hub/registry.ts";
 
 export type CommandResult = { code: number; stdout: string; stderr: string };
 export type RunCommand = (args: string[], options?: { cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number }) => Promise<CommandResult>;
@@ -109,7 +110,11 @@ export function verifyPackage(root: string, version: string, options: { ownDepen
 export function recoveryPackageOptions(kind: "restart" | "upgrade", root: string): { ownDependencies?: boolean; dependencyRoot?: string } {
   if (kind === "restart") return { ownDependencies: true };
   if (kind !== "upgrade") throw new Error("unsupported recovery package kind");
-  const canonical = realPath(root), dependencyRoot = resolve(canonical, "../../..");
+  const canonical = realPath(root);
+  // Project captures own the exact dependency and keep the registry install separate below this version.
+  if (canonical === root && /^source-[a-f0-9]{64}$/.test(basename(canonical)) && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(basename(dirname(canonical)))
+    && basename(dirname(dirname(canonical))) === "releases") return { ownDependencies: true };
+  const dependencyRoot = resolve(canonical, "../../..");
   if (canonical !== root || canonical !== join(dependencyRoot, "node_modules", "@staix", "agent-hub")) throw new Error("invalid staged recovery package path");
   return { dependencyRoot };
 }
@@ -122,6 +127,82 @@ export function verifyRecoveryTarget(kind: "restart" | "upgrade", root: string,
   return verifyPackage(root, version, recoveryPackageOptions(kind, root));
 }
 
+const RUNTIME_ASSETS = ["src", "plugins", "templates", ".claude-plugin", "package.json", "README.md", "LICENSE", "CHANGELOG.md"] as const;
+function runtimeDirectory(directory: string): void {
+  let info;
+  try { info = lstatSync(directory); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    try { mkdirSync(directory, { mode: 0o700 }); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+    info = lstatSync(directory);
+  }
+  if (info.isSymbolicLink() || !info.isDirectory()) throw new Error("runtime cache must contain real directories");
+}
+
+/** Preserve the exact bounded asset set; legacy coordinators need not have a plugin identity manifest. */
+function preserveRuntimeAssets(sourceRoot: string, destination: string, expectedDigest: string, version?: string): { root: string; digest: string } {
+  const digest = (root: string, ownDependencies = false) => version === undefined
+    ? packageDigest(root, { ownDependencies }) : verifyPackage(root, version, { ownDependencies });
+  if (digest(sourceRoot) !== expectedDigest) throw new Error("source package changed before preservation");
+  runtimeDirectory(dirname(destination));
+  const cached = () => {
+    let info;
+    try { info = lstatSync(destination); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; }
+    if (info.isSymbolicLink() || !info.isDirectory() || digest(destination, true) !== expectedDigest)
+      throw new Error(version === undefined ? "preserved source package changed" : "preserved runtime changed; refusing it");
+    return { root: realPath(destination), digest: expectedDigest };
+  };
+  const previous = cached(); if (previous) return previous;
+  const temporary = join(dirname(destination), `.source-${randomUUID()}`);
+  mkdirSync(temporary, { mode: 0o700 });
+  try {
+    for (const name of RUNTIME_ASSETS) cpSync(join(sourceRoot, name), join(temporary, name), { recursive: true, dereference: false });
+    preserveRuntimeDependencies(sourceRoot, temporary);
+    if (digest(temporary, true) !== expectedDigest || digest(sourceRoot) !== expectedDigest)
+      throw new Error("source package changed while being preserved");
+    try { renameSync(temporary, destination); }
+    catch (error) {
+      if (!["EEXIST", "ENOTEMPTY"].includes((error as NodeJS.ErrnoException).code ?? "")) throw error;
+      // A concurrent publisher may have won. Validate its complete bytes; never remove its directory.
+      const winner = cached(); if (winner) return winner;
+      throw error;
+    }
+    const published = cached();
+    if (!published) throw new Error("preserved runtime vanished after publication");
+    return published;
+  } finally { rmSync(temporary, { recursive: true, force: true }); }
+}
+
+/** Capture a verified package identity and its exact first-party dependency, never a node_modules tree. */
+export function preserveRuntimePackage(sourceRoot: string, destination: string, expectedDigest: string): { root: string; digest: string; version: string } {
+  const version = exactVersion(JSON.parse(readFileSync(join(sourceRoot, "package.json"), "utf8")).version);
+  return { ...preserveRuntimeAssets(sourceRoot, destination, expectedDigest, version), version };
+}
+
+/** Retained legacy coordinators keep their digest-only contract and still require their own exact dependency. */
+export function preserveRuntimeSource(sourceRoot: string, destination: string, expectedDigest: string): string {
+  preserveRuntimeAssets(sourceRoot, destination, expectedDigest);
+  return destination; // Legacy receipts retain the path spelling their coordinator already bound.
+}
+
+/** Ordinary startup preserves the invoking package, including unpublished builds, below its version namespace. */
+export function stageCurrentRuntime(sourceRoot: string, version: string, home = hubHome(), registry?: Registry): { root: string; digest: string; version: string } {
+  exactVersion(version);
+  const digest = verifyPackage(sourceRoot, version);
+  const owner = registry ?? new Registry(join(home, "registry.db"));
+  try {
+    if (realPath(owner.path) !== realPath(join(home, "registry.db"))) throw new Error("runtime capture registry belongs to another home");
+    return owner.runtimeCaptureLocked(() => {
+      mkdirSync(home, { recursive: true, mode: 0o700 });
+      const releases = join(realPath(home), "releases"); runtimeDirectory(releases);
+      const versionRoot = join(releases, version); runtimeDirectory(versionRoot);
+      return preserveRuntimePackage(sourceRoot, join(versionRoot, `source-${digest}`), digest);
+    });
+  } finally { if (!registry) owner.close(); }
+}
+
 export async function registryRelease(version: string, run: RunCommand = runCommand): Promise<{ version: string; integrity: string }> {
   exactVersion(version);
   const result = await run(["npm", "view", `@staix/agent-hub@${version}`, "version", "dist.integrity", "--json"], { timeoutMs: 30_000 });
@@ -151,10 +232,18 @@ export function newerVersion(a: string, b: string): boolean {
 }
 
 /** Stage outside the mutable global install; retain successful versions for recovery. */
-export async function stageRelease(version: string, integrity: string, run: RunCommand = runCommand, home = hubHome()): Promise<{ root: string; digest: string }> {
+export async function stageRelease(version: string, integrity: string, run: RunCommand = runCommand, home = hubHome(), project = false): Promise<{ root: string; digest: string }> {
   exactVersion(version);
   const base = join(home, "releases");
-  const destination = join(base, version);
+  const versionRoot = join(base, version);
+  // Ordinary startup can create this parent before an unstaged legacy receipt resumes.
+  // An actual legacy install (even a damaged one) must retain its original path and validation.
+  if (!project && existsSync(versionRoot) && !existsSync(join(versionRoot, "verified.json")) && !existsSync(join(versionRoot, "node_modules"))) {
+    runtimeDirectory(versionRoot);
+    if (!readdirSync(versionRoot).every(name => name === "registry" || /^source-[a-f0-9]{64}$/.test(name))) throw new Error("cached release state is unknown; refusing it");
+    project = true;
+  }
+  const destination = project ? join(versionRoot, "registry") : versionRoot;
   const root = join(destination, "node_modules/@staix/agent-hub");
   if (existsSync(destination)) {
     const saved = JSON.parse(readFileSync(join(destination, "verified.json"), "utf8"));
@@ -163,6 +252,7 @@ export async function stageRelease(version: string, integrity: string, run: RunC
     return { root, digest };
   }
   mkdirSync(base, { recursive: true, mode: 0o700 });
+  if (project) runtimeDirectory(join(base, version));
   const temporary = join(base, `.stage-${randomUUID()}`);
   mkdirSync(temporary, { mode: 0o700 });
   try {

package/src/cli/reset.ts

@@ -1,4 +1,5 @@
 import { constants, Database } from "bun:sqlite";
+import { assertHubDbCompatible, openHubDatabase } from "../hub/db-schema.ts";
 import { randomUUID } from "node:crypto";
 import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -50,21 +51,30 @@ const isEnvelope = (v: unknown) => isObject(v) && typeof v.id === "string";
 /** Valid JSON of the wrong shape is damage as well: the journal refuses it on every open, so the message says so. */
 const shaped = (ok: boolean, what: string) => { if (!ok) throw new Error(`invalid delivery journal: ${what} has the wrong shape`); };
 
+/** The existing quiet archive preview owns its raw URI handle and sets its one bounded timeout at open. */
+function quietResetDatabase(file: string): Database {
+  const db = new Database(`file:${file.replace(/[%?#]/g, (c) => `%${c.charCodeAt(0).toString(16)}`)}?immutable=1`, constants.SQLITE_OPEN_READONLY | constants.SQLITE_OPEN_URI);
+  try {
+    db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    return db;
+  } catch (error) { db.close(); throw error; }
+}
+
 /** 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: 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;
+  assertHubDbCompatible(file); // A normal readonly guard sees WAL metadata before the quiet preview may use immutable.
   // A read-only open of a WAL database creates hub.db-wal and -shm when the last writer's close removed them (Linux),
   // and fails without them on macOS. Without them no writer is mid-transaction, so `immutable` reads hub.db alone and
   // writes nothing. ponytail: a -wal left without its -shm (deleted by hand) is ignored then, and commits still in
   // it go unlisted; open plainly in that corner if it ever matters. SQLITE_OPEN_URI is passed because Linux builds do
   // not parse `file:` names by default (the name then fails as a plain path).
   const quiet = !existsSync(`${file}-wal`) || !existsSync(`${file}-shm`);
-  const db = quiet ? new Database(`file:${file.replace(/[%?#]/g, (c) => `%${c.charCodeAt(0).toString(16)}`)}?immutable=1`, constants.SQLITE_OPEN_READONLY | constants.SQLITE_OPEN_URI) : new Database(file, { readonly: true });
+  const db = quiet ? quietResetDatabase(file) : openHubDatabase(file, { readonly: true });
   try {
-    db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
     const has = (table: string) => !!db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table);
     const peers = (table: string) => has(table) ? (db.query(`SELECT peer FROM ${table} ORDER BY peer`).all() as { peer: string }[]).map((row) => row.peer) : [];
     plan.budgetPauses = peers("budget_pauses");
@@ -120,6 +130,7 @@ export function resetLines(plan: ResetPlan): string[] {
  */
 export function resetRuntime(stateDir: string, project: Project): { settled: string[]; plan: ResetPlan; stale: string[] } {
   const file = join(stateDir, "hub.db");
+  assertHubDbCompatible(file); // Refuse before journal settlement or any direct runtime-state mutation.
   const plan = planReset(stateDir, project.id);
   const settled: string[] = [];
   if (existsSync(file)) {
@@ -135,9 +146,8 @@ export function resetRuntime(stateDir: string, project: Project): { settled: str
       }
       bus.setManualPaused([]);
     } finally { bus.closeJournal(); }
-    const db = new Database(file);
+    const db = openHubDatabase(file);
     try {
-      db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
       db.transaction(() => {
         for (const table of ["budget_pauses", "conductor_holds"]) {
           if (db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table)) db.run(`DELETE FROM ${table}`);

package/src/cli/runtime-version-warning.ts

@@ -0,0 +1,28 @@
+import type { DoctorCheck } from "./output.ts";
+
+const VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?(?:\+[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/;
+const version = (value: unknown): string | undefined => typeof value === "string" && value.length <= 64 && VERSION.exec(value)?.[0] === value ? value : undefined;
+
+/** Authenticated daemon status and the existing plugin inventory only. Suggestions never run an update. */
+export function runtimeVersionWarnings(daemonVersion: unknown, cliVersion: unknown, pluginVersion: unknown): DoctorCheck[] {
+  const running = version(daemonVersion), cli = version(cliVersion), plugin = version(pluginVersion);
+  const rows: DoctorCheck[] = [];
+  const unknown = (name: string, detail: string) => rows.push({ section: "Hub", level: "unknown", name, detail });
+  if (!running) {
+    unknown("runtime version comparison", "authenticated daemon version unavailable; CLI and plugin age are unknown");
+    return rows;
+  }
+  let cliOlder = false;
+  if (!cli) unknown("CLI versus daemon", "this CLI version is unavailable; its age relative to the daemon is unknown");
+  else try {
+    cliOlder = Bun.semver.order(cli, running) < 0;
+    if (cliOlder) rows.push({ section: "Hub", level: "warn", name: "CLI versus daemon",
+      detail: `running daemon ${running} is newer than this CLI ${cli}; update separately: bun add --global @staix/agent-hub@${running}` });
+  } catch { unknown("CLI versus daemon", "CLI and daemon versions could not be compared"); }
+  if (!plugin) unknown("plugin versus daemon", "installed plugin version unavailable; run ahub setup with an updated CLI to inspect it");
+  else try {
+    if (Bun.semver.order(plugin, running) < 0) rows.push({ section: "Hub", level: "warn", name: "plugin versus daemon",
+      detail: `running daemon ${running} is newer than installed plugin ${plugin}; run ahub setup${cliOlder ? " after the CLI update" : " with a CLI at least as new as the daemon"}` });
+  } catch { unknown("plugin versus daemon", "plugin and daemon versions could not be compared"); }
+  return rows;
+}

package/src/cli/start-agents-run.ts

@@ -0,0 +1,125 @@
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ControlClient } from "../hub/control-client.ts";
+import { readAutonomyDefaults, writeMachineStartAgents } from "../hub/autonomy-defaults.ts";
+import { configRefusal } from "../hub/config-trust.ts";
+import { START_AGENTS_DEFAULT, parseStartAgents } from "../hub/start-agents.ts";
+import { MAX_COMMAND_MS } from "./terminal-recovery.ts";
+
+/**
+ * #608 (agent-hub#1040): the default agent set `ahub up` starts. Every start goes through the console `peer_start`, so it is
+ * `hubStart`'s start (the peer's own start mode, the terminal provider, `already` for an attached peer, the manual command for
+ * a refusal) and never a headless fallback. Nothing here reaches the daemon except that one message per listed peer.
+ */
+export interface StartRequester { request(message: Record<string, unknown>, timeoutMs?: number): Promise<Record<string, any>> }
+
+/** One printable line per agent. A refusal carries the hub's own reason, which already names the manual command. */
+export function startLine(id: string, reply: Record<string, any>): string {
+  if (reply.ok === true) {
+    if (reply.already === true) return `${id}: already attached`;
+    return `${id}: started${reply.mode ? ` ${reply.mode}` : ""}${reply.opened ? ` (${reply.opened})` : ""}${reply.mode === "tui" ? ", it attaches when its TUI is ready" : ""}`;
+  }
+  return `${id}: not started: ${String(reply.error ?? "the hub refused")}`;
+}
+
+/** Asks for every listed peer at once and returns the lines in list order. A refusal or a failed request never stops the others. */
+export async function startDefaultAgents(client: StartRequester, agents: readonly string[]): Promise<string[]> {
+  return Promise.all(agents.map(async id => {
+    try { return startLine(id, await client.request({ t: "peer_start", peer: id }, MAX_COMMAND_MS + 5_000)); }
+    catch (error) { return `${id}: not started: ${(error as Error).message}`; }
+  }));
+}
+
+/** The list `ahub up` starts: the project's machine-local value, else this machine's `ahub setup` choice, else claude and codex. */
+export function effectiveStartAgents(projectRoot: string, projectValue: readonly string[], home: string, roots: readonly string[] = []): { agents: string[]; source: "project" | "machine" | "default"; notice?: string } {
+  let set = false;
+  try {
+    const file = join(projectRoot, ".agenthub", "config.local.json");
+    if (existsSync(file)) { const doc = JSON.parse(readFileSync(file, "utf8")); set = Array.isArray(doc?.start?.agents); }
+  } catch { set = false; }
+  if (set) return { agents: [...projectValue], source: "project" };
+  const machine = readAutonomyDefaults(home, roots);
+  if (machine.startAgents) return { agents: [...machine.startAgents], source: "machine" };
+  return { agents: [...START_AGENTS_DEFAULT], source: "default", ...(machine.notice ? { notice: machine.notice } : {}) };
+}
+
+/** The dashboard manager's and `ahub up`'s common path: a console connection to the running hub, then the set. */
+export async function startProjectAgents(project: { root: string; stateDir: string }, agents: readonly string[], connect?: () => Promise<ControlClient>): Promise<string[]> {
+  if (!agents.length) return [];
+  let client: ControlClient;
+  try { client = await (connect ?? (() => ControlClient.connect(project.stateDir, { role: "console", projectRoot: project.root }, 5_000)))(); }
+  catch (error) { return agents.map(id => `${id}: not started: the hub did not answer (${(error as Error).message})`); }
+  try { return await startDefaultAgents(client, agents); }
+  finally { client.close(); }
+}
+
+export interface SetupStartPorts {
+  home: string;
+  roots: readonly string[];
+  /** `--agents <a,b>`, already split from argv, or undefined. */
+  flag?: string;
+  yes: boolean;
+  ask?: (prompt: string) => Promise<string | null>;
+  print: (line: string) => void;
+}
+const show = (agents: readonly string[]) => agents.length ? agents.join(", ") : "none";
+
+/**
+ * `ahub setup`'s one question (#608): which agents `ahub up` starts. `--agents` answers it, `--yes` takes this machine's current
+ * choice (or claude and codex), a terminal is asked once (an answer already on this machine is shown, not asked again), and a
+ * run with no terminal and neither flag keeps the default and says so. Writes only `start.agents` of `~/.agenthub/defaults.json`.
+ * Returns the refusal text for a bad `--agents`, else undefined.
+ */
+export async function setupStartAgents(ports: SetupStartPorts): Promise<string | undefined> {
+  const held = readAutonomyDefaults(ports.home, ports.roots);
+  const current = held.startAgents ?? [...START_AGENTS_DEFAULT];
+  const save = (agents: string[]): void => {
+    try { writeMachineStartAgents(ports.home, agents, held.fingerprint, ports.roots); ports.print(`Agents ahub up starts: ${show(agents)} (saved in this machine's defaults; a new project inherits it at ahub init).`); }
+    catch { ports.print("Agents ahub up starts: not saved, because this machine's defaults.json is unsafe or changed; the default stays (claude, codex)."); }
+  };
+  if (ports.flag !== undefined) {
+    let agents: string[];
+    try { agents = parseStartAgents(ports.flag); } catch (error) { return (error as Error).message; }
+    save(agents); return undefined;
+  }
+  if (ports.yes) { if (held.startAgents) ports.print(`Agents ahub up starts: ${show(current)} (kept).`); else save(current); return undefined; }
+  if (held.startAgents) { ports.print(`Agents ahub up starts: ${show(current)} (change it with ahub setup --agents <a,b> or ahub settings set start.agents <a,b>).`); return undefined; }
+  if (!ports.ask) { ports.print(`Agents ahub up starts: ${show(current)} (the default; no terminal to ask in, so pass --agents <a,b> to choose).`); return undefined; }
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const answer = await ports.ask(`Agents to start with ahub up [${show(current)}] (comma list, "none" for no agent): `);
+    if (answer === null || !answer.trim()) { save(current); return undefined; }
+    try { save(parseStartAgents(answer)); return undefined; } catch (error) { ports.print((error as Error).message); }
+  }
+  ports.print(`Agents ahub up starts: ${show(current)} (no valid answer; the default stays).`);
+  return undefined;
+}
+
+/**
+ * `ahub init` of a new project (#608): copies this machine's chosen set into the project's `.agenthub/config.local.json`, as the
+ * autonomy preset is inherited. Only when `ahub setup` chose one, never over a value the project already has, and never into a
+ * file git tracks. Person-only by its caller; returns the lines to print.
+ */
+export function inheritMachineStart(projectRoot: string, home: string, roots: readonly string[]): string[] {
+  const machine = readAutonomyDefaults(home, roots);
+  if (machine.notice) return [machine.notice];
+  if (!machine.startAgents) return [];
+  const file = join(projectRoot, ".agenthub", "config.local.json");
+  let doc: Record<string, unknown> = {};
+  try {
+    if (existsSync(file)) {
+      const parsed: unknown = JSON.parse(readFileSync(file, "utf8"));
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return ["start.agents not copied: .agenthub/config.local.json is not a JSON object"];
+      doc = parsed as Record<string, unknown>;
+    }
+  } catch { return ["start.agents not copied: .agenthub/config.local.json could not be read"]; }
+  const start = doc.start;
+  if (start !== undefined && (typeof start !== "object" || start === null || Array.isArray(start))) return ["start.agents not copied: start in .agenthub/config.local.json is not an object"];
+  if (start && (start as Record<string, unknown>).agents !== undefined) return [];
+  const why = configRefusal(projectRoot, "config.local.json");
+  if (why) return [`start.agents not copied: ${why}`];
+  const text = `${JSON.stringify({ ...doc, start: { ...(start as object | undefined), agents: machine.startAgents } }, null, 2)}\n`;
+  const temporary = `${file}.${process.pid}.tmp`;
+  try { writeFileSync(temporary, text, { mode: 0o600, flag: "wx" }); renameSync(temporary, file); }
+  catch (error) { try { unlinkSync(temporary); } catch { /* nothing was written */ } return [`start.agents not copied: ${(error as NodeJS.ErrnoException).code ?? "write failed"}`]; }
+  return [`Inherited the machine's agent set for ahub up: ${show(machine.startAgents)}.`];
+}

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;
+}

package/src/cli/study.ts

@@ -1,5 +1,5 @@
 // Argument parsing for `ahub study` (#601). Pure: argv in, one request description or a usage line out, so the I/O in main.ts stays a thin dispatcher and every form is testable without a daemon.
-export const STUDY_USAGE = "usage: ahub study draft <parent> <contract.json> | revise <id> <revision> <contract.json> | approve <id> <revision> | approve-protocol <hash> | close <id> <revision> --reason <text> | show [<id> | --after <id>] [--json] [--color=auto|always|never]";
+export const STUDY_USAGE = "usage: ahub study draft <parent> <contract.json> | revise <id> <revision> <contract.json> | approve <id> <revision> | approve-protocol <hash> | close <id> <revision> --reason <text> | show [<id> | --after <id>] | experiments (--campaign <id> [--after <n>] | --attempt <ra-id> [--events-after <n>] | --plan <hash> --baseline <ra-id> --variant <ra-id>) [--json] [--color=auto|always|never]";
 
 export type StudyRequest =
   | { op: "draft"; parentTaskId: number; file: string }
@@ -7,9 +7,10 @@ export type StudyRequest =
   | { op: "approve"; id: string; revision: number }
   | { op: "approve_protocol"; hash: string }
   | { op: "close"; id: string; revision: number; reason: string }
-  | { op: "show"; id?: string; after?: string };
+  | { op: "show"; id?: string; after?: string }
+  | { op: "experiments"; campaign?: string; attempt?: string; after?: number; eventsAfter?: number; plan?: string; baseline?: string; variant?: string };
 
-const ID = /^rc-[a-f0-9]{12}$/, INT = /^[1-9]\d{0,8}$/;
+const ID = /^rc-[a-f0-9]{12}$/, INT = /^[1-9]\d{0,8}$/, ATTEMPT = /^ra-[a-f0-9]{12}$/, HASH = /^[a-f0-9]{64}$/, CURSOR = /^(0|[1-9]\d{0,8})$/;
 
 /** `operands` is argv with the presentation flags (`--json`, `--color=`) already removed by `splitPresentation`. `--reason` takes the rest of the words, as `task cancel --reason` does. */
 export function parseStudyArgs(operands: readonly string[]): StudyRequest | { usage: string } {
@@ -22,6 +23,28 @@ export function parseStudyArgs(operands: readonly string[]): StudyRequest | { us
     const hash = rest[0];
     return hash?.length === 64 && /^[a-f0-9]{64}$/.test(hash) ? { op: "approve_protocol", hash } : usage("a protocol hash is 64 lowercase hexadecimal characters");
   }
+  if (sub === "experiments") {
+    // Three closed forms, the ones Tasks.experimentShow takes: a campaign page, one attempt, or one comparison. A flag with no value, a repeat, a stray word or a mix is a usage error before anything is sent.
+    const names = ["--campaign", "--attempt", "--after", "--events-after", "--plan", "--baseline", "--variant"], seen = new Map<string, string>();
+    for (let at = 0; at < rest.length; at += 2) {
+      const name = rest[at], value = rest[at + 1];
+      if (name === undefined || !names.includes(name) || value === undefined || value.startsWith("--") || seen.has(name)) return usage();
+      seen.set(name, value);
+    }
+    const campaign = seen.get("--campaign"), attempt = seen.get("--attempt"), after = seen.get("--after"), eventsAfter = seen.get("--events-after"), plan = seen.get("--plan"), baseline = seen.get("--baseline"), variant = seen.get("--variant");
+    if (campaign !== undefined && !id(campaign)) return usage("a campaign id looks like rc-0123456789ab");
+    for (const [name, value] of [["--attempt", attempt], ["--baseline", baseline], ["--variant", variant]] as const) if (value !== undefined && !ATTEMPT.test(value)) return usage(`${name} takes an attempt id like ra-0123456789ab`);
+    if (plan !== undefined && !HASH.test(plan)) return usage("a plan hash is 64 lowercase hexadecimal characters");
+    if (after !== undefined && !CURSOR.test(after)) return usage("--after takes the cursor a previous page printed");
+    if (eventsAfter !== undefined && !CURSOR.test(eventsAfter)) return usage("--events-after takes the event cursor a previous page printed");
+    const comparison = plan !== undefined || baseline !== undefined || variant !== undefined;
+    if (comparison) return plan !== undefined && baseline !== undefined && variant !== undefined && campaign === undefined && attempt === undefined && after === undefined && eventsAfter === undefined
+      ? { op: "experiments", plan, baseline, variant } : usage("a comparison needs --plan, --baseline and --variant and nothing else");
+    if ((campaign === undefined) === (attempt === undefined)) return usage("give --campaign or --attempt");
+    if (attempt !== undefined && after !== undefined) return usage("--after pages a campaign, not one attempt; --events-after pages the events of one attempt");
+    if (campaign !== undefined && eventsAfter !== undefined) return usage("--events-after pages the events of one attempt, not a campaign");
+    return attempt !== undefined ? { op: "experiments", attempt, ...(eventsAfter === undefined ? {} : { eventsAfter: Number(eventsAfter) }) } : { op: "experiments", campaign: campaign!, ...(after === undefined ? {} : { after: Number(after) }) };
+  }
   if (sub === "show") {
     // `--after <id>` continues a list from the cursor a previous page printed; it has no meaning with an id, which shows one campaign.
     if (rest[0] === "--after") {

package/src/cli/task-output.ts

@@ -120,6 +120,11 @@ function taskBlock(task: any, columns: number | undefined, now: number, detail:
   const refText = [refs.repo, refs.branch ? `branch ${refs.branch}` : "", refs.commit ? `commit ${short(refs.commit)}` : ""].filter(Boolean).join(", ");
   if (refText) out.push(blank, ...pair("refs", refText, columns, w, undefined, "  "));
   out.push(...bullets("ref paths", list(refs.paths), columns, undefined, "  "));
+  if (!isStub(task) && task?.approval) {
+    const approval = task.approval;
+    const binding = `head ${approval.head ?? "unknown"}; latest ${approval.latestHead ?? "unknown"}; ${approval.mismatch ? "HEAD MISMATCH, approval is stale" : approval.current ? "current" : "not current, review required"}`;
+    out.push(...pair("approval", binding, columns, w, approval.current ? "success" : "attention", "  "));
+  }
   const plan = planBlock(task?.plan, columns);
   if (plan.length) out.push(blank, [s("plan", "muted")], ...plan);
   const sdlc = task?.sdlc;

package/src/cli/upgrade-interactive.ts

@@ -36,8 +36,8 @@ export interface UpgradeHost {
   apply(plan: UpgradePlan, interrupted: () => boolean): Promise<RecoveryOperation>;
   /** End one attached agent now: close a TUI agent's terminal, or ask the hub to stop a headless one. One line of outcome. */
   endPeer(planned: PlannedProject, peer: RecoveryPeer): Promise<string>;
-  /** The operation that holds the machine's recovery lock. */
-  lock(): string | undefined;
+  /** This selected project's hold, or an authoritative retained legacy machine hold. A reset may name another project. */
+  lock(projectRoot?: string): string | undefined;
   read(id: string): RecoveryOperation;
   runner(id: string): number | "unknown" | undefined;
   live(op: RecoveryOperation): Promise<Record<string, Inspection | undefined>>;
@@ -215,13 +215,13 @@ export async function endAgents(host: UpgradeHost, io: ScreenIO, endable: { plan
 
 /** `ahub reset` for one project: the scope, its dry run, a confirmation, then the reset itself. */
 export async function resetFlow(host: UpgradeHost, io: ScreenIO, projects: { id: string; root: string }[]): Promise<void> {
-  if (host.lock()) return human(io, "an operation holds the recovery lock; cancel or end it before a reset");
   let project = projects[0];
   if (projects.length > 1) {
     projects.forEach((p, i) => human(io, `  ${i + 1}  ${p.id}  ${p.root}`));
     project = projects[Number(await ask(io, "Reset which project? [number, Enter: none] ")) - 1];
   }
   if (!project) return human(io, "nothing was reset");
+  if (host.lock(project.root)) return human(io, "an operation holds the recovery lock; cancel or end it before a reset");
   const scope = ((await ask(io, "[r] runtime reset (deliveries, holds, pauses, session pointers)  [a] full reset (archive the state directory)  [Enter] none: ")) ?? "").toLowerCase();
   if (scope !== "r" && scope !== "a") return human(io, "nothing was reset");
   const reset = [host.entry, "--project", project.root, "reset", ...(scope === "a" ? ["--all"] : [])];
@@ -323,7 +323,7 @@ export async function planScreen(host: UpgradeHost, io: ScreenIO): Promise<void>
     if (io.presentation) emit(io, renderPlan(plan, host.version, io.presentation, planLines(plan, host.version)));
     else for (const line of planLines(plan, host.version)) human(io, line);
     const blocked = plan.blockers.length > 0 || plan.projects.some((p) => p.blockers.length > 0);
-    if (!plan.projects.length) human(io, plan.kind === "upgrade" ? `no hub is running, so nothing is carried over: install with \`bun add -g @staix/agent-hub@${plan.version}\`, then \`ahub setup\`` : "this project's hub is not running: `ahub up` starts it");
+    if (!plan.projects.length) human(io, plan.kind === "upgrade" && plan.scope === undefined ? `no hub is running, so nothing is carried over: install with \`bun add -g @staix/agent-hub@${plan.version}\`, then \`ahub setup\`` : "this project's hub is not running: `ahub up` starts it");
     const endable = plan.projects.flatMap((p) => p.source.peers.filter((peer) => ["tui", "headless"].includes(peerKind(p, peer))).map((peer) => ({ planned: p, peer })));
     const keys = [...(blocked ? [] : ["[a] apply"]), "[r] refresh", ...(endable.length ? ["[k] end agents"] : []), "[j] plan as JSON", ...(plan.projects.length ? ["[x] reset a project's hub"] : []), "[q] quit"];
     const preferred = "r"; // Enter never closes terminals, stops a hub, resumes or reattaches implicitly.