@staix/agent-hub 0.21.0 → 0.22.0

package/docs/verified.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "documents": {
     "README.md": {
-      "verifiedAgainst": "43867c65caaadc8d7bdc44e034ecf1b933c8df77",
+      "verifiedAgainst": "cb942e06d89c6cd9fbe81a3f6d36f3f1d1c14c14",
       "paths": [
         "package.json",
         "src/",
@@ -11,14 +11,14 @@
       ]
     },
     "docs/security.md": {
-      "verifiedAgainst": "43867c65caaadc8d7bdc44e034ecf1b933c8df77",
+      "verifiedAgainst": "cb942e06d89c6cd9fbe81a3f6d36f3f1d1c14c14",
       "paths": [
         "src/",
         "templates/"
       ]
     },
     "docs/operations.md": {
-      "verifiedAgainst": "43867c65caaadc8d7bdc44e034ecf1b933c8df77",
+      "verifiedAgainst": "cb942e06d89c6cd9fbe81a3f6d36f3f1d1c14c14",
       "paths": [
         "package.json",
         "src/",
@@ -35,7 +35,7 @@
       ]
     },
     "docs/quickstart.md": {
-      "verifiedAgainst": "43867c65caaadc8d7bdc44e034ecf1b933c8df77",
+      "verifiedAgainst": "cb942e06d89c6cd9fbe81a3f6d36f3f1d1c14c14",
       "paths": [
         "package.json",
         "src/",
@@ -43,7 +43,7 @@
       ]
     },
     "docs/agent-notes/adapters.md": {
-      "verifiedAgainst": "43867c65caaadc8d7bdc44e034ecf1b933c8df77",
+      "verifiedAgainst": "cb942e06d89c6cd9fbe81a3f6d36f3f1d1c14c14",
       "paths": [
         "src/adapters/",
         "src/pi/",
@@ -93,7 +93,7 @@
       ]
     },
     "docs/agent-notes/budget.md": {
-      "verifiedAgainst": "43867c65caaadc8d7bdc44e034ecf1b933c8df77",
+      "verifiedAgainst": "cb942e06d89c6cd9fbe81a3f6d36f3f1d1c14c14",
       "paths": [
         "src/hub/budget.ts",
         "src/cli/statusline-tee.ts",
@@ -117,7 +117,7 @@
       ]
     },
     "docs/agent-notes/bus.md": {
-      "verifiedAgainst": "43867c65caaadc8d7bdc44e034ecf1b933c8df77",
+      "verifiedAgainst": "cb942e06d89c6cd9fbe81a3f6d36f3f1d1c14c14",
       "paths": [
         "src/hub/bus.ts",
         "src/hub/envelope.ts",
@@ -132,7 +132,7 @@
       ]
     },
     "docs/agent-notes/daemon.md": {
-      "verifiedAgainst": "43867c65caaadc8d7bdc44e034ecf1b933c8df77",
+      "verifiedAgainst": "cb942e06d89c6cd9fbe81a3f6d36f3f1d1c14c14",
       "paths": [
         "src/hub/daemon.ts",
         "src/hub/control-client.ts",
@@ -225,7 +225,7 @@
       ]
     },
     "docs/agent-notes/tasks.md": {
-      "verifiedAgainst": "43867c65caaadc8d7bdc44e034ecf1b933c8df77",
+      "verifiedAgainst": "cb942e06d89c6cd9fbe81a3f6d36f3f1d1c14c14",
       "paths": [
         "src/hub/tasks.ts",
         "src/hub/board.ts",
@@ -264,7 +264,7 @@
       ]
     },
     "docs/agent-notes/tests.md": {
-      "verifiedAgainst": "43867c65caaadc8d7bdc44e034ecf1b933c8df77",
+      "verifiedAgainst": "cb942e06d89c6cd9fbe81a3f6d36f3f1d1c14c14",
       "paths": [
         "test/",
         "scripts/check.sh",
@@ -292,7 +292,7 @@
       ]
     },
     "docs/agent-notes/README.md": {
-      "verifiedAgainst": "43867c65caaadc8d7bdc44e034ecf1b933c8df77",
+      "verifiedAgainst": "cb942e06d89c6cd9fbe81a3f6d36f3f1d1c14c14",
       "paths": [
         "src/cli/console-state.ts",
         "src/cli/attention.ts",
@@ -301,7 +301,7 @@
       ]
     },
     "src/cli/help.ts": {
-      "verifiedAgainst": "aeeaeb048860316dd4e08d84a658519ed6c0ad24",
+      "verifiedAgainst": "cb942e06d89c6cd9fbe81a3f6d36f3f1d1c14c14",
       "paths": [
         "src/cli/main.ts",
         "src/cli/launch.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   "license": "MIT",
   "type": "module",

package/plugins/agent-hub/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hub",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Channel between Claude Code and the agent-hub daemon: peer messages from Codex, Kimi and the local worker arrive as channel events; hub_send replies.",
   "author": {
     "name": "Young Joon Lee",

package/plugins/agent-hub/server.js

@@ -22536,7 +22536,7 @@ init_security_baseline();
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.21.0",
+  version: "0.22.0",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   license: "MIT",
   type: "module",

package/src/cli/help.ts

@@ -102,6 +102,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub source add <path|url> | list [--json] [--color=auto|always|never]", "list is person only, add the person's or the configured conductor's: register an input as a content-hashed source (src:<16 hex of the SHA-256>) under the hub state dir sources/<id>/ (meta.json, raw, text); a URL is fetched once by this command, https only, at most 5 redirects; up to 16 MiB, never truncated; a path under pii.paths or text matching signals.pii_patterns is private, and private is never downgraded"],
     ["ahub schedule list | run <id> | pause <id> | resume <id> [--json] [--color=auto|always|never]", "list is person only; run, pause and resume are the person's or the configured conductor's: the machine-local schedules (`schedules` in .agenthub/config.local.json); list shows each one's next run, run proposes one now through the same hold, open-task and PII path as the timer and restarts its period, pause stops the timer proposing it without counting a skip, resume starts a fresh period so a pause is never replayed as a run"],
     ["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 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 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

@@ -186,9 +186,11 @@ export function cliCommandLabel(command: string, args: readonly string[], catalo
   if (command === "schedule") return ["list", "run", "pause", "resume"].includes(args.find(arg => arg !== "--json") ?? "") ? `schedule ${args.find(arg => arg !== "--json")}` : "schedule";
   // #334: intake names its two subcommands in the audit and a refusal, never the request text (it can carry a secret).
   if (command === "intake") return ["approve", "discard"].includes(args.find(arg => arg !== "--json") ?? "") ? `intake ${args.find(arg => arg !== "--json")}` : "intake";
+  // #514b: the audit and a refusal name the subcommand only, never the card id or any text.
+  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";
   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"].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"].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/learn-output.ts

@@ -0,0 +1,38 @@
+// Human output for `ahub learn` (#514b). Pure: parsed hub-tool JSON in, spans out, no I/O. `--json` is the caller's branch and prints the same text.
+// Ids, counts, the key parts and the one line the hub itself generates are all it shows: the card's own text is never echoed (a card is data to the parser, not to this printer).
+import { blank, grid, heading, pair, s } from "./sdlc-output.ts";
+import type { Span } from "./console-state.ts";
+
+const list = (value: unknown): any[] => Array.isArray(value) ? value : [];
+const dash = (value: unknown) => value === undefined || value === null || value === "" ? "-" : String(value);
+
+/** `ahub learn list [--all]`: one row per candidate, and what each command would do. */
+export function renderLearnList(result: unknown, columns?: number, all = false): Span[][] {
+  const rows = list(result);
+  const open = rows.filter(row => row.status === "open").length;
+  const out: Span[][] = [...heading(all ? `Review checklist candidates: ${open} open, ${rows.length - open} decided` : `Review checklist candidates: ${open} open`, columns)];
+  if (!rows.length) {
+    out.push(blank, [s(all ? "no candidate has been filed" : "no open candidate; pass --all to include decided ones", "muted")]);
+    return out;
+  }
+  out.push(...grid(["ID", "STATUS", "PROFILE/CLASS", "CRITERION", "TASKS", "LINE TO ADD"], rows.map((row: any) => [
+    s(`#${row.id}`, "taskRef"), s(dash(row.status), row.status === "open" ? "attention" : "muted"), s(`${dash(row.profile)}/${dash(row.class)}`), s(dash(row.criterion)), s(String(list(row.tasks).length)), s(dash(row.line)),
+  ]), columns));
+  if (open) out.push(blank, [s("accept writes the line to .agenthub/config.local.json (ahub settings undo puts it back); reject closes the card. Nothing else changes.", "muted")]);
+  return out;
+}
+
+/** `ahub learn accept|reject <id>`: what was decided, and for accept exactly what was written and where. */
+export function renderLearnChange(op: "accept" | "reject", result: unknown, columns?: number): Span[][] {
+  const r = (result ?? {}) as any;
+  const card = op === "accept" ? r.card : r;
+  const out: Span[][] = [...heading(op === "accept" ? `Candidate #${dash(card?.id)} accepted` : `Candidate #${dash(card?.id)} rejected and closed`, columns)];
+  if (op === "reject") return [...out, ...pair("written", "nothing", columns, 8, "muted")];
+  const a = r.accepted ?? {};
+  if (a.alreadyAccepted) return [...heading(`Candidate #${dash(card?.id)} was already accepted`, columns), ...pair("profile", `${dash(a.profile)}/${dash(a.class)}`, columns, 8), ...pair("criterion", a.criterion, columns, 8), ...pair("written", "nothing: it was accepted before (ahub settings undo still puts back that write if it is the latest)", columns, 8, "muted")];
+  out.push(...pair("profile", `${dash(a.profile)}/${dash(a.class)}`, columns, 8), ...pair("criterion", a.criterion, columns, 8), ...pair("line", a.line, columns, 8),
+    ...pair("file", `${dash(a.file)} (this machine only; the shared config is untouched)`, columns, 8), ...pair("now", a.alreadyPresent ? `the checklist already had this line: nothing was written` : `${dash(a.lines)} lines in the checklist`, columns, 8),
+    ...pair("applies", dash(a.applies), columns, 8, "attention"));
+  if (a.undo) out.push(blank, [s(`put it back with ${a.undo}`, "muted")]);
+  return out;
+}

package/src/cli/main.ts

@@ -26,6 +26,7 @@ import { fetchSourceUrl, MAX_SOURCE_BYTES, publicSourceView, screenRegistration,
 import { renderSourceAdd, renderSourceList } from "./source-output.ts";
 import { renderScheduleChange, renderScheduleList, renderScheduleRun } from "./schedule-output.ts";
 import { renderIntake, renderIntakeChange } from "./intake-output.ts";
+import { renderLearnChange, renderLearnList } from "./learn-output.ts";
 import { terminalText } from "./console-state.ts";
 import { parseSettingsEditArgs, runSettingsEdit, SETTINGS_EDIT_USAGE } from "./settings-edit.ts";
 import { petView, readPet, renderPet } from "./pet.ts";
@@ -38,7 +39,7 @@ import { verifiedJcodeCommand } from "../adapters/jcode.ts";
 import { configureJcodeMcp, jcodeExtraMcpServers } from "./jcode-mcp.ts";
 import { qwenSessionId } from "../hub/crash.ts";
 import { isPermissionMode } from "../hub/permission-mode.ts";
-import { parseSettingText, settingDef, settingText, type SettingRow } from "../hub/settings.ts";
+import { parseSettingText, settingDef, settingText, undoableDef, type SettingRow } from "../hub/settings.ts";
 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";
@@ -1450,6 +1451,23 @@ 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);
   },
 
+  learn: async () => {
+    // #514b: the person's verdict on a recurring-criterion candidate (#514a). Person only, end to end: `learn` is a `console` command for an agent shell (classifyPeerCommand has no entry for it, so the
+    // identity layer refuses it before this runs), and the daemon refuses any caller but the person again. `accept` writes ONE key (profile_overrides.review_checklist) to the machine-local
+    // config through the settings writer; nothing in a card's text is written.
+    const split = splitPresentation(args);
+    const present = outputOptions(split.flags); // before any request: an invalid --color must refuse before a mutation is sent
+    const usage = "usage: ahub learn list [--all] | accept <id> | reject <id> [--json] [--color=auto|always|never]";
+    const [sub, ...rest] = split.operands;
+    if (sub === "list" && rest.every(arg => arg === "--all")) {
+      const all = rest.includes("--all");
+      return showToolText(data => renderLearnList(data, present.columns, all), await taskOp("learn_list", { ...(all ? { all: true } : {}) }), present);
+    }
+    const [id, ...extra] = rest;
+    if ((sub !== "accept" && sub !== "reject") || !id || extra.length || !/^[1-9]\d*$/.test(id)) return fail(usage);
+    return showToolText(data => renderLearnChange(sub, data, present.columns), await taskOp(sub === "accept" ? "learn_accept" : "learn_reject", { id: Number(id) }), present);
+  },
+
   intake: async () => {
     // #334 (#511a): natural-language intake. Person only, except approve (#933: the configured conductor too, admitted and audited by the daemon).
     // The request is a draft backlog card that nothing offers until `approve`; the hub, not this process, splits it.
@@ -1952,7 +1970,7 @@ const commands: Record<string, () => Promise<void> | void> = {
         return console.log(paint([{ text: result.text }], false));
       }
       if (sub === "undo") {
-        const view = await request({ t: "settings_get" }), undoDef = settingDef(view.undo, settingScope.instances, settingScope.catalog);
+        const view = await request({ t: "settings_get" }), undoDef = undoableDef(view.undo, settingScope.instances, settingScope.catalog);
         // A roster undo of a declared peer needs its confirmation prompt; without readable declarations, refuse rather than skip it.
         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;

package/src/cli/recovery-waits.ts

@@ -0,0 +1,26 @@
+import { configRefusal } from "../hub/config-trust.ts";
+import { readInstanceConfigLayers } from "../hub/instance-config.ts";
+import { recoveryWaits, type RecoveryOperationalConfig, type RecoveryWaits } from "../hub/operational-settings.ts";
+
+/**
+ * #489 H4. The upgrade coordinator is a CLI process, not the daemon, so it reads the five recovery waits itself, from the project it is acting on, at the START of each wait (a wait already running keeps
+ * its deadline, and the receipt's `waits` records it). Both layers count, the machine-local file last, as `loadConfig` merges them; a layer git tracks as local policy is refused like every other local
+ * policy (`configRefusal`) and a file that cannot be read or parsed is the default. A recovery never fails on its configuration: bounds were checked when the value was written, and `recoveryWaits` falls
+ * back to the default for a value outside them.
+ */
+const LEAVES = new Set(["reconnect_wait_s", "unmanaged_reconnect_wait_s", "control_timeout_s", "shutdown_wait_s", "terminal_idle_wait_s"]);
+export function readRecoveryWaits(projectRoot: string | undefined, read: (cwd: string) => ReturnType<typeof readInstanceConfigLayers> = readInstanceConfigLayers): RecoveryWaits {
+  if (!projectRoot) return recoveryWaits(() => undefined);
+  let merged: RecoveryOperationalConfig["recovery"];
+  try {
+    for (const layer of read(projectRoot)) {
+      const recovery = layer.raw.recovery;
+      if (!recovery || typeof recovery !== "object" || Array.isArray(recovery) || !Object.keys(recovery).some(key => LEAVES.has(key))) continue;
+      // The shared file is team policy and always read; the machine-local file only when git does not track it. Git is asked only when that file actually sets one of the five
+      // (a recovery polls and sends many control requests, and a file that sets none must cost no subprocess).
+      if (layer.name === "config.local.json" && configRefusal(projectRoot, layer.name)) continue;
+      merged = { ...merged, ...(recovery as Record<string, unknown>) };
+    }
+  } catch { return recoveryWaits(() => undefined); }
+  return recoveryWaits(() => ({ recovery: merged }));
+}

package/src/cli/smoke-pty-bridge.ts

@@ -1,33 +1,82 @@
 // macOS script(1) requires a terminal on its own stdin, including when its child gets a PTY.
 // Keep a real PTY in this owned bridge instead; the outer Node child remains tracked by stopOwnedProcess.
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * #560: Bun up to 1.4.3 can hang for good inside `Bun.spawn({ terminal })` on macOS when the child writes and starts exiting before the call returns (oven-sh/bun#45300, fixed in 1.4.4): the
+ * event loop thread blocks in wait4 while the exiting session leader waits for that same thread to drain its pty. Measured here with a bare Bun script and no agent-hub code: 26 of 96 runs hung
+ * at 12 in parallel on 1.4.3 and 0 of 180 on 1.4.4. The child therefore starts behind a gate: a shell that waits for a file the bridge writes right after `Bun.spawn` has returned, then `exec`s the
+ * real command (same pid, same session, same terminal). The wait has no bound of its own: a bridge that dies before it opens the gate closes the pty, which hangs the shell up (the trap below), and a bridge
+ * that is alive but never opens it is a hung bridge, which `runPty` stops with its group.
+ * ponytail: ceiling and upgrade path. The gate exists only because of oven-sh/bun#45300 on Bun up to 1.4.3 (this repo pins 1.4.2 in `.bun-version`); the upgrade path is to delete GATE_SCRIPT, `gate` and `gateDir` once the pinned Bun is 1.4.4 or newer, which is its own task because it
+ * touches CI and every OS leg. The parent-death stop below stays whatever the Bun version: an orphaned bridge is this repository's bug, not Bun's. The gate costs about one shell start (a few ms).
+ */
+// The shell removes its own gate (file, then directory) once released and when it is hung up or terminated (a bridge killed with SIGKILL runs no cleanup, and the pty closing
+// sends the shell SIGHUP), so no path leaves a directory behind. `exec` resets the traps for the real command.
+const GATE_SCRIPT = 'd=${0%/*}; trap "rm -f \\"$0\\"; rmdir \\"$d\\" 2>/dev/null; exit 125" HUP TERM INT; while [ ! -e "$0" ]; do sleep 0.01; done; rm -f "$0"; rmdir "$d" 2>/dev/null; exec "$@"';
+/** A bridge whose caller died is stopped instead of running on: its child holds a terminal nobody reads and, under launchd, nothing else would ever stop it. */
+const PARENT_POLL_MS = 250;
+const PARENT_TERM_GRACE_MS = 1_000;
+const PARENT_HARD_EXIT_MS = 3_000;
+
+// The caller is whoever started this bridge, read before anything that can take time: a caller that dies while `Bun.spawn` runs (the window #45300 widens) has already reparented this process by the
+// time the call returns, and a parent read after it would be launchd and never change.
+const parent = process.ppid;
+const callerGone = (): boolean => process.ppid !== parent;
 const argv = process.argv.slice(2);
 if (!argv.length) {
   process.exitCode = 125;
 } else {
   let streamClosed!: () => void;
   const eof = new Promise<void>(resolve => { streamClosed = resolve; });
-  const child = Bun.spawn(argv, {
-    cwd: process.cwd(), env: process.env,
-    terminal: {
-      cols: 120, rows: 40, name: "xterm-256color",
-      data: (_terminal, data) => { process.stdout.write(data); },
-      exit: () => streamClosed(),
-    },
-  });
-  const stop = () => { try { child.kill("SIGTERM"); } catch { /* exit readback decides */ } };
-  process.on("SIGINT", stop); process.on("SIGTERM", stop);
+  const gateDir = process.platform === "darwin" ? mkdtempSync(join(tmpdir(), "ahub-pty-gate-")) : undefined;
+  const gate = gateDir ? join(gateDir, "open") : undefined;
+  let watch: ReturnType<typeof setInterval> | undefined;
   try {
-    const code = await child.exited;
-    // Drain the PTY before closing it; a descendant holding a slave cannot make the bridge wait forever.
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    await Promise.race([eof, new Promise<void>(resolve => { timer = setTimeout(resolve, 250); })]);
-    if (timer) clearTimeout(timer);
-    process.exitCode = code;
+    const child = Bun.spawn(gate ? ["/bin/sh", "-c", GATE_SCRIPT, gate, ...argv] : argv, {
+      cwd: process.cwd(), env: process.env,
+      terminal: {
+        cols: 120, rows: 40, name: "xterm-256color",
+        data: (_terminal, data) => { process.stdout.write(data); },
+        exit: () => streamClosed(),
+      },
+    });
+    const stop = () => { try { child.kill("SIGTERM"); } catch { /* exit readback decides */ } };
+    process.on("SIGINT", stop); process.on("SIGTERM", stop);
+    /** The caller is gone: stop the child now, kill it after a grace period, and exit even if its exit is never reported. */
+    const abandon = () => {
+      clearInterval(watch);
+      stop();
+      setTimeout(() => { try { child.kill("SIGKILL"); } catch { /* already gone */ } }, PARENT_TERM_GRACE_MS).unref();
+      setTimeout(() => process.exit(129), PARENT_HARD_EXIT_MS).unref();
+    };
+    // A caller that died while Bun.spawn ran never gets its command run: the gate stays shut and the gate shell takes the SIGTERM (its trap removes the gate and exits).
+    // Abandoning once is enough: the interval below exists only while the caller is still there, and clears itself the first time it is not.
+    if (callerGone()) abandon();
+    else {
+      if (gate) writeFileSync(gate, "");
+      watch = setInterval(() => { if (callerGone()) abandon(); }, PARENT_POLL_MS);
+    }
+    try {
+      const code = await child.exited;
+      // Drain the PTY before closing it; a descendant holding a slave cannot make the bridge wait forever.
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      await Promise.race([eof, new Promise<void>(resolve => { timer = setTimeout(resolve, 250); })]);
+      if (timer) clearTimeout(timer);
+      process.exitCode = code;
+    } catch {
+      process.exitCode = 125;
+    } finally {
+      child.terminal?.close();
+      process.removeListener("SIGINT", stop); process.removeListener("SIGTERM", stop);
+    }
   } catch {
     process.exitCode = 125;
   } finally {
-    child.terminal?.close();
-    process.removeListener("SIGINT", stop); process.removeListener("SIGTERM", stop);
+    if (watch) clearInterval(watch);
+    if (gateDir) rmSync(gateDir, { recursive: true, force: true });
   }
 }
 export {};

package/src/cli/smoke-pty.ts

@@ -54,14 +54,22 @@ function waitForExit(proc: ChildProcess): Promise<{ code: number | null }> {
 }
 
 /** Run an argv vector inside a fixed-size PTY, always stopping its owned process group before returning. */
-export async function runPty(argv: readonly string[], options: PtyOptions): Promise<PtyResult> {
+export function runPty(argv: readonly string[], options: PtyOptions): Promise<PtyResult> {
+  return runPtyWith(commandFor, argv, options);
+}
+
+/**
+ * `runPty` with the launcher named by the caller. Only code can reach it (a test names a bridge that ignores SIGTERM or never exits); no config key, request or environment variable does, so the
+ * bridge a hub runs is always `commandFor`'s.
+ */
+export async function runPtyWith(launcher: (argv: readonly string[]) => string[], argv: readonly string[], options: PtyOptions): Promise<PtyResult> {
   validate(argv, options);
   const started = Date.now();
   if (options.signal?.aborted) return { outcome: "aborted", exitCode: null, outputBytes: 0, elapsedMs: Date.now() - started, cleaned: true };
 
   let proc: ChildProcess;
   try {
-    const command = commandFor(argv);
+    const command = launcher(argv);
     proc = spawn(command[0]!, command.slice(1), {
       cwd: options.cwd,
       env: { ...options.env, TERM: "xterm-256color" },

package/src/cli/upgrade-runtime.ts

@@ -3,6 +3,7 @@ import { resolveAcceptedBinding } from "./recovery-guidance.ts";
 import { claudeStateFile } from "../hub/claude-state.ts";
 import { ADAPTERS, definitionOf } from "../adapters/registry.ts";
 import { readInstanceConfig, readInstanceConfigLayers } from "../hub/instance-config.ts";
+import { readRecoveryWaits } from "./recovery-waits.ts";
 import { readAdapterModuleDeclarations } from "../adapters/external-modules.ts";
 import { configRefusal } from "../hub/config-trust.ts";
 import { validExternalInstanceBinding } from "../hub/external-instance.ts";
@@ -26,10 +27,9 @@ import { decodeRestoreReceipt, restoreTransition, type RestoreReceipt, type Rest
 import { RecoveryDeferredHubError } from "../hub/deferred-hub.ts";
 import { RecoveryPreservationError, RecoveryPresentationError, type RecoveryNativeCause } from "./upgrade-presentation-data.ts";
 
-/** An unmanaged Claude's plugin retries with a backoff of at most 30 s; three of those bound the reconnect wait (#206). */
-const UNMANAGED_RECONNECT_WAIT_MS = 90_000;
-/** Managed TUI startup can include resume and MCP handshakes; match createTerminal's ten-minute readiness ceiling. */
-const RECONNECT_WAIT_MS = 600_000;
+// #489 H4: the reconnect, unmanaged reconnect, control request, terminal idle and shutdown waits are settings now (`recovery.*`, src/hub/operational-settings.ts), read by `readRecoveryWaits` at the start of
+// each wait. Their defaults are the constants that stood here: an unmanaged Claude's plugin retries with a backoff of at most 30 s and three of those bound its reconnect wait (#206, 90 s); managed TUI startup
+// can include resume and MCP handshakes, so its wait matches createTerminal's ten-minute readiness ceiling (600 s, which is also the setting's floor).
 class AttachmentLauncherGone extends Error {
   constructor(readonly transition: RestoreTransition) { super("chosen attachment launcher exited"); }
 }
@@ -80,12 +80,12 @@ export function restoredTerminalArgv(entrypoint: string, projectRoot: string, bi
   return [process.execPath, entrypoint, "--project", projectRoot, ...tail];
 }
 
-const RECOVERY_CONTROL_TIMEOUT_MS = 30_000;
 
 async function rpc(project: Project, message: Record<string, unknown>, protocol = PROTOCOL, conductorPeer?: string): Promise<any> {
-  const client = await ControlClient.connect(project.stateDir, { ...(conductorPeer ? { role: "tools" as const, peer: conductorPeer } : { role: "console" as const }), projectRoot: project.root, projectId: project.id }, RECOVERY_CONTROL_TIMEOUT_MS, protocol);
+  const controlTimeoutMs = readRecoveryWaits(project.root).controlTimeoutMs;
+  const client = await ControlClient.connect(project.stateDir, { ...(conductorPeer ? { role: "tools" as const, peer: conductorPeer } : { role: "console" as const }), projectRoot: project.root, projectId: project.id }, controlTimeoutMs, protocol);
   try {
-    const reply = await client.request(message, RECOVERY_CONTROL_TIMEOUT_MS);
+    const reply = await client.request(message, controlTimeoutMs);
     if (reply.ok === false) {
       // An older hub has only its exact SQLite message; preserve compatibility without trusting arbitrary text.
       if (isDatabaseBusyReply(reply)) throw new RecoveryDatabaseBusy();
@@ -215,7 +215,7 @@ export async function inspectRecovery(project: Project, targetFeatures?: readonl
   // pid from planning time (after a reboot another process may hold it). A registry that cannot be read throws: the
   // caller reads that as not inspected, never as stopped.
   const claim = registeredProjects().find((p) => p.id === project.id);
-  const base = await inspectProject({ ...project, instanceId: claim?.instanceId ?? null, pid: claim?.pid ?? null, pidSignature: claim?.pidSignature ?? null }, RECOVERY_CONTROL_TIMEOUT_MS, conductorPeer);
+  const base = await inspectProject({ ...project, instanceId: claim?.instanceId ?? null, pid: claim?.pid ?? null, pidSignature: claim?.pidSignature ?? null }, readRecoveryWaits(project.root).controlTimeoutMs, conductorPeer);
   if (base.failure?.code === "database_busy") throw new RecoveryDatabaseBusy();
   const control = readControl(project.stateDir);
   const sourceProtocol = control?.protocol;
@@ -469,7 +469,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
     if (found.manualRequired || !current || (exact && (current.handle !== saved.handle || current.incarnationId !== saved.incarnationId || current.worktreeId !== saved.worktreeId || current.projectRoot !== saved.projectRoot))) {
       throw nativeFailure(planned, saved.peer, "terminal_unverified", `${saved.peer}: saved terminal identity changed or is not verified; manual-required`, { handle: saved.handle });
     }
-    const idle = await waitForIdle(exact ? saved : current, 120_000, options);
+    const idle = await waitForIdle(exact ? saved : current, readRecoveryWaits(planned.project.root).terminalIdleWaitMs, options);
     if (!idle.satisfied) throw nativeFailure(planned, saved.peer, "terminal_unverified", `${saved.peer}: terminal is not idle; manual-required`, { handle: saved.handle });
     const observed = await inspectRecovery(planned.project);
     if (observed.instanceId !== progress.instanceId) throw nativeFailure(planned, saved.peer, "target_unavailable", `${saved.peer}: daemon instance changed during terminal revalidation`, { handle: saved.handle, targetState: observed.state });
@@ -567,7 +567,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       if (seen !== "absent") throw new Error(closeUnsettled(retired, seen));
       progress.terminals[key] = true; save(); return;
     }
-    const idle = await waitForIdle(retired, 120_000, terminalOptions(run));
+    const idle = await waitForIdle(retired, readRecoveryWaits(retired.projectRoot).terminalIdleWaitMs, terminalOptions(run));
     if (!idle.satisfied) throw new Error(`${peer}: terminal ${retired.handle} of the stopped target's session is not verified idle; finish or cancel its turn, or close that terminal by hand, first`);
     progress.terminals[key] = "pending"; save();
     await recoveryCurrent();
@@ -583,7 +583,8 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
     };
     const binding = waiting.binding;
     const matchesTerminal = (terminal: Pick<TerminalBinding, "handle" | "incarnationId" | "worktreeId">) => terminal.handle === binding.handle && terminal.incarnationId === binding.incarnationId && terminal.worktreeId === binding.worktreeId;
-    const startedAt = now(), deadline = startedAt + RECONNECT_WAIT_MS;
+    const reconnectWaitMs = readRecoveryWaits(planned.project.root).reconnectWaitMs; // read once, at the start: a wait already running keeps the deadline the receipt records
+    const startedAt = now(), deadline = startedAt + reconnectWaitMs;
     const waitStep = op.step;
     if (waitStep) {
       (op.waits ??= {})[waitStep] = { waitStartedAt: new Date(startedAt).toISOString(), deadlineAt: new Date(deadline).toISOString() };
@@ -656,7 +657,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       hub: { state: live.state, ...(live.instanceId ? { instanceId: live.instanceId } : {}), ...(peer ? { peerState: peer.state } : {}), ...(session ? { sessionId: session } : {}) },
       lastHubConnectAttempt: "unknown" };
     save();
-    throw nativeFailure(planned, binding.peer, "attachment_timeout", `${binding.peer}: attachment not verified within ${RECONNECT_WAIT_MS / 1000} s; terminal ${binding.handle} retained; resume after it attaches (native-start diagnostic recorded; last hub connect attempt unknown)`, { handle: binding.handle, timeoutMs: RECONNECT_WAIT_MS });
+    throw nativeFailure(planned, binding.peer, "attachment_timeout", `${binding.peer}: attachment not verified within ${reconnectWaitMs / 1000} s; terminal ${binding.handle} retained; resume after it attaches (native-start diagnostic recorded; last hub connect attempt unknown)`, { handle: binding.handle, timeoutMs: reconnectWaitMs });
     } catch (error) { waitFailed = true; throw error; }
     finally {
       const finish = () => {
@@ -1030,9 +1031,10 @@ export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?:
       }
       if (group !== "native" && !onlyPeer) for (const id of planned.reconnectOnly ?? []) {
         // #206: nothing is launched for an unmanaged session; its plugin reconnects by itself, within a bound.
-        const deadline = now() + UNMANAGED_RECONNECT_WAIT_MS;
+        const unmanagedWaitMs = readRecoveryWaits(planned.project.root).unmanagedReconnectWaitMs;
+        const deadline = now() + unmanagedWaitMs;
         while (!(await inspectRecovery(planned.project)).peers.some((p) => p.id === id && p.state !== "offline")) {
-          if (now() >= deadline) throw nativeFailure(planned, id, "attachment_timeout", `${id}: the unmanaged session did not reconnect within ${UNMANAGED_RECONNECT_WAIT_MS / 1000} s; if that Claude session was closed, start Claude in the project again (its plugin reconnects) first`, { timeoutMs: UNMANAGED_RECONNECT_WAIT_MS });
+          if (now() >= deadline) throw nativeFailure(planned, id, "attachment_timeout", `${id}: the unmanaged session did not reconnect within ${unmanagedWaitMs / 1000} s; if that Claude session was closed, start Claude in the project again (its plugin reconnects) first`, { timeoutMs: unmanagedWaitMs });
           await sleep(1000);
         }
       }

package/src/cli/upgrade.ts

@@ -12,6 +12,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { REGISTRY_DB_BUSY_TIMEOUT_MS, PROJECT_COLUMNS, projectFromRow, type Project } from "../hub/registry.ts";
 import { hubHome } from "../hub/project.ts";
+import { readRecoveryWaits } from "./recovery-waits.ts";
 import { acquireRecoveryLock, claimRunner, coordinatorCurrent, operationIdPattern, readOperation, recoveryCommand, recoveryLock, releaseRecoveryLock, writeOperation } from "../hub/recovery-store.ts";
 import { resolveAcceptedBinding, piArchiveExit, recordedPeerGuidance, type RecoveryNativePeer } from "./recovery-guidance.ts";
 import type { TerminalBinding } from "./terminal-recovery.ts";
@@ -802,7 +803,7 @@ export async function runRecovery(id: string, driver: RecoveryDriver, home = hub
           throw new Error(`${project.id}: the source stopped while prepared and no commit was requested, so there is nothing to restore`);
         }
         if (awaitShutdown) {
-          const deadline = driver.now() + 30_000;
+          const deadline = driver.now() + readRecoveryWaits(project.root).shutdownWaitMs; // #489 H4: recovery.shutdown_wait_s, 30 s unset
           // An already-sent commit can be between its final reply and the source closing its control server.
           if (resumedShutdown) {
             if (live.instanceId && live.instanceId !== planned.source.instanceId) throw new Error(`${project.id}: another daemon started during shutdown`);