@staix/agent-hub 0.12.30 → 0.12.32

package/src/hub/recovery-continuity.ts

@@ -0,0 +1,152 @@
+import { Database } from "bun:sqlite";
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, closeSync, constants, fstatSync, lstatSync, openSync, readSync, renameSync, unlinkSync } from "node:fs";
+import { isAbsolute, join, normalize } from "node:path";
+import { realPath } from "./project.ts";
+import { atomicPrivateJSON, operationIdPattern } from "./recovery-store.ts";
+
+export const RECOVERY_CONTINUITY_BUSY_TIMEOUT_MS = 3000;
+const MAX_BOOKMARK_BYTES = 16 * 1024;
+const BOOKMARK = "recovery-continuity.json", LOCK = "recovery-continuity-lock.db";
+
+export interface RecoveryContinuityBookmark {
+  schema: 1;
+  operationId: string;
+  projectId: string;
+  projectRoot: string;
+  at: number;
+  pi: { sessionId: string; sessionFile?: string; backend?: "auto" | "dgx" | "mlx"; model?: string };
+}
+export interface RecoveryContinuityExpected { projectId: string; projectRoot: string; operationId?: string }
+export type ContinuityRetirementReason = "authenticated_session_changed" | "resume_unavailable" | "recovery_released";
+export type RecoveryContinuityReading =
+  | { state: "absent" }
+  | { state: "invalid"; reason: "unavailable" | "invalid_shape" | "invalid_path" | "identity_mismatch" | "oversized" }
+  | { state: "ready"; bookmark: RecoveryContinuityBookmark; digest: string };
+
+const unavailable = (): never => { throw new Error("recovery continuity metadata unavailable or invalid"); };
+const record = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const keys = (value: Record<string, unknown>, allowed: readonly string[]): boolean => Object.keys(value).every(key => allowed.includes(key));
+const text = (value: unknown, max: number): value is string => typeof value === "string" && value.length > 0 && value.length <= max && !/[\x00-\x1f\x7f]/.test(value);
+const id = (value: unknown): value is string => text(value, 256) && /^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(value);
+const absolute = (value: unknown): value is string => text(value, 4096) && isAbsolute(value) && normalize(value) === value;
+function canonicalRoot(value: unknown): string {
+  if (!absolute(value)) return unavailable();
+  const root = realPath(value);
+  if (!lstatSync(root).isDirectory()) return unavailable();
+  return root;
+}
+function checked(value: unknown): RecoveryContinuityBookmark {
+  if (!record(value) || !keys(value, ["schema", "operationId", "projectId", "projectRoot", "at", "pi"]) || value.schema !== 1 || typeof value.operationId !== "string" || !operationIdPattern.test(value.operationId) || !id(value.projectId) || !absolute(value.projectRoot) || !Number.isSafeInteger(value.at) || (value.at as number) < 0) return unavailable();
+  const pi = value.pi;
+  if (!record(pi) || !keys(pi, ["sessionId", "sessionFile", "backend", "model"]) || !id(pi.sessionId) || pi.sessionFile !== undefined && !absolute(pi.sessionFile) || pi.backend !== undefined && !["auto", "dgx", "mlx"].includes(String(pi.backend)) || pi.model !== undefined && !text(pi.model, 4096)) return unavailable();
+  const projectRoot = canonicalRoot(value.projectRoot);
+  return { schema: 1, operationId: value.operationId, projectId: value.projectId, projectRoot, at: value.at as number,
+    pi: { sessionId: pi.sessionId, ...(pi.sessionFile === undefined ? {} : { sessionFile: pi.sessionFile as string }), ...(pi.backend === undefined ? {} : { backend: pi.backend as "auto" | "dgx" | "mlx" }), ...(pi.model === undefined ? {} : { model: pi.model as string }) } };
+}
+function stateDirectory(stateDir: string): void {
+  if (!absolute(stateDir)) return unavailable();
+  const stat = lstatSync(stateDir);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) return unavailable();
+}
+function privateFile(path: string, missing = false): void {
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.mode & 0o077) return unavailable();
+  } catch (error) { if (!missing || (error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+}
+const digest = (bytes: Buffer): string => createHash("sha256").update(bytes).digest("hex");
+
+/** Read one bounded project-local file; invalid evidence is deliberately distinct from no bookmark. */
+export function readRecoveryContinuity(stateDir: string, expected: RecoveryContinuityExpected): RecoveryContinuityReading {
+  let fd: number | undefined;
+  let expectedRoot: string;
+  try { expectedRoot = canonicalRoot(expected.projectRoot); }
+  catch { return { state: "invalid", reason: "identity_mismatch" }; }
+  try {
+    stateDirectory(stateDir);
+    const file = join(stateDir, BOOKMARK);
+    privateFile(file);
+    fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.mode & 0o077) return { state: "invalid", reason: "invalid_path" };
+    if (stat.size > MAX_BOOKMARK_BYTES) return { state: "invalid", reason: "oversized" };
+    const buffer = Buffer.alloc(MAX_BOOKMARK_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) { const n = readSync(fd, buffer, length, buffer.length - length, null); if (!n) break; length += n; }
+    if (length > MAX_BOOKMARK_BYTES) return { state: "invalid", reason: "oversized" };
+    const bytes = buffer.subarray(0, length);
+    let bookmark: RecoveryContinuityBookmark;
+    try {
+      const raw: unknown = JSON.parse(bytes.toString("utf8"));
+      bookmark = checked(raw);
+      if (!record(raw) || raw.projectRoot !== bookmark.projectRoot) return { state: "invalid", reason: "invalid_path" };
+    } catch { return { state: "invalid", reason: "invalid_shape" }; }
+    if (!id(expected.projectId) || expected.operationId !== undefined && !operationIdPattern.test(expected.operationId) || bookmark.projectId !== expected.projectId || bookmark.projectRoot !== expectedRoot || expected.operationId !== undefined && bookmark.operationId !== expected.operationId) return { state: "invalid", reason: "identity_mismatch" };
+    return { state: "ready", bookmark, digest: digest(bytes) };
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ENOENT" ? { state: "absent" } : { state: "invalid", reason: "unavailable" };
+  } finally { if (fd !== undefined) closeSync(fd); }
+}
+
+/** A crash releases SQLite's lock; no lockfile ownership or stale-process inference is needed. */
+function withWriter<T>(stateDir: string, action: () => T): T {
+  stateDirectory(stateDir);
+  const file = join(stateDir, LOCK);
+  privateFile(file, true);
+  for (const suffix of ["-journal", "-wal", "-shm"]) privateFile(file + suffix, true);
+  const db = new Database(file, { create: true });
+  db.run(`PRAGMA busy_timeout = ${RECOVERY_CONTINUITY_BUSY_TIMEOUT_MS}`);
+  try {
+    chmodSync(file, 0o600);
+    db.run("BEGIN IMMEDIATE");
+    try { return action(); } finally { db.run("ROLLBACK"); }
+  } finally { db.close(); }
+}
+
+/** Called only after the coordinator confirmed its target stopped and archived that operation's snapshot. */
+export function writeRecoveryContinuity(stateDir: string, value: RecoveryContinuityBookmark): { digest: string } {
+  const bookmark = checked(value), bytes = Buffer.from(JSON.stringify(bookmark, null, 2) + "\n");
+  if (bytes.length > MAX_BOOKMARK_BYTES) return unavailable();
+  return withWriter(stateDir, () => {
+    privateFile(join(stateDir, BOOKMARK), true);
+    atomicPrivateJSON(join(stateDir, BOOKMARK), bookmark);
+    return { digest: digest(bytes) };
+  });
+}
+
+/** Consume only the exact bookmark whose recorded session has authenticated; stale receipts retain newer data. */
+export function consumeRecoveryContinuity(stateDir: string, expected: RecoveryContinuityExpected & { operationId: string; digest: string }): boolean {
+  if (!operationIdPattern.test(expected.operationId) || !/^[a-f0-9]{64}$/.test(expected.digest)) return false;
+  return withWriter(stateDir, () => {
+    const current = readRecoveryContinuity(stateDir, { projectId: expected.projectId, projectRoot: expected.projectRoot });
+    if (current.state === "absent") return false;
+    if (current.state === "invalid") return unavailable();
+    if (current.bookmark.operationId !== expected.operationId || current.digest !== expected.digest) return false;
+    unlinkSync(join(stateDir, BOOKMARK));
+    return true;
+  });
+}
+
+/** Preserve superseded evidence privately; only a matching project/operation/digest may retire the active file. */
+export function retireRecoveryContinuity(
+  stateDir: string,
+  expected: RecoveryContinuityExpected & { operationId: string; digest: string },
+  reason: ContinuityRetirementReason,
+): { retired: boolean; archive?: string } {
+  if (!["authenticated_session_changed", "resume_unavailable", "recovery_released"].includes(reason)) return unavailable();
+  if (!operationIdPattern.test(expected.operationId) || !/^[a-f0-9]{64}$/.test(expected.digest)) return { retired: false };
+  return withWriter(stateDir, () => {
+    const current = readRecoveryContinuity(stateDir, { projectId: expected.projectId, projectRoot: expected.projectRoot });
+    if (current.state === "absent") return { retired: false };
+    if (current.state === "invalid") return unavailable();
+    if (current.bookmark.operationId !== expected.operationId || current.digest !== expected.digest) return { retired: false };
+    // A unique destination preserves an earlier retirement even when the same bookmark was explicitly restored.
+    const archive = join(stateDir, `recovery-continuity.retired.${reason}.${current.digest}.${randomUUID()}.json`);
+    try { lstatSync(archive); return unavailable(); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    renameSync(join(stateDir, BOOKMARK), archive);
+    chmodSync(archive, 0o600);
+    return { retired: true, archive };
+  });
+}

package/src/hub/recovery-store.ts

@@ -69,15 +69,21 @@ export function assertLifecycleAvailable(): void {
  * lacks dispose, refuses abort and resume on a lapsed hold and shows no next actions: then the running release is
  * named, which does all of that in-process (its resume still runs the operation's own runner).
  */
-export function recoveryCommand(op: { id: string; sourceRoot?: string }, action: "status" | "resume" | "abort" | "dispose", flags = ""): string {
-  const entry = !op.sourceRoot ? undefined : coordinatorCurrent(op.sourceRoot) ? join(op.sourceRoot, "src/cli/main.js") : join(import.meta.dir, "../cli/main.js");
+export type RecoveryAction = "status" | "resume" | "abort" | "dispose" | "reattach";
+export function supportsAction(sourceRoot: string, action: RecoveryAction): boolean {
+  if (!coordinatorCurrent(sourceRoot)) return false;
+  if (action !== "reattach") return true;
+  try { return readFileSync(join(sourceRoot, "src/cli/upgrade.ts"), "utf8").includes("export async function reattachRecovery"); } catch { return false; }
+}
+export function recoveryCommand(op: { id: string; sourceRoot?: string }, action: RecoveryAction, flags = ""): string {
+  const entry = !op.sourceRoot ? undefined : supportsAction(op.sourceRoot, action) ? join(op.sourceRoot, "src/cli/main.js") : join(import.meta.dir, "../cli/main.js");
   const cli = !entry ? "ahub" : /^[\w./@+-]+$/.test(entry) ? `bun ${entry}` : `bun '${entry.replace(/'/g, `'\\''`)}'`;
   return `${cli} recovery ${action} ${op.id}${flags ? ` ${flags}` : ""}`;
 }
 
 /** #272: the command above as an argv for `bun`, which a screen runs instead of printing; with no coordinator of its own, this release's. */
-export function recoveryArgv(op: { id: string; sourceRoot?: string }, action: "status" | "resume" | "abort" | "dispose", flags: string[] = []): string[] {
-  const entry = op.sourceRoot && coordinatorCurrent(op.sourceRoot) ? join(op.sourceRoot, "src/cli/main.js") : join(import.meta.dir, "../cli/main.js");
+export function recoveryArgv(op: { id: string; sourceRoot?: string }, action: RecoveryAction, flags: string[] = []): string[] {
+  const entry = op.sourceRoot && supportsAction(op.sourceRoot, action) ? join(op.sourceRoot, "src/cli/main.js") : join(import.meta.dir, "../cli/main.js");
   return [entry, "recovery", action, op.id, ...flags];
 }
 

package/src/hub/routing.ts

@@ -1,6 +1,9 @@
 import { readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { CLASSES, type Task, type TaskClass } from "./board.ts";
+import { isGitHubRepository, specRefs } from "./spec-read.ts";
+
+export interface PeerCapabilities { tests: boolean; spec: boolean; testsReason?: string; specReason?: string; }
 import type { PeerId, PeerState } from "./envelope.ts";
 
 import { parseHubRoutes, type HubRoute } from "../models/route/config.ts";
@@ -231,7 +234,10 @@ export function detectSignals(task: Pick<Task, "title" | "detail" | "refs">, rou
 /** A peer's entry in a peer-indexed map: own keys only, so a peer named `constructor` is never an inherited Object member. */
 export const peerEntry = <T>(map: Readonly<Record<string, T>> | undefined, peer: string): T | undefined => (map && Object.hasOwn(map, peer) ? map[peer] : undefined);
 
+export type RoutingRefusalCode = "tests" | "spec" | "roster" | "pull-only" | "not-attached" | "excluded" | "owner-admission" | "offline" | "paused" | "failing" | "pii" | "policy";
+export interface RoutingRefusal { peer: PeerId; role: "owner" | "reviewer"; code: RoutingRefusalCode; reason: string }
 export interface Assignment {
+  refusals?: RoutingRefusal[];
   owner?: PeerId;
   reviewer?: PeerId;
   /** what `local` should ask for on this task: a Switchyard route id and the model to fall back to */
@@ -248,10 +254,12 @@ export interface Assignment {
  * prints its trace. `states`: effective bus states of attached peers (a peer that is not in the map is not attached).
  */
 export function assign(
-  task: Pick<Task, "class" | "signals" | "reserved"> & Partial<Pick<Task, "state">>,
+  task: Pick<Task, "class" | "signals" | "reserved"> & Partial<Pick<Task, "state" | "title" | "detail" | "refs" | "external">>,
   states: Record<PeerId, PeerState>,
   routing: Routing,
   opts: {
+    capabilities?: Record<PeerId, PeerCapabilities>;
+    repository?: string;
     exclude?: PeerId[];
     /** Owner admission limits do not remove otherwise eligible reviewers. */
     excludeOwners?: PeerId[];
@@ -280,6 +288,7 @@ export function assign(
     roles?: Record<string, string[]>;
   } = {},
 ): Assignment {
+  if (task.state === "cancelled" || task.state === "approved") return { trace: [`${task.state}: closed; not routed`] };
   if (task.state === "backlog") return { trace: ["backlog: not routed; pull into To Do first"] };
   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"}`];
@@ -292,29 +301,39 @@ export function assign(
   if (opts.waitsFor?.length) return { trace: [...trace, `blocked: waits for ${opts.waitsFor.map((id) => `#${id}`).join(", ")} (not approved)`, ...(reserved ? [`reserved owner ${reserved}: offered first once it is ready`] : [])] };
   const pii = task.signals.includes("pii_path") || (task.signals.includes("pii") && routing.constraints.pii === "local_only");
 
+  let needsSpec = false;
+  if (!pii) try { needsSpec = specRefs({ title: task.title ?? "", detail: task.detail ?? "", refs: task.refs ?? {}, external: task.external }, opts.repository ?? "", { bareTitle: isGitHubRepository(opts.repository) }).length > 0; }
+  catch { needsSpec = true; } // an invalid/foreign reference never grants a sandboxed peer spec access
+  const needsTests = ["implement", "test", "bulk_edit"].includes(task.class);
+  const refusals = new Map<string, RoutingRefusal>();
   const blocked = (peer: PeerId, role: "owner" | "reviewer"): string | undefined => {
-    if (opts.offRoster?.includes(peer)) return "off roster";
+    const deny = (code: RoutingRefusalCode, reason: string): string => { refusals.set(`${role}:${peer}`, { peer, role, code, reason }); return reason; };
+    if (role === "owner" && opts.capabilities && !pii) {
+      const caps = peerEntry(opts.capabilities, peer);
+      if (needsTests && !caps?.tests) return deny("tests", `missing tests: ${caps?.testsReason ?? "capability unavailable"}`);
+      if (needsSpec && !caps?.spec) return deny("spec", `missing spec: ${caps?.specReason ?? "capability unavailable"}`);
+    }
+    if (opts.offRoster?.includes(peer)) return deny("roster", "off roster");
     const named = role === "owner" ? opts.namedOwner ?? reserved : opts.namedReviewer;
-    if (opts.pullOnly?.includes(peer) && named !== peer) return "pull-only: takes work when named or when it claims it";
-    if (!Object.hasOwn(states, peer)) return "not attached";
-    if (opts.exclude?.includes(peer)) return "excluded (declined or replaced)";
-    if (role === "owner" && opts.excludeOwners?.includes(peer)) return "owner admission: WIP or delivery hold";
-    if (states[peer] === "offline") return "offline";
-    if (states[peer] === "paused" && routing.constraints.budget_paused === "skip_peer") return "paused";
+    if (opts.pullOnly?.includes(peer) && named !== peer) return deny("pull-only", "pull-only: takes work when named or when it claims it");
+    if (!Object.hasOwn(states, peer)) return deny("not-attached", "not attached");
+    if (opts.exclude?.includes(peer)) return deny("excluded", "excluded (declined or replaced)");
+    if (role === "owner" && opts.excludeOwners?.includes(peer)) return deny("owner-admission", "owner admission: WIP or delivery hold");
+    if (states[peer] === "offline") return deny("offline", "offline");
+    if (states[peer] === "paused" && routing.constraints.budget_paused === "skip_peer") return deny("paused", "paused");
     const failing = peerEntry(opts.failing, peer);
-    if (failing) return `failing: ${failing}`;
-    if (pii && peer !== LOCAL) return "pii: on-prem peers only";
-    if (peer === LOCAL && policy?.local_allowed === false) return "local_allowed = false for this class";
-    if (peer === PI && policy?.local_allowed === false) return "local_allowed = false also excludes pi for this class";
+    if (failing) return deny("failing", `failing: ${failing}`);
+    if (pii && peer !== LOCAL) return deny("pii", "pii: on-prem peers only");
+    if (peer === LOCAL && policy?.local_allowed === false) return deny("policy", "local_allowed = false for this class");
+    if (peer === PI && policy?.local_allowed === false) return deny("policy", "local_allowed = false also excludes pi for this class");
     if (peer === PI && task.signals.includes("long_context")) {
       const backend = policy?.pi_backend ?? "dgx";
       const limit = backend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens;
-      if (routing.signals.long_context_tokens > limit) return `pi ${backend} capability limit ${limit} tokens`;
+      if (routing.signals.long_context_tokens > limit) return deny("policy", `pi ${backend} capability limit ${limit} tokens`);
     }
-    if (peer === LOCAL && role === "owner" && task.signals.includes("long_context") && routing.constraints.long_context === "skip_local") return "long_context: skip local";
+    if (peer === LOCAL && role === "owner" && task.signals.includes("long_context") && routing.constraints.long_context === "skip_local") return deny("policy", "long_context: skip local");
     return undefined;
   };
-
   /** Quota that resets soonest gets used first: headroom per hour left in the window, at least 15 min (a task assigned that close to a reset mostly runs after it). */
   const drain = (p: PeerId): number | undefined => {
     const q = peerEntry(opts.quota, p);
@@ -396,7 +415,7 @@ export function assign(
   const piBackend = policy?.pi_backend;
   if (owner === LOCAL) trace.push(`route: ${route ?? "(none)"}, fixed_model ${fixedModel}`);
   if (owner === PI) trace.push(`pi decision: backend ${piBackend ?? "dgx"}${task.signals.includes("long_context") ? `, context limit ${piBackend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens}` : ""}`);
-  return { ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), trace };
+  return { ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), ...(refusals.size ? { refusals: [...refusals.values()] } : {}), trace };
 }
 
 /**

package/src/hub/sdlc.ts

@@ -3,6 +3,7 @@ import { constants, openSync, fstatSync, readSync, closeSync } from "node:fs";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
 import { childEnv, stopOwnedProcess } from "./child-process.ts";
+import { hostExecutable } from "./host-executable.ts";
 
 export const SDLC_STAGES = ["spec", "plan", "implement", "review", "verify", "merge", "release"] as const;
 export type SdlcBaseStage = typeof SDLC_STAGES[number];
@@ -219,7 +220,10 @@ export type SdlcGh = (args: string[], timeoutMs?: number, cwd?: string, maxOutpu
 /** Read-only, fixed argv. Output and time are bounded; diagnostics never expose credentials or remote text. */
 export const sdlcGh: SdlcGh = (args, timeoutMs = 10_000, cwd, maxOutputBytes = 256 * 1024) => new Promise((resolve) => {
   const outputLimit = Number.isSafeInteger(maxOutputBytes) ? Math.min(2 * 1024 * 1024, Math.max(1, maxOutputBytes)) : 256 * 1024;
-  const child = spawn("gh", args, { ...(cwd ? { cwd } : {}), env: childEnv(), detached: true, stdio: ["ignore", "pipe", "ignore"] });
+  let child: ReturnType<typeof spawn>;
+  try {
+    child = spawn(hostExecutable("gh", cwd ?? process.cwd()), args, { ...(cwd ? { cwd } : {}), env: childEnv(), detached: true, stdio: ["ignore", "pipe", "ignore"] });
+  } catch { resolve({ code: 1, stdout: "" }); return; }
   let stdout = "", failed = false;
   const stop = () => { failed = true; void stopOwnedProcess(child, { group: true }).catch(() => {}); };
   const timer = setTimeout(stop, Math.max(1, Math.min(10_000, timeoutMs)));

package/src/hub/settings.ts

@@ -1,10 +1,10 @@
-import { SUPPORTED_PEERS } from "./peer-catalog.ts";
+import { PLANNER_PEERS, 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 { configTracked, configRepositoryPresent } 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";
@@ -21,14 +21,15 @@ export interface SettingDef {
   key: string;
   group: "Permissions" | "Start" | "Routing" | "Switches" | "Roster" | "Roles";
   label: string;
-  type: "enum" | "boolean" | "peers" | "roles" | "integer";
+  type: "enum" | "boolean" | "peers" | "roles" | "integer" | "number";
   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";
+  /** `next use` keeps an active turn/session intact; `restart` retains the running value until a new daemon. */
+  applies: "live" | "next use" | "restart";
+  restartReason?: string;
   /** `raises`: only a settings session or a person's terminal may set it, except to `floor`. */
   risk: "safe" | "raises";
   floor?: string | boolean | number;
@@ -45,20 +46,23 @@ const perClass = (name: TaskClass): SettingDef[] => [
   { 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] })),
+  ...["enabled", "auto_reassign"].map((key): SettingDef => ({ key: `task_sweep.${key}`, group: "Switches", label: `Task sweep: ${key}`, type: "boolean", store: "config", applies: "live", risk: "raises", floor: false, path: ["task_sweep", key] })),
+  ...["interval_s", "unaccepted_min", "idle_min", "review_min", "ready_min", "ladder_min"].map((key): SettingDef => ({ key: `task_sweep.${key}`, group: "Switches", label: `Task sweep: ${key}`, type: "number", min: 1, max: 2_147_483_647 / (key === "interval_s" ? 1000 : 60_000), store: "config", applies: "live", risk: "raises", path: ["task_sweep", key] })),
+  ...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: "live", risk: "raises", floor: 0, path: ["tasks", "wip_limits", peer] })),
+  { key: "planner", group: "Roles", label: "Planner (the one peer that plans)", type: "enum", values: PLANNER_PEERS, store: "config", applies: "live", risk: "raises", path: ["planner"] },
+  ...SETTING_PEERS.map((peer): SettingDef => ({ key: `catalog_roles.${peer}`, group: "Roles", label: `${peer}: catalog guidance`, type: "roles", store: "config", applies: "next use", 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"] },
+  ...SETTING_PEERS.filter(peer => peer !== "jcode").map((peer): SettingDef => ({ key: `permission_modes.${peer}`, group: "Permissions", label: `${peer}: mode at next peer start`, type: "enum", values: PERMISSION_MODES, store: "config", applies: "next use", 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: "next use", 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: "next use", 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"] },
+  { key: "research.enabled", group: "Switches", label: "Research records", type: "boolean", store: "config", applies: "live", risk: "safe", path: ["research", "enabled"] },
+  { key: "approvals.notify", group: "Switches", label: "Desktop notice for a waiting approval", type: "boolean", store: "config", applies: "live", risk: "safe", path: ["approvals", "notify"] },
+  { key: "snapshots.enabled", group: "Switches", label: "Per-turn snapshots", type: "boolean", store: "config", applies: "live", risk: "safe", path: ["snapshots", "enabled"] },
+  { key: "coordination", group: "Switches", label: "Coordination of overlapping owners", type: "enum", values: ["advisory", "turn-free"], store: "config", applies: "next use", risk: "safe", path: ["coordination"] },
 ];
 
 /**
@@ -82,8 +86,8 @@ export function checkSettingValue(def: SettingDef, raw: unknown, routes: readonl
     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}`);
+  if (def.type === "integer" || def.type === "number") {
+    if (typeof raw !== "number" || !(def.type === "integer" ? Number.isSafeInteger(raw) : Number.isFinite(raw)) || raw < (def.min ?? 0) || raw > (def.max ?? Number.MAX_SAFE_INTEGER)) throw new Error(`${def.key} takes ${def.type === "integer" ? "an integer" : "a number"} from ${def.min ?? 0} to ${def.max ?? Number.MAX_SAFE_INTEGER}`);
     return raw;
   }
   if (def.type === "boolean") {
@@ -107,6 +111,7 @@ export function checkSettingValue(def: SettingDef, raw: unknown, routes: readonl
 /** 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 === "number") return text.trim() && Number.isFinite(Number(text)) ? Number(text) : text;
   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);
@@ -162,14 +167,7 @@ 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;
-  }
+  if (tracked === undefined && configRepositoryPresent(cwd)) throw new Error(`git could not confirm that .agenthub/${file} is untracked; nothing was written`);
 }
 /** 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 {
@@ -262,7 +260,7 @@ function checkConfigText(cwd: string, text: string | null, validate: (scratch: s
  * 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 {
+export function writeRoutingSetting(cwd: string, stateDir: string, def: SettingDef, value: SettingValue, check?: (routing: Routing, overlay?: RoutingOverlay) => void): Routing | undefined {
   const file = join(cwd, ".agenthub", OVERLAY_FILE);
   const before = readText(file);
   const current = before === null ? {} : parseOverlay(before);
@@ -270,7 +268,7 @@ export function writeRoutingSetting(cwd: string, stateDir: string, def: SettingD
   if (value === null ? held === undefined : same(held, value)) return undefined;
   const overlay = routingCandidate(current, def, value);
   const routing = parseRouting(routingText(cwd), overlay);
-  check?.(routing);
+  check?.(routing, overlay);
   const empty = !overlay.stay_switch && !Object.keys(overlay.classes ?? {}).length;
   store(cwd, stateDir, OVERLAY_FILE, def.key, before, empty ? null : overlayToml(overlay));
   return routing;
@@ -301,11 +299,13 @@ export function readOverlay(cwd: string): RoutingOverlay {
  * 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 } {
+export interface UndoIdentity { key: string; undoDigest: string }
+export function undoSetting(cwd: string, stateDir: string, validate: (scratch: string) => unknown, checkRouting?: (routing: Routing, overlay?: RoutingOverlay) => void, expected?: UndoIdentity): { 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 (expected && (record.key !== expected.key || digest(raw) !== expected.undoDigest)) throw new Error("undo record changed since preview; preview again; nothing was undone");
   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`);
@@ -313,10 +313,12 @@ export function undoSetting(cwd: string, stateDir: string, validate: (scratch: s
   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);
+    const overlay = record.previous === null ? undefined : parseOverlay(record.previous);
+    const restored = parseRouting(routingText(cwd), overlay);
+    checkRouting?.(restored, overlay);
   }
   else checkConfigText(cwd, record.previous, validate);
+  if (expected && readText(undoFile(stateDir)) !== raw) throw new Error("undo record changed since preview; preview again; nothing was undone");
   replaceFile(path, record.file, record.previous);
   rmSync(undoFile(stateDir), { force: true });
   return { key: String(record.key), file: record.file };
@@ -334,13 +336,23 @@ export function restoredValue(cwd: string, stateDir: string, def: SettingDef, in
   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; }
+    try { const record = JSON.parse(readFileSync(undoFile(stateDir), "utf8")) as UndoRecord;
+      if (record.file === OVERLAY_FILE && def.store === "routing") return valueAt(parseRouting(routingText(cwd), record.previous === null ? undefined : parseOverlay(record.previous)), def.path);
+      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; }
+  return pendingUndoIdentity(stateDir)?.key;
+}
+/** Snapshot identity of the exact record, including its previous bytes, file and write time. */
+export function pendingUndoIdentity(stateDir: string): UndoIdentity | undefined {
+  try {
+    const raw = readFileSync(undoFile(stateDir), "utf8"), record = JSON.parse(raw) as UndoRecord;
+    return typeof record.key === "string" && record.key.length > 0 ? { key: record.key, undoDigest: digest(raw)! } : 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). */
@@ -354,9 +366,12 @@ 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;
+  applies: SettingDef["applies"] | "peer start" | "hub start"; risk: SettingDef["risk"]; floor?: string | boolean | number;
   /** What is in force now; null when nothing sets it. */
   value: SettingValue;
+  /** Optional for replies from pre-#439 daemons; current projections always supply it. */
+  fileValue?: SettingValue;
+  restartReason?: string;
   /** 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. */
@@ -389,23 +404,23 @@ export function settingRows(input: {
   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 }),
+    const base = { key: def.key, group: def.group, label: def.label, type: def.type, ...(["integer", "number"].includes(def.type) ? { min: def.min, max: def.max } : {}), applies: def.applies, ...(def.restartReason ? { restartReason: def.restartReason } : {}), 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 } : {}) };
+      return { ...base, values: def.values!, file: "this hub run", value: mode.value ?? null, fileValue: 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"),
+      return { ...base, ...(def.type === "enum" ? { values: def.values ?? routes } : {}), file: OVERLAY_FILE, value, fileValue: 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." };
+    if (def.type === "roles" && input.roles) { const roles = input.roles(def.path[1]!); return { ...base, ...roles, fileValue: roles.pending !== undefined ? roles.pending : roles.value, 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 }),
+    return { ...base, ...(def.values ? { values: def.values } : {}), file: CONFIG_LOCAL, value, fileValue: stored, 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/settled-roles.ts

@@ -0,0 +1,35 @@
+import { conductorPeer } from "./conductor.ts";
+import { PLANNER_PEERS } from "./peer-catalog.ts";
+
+export interface SettledRoles {
+  roles: Record<string, string[]>;
+  source: "setting" | "roles" | "automatic" | "none";
+  planners: string[];
+  conductor?: string;
+}
+
+/** Resolve the runtime planner fallback without changing the configured policy role map. */
+export function resolveSettledRoles(
+  policyRoles: Readonly<Record<string, readonly string[]>>,
+  planner: string | undefined,
+  rostered: (peer: string) => boolean,
+): SettledRoles {
+  const roles = Object.fromEntries(Object.entries(policyRoles).map(([peer, list]) => [peer, [...list]]));
+  const pinned = (PLANNER_PEERS as readonly string[]).includes(planner ?? "") ? planner! : undefined;
+  let source: SettledRoles["source"];
+  if (pinned) {
+    for (const peer of Object.keys(roles)) roles[peer] = roles[peer]!.filter(role => role !== "planner");
+    roles[pinned] = ["planner", ...(roles[pinned] ?? [])];
+    source = "setting";
+  } else if (Object.entries(roles).some(([peer, list]) => list.includes("planner") && rostered(peer))) source = "roles";
+  else {
+    const auto = PLANNER_PEERS.find(rostered);
+    if (auto) {
+      for (const peer of Object.keys(roles)) roles[peer] = roles[peer]!.filter(role => role !== "planner");
+      roles[auto] = [...(roles[auto] ?? []), "planner"];
+    }
+    source = auto ? "automatic" : "none";
+  }
+  const conductor = conductorPeer(roles);
+  return { roles, source, planners: Object.keys(roles).filter(peer => roles[peer]!.includes("planner")).sort(), ...(conductor === null ? {} : { conductor }) };
+}