@staix/agent-hub 0.23.1 → 0.25.0

package/src/cli/claude-profile-hook.ts

@@ -0,0 +1,130 @@
+import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, renameSync, rmSync, writeFileSync, type Stats } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { dirname, isAbsolute, join } from "node:path";
+import { canonicalJson } from "../hub/packs.ts";
+import { factsHook } from "./facts-hook.ts";
+import { shellQuote } from "./shell-quote.ts";
+import type { ClaudeHome } from "./claude-homes.ts";
+
+export interface ClaudeProfileHookOptions { script?: string; runtime?: string }
+export interface ClaudeProfileHookCheck { state: "installed" | "missing" | "refused"; reason: string }
+export interface ClaudeProfileHookInstall extends ClaudeProfileHookCheck { changed: boolean }
+const MAX_SETTINGS_BYTES = 1024 * 1024;
+const validPath = (value: unknown): value is string => typeof value === "string" && value.length > 0 && value.length <= 4096 && isAbsolute(value) && !/[\x00-\x1f\x7f]/.test(value);
+const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const owned = (info: Stats) => !!process.getuid && info.uid === process.getuid() && (info.mode & 0o022) === 0;
+const same = (left: Stats | undefined, right: Stats | undefined) => !left && !right || !!left && !!right && left.dev === right.dev && left.ino === right.ino;
+
+interface HookPlan {
+  check: ClaudeProfileHookCheck;
+  file: string;
+  next?: string;
+  home?: Stats;
+  parent?: Stats;
+  source?: { info: Stats; digest: string };
+}
+
+function hookEntry(options: ClaudeProfileHookOptions): Record<string, unknown> {
+  const script = options.script ?? join(import.meta.dir, "claude-profile-hook.ts"), runtime = options.runtime ?? process.execPath;
+  if (!validPath(script) || !validPath(runtime)) throw new Error("invalid profile hook command");
+  return { matcher: "*", hooks: [{ type: "command", command: `${shellQuote(runtime)} ${shellQuote(script)} --run`, timeout: 5 }] };
+}
+
+function settingsSource(file: string): { value: Record<string, unknown>; source?: HookPlan["source"] } {
+  let fd: number | undefined;
+  try {
+    fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const info = fstatSync(fd);
+    if (!info.isFile() || info.nlink !== 1 || !owned(info) || info.size > MAX_SETTINGS_BYTES) throw new Error("unsafe settings");
+    const bytes = Buffer.alloc(MAX_SETTINGS_BYTES + 1), count = readSync(fd, bytes, 0, bytes.length, 0);
+    if (count > MAX_SETTINGS_BYTES) throw new Error("oversized settings");
+    const content = bytes.subarray(0, count), value: unknown = JSON.parse(content.toString("utf8"));
+    if (!object(value)) throw new Error("invalid settings");
+    return { value, source: { info, digest: createHash("sha256").update(content).digest("hex") } };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { value: {} };
+    throw error;
+  } finally { if (fd !== undefined) closeSync(fd); }
+}
+
+/** A shared read-only plan keeps inspection and installation's refusal rules identical. */
+function planClaudeProfileHook(home: ClaudeHome, options: ClaudeProfileHookOptions): HookPlan {
+  const file = validPath(home.path) ? join(home.path, "settings.json") : "";
+  const refuse = (reason: string): HookPlan => ({ file, check: { state: "refused", reason } });
+  if (!file || !home.sources.length || home.sources.some(source => !["environment", "default", "recorded-launch"].includes(source))) return refuse("No explicitly selected Claude configuration home is available.");
+  try {
+    const directory = lstatSync(home.path, { throwIfNoEntry: false });
+    let parent: Stats | undefined;
+    if (directory && (!directory.isDirectory() || directory.isSymbolicLink() || !owned(directory))) return refuse("The selected Claude home is unsafe or not owned by this user.");
+    if (!directory) {
+      if (home.exists && !home.sources.some(source => source === "environment" || source === "recorded-launch")) return refuse("The previously observed default Claude home is no longer present.");
+      parent = lstatSync(dirname(home.path), { throwIfNoEntry: false });
+      if (!parent?.isDirectory() || parent.isSymbolicLink() || !owned(parent)) return refuse("The selected Claude home's parent is unsafe or unavailable.");
+    }
+    const { value, source } = settingsSource(file);
+    if (value.disableAllHooks === true) return refuse("Claude has disableAllHooks enabled; the profile hook cannot be installed.");
+    if (value.disableAllHooks !== undefined && typeof value.disableAllHooks !== "boolean") return refuse("Claude's hook enablement setting is malformed.");
+    if (value.hooks !== undefined && !object(value.hooks)) return refuse("Claude's hook configuration is malformed.");
+    const hooks = value.hooks ?? {}, existing = hooks.PreToolUse ?? [];
+    if (!Array.isArray(existing)) return refuse("Claude's PreToolUse hook list is malformed.");
+    const entry = hookEntry(options), expected = canonicalJson(entry);
+    const matches = existing.filter(candidate => canonicalJson(candidate) === expected).length;
+    const next = matches === 1 ? undefined : `${JSON.stringify({ ...value, hooks: { ...hooks, PreToolUse: [...existing.filter(candidate => canonicalJson(candidate) !== expected), entry] } }, null, 2)}\n`;
+    if (next !== undefined && Buffer.byteLength(next, "utf8") > MAX_SETTINGS_BYTES) return refuse("Claude's settings would exceed the bounded profile settings size.");
+    return { file, home: directory, parent, source, next, check: matches === 1
+      ? { state: "installed", reason: "The project-neutral profile hook is configured; this does not prove live permission enforcement." }
+      : { state: "missing", reason: matches ? "Duplicate managed profile hooks need normalization." : "The project-neutral profile hook is not configured." } };
+  } catch { return refuse("Claude profile settings could not be safely inspected; no settings were changed."); }
+}
+
+export function checkClaudeProfileHook(home: ClaudeHome, options: ClaudeProfileHookOptions = {}): ClaudeProfileHookCheck {
+  return planClaudeProfileHook(home, options).check;
+}
+
+/** Only the selected home is created; unrelated profile directories and settings are never touched. */
+export function installClaudeProfileHook(home: ClaudeHome, options: ClaudeProfileHookOptions = {}): ClaudeProfileHookInstall {
+  const plan = planClaudeProfileHook(home, options);
+  if (plan.check.state !== "missing" || plan.next === undefined) return { ...plan.check, changed: false };
+  const temporary = join(home.path, `.agent-hub-profile-hook-${randomUUID()}.tmp`);
+  let created: Stats | undefined;
+  try {
+    if (!plan.home) {
+      const current = lstatSync(dirname(home.path));
+      if (!same(plan.parent, current) || !owned(current)) throw new Error("parent changed");
+      mkdirSync(home.path, { mode: 0o700 });
+      created = lstatSync(home.path);
+      if (!created.isDirectory() || created.isSymbolicLink() || !owned(created)) throw new Error("home changed");
+    }
+    const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    let prepared: Stats;
+    try { writeFileSync(fd, plan.next); fchmodSync(fd, 0o600); fsyncSync(fd); prepared = fstatSync(fd); }
+    finally { closeSync(fd); }
+    const current = planClaudeProfileHook(home, options);
+    if (current.check.state === "refused" || !same(plan.home ?? created, current.home) || !same(plan.source?.info, current.source?.info) || plan.source?.digest !== current.source?.digest) throw new Error("settings changed");
+    const named = lstatSync(temporary);
+    if (!same(prepared, named) || !named.isFile() || named.isSymbolicLink() || named.nlink !== 1 || !owned(named)) throw new Error("temporary settings changed");
+    renameSync(temporary, plan.file);
+    return { state: "installed", changed: true, reason: "The project-neutral profile hook is configured; this does not prove live permission enforcement." };
+  } catch { return { state: "refused", changed: false, reason: "Claude profile settings changed or could not be safely written; inspect the selected home before trying again." }; }
+  finally { try { rmSync(temporary, { force: true }); } catch { /* Only this invocation's generated temporary name is considered. */ } }
+}
+
+export interface ClaudeProfileHookTarget { stateDir: string; peer: string }
+export function claudeProfileHookTarget(env: NodeJS.ProcessEnv): ClaudeProfileHookTarget | undefined {
+  if (Object.hasOwn(env, "AGENTHUB_LAUNCH_ID") || !validPath(env.AGENTHUB_STATE_DIR) || !/^[a-z][a-z0-9_-]{0,63}$/.test(env.AGENTHUB_PEER_ID ?? "")) return;
+  return { stateDir: env.AGENTHUB_STATE_DIR, peer: env.AGENTHUB_PEER_ID! };
+}
+export type ClaudeProfileHookTransport = (input: string, stateDir: string, peer: string) => Promise<string | undefined>;
+export async function runClaudeProfileHook(input: string, env: NodeJS.ProcessEnv, transport: ClaudeProfileHookTransport = factsHook): Promise<string | undefined> {
+  const target = claudeProfileHookTarget(env);
+  if (!target || Buffer.byteLength(input, "utf8") > MAX_SETTINGS_BYTES) return;
+  try { return await transport(input, target.stateDir, target.peer); } catch { return; }
+}
+
+// Managed launches inject their own authoritative session hook; ordinary non-hub sessions have no target.
+if (import.meta.main && process.argv.length === 3 && process.argv[2] === "--run" && claudeProfileHookTarget(process.env)) {
+  try {
+    const output = await runClaudeProfileHook(await Bun.stdin.text(), process.env);
+    if (output) console.log(output);
+  } catch { /* A profile hook never turns a transport failure into a native permission decision. */ }
+}

package/src/cli/handoff-args.ts

@@ -0,0 +1,27 @@
+// Argument parsing for `ahub task handoff` (#604, agent-hub#1030). Pure: argv in, one request or a usage line out, so main.ts stays a thin dispatcher and every form is testable without a daemon.
+import { CLASSES } from "../hub/board.ts";
+
+export const HANDOFF_USAGE = "usage: ahub task handoff --project <root|id> [<class>] <title...> [--path <p>]... [--issue <n>] [--task <n>] [--detail <text>] [--json] [--color=auto|always|never]";
+
+export interface HandoffCliRequest { project: string; title: string; class?: string; detail?: string; paths?: string[]; issue?: number; task?: number }
+
+/** `operands` is argv after `task handoff`, presentation flags already removed. A first word that is a class name is the class, said out loud by the caller (the documented short form). */
+export function parseHandoffArgs(operands: readonly string[]): HandoffCliRequest | { usage: string } {
+  const one: Record<string, string> = {}, paths: string[] = [], rest: string[] = [];
+  for (let i = 0; i < operands.length; i++) {
+    const arg = operands[i]!;
+    if (arg === "--project" || arg === "--detail" || arg === "--issue" || arg === "--task" || arg === "--path") {
+      const value = operands[++i];
+      if (value === undefined || value.startsWith("--")) return { usage: HANDOFF_USAGE };
+      if (arg === "--path") paths.push(value); else { if (Object.hasOwn(one, arg)) return { usage: HANDOFF_USAGE }; one[arg] = value; }
+    } else if (arg.startsWith("--")) return { usage: HANDOFF_USAGE };
+    else rest.push(arg);
+  }
+  const project = one["--project"];
+  const classed = rest[0] !== undefined && (CLASSES as readonly string[]).includes(rest[0]) && rest.length > 1;
+  const title = (classed ? rest.slice(1) : rest).join(" ").trim();
+  if (!project || !title) return { usage: HANDOFF_USAGE };
+  if (one["--issue"] !== undefined && !/^[1-9]\d{0,9}$/.test(one["--issue"])) return { usage: `${HANDOFF_USAGE}\n--issue is the target repository's issue number` };
+  if (one["--task"] !== undefined && !/^[1-9]\d{0,9}$/.test(one["--task"])) return { usage: `${HANDOFF_USAGE}\n--task is this project's own task id` };
+  return { project, title, ...(classed ? { class: rest[0]! } : {}), ...(one["--detail"] !== undefined ? { detail: one["--detail"] } : {}), ...(paths.length ? { paths } : {}), ...(one["--issue"] !== undefined ? { issue: Number(one["--issue"]) } : {}), ...(one["--task"] !== undefined ? { task: Number(one["--task"]) } : {}) };
+}

package/src/cli/handoff-output.ts

@@ -0,0 +1,25 @@
+// Human output for `ahub task handoff` and `ahub board --handoffs` (#604, agent-hub#1030). Pure: the hub's parsed JSON in, spans out, no I/O. `--json` is the caller's branch and prints the same text.
+// Only ids, states and counts are shown: the title of a handed-off task is the caller's own and was bounded and sanitized by the hub.
+import { blank, grid, heading, pair, s } from "./sdlc-output.ts";
+import type { Span, Tone } from "./console-state.ts";
+
+const STATE_TONE: Record<string, Tone | undefined> = { approved: undefined, cancelled: "muted", declined: "attention", proposed: "attention" };
+const num = (value: unknown): string => typeof value === "number" && Number.isSafeInteger(value) ? String(value) : "-";
+
+/** The receipt of one handoff: where the task now lives and what to run to follow it. */
+export function renderHandoffReceipt(receipt: unknown, columns?: number): Span[][] {
+  const r = receipt as any;
+  return [...heading(`Handed off to project ${r?.project ?? "?"}`, columns),
+    ...pair("task", `#${num(r?.task)} (${r?.state ?? "proposed"})`, columns, 8, "taskRef"),
+    blank, [s("it is on that project's board as an ownerless proposal; its own roles plan, implement and review it, and you are told when it changes state", "muted")],
+    [s("ahub board --handoffs shows the last state it reported", "muted")]];
+}
+
+/** What this project handed to others, with the last state each target reported. */
+export function renderHandoffs(data: unknown, columns?: number): Span[][] {
+  const rows: any[] = Array.isArray((data as any)?.handoffs) ? (data as any).handoffs : [];
+  if (!rows.length) return [[s("no handoffs: hand work that belongs to another project with `ahub task handoff --project <root|id> <title...>`", "muted")]];
+  return [...heading(`Handoffs (${rows.length})`, columns), ...grid(["PROJECT", "TASK", "STATE", "PR", "BY", "TITLE"], rows.map(row => [
+    s(String(row.remoteProject ?? "?").slice(0, 24), "issueRef"), s(`#${num(row.remoteTask)}`, "taskRef"), s(String(row.state ?? "?"), STATE_TONE[row.state]),
+    s(typeof row.pr === "number" ? `#${row.pr}` : "-"), s(String(row.originPeer ?? "?")), s(String(row.title ?? ""))]), columns)];
+}

package/src/cli/help.ts

@@ -10,8 +10,8 @@ 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 Claude Code channel plugin from this package, 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"],
+    ["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 --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"],
@@ -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 and memory library 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"],
     ["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)"],
@@ -74,6 +74,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub permit <id> <option>", "answer a permission request shown by tail (\"deny\" cancels)"],
     ["ahub roster [--json] [--color=auto|always|never]", "every known peer, participation, start mode and retained work"],
     ["ahub roster add <peer> | remove <peer> [--yes] [--now]", "person or configured conductor: change live participation through settings; removal previews retained messages and task handoff; remove also deletes the roster key of an instance no longer declared"],
+    ["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"],
@@ -85,8 +86,9 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
   ]],
   ["Tasks and review", [
     ["ahub board import github --label <label> [--milestone <milestone>] [--repo <owner/repo>]", "person or configured conductor: read bounded open issues into deduplicated Backlog; never writes GitHub"],
-    ["ahub board [state | --ready] [--columns] [--release <name> | --release-id <id>] [--json] [--full] [--color=auto|always|never]", "the task board, one line per task at a terminal width; --full: whole titles and SDLC advice; --ready: proposed tasks with nothing left to wait for"],
+    ["ahub board [state | --ready] [--columns] [--release <name> | --release-id <id>] [--handoffs] [--json] [--full] [--color=auto|always|never]", "the task board, one line per task at a terminal width; --full: whole titles and SDLC advice; --ready: proposed tasks with nothing left to wait for; --handoffs: what this project handed to other projects and the last state each reported"],
     ["ahub task propose [--class <c> | <class>] <title...> [--owner <peer>] [--path <p>]... [--after <id>]... [--urgent] [--backlog] [--detail <text>]", "put a task on the board; a first word that names a class is taken as the class; while a task named by --after is not approved yet, --owner reserves the task for that peer, offered to it first once it is ready; otherwise --owner assigns it now"],
+    ["ahub task handoff --project <root|id> [<class>] <title...> [--path <p>]... [--issue <n>] [--task <n>] [--detail <text>] [--json] [--color=auto|always|never]", "person only: register work that belongs to ANOTHER project that runs agent-hub on that project's board (an ownerless proposal its own roles take from there); the target must be registered and running, nothing is queued; a feature or behavior change first needs a spec issue there (--issue); its state changes show in ahub board --handoffs (an agent that hands off gets them as task messages)"],
     ["ahub backlog list [--json] [--full] [--color=auto|always|never] | add <class> <title...> | plan <id> <revision> <fields-json> <reason...> | pin <id> <revision> true|false <reason...> | undo <id> <revision> [--json] [--color=auto|always|never]", "person only: plan work with a reason; {} records a note-only revision, fields.sdlc sets backlog repo/issue identity and clears old spec acceptance; preserve pins/frozen scope and refuse stale edits; list is by rank (--json: raw listing)"],
     ["ahub release new <name> <goal> <order> | list | show <name> | plan <name> <revision> <dates-json> | activate|freeze|ship|drop <name> <revision> [--json] [--color=auto|always|never]", "person only, except show (any agent, public metadata): planned UTC millisecond dates and phased scope; ship records a time after approval, never tags or publishes"],
     ["ahub backlog split <id> <revision> <parts-json> <reason...> [--json] [--color=auto|always|never]", "person only: stage2..8 child prerequisites; original task retains integration, undo refuses used or changed children"],
@@ -104,6 +106,8 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub intake \"<text>\" [--source <id>...] | approve <id> | discard <id> [--json] [--color=auto|always|never]", "person only, except approve (person or configured conductor): turn a plain request into a draft backlog card that nothing offers or pulls until you approve it; the configured planner is asked to split it with hub_backlog_split, or the hub model proposes the split (a PII request only on an on-prem model, never to a planner); each --source must be a registered src: id; approve clears the draft on it and its parts, discard cancels them through task cancel"],
     ["ahub capabilities [--json] [--color=auto|always|never]", "person only, never a conductor or an agent shell: list the skills and commands each attached peer offers (Kimi 2.3.2 and Qwen 0.26.1 sessions, Codex 0.166.0 skills; other versions list nothing), whether you share each one, its digest and the class a call would count as; sharing is invocation.share in .agenthub/config.local.json, this machine only; it only lists and never calls anything"],
     ["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 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

@@ -22,10 +22,13 @@ export function liveTestRefusal(command: string, args: readonly string[], contex
     || (command === "room" && !["list", "status"].includes(sub ?? ""))
     || (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 === "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"
     // #691: trusting an untested agent CLI version is the person's consent, never a delegated live-test operation.
+    || command === "autonomy"
     || (command === "agents" && !args.every(arg => arg === "--json"));
 }
 
@@ -81,6 +84,8 @@ const peerReadForms: Readonly<Record<string, Readonly<Record<string, PeerReadFor
   // #814 renders these reads for people and keeps JSON as an explicit data format.
   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 } },
   projects: { "": {} },
   models: { status: {} },
   recovery: { status: { positional: 1 } },
@@ -190,8 +195,10 @@ export function cliCommandLabel(command: string, args: readonly string[], catalo
   if (command === "capabilities") return "capabilities"; // #445 C1: no argument is ever echoed into the audit
   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 === "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"].includes(command)) return "unknown";
+  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)) {
     const sub = command === "bench" || command === "memory" || command === "goal" ? args.find((arg) => arg !== "--json") : args[0];
     if (sub && ["propose", "show", "assign", "unassign", "escalate", "cancel", "claim", "label", "list", "add", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "reattach", "setup", "start", "stop", "remove", "discard", "export", "backfill", "addons", "run", "report", "compare", "search", "graph", "promote", "demote", "forget", "supersede", "dedupe", "decay", "rebuild", "sync", "machine", "import", "suggestions", "confirm", "reject", "new", "link", "state", "done", "take", "trust"].includes(sub)) return `${command} ${sub}`;

package/src/cli/main.ts

@@ -16,7 +16,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,8 +28,20 @@ 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";
+import { readAutonomyDefaults, writeAutonomyDefaults } from "../hub/autonomy-defaults.ts";
+import { inheritMachineAutonomy, prepareAutonomyProject, runAllProjectAutonomy, type PreparedAutonomyProject } from "./autonomy-projects.ts";
+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";
@@ -44,7 +56,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";
@@ -1006,47 +1018,48 @@ const commands: Record<string, () => Promise<void> | void> = {
     recoveryLauncherCurrent?.();
     assertLifecycleAvailable();
     const root = join(import.meta.dir, "..", "..");
-    const state = () => {
-      const out = (argv: string[]) => { recoveryLauncherCurrent?.(); const result = spawnSync("claude", argv, { encoding: "utf8", ...(recoveryLauncherCurrent ? { timeout: 30_000 } : {}) }); recoveryLauncherCurrent?.(); return result.stdout ?? ""; };
-      return nextStep(parseList<InstalledPlugin>(out(["plugin", "list", "--json"])), parseList<Marketplace>(out(["plugin", "marketplace", "list", "--json"])), root);
-    };
-    let step = state();
-    if (!step) console.log(`Claude Code plugin agent-hub@agent-hub ${VERSION} is installed from this package.`);
-    else {
-      console.log(`ahub setup changes your Claude Code plugin configuration, one step at a time, re-checking after each. First step:\n  ${step.argv.join(" ")}\n      ${step.why}`);
-      if (!args.includes("--yes")) {
-        // Nobody can answer without a terminal: waiting would hang a script forever (issue #73).
-        if (!process.stdin.isTTY) fail("not a terminal: nothing was changed; rerun with --yes to apply");
-        const rl = createInterface({ input: process.stdin, output: process.stdout });
-        const answer = (await rl.question("Proceed (this and the steps that follow from it)? [y/N] ")).trim().toLowerCase();
-        rl.close();
-        if (answer !== "y" && answer !== "yes") return console.log("nothing was changed");
-      }
-      for (let i = 0; step && i < 6; i++, step = state()) {
-        console.log(`> ${step.argv.join(" ")}   (${step.why})`);
-        recoveryLauncherCurrent?.();
-        if (spawnSync(step.argv[0]!, step.argv.slice(1), { stdio: "inherit", ...(recoveryLauncherCurrent ? { timeout: 30_000 } : {}) }).status !== 0) fail(`"${step.argv.join(" ")}" failed; nothing after it was run`);
-        recoveryLauncherCurrent?.();
-      }
-      if (step) fail(`still not done after 6 steps; next would be: ${step.argv.join(" ")}`);
-    }
+    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(); },
+        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; },
+      });
+    } 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!();
   },
 
-  init: () => {
+  init: async () => {
     const flags = takeFlags(args.filter(arg => arg !== "--dry-run" && arg !== "--json" && arg !== "--shadow" && arg !== "--release-guard"), ["--profile"], []);
     if (flags.rest.length) fail("usage: ahub init [--profile dev|research|writing|general|<pack>] [--shadow] [--release-guard] [--dry-run --json]");
     // A pack is a project file in .agenthub/roles/<name>.pack.json (#513a); init resolves the name and refuses an unknown one with the profiles and packs it knows.
     const requestedProfile = flags.one["--profile"];
+    const newProject = !existsSync(join(cwd, ".agenthub/config.json"));
     if (args.includes("--dry-run")) {
       const plan = planInit(cwd, requestedProfile, args.includes("--shadow"), args.includes("--release-guard"));
+      const defaults = readAutonomyDefaults(hubHome(), [cwd]);
+      if (newProject && defaults.enabled) plan.push({ action: existsSync(join(cwd, ".agenthub/config.local.json")) ? "modify" : "create", path: join(cwd, ".agenthub/config.local.json"), reason: "inherit the trusted machine autonomy preset; consent is checked at daemon startup" });
+      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();
+    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"));
-    registeredProject();
+    const project = registeredProject();
     console.log(changed.length ? changed.map((p) => `${existsSync(p) ? "wrote" : "removed"} ${p}`).join("\n") : "already up to date");
+    if (newProject) {
+      const registry = new Registry();
+      try { for (const line of await inheritMachineAutonomy(project, hubHome(), autonomyEnvironment(process.env, !!process.stdin.isTTY), registry)) console.log(terminalText(line)); }
+      finally { registry.close(); }
+    }
     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")));
   },
@@ -1452,6 +1465,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);
@@ -1525,6 +1572,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>");
@@ -1768,7 +1820,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");
@@ -1890,6 +1951,68 @@ const commands: Record<string, () => Promise<void> | void> = {
       printOutput([[{ text: result.text }]], options.color);
     } finally { hub.close(); }
   },
+  autonomy: async () => {
+    let hub: ControlClient | undefined;
+    let prepared: PreparedAutonomyProject | undefined, previewToken: string | undefined;
+    const registry = new Registry();
+    const rl = process.stdin.isTTY ? createInterface({ input: process.stdin, output: process.stdout }) : undefined;
+    try {
+      const environment = autonomyEnvironment(process.env, !!process.stdin.isTTY), home = hubHome();
+      if (args.includes("--all-projects")) {
+        assertLifecycleAvailable();
+        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)),
+        });
+        return;
+      }
+      const roots = [...registry.list().map(project => project.root), cwd], defaults = readAutonomyDefaults(home, roots);
+      const usage = await runAutonomy(args, {
+        environment,
+        request: async message => {
+          if (message.action === "preview") {
+            prepared?.close();
+            prepared = await prepareAutonomyProject(registeredProject(), environment, true, registry);
+            previewToken = randomUUID();
+            return { ok: true, confirmation: previewToken, lines: prepared.lines };
+          }
+          if (message.action === "on") {
+            if (!prepared || message.confirmation !== previewToken) return { ok: false, error: "autonomy preview is stale or missing" };
+            previewToken = undefined;
+            return { ok: true, lines: await prepared.apply() };
+          }
+          if (message.action === "off") {
+            prepared = await prepareAutonomyProject(registeredProject(), environment, false, registry);
+            return { ok: true, lines: await prepared.apply() };
+          }
+          const project = registry.list().find(row => row.root === cwd && row.stateDir === stateDir);
+          if (project && (await inspectProject(project)).state === "stopped") return offlineAutonomyStatus(project, environment);
+          hub ??= await connect(); return hub.request(message, 35_000);
+        },
+        ask: async prompt => { if (!rl) return null; try { return await rl.question(prompt); } catch { return null; } },
+        print: line => console.log(terminalText(line)),
+        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();
+          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}.`);
+        },
+        decorateStatus: async reply => {
+          const machine = readAutonomyDefaults(home, roots);
+          const profiles = await autonomyHomeStatus(registry, homedir(), process.env, join(import.meta.dir, "..", ".."), (argv, options) => {
+            const result = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8", env: options.env, timeout: options.timeoutMs, maxBuffer: 1024 * 1024 });
+            return { status: result.status ?? -1, stdout: result.stdout ?? "" };
+          });
+          return { ...reply, status: { ...(reply.status as Record<string, unknown>), machineDefault: { enabled: machine.enabled, ...(machine.notice ? { notice: machine.notice } : {}) }, claudeHomes: profiles.homes, claudeHomeDiscoveryComplete: profiles.complete, claudeHomeNotices: profiles.notices },
+            lines: [...(reply.lines as string[]), `Machine autonomy default: ${machine.enabled ? "on" : "off"}.`, ...(machine.notice ? [machine.notice] : []), ...profiles.notices,
+              ...profiles.homes.map(profile => `Claude home ${profile.home.path}: plugin ${profile.plugin.state}; hook ${profile.hook.state}. ${profile.hook.reason}`)] };
+        },
+      });
+      if (usage) fail(usage);
+    } finally { prepared?.close(); rl?.close(); hub?.close(); registry.close(); }
+  },
   settings: async () => {
     // #689: structural config edits (instances, review, snapshots, approvals, context.gate, sdlc.toml) and their backups. The hub validates and writes.
     if (args[0] === "edit" || args[0] === "backups") {
@@ -1983,6 +2106,11 @@ const commands: Record<string, () => Promise<void> | void> = {
         if (typeof undoDef === "string" && settingScopeError) fail(`pending undo ${String(view.undo)}: ${undoDef}; the project config could not be read: ${settingScopeError}`);
         const rosterPeer = typeof undoDef !== "string" && undoDef.group === "Roster" ? undoDef.path[1] : undefined;
         let confirm: string | undefined;
+        if (typeof undoDef !== "string" && undoDef.managed === "autonomy") {
+          if (!process.stdin.isTTY) fail("undoing project autonomy requires a person's terminal confirmation");
+          const rl = createInterface({ input: process.stdin, output: process.stdout });
+          try { confirm = (await rl.question("Type autonomy to undo the complete preset change: ")).trim(); } finally { rl.close(); }
+        }
         if (rosterPeer) {
           if (!process.stdin.isTTY) fail("undoing a roster setting needs confirmation in a terminal; use ahub settings set for an explicit scripted change");
           const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -2586,11 +2714,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.
@@ -2600,6 +2728,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