@staix/agent-hub 0.24.0 → 0.26.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/schedule-output.ts

@@ -3,22 +3,26 @@
 import { blank, grid, heading, pair, s } from "./sdlc-output.ts";
 import { moment } from "./sdlc-output.ts";
 import type { Span, Tone } from "./console-state.ts";
+import { schedulePeriodText, scheduleWhen } from "../hub/schedules.ts";
 
 const list = (value: unknown): any[] => Array.isArray(value) ? value : [];
 const TONE: Record<string, Tone | undefined> = { due: "attention", waiting: "attention", held: "attention", paused: "muted", scheduled: undefined };
 const WHEN: Record<string, string> = { scheduled: "next", due: "due now", waiting: "due, waiting for its task to close", held: "due, held (the hub is stopping or recovering)", paused: "paused" };
 
 /** The next run, as the person reads it: a paused schedule says so and what it would have been. */
-export const nextText = (row: any, now: number): string =>
-  row?.state === "paused" ? `paused (would be ${moment(row.next, now)})` : row?.state === "scheduled" ? moment(row.next, now) : WHEN[row?.state] ?? "unknown";
+export const nextText = (row: any, now: number): string => {
+  // A calendar schedule reads its next run in its own zone, with the relative time after it; an `every` schedule keeps the UTC form.
+  const at = (instant: unknown) => row?.zone && typeof instant === "number" && Number.isFinite(instant) ? `${scheduleWhen(row, instant)} (${moment(instant, now).replace(/^.*?\((.*)\)$/, "$1")})` : moment(instant, now);
+  return row?.state === "paused" ? `paused (would be ${at(row.next)})` : row?.state === "scheduled" ? at(row.next) : WHEN[row?.state] ?? "unknown";
+};
 
 /** `ahub schedule list`: one row per configured schedule with its next run. */
 export function renderScheduleList(rows: unknown, columns?: number, now = Date.now()): Span[][] {
   const schedules = list(rows);
   if (!schedules.length) return [[s("no schedules configured; add them under `schedules` in .agenthub/config.local.json", "muted")]];
   const out: Span[][] = [...heading(`Schedules (${schedules.length})`, columns)];
-  out.push(...grid(["ID", "EVERY", "CLASS", "QUEUE", "STATE", "NEXT RUN", "LAST RUN", "TASK"], schedules.map((row: any) => [
-    s(row.id, "issueRef"), s(row.every), s(row.class), s(row.queue), s(row.state, TONE[row.state]), s(nextText(row, now), TONE[row.state]),
+  out.push(...grid(["ID", "SCHEDULE", "CLASS", "QUEUE", "STATE", "NEXT RUN", "LAST RUN", "TASK"], schedules.map((row: any) => [
+    s(row.id, "issueRef"), s(row.cron !== undefined ? schedulePeriodText(row) : String(row.every)), s(row.class), s(row.queue), s(row.state, TONE[row.state]), s(nextText(row, now), TONE[row.state]),
     s(row.last ? moment(row.last, now) : "never", "muted"), s(row.task === undefined ? "-" : `#${row.task}`, "taskRef"),
   ]), columns));
   for (const row of schedules) {

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

@@ -0,0 +1,71 @@
+// Human output for `ahub study draft|revise|approve|approve-protocol|close|show`. Pure: the hub's parsed JSON in, spans out, no I/O. `--json` is the caller's branch and prints the same text.
+// A campaign is named by ids, revisions, states and counts. The hub already stubs private campaigns, tasks and sources; this file never asks for a question, scope, path or excerpt.
+import { blank, grid, heading, pair, s } from "./sdlc-output.ts";
+import type { Span, Tone } from "./console-state.ts";
+
+const list = (value: unknown): any[] => Array.isArray(value) ? value : [];
+const count = (value: unknown): number => typeof value === "number" && Number.isFinite(value) ? value : 0;
+const STATUS_TONE: Record<string, Tone | undefined> = { approved: undefined, draft: "attention", superseded: "muted", closed: "muted" };
+
+/** `ahub study show` with no id: one page of campaigns of this project, with the command that continues it when the hub says there is more. */
+export function renderStudyList(page: unknown, columns?: number): Span[][] {
+  const campaigns = list((page as any)?.campaigns), next = typeof (page as any)?.next === "string" ? (page as any).next as string : undefined;
+  if (!campaigns.length) return [[s("no research campaigns in this project; a planner or you draft one with `ahub study draft <parent> <contract.json>`", "muted")]];
+  const out: Span[][] = [...heading(`Research campaigns (${campaigns.length}${next ? ", more follow" : ""})`, columns)];
+  out.push(...grid(["ID", "REV", "STATUS", "PARENT", "UNITS"], campaigns.map((row: any) => [
+    s(row.id, "issueRef"), s(`r${count(row.revision)}`), s(row.status, STATUS_TONE[row.status]), s(`#${count(row.parentTaskId)}`, "taskRef"), s(count(row.unitCount)),
+  ]), columns));
+  if (next) out.push(blank, [s(`more campaigns: ahub study show --after ${next}`, "muted")]);
+  return out;
+}
+
+const SUPPORT_TONE: Record<string, Tone | undefined> = { enforceable: undefined, supported: undefined, advisory: "muted", unavailable: "attention", unsupported: "attention", unknown: "attention" };
+
+/** `ahub study show <id>`: the coverage and stop projection the hub computed. Held work is said first, with every reason. */
+export function renderStudyShow(projection: unknown, columns?: number): Span[][] {
+  const p = projection as any, units = list(p?.units), rounds = list(p?.discoveryRounds), reasons = list(p?.reasons);
+  const out: Span[][] = [...heading(`Research campaign ${p?.id ?? "?"}, revision ${count(p?.revision)}${p?.held ? ", dispatch HELD" : ""}`, columns)];
+  for (const reason of reasons) out.push(...pair("held", reason, columns, 8, "attention"));
+  if (p?.sharedPeerLedger) out.push(...pair("budget", "one run ledger is shared by the peers", columns, 8, "muted"));
+  if (rounds.length) out.push(...pair("rounds", rounds.map((round: any) => `${count(round.round)}: ${round.complete ? "discovery complete" : "discovery open"}`).join(", "), columns, 8));
+  out.push(blank);
+  if (!units.length) return [...out, [s("no units", "muted")]];
+  out.push(...grid(["UNIT", "ROUND", "TASK", "STATE", "PURPOSE", "HANDOFF", "SOURCES"], units.map((unit: any) => {
+    const handoff = unit.handoff ?? {};
+    const evidence = handoff.insufficientEvidence ? "insufficient evidence" : handoff.complete ? "complete" : handoff.present ? "incomplete" : "none";
+    const covered = list(unit.sourceIds).length;
+    const note = [unit.intentionalIndependentCheck ? "independent check" : "", list(unit.duplicateSourceIds).length ? `${list(unit.duplicateSourceIds).length} duplicated` : ""].filter(Boolean).join(", ");
+    return [s(unit.unitId, "issueRef"), s(count(unit.round)), s(unit.taskId == null ? "-" : `#${unit.taskId}`, "taskRef"), s(unit.state), s(unit.purpose), s(evidence, handoff.complete || handoff.insufficientEvidence ? undefined : "attention"),
+      s(covered ? `${list(handoff.coveredSourceIds).length}/${covered} covered${note ? `, ${note}` : ""}` : note || "-", "muted")];
+  }), columns));
+  // Every resource of a unit is shown whenever the campaign names a budget, with its support state: a limit the ledger does not carry (`null`) is a placeholder, not a reason to hide a row that says
+  // `unavailable` or `advisory`. A campaign that names no budget has nothing to say (its `tokens` row reads `unavailable` whatever the ledger is), so the hub's `budgetNamed` decides, not the values.
+  const budgeted = units.flatMap((unit: any) => Object.entries(unit.budget ?? {}).filter(([, value]: [string, any]) => value && typeof value === "object").map(([name, value]: [string, any]) => ({ unit: unit.unitId, name, value })));
+  if (budgeted.length && p?.budgetNamed === true) {
+    out.push(blank, ...heading("Budget", columns));
+    out.push(...grid(["UNIT", "RESOURCE", "SUPPORT", "USED", "LIMIT"], budgeted.map(({ unit, name, value }) => [
+      s(unit, "issueRef"), s(name), s(value.support, SUPPORT_TONE[value.support]), s(value.used === null || value.used === undefined ? "-" : value.used), s(value.limit === null || value.limit === undefined ? "-" : value.limit),
+    ]), columns));
+  }
+  return out;
+}
+
+const VERB: Record<string, string> = { draft: "drafted", revise: "drafted as the next revision", approve: "approved", close: "closed" };
+
+/** The receipt of a draft, revision, approval or close. */
+export function renderStudyReceipt(op: string, receipt: unknown, columns?: number): Span[][] {
+  const r = receipt as any, units = list(r?.units);
+  if (op === "approve_protocol") {
+    const hash = (value: unknown) => typeof value === "string" && value.length === 64 && /^[a-f0-9]{64}$/.test(value) ? value : "unknown";
+    const by = typeof r?.approvedBy === "string" && /^[a-z][a-z0-9_-]{0,63}$/.test(r.approvedBy) ? r.approvedBy : "unknown";
+    const at = typeof r?.approvedAt === "number" && Number.isFinite(r.approvedAt) && r.approvedAt >= 0 && r.approvedAt <= 8_640_000_000_000_000
+      ? new Date(r.approvedAt).toISOString().slice(0, 19).replace("T", " ") + " UTC" : "unknown";
+    return [...heading("Research protocol approval", columns), ...pair("protocol hash", hash(r?.protocolHash), columns, 16),
+      ...pair("evaluator hash", hash(r?.evaluatorHash), columns, 16), ...pair("approved by", by, columns, 16), ...pair("approved at", at, columns, 16)];
+  }
+  const out: Span[][] = [...heading(`Research campaign ${r?.id ?? "?"} revision ${count(r?.revision)} ${VERB[op] ?? op}`, columns)];
+  out.push(...pair("status", r?.status, columns, 8, STATUS_TONE[r?.status]), ...pair("parent", `#${count(r?.parentTaskId)}`, columns, 8, "taskRef"), ...pair("units", count(r?.unitCount), columns, 8));
+  if (units.length) out.push(blank, ...grid(["UNIT", "TASK", "ROUND"], units.map((unit: any) => [s(unit.unitId, "issueRef"), s(`#${count(unit.taskId)}`, "taskRef"), s(count(unit.round))]), columns));
+  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;
+}

package/src/cli/study.ts

@@ -0,0 +1,58 @@
+// 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 type StudyRequest =
+  | { op: "draft"; parentTaskId: number; file: string }
+  | { op: "revise"; id: string; revision: number; file: string }
+  | { 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 };
+
+const ID = /^rc-[a-f0-9]{12}$/, INT = /^[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 } {
+  const usage = (detail?: string) => ({ usage: detail ? `${detail}\n${STUDY_USAGE}` : STUDY_USAGE });
+  const [sub, ...rest] = operands;
+  const id = (value: string | undefined) => value !== undefined && ID.test(value) ? value : undefined;
+  const int = (value: string | undefined) => value !== undefined && INT.test(value) ? Number(value) : undefined;
+  if (sub === "approve-protocol") {
+    if (rest.length !== 1) return usage();
+    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 === "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") {
+      if (rest.length !== 2) return usage();
+      return id(rest[1]) ? { op: "show", after: rest[1]! } : usage("a campaign id looks like rc-0123456789ab");
+    }
+    if (rest.length > 1) return usage();
+    if (rest[0] === undefined) return { op: "show" };
+    return id(rest[0]) ? { op: "show", id: rest[0] } : usage("a campaign id looks like rc-0123456789ab");
+  }
+  if (sub === "draft") {
+    const parent = int(rest[0]);
+    if (parent === undefined || !rest[1] || rest.length !== 2) return usage();
+    return { op: "draft", parentTaskId: parent, file: rest[1] };
+  }
+  if (sub === "revise") {
+    const revision = int(rest[1]);
+    if (!id(rest[0]) || revision === undefined || !rest[2] || rest.length !== 3) return usage();
+    return { op: "revise", id: rest[0]!, revision, file: rest[2] };
+  }
+  if (sub === "approve") {
+    const revision = int(rest[1]);
+    if (!id(rest[0]) || revision === undefined || rest.length !== 2) return usage();
+    return { op: "approve", id: rest[0]!, revision };
+  }
+  if (sub === "close") {
+    const revision = int(rest[1]);
+    const at = rest.indexOf("--reason");
+    if (!id(rest[0]) || revision === undefined || at !== 2) return usage();
+    const reason = rest.slice(at + 1).join(" ").trim();
+    return reason ? { op: "close", id: rest[0]!, revision, reason } : usage("study close needs a reason");
+  }
+  return usage();
+}

package/src/cli/task-output.ts

@@ -104,6 +104,7 @@ function taskBlock(task: any, columns: number | undefined, now: number, detail:
     ...pair("class", dash(task?.class), columns, w, undefined, "  "), ...pair("owner", taskHolderText(task, "owner"), columns, w, undefined, "  "), ...pair("reviewer", taskHolderText(task, "reviewer"), columns, w, undefined, "  "));
   if (task?.planner !== undefined) out.push(...pair("planner", taskHolderText(task, "planner"), columns, w, undefined, "  "));
   if (task?.reserved) out.push(...pair("reserved", task.reserved, columns, w, undefined, "  "));
+  if (task?.handoffOrigin) out.push(...pair("from", `project ${task.handoffOrigin.projectId}, handed off by ${task.handoffOrigin.peer}${typeof task.handoffOrigin.task === "number" ? ` (their task #${task.handoffOrigin.task})` : ""}`, columns, w, "attention", "  "));
   out.push(...pair("after", ids(task?.deps), columns, w, undefined, "  "));
   if (typeof task?.release === "number") out.push(...pair("release", `#${task.release}`, columns, w, undefined, "  "));
   if (typeof task?.rank === "number" || typeof task?.priority === "number") out.push(...pair("planning", [typeof task.rank === "number" ? `rank ${task.rank}` : "", typeof task.priority === "number" ? `priority P${task.priority}` : "", task.pinned ? "pinned" : ""].filter(Boolean).join(", "), columns, w, undefined, "  "));
@@ -119,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.