@staix/agent-hub 0.23.1 → 0.25.0

package/src/adapters/claude-channel.ts

@@ -12,7 +12,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { ControlClient, INVOCATION_CONTROL_TIMEOUT_MS, stateDirFor } from "../hub/control-client.ts";
+import { ControlClient, INVOCATION_CONTROL_TIMEOUT_MS } from "../hub/control-client.ts";
+import { channelProject } from "../hub/channel-project.ts";
 import { VERSION } from "../version.ts";
 import { IMPLEMENTER_HUB_TOOL_NAMES, IMPLEMENTER_PERMISSION_TOOL, ACTIONABLE_MESSAGE_INSTRUCTION, projectConductorTools, projectToolList, CONDUCTOR_TOOL_NAMES, DEFAULT_ROLES, roleContract, TASK_TOOL_NAMES, TASK_TOOLS, profileTaskTools } from "../hub/hub-tools.ts";
 import { frame, replyParent, sanitize, HUB_MESSAGE_INSTRUCTION, type Envelope } from "../hub/envelope.ts";
@@ -22,8 +23,23 @@ import { acceptsNativePermissionRequest, buildNativePermissionProbe, NATIVE_PERM
 // A native session is pinned at launch. Unlike a new CLI invocation after `cd`,
 // its MCP server must not silently move to another hub (including while offline).
 // ControlClient verifies the manifest identity on every connection.
-const stateDir = process.env.AGENTHUB_STATE_DIR ?? stateDirFor(process.cwd());
-const projectRoot = process.env.AGENTHUB_PROJECT_DIR ?? process.cwd();
+//
+// agent-hub#1036: which project this plugin joins is decided by `channelProject`, the same decision the CLI makes at startup. An inherited AGENTHUB_STATE_DIR is used as the peer only when the
+// root recorded in it equals the resolved root of this process's cwd, or (a declared extra instance) when its managed worktree is this cwd. A session started in `<repo>/.worktrees/<name>`
+// uses its own project. A session with no project of its own that inherited another project's state joins THAT hub as a distinct session (`<peer>~<id>`, minted by the hub): it can send and
+// read, holds none of the peer's roles, and never replaces the attached session. Nothing is refused. Limit: this makes sessions distinguishable, it does not authenticate them.
+const own = channelProject(process.cwd(), process.env, root => {
+  const read = (name: string) => { try { return JSON.parse(readFileSync(join(root, ".agenthub", name), "utf8")).roles ?? {}; } catch { return {}; } };
+  return { ...DEFAULT_ROLES, ...read("config.json"), ...read("config.local.json") };
+});
+/** Set when this process joins as a distinct session. The hub's answer names the minted id; until then the session is only "a session". */
+const sessionJoin = own?.session;
+/** A hub that predates `session_identity` would ignore the request and bind the real peer id, which is the takeover this exists to prevent: such a session does not connect, and says why. */
+const NO_SESSION_SUPPORT = "this process has no project of its own and the hub it inherited predates session identities, so it would be taken for the peer it names; restart the hub (ahub restart) or start this session from its own project";
+const NO_PROJECT = "agent-hub has no hub to join: this process has no project of its own and inherited no state directory. Start it from a project that runs agent-hub.";
+if (process.env.AGENTHUB_STATE_DIR && own && !own.inherited && !own.session) console.error(`[agent-hub] ignoring an inherited AGENTHUB_STATE_DIR: it records another project, not ${own.root}. Using this project's own hub.`);
+const stateDir = own?.stateDir ?? "";
+const projectRoot = own?.root ?? "";
 /** tools mode: the same server, run by Kimi (ACP mcpServers), Codex (mcp_servers override) or Jcode. Their messages arrive through their own adapters, so no channel here. Not the "tools-only" Claude below. */
 const toolsMode = process.env.AGENTHUB_MODE === "tools";
 const permissionTool = toolsMode && process.env.AGENTHUB_PERMISSION_TOOL === "1";
@@ -111,6 +127,10 @@ const INBOX_CAP = 200;
  * whoever said hello last, so reconnecting blind would evict the session that just took it and the two
  * would trade the peer forever. This file is advisory: a standby hello also checks live ownership at the daemon.
  */
+/** Whether the hub this process would join as a session knows `session_identity`, from the daemon's own status file. Unknown reads as unsupported. */
+function sessionSupported(): boolean {
+  try { return (JSON.parse(readFileSync(join(stateDir, "status.json"), "utf8")).features ?? []).includes("session_identity"); } catch { return false; }
+}
 function peerHeld(): boolean {
   try {
     const status = JSON.parse(readFileSync(join(stateDir, "status.json"), "utf8")) as { peers?: Record<string, { state?: string; claiming?: boolean; toolsOnly?: string }> };
@@ -266,7 +286,8 @@ async function connectLoop(): Promise<void> {
         try { executionCwd = realPath(process.cwd()); }
         catch { /* A removed native cwd revokes root evidence, never the messaging connection. */ }
       }
-      const client = await ControlClient.connect(stateDir, { role: toolsMode ? "tools" : "peer", peer: peerId, ...(toolsMode ? {} : { channel }),
+      const client = await ControlClient.connect(stateDir, { role: toolsMode || sessionJoin ? "tools" : "peer", peer: peerId, ...(toolsMode || sessionJoin ? {} : { channel }),
+        ...(sessionJoin ? { session: sessionJoin.label } : {}),
         ...(process.env.AGENTHUB_LAUNCH_ID ? { launchId: process.env.AGENTHUB_LAUNCH_ID } : {}),
         ...(executionCwd !== undefined ? { cwd: executionCwd } : {}),
         ...(!toolsMode && standingBy ? { standby: true } : {}),
@@ -293,7 +314,7 @@ async function connectLoop(): Promise<void> {
       attempt = -1;
       standingBy = false;
       detached = undefined;
-      log(`connected to hub as "${peerId}"`);
+      log(sessionJoin ? `connected to hub as the distinct session "${client.sessionId ?? "?"}", not as "${peerId}": it can send and read, and holds none of ${peerId}'s roles` : `connected to hub as "${peerId}"`);
       // The tool list depends on the connected hub (its lifecycle): when it differs from what the host last listed,
       // ask the host to list it again (#490).
       if (listedTools !== undefined) void reannounce(client).catch(() => {});
@@ -394,6 +415,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 async function callTool(req: { params: { name: string; arguments?: Record<string, unknown> } }, signal?: AbortSignal) {
   const { name, arguments: args } = req.params;
   if (unidentified) return { ...text(UNIDENTIFIED), isError: true };
+  if (!own) return { ...text(NO_PROJECT), isError: true };
+  if (sessionJoin && !sessionSupported()) return { ...text(NO_SESSION_SUPPORT), isError: true };
   if (permissionTool && !IMPLEMENTER_HUB_TOOL_NAMES.includes(name)) return { ...text("tool unavailable to this owned implementer child"), isError: true };
   if (name === "hub_permission_request") {
     const deny = (message: string) => text(JSON.stringify({ behavior: "deny", message }));
@@ -473,4 +496,4 @@ await server.connect(new StdioServerTransport());
 // The host (Claude Code, Codex, Kimi) talks over stdin; once it is gone nothing can use this server, and a leftover would keep reconnecting.
 process.stdin.on("end", () => process.exit(0));
 process.stdin.on("close", () => process.exit(0));
-if (unidentified) log(UNIDENTIFIED); else void connectLoop();
+if (unidentified) log(UNIDENTIFIED); else if (!own) log(NO_PROJECT); else if (sessionJoin && !sessionSupported()) log(NO_SESSION_SUPPORT); else void connectLoop();

package/src/adapters/compat.ts

@@ -34,11 +34,11 @@ export const COMPAT = {
     parse: out => plain(out.trim()),
     trustNote: "The model-free extension load, RPC session identity and managed tool receipt path were checked on 1.4.0. Permissions remain host-owned; account-backed inference and another version's extension contract are unverified.",
     receipt: "docs/verification/2026-10-26-pi-140-compat.md" },
-  // Transport receipts: docs/verification/2026-10-23-headless-claude-permissions.md; 2.1.310: docs/verification/2026-10-26-claude-implementer-2.1.310.md; 2.1.314 (transport and wrapper): docs/verification/2026-10-31-claude-implementer-2.1.314.md; host-wrapper receipt below repeats with them.
-  "claude-implementer": { label: "Claude headless implementer", verified: ["2.1.309", "2.1.310", "2.1.314"], gate: "contract", probe: ["claude", "--version"],
+  // Transport receipts: docs/verification/2026-10-23-headless-claude-permissions.md; 2.1.310: docs/verification/2026-10-26-claude-implementer-2.1.310.md; 2.1.314 (transport and wrapper): docs/verification/2026-10-31-claude-implementer-2.1.314.md; 2.1.316: docs/verification/2026-10-31-claude-implementer-2.1.316.md; host-wrapper receipt below repeats with them.
+  "claude-implementer": { label: "Claude headless implementer", verified: ["2.1.309", "2.1.310", "2.1.314", "2.1.316"], gate: "contract", probe: ["claude", "--version"],
     parse: out => plain(out.trim().replace(/ \(Claude Code\)$/, "")),
     trustNote: "The native prompt-tool transport and host-wrapper rewrite, environment isolation and replay contract have isolated receipts. No dontAsk/bypass fallback exists; another version's permission or rewrite behavior is unverified.",
-    receipt: "docs/verification/2026-10-31-claude-implementer-2.1.314.md" },
+    receipt: "docs/verification/2026-10-31-claude-implementer-2.1.316.md" },
   // 0.163.0 receipt: docs/verification/2026-10-22-codex-reviewer-isolation.md; 0.164.0 receipt: docs/verification/2026-10-24-codex-0164-reviewer-isolation.md; 0.166.0: docs/verification/2026-10-31-codex-0166-reviewer-isolation.md
   "codex-review": { label: "Codex reviewer (codex-cli)", verified: ["0.146.0", "0.163.0", "0.164.0"], gate: "isolation", probe: ["codex", "--version"], config: "codex_bin",
     parse: out => plain(out.trim().replace(/^codex-cli /, "")),

package/src/adapters/definitions/native-cli-claude-setup.ts

@@ -4,6 +4,10 @@ import { realPath } from "../../hub/project.ts";
 import { VERSION } from "../../version.ts";
 
 export const PLUGIN = "agent-hub@agent-hub";
+export const CLAUDE_PLUGIN_INVENTORY = Object.freeze({
+  plugins: Object.freeze(["claude", "plugin", "list", "--json"]),
+  marketplaces: Object.freeze(["claude", "plugin", "marketplace", "list", "--json"]),
+});
 const MARKETPLACE = "agent-hub";
 
 export interface InstalledPlugin {

package/src/adapters/definitions/native-cli-doctor.ts

@@ -8,6 +8,36 @@ const nativeTools = [
 ] as const;
 export const DOCTOR_TOOL_PROBES: readonly string[] = Object.freeze(["bun", ...nativeTools.filter(tool => tool.initial).map(tool => tool.id)]);
 export const DOCTOR_MEMORY_CAPTURE_PEERS = Object.freeze(["codex", "kimi"] as const);
+/**
+ * What one read of agent-mem's own setup state gave (`amem setup <tool> --json`, a preview that writes nothing): the parsed plan, or why there is none. Agent-mem owns the state;
+ * doctor never reads dotfiles text or a client's config itself (#1008).
+ */
+export type MemorySetupReading = { kind: "read"; plan: unknown } | { kind: "unavailable"; reason: string };
+
+/**
+ * One memory-capture doctor row from agent-mem's structured setup plan: `applied` (the hub's receipt matches and the MCP entry and hooks are as setup would write them), `pending`
+ * (setup would add or replace something, so `amem setup <tool> --apply` is the fix), or `client missing` (the native CLI is not installed). A reading that cannot be trusted as the shape
+ * agent-mem documents is unknown, never ready: the row says it could not be read instead of guessing. Pure: the plan is data, never text, and nothing here runs a process.
+ * Codex also needs the person's native `/hooks` review before a newly registered hook runs, which agent-mem's setup does not grant, so an applied Codex row says so.
+ */
+export function nativeMemoryCaptureRow(tool: string, reading: MemorySetupReading): { ok: boolean | undefined; detail: string } {
+  const unknown = (why: string) => ({ ok: undefined, detail: `unknown (${why})` });
+  if (reading.kind !== "read") return unknown(reading.reason);
+  const plan = reading.plan as { mode?: unknown; actions?: unknown } | null;
+  const actions = plan && typeof plan === "object" && plan.mode === "preview" && Array.isArray(plan.actions) ? plan.actions : undefined;
+  const action = actions?.length === 1 ? actions[0] as Record<string, unknown> | null : undefined;
+  if (!action || typeof action !== "object" || action.target !== tool || typeof action.available !== "boolean" || !["add", "replace", "restore", "unchanged"].includes(String(action.mcpChange)))
+    return unknown("`amem setup " + tool + " --json` did not return the setup plan it documents");
+  if (action.available === false) return { ok: false, detail: `client missing: the ${tool} CLI is not installed, so there is nothing to set up` };
+  const setup = `amem setup ${tool} --apply`;
+  if (action.mcpChange !== "unchanged") {
+    const state = typeof action.state === "string" ? action.state.slice(0, 60).replace(/[^\x20-\x7e]/g, "?") : "unknown";
+    return { ok: false, detail: `not set up (${state}); run \`${setup}\`` };
+  }
+  const hooks = tool === "codex" ? "; newly registered hooks need the native /hooks review in Codex before they run (amem setup does not grant hook trust)" : "";
+  return { ok: true, detail: `set up, per \`amem setup ${tool}\`${hooks}` };
+}
+
 export const DOCTOR_PLUGIN_PROBE = Object.freeze({ command: "claude", argv: Object.freeze(["plugin", "list", "--json"] as const), name: "claude plugin" });
 
 /** Exact legacy section and severity classification, including non-native and unknown diagnostic names. */

package/src/adapters/jcode.ts

@@ -210,6 +210,9 @@ export class JcodePeer extends AcpPeer {
   }
 
   /** True only for the id of this peer's current owned launch, while it is not ending: the proof a hub-tools hello must carry (#368). */
+  /** The id of this peer's current owned launch, for the provenance of what it publishes (agent-hub#1036). Evidence for the log, never a credential: nothing admits a connection by reading it. */
+  get ownedLaunchId(): string | undefined { return this.ending ? undefined : this.launchId; }
+
   ownsLaunch(launchId: unknown): boolean { return !this.ending && typeof launchId === "string" && launchId === this.launchId; }
 
   override async start(): Promise<void> {

package/src/adapters/registry.ts

@@ -292,7 +292,7 @@ export function builtinPreviewOf(id: string) {
 }
 
 /** Fixed builtin doctor metadata and pure observed-value projections; the CLI retains all probe effects. */
-export { DOCTOR_TOOL_PROBES, DOCTOR_MEMORY_CAPTURE_PEERS, DOCTOR_PLUGIN_PROBE, nativeDoctorCheck, nativeDoctorRecoveryIdentity, nativeDoctorOptionalProbes } from "./definitions/native-cli-doctor.ts";
+export { DOCTOR_TOOL_PROBES, DOCTOR_MEMORY_CAPTURE_PEERS, DOCTOR_PLUGIN_PROBE, nativeDoctorCheck, nativeMemoryCaptureRow, type MemorySetupReading, nativeDoctorRecoveryIdentity, nativeDoctorOptionalProbes } from "./definitions/native-cli-doctor.ts";
 
 /** Definition-owned CLI entries are restricted to fixed builtins, never config or external execution extensions. */
 export const BUILTIN_CLI_ENTRIES = Object.freeze(builtinCliEntries(ADAPTERS).map(entry => {

package/src/cli/acon-register.ts

@@ -0,0 +1,29 @@
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+
+/** Where `ahub setup` registers the acon plugin (#935): acon reads $AGENTHUB_HOME/console/plugins/<tool>.json. */
+export function aconManifestPath(home: string): string {
+  return join(home, "console", "plugins", "ahub.json");
+}
+
+/**
+ * Write the acon registration for this package's plugin module with its sha256, so acon refuses a module that changed
+ * after setup. The directory is created 0700; the file is replaced atomically. Returns what was written, or why not.
+ */
+export function registerAconPlugin(home: string, module: string): { path: string; changed: boolean } | { error: string } {
+  if (!existsSync(module)) return { error: `acon plugin module ${module} is missing` };
+  const dir = join(home, "console", "plugins");
+  for (const part of [join(home, "console"), dir]) {
+    if (!existsSync(part)) mkdirSync(part, { mode: 0o700 });
+    if (!lstatSync(part).isDirectory()) return { error: `${part} is not a directory` };
+    chmodSync(part, 0o700);
+  }
+  const path = aconManifestPath(home);
+  const body = `${JSON.stringify({ api: 1, tool: "ahub", module, sha256: createHash("sha256").update(readFileSync(module)).digest("hex") })}\n`;
+  if (existsSync(path) && readFileSync(path, "utf8") === body) return { path, changed: false };
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, body, { mode: 0o600 });
+  renameSync(temp, path);
+  return { path, changed: true };
+}

package/src/cli/autonomy-homes.ts

@@ -0,0 +1,33 @@
+import { readControl } from "../hub/control-client.ts";
+import { readInstanceRoleConfig } from "../hub/instance-config.ts";
+import type { Registry } from "../hub/registry.ts";
+import { checkClaudeHome, discoverClaudeHomes, type ClaudeHomeProject, type ClaudeHomeProbe } from "./claude-homes.ts";
+import { checkClaudeProfileHook } from "./claude-profile-hook.ts";
+
+export async function usedClaudeHomes(registry: Registry, home: string, env: NodeJS.ProcessEnv) {
+  const projects: ClaudeHomeProject[] = [], notices: string[] = [];
+  const registered = registry.list();
+  if (registered.length > 256) notices.push("Claude profile discovery is limited to the first 256 registered projects.");
+  for (const project of registered.slice(0, 256)) {
+    const control = readControl(project.stateDir);
+    if (!control?.instanceId) continue;
+    try {
+      const scope = readInstanceRoleConfig(project.root);
+      const ids = [...new Set([...scope.catalog.definitions.map(definition => definition.kind), ...Object.keys(scope.instances ?? {})])];
+      const claudePeers = ids.filter(id => scope.catalog.definitionOf(id, scope.instances)?.transport === "claude-channel");
+      projects.push({ root: project.root, stateDir: project.stateDir, instanceId: control.instanceId, claudePeers });
+    } catch { notices.push(`Claude profile evidence is unavailable for project ${project.id}.`); }
+  }
+  const found = await discoverClaudeHomes({ home, env, projects });
+  return { ...found, complete: found.complete && !notices.length, notices: [...notices, ...found.notices] };
+}
+export async function autonomyHomeStatus(registry: Registry, home: string, env: NodeJS.ProcessEnv, packageRoot: string, probe: ClaudeHomeProbe) {
+  const found = await usedClaudeHomes(registry, home, env), deadline = performance.now() + 6000;
+  const homes = [];
+  for (const selected of found.homes) {
+    const remaining = Math.floor(deadline - performance.now());
+    if (remaining < 1) homes.push({ home: selected, plugin: { state: "unknown", reason: "The machine profile inventory time bound was reached." }, hook: checkClaudeProfileHook(selected) });
+    else homes.push(await checkClaudeHome(selected, packageRoot, env, probe, Math.min(remaining, 6000)));
+  }
+  return { homes, notices: found.notices, complete: found.complete && performance.now() <= deadline };
+}

package/src/cli/autonomy-offline.ts

@@ -0,0 +1,75 @@
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { planAutonomy, autonomyRemovalKeys, autonomyStatus, autonomyPreset, type AutonomyOperation, type AutonomyPeer, type AutonomyFloorStatus } from "../hub/autonomy.ts";
+import { configFingerprint, configSourceTexts } from "../hub/config-reload.ts";
+import { configRefusal } from "../hub/config-trust.ts";
+import { loadConfig } from "../hub/daemon.ts";
+import { validateEffectiveConfig } from "../hub/config-apply.ts";
+import { readInstanceConfigLayers, readInstanceRoleConfig } from "../hub/instance-config.ts";
+import { checkSettingValue, settingDef, settingText, writeAutonomyPreset } from "../hub/settings.ts";
+import type { Project } from "../hub/registry.ts";
+
+export interface OfflineAutonomyPlan { fingerprint: string; operations: AutonomyOperation[]; lines: string[] }
+type Target = Pick<Project, "root" | "stateDir">;
+function scopeOf(root: string) {
+  const directory = lstatSync(join(root, ".agenthub"), { throwIfNoEntry: false });
+  if (!directory?.isDirectory() || directory.isSymbolicLink() || directory.uid !== process.getuid?.() || (directory.mode & 0o022) !== 0) throw new Error("project configuration directory is unsafe; autonomy was not changed");
+  const local = lstatSync(join(root, ".agenthub/config.local.json"), { throwIfNoEntry: false });
+  if (local && (!local.isFile() || local.isSymbolicLink() || local.nlink !== 1 || local.uid !== process.getuid?.() || (local.mode & 0o022) !== 0)) throw new Error("project config.local.json is unsafe; autonomy was not changed");
+  const refusal = configRefusal(root, "config.local.json");
+  if (refusal) throw new Error(refusal);
+  const scope = readInstanceRoleConfig(root);
+  // Runtime module policy is captured only by the daemon, never imported by a file writer.
+  if (scope.adapter_modules?.length) throw new Error("this project uses adapter modules; start its hub before applying autonomy");
+  const config = loadConfig(root);
+  validateEffectiveConfig(config, scope.catalog);
+  const ids = [...new Set([...scope.catalog.definitions.map(definition => definition.kind), ...Object.keys(scope.instances ?? {})])]
+    .filter(id => scope.catalog.isSupportedPeer(id, scope.instances));
+  const peers: AutonomyPeer[] = ids.map(id => {
+    const definition = scope.catalog.definitionOf(id, scope.instances)!;
+    return { id, kind: definition.kind, unmanaged: !!definition.permission.unmanaged, ...(scope.instances?.[id]?.start_mode ? { form: scope.instances[id]!.start_mode } : {}) };
+  });
+  return { scope, peers };
+}
+/** Read-only preview. The caller must hold the stopped project's registry claim while applying it. */
+export function planOfflineAutonomy(project: Target, environment: string, enabled: boolean): OfflineAutonomyPlan {
+  const { scope, peers } = scopeOf(project.root);
+  const operations = enabled ? planAutonomy(environment, key => {
+    const def = settingDef(key, scope.instances, scope.catalog);
+    return typeof def === "string" || def.store !== "config" ? undefined : { store: def.store, values: def.values, locked: def.locked };
+  }, peers) : autonomyRemovalKeys(peers).map(key => ({ key, value: null, store: "config" as const }));
+  for (const operation of operations) if (enabled) {
+    const def = settingDef(operation.key, scope.instances, scope.catalog);
+    if (typeof def === "string") throw new Error(def);
+    checkSettingValue(def, operation.value);
+  }
+  return { fingerprint: configFingerprint(configSourceTexts(project.root)), operations,
+    lines: operations.map(operation => `${operation.key}: ${enabled ? settingText(operation.value) : "inherit"} (next hub/peer start)`) };
+}
+/** No consent or witnesses are created here. A trusted machine opt-in is checked independently by the next daemon. */
+export function applyOfflineAutonomy(project: Target, environment: string, enabled: boolean, preview: OfflineAutonomyPlan): string[] {
+  const current = planOfflineAutonomy(project, environment, enabled);
+  if (preview.fingerprint !== current.fingerprint || JSON.stringify(preview.operations) !== JSON.stringify(current.operations)) throw new Error("project autonomy preview changed; nothing was written");
+  const { scope } = scopeOf(project.root);
+  const result = writeAutonomyPreset(project.root, project.stateDir, enabled, current.operations, scratch => {
+    // Keep original project path/trust semantics while validating the candidate bytes.
+    const candidate = loadConfig(project.root, readInstanceConfigLayers(scratch));
+    validateEffectiveConfig(candidate, scope.catalog);
+  });
+  return [`Project autonomy ${enabled ? "on" : "off"}: ${result.changed ? "saved" : "unchanged"}; applies at the next hub/peer start.`,
+    "Permission confirmation is checked against the trusted machine default when the hub starts."];
+}
+
+/** Stopped-hub status reports preset intent, never a claimed effective native mode or consent. */
+export function offlineAutonomyStatus(project: Target, environment: string): Record<string, unknown> {
+  try {
+    const { peers } = scopeOf(project.root);
+    const floorEnforcement = Object.fromEntries(peers.map(peer => [peer.id, Object.fromEntries(autonomyPreset().floorClasses.map(action => [action,
+      { class: action, status: "not-enforced", reason: "The hub is stopped; runtime floor enforcement is unverified." } satisfies AutonomyFloorStatus]))]));
+    const rows = autonomyStatus({ environment, peers, floorEnforcement });
+    return { ok: true, status: { environment, runtime: "stopped", consentState: "unknown", consentedPeers: [], peers: rows },
+      lines: ["The hub is stopped; effective runtime modes and retained consent are unknown.", ...rows.map(row => `${row.id}: ${row.effectiveMode}; preset ${row.nextMode ?? "unmanaged"} at ${row.applies}`)] };
+  } catch {
+    return { ok: true, status: { environment, runtime: "stopped", consentState: "unknown", consentedPeers: [], peers: [], missing: ["Project configuration could not be safely inspected."] }, lines: ["The hub is stopped and its project configuration could not be safely inspected; runtime modes and consent are unknown."] };
+  }
+}

package/src/cli/autonomy-projects.ts

@@ -0,0 +1,103 @@
+import { randomUUID } from "node:crypto";
+import { relative, resolve } from "node:path";
+import { readAutonomyDefaults, writeAutonomyDefaults } from "../hub/autonomy-defaults.ts";
+import { autonomyConsentStateDir, createAutonomyConsent } from "../hub/autonomy-consent.ts";
+import { canonicalPath, hubHome } from "../hub/project.ts";
+import { insideRoot } from "../hub/path-policy.ts";
+import { readInstanceRoleConfig } from "../hub/instance-config.ts";
+import { ControlClient } from "../hub/control-client.ts";
+import { inspectProject } from "../hub/lifecycle.ts";
+import { processSignature } from "../pi/process-signature.ts";
+import type { Project, Registry } from "../hub/registry.ts";
+import { applyOfflineAutonomy, planOfflineAutonomy } from "./autonomy-offline.ts";
+
+export interface PreparedAutonomyProject { lines: string[]; apply(): Promise<string[]>; close(): void }
+export interface AllProjectAutonomyPorts {
+  home: string;
+  environment: string;
+  projects: readonly Project[];
+  prepare(project: Project, enabled: boolean): Promise<PreparedAutonomyProject>;
+  ask(prompt: string): Promise<string | null>;
+  print(line: string): void;
+}
+/** Init is already person-only. Inheritance writes no consent and starts no daemon. */
+export async function inheritMachineAutonomy(project: Project, home: string, environment: string, registry: Registry): Promise<string[]> {
+  const defaults = readAutonomyDefaults(home, registry.list().map(row => row.root));
+  if (defaults.notice) return [defaults.notice];
+  if (!defaults.enabled) return [];
+  const prepared = await prepareAutonomyProject(project, environment, true, registry);
+  try { return ["Inherited the trusted machine autonomy default.", ...await prepared.apply()]; }
+  finally { prepared.close(); }
+}
+/** Registry ownership excludes a concurrent daemon starter while an offline write runs. */
+export async function prepareAutonomyProject(project: Project, environment: string, enabled: boolean, registry: Registry): Promise<PreparedAutonomyProject> {
+  const consentHome = hubHome();
+  const inspection = await inspectProject(project);
+  if (inspection.state === "running") {
+    const client = await ControlClient.connect(project.stateDir, { role: "console", projectRoot: project.root, instanceId: inspection.status.instanceId });
+    const request = async (action: string, confirmation?: string) => {
+      const reply = await client.request({ t: "autonomy", action, environment, ...(enabled ? { confirmed: true, confirmation } : {}) }, 35_000);
+      if (reply.ok !== true) throw new Error(String(reply.error ?? "project autonomy request refused"));
+      return reply;
+    };
+    try {
+      const preview = enabled ? await request("preview") : undefined;
+      if (enabled && typeof preview?.confirmation !== "string") throw new Error("project autonomy preview is unavailable; upgrade this hub");
+      return { lines: preview?.lines ?? ["Remove the fixed preset keys and retained consent, including manual edits to those keys."],
+        apply: async () => (await request(enabled ? "on" : "off", preview?.confirmation)).lines ?? [], close: () => client.close() };
+    } catch (error) { client.close(); throw error; }
+  }
+  if (inspection.state !== "stopped") throw new Error(inspection.error ?? `project is ${inspection.state}; autonomy was not changed`);
+  const preview = planOfflineAutonomy(project, environment, enabled);
+  return { lines: preview.lines, close: () => {}, apply: async () => {
+    const current = registry.get(project.id);
+    if (!current || current.root !== project.root || current.stateDir !== project.stateDir) throw new Error("project registration changed; autonomy was not changed");
+    const claim = randomUUID();
+    if (!registry.claim(project.id, claim, process.pid, processSignature(process.pid))) throw new Error("project acquired a live owner; autonomy was not changed");
+    try {
+      if (!enabled) {
+        try {
+          const scope = readInstanceRoleConfig(project.root), stateDir = autonomyConsentStateDir(consentHome, project.id), held = canonicalPath(stateDir);
+          const roots = [project.root, ...Object.values(scope.instances ?? {}).flatMap(instance => instance.worktree ? [resolve(project.root, instance.worktree)] : [])];
+          if (roots.some(root => insideRoot(relative(canonicalPath(root), held)))) throw new Error("private consent state is inside an execution root");
+          // Revocation only: this command never calls confirm or creates a consent key/witness.
+          // Keep the original name: clear's lstat must see and refuse a directory alias.
+          createAutonomyConsent(stateDir, project.id).clear();
+        } catch { throw new Error(`${project.root}: retained autonomy consent could not be revoked; project autonomy was not changed`); }
+      }
+      return applyOfflineAutonomy(project, environment, enabled, preview);
+    }
+    finally { registry.release(project.id, claim); }
+  } };
+}
+/** All on previews precede the one confirmation; partial apply failures are named rather than hidden. */
+export async function runAllProjectAutonomy(args: readonly string[], ports: AllProjectAutonomyPorts): Promise<void> {
+  const [action, ...flags] = args;
+  if (!["on", "off"].includes(action ?? "") || !flags.includes("--all-projects") || new Set(flags).size !== flags.length || flags.some(flag => flag !== "--all-projects" && !(action === "on" && flag === "--yes"))) throw new Error("usage: ahub autonomy on [--yes] --all-projects | off --all-projects");
+  // ponytail: 256 project previews per confirmation; larger registries need paginated confirmations.
+  if (ports.projects.length > 256) throw new Error("at most 256 registered projects can be applied in one command");
+  const enabled = action === "on", roots = ports.projects.map(project => project.root), defaults = readAutonomyDefaults(ports.home, roots);
+  if (defaults.notice) ports.print(defaults.notice);
+  const prepared: { project: Project; plan: PreparedAutonomyProject }[] = [], failures: string[] = [];
+  try {
+    for (const project of ports.projects) {
+      try {
+        const plan = await ports.prepare(project, enabled);
+        prepared.push({ project, plan });
+        ports.print(`Project ${project.root}:`);
+        for (const line of plan.lines) ports.print(`  ${line}`);
+      } catch (error) { failures.push(project.id); ports.print(`${project.root}: ${String((error as Error).message)}`); }
+    }
+    if (enabled && failures.length) throw new Error(`${failures.length} project preview(s) refused; no machine or project setting was changed`);
+    ports.print(`Machine autonomy default: ${enabled ? "on" : "off"}; ${prepared.length} registered project(s).`);
+    if (enabled && !flags.includes("--yes") && !["y", "yes"].includes((await ports.ask("Apply machine autonomy and every previewed project? [y/N] "))?.trim().toLowerCase() ?? "")) { ports.print("Machine and project autonomy were not changed."); return; }
+    if (!enabled && defaults.fingerprint === "untrusted") ports.print("Unsafe machine defaults are already ignored; their file was left unchanged.");
+    else writeAutonomyDefaults(ports.home, enabled, defaults.fingerprint, roots);
+    for (const { project, plan } of prepared) {
+      try { for (const line of await plan.apply()) ports.print(`${project.root}: ${line}`); }
+      catch (error) { failures.push(project.id); ports.print(`${project.root}: ${String((error as Error).message)}`); }
+    }
+    if (failures.length) throw new Error(`Machine default is ${enabled ? "on" : "off"}; ${failures.length} project(s) were not applied. Inspect the named projects before retrying.`);
+    ports.print(`Machine autonomy ${action}: applied to ${prepared.length} registered project(s).`);
+  } finally { for (const { plan } of prepared) plan.close(); }
+}

package/src/cli/autonomy.ts

@@ -0,0 +1,44 @@
+export { autonomyEnvironment } from "../hub/autonomy.ts";
+export const AUTONOMY_USAGE = "usage: ahub autonomy on [--all-projects] [--yes] | off [--all-projects] | status [--json]";
+export interface AutonomyCliPorts {
+  environment: string;
+  request(message: Record<string, unknown>): Promise<Record<string, unknown>>;
+  ask(prompt: string): Promise<string | null>;
+  print(line: string): void;
+  contextLines?: readonly string[];
+  confirmPrompt?: string;
+  beforeApply?(action: "on" | "off"): Promise<void> | void;
+  decorateStatus?(reply: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+/** Authority is checked by the ordinary CLI identity gate and independently by the daemon. */
+export async function runAutonomy(args: string[], ports: AutonomyCliPorts): Promise<string | undefined> {
+  const [action, flag, ...extra] = args;
+  if (!action || !["on", "off", "status"].includes(action) || extra.length || flag !== undefined && !(action === "on" && flag === "--yes" || action === "status" && flag === "--json")) return AUTONOMY_USAGE;
+  if (action !== "status") for (const line of ports.contextLines ?? []) ports.print(line);
+  let confirmation: string | undefined;
+  const request = async (action: string) => {
+    const reply = await ports.request({ t: "autonomy", action, environment: ports.environment, ...(action === "on" ? { confirmed: true, confirmation } : {}) });
+    if (reply.ok !== true) throw new Error(`${typeof reply.error === "string" ? reply.error : "autonomy request refused"}${reply.saved === true ? "; project configuration was saved; inspect ahub autonomy status or ahub settings undo" : ""}`);
+    return reply;
+  };
+  if (action === "on") {
+    const preview = await request("preview");
+    if (typeof preview.confirmation !== "string" || !preview.confirmation) throw new Error("autonomy confirmation preview is unavailable; upgrade the running hub");
+    confirmation = preview.confirmation;
+    for (const line of Array.isArray(preview.lines) ? preview.lines : []) if (typeof line === "string") ports.print(line);
+    if (flag !== "--yes" && (await ports.ask(ports.confirmPrompt ?? "Apply project autonomy? Approval prompts change; sandboxes and trust stay in force. [y/N] "))?.trim().toLowerCase() !== "y") {
+      ports.print("Project autonomy was not changed."); return;
+    }
+  }
+  let machineApplied = false;
+  if (action === "on" || action === "off") { await ports.beforeApply?.(action); machineApplied = ports.beforeApply !== undefined; }
+  let reply: Record<string, unknown>;
+  try { reply = await request(action); }
+  catch (error) {
+    if (machineApplied) throw new Error(`${error instanceof Error ? error.message : String(error)}; Machine autonomy default was set to ${action}; project apply failed. Inspect ahub autonomy status before retrying.`);
+    throw error;
+  }
+  if (action === "status" && ports.decorateStatus) reply = await ports.decorateStatus(reply);
+  if (action === "status" && args.includes("--json")) ports.print(JSON.stringify(reply.status));
+  else for (const line of Array.isArray(reply.lines) ? reply.lines : typeof reply.text === "string" ? [reply.text] : []) if (typeof line === "string") ports.print(line);
+}

package/src/cli/claude-homes.ts

@@ -0,0 +1,123 @@
+import { lstatSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { realPath } from "../hub/project.ts";
+import { launcherOf, recordPath, MAX_COMMAND_MS, type ProcessIdentity } from "./terminal-recovery.ts";
+import { CLAUDE_PLUGIN_INVENTORY, nextStep, pluginState, type InstalledPlugin, type Marketplace, type PluginState, type SetupStep } from "./setup.ts";
+import { checkClaudeProfileHook, type ClaudeProfileHookCheck } from "./claude-profile-hook.ts";
+
+export type ClaudeHomeSource = "environment" | "default" | "recorded-launch";
+export interface ClaudeHome { path: string; exists: boolean; sources: ClaudeHomeSource[] }
+/** The caller selects Claude channel peers from the resolved project catalog, never from an id spelling. */
+export interface ClaudeHomeProject { root: string; stateDir: string; instanceId: string; claudePeers: readonly string[] }
+export interface ClaudeHomeDiscovery { homes: ClaudeHome[]; notices: string[]; complete: boolean }
+export interface ClaudeHomeDiscoveryInput {
+  home: string;
+  env: NodeJS.ProcessEnv;
+  projects?: readonly ClaudeHomeProject[];
+  processIdentity?: ProcessIdentity;
+}
+
+// ponytail: 128 live launch candidates and 1 MiB per private record file bound local discovery;
+// a larger machine needs a paginated host inventory, never a profile-directory scan.
+const MAX_CANDIDATES = 128;
+const MAX_RECORD_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);
+
+/** No credentials, native profile caches or arbitrary profile directories are inspected. */
+export async function discoverClaudeHomes(input: ClaudeHomeDiscoveryInput): Promise<ClaudeHomeDiscovery> {
+  const homes = new Map<string, ClaudeHome>(), notices: string[] = [];
+  let complete = true, candidates = 0;
+  const unavailable = (message: string) => { complete = false; if (!notices.includes(message)) notices.push(message); };
+  const add = (value: unknown, source: ClaudeHomeSource, requireExisting = false) => {
+    if (!validPath(value)) { unavailable("A Claude configuration home path is invalid; no home was selected from that evidence."); return; }
+    try {
+      const info = statSync(value, { throwIfNoEntry: false });
+      if (info && !info.isDirectory()) { unavailable("A selected Claude configuration home is not a directory."); return; }
+      if (!info && requireExisting) return;
+      const path = info ? realPath(value) : value;
+      const previous = homes.get(path);
+      if (previous) { if (!previous.sources.includes(source)) previous.sources.push(source); }
+      else homes.set(path, { path, exists: !!info, sources: [source] });
+    } catch { unavailable("A selected Claude configuration home could not be inspected."); }
+  };
+  if (input.env.CLAUDE_CONFIG_DIR !== undefined && input.env.CLAUDE_CONFIG_DIR !== "") add(input.env.CLAUDE_CONFIG_DIR, "environment");
+  else if (validPath(input.home)) add(join(input.home, ".claude"), "default", true);
+  else unavailable("The user home is unavailable; no default Claude home was selected.");
+
+  for (const project of input.projects ?? []) {
+    if (++candidates > MAX_CANDIDATES) { unavailable("Claude home discovery reached its live-launch candidate limit."); break; }
+    if (!validPath(project.root) || !validPath(project.stateDir) || !project.instanceId || project.instanceId.length > 256) {
+      unavailable("A project has invalid live-launch scope; its Claude homes were not selected."); continue;
+    }
+    try {
+      const info = lstatSync(recordPath(project.stateDir), { throwIfNoEntry: false });
+      if (!info) continue;
+      if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1 || info.size > MAX_RECORD_BYTES || (info.mode & 0o022) !== 0 || !process.getuid || info.uid !== process.getuid()) {
+        unavailable("A project launch record is unsafe or exceeds the discovery size limit."); continue;
+      }
+    } catch { unavailable("A project launch record could not be inspected."); continue; }
+    for (const peer of project.claudePeers) {
+      if (++candidates > MAX_CANDIDATES) { unavailable("Claude home discovery reached its live-launch candidate limit."); break; }
+      if (!/^[a-z][a-z0-9_-]{0,63}$/.test(peer)) { unavailable("A project has an invalid Claude peer id."); continue; }
+      try {
+        const launch = await launcherOf(peer, project.root, { stateDir: project.stateDir, instanceId: project.instanceId, ...(input.processIdentity ? { processIdentity: input.processIdentity } : {}) });
+        if (!launch || launch.state === "gone") continue;
+        if (launch.state !== "live" || !launch.record) { unavailable("A Claude launch cannot be proven live; its configuration home was not selected."); continue; }
+        const profile = launch.record.env.CLAUDE_CONFIG_DIR;
+        if (profile !== undefined && profile !== "") add(profile, "recorded-launch");
+        else if (validPath(input.home)) add(join(input.home, ".claude"), "recorded-launch", true);
+        else unavailable("A live Claude launch has no usable configuration home.");
+      } catch { unavailable("A Claude launch could not be inspected; its configuration home was not selected."); }
+    }
+    if (candidates > MAX_CANDIDATES) break;
+  }
+  // Claude uses its default home on first launch too; absence is not evidence of an unused profile.
+  if (!homes.size && !input.env.CLAUDE_CONFIG_DIR && validPath(input.home)) add(join(input.home, ".claude"), "default");
+  return { homes: [...homes.values()], notices, complete };
+}
+
+/** A fresh child environment for each home; never mutate process.env while visiting profiles. */
+export function claudeHomeEnvironment(home: Pick<ClaudeHome, "path">, env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  if (!validPath(home.path)) throw new Error("invalid Claude configuration home");
+  return { ...env, CLAUDE_CONFIG_DIR: home.path };
+}
+
+export interface ClaudeHomeProbeOptions { env: NodeJS.ProcessEnv; timeoutMs: number }
+/** Implementations must enforce timeoutMs at their subprocess boundary. Only the two JSON reads are requested. */
+export type ClaudeHomeProbe = (argv: readonly string[], options: ClaudeHomeProbeOptions) => { status: number; stdout: string } | Promise<{ status: number; stdout: string }>;
+export interface ClaudeHomeCheck {
+  home: ClaudeHome;
+  plugin: PluginState | { state: "unknown"; reason: string };
+  next?: SetupStep;
+  hook: ClaudeProfileHookCheck;
+}
+
+/** Read-only per-home plugin inspection. Installation never proves that a live permission hook is present. */
+export async function checkClaudeHome(home: ClaudeHome, packageRoot: string, env: NodeJS.ProcessEnv, probe: ClaudeHomeProbe, timeoutMs = MAX_COMMAND_MS, probeMissingDefault = false): Promise<ClaudeHomeCheck> {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_COMMAND_MS) throw new Error("invalid Claude plugin probe time bound");
+  const hook = checkClaudeProfileHook(home);
+  const unknown = (): ClaudeHomeCheck => ({ home, plugin: { state: "unknown", reason: "Claude plugin inventory is unavailable or invalid for this home." }, hook });
+  if (hook.state === "refused") return unknown();
+  if (!home.exists && !(probeMissingDefault && home.sources.includes("default"))) return { home, plugin: { state: "missing" }, next: nextStep([], [], packageRoot), hook };
+  const scoped = claudeHomeEnvironment(home, env), deadline = performance.now() + timeoutMs;
+  const read = async (argv: readonly string[]): Promise<unknown[] | undefined> => {
+    const remaining = Math.floor(deadline - performance.now());
+    if (remaining < 1) return;
+    const result = await probe(argv, { env: scoped, timeoutMs: remaining });
+    if (result.status !== 0 || Buffer.byteLength(result.stdout, "utf8") > MAX_RECORD_BYTES || performance.now() > deadline) return;
+    const value: unknown = JSON.parse(result.stdout);
+    return Array.isArray(value) ? value : undefined;
+  };
+  try {
+    const plugins = await read(CLAUDE_PLUGIN_INVENTORY.plugins);
+    if (!plugins) return unknown();
+    const marketplaces = await read(CLAUDE_PLUGIN_INVENTORY.marketplaces);
+    if (!marketplaces) return unknown();
+    const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+    if (!plugins.every(row => object(row) && typeof row.id === "string" && row.id.length <= 256 &&
+      (row.version === undefined || typeof row.version === "string" && row.version.length <= 64 && /^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/.test(row.version)) &&
+      (row.installPath === undefined || validPath(row.installPath))) ||
+      !marketplaces.every(row => object(row) && typeof row.name === "string" && row.name.length <= 256 && (row.path === undefined || validPath(row.path)))) return unknown();
+    return { home, plugin: pluginState(plugins as InstalledPlugin[], packageRoot), next: nextStep(plugins as InstalledPlugin[], marketplaces as Marketplace[], packageRoot), hook };
+  } catch { return unknown(); }
+}