@staix/agent-hub 0.12.22 → 0.12.23

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 {
@@ -24,7 +26,7 @@ export interface PeerAdapter {
   /** 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,7 +79,7 @@ export abstract class BasePeer implements PeerAdapter {
     this.onDelivery?.(receipt);
   }
 
-  private clearWatchdog(): void {
+  protected clearWatchdog(): void {
     if (this.timer) clearTimeout(this.timer);
     this.timer = undefined;
   }

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");
@@ -111,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;
@@ -133,7 +134,7 @@ export function signedRunner(id: string, home = hubHome()): number | undefined {
   let db: Database | undefined;
   try {
     db = new Database(path, { readonly: true });
-    db.run("PRAGMA busy_timeout = 3000");
+    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;
@@ -157,11 +158,11 @@ export async function stopSignedRunner(id: string, home = hubHome(), waitMs = 50
 /** 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) {

package/src/hub/routing.ts

@@ -1,6 +1,6 @@
 import { readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
-import type { Task, TaskClass } from "./board.ts";
+import { CLASSES, type Task, type TaskClass } from "./board.ts";
 import type { PeerId, PeerState } from "./envelope.ts";
 
 import { parseHubRoutes, type HubRoute } from "../models/route/config.ts";
@@ -36,21 +36,115 @@ export interface Routing {
   constraints: { pii: "local_only" | "off"; long_context: "skip_local" | "off"; budget_paused: "skip_peer" | "off" };
   /** `efficient_wait_ms`, opt-in (#199): how long a hub/auto request waits for a busy MLX slot before it moves to dgx/fast; absent, nothing moves for load. */
   pi: { dgx_max_context_tokens: number; mlx_max_context_tokens: number; efficient_wait_ms?: number };
+  /** The keys `.agenthub/routing.local.toml` set (#269), such as `classes.implement.peers`; every other value is routing.toml's. */
+  sources?: Record<string, "routing.local.toml">;
+}
+
+/**
+ * What `.agenthub/routing.local.toml` may hold (#269): a person's machine-local override of these keys and nothing
+ * else, so a settings write can never reach targets, routes, signals or the PII constraint.
+ */
+export interface RoutingOverlay {
+  stay_switch?: StaySwitchMode;
+  classes?: Partial<Record<TaskClass, { peers?: PeerId[]; escalate_to?: PeerId[]; route?: string; pi_backend?: "dgx" | "mlx" }>>;
+}
+export const OVERLAY_FILE = "routing.local.toml";
+const OVERLAY_PEER = /^[a-z][a-z0-9-]{0,31}$/;
+const OVERLAY_ROUTE = /^[A-Za-z0-9][A-Za-z0-9_./-]{0,63}$/;
+const OVERLAY_PEERS_MAX = 8;
+
+/** A checked copy of an overlay, in a fixed key order; throws on anything outside the keys above. */
+export function checkOverlay(raw: unknown): RoutingOverlay {
+  const bad = (what: string): never => { throw new Error(`${OVERLAY_FILE}: ${what}`); };
+  const table = (value: unknown, where: string): Record<string, unknown> => (!value || typeof value !== "object" || Array.isArray(value) ? bad(`${where} must be a table`) : value as Record<string, unknown>);
+  const peers = (value: unknown, where: string): PeerId[] => {
+    if (!Array.isArray(value) || value.length > OVERLAY_PEERS_MAX || value.some((p) => typeof p !== "string" || !OVERLAY_PEER.test(p)) || new Set(value).size !== value.length) bad(`${where} must list up to ${OVERLAY_PEERS_MAX} distinct peer ids`);
+    return [...(value as PeerId[])];
+  };
+  const top = table(raw, "the file");
+  const out: RoutingOverlay = {};
+  for (const [key, value] of Object.entries(top)) {
+    if (key === "stay_switch") {
+      if (value !== "off" && value !== "shadow" && value !== "enforce") bad('stay_switch must be "off", "shadow" or "enforce"');
+      out.stay_switch = value as StaySwitchMode;
+    } else if (key === "classes") {
+      for (const [name, policy] of Object.entries(table(value, "classes"))) {
+        if (!(CLASSES as readonly string[]).includes(name)) bad(`[classes.${name}] is not a task class`);
+        const entry: NonNullable<RoutingOverlay["classes"]>[TaskClass] = {};
+        for (const [field, v] of Object.entries(table(policy, `[classes.${name}]`))) {
+          if (field === "peers" || field === "escalate_to") entry[field] = peers(v, `[classes.${name}] ${field}`);
+          else if (field === "route") entry.route = typeof v === "string" && OVERLAY_ROUTE.test(v) ? v : bad(`[classes.${name}] route must be a route id`);
+          else if (field === "pi_backend") entry.pi_backend = v === "dgx" || v === "mlx" ? v : bad(`[classes.${name}] pi_backend must be "dgx" or "mlx"`);
+          else bad(`[classes.${name}] ${field} is not a setting this file holds; edit routing.toml`);
+        }
+        if (Object.keys(entry).length) (out.classes ??= {})[name as TaskClass] = entry;
+      }
+    } else bad(`${key} is not a setting this file holds; edit routing.toml`);
+  }
+  return out;
+}
+export const parseOverlay = (text: string): RoutingOverlay => checkOverlay(Bun.TOML.parse(text));
+
+/** The overlay as TOML. Every value is a checked id or a closed word, so a JSON string is a valid TOML basic string. */
+export function overlayToml(overlay: RoutingOverlay): string {
+  const checked = checkOverlay(overlay);
+  const lines = ["# Written by ahub settings and the dashboard (machine-local). It overrides routing.toml key by key."];
+  if (checked.stay_switch) lines.push(`stay_switch = ${JSON.stringify(checked.stay_switch)}`);
+  for (const name of CLASSES) {
+    const entry = checked.classes?.[name];
+    if (!entry) continue;
+    lines.push("", `[classes.${name}]`);
+    for (const field of ["peers", "escalate_to"] as const) if (entry[field]) lines.push(`${field} = [${entry[field]!.map((p) => JSON.stringify(p)).join(", ")}]`);
+    if (entry.route) lines.push(`route = ${JSON.stringify(entry.route)}`);
+    if (entry.pi_backend) lines.push(`pi_backend = ${JSON.stringify(entry.pi_backend)}`);
+  }
+  return `${lines.join("\n")}\n`;
 }
 
 const TEMPLATE = join(import.meta.dir, "..", "..", "templates", "routing.toml");
 export const LOCAL: PeerId = "local";
 export const PI: PeerId = "pi";
 
-/** `.agenthub/routing.toml`, or the shipped default when the project has none. Throws on a file that does not parse or lacks a fixed model. */
+/**
+ * `.agenthub/routing.toml`, or the shipped default when the project has none, with `.agenthub/routing.local.toml`
+ * merged over it key by key (#269). Throws on a file that does not parse or lacks a fixed model.
+ */
 export function loadRouting(cwd: string): Routing {
-  let text: string;
+  const text = routingText(cwd);
+  let overlay: string | undefined;
   try {
-    text = readFileSync(join(cwd, ".agenthub", "routing.toml"), "utf8");
+    overlay = readFileSync(join(cwd, ".agenthub", OVERLAY_FILE), "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  return parseRouting(text, overlay === undefined ? undefined : parseOverlay(overlay));
+}
+
+/** The project's routing.toml as text, or the shipped default when it has none. */
+export function routingText(cwd: string): string {
+  try {
+    return readFileSync(join(cwd, ".agenthub", "routing.toml"), "utf8");
   } catch {
-    text = readFileSync(TEMPLATE, "utf8");
+    return readFileSync(TEMPLATE, "utf8");
   }
+}
+
+/** The policy of a routing.toml text with an overlay merged over it: what `loadRouting` reads, without the disk. */
+export function parseRouting(text: string, overlay?: RoutingOverlay): Routing {
   const raw = Bun.TOML.parse(text) as Partial<Routing>;
+  const sources: NonNullable<Routing["sources"]> = {};
+  if (overlay) {
+    const checked = checkOverlay(overlay);
+    if (checked.stay_switch) { (raw as Record<string, unknown>).stay_switch = checked.stay_switch; sources.stay_switch = OVERLAY_FILE; }
+    const known = new Set([...Object.keys(raw.routes ?? {}), ...Object.keys(raw.hub_routes ?? {})]);
+    for (const [name, entry] of Object.entries(checked.classes ?? {})) {
+      if (entry.route && !known.has(entry.route)) throw new Error(`${OVERLAY_FILE}: [classes.${name}] route ${entry.route} names no route in routing.toml`);
+      const classes = (raw.classes ??= {}) as Record<string, ClassPolicy>;
+      // A class the shared file does not have starts from an empty peer list: the overlay may add its own.
+      classes[name] = { ...(classes[name] ?? { peers: [] }), ...entry };
+      for (const field of Object.keys(entry)) sources[`classes.${name}.${field}`] = OVERLAY_FILE;
+    }
+  }
   if (!raw.local?.fixed_model) throw new Error("routing.toml: [local] fixed_model is required (the path that works without Switchyard)");
   const signals = { pii_patterns: [], long_context_tokens: 120_000, pii_screen: "off" as const, ...raw.signals };
   for (const p of signals.pii_patterns) new RegExp(p); // a bad pattern fails here, at load, not in the middle of an assignment
@@ -82,22 +176,26 @@ export function loadRouting(cwd: string): Routing {
     signals,
     constraints: { pii: "local_only", long_context: "skip_local", budget_paused: "skip_peer", ...raw.constraints },
     pi,
+    ...(Object.keys(sources).length ? { sources } : {}),
   };
 }
 
-const cache = new Map<string, { mtime: number; routing: Routing }>();
+const cache = new Map<string, { mtime: string; routing: Routing }>();
 
 /**
  * loadRouting behind an mtime check. routing.toml is edited while the hub runs and read on every task operation;
  * a half-saved file must not abort an operation midway, so the last good parse stays in force until the file parses again.
  */
 export function currentRouting(cwd: string, log: (line: string) => void = () => {}): Routing {
-  let mtime = 0;
-  try {
-    mtime = statSync(join(cwd, ".agenthub", "routing.toml")).mtimeMs;
-  } catch {
-    // no project file: the shipped template
-  }
+  // Both files count: a settings write changes only the overlay.
+  const mtime = ["routing.toml", OVERLAY_FILE].map((name) => {
+    try {
+      const stat = statSync(join(cwd, ".agenthub", name));
+      return `${stat.mtimeMs}/${stat.size}`;
+    } catch {
+      return 0; // no project file: the shipped template, or no overlay
+    }
+  }).join(":");
   const hit = cache.get(cwd);
   if (hit && hit.mtime === mtime) return hit.routing;
   try {
@@ -106,7 +204,7 @@ export function currentRouting(cwd: string, log: (line: string) => void = () =>
     return routing;
   } catch (e) {
     if (!hit) throw e;
-    log(`routing.toml does not load, keeping the previous policy: ${(e as Error).message}`);
+    log(`routing does not load, keeping the previous policy: ${(e as Error).message}`);
     cache.set(cwd, { mtime, routing: hit.routing });
     return hit.routing;
   }
@@ -176,6 +274,9 @@ export function assign(
 ): Assignment {
   const policy = routing.classes[task.class];
   const trace: string[] = [`class ${task.class}${policy ? "" : " (no [classes] entry: only an explicit owner can take it)"}`, `signals: ${task.signals.join(", ") || "none"}`];
+  // Which file each of this class's values comes from (#269), only when the machine-local overlay sets one.
+  const local = Object.keys(routing.sources ?? {}).filter((key) => key.startsWith(`classes.${task.class}.`)).map((key) => key.slice(`classes.${task.class}.`.length));
+  if (local.length) trace.push(`policy source: ${local.join(", ")} from ${OVERLAY_FILE}; the rest from routing.toml`);
   // A reserved owner (issue #207) is offered the task first. Named candidates (an assign, an escalation, a relay) replace it.
   const reserved = opts.candidates ? undefined : task.reserved ?? undefined;
   // Readiness is an input like peer states (issue #34): a task that waits for others goes to nobody yet.