@staix/agent-hub 0.12.21 → 0.12.23

package/src/hub/db-timeout.ts

@@ -0,0 +1,3 @@
+// hub.db is shared by the board, journal, budgets, turns and Pi receipts.
+// Bound each SQLite contention wait; callers must not multiply it with retries.
+export const HUB_DB_BUSY_TIMEOUT_MS = 3000;

package/src/hub/delivery-journal.ts

@@ -4,6 +4,7 @@ import { Database } from "bun:sqlite";
 import type { BusSnapshot } from "./bus.ts";
 import type { Envelope } from "./envelope.ts";
 import { processLiveness } from "../pi/process-signature.ts";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 
 export type JournalDeliveryState =
   | "queued"
@@ -239,10 +240,10 @@ export class DeliveryJournal {
     this.operationId = options.operationId;
     mkdirSync(dirname(options.file), { recursive: true, mode: 0o700 });
     this.db = new Database(options.file, { create: true });
+    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
     this.harden();
     this.db.run("PRAGMA journal_mode = WAL");
     this.db.run("PRAGMA synchronous = FULL");
-    this.db.run("PRAGMA busy_timeout = 3000");
     this.createSchema();
     const meta = this.readMeta();
     if (!meta)

package/src/hub/envelope.ts

@@ -14,7 +14,7 @@ export interface Envelope {
   kind: Kind;
   priority: Priority;
   body: string; // agent conclusions only, never tool noise
-  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; supervision?: boolean; supervisionKey?: string };
+  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; supervision?: boolean; supervisionKey?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[] };
   /** The body must not be shown outside its recipients: console tail and log print a stub instead (PII tasks). */
   private?: boolean;
   ts: number;

package/src/hub/events.ts

@@ -12,6 +12,8 @@ export const EVENTS_SCHEMA = 1;
  */
 export type HubEvent =
   | { type: "permission_mode"; peer: string; from: import("./permission-mode.ts").PermissionMode; to: import("./permission-mode.ts").PermissionMode }
+  /** A settings change (#269): the registry key, the value in force before and after (closed words, ids or booleans, never free text) and where it came from. */
+  | { type: "settings"; key: string; from: import("./settings.ts").SettingValue; to: import("./settings.ts").SettingValue; source: "dashboard" | "terminal"; undo?: boolean }
   | { type: "envelope"; id: string; from: string; to?: string[]; priority: string; hop: number; kind?: string; task?: string; bytes?: number; private?: boolean; dropped?: string }
   | { type: "overflow" | "undeliverable"; id: string; from: string; peer: string }
   | { type: "stale"; id: string; from: string; peer: string; task?: string }
@@ -66,7 +68,7 @@ function cutShort(file: string): boolean {
 }
 
 /** An appender that never throws: the state dir can vanish under a running hub, and telemetry must not take it down. */
-export function eventLog(file: string): (e: HubEvent) => void {
+export function eventLog(file: string, onFailure?: (e: HubEvent) => void): (e: HubEvent) => void {
   let first = true;
   return (e) => {
     try {
@@ -75,6 +77,7 @@ export function eventLog(file: string): (e: HubEvent) => void {
       first = false;
       appendFileSync(file, `${lead}${JSON.stringify({ v: EVENTS_SCHEMA, at: new Date().toISOString(), ...e })}\n`);
     } catch {
+      try { onFailure?.(e); } catch { /* telemetry failure reporting is optional too */ }
       // the state dir is gone; the watchdog is stopping the hub
     }
   };

package/src/hub/execution-budget.ts

@@ -1,4 +1,5 @@
 import { Database } from "bun:sqlite";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 
 export type ExecutionUnit = "model_calls" | "tool_calls" | "elapsed_ms" | "tokens";
 export type ExecutionBudgetLimits = Partial<Record<ExecutionUnit, number>>;
@@ -42,6 +43,7 @@ export class ExecutionBudget {
   private readonly db: Database;
   constructor(path: string) {
     this.db = new Database(path, { create: true });
+    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
     this.db.run("PRAGMA journal_mode = WAL");
     this.db.run(`CREATE TABLE IF NOT EXISTS execution_budgets (
       id TEXT PRIMARY KEY, kind TEXT NOT NULL, task_id INTEGER, peers TEXT NOT NULL,

package/src/hub/facts.ts

@@ -3,6 +3,7 @@ import { closeSync, constants, fstatSync, mkdirSync, openSync, readSync, rmSync,
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { sanitize, type PeerId } from "./envelope.ts";
 import { isDenied } from "../local/deny.ts";
+import { hubGitArgv, hubGitEnv } from "./git.ts";
 import { realPath } from "./project.ts";
 
 /**
@@ -275,7 +276,7 @@ export class Facts {
     // One path per line: a newline in a name would shift the answers, and git drops a final carriage return (another file).
     files = files.filter((f) => !/[\r\n]/.test(f));
     if (!files.length) return out;
-    const r = Bun.spawnSync(["git", "cat-file", "--batch-check=%(objectname) %(objecttype)"], { cwd: this.root, stdin: new TextEncoder().encode(files.map((f) => `HEAD:./${f}`).join("\n") + "\n"), stdout: "pipe", stderr: "pipe", env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } });
+    const r = Bun.spawnSync(hubGitArgv(["cat-file", "--batch-check=%(objectname) %(objecttype)"]), { cwd: this.root, stdin: new TextEncoder().encode(files.map((f) => `HEAD:./${f}`).join("\n") + "\n"), stdout: "pipe", stderr: "pipe", env: hubGitEnv({ ...process.env, GIT_OPTIONAL_LOCKS: "0" }) });
     if (r.exitCode !== 0) return out;
     r.stdout.toString().split("\n").forEach((line, i) => {
       const [oid, type] = line.split(" ");
@@ -414,7 +415,7 @@ export class Facts {
       if (!files) {
         // Plumbing only, with optional locks off: an agent's own git commands must never meet a lock the hub holds.
         const git = (...args: string[]) => {
-          const r = Bun.spawnSync(["git", ...args, "--", p], { cwd: this.root, stdout: "pipe", stderr: "pipe", env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } });
+          const r = Bun.spawnSync(hubGitArgv([...args, "--", p]), { cwd: this.root, stdout: "pipe", stderr: "pipe", env: hubGitEnv({ ...process.env, GIT_OPTIONAL_LOCKS: "0" }) });
           return r.exitCode === 0 ? r.stdout.toString().split("\0").filter(Boolean) : undefined;
         };
         // Against HEAD, so a staged change counts (a staged move by both names); a repository without a commit yet has
@@ -693,7 +694,7 @@ export class Facts {
   tree(paths: string[], windows: { peer: PeerId; since: number; until?: number }[] = []): string {
     this.boundary();
     const h = createHash("sha1");
-    const head = Bun.spawnSync(["git", "rev-parse", "-q", "--verify", "HEAD"], { cwd: this.root, stdout: "pipe", stderr: "pipe" });
+    const head = Bun.spawnSync(hubGitArgv(["rev-parse", "-q", "--verify", "HEAD"]), { cwd: this.root, stdout: "pipe", stderr: "pipe", env: hubGitEnv() });
     h.update(head.exitCode === 0 ? head.stdout.toString().trim() : "no-head").update("\0");
     // The files the members wrote while at work in the cohort count too: a symbol-only overlap names no path, and a
     // tool's write outside the named paths still moves the work the integration checked. What they only read never
@@ -780,7 +781,7 @@ export class Facts {
     try {
       writeFileSync(a, before, { mode: 0o600 });
       writeFileSync(b, after, { mode: 0o600 });
-      const r = Bun.spawnSync(["git", "-c", "core.quotepath=off", "diff", "--no-index", "--no-color", "--no-ext-diff", "--unified=2", "--", a, b], { stdout: "pipe", stderr: "pipe" });
+      const r = Bun.spawnSync(hubGitArgv(["-c", "core.quotepath=off", "diff", "--no-index", "--no-color", "--no-ext-diff", "--no-textconv", "--unified=2", "--", a, b]), { stdout: "pipe", stderr: "pipe", env: hubGitEnv() });
       const lines = r.stdout.toString().split("\n");
       const start = lines.findIndex((l) => l.startsWith("@@"));
       if (start === -1) return [];

package/src/hub/git.ts

@@ -0,0 +1,32 @@
+import { spawnSync, type SpawnSyncOptionsWithStringEncoding, type SpawnSyncReturns } from "node:child_process";
+
+/**
+ * The one helper for every git call the hub makes outside the sandbox (#281): the repository's own configuration
+ * must not name a program the hub then runs with its own rights (defense in depth behind the seatbelt profile,
+ * which refuses a sandboxed command the writes that would plant one). Every call gets:
+ * - core.fsmonitor=false: the file-system monitor is an arbitrary command read from the repo config.
+ * - core.hooksPath=/dev/null: hooks come from a non-directory, so every hook lookup fails closed.
+ * - diff.external= (empty): no external diff driver.
+ * - core.pager=cat and --no-pager: no pager, whatever the config says (stdout is a pipe everywhere anyway).
+ * - credential.helper= (empty resets the list) and core.askpass= (empty fails closed), with GIT_TERMINAL_PROMPT=0:
+ *   no hub command authenticates, so any prompt is a bug and must fail instead of running a configured helper.
+ * git has no global switch for filter drivers or textconv: both are per-driver config keys. Of the hub's commands
+ * only the snapshot's `add`/`restore` would run a filter driver, and only a content diff would run textconv — the
+ * hub's one content diff is `diff --no-index`, which DOES read the repository's config (verified: a planted
+ * diff.external runs for it), so that call passes `--no-ext-diff` and `--no-textconv` on top of the config here,
+ * and the driver command of a filter lives in the `.git/config` the seatbelt profile refuses to a sandboxed
+ * command. GIT_CONFIG_NOSYSTEM/global are left alone: those files are the user's own.
+ */
+const SAFE_CONFIG = ["core.fsmonitor=false", "core.hooksPath=/dev/null", "diff.external=", "core.pager=cat", "credential.helper=", "core.askpass="];
+
+/** `["git", ...safe options, ...args]`: use instead of a literal "git" argv anywhere under src/. */
+export const hubGitArgv = (args: string[]): string[] => ["git", "--no-pager", ...SAFE_CONFIG.flatMap((c) => ["-c", c]), ...args];
+
+/** The caller's env plus the no-prompt switch; existing keys (childEnv, GIT_OPTIONAL_LOCKS=0) pass through. */
+export const hubGitEnv = (env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv => ({ ...env, GIT_TERMINAL_PROMPT: "0" });
+
+/** spawnSync form of the same call: the env option is merged with hubGitEnv, everything else passes through. */
+export function hubGitSync(args: string[], options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns<string> {
+  const argv = hubGitArgv(args);
+  return spawnSync(argv[0]!, argv.slice(1), { ...options, env: hubGitEnv(options.env ?? process.env) });
+}

package/src/hub/hub-tools.ts

@@ -53,7 +53,7 @@ export const CONDUCTOR_TOOLS: HubTool[] = [
   tool("hub_task_show", "Read a task's public view and history, its done summary and check result included. PII tasks remain stubs. Only the conductor and the task's current owner and reviewer may use this tool.", { id }, ["id"]),
   tool("hub_task_assign", "Move a task to another peer, as the conductor, or redirect a task you proposed while it is proposed and nobody accepted it. A task that still waits gets the peer as its reserved owner. When you have an explicit capabilities list, the conductor needs assign capability for any assign, the proposer only to hand the task to another peer.", { id, peer: str }, ["id", "peer"]),
   tool("hub_task_escalate", "Escalate a task through the normal task flow, as the conductor. Requires assign capability when explicitly listed.", { id }, ["id"]),
-  tool("hub_peer_start", "Start local, kimi or headless pi. Claude, Codex and Pi TUI requests return a command for the person to run, without launching a terminal.", { peer: { type: "string", enum: ["local", "kimi", "pi", "claude", "codex"] }, mode: { type: "string", enum: ["headless", "tui"] } }, ["peer"]),
+  tool("hub_peer_start", "Start local, kimi, pi, claude or codex in the start mode a person set for it; you cannot choose the mode. A headless peer starts at once. A TUI peer (claude, and pi and codex by default) opens in a terminal with a fixed command; when the hub cannot open a terminal the call fails with the command for the person to run.", { peer: { type: "string", enum: ["local", "kimi", "pi", "claude", "codex"] } }, ["peer"]),
   tool("hub_peer_hold", "Hold a peer's deliveries as the conductor. This hold is separate from the person's hold and budget pauses.", { peer: str }, ["peer"]),
   tool("hub_peer_release", "Release only the conductor hold you placed. Never lifts a person's hold or a budget pause.", { peer: str }, ["peer"]),
 ];

package/src/hub/lifecycle.ts

@@ -1,3 +1,4 @@
+import { isDatabaseBusyReply, RecoveryDatabaseBusy } from "./recovery-error.ts";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from "node:fs";
@@ -5,19 +6,21 @@ import { join } from "node:path";
 import { createServer, type Server } from "node:net";
 import { ControlClient, PROTOCOL, readControl } from "./control-client.ts";
 import { startDaemon } from "./daemon.ts";
+import { terminalOpener } from "./terminal-open.ts";
 import { Registry, type Project } from "./registry.ts";
 import { CODEX_APP, CODEX_PROXY, CONTROL, SWITCHYARD } from "./ports.ts";
 import { assertLifecycleAvailable, recoveryLock } from "./recovery-store.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 
 export type ProjectInspection = {
+  failure?: { code: "database_busy" };
   state: "running" | "stopped" | "stopping" | "unavailable" | "incompatible" | "missing" | "starting";
   status?: any;
   error?: string;
 };
 
 /** A port or PID alone is never evidence that the selected project's hub is alive. */
-export async function inspectProject(project: Project): Promise<ProjectInspection> {
+export async function inspectProject(project: Project, timeoutMs = 3000): Promise<ProjectInspection> {
   if (!existsSync(project.root)) return { state: "missing", error: "project directory is missing" };
   const control = readControl(project.stateDir);
   if (control) {
@@ -32,8 +35,9 @@ export async function inspectProject(project: Project): Promise<ProjectInspectio
     try {
       // Older manifests omit identity. Authenticate first, then require the full current contract.
       client = await ControlClient.connect(project.stateDir, { role: "console", projectRoot: project.root,
-        ...(control.projectId ? { projectId: project.id } : {}), ...(control.instanceId ? { instanceId: control.instanceId } : {}) });
-      const response = await client.request({ t: "status" }, 3000);
+        ...(control.projectId ? { projectId: project.id } : {}), ...(control.instanceId ? { instanceId: control.instanceId } : {}) }, timeoutMs);
+      const response = await client.request({ t: "status" }, timeoutMs);
+      if (isDatabaseBusyReply(response)) return { state: "unavailable", error: new RecoveryDatabaseBusy().message, failure: { code: "database_busy" } };
       if (!response.status || response.status.projectId !== project.id || !response.status.instanceId || response.status.cwd !== project.root) {
         return { state: "unavailable", error: "authenticated hub identity does not match registration" };
       }
@@ -112,7 +116,9 @@ export async function runProjectDaemon(project: Project, unattended = false): Pr
         try {
           daemon = await startDaemon({ cwd: project.root, stateDir: project.stateDir, projectId: project.id, instanceId,
             controlPort: base + CONTROL, codexAppPort: base + CODEX_APP, codexProxyPort: base + CODEX_PROXY,
-            switchyardPort: base + SWITCHYARD, unattended, onShutdownStart });
+            switchyardPort: base + SWITCHYARD, unattended, onShutdownStart,
+            // #269: the real terminal providers belong to the running product; a daemon built without them opens nothing.
+            terminal: (template) => terminalOpener({ template, cwd: project.root, stateDir: project.stateDir }) });
           break;
         } catch (error) {
           if ((error as NodeJS.ErrnoException).code !== "EADDRINUSE") throw error;

package/src/hub/manager.ts

@@ -9,15 +9,19 @@ import { hubHome } from "./project.ts";
 import { startDashboard } from "./ui.ts";
 import { projectChain } from "../memory/recall.ts";
 import type { ProjectInspection } from "./lifecycle.ts";
+import { MAX_COMMAND_MS } from "../cli/terminal-recovery.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 
+const MANAGER_OWNER_DB_BUSY_TIMEOUT_MS = 5000;
 export type ProjectRecord = Project;
 export type Lifecycle = {
   inspectProject(project: Project): Promise<ProjectInspection>;
   startProject(project: Project, options?: { unattended?: boolean; env?: NodeJS.ProcessEnv }): Promise<any>;
   stopProject(project: Project, expectedInstance?: string): Promise<void>;
 };
-export type ManagerOptions = { registry?: Registry; lifecycle?: Lifecycle; home?: string; cli?: string; orphanWatchMs?: number };
+export type ManagerOptions = { registry?: Registry; lifecycle?: Lifecycle; home?: string; cli?: string; orphanWatchMs?: number;
+  /** Test clock seam: maps nominal forwarding deadlines, never comes from dashboard input. */
+  forwardTimeoutMs?: (action: string, nominalMs: number) => number };
 type ManagerHandle = { stop(): Promise<void>; stopped: Promise<void> };
 type Manifest = { port: number; protocol: number; instanceId: string; pid: number; pidSignature?: string };
 const active = new Map<string, { handle: ManagerHandle; issue(): string }>();
@@ -45,7 +49,7 @@ async function bounded<T>(promise: Promise<T>, ms: number): Promise<T> {
 function claimOwner(path: string, instanceId: string, signature: string | undefined): Database {
   const db = new Database(path, { create: true });
   try {
-    db.run("PRAGMA busy_timeout = 5000");
+    db.run(`PRAGMA busy_timeout = ${MANAGER_OWNER_DB_BUSY_TIMEOUT_MS}`);
     db.run("CREATE TABLE IF NOT EXISTS owner (slot INTEGER PRIMARY KEY CHECK (slot = 1), instance_id TEXT NOT NULL, pid INTEGER NOT NULL, signature TEXT)");
     if (!(db.query("PRAGMA table_info(owner)").all() as { name: string }[]).some((c) => c.name === "signature")) {
       try { db.run("ALTER TABLE owner ADD COLUMN signature TEXT"); }
@@ -148,11 +152,20 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
           await bounded(lifecycle.stopProject(project, input.instanceId), 20_000);
           return { ok: true };
         }
-        if (!["snapshot", "send", "pause", "resume", "permit", "propose", "assign"].includes(String(input.action))) return { ok: false, error: "invalid dashboard action" };
+        // The settings actions (#269) reach the project hub as an ordinary session's: this dashboard opens no settings session.
+        if (!["snapshot", "send", "pause", "resume", "permit", "propose", "assign", "setting", "setting_undo", "setting_preview", "start_peer"].includes(String(input.action))) return { ok: false, error: "invalid dashboard action" };
         client = await ControlClient.connect(project.stateDir, { role: "console", projectId: project.id, projectRoot: project.root, instanceId: input.instanceId });
-        return await client.request(input.action === "snapshot"
+        const nominalMs = input.action === "start_peer" ? MAX_COMMAND_MS + 5_000 : 10_000;
+        const timeoutMs = options.forwardTimeoutMs?.(String(input.action), nominalMs) ?? nominalMs;
+        const result = await client.request(input.action === "snapshot"
           ? { t: "ui_snapshot", after: input.after ?? 0 }
-          : { t: "ui_action", action: input, instanceId: input.instanceId }, 10_000);
+          : { t: "ui_action", action: input, instanceId: input.instanceId }, timeoutMs);
+        // ControlClient resolves its deadline as this exact sentinel; a hub refusal stays a known failure.
+        if (input.action === "start_peer" && result.ok === false && result.error === `no answer from the hub within ${Math.round(timeoutMs / 1000)} s`) {
+          const text = "Start result is unconfirmed. Check the Peers panel before retrying; the hub may still be starting the peer.";
+          return { ok: false, unconfirmed: true, text, error: text };
+        }
+        return result;
       } catch (error) { return { ok: false, error: safeError(error) }; }
       finally { client?.close(); }
     };

package/src/hub/peers.ts

@@ -4,6 +4,8 @@ export interface DeliveryReceipt {
   id: string;
   state: "accepted" | "completed" | "failed_safe" | "needs_review";
   reason?: string;
+  /** A provider refused before acceptance for quota; requeue without spending poison retries while paused. */
+  quota?: true;
 }
 
 export interface PeerAdapter {
@@ -18,13 +20,13 @@ export interface PeerAdapter {
   /** Optional: feed envelopes into the turn that is running now. Only called while `state === "busy"`. */
   steer?(envs: Envelope[], deliveryId?: string): Promise<void>;
   start(): Promise<void>;
-  stop(): Promise<void>;
+  stop(reason?: string): Promise<void>;
   /** Set by the bus. The peer said something worth sharing. */
   onMessage?: (body: string, opts?: EnvelopeOpts) => unknown;
   /** Set by the bus. */
   onState?: (state: PeerState) => void;
   /** Set by the bus. A delivery that had resolved turned out not to reach the agent: put it back. */
-  onFailed?: (envs: Envelope[]) => void;
+  onFailed?: (envs: Envelope[], failure?: { quota?: true }) => void;
   /** Correlated durable-delivery lifecycle, emitted only when the bus supplied an id. */
   onDelivery?: (receipt: DeliveryReceipt) => void;
   /** Safe restart metadata only: ids and launch parameters, never prompt/message text. */
@@ -38,7 +40,7 @@ export abstract class BasePeer implements PeerAdapter {
   /** Returns a reason (a string) when the hub refused the message (issue #38). */
   onMessage?: (body: string, opts?: EnvelopeOpts) => unknown;
   onState?: (state: PeerState) => void;
-  onFailed?: (envs: Envelope[]) => void;
+  onFailed?: (envs: Envelope[], failure?: { quota?: true }) => void;
   onDelivery?: (receipt: DeliveryReceipt) => void;
   private _state: PeerState = "offline";
   private timer: ReturnType<typeof setTimeout> | undefined;
@@ -77,12 +79,12 @@ export abstract class BasePeer implements PeerAdapter {
     this.onDelivery?.(receipt);
   }
 
-  private clearWatchdog(): void {
+  protected clearWatchdog(): void {
     if (this.timer) clearTimeout(this.timer);
     this.timer = undefined;
   }
 
   abstract deliver(envs: Envelope[], deliveryId?: string): Promise<void>;
   abstract start(): Promise<void>;
-  abstract stop(): Promise<void>;
+  abstract stop(reason?: string): Promise<void>;
 }

package/src/hub/permission-mode.ts

@@ -17,6 +17,20 @@ export function permissionDefaults(value: unknown): Record<string, PermissionMod
   }
   return result;
 }
+/** Approval frequency does not create a common sandbox across native peers. */
+export function permissionBoundary(peer: string): string {
+  if (peer === "pi" || peer === "local") return `${peer}: inside hub sandbox, path guard and denylist`;
+  if (peer === "claude" || peer === "codex") return `${peer}: native vendor bounds; no hub sandbox`;
+  return `${peer}: runs its own tools; NO hub sandbox`;
+}
+/** What a mode lets a peer do without asking, in one line a person reads before choosing it (#269). */
+export function permissionGrant(peer: string, mode: PermissionMode): string {
+  if (mode === "ask") return peer === "codex" ? "the session's own approval policy applies again" : peer === "kimi" ? "Kimi asks as it does on its own" : peer === "claude" ? "Claude's own permission rules decide" : "every write, edit and shell command asks";
+  if (peer === "kimi") return mode === "never-ask" ? "Kimi's auto mode: nothing asks" : "Kimi's yolo mode: it asks only where it judges it must";
+  if (peer === "codex") return mode === "never-ask" ? "approval policy never on every turn: nothing asks" : "approval policy on-request on every turn";
+  if (peer === "claude") return mode === "never-ask" ? "every tool runs without asking" : "file tools on project files run without asking, outside .agenthub, .git and agent configuration; other tools keep Claude's own rules";
+  return mode === "never-ask" ? "every tool runs without asking, inside the hub sandbox and path guard" : "write and edit inside the project run without asking; shell and git writes still ask";
+}
 export const PI_EDIT_TOOLS = new Set(["edit", "write"]);
 /** Native agent policy files are never included in scoped automatic file grants. */
 export const AGENT_CONFIG_SEGMENTS: ReadonlySet<string> = new Set([".claude", ".codex", ".qwen", ".kimi", ".pi", ".mcp.json"]);

package/src/hub/project.ts

@@ -2,6 +2,7 @@ import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
+import { hubGitSync } from "./git.ts";
 
 const canonical = (path: string): string => {
   const absolute = resolve(path);
@@ -39,7 +40,7 @@ export function realPath(path: string): string {
 }
 
 function gitRoot(dir: string): string | undefined {
-  const result = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  const result = hubGitSync(["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
   if (result.status !== 0) return undefined;
   const root = result.stdout.trim();
   return root ? canonical(root) : undefined;

package/src/hub/recovery-error.ts

@@ -0,0 +1,31 @@
+import { sanitize } from "./envelope.ts";
+
+/** Additive recovery outcome: older clients still receive ok:false and a useful error. */
+export class RecoveryDatabaseBusy extends Error {
+  readonly code = "database_busy";
+  readonly retryable = true;
+  constructor() {
+    super("database_busy: a database is busy; wait for the other connection to settle before retrying the request");
+  }
+}
+
+export function isDatabaseBusy(error: unknown): boolean {
+  if (error instanceof RecoveryDatabaseBusy) return true;
+  if (!error || typeof error !== "object") return false;
+  const value = error as { code?: unknown; errno?: unknown };
+  if (typeof value.code === "string") return /^(SQLITE_BUSY|SQLITE_LOCKED)(_|$)/.test(value.code);
+  return error instanceof Error && error.name === "SQLiteError"
+    && typeof value.errno === "number" && value.errno > 0 && [5, 6].includes(value.errno & 255);
+}
+
+/** Only exact legacy SQLite refusals are inferred from an authenticated hub reply. */
+export function isDatabaseBusyReply(reply: any): boolean {
+  return reply?.ok === false && (reply.code === "database_busy"
+    || reply.error === "database is locked" || reply.error === "database table is locked");
+}
+
+/** Frames only: retain the throw site without carrying a native error's message. */
+export function databaseBusySite(error: unknown): string[] {
+  const stack = error instanceof Error ? error.stack : undefined;
+  return (stack ?? "").split("\n").filter(line => /^\s*at /.test(line)).slice(0, 8).map(line => sanitize(line.trim()).slice(0, 400));
+}

package/src/hub/recovery-store.ts

@@ -5,6 +5,7 @@ import { Database } from "bun:sqlite";
 import { hubHome } from "./project.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 
+const RUNNER_DB_BUSY_TIMEOUT_MS = 3000;
 export const operationIdPattern = /^[a-f0-9-]{36}$/;
 export function operationPath(id: string, home = hubHome()): string {
   if (!operationIdPattern.test(id)) throw new Error("invalid recovery operation ID");
@@ -74,6 +75,12 @@ export function recoveryCommand(op: { id: string; sourceRoot?: string }, action:
   return `${cli} recovery ${action} ${op.id}${flags ? ` ${flags}` : ""}`;
 }
 
+/** #272: the command above as an argv for `bun`, which a screen runs instead of printing; with no coordinator of its own, this release's. */
+export function recoveryArgv(op: { id: string; sourceRoot?: string }, action: "status" | "resume" | "abort" | "dispose", flags: string[] = []): string[] {
+  const entry = op.sourceRoot && coordinatorCurrent(op.sourceRoot) ? join(op.sourceRoot, "src/cli/main.js") : join(import.meta.dir, "../cli/main.js");
+  return [entry, "recovery", action, op.id, ...flags];
+}
+
 /**
  * Whether a coordinator has the #215 recovery commands (dispose, re-preparation, next actions).
  * ponytail: a text sniff of its upgrade.ts; a rename or re-export reads as an older coordinator (the running release is
@@ -105,7 +112,7 @@ export function recoveryRunner(id: string, home = hubHome()): number | "unknown"
   let db: Database | undefined;
   try {
     db = new Database(path, { readonly: true });
-    db.run("PRAGMA busy_timeout = 3000"); // a claim in progress must not read as no runner
+    db.run(`PRAGMA busy_timeout = ${RUNNER_DB_BUSY_TIMEOUT_MS}`); // a claim in progress must not read as no runner
     // A crash between creating the file and its table leaves no runner; claimRunner creates the table and claims.
     if (!db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'runner'").get()) return undefined;
     const row = db.query(`SELECT pid${signed(db) ? ", signature" : ""} FROM runner WHERE slot = 1`).get() as { pid: number; signature?: string | null } | null;
@@ -116,14 +123,46 @@ export function recoveryRunner(id: string, home = hubHome()): number | "unknown"
   } catch { return "unknown"; } finally { db?.close(); }
 }
 
+/**
+ * #272: the pid of the runner that holds `id`, only when its claim carries a process signature that still matches.
+ * `recoveryRunner` answers a claim without one (a coordinator of 0.12.20 or older, or a `ps` that failed at claim
+ * time) from its bare pid, which is enough to wait for it and never enough to signal it.
+ */
+export function signedRunner(id: string, home = hubHome()): number | undefined {
+  const path = `${operationPath(id, home)}.runner.db`;
+  if (!existsSync(path)) return undefined;
+  let db: Database | undefined;
+  try {
+    db = new Database(path, { readonly: true });
+    db.run(`PRAGMA busy_timeout = ${RUNNER_DB_BUSY_TIMEOUT_MS}`);
+    if (!signed(db)) return undefined;
+    const row = db.query("SELECT pid, signature FROM runner WHERE slot = 1").get() as { pid: number; signature: string | null } | null;
+    if (!row?.signature || !Number.isSafeInteger(row.pid) || row.pid < 1) return undefined;
+    return processSignature(row.pid) === row.signature ? row.pid : undefined;
+  } catch { return undefined; } finally { db?.close(); }
+}
+
+/** #272: stop that verified runner and wait until no runner holds the operation. False when one still does, or cannot be verified. */
+export async function stopSignedRunner(id: string, home = hubHome(), waitMs = 5000): Promise<boolean> {
+  if (recoveryRunner(id, home) === undefined) return true;
+  const pid = signedRunner(id, home);
+  if (pid === undefined) return false;
+  try { process.kill(pid, "SIGTERM"); } catch { /* gone meanwhile */ }
+  for (const deadline = Date.now() + waitMs; Date.now() < deadline;) {
+    if (recoveryRunner(id, home) === undefined) return true;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return false;
+}
+
 /** An exclusive runner claim. Never steal a live or uncertain owner on resume. */
 export function claimRunner(id: string, home = hubHome()): () => void {
   const path = `${operationPath(id, home)}.runner.db`;
-  const db = new Database(path, { create: true });
-  chmodSync(path, 0o600);
   const nonce = randomUUID();
+  const db = new Database(path, { create: true });
   try {
-    db.run("PRAGMA busy_timeout = 3000");
+    db.run(`PRAGMA busy_timeout = ${RUNNER_DB_BUSY_TIMEOUT_MS}`);
+    chmodSync(path, 0o600);
     db.run("CREATE TABLE IF NOT EXISTS runner (slot INTEGER PRIMARY KEY, pid INTEGER NOT NULL, nonce TEXT NOT NULL, signature TEXT)");
     if (!signed(db)) {
       try { db.run("ALTER TABLE runner ADD COLUMN signature TEXT"); }

package/src/hub/registry.ts

@@ -7,6 +7,7 @@ import { processLiveness } from "../pi/process-signature.ts";
 
 const BASE_PORT = 4600;
 const STRIDE = 10;
+export const REGISTRY_DB_BUSY_TIMEOUT_MS = 5000;
 const MAX_PORT = 65535 - 3;
 const LEGACY_DONE = "legacy_ports_imported";
 type Tx = { immediate(): void };
@@ -50,7 +51,7 @@ export class Registry {
     this.path = path;
     mkdirSync(dirname(path), { recursive: true });
     this.db = new Database(path, { create: true });
-    this.db.run("PRAGMA busy_timeout = 5000");
+    this.db.run(`PRAGMA busy_timeout = ${REGISTRY_DB_BUSY_TIMEOUT_MS}`);
     try {
       this.db.run("PRAGMA journal_mode = WAL");
     } catch (error) {