@staix/agent-hub 0.12.21 → 0.12.23

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.

package/src/hub/settings.ts

@@ -0,0 +1,392 @@
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { CLASSES, type TaskClass } from "./board.ts";
+import { configTracked } from "./config-trust.ts";
+import { PERMISSION_MODES, permissionBoundary } from "./permission-mode.ts";
+import { START_MODE_PEERS, START_MODES } from "./start-mode.ts";
+import { OVERLAY_FILE, overlayToml, parseOverlay, parseRouting, routingText, type Routing, type RoutingOverlay } from "./routing.ts";
+
+/**
+ * #269: the settings a person may change from the dashboard or `ahub settings`. A key that is not in SETTINGS cannot be
+ * written by either. Writes go only to the machine-local files (`.agenthub/config.local.json`,
+ * `.agenthub/routing.local.toml`), never to a tracked one.
+ */
+export const SETTING_PEERS = ["claude", "codex", "kimi", "pi", "local"] as const;
+/** `null` removes the machine-local value, so the shared file's or the default applies again. */
+export type SettingValue = string | boolean | string[] | null;
+export interface SettingDef {
+  key: string;
+  group: "Permissions" | "Start" | "Routing" | "Switches";
+  label: string;
+  type: "enum" | "boolean" | "peers";
+  /** The closed values of an enum; a route setting takes the project's own route ids instead. */
+  values?: readonly string[];
+  /** `runtime` lives in the running hub only; the others are the machine-local file that holds the value. */
+  store: "runtime" | "config" | "routing";
+  /** `peer start`: stored, and taken up by the running hub at that peer's next start. */
+  applies: "live" | "peer start" | "hub start";
+  /** `raises`: only a settings session or a person's terminal may set it, except to `floor`. */
+  risk: "safe" | "raises";
+  floor?: string | boolean;
+  /** Where the value sits inside its file (or, for `runtime`, the peer). */
+  path: readonly string[];
+}
+
+const PEER = /^[a-z][a-z0-9-]{0,31}$/;
+const PEERS_MAX = 8;
+const perClass = (name: TaskClass): SettingDef[] => [
+  { key: `routing.classes.${name}.peers`, group: "Routing", label: `${name}: owner preference order`, type: "peers", store: "routing", applies: "live", risk: "raises", path: ["classes", name, "peers"] },
+  { key: `routing.classes.${name}.escalate_to`, group: "Routing", label: `${name}: escalation order`, type: "peers", store: "routing", applies: "live", risk: "raises", path: ["classes", name, "escalate_to"] },
+  { key: `routing.classes.${name}.route`, group: "Routing", label: `${name}: local worker route`, type: "enum", store: "routing", applies: "live", risk: "raises", path: ["classes", name, "route"] },
+  { key: `routing.classes.${name}.pi_backend`, group: "Routing", label: `${name}: Pi backend`, type: "enum", values: ["dgx", "mlx"], store: "routing", applies: "live", risk: "raises", path: ["classes", name, "pi_backend"] },
+];
+export const SETTINGS: readonly SettingDef[] = [
+  ...SETTING_PEERS.map((peer): SettingDef => ({ key: `permission.${peer}`, group: "Permissions", label: `${peer}: mode now`, type: "enum", values: PERMISSION_MODES, store: "runtime", applies: "live", risk: "raises", floor: "ask", path: [peer] })),
+  ...SETTING_PEERS.map((peer): SettingDef => ({ key: `permission_modes.${peer}`, group: "Permissions", label: `${peer}: mode at hub start`, type: "enum", values: PERMISSION_MODES, store: "config", applies: "hub start", risk: "raises", floor: "ask", path: ["permission_modes", peer] })),
+  ...START_MODE_PEERS.map((peer): SettingDef => ({ key: `peers.${peer}.start_mode`, group: "Start", label: `${peer}: start mode (tui unless set)`, type: "enum", values: START_MODES, store: "config", applies: "peer start", risk: "raises", floor: "tui", path: ["peers", peer, "start_mode"] })),
+  { key: "pi.auto_start", group: "Start", label: "Start Pi with the hub", type: "boolean", store: "config", applies: "hub start", risk: "raises", floor: false, path: ["pi", "auto_start"] },
+  { key: "routing.stay_switch", group: "Routing", label: "Stay or switch (hub/auto and stage routes)", type: "enum", values: ["off", "shadow", "enforce"], store: "routing", applies: "live", risk: "raises", path: ["stay_switch"] },
+  ...CLASSES.flatMap(perClass),
+  { key: "research.enabled", group: "Switches", label: "Research records", type: "boolean", store: "config", applies: "hub start", risk: "safe", path: ["research", "enabled"] },
+  { key: "approvals.notify", group: "Switches", label: "Desktop notice for a waiting approval", type: "boolean", store: "config", applies: "hub start", risk: "safe", path: ["approvals", "notify"] },
+  { key: "snapshots.enabled", group: "Switches", label: "Per-turn snapshots", type: "boolean", store: "config", applies: "hub start", risk: "safe", path: ["snapshots", "enabled"] },
+  { key: "coordination", group: "Switches", label: "Coordination of overlapping owners", type: "enum", values: ["advisory", "turn-free"], store: "config", applies: "hub start", risk: "safe", path: ["coordination"] },
+];
+
+/**
+ * Never editable from settings, whatever the session: these choose what the hub executes or where secrets and task
+ * text go. A key equal to an entry, or below it, is refused by name.
+ */
+export const NEVER_EDITABLE = ["kimi_cmd", "codex_bin", "pi.cmd", "checks", "mlx", "omniroute", "memory.worker_url", "local.read_allow", "local.bash_network", "local.network_allow", "bench.enabled", "terminal"] as const;
+
+/** The definition of a key, or why there is none. */
+export function settingDef(key: unknown): SettingDef | string {
+  if (typeof key !== "string" || key.length > 80) return "unknown setting";
+  const found = SETTINGS.find((s) => s.key === key);
+  if (found) return found;
+  if (NEVER_EDITABLE.some((never) => key === never || key.startsWith(`${never}.`))) return `${key} chooses what the hub runs or where secrets and task text go: it is never editable from settings; edit .agenthub/config.local.json in your editor`;
+  return "unknown setting; run ahub settings list";
+}
+
+/** The checked value, or a thrown reason. `routes`: the route ids the project's routing defines. */
+export function checkSettingValue(def: SettingDef, raw: unknown, routes: readonly string[] = []): SettingValue {
+  if (raw === null) {
+    if (def.store === "runtime") throw new Error(`${def.key} has no stored value to remove`);
+    return null;
+  }
+  if (def.type === "boolean") {
+    if (typeof raw !== "boolean") throw new Error(`${def.key} takes true or false`);
+    return raw;
+  }
+  if (def.type === "peers") {
+    if (!Array.isArray(raw) || raw.length > PEERS_MAX || raw.some((p) => typeof p !== "string" || !PEER.test(p)) || new Set(raw).size !== raw.length) throw new Error(`${def.key} takes up to ${PEERS_MAX} distinct peer ids`);
+    return [...(raw as string[])];
+  }
+  const values = def.values ?? routes;
+  if (typeof raw !== "string" || !values.includes(raw)) throw new Error(`${def.key} takes one of: ${values.join(", ") || "(the project defines no route)"}`);
+  return raw;
+}
+
+/** A terminal's text for a value: `inherit` removes the machine-local value, a peers setting takes a comma list. */
+export function parseSettingText(def: SettingDef, text: string): unknown {
+  if (text === "inherit") return null;
+  if (def.type === "boolean") return text === "true" ? true : text === "false" ? false : text;
+  if (def.type === "peers") return text.split(",").map((p) => p.trim()).filter(Boolean);
+  return text;
+}
+export const settingText = (value: unknown): string => value === null || value === undefined ? "(not set)" : Array.isArray(value) ? value.join(",") || "(none)" : String(value);
+
+/** `ordinary`: a dashboard session from `ahub ui`. `settings`: one from `ahub ui --settings`. `terminal`: `ahub settings`. */
+export type SettingAuthority = "ordinary" | "settings" | "terminal";
+/** Why this authority may not set this value, or undefined. Removing a stored value can raise, so it counts as one. */
+export function settingRefusal(def: SettingDef, value: SettingValue, authority: SettingAuthority): string | undefined {
+  if (def.risk === "safe" || authority !== "ordinary") return undefined;
+  if (value !== null && value === def.floor) return undefined;
+  return `${def.key} can widen what agents do without asking: open a settings session with ahub ui --settings, or use ahub settings in a terminal`;
+}
+
+const CONFIG_LOCAL = "config.local.json";
+type StoredFile = typeof CONFIG_LOCAL | typeof OVERLAY_FILE;
+interface UndoRecord { file: StoredFile; key: string; previous: string | null; written: string | null; at: number }
+const undoFile = (stateDir: string): string => join(stateDir, "settings-undo.json");
+const digest = (text: string | null): string | null => text === null ? null : createHash("sha256").update(text).digest("hex");
+/** The file's text, or null when it is not there. Any other failure is named by its code: its own text holds absolute paths. */
+const readText = (file: string): string | null => {
+  try { return readFileSync(file, "utf8"); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw new Error(`.agenthub/${basename(file)} could not be read (${(error as NodeJS.ErrnoException).code ?? "unknown error"})`);
+  }
+};
+const isObject = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+function parseObject(text: string, name: string): Record<string, unknown> {
+  let doc: unknown;
+  try { doc = JSON.parse(text); } catch { throw new Error(`.agenthub/${name} is not valid JSON; fix it in your editor first`); }
+  if (!isObject(doc)) throw new Error(`.agenthub/${name} must hold a JSON object`);
+  return doc;
+}
+/** Temp file and rename in the same directory: a reader sees the old file or the new one, never half of it. */
+function atomicWrite(file: string, text: string): void {
+  let mode = 0o600;
+  try { mode = statSync(file).mode & 0o777; } catch { /* a new file is the owner's alone */ }
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmp, text, { mode, flag: "wx" });
+    renameSync(tmp, file);
+  } catch (error) {
+    try { unlinkSync(tmp); } catch { /* nothing was written */ }
+    throw error;
+  }
+}
+/** A settings write never changes a file git tracks: the machine-local files are meant to stay out of the repository. */
+function refuseTracked(cwd: string, file: StoredFile): void {
+  const tracked = configTracked(cwd, file);
+  if (tracked) throw new Error(`.agenthub/${file} is committed to git; settings write only machine-local files. Remove it from the repository (git rm --cached) and ignore it`);
+  // Unknown is not untracked where there is a repository to ask; only a project outside git has nothing tracked.
+  if (tracked === undefined && insideRepository(cwd)) throw new Error(`git could not confirm that .agenthub/${file} is untracked; nothing was written`);
+}
+/** Whether this directory or one above it holds a `.git`: a repository git should have been able to answer for. */
+function insideRepository(dir: string): boolean {
+  for (let at = dir; ; at = dirname(at)) {
+    if (existsSync(join(at, ".git"))) return true;
+    if (dirname(at) === at) return false;
+  }
+}
+/** Keeps the one previous version, then replaces (or removes) the file. */
+function store(cwd: string, stateDir: string, file: StoredFile, key: string, previous: string | null, next: string | null): void {
+  refuseTracked(cwd, file);
+  replaceFile(join(cwd, ".agenthub", file), file, next);
+  // The record follows the file: a write that failed leaves the earlier record valid, because the file is as it left it.
+  const record: UndoRecord = { file, key, previous, written: digest(next), at: Date.now() };
+  try {
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    rmSync(undoFile(stateDir), { force: true });
+    writeFileSync(undoFile(stateDir), JSON.stringify(record), { mode: 0o600 });
+  } catch {
+    rmSync(undoFile(stateDir), { force: true }); // this write has no undo, and an older record must not offer one
+  }
+}
+/** Replaces or removes the file. A file-system failure is reported by its code only: its text names absolute paths, and this reaches the dashboard. */
+function replaceFile(path: string, file: StoredFile, text: string | null): void {
+  try {
+    if (text === null) rmSync(path, { force: true });
+    else atomicWrite(path, text);
+  } catch (error) {
+    throw new Error(`.agenthub/${file} could not be written (${(error as NodeJS.ErrnoException).code ?? "unknown error"}); nothing was changed`);
+  }
+}
+
+/** The value a config file holds at a path, or undefined. */
+export function valueAt(doc: unknown, path: readonly string[]): unknown {
+  let node = doc;
+  for (const part of path) {
+    if (!isObject(node) || !Object.hasOwn(node, part)) return undefined;
+    node = node[part];
+  }
+  return node;
+}
+
+/**
+ * Sets (or with null removes) one key of `.agenthub/config.local.json`. `validate` gets a scratch project that holds
+ * the shared config and the candidate, and throws when the hub's own loader would refuse it: nothing is written then.
+ */
+export function writeConfigSetting(cwd: string, stateDir: string, def: SettingDef, value: SettingValue, validate: (scratch: string) => unknown): boolean {
+  const file = join(cwd, ".agenthub", CONFIG_LOCAL);
+  const before = readText(file);
+  const doc = before === null ? {} : parseObject(before, CONFIG_LOCAL);
+  // Nothing to change: no file is created or rewritten, and the undo record keeps the last real write.
+  const held = valueAt(doc, def.path);
+  if (value === null ? held === undefined : same(held, value)) return false;
+  // The loader gives a project that has any config file its project defaults (snapshots, limits, the budget relay,
+  // the approval notice). A settings write must not be what silently makes the first one.
+  if (before === null && !existsSync(join(cwd, ".agenthub", "config.json"))) throw new Error("this project has no .agenthub/config.json: run ahub init first. A first config file also turns on the project defaults (snapshots, limits, the budget relay), which a settings write does not do for you");
+  let node = doc;
+  const trail: [Record<string, unknown>, string][] = [];
+  for (const part of def.path.slice(0, -1)) {
+    if (node[part] === undefined) {
+      if (value === null) { node = {}; break; } // nothing to remove below a block that is not there
+      node[part] = {};
+    }
+    const next = node[part];
+    if (!isObject(next)) throw new Error(`.agenthub/${CONFIG_LOCAL}: ${part} is not an object; fix it in your editor first`);
+    trail.push([node, part]);
+    node = next;
+  }
+  const leaf = def.path.at(-1)!;
+  if (value === null) {
+    delete node[leaf];
+    // A block the removal emptied goes with it, so setting a value and removing it again leaves the file as it was.
+    for (const [parent, part] of trail.reverse()) {
+      if (Object.keys(parent[part] as object).length) break;
+      delete parent[part];
+    }
+  } else node[leaf] = value;
+  const text = `${JSON.stringify(doc, null, 2)}\n`;
+  checkConfigText(cwd, text, validate);
+  store(cwd, stateDir, CONFIG_LOCAL, def.key, before, text);
+  return true;
+}
+/** Runs `validate` on a scratch project holding the shared config and this candidate for the machine-local one. */
+function checkConfigText(cwd: string, text: string | null, validate: (scratch: string) => unknown): void {
+  const scratch = mkdtempSync(join(tmpdir(), "ahub-settings-"));
+  try {
+    mkdirSync(join(scratch, ".agenthub"));
+    if (existsSync(join(cwd, ".agenthub", "config.json"))) copyFileSync(join(cwd, ".agenthub", "config.json"), join(scratch, ".agenthub", "config.json"));
+    if (text !== null) writeFileSync(join(scratch, ".agenthub", CONFIG_LOCAL), text);
+    validate(scratch);
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Sets (or with null removes) one key of `.agenthub/routing.local.toml`; the real parser reads the result first, and
+ * `check` may refuse the policy it yields. Undefined when the overlay already holds that value: nothing is written.
+ */
+export function writeRoutingSetting(cwd: string, stateDir: string, def: SettingDef, value: SettingValue, check?: (routing: Routing) => void): Routing | undefined {
+  const file = join(cwd, ".agenthub", OVERLAY_FILE);
+  const before = readText(file);
+  const current = before === null ? {} : parseOverlay(before);
+  const held = def.path[0] === "stay_switch" ? current.stay_switch : (current.classes?.[def.path[1] as TaskClass] as Record<string, unknown> | undefined)?.[def.path[2]!];
+  if (value === null ? held === undefined : same(held, value)) return undefined;
+  const overlay = routingCandidate(current, def, value);
+  const routing = parseRouting(routingText(cwd), overlay);
+  check?.(routing);
+  const empty = !overlay.stay_switch && !Object.keys(overlay.classes ?? {}).length;
+  store(cwd, stateDir, OVERLAY_FILE, def.key, before, empty ? null : overlayToml(overlay));
+  return routing;
+}
+/** An overlay with one key set or removed: the candidate a write stores and a preview only reads. */
+export function routingCandidate(current: RoutingOverlay, def: SettingDef, value: SettingValue): RoutingOverlay {
+  const overlay: RoutingOverlay = { ...(current.stay_switch ? { stay_switch: current.stay_switch } : {}), classes: Object.fromEntries(Object.entries(current.classes ?? {}).map(([name, entry]) => [name, { ...entry }])) };
+  if (def.path[0] === "stay_switch") {
+    if (value === null) delete overlay.stay_switch;
+    else overlay.stay_switch = value as RoutingOverlay["stay_switch"];
+    return overlay;
+  }
+  const [, name, field] = def.path as [string, TaskClass, "peers" | "escalate_to" | "route" | "pi_backend"];
+  const entry: Record<string, unknown> = { ...overlay.classes![name] };
+  if (value === null) delete entry[field];
+  else entry[field] = value;
+  if (Object.keys(entry).length) overlay.classes![name] = entry;
+  else delete overlay.classes![name];
+  return overlay;
+}
+/** The overlay on disk, or an empty one. */
+export function readOverlay(cwd: string): RoutingOverlay {
+  const text = readText(join(cwd, ".agenthub", OVERLAY_FILE));
+  return text === null ? {} : parseOverlay(text);
+}
+
+/**
+ * Puts back the one previous version of the file the last settings write changed. Refused when the file changed since
+ * that write (a hand edit would be lost), when the loaders no longer accept that version, or when there is nothing to undo.
+ */
+export function undoSetting(cwd: string, stateDir: string, validate: (scratch: string) => unknown, checkRouting?: (routing: Routing) => void): { key: string; file: StoredFile } {
+  const raw = readText(undoFile(stateDir));
+  if (raw === null) throw new Error("nothing to undo");
+  let record: UndoRecord;
+  try { record = JSON.parse(raw) as UndoRecord; } catch { throw new Error("nothing to undo"); }
+  if (record.file !== CONFIG_LOCAL && record.file !== OVERLAY_FILE) throw new Error("nothing to undo");
+  const path = join(cwd, ".agenthub", record.file);
+  if (digest(readText(path)) !== record.written) throw new Error(`.agenthub/${record.file} changed since the last settings write; nothing was undone`);
+  if (record.previous !== null && typeof record.previous !== "string") throw new Error("nothing to undo");
+  refuseTracked(cwd, record.file);
+  if (record.file === OVERLAY_FILE) {
+    // The parser always reads what is put back; the caller's check is on top of it.
+    const restored = parseRouting(routingText(cwd), record.previous === null ? undefined : parseOverlay(record.previous));
+    checkRouting?.(restored);
+  }
+  else checkConfigText(cwd, record.previous, validate);
+  replaceFile(path, record.file, record.previous);
+  rmSync(undoFile(stateDir), { force: true });
+  return { key: String(record.key), file: record.file };
+}
+/** Whether the machine-local config file holds a value for this setting now. */
+export function storedLocally(cwd: string, def: SettingDef): boolean {
+  try { return valueAt(JSON.parse(readFileSync(join(cwd, ".agenthub", CONFIG_LOCAL), "utf8")), def.path) !== undefined; } catch { return false; }
+}
+/**
+ * For a config setting: the value the config files would hold for it after the pending undo (the previous version of
+ * the machine-local file, else the shared file), or, with `inherit`, after the machine-local value is removed (the
+ * shared file's). Undefined when neither sets it or nothing reads.
+ */
+export function restoredValue(cwd: string, stateDir: string, def: SettingDef, inherit = false): unknown {
+  const parse = (text: string | null): unknown => { try { return text === null ? {} : JSON.parse(text); } catch { return {}; } };
+  let local: unknown = {};
+  if (!inherit) {
+    try { const record = JSON.parse(readFileSync(undoFile(stateDir), "utf8")) as UndoRecord; if (record.file !== CONFIG_LOCAL) return undefined; local = parse(record.previous); } catch { return undefined; }
+  }
+  return valueAt(local, def.path) ?? valueAt(parse(readText(join(cwd, ".agenthub", "config.json"))), def.path);
+}
+/** The key the next undo would put back, if any. */
+export function pendingUndo(stateDir: string): string | undefined {
+  try { const record = JSON.parse(readFileSync(undoFile(stateDir), "utf8")) as UndoRecord; return typeof record.key === "string" ? record.key : undefined; } catch { return undefined; }
+}
+
+/** The loader's line saying it ignored this setting's field in the machine-local file, if it did (config trust, #17). */
+export function ignoredLine(ignored: readonly string[] | undefined, def: SettingDef): string | undefined {
+  return ignored?.find((line) => {
+    const at = line.indexOf(` in .agenthub/${CONFIG_LOCAL} ignored:`);
+    return at > 0 && line.slice(0, at).split(", ").some((field) => field === def.path[0] || field === def.path.slice(0, 2).join("."));
+  });
+}
+export interface SettingRow {
+  key: string; group: SettingDef["group"]; label: string; type: SettingDef["type"]; values?: readonly string[];
+  /** The file a write goes to, or "this hub run". */
+  file: string;
+  applies: SettingDef["applies"]; risk: SettingDef["risk"]; floor?: string | boolean;
+  /** What is in force now; null when nothing sets it. */
+  value: SettingValue;
+  /** Which file the value in force comes from. */
+  source: string;
+  /** The stored value the next hub start reads, when it differs from the one in force. */
+  pending?: SettingValue;
+  /** Why the row cannot be changed now. */
+  note?: string;
+  /** For a permission row: the bounds the peer's tools run in, whatever the mode. */
+  hint?: string;
+}
+const same = (a: unknown, b: unknown): boolean => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+
+/**
+ * One row per setting, for the dashboard and `ahub settings list`. `running` is the configuration the hub started
+ * with, `next` what its loader reads from the files now (undefined when they do not load), `mode` a peer's mode now.
+ */
+export function settingRows(input: {
+  cwd: string; routing: Routing;
+  running: (path: readonly string[]) => unknown;
+  next: ((path: readonly string[]) => unknown) | undefined;
+  mode: (peer: string) => { value?: string; note?: string };
+  /** Why the overlay does not load, when it does not: the rows then show the last policy that did. */
+  routingProblem?: string;
+  /** The loader's own lines about machine-local fields it ignored (`HubConfig.ignored`). */
+  ignored?: string[];
+}): SettingRow[] {
+  const raw = (name: string): unknown => { try { return JSON.parse(readFileSync(join(input.cwd, ".agenthub", name), "utf8")); } catch { return undefined; } };
+  const local = raw(CONFIG_LOCAL), shared = raw("config.json");
+  const projectRouting = existsSync(join(input.cwd, ".agenthub", "routing.toml"));
+  const routes = [...Object.keys(input.routing.routes), ...Object.keys(input.routing.hub_routes ?? {})];
+  const scalar = (value: unknown): SettingValue => typeof value === "string" || typeof value === "boolean" ? value : Array.isArray(value) ? value.map(String) : null;
+  return SETTINGS.map((def): SettingRow => {
+    const base = { key: def.key, group: def.group, label: def.label, type: def.type, applies: def.applies, risk: def.risk, ...(def.floor === undefined ? {} : { floor: def.floor }),
+      ...(def.group === "Permissions" ? { hint: permissionBoundary(def.path.at(-1)!) } : {}) };
+    if (def.store === "runtime") {
+      const mode = input.mode(def.path[0]!);
+      return { ...base, values: def.values!, file: "this hub run", value: mode.value ?? null, source: "this hub run", ...(mode.note ? { note: mode.note } : {}) };
+    }
+    if (def.store === "routing") {
+      const value = scalar(def.path[0] === "stay_switch" ? input.routing.stay_switch : (input.routing.classes[def.path[1] as TaskClass] as Record<string, unknown> | undefined)?.[def.path[2]!]);
+      return { ...base, ...(def.type === "enum" ? { values: def.values ?? routes } : {}), file: OVERLAY_FILE, value, source: input.routing.sources?.[def.key.slice("routing.".length)] ?? (value === null ? "default" : projectRouting ? "routing.toml" : "default"),
+        ...(input.routingProblem ? { note: `the routing files do not load, so the last policy that did stays in force: ${input.routingProblem}` } : {}) };
+    }
+    const value = scalar(input.running(def.path));
+    const stored = input.next ? scalar(input.next(def.path)) : value;
+    const source = valueAt(local, def.path) !== undefined ? CONFIG_LOCAL : valueAt(shared, def.path) !== undefined ? "config.json" : "default";
+    const dropped = ignoredLine(input.ignored, def);
+    return { ...base, ...(def.values ? { values: def.values } : {}), file: CONFIG_LOCAL, value, source, ...(same(value, stored) ? {} : { pending: stored }),
+      ...(!input.next ? { note: "the config files do not load; fix them in your editor" } : dropped ? { note: `the hub does not read this value: ${dropped}` } : {}) };
+  });
+}

package/src/hub/snapshots.ts

@@ -1,10 +1,11 @@
 import { Database } from "bun:sqlite";
-import { spawnSync } from "node:child_process";
 import { copyFileSync, existsSync, mkdtempSync, rmSync, statSync, utimesSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { childEnv } from "./child-process.ts";
 import type { Touch } from "./conflicts.ts";
+import { hubGitSync } from "./git.ts";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
 
 /**
  * Per-turn workspace snapshots (issue #33): git tree objects written through a copy of the index, so the user's index
@@ -15,7 +16,7 @@ import type { Touch } from "./conflicts.ts";
  * of an older turn says so. Refs under refs/agenthub/ would keep them, at the cost of showing up in the user's repo.
  */
 const git = (top: string, args: string[], env: Record<string, string> = {}) =>
-  spawnSync("git", ["-C", top, ...args], {
+  hubGitSync(["-C", top, ...args], {
     encoding: "utf8",
     env: { ...childEnv(process.env), ...env },
     // These run inside the bus's state change: a hung git (a huge new directory, a stuck filter) must not freeze the hub.
@@ -144,6 +145,7 @@ export class Turns {
   private readonly db: Database;
   constructor(path: string, readonly?: boolean) {
     this.db = new Database(path, readonly ? { readonly: true } : { create: true });
+    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
     if (readonly) return;
     this.db.run("PRAGMA journal_mode = WAL");
     this.db.run(`CREATE TABLE IF NOT EXISTS turns (id TEXT PRIMARY KEY, peer TEXT NOT NULL, started INTEGER NOT NULL, ended INTEGER,