@staix/agent-hub 0.25.0 → 0.27.0

package/src/adapters/channel-peer.ts

@@ -6,7 +6,7 @@ import type { StartForm } from "./registry-types.ts";
 /** Only the control socket operations the peer owns; authentication remains in the daemon. */
 export interface ChannelSocket {
   readyState: number;
-  data: { launchId?: string };
+  data: { launchId?: string; protocol?: number };
   send(data: string): unknown;
   close(code?: number, reason?: string): void;
 }
@@ -142,7 +142,9 @@ export class WsPeer extends BasePeer {
   }
 
   recoveryMetadata(): Record<string, unknown> {
-    return { launch: definitionOf(this.id)?.attach?.recoveryLaunch?.(this.id) ?? { kind: "claude-channel", peer: this.id } };
+    const protocol = this.attached ? this.sock?.data.protocol : undefined;
+    return { launch: definitionOf(this.id)?.attach?.recoveryLaunch?.(this.id) ?? { kind: "claude-channel", peer: this.id },
+      ...(typeof protocol === "number" && Number.isSafeInteger(protocol) && protocol > 0 ? { controlProtocol: protocol } : {}) };
   }
 }
 

package/src/adapters/definitions/builtin-metadata.ts

@@ -76,7 +76,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     projection: { roleRank: 0, helpRank: 0, plannerEligible: true },
     api: 1, kind: "claude", displayName: "Claude Code", family: "claude", transport: "claude-channel",
     roles: Object.freeze(["planner", "reviewer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-    start: { forms: Object.freeze(["tui"] as const), defaultForm: "tui", launch: claudeNativeLaunch, version: claudeObservedVersion, ...CLAUDE_LAUNCH_POLICY, conductorStartable: true,
+    start: { forms: Object.freeze(["tui"] as const), defaultForm: "tui", launch: claudeNativeLaunch, version: claudeObservedVersion, ...CLAUDE_LAUNCH_POLICY, conductorStartable: true, upStart: { allowed: true, default: true },
       unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--dangerously-load-development-channels", "--dangerously-skip-permissions"]) },
     identity: { mcp: "channel-plugin" }, instances: { mode: "external", roles: ["planner", "implementer", "verifier", "reviewer"] }, attach: { externalHello: true, recoveryLaunch: claudeRecoveryLaunch },
     // Approval enforcement belongs to the verified native transport and host permission gate.
@@ -93,7 +93,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     projection: { roleRank: 1, startRank: 1, helpRank: 1, plannerEligible: true },
     api: 1, kind: "codex", displayName: "Codex", family: "codex", transport: "codex-appserver",
     roles: Object.freeze(["implementer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-    start: { create: createCodex, daemonPort: "codex-appserver", forms: dualForms, defaultForm: "tui", launch: codexNativeLaunch, version: codexObservedVersion, ...CODEX_LAUNCH_POLICY, conductorStartable: true,
+    start: { create: createCodex, daemonPort: "codex-appserver", forms: dualForms, defaultForm: "tui", launch: codexNativeLaunch, version: codexObservedVersion, ...CODEX_LAUNCH_POLICY, conductorStartable: true, upStart: { allowed: true, default: true },
       unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--remote", "--remote-auth-token-env", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]) },
     identity: { mcp: "env" }, instances: { mode: "headless" },
     permission: { trackUnattended: true, grants: { ask: "the session's own approval policy applies again", "ask-when-needed": "approval policy on-request on every turn", "never-ask": "approval policy never on every turn: nothing asks" } },
@@ -106,7 +106,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     projection: { roleRank: 2, startRank: 2, helpRank: 2, plannerEligible: true },
     api: 1, kind: "kimi", displayName: "Kimi Code", family: "kimi", transport: "acp",
     roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
-    start: { create: createKimi, acpCommand: kimiAcpCommand, explicitHeadlessMode: true, planCommand: () => "ahub kimi", daemonPort: "acp", forms: dualForms, defaultForm: "tui", conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    start: { create: createKimi, acpCommand: kimiAcpCommand, explicitHeadlessMode: true, planCommand: () => "ahub kimi", daemonPort: "acp", forms: dualForms, defaultForm: "tui", conductorStartable: true, upStart: { allowed: true }, hubSwitches: [], ownedFlags: [] },
     // ACP sessions carry headless identity; the existing CLI alone owns the TUI's project MCP entry.
     identity: { mcp: "acp-session" }, instances: { mode: "headless" }, attach: { pullOnlyForms: Object.freeze(["tui"] as const), recoveryLaunch: kimiRecoveryLaunch,
       pullOnlyNotice: "pull-only: messages wait for hub_inbox; no push, steer, watchdog or automatic quota handoff",
@@ -121,7 +121,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     projection: { roleRank: 4, startRank: 0, helpRank: 6, plannerEligible: false },
     api: 1, kind: "pi", enabledSwitchStartOnly: true, displayName: "Pi", family: "pi", transport: "hub-native",
     roles: implementerRoles, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: true },
-    start: { create: createPi, exclusiveStartRefusal: "Pi start is in progress; inspect status before retrying", refreshTools: true, explicitHeadlessMode: true, daemonPort: "pi-rpc", forms: dualForms, defaultForm: "tui", conductorStartable: true, autoStart: "pi.auto_start", conductorStartArgs: piConductorStartArgs, hubSwitches: [], ownedFlags: [] },
+    start: { create: createPi, exclusiveStartRefusal: "Pi start is in progress; inspect status before retrying", refreshTools: true, explicitHeadlessMode: true, daemonPort: "pi-rpc", forms: dualForms, defaultForm: "tui", conductorStartable: true, upStart: { allowed: true }, autoStart: "pi.auto_start", conductorStartArgs: piConductorStartArgs, hubSwitches: [], ownedFlags: [] },
     identity: { mcp: "env" }, instances: { mode: "headless" },
     // Approval enforcement belongs to the verified native transport and host permission gate.
     permission: { grants: { ...hubGrants } },
@@ -134,7 +134,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     projection: { roleRank: 3, helpRank: 7, plannerEligible: false },
     api: 1, kind: "local", displayName: "Local worker", family: "local", transport: "hub-native",
     roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: true, hubSandboxed: true },
-    start: { create: createLocal, reconfigureWhileAttached: true, refreshTools: true, daemonPort: "local-worker", forms: headlessForms, defaultForm: "headless", conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    start: { create: createLocal, reconfigureWhileAttached: true, refreshTools: true, daemonPort: "local-worker", forms: headlessForms, defaultForm: "headless", conductorStartable: true, upStart: { allowed: true }, hubSwitches: [], ownedFlags: [] },
     identity: { mcp: "env" }, instances: { mode: "headless" },
     // Approval enforcement belongs to the verified native transport and host permission gate.
     permission: { grants: { ...hubGrants } },
@@ -147,7 +147,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     projection: { roleRank: 6, startRank: 3, helpRank: 3, plannerEligible: true },
     api: 1, kind: "jcode", displayName: "Jcode", family: "jcode", transport: "acp",
     roles: implementerRoles, optional: true, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: false },
-    start: { create: createJcode, preflight: jcodeStartPreflight, daemonPort: "owned-acp", forms: dualForms, defaultForm: "tui", explicitHeadlessMode: true, conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    start: { create: createJcode, preflight: jcodeStartPreflight, daemonPort: "owned-acp", forms: dualForms, defaultForm: "tui", explicitHeadlessMode: true, conductorStartable: true, upStart: { allowed: true }, hubSwitches: [], ownedFlags: [] },
     // #685: an extra Jcode is a headless instance with its own native home, socket and state (instances.<id>.jcode_home).
     identity: { mcp: "project-file" }, instances: { mode: "headless", nativeHome: true },
     permission: { unmanaged: "Jcode native policy is unmanaged; no hub mode mapping", grants: {

package/src/adapters/definitions/qwen.ts

@@ -26,6 +26,8 @@ export const QWEN_DEFINITION: AdapterDefinition = {
     forms: ["headless"],
     defaultForm: "headless",
     conductorStartable: true,
+    // #608: the TUI is explicit only, so `ahub up` never starts Qwen from the start set; the text names why.
+    upStart: { allowed: false, refusal: "the hub never opens its TUI, and a Qwen is started only by ahub qwen" },
     hubSwitches: [],
     ownedFlags: [],
     // The TUI (#286 Part 3) is explicit only: forms stays headless, so Qwen never becomes a start-mode peer and the hub never opens it by itself.

package/src/adapters/registry-types.ts

@@ -188,6 +188,8 @@ export interface AdapterDefinition {
     preflight?(ctx: StartRequest): string | undefined;
     version?(ctx: VersionContext): string | undefined;
     conductorStartable: boolean;
+    /** #608: whether `ahub up` may start this kind from the `start.agents` set, and whether it is in the default set. `allowed: false` carries the reason a listing is refused. Absent: not startable by `ahub up`, refused with the generic reason. Fixed builtins only. */
+    upStart?: { allowed: true; default?: true } | { allowed: false; refusal: string };
     passthrough?: boolean;
     autoStart?: "pi.auto_start";
     exclusiveStartRefusal?: string;

package/src/adapters/registry.ts

@@ -247,6 +247,7 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
     ["start.daemonPort pi-rpc", definition.start.daemonPort === "pi-rpc"],
     ["start.daemonPort qwen-dual", definition.start.daemonPort === "qwen-dual"],
     ["start.createTui", declared(definition.start, "createTui")],
+    ["start.upStart", declared(definition.start, "upStart")], // #608: which kinds `ahub up` may start is a fixed-builtin decision, never a declared one
     ["routing", definition.routing !== undefined],
     ["projection", definition.projection !== undefined],
     ["instances.nativeHome", declared(definition.instances, "nativeHome")], // #685: a fixed-builtin assumption, one native data home per declared instance

package/src/cli/conductor-recovery.ts

@@ -9,14 +9,15 @@ import { readRestartSnapshot } from "../hub/restart.ts";
 import { processLiveness } from "../pi/process-signature.ts";
 import { packageDigest, recoveryTargetDigest } from "./recovery-package.ts";
 import type { Project } from "../hub/registry.ts";
-import { planFingerprint, registeredProjects, type RecoveryOperation, type UpgradePlan } from "./upgrade.ts";
+import { planFingerprint, recoveryScope, registeredProjects, type RecoveryOperation, type UpgradePlan } from "./upgrade.ts";
 import { realPath } from "../hub/project.ts";
 
 function unavailable(): never { throw new RecoveryAuthorityError(); }
 function validateConductorOperation(op: RecoveryOperation): void {
   try {
     const { fingerprint, ...body } = op.plan;
-    if (op.schema !== 1 || !["restart", "upgrade"].includes(op.plan.kind) || planFingerprint(body) !== fingerprint || !op.plan.projects.length
+    const scope = recoveryScope(op.plan);
+    if (!(op.schema === 1 || op.schema === 3 && scope !== undefined) || !["restart", "upgrade"].includes(op.plan.kind) || planFingerprint(body) !== fingerprint || !op.plan.projects.length
       || op.plan.projects.length > 128 || new Set(op.plan.projects.map(row => row.project.id)).size !== op.plan.projects.length) unavailable();
   } catch { unavailable(); }
 }

package/src/cli/help.ts

@@ -10,15 +10,15 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub --project <path|id> <command>", "select a repository or worktree explicitly"],
     ["ahub projects [--json] [--full] [--color=auto|always|never]", "list registered projects and live status"],
     ["ahub projects remove <id>", "forget a stopped registration (keeps project files)"],
-    ["ahub setup [--yes]", "install or update the channel plugin and project-neutral hook in Claude configuration homes in use, preserving unrelated profile settings, register the acon console plugin (console/plugins/ahub.json in the hub home, read at acon's next start), then run doctor"],
-    ["ahub init [--profile dev|research|writing|general|<pack>] [--shadow] [--release-guard] [--dry-run --json]", "preview or write .agenthub/config.json and the AGENTS.md marker block (drops a legacy CLAUDE.md block); a pack is a shipped one (writing-pack, analysis, ops) or a project file .agenthub/roles/<name>.pack.json; a new project inherits a trusted machine autonomy default into config.local.json"],
+    ["ahub setup [--yes] [--agents <a,b>]", "install or update the channel plugin and project-neutral hook in Claude configuration homes in use, preserving unrelated profile settings, ask once which agents ahub up starts (--agents answers it, --yes keeps the current choice or claude,codex, no terminal keeps the default), register the acon console plugin (console/plugins/ahub.json in the hub home, read at acon's next start), then run doctor"],
+    ["ahub init [--profile dev|research|writing|general|<pack>] [--shadow] [--release-guard] [--dry-run --json]", "preview or write .agenthub/config.json and the AGENTS.md marker block (drops a legacy CLAUDE.md block); a pack is a shipped one (writing-pack, analysis, ops) or a project file .agenthub/roles/<name>.pack.json; a new project inherits a trusted machine autonomy default and the agent set chosen at ahub setup (start.agents) into config.local.json"],
     ["ahub --live-test [--project <path|id>] <command> [args...]", "user-authorized operational console delegation; ordinary calls retain peer identity; person-authored content refuses"],
     ["ahub help [command]", "this help, or one command's entries; also --help and -h"],
     ["ahub version | --version", "print the installed version"],
     ["ahub completion zsh|bash|fish", "print a shell completion script; its candidates come from these help entries"],
   ]],
   ["Daemon and runtime", [
-    ["ahub up [--unattended] [--no-console]", "start the daemon; interactive terminals enter console"],
+    ["ahub up [--unattended] [--no-console] [--no-agents]", "start the daemon, then ask it to start this project's default agents (start.agents, claude and codex unless chosen at setup; one line each, a refusal names the manual command; --no-agents skips them), then enter console in an interactive terminal"],
     ["ahub console [--panels] [--color=auto|always|never]", "enter the human console; P cycles built-in pet characters/off; exiting leaves the daemon running"],
     ["ahub console --no-pet", "turn off attention for this session; combines with --panels and --color"],
     ["ahub pet --window [--close]", "start or close the macOS floating window, from a person's terminal"],
@@ -27,7 +27,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub sdlc status [task] | explain <task> [--json] [--color=auto|always|never] | export <task> | record <task> <receipt-json>", "read head-bound lifecycle gates and the next actor/action; status and explain are open to any agent as a public view (private tasks stay stubs), export and record are person only; export stays JSON"],
     ["ahub sdlc queue <owner/repo> | release <owner/repo> [live-issue...] [--json] [--color=auto|always|never]", "read-only merge and release evidence; open to any agent as public readback of the checkout's repositories, never an authorization"],
     ["ahub sdlc merge <task> [--dry-run] [--json] [--color=auto|always|never]", "guarded squash merge of an approved task at its approved head after every gate is re-read; follows sdlc.toml auto_merge (off, dry-run, on); --dry-run only reports (person or conductor)"],
-    ["ahub sdlc authorize-release <version> [--json] [--color=auto|always|never]", "approve this daemon checkout commit, version and fresh docs (person only; restart revokes)"],
+    ["ahub sdlc authorize-release <version> [--json] [--color=auto|always|never]", "approve this daemon checkout commit, version and fresh docs (person or unique configured conductor on the person's explicit release instruction naming the release in its own session; hub/task/review/file/peer relays never qualify; restart revokes)"],
     ["ahub sdlc release-guard -- <literal git push|gh release create|npm publish argv>", "read-only authorization preflight; init --release-guard installs the tag pre-push hook"],
     ["ahub sdlc release-guard-hook <remote-name> <remote-url>", "internal pre-push readback; validates version tags and forwards exact stdin on success"],
     ["ahub sdlc accept <task> --issue <n> [--repo owner/repo]", "accept the task's spec issue at its current body; build entry needs it in enforce (person only)"],
@@ -41,7 +41,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub status [--json] [--full] [--color=auto|always|never]", "the hub, its peers, model backends and task counts"],
     ["ahub status --all [--json] [--color=auto|always|never]", "show every registered project"],
     ["ahub logs [-f]", "person: last 100 hub.log lines (-f starts at 10); conductor: bounded public lines and follow while authority remains"],
-    ["ahub doctor [--json] [--full] [--color=auto|always|never]", "check the tools, daemon, plugin, gateway, models, memory library and memory capture setup (read from `amem setup <tool> --json`, a preview) this project uses"],
+    ["ahub doctor [--json] [--full] [--color=auto|always|never]", "check the tools, daemon, plugin, gateway, models, memory library and memory capture setup (read from `amem setup <tool> --json`, a preview) this project uses, and the runtime capture pruning ledger; warn when the CLI or plugin is older than its running daemon"],
     ["ahub doctor --stale-anchors [--json]", "read-only bounded report of public memory symbol anchors at current HEAD; private or unavailable evidence stays unknown"],
     ["ahub doctor --orphans [--kill] [--json] [--color=auto|always|never]", "person: inspect missing-root registrations; conductor --kill: selected project only; signed hub ownership is required before any stop"],
     ["ahub agents [--json]", "show each gated agent CLI's installed version and verdict (verified, in-line, trusted, refused or unknown)"],
@@ -50,8 +50,8 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub down", "stop this project's hub, the counterpart of ahub up (same as ahub kill)"],
     ["ahub reset [--all] [--yes]", "list, then with --yes stop the hub and discard every queued and needs_review delivery, clear holds and pauses and drop session pointers; --all moves the state directory to .agenthub/archive instead"],
     ["ahub restart [--dry-run] [--yes] [--json] [--verbose] [--color=auto|always|never]", "recover this project's runtime; a configured conductor's --yes requires a same-project, source-issued continuation proof, otherwise run it as the person"],
-    ["ahub upgrade [--to <version>] [--dry-run] [--yes] [--json] [--verbose] [--color=auto|always|never]", "review and upgrade running projects; --to defaults to latest for interactive review or dry-run, while --yes requires --to <exact-version>; conductor apply needs the same project's supported proof, and a newer-coordinator handoff is person-only"],
-    ["ahub recovery [status|resume|abort] [<operation-id>] [--json] [--color=auto|always|never]", "inspect a preflight; without an id, resume/abort select the operation holding the lock; a bare terminal opens the person's screen; only its initiating conductor may continue its own supported restart/upgrade with fresh proof"],
+    ["ahub upgrade [--project <path|id>] [--to <version>] [--dry-run] [--yes] [--json] [--verbose] [--color=auto|always|never]", "review and upgrade this selected project (default: current directory; --project selects another); global CLI/plugin updates are separate; --to defaults to latest for interactive review or dry-run, while --yes requires --to <exact-version>; conductor apply needs the same project's supported proof, and a newer-coordinator handoff is person-only"],
+    ["ahub recovery [status|resume|abort] [<operation-id>] [--json] [--color=auto|always|never]", "inspect a preflight; without an id, resume/abort select this project's hold or a retained legacy machine hold; a bare terminal opens the person's screen; only its initiating conductor may continue its own supported restart/upgrade with fresh proof"],
     ["ahub recovery reattach <operation-id> codex|claude|pi", "person only: repair that blocked peer with its recorded session; leaves the rest for recovery resume"],
     ["ahub recovery dispose [<operation-id>] --fresh-session codex|claude --reason <text>", "end a partial operation by starting that peer as a new session, recording the lost conversation"],
     ["ahub recovery dispose [<operation-id>] --stop-and-archive --reason <text>", "end a partial operation: stop its own targets, archive its snapshot and release the lock; the upgrade is abandoned, not completed"],
@@ -77,7 +77,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub autonomy on [--all-projects] [--yes] | off [--all-projects] | status [--json]", "person only: apply the autonomy preset and machine default with one confirmation, optionally to every registered project; off removes fixed preset keys (manual edits included); status reports modes, floor enforcement and Claude homes; settings undo restores a live-hub project write"],
     ["ahub settings [list] [--json] | get <key> [--json]", "the settings the dashboard can change, each with its value, the file it comes from and when it applies"],
     ["ahub settings set <key> <value|inherit> [--yes] [--preview] [--now] | undo | reload", "validated settings: conductor set is limited to exact live operational keys; undo/reload and other keys are person only; --preview saves nothing; conductor writes keep the person undo record"],
-    ["ahub settings edit <config.local.json|sdlc.toml> (set <path> <json> | remove <path>)... [--reason <text>] [--preview] [--yes] | backups [--json]", "human only: structural config (instances, review, snapshots, approvals, context.gate, sdlc.toml mode and required_checks) validated by the hub's own loaders, previewed as a diff and written with a backup; a key that runs code or locates secrets needs its name typed, never --yes"],
+    ["ahub settings edit <config.local.json|sdlc.toml> (set <path> <json> | remove <path>)... [--reason <text>] [--preview] [--yes] | backups [--json]", "human only: structural config (instances, review, snapshots, approvals, context.gate, research.runners, sdlc.toml mode and required_checks) validated by the hub's own loaders, previewed as a diff and written with a backup; a key that runs code or locates secrets needs its name typed, never --yes"],
     ["ahub pause|resume <peer>", "hold a peer's deliveries in its queue / release them"],
     ["ahub queue list [--peer <id>] [--json] [--full] [--color=auto|always|never]", "inspect durable deliveries; open to any agent as public queue metadata, held bodies stay with the person or conductor"],
     ["ahub queue show <delivery-id> [--json] [--color=auto|always|never]", "person or configured conductor: inspect one delivery and revision; agent output uses the public view"],
@@ -108,6 +108,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub learn list [--all] | accept <id> | reject <id> [--json] [--color=auto|always|never]", "person only, never a conductor or an agent shell: review a recurring-unmet-criterion candidate the hub filed (#514a); accept writes its one review checklist line, added to your current checklist, to .agenthub/config.local.json through the settings writer (this machine only, never a tracked file, ahub settings undo puts it back, applies after a restart) and closes the card; reject only closes it"],
     ["ahub study draft <parent> <contract.json> | revise <id> <revision> <contract.json> | approve <id> <revision> | close <id> <revision> --reason <text> | approve-protocol <hash> [--json] [--color=auto|always|never]", "person only: store a research campaign contract as a draft, revise it, approve it (the only step that creates the unit tasks and lets work start) or close it; approve-protocol binds approval to the exact protocol and evaluator hashes; a planner drafts through hub_study_draft and hub_study_revise and can never approve"],
     ["ahub study show [<id> | --after <id>] [--json] [--color=auto|always|never]", "read-only for anyone: list this project's research campaigns, 50 per page (the page names the --after cursor that continues it), or one campaign's coverage per unit, handoff state, budget support and why dispatch is held; a private campaign, task or source shows ids, counts and states only"],
+    ["ahub study experiments (--campaign <id> [--after <n>] | --attempt <ra-id> [--events-after <n>] | --plan <hash> --baseline <ra-id> --variant <ra-id>) [--json] [--color=auto|always|never]", "read-only for anyone, the same read as hub_experiment_show: a campaign's recorded attempts (50 a page, --after continues), one attempt with its events, or one comparison under a recorded plan; each value names its provenance and a declared value is never shown as observed"],
     ["ahub deliverables [--task <id>] [--approved] [--check] [--json] [--color=auto|always|never]", "what each task delivered and a reviewer approved, by id, hash and size (a path only where the PII screen allows); --check measures the files now and marks one changed since review; an agent sees only the tasks hub_task_show shows it"],
     ["ahub task show <id> [--json] [--full] [--color=auto|always|never] | escalate <id>", "full task with history (the person sees PII text, an agent the public view) / hand it to the next peer in escalate_to (person or configured conductor)"],
     ["ahub task role <id> <role|none>", "the person, or an agent on a task it owns: change bounded catalog guidance on an open task; routing and authority are unchanged"],

package/src/cli/identity.ts

@@ -23,7 +23,7 @@ export function liveTestRefusal(command: string, args: readonly string[], contex
     || (command === "backlog" && sub !== "list") || (command === "release" && !["list", "show"].includes(sub ?? ""))
     || (command === "memory" && sub !== "graph")
     // #601: a campaign's draft, revise, approve and close are the person's verdicts; only `show` is a read. Without this an agent shell could run them as the person through `--live-test`.
-    || (command === "study" && sub !== "show")
+    || (command === "study" && sub !== "show" && sub !== "experiments")
     || (command === "recovery" && (sub === "reattach" || sub === "dispose" && context.repairedFresh === true))
     || (command === "board" && args[0] === "import") || (command === "sdlc" && (args[0] === "record" || args[0] === "accept" || args[0] === "accept-departure"))
     || (command === "bench" && args.find(arg => arg !== "--json") === "run") || command === "pet"
@@ -85,7 +85,7 @@ const peerReadForms: Readonly<Record<string, Readonly<Record<string, PeerReadFor
   sdlc: { status: { positional: 1, displayFlags: sdlcReadDisplayFlags }, explain: { positional: 1, displayFlags: sdlcReadDisplayFlags }, queue: { positional: 1, minimum: 1, displayFlags: sdlcReadDisplayFlags }, release: { positional: 33, minimum: 1, displayFlags: sdlcReadDisplayFlags } },
   release: { show: { positional: 1, minimum: 1, displayFlags: [] } },
   // #601: reading a campaign is harmless for any agent (the hub stubs a private one); draft, revise, approve and close fall to `console`.
-  study: { show: { positional: 1, valueFlags: ["--after"], displayFlags: sdlcReadDisplayFlags } },
+  study: { show: { positional: 1, valueFlags: ["--after"], displayFlags: sdlcReadDisplayFlags }, experiments: { valueFlags: ["--campaign", "--attempt", "--after", "--events-after", "--plan", "--baseline", "--variant"], displayFlags: sdlcReadDisplayFlags } },
   projects: { "": {} },
   models: { status: {} },
   recovery: { status: { positional: 1 } },
@@ -138,8 +138,8 @@ export function classifyPeerCommand(command: string, args: readonly string[], ca
   if (conductorOperation(command,args)) return "conductor";
   if (command === "stop") return "console";
   if (command === "sdlc" && ["release-guard", "release-guard-hook"].includes(args[0] ?? "")) return "allowed";
-  // #786: the guarded merge is the person's or the configured conductor's; the daemon refuses any other peer by role.
-  if (command === "sdlc" && args[0] === "merge") return "conductor";
+  // #786, #1063: guarded merge and recording explicitly instructed release consent admit the person or unique configured conductor; the daemon checks the role.
+  if (command === "sdlc" && ["merge", "authorize-release"].includes(args[0] ?? "")) return "conductor";
   if (command === "role") return ["list", "show"].includes(args[0] ?? "") ? "allowed" : "console";
   if (command === "task") {
     // #933: cancel, label and role act on the caller's own task only; the daemon refuses another peer's task by role (Tasks.cancel, task_catalog_role, task_label_check).
@@ -196,7 +196,7 @@ export function cliCommandLabel(command: string, args: readonly string[], catalo
   if (command === "learn") return ["list", "accept", "reject"].includes(args.find(arg => arg !== "--json") ?? "") ? `learn ${args.find(arg => arg !== "--json")}` : "learn";
   if (command === "source") return ["add", "list"].includes(args.find(arg => arg !== "--json") ?? "") ? `source ${args.find(arg => arg !== "--json")}` : "source";
   // #601: a campaign id and a contract path are text the person chose, so the audit names the subcommand only.
-  if (command === "study") return ["draft", "revise", "approve", "close", "show"].includes(args[0] ?? "") ? `study ${args[0]}` : "study";
+  if (command === "study") return ["draft", "revise", "approve", "close", "show", "experiments"].includes(args[0] ?? "") ? `study ${args[0]}` : "study";
   if (command === "release") return ["new", "list", "show", "plan", "activate", "freeze", "ship", "drop"].includes(args[0] ?? "") ? `release ${args[0]}` : "release";
   if (!(catalog?.definitionOf(command) ?? definitionOf(command)) && !["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "completion", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "stop", "models", "say", "queue", "tail", "watch", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "settings", "roster", "status", "pet", "logs", "export", "report", "research", "memory", "goal", "bench", "sdlc", "role", "facts", "check-path", "turns", "undo", "kill", "down", "reset", "doctor", "agents", "source", "broker", "schedule", "intake", "learn", "study"].includes(command)) return "unknown";
   if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "memory", "goal", "bench", "agents", "roster", "settings"].includes(command)) {

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";
@@ -29,7 +30,7 @@ import { renderIntake, renderIntakeChange } from "./intake-output.ts";
 import { renderLearnChange, renderLearnList } from "./learn-output.ts";
 import { renderCapabilities } from "./capabilities-output.ts";
 import { parseStudyArgs } from "./study.ts";
-import { renderStudyList, renderStudyReceipt, renderStudyShow } from "./study-output.ts";
+import { renderExperiments, renderStudyList, renderStudyReceipt, renderStudyShow } from "./study-output.ts";
 import { renderHandoffReceipt, renderHandoffs } from "./handoff-output.ts";
 import { parseHandoffArgs } from "./handoff-args.ts";
 import { terminalText } from "./console-state.ts";
@@ -84,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";
 
@@ -142,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 {
@@ -385,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. */
@@ -680,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.
@@ -693,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),
@@ -709,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);
@@ -725,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 });
@@ -743,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
@@ -757,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 });
@@ -765,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);
@@ -868,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");
@@ -1009,26 +1021,38 @@ 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"));
@@ -1050,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();
@@ -1059,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")));
@@ -1086,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; }
@@ -1491,6 +1525,11 @@ const commands: Record<string, () => Promise<void> | void> = {
       catch { return fail("cannot read the contract file"); }
       try { return JSON.parse(text); } catch { return fail("the contract file is not valid JSON"); }
     };
+    if (parsed.op === "experiments") {
+      // A read of the records Tasks keeps (hub_experiment_show): it runs no command and reads no file, and the hub blanks a private record itself.
+      const args = parsed.attempt ? { attemptId: parsed.attempt, ...(parsed.eventsAfter === undefined ? {} : { eventAfter: parsed.eventsAfter }) } : parsed.plan ? { planHash: parsed.plan, baselineAttemptId: parsed.baseline, variantAttemptId: parsed.variant } : { campaignId: parsed.campaign, ...(parsed.after === undefined ? {} : { after: parsed.after }) };
+      return showToolText(data => renderExperiments(data, present.columns), await taskOp("hub_experiment_show", args), present);
+    }
     if (parsed.op === "show") return showToolText(data => parsed.id ? renderStudyShow(data, present.columns) : renderStudyList(data, present.columns), await taskOp("hub_study_show", parsed.id ? { id: parsed.id } : parsed.after ? { after: parsed.after } : {}), present);
     const request = parsed.op === "draft" ? { parentTaskId: parsed.parentTaskId, contract: contract(parsed.file) }
       : parsed.op === "revise" ? { id: parsed.id, revision: parsed.revision, contract: contract(parsed.file) }
@@ -1959,7 +1998,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)),
@@ -1994,7 +2034,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}.`);
@@ -2550,7 +2590,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;
@@ -2635,6 +2675,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 {
@@ -2646,11 +2687,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.
@@ -2666,6 +2709,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");
@@ -2862,7 +2906,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`));