@staix/agent-hub 0.12.22 → 0.12.24

package/src/hub/settings.ts

@@ -0,0 +1,411 @@
+import { SUPPORTED_PEERS } from "./peer-catalog.ts";
+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 = SUPPORTED_PEERS;
+/** `null` removes the machine-local value, so the shared file's or the default applies again. */
+export type SettingValue = string | boolean | number | string[] | null;
+export interface SettingDef {
+  key: string;
+  group: "Permissions" | "Start" | "Routing" | "Switches" | "Roster" | "Roles";
+  label: string;
+  type: "enum" | "boolean" | "peers" | "roles" | "integer";
+  min?: number; max?: number;
+  /** 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 | number;
+  /** 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: `tasks.wip_limits.${peer}`, group: "Routing", label: `${peer}: planner WIP limit`, type: "integer", min: 0, max: 32, store: "config", applies: "hub start", risk: "raises", floor: 0, path: ["tasks", "wip_limits", peer] })),
+  ...SETTING_PEERS.map((peer): SettingDef => ({ key: `catalog_roles.${peer}`, group: "Roles", label: `${peer}: catalog guidance`, type: "roles", store: "config", applies: "peer start", risk: "safe", path: ["catalog_roles", peer] })),
+  { key: "scoped_grants.protect_instructions", group: "Permissions", label: "Ask before writing instruction files", type: "boolean", store: "config", applies: "live", risk: "raises", floor: true, path: ["protect_instruction_files"] },
+  ...SETTING_PEERS.map((peer): SettingDef => ({ key: `roster.${peer}`, group: "Roster", label: `${peer}: participates`, type: "boolean", store: "config", applies: "live", risk: "raises", floor: false, path: ["roster", peer] })),
+  ...SETTING_PEERS.filter(peer => peer !== "jcode").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.filter(peer => peer !== "jcode").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", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "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 === "integer") {
+    if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw < (def.min ?? 0) || raw > (def.max ?? Number.MAX_SAFE_INTEGER)) throw new Error(`${def.key} takes an integer from ${def.min ?? 0} to ${def.max ?? Number.MAX_SAFE_INTEGER}`);
+    return raw;
+  }
+  if (def.type === "boolean") {
+    if (typeof raw !== "boolean") throw new Error(`${def.key} takes true or false`);
+    return raw;
+  }
+  if (def.type === "roles") {
+    const allowed = def.values ?? routes;
+    if (!Array.isArray(raw) || raw.length > 2 || new Set(raw).size !== raw.length || raw.some(id => typeof id !== "string" || !allowed.includes(id))) throw new Error(`${def.key} takes at most two distinct compatible catalog ids; allowed: ${allowed.join(", ") || "(none)"}`);
+    return [...raw] as string[];
+  }
+  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 === "integer") return /^(0|[1-9]\d*)$/.test(text) ? Number(text) : text;
+  if (def.type === "boolean") return text === "true" ? true : text === "false" ? false : text;
+  if (def.type === "peers" || def.type === "roles") 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 | string, value: SettingValue, authority: SettingAuthority): string | undefined {
+  if (typeof def === "string") return def || "invalid setting definition";
+  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[]; min?: number; max?: number;
+  /** The file a write goes to, or "this hub run". */
+  file: string;
+  applies: SettingDef["applies"]; risk: SettingDef["risk"]; floor?: string | boolean | number;
+  /** 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[];
+  roles?: (peer: string) => { value: SettingValue; pending?: SettingValue; values: string[]; note?: 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" || typeof value === "number" ? 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, ...(def.type === "integer" ? { min: def.min, max: def.max } : {}), applies: def.applies, risk: def.risk, ...(def.floor === undefined ? {} : { floor: def.floor }),
+      ...(def.key === "scoped_grants.protect_instructions" ? { hint: "AGENTS.md, CLAUDE.md and QWEN.md remain grantable by default; enabling this asks before scoped writes and edits" } : 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}` } : {}) };
+    }
+    if (def.type === "roles" && input.roles) return { ...base, ...input.roles(def.path[1]!), file: CONFIG_LOCAL, source: valueAt(local, def.path) !== undefined ? CONFIG_LOCAL : valueAt(shared, def.path) !== undefined ? "config.json" : "profile/default", hint: "Guidance only; grants no tool or permission. At most two roles, applied at the next peer start." };
+    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/shipped-roles.ts

@@ -0,0 +1,25 @@
+import role0 from "../../templates/roles/dev/software-architect.md" with { type: "text" };
+import role1 from "../../templates/roles/dev/backend-engineer.md" with { type: "text" };
+import role2 from "../../templates/roles/dev/frontend-engineer.md" with { type: "text" };
+import role3 from "../../templates/roles/dev/test-engineer.md" with { type: "text" };
+import role4 from "../../templates/roles/dev/code-reviewer.md" with { type: "text" };
+import role5 from "../../templates/roles/dev/security-reviewer.md" with { type: "text" };
+import role6 from "../../templates/roles/research/research-lead.md" with { type: "text" };
+import role7 from "../../templates/roles/research/researcher.md" with { type: "text" };
+import role8 from "../../templates/roles/research/analyst.md" with { type: "text" };
+import role9 from "../../templates/roles/research/statistician.md" with { type: "text" };
+import role10 from "../../templates/roles/research/fact-checker.md" with { type: "text" };
+
+export const SHIPPED_ROLES: Readonly<Record<string, string>> = {
+  "software-architect": role0,
+  "backend-engineer": role1,
+  "frontend-engineer": role2,
+  "test-engineer": role3,
+  "code-reviewer": role4,
+  "security-reviewer": role5,
+  "research-lead": role6,
+  "researcher": role7,
+  "analyst": role8,
+  "statistician": role9,
+  "fact-checker": role10,
+};

package/src/hub/snapshots.ts

@@ -1,10 +1,12 @@
 import { Database } from "bun:sqlite";
-import { spawnSync } from "node:child_process";
-import { copyFileSync, existsSync, mkdtempSync, rmSync, statSync, utimesSync } from "node:fs";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync } 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 { realPath } from "./project.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
@@ -14,10 +16,10 @@ import type { Touch } from "./conflicts.ts";
  * ponytail: the trees are unreferenced, so `git gc` may prune them after gc.pruneExpire (two weeks by default); undo
  * 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], {
+const git = (top: string | Repo, args: string[], env: Record<string, string> = {}) =>
+  hubGitSync(repoGitArgs(top, args), {
     encoding: "utf8",
-    env: { ...childEnv(process.env), ...env },
+    env: { ...repoGitEnv(top), ...env },
     // These run inside the bus's state change: a hung git (a huge new directory, a stuck filter) must not freeze the hub.
     timeout: SNAPSHOT_TIMEOUT_MS,
   });
@@ -28,14 +30,73 @@ export interface Repo {
   top: string;
   dir: string;
   prefix: string;
+  shadow?: true;
+}
+
+/** Refuse links throughout metadata, including loose-object fan-outs and packed-object files. */
+function shadowStorageSafe(dir: string): boolean {
+  let entries = 0;
+  const visit = (path: string, depth: number): boolean => {
+    if (++entries > 20000 || depth > 32) return false;
+    const st = lstatSync(path);
+    if (st.isSymbolicLink()) return false;
+    if (st.isFile()) return st.nlink === 1;
+    if (!st.isDirectory()) return false;
+    return readdirSync(path).every(name => visit(join(path, name), depth + 1));
+  };
+  try {
+    if (lstatSync(join(dir, "commondir"), { throwIfNoEntry: false }) || lstatSync(join(dir, "objects/info/alternates"), { throwIfNoEntry: false })) return false;
+    return visit(dir, 0);
+  } catch { return false; }
+}
+/** Explicit flags keep the shadow work tree at its verified project root. */
+export function repoGitArgs(repo: string | Repo, args: string[]): string[] {
+  const top = typeof repo === "string" ? repo : repo.top;
+  if (typeof repo !== "string" && repo.shadow) {
+    const parent = lstatSync(join(repo.top, ".agenthub"), { throwIfNoEntry: false });
+    const ignore = parent?.isDirectory() && !parent.isSymbolicLink() ? lstatSync(join(repo.top, ".agenthub/ignore"), { throwIfNoEntry: false }) : undefined;
+    if (!parent?.isDirectory() || parent.isSymbolicLink() || ignore && (!ignore.isFile() || ignore.isSymbolicLink() || ignore.nlink !== 1) || repo.dir !== join(repo.top, ".agenthub/shadow.git") || !shadowStorageSafe(repo.dir)) throw new Error("shadow repository metadata is invalid or linked; operation refused");
+  }
+  return ["-C", top, ...(typeof repo !== "string" && repo.shadow ? ["--git-dir=" + repo.dir, "--work-tree=" + repo.top, "-c", "core.excludesFile=" + join(repo.top, ".agenthub", "ignore")] : []), ...args];
+}
+export function repoGitEnv(repo: string | Repo, env = process.env): NodeJS.ProcessEnv {
+  return { ...childEnv(env), ...(typeof repo !== "string" && repo.shadow ? { GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_SYSTEM: "/dev/null", GIT_ATTR_NOSYSTEM: "1" } : {}) };
 }
 
 /** The repository holding `root`, or undefined when it is not inside a work tree. */
 export function repoOf(root: string): Repo | undefined {
   const r = git(root, ["rev-parse", "--show-toplevel", "--absolute-git-dir", "--show-prefix"]);
-  if (r.status !== 0) return undefined;
-  const [top, dir, prefix = ""] = r.stdout.replace(/\n$/, "").split("\n");
-  return top && dir ? { top, dir, prefix } : undefined;
+  if (r.status === 0) {
+    const [top, dir, prefix = ""] = r.stdout.replace(/\n$/, "").split("\n");
+    if (top && dir) return { top, dir, prefix };
+  }
+  const top = realPath(root), hub = join(top, ".agenthub"), dir = join(hub, "shadow.git");
+  const parent = lstatSync(hub, { throwIfNoEntry: false });
+  if (!parent?.isDirectory() || parent.isSymbolicLink()) return undefined;
+  const own = lstatSync(dir, { throwIfNoEntry: false });
+  if (!own?.isDirectory() || own.isSymbolicLink()) return undefined;
+  for (const name of ["objects", "refs", "hooks", "info"]) { const st = lstatSync(join(dir, name), { throwIfNoEntry: false }); if (!st?.isDirectory() || st.isSymbolicLink()) return undefined; }
+  for (const file of ["config", "HEAD"]) { const st = lstatSync(join(dir, file), { throwIfNoEntry: false }); if (!st?.isFile() || st.isSymbolicLink() || st.nlink !== 1) return undefined; }
+  if (existsSync(join(dir, "commondir")) || existsSync(join(dir, "objects/info/alternates"))) return undefined;
+  const ignore = lstatSync(join(hub, "ignore"), { throwIfNoEntry: false });
+  if (ignore && (!ignore.isFile() || ignore.isSymbolicLink() || ignore.nlink !== 1)) return undefined;
+  if (!shadowStorageSafe(dir)) return undefined;
+  const repo: Repo = { top, dir: realPath(dir), prefix: "", shadow: true };
+  const probe = git(repo, ["rev-parse", "--absolute-git-dir"]);
+  return probe.status === 0 && realPath(probe.stdout.trim()) === repo.dir ? repo : undefined;
+}
+/** Opt-in creation only; a real repository is never replaced or modified. */
+export function initShadow(root: string): boolean {
+  const top = realPath(root), hub = join(top, ".agenthub"), dir = join(hub, "shadow.git"), existing = repoOf(top);
+  if (existing) { if (!existing.shadow) throw new Error("project already has a Git work tree; shadow mode is for non-git folders"); return false; }
+  const parent = lstatSync(hub, { throwIfNoEntry: false });
+  if (parent && (!parent.isDirectory() || parent.isSymbolicLink())) throw new Error(".agenthub must be a project directory, not a link");
+  if (lstatSync(dir, { throwIfNoEntry: false })) throw new Error("existing shadow metadata is invalid; nothing was replaced");
+  mkdirSync(hub, { recursive: true });
+  const result = hubGitSync(["init", "--bare", "--quiet", dir], { cwd: top, encoding: "utf8", timeout: SNAPSHOT_TIMEOUT_MS, env: { ...childEnv(process.env), GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_SYSTEM: "/dev/null" } });
+  if (result.status !== 0) throw new Error("could not initialize shadow repository");
+  writeFileSync(join(dir, "info/exclude"), ".agenthub/shadow.git/\n.agenthub/state/\n.agenthub/archive/\n.agenthub/config.local.json\n.agenthub/routing.local.toml\n", { mode: 0o600 });
+  return true;
 }
 
 /**
@@ -61,12 +122,12 @@ export function snapshot(repo: Repo): string | undefined {
       utimesSync(env.GIT_INDEX_FILE, atime, mtime);
     }
     // `ahub reset --all` archives hub.db (task text, PII included) under .agenthub/archive: never copy it either.
-    if (git(repo.top, ["add", "-A", "--", scope(repo), ":(exclude,glob)**/.agenthub/state/**", ":(exclude,glob)**/.agenthub/archive/**"], env).status !== 0) return undefined;
+    if (git(repo, ["add", "-A", "--", scope(repo), ":(exclude,glob)**/.agenthub/state/**", ":(exclude,glob)**/.agenthub/archive/**", ...(repo.shadow ? [":(exclude,glob)**/.agenthub/shadow.git/**"] : [])], env).status !== 0) return undefined;
     // The copy starts from the user's index: hub state somebody tracked or staged is still in it, and the exclude above
     // only keeps `add` from touching it. Take it out explicitly; -f because staged state the hub has rewritten since
     // matches neither HEAD nor the file, which `rm --cached` otherwise refuses. Only the copy changes.
-    if (git(repo.top, ["rm", "-r", "-f", "--cached", "--quiet", "--ignore-unmatch", "--", ":(glob)**/.agenthub/state/**", ":(glob)**/.agenthub/archive/**"], env).status !== 0) return undefined;
-    const r = git(repo.top, ["write-tree"], env);
+    if (git(repo, ["rm", "-r", "-f", "--cached", "--quiet", "--ignore-unmatch", "--", ":(glob)**/.agenthub/state/**", ":(glob)**/.agenthub/archive/**", ...(repo.shadow ? [":(glob)**/.agenthub/shadow.git/**"] : [])], env).status !== 0) return undefined;
+    const r = git(repo, ["write-tree"], env);
     return r.status === 0 ? r.stdout.trim() : undefined;
   } finally {
     rmSync(tmp, { recursive: true, force: true });
@@ -75,14 +136,14 @@ export function snapshot(repo: Repo): string | undefined {
 
 /** Project paths (relative to the top level) that differ between two trees. */
 export function changedPaths(repo: Repo, from: string, to: string): string[] {
-  const r = git(repo.top, ["diff-tree", "-r", "--no-renames", "--name-only", "-z", from, to, "--", scope(repo)]);
+  const r = git(repo, ["diff-tree", "-r", "--no-renames", "--name-only", "-z", from, to, "--", scope(repo)]);
   return r.status === 0 ? r.stdout.split("\0").filter(Boolean) : [];
 }
 
-const inTree = (top: string, tree: string, path: string) => git(top, ["rev-parse", "--verify", "--quiet", `${tree}:${path}`]).status === 0;
+const inTree = (top: string | Repo, tree: string, path: string) => git(top, ["rev-parse", "--verify", "--quiet", `${tree}:${path}`]).status === 0;
 
 /** Whether a snapshot's tree is still in the object store (`git gc` prunes unreferenced ones eventually). */
-export const hasTree = (top: string, tree: string): boolean => git(top, ["cat-file", "-e", `${tree}^{tree}`]).status === 0;
+export const hasTree = (top: string | Repo, tree: string): boolean => git(top, ["cat-file", "-e", `${tree}^{tree}`]).status === 0;
 
 export interface UndoPlan {
   restore: string[];
@@ -121,10 +182,10 @@ export function planUndo(repo: Repo, turn: { start_tree: string; end_tree: strin
 export function restore(repo: Repo, startTree: string, paths: string[]): void {
   // Removals first: after a case-only rename on a case-insensitive disk, `Foo.ts` and `foo.ts` are one file, and
   // removing the created spelling after restoring the old one would delete it.
-  const back = paths.filter((p) => inTree(repo.top, startTree, p));
+  const back = paths.filter((p) => inTree(repo, startTree, p));
   for (const path of paths.filter((p) => !back.includes(p))) rmSync(join(repo.top, path), { force: true });
   for (const path of back) {
-    if (git(repo.top, ["restore", `--source=${startTree}`, "--worktree", "--", literal(path)]).status !== 0) throw new Error(`could not restore ${path}`);
+    if (git(repo, ["restore", `--source=${startTree}`, "--worktree", "--", literal(path)]).status !== 0) throw new Error(`could not restore ${path}`);
   }
 }
 
@@ -144,6 +205,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,
@@ -154,6 +216,20 @@ export class Turns {
     // ponytail: rows of finished tasks stay (a few per file per task); prune by task state if hub.db ever grows.
     this.db.run("CREATE TABLE IF NOT EXISTS touches (task INTEGER NOT NULL, peer TEXT NOT NULL, path TEXT NOT NULL, at INTEGER NOT NULL, PRIMARY KEY (task, peer, path))");
     this.db.run("CREATE INDEX IF NOT EXISTS touches_path ON touches (path)"); // the PreToolUse hook looks up one path
+    this.db.run("CREATE TABLE IF NOT EXISTS task_snapshots (task INTEGER NOT NULL, proposed_at INTEGER NOT NULL, start_tree TEXT, PRIMARY KEY (task, proposed_at))");
+  }
+  /** A proposal's original project snapshot; task ids may be reused after reset. Never repair a missing baseline later. */
+  rememberTaskStart(task: number, proposedAt: number, tree: string | undefined): void {
+    this.db.query("INSERT OR IGNORE INTO task_snapshots (task, proposed_at, start_tree) VALUES (?, ?, ?)").run(task, proposedAt, tree ?? null);
+  }
+  taskStart(task: number, proposedAt: number): string | undefined {
+    try {
+      const row = this.db.query("SELECT start_tree FROM task_snapshots WHERE task = ? AND proposed_at = ?").get(task, proposedAt) as { start_tree: string | null } | null;
+      return row?.start_tree ?? undefined;
+    } catch (error) {
+      if (/no such table/.test((error as Error).message)) return undefined;
+      throw error;
+    }
   }
   begin(id: string, peer: string, startTree: string | undefined): void {
     this.db.query("INSERT OR REPLACE INTO turns (id, peer, started, start_tree) VALUES (?, ?, ?, ?)").run(id, peer, Date.now(), startTree ?? null);