@staix/agent-hub 0.24.0 → 0.26.0

package/src/cli/main.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { assertConductorOperationLocal, authorizeConductorOperation, authorizeConductorLaunch, issueConductorOperation, preflightConductorRecovery, retireConductorOperation } from "./conductor-recovery.ts";
+import { runtimePruneHealth } from "../hub/runtime-prune-health.ts";
 import { conductorLocalOperation, conductorOperation, OPERATIONAL_PERSON_GUIDANCE } from "../hub/operational-authority.ts";
 import { sayRecipients } from "./say-input.ts";
 import type { DeliverableRow } from "../hub/tasks.ts";
@@ -16,7 +17,7 @@ import { readInstanceRoleConfig, readInstanceConfig, type InstanceRoleConfig } f
 import { staleInstanceKey } from "../hub/roster.ts";
 import { parseConfiguredAcpArguments, runConfiguredAcpEntry, requireActiveConfiguredAcp } from "./configured-acp-entry.ts";
 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, nativeDoctorRecoveryIdentity, nativeDoctorOptionalProbes } from "../adapters/registry.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 { matchesPolicy } from "../hub/path-policy.ts";
@@ -28,6 +29,10 @@ import { renderScheduleChange, renderScheduleList, renderScheduleRun } from "./s
 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 { renderHandoffReceipt, renderHandoffs } from "./handoff-output.ts";
+import { parseHandoffArgs } from "./handoff-args.ts";
 import { terminalText } from "./console-state.ts";
 import { parseSettingsEditArgs, runSettingsEdit, SETTINGS_EDIT_USAGE } from "./settings-edit.ts";
 import { autonomyEnvironment, runAutonomy } from "./autonomy.ts";
@@ -37,6 +42,7 @@ import { offlineAutonomyStatus } from "./autonomy-offline.ts";
 import { autonomyHomeStatus, usedClaudeHomes } from "./autonomy-homes.ts";
 import { discoverClaudeHomes } from "./claude-homes.ts";
 import { setupClaudeHomes } from "./setup-homes.ts";
+import { registerAconPlugin } from "./acon-register.ts";
 import { petView, readPet, renderPet } from "./pet.ts";
 import { startPetWindow, closePetWindow } from "../pet/window.ts";
 import { loadPetConfig, savePetPalette } from "./pet-config.ts";
@@ -51,7 +57,7 @@ import { parseSettingText, settingDef, settingText, undoableDef, type SettingRow
 import { startModeOf } from "../hub/start-mode.ts";
 import { currentRouting, OVERLAY_FILE, parseOverlay, parseRouting, routingText, type Routing, type RoutingOverlay } from "../hub/routing.ts";
 import { spawn, spawnSync } from "node:child_process";
-import { chmodSync, closeSync, constants, existsSync, fstatSync, openSync, readFileSync, readSync, renameSync, writeFileSync } from "node:fs";
+import { chmodSync, closeSync, constants, existsSync, fstatSync, openSync, readFileSync, readSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
@@ -79,11 +85,13 @@ import { childEnv, personEnv } from "../hub/child-process.ts";
 import { abortRecovery, createOperation, disposeRecovery, recordRecoveryDelegation, repairedFreshSession, reattachRecovery, liveProjects, nextChoices, nextActionsText, publicOperation, recoveryCommand, registeredProjects, runRecovery, type RecoveryOperation, type Inspection } from "./upgrade.ts";
 import { endPlannedPeer, makeRecoveryDriver, makeUpgradePlan, preserveSource } from "./upgrade-runtime.ts";
 import { exactVersion, latestRelease, newerVersion } from "./recovery-package.ts";
+import { runtimeVersionWarnings } from "./runtime-version-warning.ts";
 import { operationScreen, planScreen, type ScreenIO, type UpgradeHost } from "./upgrade-interactive.ts";
 import { readRecoveryPresentationFlags } from "./upgrade-presentation-flags.ts";
 import { renderOperation, renderBlocked, renderSummary, type RecoveryPresentationOptions } from "./upgrade-presentation.ts";
 import { renderBudgetResult, renderRecoveryStatus, renderUpgradePlan } from "./upgrade-output.ts";
 import { recordTerminalLaunch, prepareTerminalLaunch, registerTerminalLaunch, type TerminalPeer } from "./terminal-recovery.ts";
+import { effectiveStartAgents, inheritMachineStart, setupStartAgents, startProjectAgents } from "./start-agents-run.ts";
 import { ensureMlx, inspectMlx, stopMlx } from "../models/mlx.ts";
 import { setupOllamaModel } from "./models-setup.ts";
 
@@ -137,6 +145,16 @@ while (argv[0] === "--project" || argv[0] === "--live-test") {
     if (!selector || selector.startsWith("--")) fail("--project needs a path or project ID");
   }
 }
+// Upgrade accepts its documented command-local selector as well as the leading global form.
+if (argv[0] === "upgrade") {
+  const at = argv.indexOf("--project", 1);
+  if (at >= 0) {
+    if (selector !== undefined || argv.indexOf("--project", at + 1) >= 0) fail("--project may appear only once");
+    selector = argv[at + 1];
+    if (!selector || selector.startsWith("--")) fail("--project needs a path or project ID");
+    argv.splice(at, 2);
+  }
+}
 const [given = "help", ...rest] = argv;
 let selected: { root: string; stateDir: string };
 try {
@@ -380,10 +398,10 @@ function matchingProject(): Project | undefined {
   finally { registry.close(); }
 }
 const hubManifest = () => !!readControl(stateDir) || existsSync(join(stateDir, "hub.pid"));
-/** A reset is never part of an upgrade or recovery: any operation holding the machine's lock refuses it, whatever
+/** A reset is never part of an upgrade or recovery: this project's or a legacy machine hold refuses it, whatever
  *  AGENTHUB_RECOVERY_OPERATION says (assertLifecycleAvailable lets that operation's own processes through). */
 function resetLockFree(): void {
-  const owner = recoveryLock();
+  const owner = recoveryLock(undefined, cwd);
   if (owner) throw new Error(`${activeOperation(owner)}; nothing was changed`);
 }
 /** A manifest whose daemon is alive or uncertain, by inspectProject's rule; a crashed daemon's leftovers do not count. */
@@ -675,11 +693,11 @@ async function onTerminal(screens: (io: ScreenIO) => Promise<void>, presentation
 }
 
 function upgradeHost(kind: "restart" | "upgrade", version: string): UpgradeHost {
-  const scope = kind === "restart" ? cwd : undefined;
+  const scope = cwd;
   return {
     plan: () => makeUpgradePlan(kind, version, scope),
     apply: async (plan, interrupted) => {
-      assertLifecycleAvailable();
+      assertLifecycleAvailable(cwd);
       const current = await makeUpgradePlan(kind, plan.version, scope);
       if (current.fingerprint !== plan.fingerprint) throw new Error("the plan changed during review; review it again");
       // The check above takes seconds: a Ctrl+C in that time is still a no.
@@ -688,7 +706,7 @@ function upgradeHost(kind: "restart" | "upgrade", version: string): UpgradeHost
       spawnRecovery(operation, true);
       return operation;
     },
-    lock: recoveryLock,
+    lock: (projectRoot = cwd) => recoveryLock(undefined, projectRoot),
     read: (id) => readOperation<RecoveryOperation>(id),
     runner: recoveryRunner,
     live: (op) => liveProjects(op, makeRecoveryDriver(undefined, delegatedPeer, undefined, conductorPeer).inspect),
@@ -704,8 +722,7 @@ function upgradeHost(kind: "restart" | "upgrade", version: string): UpgradeHost
 async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
   const display = recoveryDisplay();
   const { one, rest } = takeFlags(display.args, ["--to"], []);
-  if (rest.some((a) => !["--dry-run", "--yes"].includes(a)) || (kind === "restart" && one["--to"])) fail("usage: ahub upgrade [--to <version>] [--dry-run] [--yes] | ahub restart [--dry-run] [--yes]");
-  if (kind === "upgrade" && selector) fail("upgrade changes the shared package/plugin; omit --project to review all affected running projects");
+  if (rest.some((a) => !["--dry-run", "--yes"].includes(a)) || (kind === "restart" && one["--to"])) fail("usage: ahub upgrade [--project <path|id>] [--to <version>] [--dry-run] [--yes] | ahub restart [--dry-run] [--yes]");
   const yes = rest.includes("--yes"), dry = rest.includes("--dry-run") || (display.json && !yes);
   // #272: on a terminal, with neither flag, the plan is reviewed, applied and followed in one session.
   const interactive = !dry && !yes && humanRecovery(display.json);
@@ -720,7 +737,7 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
   // An older CLI must not coordinate a newer target (docs/operations.md): the target's own coordinator takes over.
   if (conductorPeer && kind === "upgrade" && newerVersion(to!, VERSION)) fail("a supporting target coordinator is required; the person runs it in ahub console or a terminal");
   if (kind === "upgrade" && newerVersion(to!, VERSION) && process.env.AGENTHUB_UPGRADE_HANDOVER !== "1") {
-    const argv = ["x", "--package", `@staix/agent-hub@${to}`, "ahub", ...liveTestArgs, "upgrade", "--to", to!, ...rest, ...display.flags, ...(dry && !rest.includes("--dry-run") ? ["--dry-run"] : [])];
+    const argv = ["x", "--package", `@staix/agent-hub@${to}`, "ahub", "--project", cwd, ...liveTestArgs, "upgrade", "--to", to!, ...rest, ...display.flags, ...(dry && !rest.includes("--dry-run") ? ["--dry-run"] : [])];
     console.error(`ahub: ${to} is newer than this CLI (${VERSION}), so its own coordinator runs the upgrade: bun ${argv.join(" ")}`);
     if (interactive) {
       const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -738,7 +755,7 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
   }
   if (kind === "upgrade") console.error("ahub: Kimi now defaults to its own TUI (pull-only) in projects without peers.kimi.start_mode. To keep ACP: ahub settings set peers.kimi.start_mode headless");
   if (interactive) return onTerminal((io) => planScreen(upgradeHost(kind, to ?? VERSION), io), display.options);
-  const plan = await makeUpgradePlan(kind, to ?? VERSION, kind === "restart" ? cwd : undefined, undefined, conductorPeer);
+  const plan = await makeUpgradePlan(kind, to ?? VERSION, cwd, undefined, conductorPeer);
   if (conductorPeer) await preflightConductorRecovery(plan, conductorPeer);
   const jsonApply = display.json && yes && !dry;
   // #814: a person reading a pipe or a dry run gets the plan screen's rows, with every blocker, reconnect-only session and
@@ -752,7 +769,7 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
   if (display.json) for (const blocker of blockers) console.error(`ahub: blocker: ${blocker}`);
   if (dry) return;
   if (blockers.length) { if (jsonApply) console.log(JSON.stringify(plan, null, 2)); fail(conductorPeer ? "conductor recovery cannot prove this plan; no runtime was changed; the person runs it in ahub console or a terminal" : "plan has blockers; no runtime was changed"); }
-  assertLifecycleAvailable();
+  assertLifecycleAvailable(cwd);
   if (!yes) {
     if (!process.stdin.isTTY) fail("review --dry-run and use --yes in non-interactive sessions");
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -760,14 +777,14 @@ async function upgrade(kind: "restart" | "upgrade"): Promise<void> {
       if (!/^(y|yes)$/i.test((await rl.question("Apply this project list and restore its sessions? [y/N] ")).trim())) return;
     } finally { rl.close(); }
   }
-  const current = await makeUpgradePlan(kind, plan.version, kind === "restart" ? cwd : undefined, undefined, conductorPeer);
+  const current = await makeUpgradePlan(kind, plan.version, cwd, undefined, conductorPeer);
   if (current.fingerprint !== plan.fingerprint) fail("plan changed during review; run the command again");
   const routingDefaults = conductorPeer ? await preflightConductorRecovery(plan, conductorPeer) : undefined;
   const sourceRoot = preserveSource(plan);
   let operation: RecoveryOperation;
   if (conductorPeer) {
     const id = randomUUID();
-    const pending: RecoveryOperation = { schema: 1, id, plan, sourceRoot, createdAt: Date.now(), updatedAt: Date.now(), phase: "pending", step: "stage", ...(routingDefaults ? { conductorRoutingDefaults: routingDefaults } : {}), projects: plan.projects.map(row => ({ id: row.project.id, phase: "pending", terminals: {} })) };
+    const pending: RecoveryOperation = { schema: 3, id, plan, sourceRoot, createdAt: Date.now(), updatedAt: Date.now(), phase: "pending", step: "stage", ...(routingDefaults ? { conductorRoutingDefaults: routingDefaults } : {}), projects: plan.projects.map(row => ({ id: row.project.id, phase: "pending", terminals: {} })) };
     const target = await makeRecoveryDriver().stage(pending);
     pending.targetRoot = target.root; pending.targetDigest = target.digest; pending.targetFeatures = target.targetFeatures;
     await issueConductorOperation(pending, conductorPeer);
@@ -863,9 +880,9 @@ const commands: Record<string, () => Promise<void> | void> = {
       printRecovery(renderBlocked(result, nextChoices(result, undefined, live), display.options));
       return;
     }
-    // #272: without an id, the operation that holds the machine's lock; bare on a terminal, its screen.
+    // #272: without an id, this project's hold (or a retained legacy machine hold); bare on a terminal, its screen.
     const named = !!given && operationIdPattern.test(given);
-    const id = named ? given : recoveryLock();
+    const id = named ? given : recoveryLock(undefined, cwd);
     const rest = named || given === undefined ? more : [given, ...more];
     if (action === undefined && humanRecovery(display.json)) {
       if (!id) return console.log("no recovery operation is open");
@@ -1004,27 +1021,42 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 
   manager: async () => {
-    const manager = await startManager({ lifecycle });
+    // #608: the dashboard's "start" counts as the person's `ahub up`: the manager starts the project's default agent set after the hub is ready.
+    const manager = await startManager({ lifecycle, afterStart: async (project) => {
+      const chosen = effectiveStartAgents(project.root, loadConfig(project.root).start.agents, hubHome(), [project.root]);
+      return startProjectAgents(project, chosen.agents);
+    } });
     for (const signal of ["SIGINT", "SIGTERM"] as const) process.on(signal, () => void manager.stop());
     await manager.stopped;
   },
 
   setup: async () => {
     recoveryLauncherCurrent?.();
-    assertLifecycleAvailable();
+    assertLifecycleAvailable(cwd);
     const root = join(import.meta.dir, "..", "..");
+    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;
     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(); },
+        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; },
       });
+      // #608: the one question about the default agent set, after the Claude homes and before doctor.
+      if (!recoveryLauncherCurrent && !delegatedPeer) {
+        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(); }
+    // #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}`);
     if (recoveryLauncherCurrent) recoveryLauncherCurrent();
     else await commands.doctor!();
   },
@@ -1042,7 +1074,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       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");
     }
-    assertLifecycleAvailable();
+    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"));
     const project = registeredProject();
@@ -1051,6 +1083,8 @@ const commands: Record<string, () => Promise<void> | void> = {
       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 (!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;
     if (examples.length) console.log(terminalText("Example checks (advisory):\n" + examples.map(example => "- " + example).join("\n")));
@@ -1078,12 +1112,20 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (recoveryLauncherCurrent) { recoveryLauncherCurrent(); return; }
     try { if (loadPetConfig(cwd).window) console.log(await startPetWindow(stateDir, cwd)); }
     catch { console.error("Pet window was not started; run ahub pet --window to inspect it."); }
+    // #608: the default agent set, only for a person's own `ahub up` (never an agent's, a live test's, or an upgrade or recovery relaunch, which set AGENTHUB_RECOVERY_OPERATION).
+    if (!args.includes("--no-agents") && !liveTest && caller.role === "console" && identity.role === "console" && !process.env.AGENTHUB_RECOVERY_OPERATION) {
+      try {
+        const chosen = effectiveStartAgents(cwd, loadConfig(cwd).start.agents, hubHome(), [cwd]);
+        if (chosen.notice) console.error(chosen.notice);
+        for (const line of await startProjectAgents({ root: cwd, stateDir }, chosen.agents)) console.log(terminalText(line));
+      } catch (error) { console.error(`default agents were not started: ${terminalText((error as Error).message)}`); }
+    }
     if (process.stdin.isTTY && process.stdout.isTTY && !args.includes("--no-console")) await runConsole({ client: await connect(), cwd, stateDir, liveTest });
   },
 
   ...Object.fromEntries(BUILTIN_CLI_ENTRIES.map(entry => [entry.command, async () => {
     // Preserve the original guard before native effects; previews remain read-only and precede this guard.
-    if (entry.lifecycleAdmission && !args.includes("--print-command") && !args.includes("--dry-run")) assertLifecycleAvailable();
+    if (entry.lifecycleAdmission && !args.includes("--print-command") && !args.includes("--dry-run")) assertLifecycleAvailable(cwd);
     const nativeConnect = async () => {
       const hub = await connectLaunch();
       try { if (selectedInstance) { requirePeerInstances(hub.features); requireActiveInstance((await hub.request({ t: "status" })).status, selectedInstance); } return hub; }
@@ -1457,6 +1499,40 @@ const commands: Record<string, () => Promise<void> | void> = {
     return showToolText(data => renderScheduleChange(sub as "pause" | "resume", data, present.columns, Date.now()), await taskOp(sub === "pause" ? "schedule_pause" : "schedule_resume", { id }), present);
   },
 
+  study: async () => {
+    // #601: research campaigns. The hub keeps every campaign and decides every rule (Tasks.study*); this process parses argv, reads the contract file the person names and asks.
+    // Person only for draft, revise, approve and close (a console control op the daemon refuses on any other connection, and `study` has no agent form in classifyPeerCommand besides the
+    // read-only `show`); an agent drafts through the hub_study_* tools. `show` is a read: for a private campaign, task or source the hub sends ids, counts and states only.
+    const split = splitPresentation(args, { edges: true });
+    const present = outputOptions(split.flags); // before any request: an invalid --color must refuse before a mutation is sent
+    const parsed = parseStudyArgs(split.operands);
+    if ("usage" in parsed) return fail(parsed.usage);
+    const contract = (file: string): unknown => {
+      // One descriptor decides everything: opened non-blocking and without following a final symlink (a FIFO would otherwise block the open), checked to be a regular file with fstat, and
+      // read for at most the cap plus one byte, so a file that grows or is replaced after the check, or a device that reports size zero, cannot exhaust memory or hang this process.
+      const cap = 64 * 1024;
+      let text: string;
+      try {
+        const fd = openSync(resolve(invokedFrom, file), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+          if (!fstatSync(fd).isFile()) return fail("the contract file is not a regular file");
+          const bytes = Buffer.alloc(cap + 1); let got = 0;
+          while (got < bytes.length) { const n = readSync(fd, bytes, got, bytes.length - got, null); if (!n) break; got += n; }
+          if (got > cap) return fail("the contract file is over 64 KiB");
+          text = bytes.subarray(0, got).toString("utf8");
+        } finally { closeSync(fd); }
+      }
+      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 === "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) }
+      : parsed.op === "approve_protocol" ? { hash: parsed.hash }
+      : parsed.op === "approve" ? { id: parsed.id, revision: parsed.revision } : { id: parsed.id, revision: parsed.revision, reason: parsed.reason };
+    return showToolText(data => renderStudyReceipt(parsed.op, data, present.columns), await taskOp(`study_${parsed.op}`, request, false, undefined, parsed.op === "approve" ? 90_000 : undefined), present);
+  },
+
   capabilities: async () => {
     // #445 C1: what each attached peer offers and which of it you share. Person only, like `learn`: `capabilities` has no entry in classifyPeerCommand, so an agent shell is refused before this runs and the daemon refuses any caller but the person again. It lists; it never calls anything.
     const split = splitPresentation(args);
@@ -1530,6 +1606,11 @@ const commands: Record<string, () => Promise<void> | void> = {
       if (!selection.label) fail("GitHub import requires --label");
       return console.log(await taskOp("github_import", selection));
     }
+    if (args[0] === "--handoffs" || args.includes("--handoffs")) {
+      // #604: what this project handed to other projects and the last state each reported (read-only).
+      const options = outputOptions();
+      return showToolText(data => renderHandoffs(data, options.columns), await taskOp("hub_task_handoffs", {}), options);
+    }
     const options = outputOptions();
     const { one, rest } = takeFlags(args, ["--release", "--release-id"], []);
     if (one["--release"] !== undefined && !one["--release"].trim() || one["--release"] !== undefined && one["--release-id"] !== undefined || one["--release-id"] !== undefined && !/^[1-9]\d*$/.test(one["--release-id"])) fail("choose --release <nonempty name> or --release-id <positive id>");
@@ -1773,7 +1854,16 @@ const commands: Record<string, () => Promise<void> | void> = {
       appendRecords(project.id, [{ schema: RESEARCH_SCHEMA, kind: "label", project: projectKey(project.id), task: id, createdAt: record!.createdAt!, label, at: new Date().toISOString(), ...(identity.role === "tools" ? { by: identity.peer } : {}) }]);
       return console.log(`task #${id} (approved ${record!.approvedAt}) labelled ${label} in the research records`);
     }
-    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>");
+    if (sub === "handoff") {
+      // #604: work that belongs to ANOTHER project that runs agent-hub goes onto that project's board. The person's form (a console command: the classifier gives an agent `console` for it, and an
+      // agent uses hub_task_handoff); the hub resolves the target, asks its daemon and records the answer. Nothing is queued: a target that is not running is named with the action.
+      const present = outputOptions(splitPresentation(rest, { valueFlags: ["--project", "--path", "--issue", "--task", "--detail"], edges: true }).flags);
+      const parsed = parseHandoffArgs(splitPresentation(rest, { valueFlags: ["--project", "--path", "--issue", "--task", "--detail"], edges: true }).operands);
+      if ("usage" in parsed) return fail(parsed.usage);
+      const text = await taskOp("hub_task_handoff", { ...parsed });
+      return showToolText(data => renderHandoffReceipt(data, present.columns), text, present);
+    }
+    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");
@@ -1903,7 +1993,8 @@ const commands: Record<string, () => Promise<void> | void> = {
     try {
       const environment = autonomyEnvironment(process.env, !!process.stdin.isTTY), home = hubHome();
       if (args.includes("--all-projects")) {
-        assertLifecycleAvailable();
+        assertLifecycleAvailable(cwd);
+        for (const project of registry.list()) assertLifecycleAvailable(project.root);
         await runAllProjectAutonomy(args, { home, environment, projects: registry.list(),
           prepare: (project, enabled) => prepareAutonomyProject(project, environment, enabled, registry),
           ask: async prompt => rl ? rl.question(prompt) : null, print: line => console.log(terminalText(line)),
@@ -1938,7 +2029,7 @@ const commands: Record<string, () => Promise<void> | void> = {
         contextLines: [...(defaults.notice ? [defaults.notice] : []), "On/off also changes this machine's autonomy default for new projects; --all-projects applies the change to every registered project."],
         confirmPrompt: "Apply this project's preset and this machine's autonomy default? [y/N] ",
         beforeApply: action => {
-          assertLifecycleAvailable();
+          assertLifecycleAvailable(cwd);
           if (action === "off" && defaults.fingerprint === "untrusted") console.log("Unsafe machine defaults are already ignored; their file was left unchanged.");
           else writeAutonomyDefaults(home, action === "on", defaults.fingerprint, roots);
           console.log(`Machine autonomy default: ${action}.`);
@@ -2494,7 +2585,7 @@ const commands: Record<string, () => Promise<void> | void> = {
         throw new Error(holder?.instanceId?.startsWith("reset-") ? `another ahub reset of this project is running (pid ${holder.pid}); nothing was reset` : "a hub started after the stop; nothing was reset, run ahub reset again");
       }
       if (liveManifest()) throw new Error("a hub started after the stop; nothing was reset, run ahub reset again");
-      // An upgrade or recovery that took the machine's lock after the first check must not run beside the reset.
+      // A recovery that took this project's hold after the first check must not run beside its reset.
       resetLockFree();
       if (all) {
         let archived: string;
@@ -2579,6 +2670,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     const row = (ok: boolean | undefined, name: string, detail: string) => { checks.push(nativeDoctorCheck(ok, name, detail)); };
 
     try {
+      for (const check of runtimePruneHealth()) row(check.ok, check.name, check.detail);
       const catalog = loadRoleCatalog(cwd);
       for (const error of catalog.errors) row(false, "catalog role", `${error.id}: ${error.reason}`);
       try {
@@ -2590,11 +2682,13 @@ const commands: Record<string, () => Promise<void> | void> = {
         row(!!v, bin, v ?? "not found on PATH");
       }
       const up = await healthy();
+      let daemonVersion: unknown;
       row(up, "ahub daemon", up ? readControl(stateDir)!.url : "not running (ahub up)");
       if (up) {
         const hub = await connect();
         try {
           const { status } = await hub.request({ t: "status" });
+          daemonVersion = status.version; // Authenticated reply, never the unauthenticated disk manifest.
           const pending = Object.values(status.peers as Record<string, PeerRow>).reduce((n, peer) => n + (peer.needsReview ?? 0), 0);
           row(!status.deliveryError && pending === 0, "delivery recovery", status.deliveryError ?? (pending ? `${pending} deliveries need review; run ahub queue list` : "journal healthy; no deliveries need review"));
           // #285 AC10: where Kimi's number comes from, and whether the hub can trust it right now. An older hub answers without `kimiSource`: no row, not a failure.
@@ -2610,6 +2704,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       }
       const plugin = pluginState(parseList<InstalledPlugin>(spawnSync(DOCTOR_PLUGIN_PROBE.command, [...DOCTOR_PLUGIN_PROBE.argv], { encoding: "utf8" }).stdout ?? ""), join(import.meta.dir, "..", ".."));
       row(plugin.state === "current", DOCTOR_PLUGIN_PROBE.name, plugin.state === "missing" ? "missing: run ahub setup" : plugin.state === "current" ? `agent-hub@agent-hub ${plugin.version}` : `agent-hub@agent-hub is stale (${plugin.why}): run ahub setup`);
+      if (up) checks.push(...runtimeVersionWarnings(daemonVersion, VERSION, plugin.state === "missing" ? undefined : plugin.version));
 
       const config = loadConfig(cwd);
       row(!config.ignored, "config", config.ignored ? `${config.ignored.join("; ")} (move them to .agenthub/config.local.json)` : "no machine-local field ignored");
@@ -2658,11 +2753,11 @@ const commands: Record<string, () => Promise<void> | void> = {
       let memoryLibraryReady = false;
       try { assertAgentMemVersion({ name: "@staix/agent-mem", version: AGENT_MEM_VERSION }); memoryLibraryReady = true; } catch { /* report the failed exact pin without opening a store */ }
       row(memoryLibraryReady, "memory library", memoryLibraryReady ? `amem ${AGENT_MEM_VERSION}; in-process, no claude-mem worker` : "installed amem does not match the exact dependency pin");
-      const bridge = spawnSync("dot", ["ai", "memory", "status"], { encoding: "utf8" });
-      const out = bridge.error ? "" : bridge.stdout.replace(/\x1b\[[0-9;]*m/g, "");
+      // #1008: memory capture is agent-mem's own setup state, read as structured data (`amem setup <tool> --json`, a preview that writes nothing), never dotfiles text. The caller's
+      // identity is NOT scrubbed: agent-mem screens a plan for an agent, and a refusal reads as unknown here instead of being laundered into a person's answer.
       for (const tool of DOCTOR_MEMORY_CAPTURE_PEERS) {
-        const ready = new RegExp(`✓\\s+${tool} ready`).test(out);
-        row(bridge.error ? undefined : ready, `memory capture: ${tool}`, bridge.error ? "unknown (`dot ai memory status` not available)" : `${ready ? "ready" : "not ready"}, per ` + "`dot ai memory status`");
+        const found = nativeMemoryCaptureRow(tool, readMemorySetup(tool));
+        row(found.ok, `memory capture: ${tool}`, found.detail);
       }
     } finally {
       // Preserve findings already collected if a later probe (for example config parsing) throws.
@@ -2672,6 +2767,19 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 };
 
+/**
+ * One bounded read of agent-mem's setup state for a tool: `amem setup <tool> --json` with no mode flag is a preview and writes nothing. No shell, a 10 s timeout, a 256 KiB output cap,
+ * and the answer is parsed as JSON here and judged by `nativeMemoryCaptureRow`; anything that does not parse, exits non-zero or times out is "unavailable", never a guess.
+ * ponytail: runs the `amem` found on PATH (the hub pins @staix/agent-mem exactly, but the person's own `amem` may be another version); the upgrade is to call `planSetup` from the pinned
+ * library in-process once it is exported from its public entry.
+ */
+function readMemorySetup(tool: string): MemorySetupReading {
+  const found = spawnSync("amem", ["setup", tool, "--json"], { encoding: "utf8", timeout: 10_000, maxBuffer: 256 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+  if (found.error) return { kind: "unavailable", reason: (found.error as NodeJS.ErrnoException).code === "ENOENT" ? "`amem` is not on PATH" : "`amem setup` could not be run" };
+  if (found.status !== 0 || typeof found.stdout !== "string") return { kind: "unavailable", reason: found.status === null ? "`amem setup` timed out" : `\`amem setup ${tool}\` refused or failed` };
+  try { return { kind: "read", plan: JSON.parse(found.stdout) }; } catch { return { kind: "unavailable", reason: "`amem setup --json` did not print JSON" }; }
+}
+
 function sanitizeRoutingParseError(file: "routing.toml" | "routing.local.toml", error: unknown): string {
   const raw = ((error as Error)?.message || "invalid TOML").split("\n")[0]!.trim();
   const cleaned = raw
@@ -2793,7 +2901,7 @@ async function runConductorCommand(): Promise<void> {
 }
 const runConfigured = configuredCommand ? async () => {
   const selection = parseConfiguredAcpArguments(cmd, args, projectCatalog, declaredInstances, peerConfig.declaredExternalInstances);
-  if (!selection.preview) assertLifecycleAvailable();
+  if (!selection.preview) assertLifecycleAvailable(cwd);
   await runConfiguredAcpEntry({ kind: cmd, raw: args, catalog: projectCatalog, instances: declaredInstances, declaredExternalInstances: peerConfig.declaredExternalInstances, projectRoot: cwd, connect: connectLaunch, print: text => console.log(text), operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
 } : undefined;
 const run = identity.role === "tools" && commandAccess === "conductor" ? runConductorCommand : (Object.hasOwn(commands, cmd) ? commands[cmd] : undefined) ?? runConfigured ?? (() => fail(`unknown command "${cmd}"; run ahub help`));

package/src/cli/output.ts

@@ -7,6 +7,7 @@ import { cells, TABLES, table, fitLine, wrap, duration, relative, plural, termin
 import { taskProgress } from "../ui/task-progress.ts";
 import { backendLabel } from "./status-lines.ts";
 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";
 
@@ -20,7 +21,7 @@ export interface StatusOutput {
   /** #843 AC3: installed agent CLIs not on a verified version; ids, version, state and a receipt path only. */
   agentDrift?: readonly { id: string; version: string; state: string; receipt: string }[];
   /** #512a: one row per machine-local schedule; ids, times and a state only, never task text. */
-  schedules?: readonly { id: string; every: string; class: string; queue: string; next: number; last?: number; task?: number; state: string; coalesced?: number; error?: string }[];
+  schedules?: readonly { id: string; every?: string; cron?: string; zone?: string; class: string; queue: string; next: number; last?: number; task?: number; state: string; coalesced?: number; error?: string }[];
   taskStalls?: readonly { task: number; cause: { kind: string; peer?: string; dependency?: number; code: string } }[];
   pendingTaskOffers?: readonly { task: number; peer: string }[];
   isolatedChecks?: { pending?: number; orphans?: string[]; unknownReceipts?: readonly string[]; maintenanceUnavailable?: boolean };
@@ -218,8 +219,8 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     for (const pending of data.retainedConfig) out.push(...detail("retained reason", `${pending.key}: ${pending.reason}`, columns, "attention"));
   }
   for (const row of data.schedules ?? []) {
-    const when = (at: number) => new Date(at).toISOString().replace("T", " ").slice(0, 16) + "Z";
-    const text = `${row.state === "paused" ? `paused (ahub schedule resume ${row.id}); would be next ${when(row.next)}` : row.state === "scheduled" ? `next ${when(row.next)}` : row.state === "due" ? "due now" : row.state === "waiting" ? `due, waiting for task #${row.task} to close` : "due, held (the hub is stopping or recovering)"}; every ${row.every}; ${row.class} to ${row.queue}${row.last ? `; last ${when(row.last)}${row.task ? ` as task #${row.task}` : ""}` : "; never run"}${row.coalesced ? `; ${row.coalesced} skipped run${row.coalesced === 1 ? "" : "s"} coalesced` : ""}${row.error ? `; last error: ${row.error}` : ""}`;
+    const when = (at: number) => row.zone ? scheduleWhen(row, at) : new Date(at).toISOString().replace("T", " ").slice(0, 16) + "Z";
+    const text = `${row.state === "paused" ? `paused (ahub schedule resume ${row.id}); would be next ${when(row.next)}` : row.state === "scheduled" ? `next ${when(row.next)}` : row.state === "due" ? "due now" : row.state === "waiting" ? `due, waiting for task #${row.task} to close` : "due, held (the hub is stopping or recovering)"}; ${schedulePeriodText(row)}; ${row.class} to ${row.queue}${row.last ? `; last ${when(row.last)}${row.task ? ` as task #${row.task}` : ""}` : "; never run"}${row.coalesced ? `; ${row.coalesced} skipped run${row.coalesced === 1 ? "" : "s"} coalesced` : ""}${row.error ? `; last error: ${row.error}` : ""}`;
     out.push(...detail(`schedule ${row.id}`, text, columns, row.error ? "attention" : undefined));
   }
   if (data.queueBackpressure) {
@@ -347,6 +348,8 @@ export function renderBacklog(cards: any[], columns?: number, now = Date.now(),
   return [...rows(names, table, columns), [], ...lines(summary, columns)];
 }
 /** #724: one line per task. TITLE goes last and is cut to the room left; at a narrow width REVIEWER, CLASS and AGE give way first. */
+/** #604: a task another project handed over says so on the board: the project id and the peer, both ids and nothing a handoff wrote. */
+const handoffMark = (task: any): string => task?.handoffOrigin ? `  (handed off from ${String(task.handoffOrigin.projectId).slice(0, 24)} by ${String(task.handoffOrigin.peer).slice(0, 32)})` : "";
 function compactBoard(tasks: any[], data: OutputCell[][], columns: number, staged: boolean): Span[][] {
   const head = ["ID", "STATE", "OWNER", "REVIEWER", "CLASS", "AGE", "AFTER", ...(staged ? ["STAGE"] : []), "TITLE"];
   let table = tasks.map((task, i) => {
@@ -355,7 +358,7 @@ function compactBoard(tasks: any[], data: OutputCell[][], columns: number, stage
     const meter = /^\[[^\]]*\](?: cancelled)?/.exec(row[7]?.text ?? "")?.[0] ?? "[----]";
     const stage = task.lifecycle ? `${meter} ${task.lifecycle.stage}: ${stageCode(String(task.lifecycle.next ?? ""))}` : meter;
     const short = task.lifecycle ? `${meter} ${stageCode(String(task.lifecycle.next ?? ""))}` : meter;
-    return [row[0]!, row[1]!, row[2]!, row[3]!, row[4]!, row[5]!, span(after, undefined, true), ...(staged ? [{ ...span(stage, row[7]!.tone, true), short }] : []), span(flat(task.title))];
+    return [row[0]!, row[1]!, row[2]!, row[3]!, row[4]!, row[5]!, span(after, undefined, true), ...(staged ? [{ ...span(stage, row[7]!.tone, true), short }] : []), span(`${flat(task.title)}${handoffMark(task)}`)];
   });
   let names = [...head];
   const drop = (name: string) => { const at = names.indexOf(name); if (at < 0) return; names = names.filter((_, i) => i !== at); table = table.map(row => row.filter((_, i) => i !== at)); };
@@ -389,7 +392,7 @@ export function renderBoard(tasks: any[], columns?: number, now = Date.now(), fu
     const row = cells(s, task, false, now, stages);
     row[2] = span(row[2]!.text, peerTone(task.owner ?? ""));
     row[3] = span(row[3]!.text, peerTone(task.reviewer ?? ""));
-    row[6] = span(`${task.title}${task.deps?.length ? `  after ${task.deps.map((id: number) => `#${id}`).join(", ")}` : ""}${task.signals?.includes("pii") ? `  (ahub task show ${task.id})` : ""}`);
+    row[6] = span(`${task.title}${handoffMark(task)}${task.deps?.length ? `  after ${task.deps.map((id: number) => `#${id}`).join(", ")}` : ""}${task.signals?.includes("pii") ? `  (ahub task show ${task.id})` : ""}`);
     if (allTasks === null) row.pop();
     return row;
   });