@staix/agent-hub 0.12.31 → 0.12.33

package/src/hub/settings.ts

@@ -4,7 +4,7 @@ import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameS
 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,21 +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] })),
+  ...["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: "peer start", risk: "safe", path: ["catalog_roles", peer] })),
+  ...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"] },
 ];
 
 /**
@@ -83,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") {
@@ -108,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);
@@ -163,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 {
@@ -263,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);
@@ -271,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;
@@ -302,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`);
@@ -314,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 };
@@ -335,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). */
@@ -355,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. */
@@ -390,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 }) };
+}

package/src/hub/supervision.ts

@@ -31,7 +31,7 @@ export interface SupervisionDeps {
   isPrivate: (task: Task) => boolean;
   /** false means not admitted, so latches must remain retryable. No separate batching timer. */
   emit: (notice: SupervisionNotice) => boolean | void;
-  approvalAgeMs?: number;
+  approvalAgeMs?: number | (() => number);
   now?: () => number;
   /** Durable round state belongs to the daemon's store, not the controller. */
   readRound?: (peer: string) => string | undefined;
@@ -127,10 +127,11 @@ export class SupervisionFeed {
   }
 
   approvalWaiting(request: { id: string; peer: string; tool: string; createdAt: number }): boolean {
+    const approvalAgeMs = typeof this.d.approvalAgeMs === "function" ? this.d.approvalAgeMs() : this.d.approvalAgeMs ?? 60_000;
     const peer = this.recipient();
     const age = (this.d.now?.() ?? Date.now()) - request.createdAt;
     const key = `${peer}:${request.id}`;
-    if (!peer || !Number.isFinite(age) || age < (this.d.approvalAgeMs ?? 60_000) || this.approvals.has(key)) return false;
+    if (!peer || !Number.isFinite(age) || age < approvalAgeMs || this.approvals.has(key)) return false;
     const sent = this.send(`approval:${request.id}`, `${request.peer}: approval waiting; tool ${request.tool}; age ${Math.floor(age / 1000)}s; ask the person to answer it in ahub console`, "important");
     if (sent) this.approvals.add(key);
     return sent;

package/src/hub/tasks.ts

@@ -97,6 +97,8 @@ export interface TasksDeps {
   recordScreen?: (record: ScreenRecord) => void;
   /** Turn-free coordination (issue #107): configured and no PII task open. Asked at each use. */
   turnFree?: () => boolean;
+  /** Coordination preference captured for each newly created task; existing rows keep their initial mode. */
+  coordination?: () => boolean;
   /** Whether a peer's context path for facts is verified in its current session (issue #108). */
   capable?: (peer: PeerId) => boolean;
   /** Whether `peer` is between native turns now (issue #107): Codex not busy, Claude stopped since its last tool call. */
@@ -223,10 +225,15 @@ export class Tasks {
   private readonly knownPlanners = new Set<PeerId>();
   /** Turn-free cohorts (issue #107): who works without messages, and who integrates. */
   readonly cohorts: Cohorts;
-  private readonly sweepConfig: TaskSweepConfig;
+  private readonly coordinationModes = new Map<number, boolean>();
+  private sweepConfig: TaskSweepConfig;
   private sweeping = false;
 
   constructor(private readonly d: TasksDeps) {
+    if (d.coordination) {
+      const mode = d.coordination();
+      for (const task of d.board.list()) this.coordinationModes.set(task.id, mode);
+    }
     const backlog = d.board.list("backlog");
     for (const [peer, roles] of Object.entries(d.roles ?? {})) {
       if (!roles.includes("planner")) continue;
@@ -310,13 +317,14 @@ export class Tasks {
   /** Task-owned, default-off between-turn ladder. Persist before sending so restart cannot repeat a step. */
   async sweep(now = Date.now()): Promise<{ task: number; finding: SweepRecord }[]> {
     const recorded: { task: number; finding: SweepRecord }[] = [];
-    if (!this.sweepConfig.enabled || this.sweeping || this.d.sweepHeld?.() || this.d.bus.isRecoveryHeld || this.d.bus.storageError) return recorded;
+    const config = this.sweepConfig;
+    if (!config.enabled || this.sweeping || this.d.sweepHeld?.() || this.d.bus.isRecoveryHeld || this.d.bus.storageError) return recorded;
     this.sweeping = true;
     try {
       for (const task of this.d.board.list()) {
         if (this.d.sweepHeld?.() || this.d.bus.isRecoveryHeld || this.d.bus.storageError) break;
         if (!task.owner && this.personUnassigned(task)) continue;
-        const finding = nextSweep(task, this.sweepConfig, now, this.waitsFor(task).length === 0);
+        const finding = nextSweep(task, config, now, this.waitsFor(task).length === 0);
         if (!finding || this.waitsFor(task).length || this.isChecking(task.id) || this.silentFor(task.id)) continue;
         if (finding.kind === "ready-unassigned") {
           this.d.board.update(task.id, HUB, "idle sweep", {}, undefined, { sweep: finding });
@@ -329,7 +337,7 @@ export class Tasks {
           } else {
             const admission = this.plannerPullRecord(task)?.pull ? this.plannerAssignment(task, true) : assign(task, this.states(), this.d.routing(), { exclude: this.excluded(task), ...this.weights(task.class) });
             this.releaseNotice(`${text} Owner reassignment suggestion: ${admission.owner ?? "no eligible peer"}.`);
-            if (admission.owner && this.sweepConfig.auto_reassign && this.sweepAvailable(admission.owner)) {
+            if (admission.owner && config.auto_reassign && this.sweepAvailable(admission.owner)) {
               try { await this.assignOwner(this.d.board.get(task.id)!, HUB, { candidates: [admission.owner], event: "reassigned", reason: "idle", note: "ready-unassigned idle sweep" }); }
               catch (e) { if (!(e instanceof AssignmentUndeliveredError)) throw e; }
             }
@@ -338,7 +346,7 @@ export class Tasks {
         }
         const responsible = finding.kind === "review-pending" ? task.reviewer! : task.owner!;
         if (responsible !== USER && !this.sweepAvailable(responsible)) continue;
-        if (finding.step === 3 && finding.kind !== "review-pending" && this.sweepConfig.auto_reassign && this.plannerPullRecord(task)?.pull && !assign(task, this.states(), this.d.routing(), { exclude: [...this.excluded(task), responsible], excludeOwners: this.plannerFull(task), waitsFor: this.waitsFor(task), ...this.weights(task.class) }).owner) continue;
+        if (finding.step === 3 && finding.kind !== "review-pending" && config.auto_reassign && this.plannerPullRecord(task)?.pull && !assign(task, this.states(), this.d.routing(), { exclude: [...this.excluded(task), responsible], excludeOwners: this.plannerFull(task), waitsFor: this.waitsFor(task), ...this.weights(task.class) }).owner) continue;
         const title = this.publicTitle(task);
         const message = `Task ${title}: ${finding.kind}, idle escalation ${finding.step}/3.`;
         // Only identifiers, kind and step are kept in the ladder event. A crash after this write and before publish
@@ -358,7 +366,7 @@ export class Tasks {
           const candidate = reviewer ? a.reviewer : a.owner;
           this.passedOver(task, a);
           this.d.notify(`${message} ${reviewer ? "Reviewer" : "Owner"} reassignment suggestion: ${candidate ?? "no eligible peer"}.`);
-          if (!reviewer && candidate && this.sweepConfig.auto_reassign && this.sweepAvailable(candidate)) {
+          if (!reviewer && candidate && config.auto_reassign && this.sweepAvailable(candidate)) {
             try {
               await this.assignOwner(this.d.board.get(task.id)!, HUB, { candidates: [candidate], exclude: [responsible], event: "reassigned", reason: "idle", note: `idle sweep: ${finding.kind}; from ${responsible}` });
             } catch (e) {
@@ -373,6 +381,11 @@ export class Tasks {
     return recorded;
   }
 
+  /** A validated snapshot takes effect on the next sweep, never halfway through one. */
+  configureSweep(config: TaskSweepConfig): void {
+    this.sweepConfig = taskSweepConfig(config);
+  }
+
   private sweepAvailable(peer: PeerId): boolean {
     const bus = this.d.bus;
     return bus.stateOf(peer) === "idle" && (this.d.idle?.(peer) ?? true) && !peerEntry(this.d.held?.(), peer) && !bus.queueSummary(peer).heldBy && !bus.queued(peer) && !bus.hasInFlight(peer);
@@ -934,6 +947,10 @@ export class Tasks {
     const inherited = current.drafts.map((_part, index) => (initialParentPrivate || this.isPii(current.parent)) && !deterministicPrivate[index]);
     const drafts = current.drafts.map((part, index) => ({ ...part, ...(screening ? { screeningNote: inherited[index] ? "pii: inherited" : this.screenNote(verdicts[index]) } : {}), signals: [...new Set([...initialPrivacy[index]!, ...initialParentPrivacy, ...finalSignals[index]!, ...current.parent.signals.filter(signal => ["pii", "pii_path", "urgent"].includes(signal)), ...(verdicts[index] && verdicts[index]!.label !== "clear" ? ["pii"] : [])])] }));
     const result = this.d.board.splitBacklog(id, by, revision, drafts, reason, withheld || initialReasonPrivate || this.isPii(current.parent) || !this.nameable(reason));
+    if (this.d.coordination) {
+      const mode = this.d.coordination();
+      for (const child of result.children) this.coordinationModes.set(child.id, mode);
+    }
     for (const [index, child] of result.children.entries()) {
       this.incomingBacklog.add(child.id);
       if (screening) { this.recordScreen(child.id, "task", verdicts[index], inherited[index]); if (verdicts[index]?.label === "unknown") this.releaseNotice(`task #${child.id}: the PII screen gave no verdict (${verdicts[index]!.miss}); it is handled as a PII task`); }
@@ -1029,6 +1046,7 @@ export class Tasks {
     if (external) { const prior = this.d.board.imported(external.repo, external.issue); if (prior) return prior; }
     if (reserved) this.requireCapabilities({ ...draft, signals, ...(external ? { external } : {}) }, reserved);
     let task = this.d.board.propose(by, { ...draft, plan, ...(external ? { external } : {}), ...(deps.length ? { deps } : {}), ...(reserved ? { reserved } : {}), signals, ...(backlog ? { backlog: true } : {}) });
+    if (this.d.coordination) this.coordinationModes.set(task.id, this.d.coordination());
     created?.();
     if (screening) task = this.screenedTask(task, screened);
     if (goal) this.linkNative(task, goal, by);
@@ -1912,8 +1930,10 @@ export class Tasks {
    */
   private formCohort(task: Task, hits: ReturnType<Tasks["overlapHits"]>): void {
     if (!task.owner || this.isPii(task)) return;
+    const coordinate = this.coordinationModes.get(task.id);
+    const coordinated = this.d.coordination ? hits.filter(hit => this.coordinationModes.get(hit.task.id) === coordinate) : hits;
     const before = this.cohorts.of(task.id)?.revision;
-    const joined = this.cohorts.join(task, hits.map((h) => h.task), ownerGen, handedAt);
+    const joined = this.cohorts.join(task, coordinated.map((h) => h.task), ownerGen, handedAt, !this.d.coordination || coordinate === true);
     if (!joined) return;
     const c = joined.cohort;
     if (joined.formed || c.revision !== before) {
@@ -2395,7 +2415,7 @@ export class Tasks {
       const acceptance = previous.history.slice(assignment + 1).some(entry => entry.event === "accepted" && entry.by === peer);
       const boardEvidence = role === "owner" && acceptance;
       const mayHaveReceived = boardEvidence || this.d.bus.lastDeliveredTo(peer).some(matches) || this.d.bus.queueList(peer).some(row => ["dispatching", "accepted", "needs_review", "completed"].includes(row.state) && row.originals.some(matches));
-      for (const env of this.d.bus.snapshot(false).queues[peer] ?? []) if (matches(env)) this.d.bus.withdraw(env.id);
+      for (const env of this.d.bus.pendingEnvelopes(peer)) if (matches(env)) this.d.bus.withdraw(env.id);
       if (!mayHaveReceived) return;
       const body = role === "owner"
         ? `Task ${this.publicTitle(next)} is no longer assigned to you${next.owner ? `; its owner is now ${next.owner}` : "; it is unassigned"}. Do not accept or complete it; late calls under your former assignment are refused.`
@@ -2668,7 +2688,7 @@ export class Tasks {
     let n = 0;
     for (const t of this.d.board.list("approved")) {
       if (this.isPii(t)) continue;
-      try { this.d.memoryCheck?.(); const key = this.memoryKey(t); if (this.d.store.store.hasTask(key) && !this.d.store.store.settled(key)) { this.settleMemory(t); n++; } }
+      try { this.d.memoryCheck?.(); const key = this.memoryKey(t); if (this.d.store.store.hasTask(key) && !this.d.store.store.settled(key, { includeLegacy: true })) { this.settleMemory(t); n++; } }
       catch { /* fail-open: tried again at the next start */ }
     }
     return n;

package/src/hub/ui.ts

@@ -131,7 +131,7 @@ export function startDashboard(options: DashboardOptions) {
         }
       }
       try {
-        if (sessionOf(cookie).liveTest && !["start", "stop", "pause", "resume", "permit", "start_peer", "setting", "setting_undo", "setting_preview", "sdlc_queue", "sdlc_release"].includes(String(input.action))) {
+        if (sessionOf(cookie).liveTest && !["start", "stop", "pause", "resume", "permit", "start_peer", "setting", "setting_undo", "setting_preview", "setting_reload", "sdlc_queue", "sdlc_release"].includes(String(input.action))) {
           return reject(403, "live-test dashboard cannot write person-attributed content; use peer tools");
         }
         if (input.action === "sdlc_queue" || input.action === "sdlc_release") server.timeout(req, 35);

package/src/memory/brief.ts

@@ -45,7 +45,7 @@ export class Briefs {
   constructor(
     private readonly client: MemoryClient | undefined,
     private readonly project: string,
-    private readonly maxItems = 8,
+    private readonly maxItems: number | (() => number) = 8,
     private readonly native?: NativeBrief,
     /** Counts of what a brief carried, for the research records (#258 AC11); never its text. */
     private readonly observe?: (peer: PeerId, task: number, counts: { native: number; fails: number; claudeMem: number }) => void,
@@ -53,18 +53,19 @@ export class Briefs {
   ) {}
 
   async forTask(peer: PeerId, task: BriefTask, priority: readonly NativeItem[] = []): Promise<string | undefined> {
+    const maximum = typeof this.maxItems === "function" ? this.maxItems() : this.maxItems;
     const seen = this.seen.get(peer) ?? new Set<string>();
     this.seen.set(peer, seen);
     const own: NativeItem[] = [];
     // A plan fail is task-specific guidance even when a previous task already carried it.
-    for (const item of priority) if (own.length < this.maxItems && !own.some(existing => existing.id === item.id)) own.push(item);
-    try { for (const item of this.native?.(task) ?? []) if (!seen.has(item.id) && !own.some(existing => existing.id === item.id) && own.length < this.maxItems) own.push(item); } catch { /* fail-open: the store is optional */ }
-    const found = this.client && own.length < this.maxItems ? await related(this.client, this.project, [task.title, ...(task.refs.paths ?? [])].join(" ")) : [];
+    for (const item of priority) if (own.length < maximum && !own.some(existing => existing.id === item.id)) own.push(item);
+    try { for (const item of this.native?.(task) ?? []) if (!seen.has(item.id) && !own.some(existing => existing.id === item.id) && own.length < maximum) own.push(item); } catch { /* fail-open: the store is optional */ }
+    const found = this.client && own.length < maximum ? await related(this.client, this.project, [task.title, ...(task.refs.paths ?? [])].join(" ")) : [];
     const items: BriefItem[] = [];
     for (const item of found) {
       if (seen.has(`#${item.id}`)) continue;
       items.push(item);
-      if (own.length + items.length === this.maxItems) break;
+      if (own.length + items.length === maximum) break;
     }
     if (!own.length && !items.length) return undefined;
     for (const item of own) seen.add(item.id);

package/src/pi/session.ts

@@ -4,13 +4,32 @@ import { randomUUID } from "node:crypto";
 import { realPath } from "../hub/project.ts";
 import { atomicPrivateJSON } from "../hub/recovery-store.ts";
 
+export class PiSessionUnresumable extends Error {
+  readonly code = "pi_session_unresumable";
+  constructor(readonly reason: "missing" | "outside_managed" | "invalid_header", message: string, options?: ErrorOptions) { super(message, options); }
+}
+export class PiSessionBookmarkMismatch extends Error {
+  readonly code = "pi_session_bookmark_mismatch";
+  readonly reason = "bookmark_mismatch";
+}
+function sessionReadFailure(error: unknown): never {
+  if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new PiSessionUnresumable("missing", (error as Error).message, { cause: error });
+  throw error;
+}
+
 /** One validation boundary for ordinary starts and explicit preserved-history selection. */
 export function validatePiSession(stateDir: string, cwd: string, sessionFile: string, sessionId?: string): { sessionFile: string; sessionId: string } {
-  const file = realPath(sessionFile), sessions = realPath(join(stateDir, "pi-sessions"));
+  let file: string, sessions: string;
+  try { file = realPath(sessionFile); sessions = realPath(join(stateDir, "pi-sessions")); }
+  catch (error) { return sessionReadFailure(error); }
   const rel = relative(sessions, file);
-  if (!rel || rel.startsWith("..") || resolve(sessions, rel) !== file) throw new Error("Pi session file is outside the managed project session directory");
-  const header = JSON.parse(readFileSync(file, "utf8").split("\n", 1)[0]!);
-  if (header.type !== "session" || typeof header.id !== "string" || !header.id || typeof header.cwd !== "string" || realPath(header.cwd) !== realPath(cwd) || (sessionId && header.id !== sessionId)) throw new Error("Pi session header does not match the requested project/session");
+  if (!rel || rel.startsWith("..") || resolve(sessions, rel) !== file) throw new PiSessionUnresumable("outside_managed", "Pi session file is outside the managed project session directory");
+  let first: string;
+  try { first = readFileSync(file, "utf8").split("\n", 1)[0]!; } catch (error) { return sessionReadFailure(error); }
+  let header: { type?: unknown; id?: unknown; cwd?: unknown } | null;
+  try { header = JSON.parse(first); } catch (error) { throw new PiSessionUnresumable("invalid_header", (error as Error).message, { cause: error }); }
+  if (!header || header.type !== "session" || typeof header.id !== "string" || !header.id || typeof header.cwd !== "string" || realPath(header.cwd) !== realPath(cwd)) throw new PiSessionUnresumable("invalid_header", "Pi session header does not match the requested project/session");
+  if (sessionId && header.id !== sessionId) throw new PiSessionBookmarkMismatch("Pi continuity bookmark does not match the preserved session");
   return { sessionFile: file, sessionId: header.id };
 }
 

package/src/ui/index.html

@@ -319,16 +319,19 @@ async function previewSetting(row, value, out, control) {
 function settingRow(row, raise) {
   const node = el('div', undefined, 'row'), head = el('div', undefined, 'row-head'), id = 'setting-' + row.key.replaceAll('.', '-');
   const title = el('label', row.label, 'label'); title.htmlFor = id;
+  const fileValue = row.fileValue !== undefined ? row.fileValue : row.pending !== undefined ? row.pending : row.value;
   head.append(title, badge(settingText(row.value), row.group === 'Permissions' && row.value !== null && row.value !== 'ask' ? 'warn' : ''));
-  node.append(head, el('p', row.key + ' / from ' + row.source + ' / ' + (row.applies === 'live' ? 'applies at once' : row.applies === 'peer start' ? "applies at the peer's next start" : 'read at hub start') + ' / written to ' + row.file, 'meta'));
-  if (row.pending !== undefined) node.append(el('p', 'Pending restart: ' + settingText(row.pending) + ' at the next ' + (row.applies === 'peer start' ? 'peer' : 'hub') + ' start.', 'meta'));
+  node.append(head, el('p', row.key + ' / from ' + row.source + ' / ' + (row.applies === 'live' ? 'applies at once' : row.applies === 'next use' ? 'applies at next use' : row.applies === 'restart' ? 'applies after restart' : row.applies === 'peer start' ? "applies at the peer's next start" : 'read at hub start') + ' / written to ' + row.file, 'meta'));
+  node.append(el('p', 'Running: ' + settingText(row.value) + ' / File: ' + settingText(fileValue), 'meta'));
+  if (['live', 'next use', 'restart'].includes(row.applies)) node.append(el('p', 'Apply: ' + row.applies + (row.restartReason ? ' / ' + row.restartReason : ''), 'meta'));
+  if (row.pending !== undefined) node.append(el('p', ['hub start', 'peer start'].includes(row.applies) ? 'Pending restart: ' + settingText(row.pending) + ' at the next ' + (row.applies === 'peer start' ? 'peer' : 'hub') + ' start.' : 'Pending ' + row.applies + ': ' + settingText(row.pending), 'meta'));
   if (row.hint) node.append(el('p', 'Bounds: ' + row.hint, 'meta'));
   if (row.note) node.append(el('p', row.note, 'meta'));
   if (row.risk === 'raises' && !raise) node.append(el('p', 'Raising this needs a settings session: run ahub ui --settings.' + (row.floor === undefined ? '' : ' Setting it to ' + row.floor + ' works here.'), 'meta'));
   const actions = el('div', undefined, 'actions'), stored = row.file !== 'this hub run';
   let read, confirm, force;
   if (row.type === 'roles') {
-    const current = Array.isArray(row.pending) ? row.pending : Array.isArray(row.value) ? row.value : [];
+    const current = Array.isArray(fileValue) ? fileValue : [];
     const choices = [0, 1].map(index => {
       const select = el('select'); select.id = index ? id + '-second' : id;
       if (index) select.setAttribute('aria-label', row.label + ': second optional role');
@@ -338,15 +341,15 @@ function settingRow(row, raise) {
       select.value = current[index] || ''; actions.append(select); return select;
     });
     read = () => choices.map(select => select.value).filter(Boolean);
-  } else if (row.type === 'integer') {
-    const input=el('input');input.type='number';input.id=id;input.step='1';input.min=String(row.min ?? 0);input.max=String(row.max ?? Number.MAX_SAFE_INTEGER);const current=row.pending!==undefined ? row.pending : row.value;input.value=current===null ? '' : String(current);input.placeholder='Empty inherits';
+  } else if (row.type === 'integer' || row.type === 'number') {
+    const input=el('input');input.type='number';input.id=id;input.step=row.type === 'number' ? 'any' : '1';input.min=String(row.min ?? 0);input.max=String(row.max ?? Number.MAX_SAFE_INTEGER);const current=fileValue;input.value=current===null ? '' : String(current);input.placeholder='Empty inherits';
     read=()=>input.value==='' ? null : Number(input.value);actions.append(input);
   } else if (row.type === 'peers') {
-    const input = el('input'); input.type = 'text'; input.id = id; input.value = Array.isArray(row.value) ? row.value.join(', ') : ''; input.placeholder = 'peer ids, comma-separated; empty inherits'; input.autocomplete = 'off'; input.spellcheck = false;
+    const input = el('input'); input.type = 'text'; input.id = id; input.value = Array.isArray(fileValue) ? fileValue.join(', ') : ''; input.placeholder = 'peer ids, comma-separated; empty inherits'; input.autocomplete = 'off'; input.spellcheck = false;
     read = () => { const list = input.value.split(',').map((value) => value.trim()).filter(Boolean); return list.length ? list : null; };
     actions.append(input);
   } else {
-    const select = el('select'), values = row.type === 'boolean' ? ['true', 'false'] : (row.values || []), current = row.value === null ? '' : String(row.value); select.id = id;
+    const select = el('select'), values = row.type === 'boolean' ? ['true', 'false'] : (row.values || []), current = fileValue === null ? '' : String(fileValue); select.id = id;
     if (current && !values.includes(current)) { const option = el('option', current + ' (now)'); option.value = current; option.disabled = true; select.append(option); }
     for (const value of values) { const option = el('option', value); option.value = value; select.append(option); }
     if (stored) { const option = el('option', 'inherit (remove the machine-local value)'); option.value = INHERIT; select.append(option); }
@@ -391,6 +394,7 @@ function renderSettings(settings, roster = []) {
   // are rebuilt only when their own data changed, so a value being typed in one row survives a save of another.
   update('settings', settings.rows.map((row) => row.key), (target) => {
     settingSlots.clear();
+    const reload = el('div'); settingSlots.set('$reload', { node: reload, signature: null }); target.append(reload);
     const undo = el('div'); settingSlots.set('', { node: undo, signature: null }); target.append(undo);
     for (const group of SETTING_GROUPS) {
       const rows = settings.rows.filter((row) => row.group === group);
@@ -402,6 +406,18 @@ function renderSettings(settings, roster = []) {
       target.append(box);
     }
   });
+  const reloadSlot = settingSlots.get('$reload'), reloadSupported = Array.isArray(settings.pendingRestart);
+  const reloadSignature = JSON.stringify([settings.pendingRestart, managerMode && !snapshotValid]);
+  if (reloadSlot && reloadSlot.signature !== reloadSignature) {
+    reloadSlot.signature = reloadSignature; reloadSlot.node.replaceChildren();
+    if (reloadSupported) {
+      reloadSlot.node.append(button('Reload configuration', {action:'setting_reload'}));
+      if (settings.pendingRestart.length) {
+        reloadSlot.node.append(el('p', 'Pending restart', 'label'));
+        for (const pending of settings.pendingRestart) reloadSlot.node.append(el('p', pending.key + ': ' + pending.reason, 'meta'));
+      }
+    }
+  }
   const undoSlot = settingSlots.get(''), undoKey = settings.undo || '';
   if (undoSlot && undoSlot.signature !== undoKey) {
     undoSlot.signature = undoKey; undoSlot.node.replaceChildren();