@staix/agent-hub 0.12.31 → 0.12.33

package/src/hub/bus.ts

@@ -2,6 +2,7 @@ import { appendNote, DIGEST, HUB, keepNotes, MAX_HOP, mergePrefaces, newEnvelope
 import type { PeerAdapter, DeliveryReceipt } from "./peers.ts";
 import { DeliveryJournal, MAX_ENVELOPE_BODY, type JournalDelivery, type JournalDeliveryState } from "./delivery-journal.ts";
 import { DELIVERY_RETRY_WARNING } from "./delivery-hints.ts";
+import { MAX_DEFERRED_HUB, RecoveryDeferredHubError, validateDeferredHub } from "./deferred-hub.ts";
 import { PreEffectToolRefusal } from "./tool-refusal.ts";
 
 export type { DeliveryReceipt } from "./peers.ts";
@@ -64,6 +65,8 @@ export interface BusSnapshot {
   attempts: Record<string, number>;
   withdrawn: string[];
   manualPaused?: string[];
+  /** Hub notices accepted during recovery, durable but outside the carried delivery queues. */
+  deferredHub?: Envelope[];
   journal?: ReturnType<DeliveryJournal["snapshot"]>;
 }
 
@@ -142,6 +145,12 @@ export class Bus {
   /** Synchronous native failure observation, before queue callbacks can finish turn metrics. */
   onDeliveryFailed?: (peer: PeerId) => void;
   private recoveryHeld = false;
+  private deferHub = false;
+  private readonly deferredHub = new Map<string, Envelope>();
+  private flushingHub = false;
+  private replayingHub = false;
+  private deferredEvents: BusEvent[] = [];
+  private deferredNudges: (() => void)[] = [];
   private steering = 0;
   private condensing = 0;
   private closed = false;
@@ -162,6 +171,17 @@ export class Bus {
     }
   }
 
+  /** Apply future batching and admission limits without disturbing queued work or its existing deadline. */
+  configureScheduling(config: Pick<BusOptions, "batchMax" | "batchMs" | "queueCap">): void {
+    const { batchMax, batchMs, queueCap } = config;
+    if (!Number.isSafeInteger(batchMax) || batchMax < 1 || batchMax > 2_147_483_647 ||
+        !Number.isFinite(batchMs) || batchMs < 0 || batchMs > 2_147_483_647 ||
+        !Number.isSafeInteger(queueCap) || queueCap < 1 || queueCap > 2_147_483_647) {
+      throw new Error("invalid bus scheduling configuration");
+    }
+    Object.assign(this.opts, { batchMax, batchMs, queueCap });
+  }
+
   add(peer: PeerAdapter): void {
     this.peers.set(peer.id, peer);
     if (!this.queues.has(peer.id)) this.queues.set(peer.id, []);
@@ -262,10 +282,61 @@ export class Bus {
   }
 
   /** Stop new deliveries while a coordinator takes a stable snapshot. Existing adapter turns are left alone. */
-  setRecoveryHold(held: boolean): void {
-    this.recoveryHeld = held;
-    if (!held) this.onQueues?.(); // restored holds need classification even when no peer is attached
-    if (!held) for (const id of this.peers.keys()) void this.drain(id);
+  setRecoveryHold(held: boolean, deferHub = false): void {
+    if (this.replayingHub) throw new RecoveryDeferredHubError("recovery notice release is already in progress");
+    if (held) {
+      this.recoveryHeld = true;
+      this.deferHub = deferHub;
+      // An older target cannot carry this additive field: materialize before commit's expected integrity.
+      if (!deferHub) this.flushDeferredHub();
+      return;
+    }
+    // Persist each deferred -> queued transition while deliveries are still fenced. A failed checkpoint
+    // leaves the hold and the original pending head intact; a crash after it resumes from the journal.
+    this.flushDeferredHub();
+    this.recoveryHeld = false;
+    this.onQueues?.();
+    for (const id of this.peers.keys()) void this.drain(id);
+  }
+
+  private flushDeferredHub(): void {
+    if (this.flushingHub) return;
+    if (this.storageError) this.persist();
+    this.replayingHub = true;
+    try { while (this.deferredHub.size) {
+      const env = this.deferredHub.values().next().value!;
+      const beforeDeferred = [...this.deferredHub], beforeSeen = [...this.seen], beforeWithdrawn = [...this.withdrawn];
+      const affected = new Map(this.audience(env).map(peer => {
+        const queue = this.queues.get(peer);
+        return [peer, queue ? { queue, contents: [...queue] } : undefined] as const;
+      }));
+      const outcomes = this.pendingOutcomes.length;
+      this.flushingHub = true;
+      this.deferredEvents = []; this.deferredNudges = [];
+      try {
+        this.deferredHub.delete(env.id);
+        this.publishNow(env);
+      } catch (error) {
+        // Only publication state is transactional. A live peer's preface, pauses, attempts and
+        // recovery mode are independent state, not something a failed checkpoint may reload.
+        this.deferredHub.clear(); for (const [id, pending] of beforeDeferred) this.deferredHub.set(id, pending);
+        this.seen.clear(); for (const [id, seen] of beforeSeen) this.seen.set(id, seen);
+        this.withdrawn.clear(); for (const id of beforeWithdrawn) this.withdrawn.add(id);
+        for (const [peer, queue] of affected) {
+          if (queue) { queue.queue.splice(0, queue.queue.length, ...queue.contents); this.queues.set(peer, queue.queue); }
+          else this.queues.delete(peer);
+        }
+        this.pendingOutcomes.length = outcomes;
+        this.deferredEvents = []; this.deferredNudges = [];
+        throw new RecoveryDeferredHubError("deferred hub notice checkpoint failed; recovery remains held; restore delivery storage, then retry release or abort");
+      } finally { this.flushingHub = false; }
+      // Publication observers run only after the durable transition. Reentrant notices join the FIFO tail.
+      const events = this.deferredEvents; this.deferredEvents = [];
+      for (const event of events) this.emit(event);
+      const nudges = this.deferredNudges; this.deferredNudges = [];
+      for (const nudge of nudges) nudge();
+      this.onQueues?.();
+    } } finally { this.replayingHub = false; }
   }
 
   get isRecoveryHeld(): boolean {
@@ -285,7 +356,7 @@ export class Bus {
     let delay = 1;
     while (this.draining.size || this.steering || this.condensing) {
       if (Date.now() >= deadline) {
-        this.recoveryHeld = heldBefore;
+        if (!heldBefore) this.setRecoveryHold(false);
         throw new Error(`recovery fence timed out after ${timeoutMs} ms with ${this.draining.size + this.steering + this.condensing} deliveries still in flight; retry the operation`);
       }
       await Bun.sleep(delay);
@@ -303,6 +374,7 @@ export class Bus {
       attempts: Object.fromEntries(this.attempts),
       withdrawn: [...this.withdrawn],
       manualPaused: [...this.manualPaused],
+      ...(this.deferredHub.size ? { deferredHub: structuredClone([...this.deferredHub.values()]) } : {}),
     };
     if (includeJournal && this.journal) out.journal = this.journal.snapshot();
     return out;
@@ -330,6 +402,10 @@ export class Bus {
   }
 
   private loadSnapshot(snapshot: BusSnapshot): void {
+    const deferred = validateDeferredHub(snapshot.deferredHub, undefined, new Set([...snapshot.seen.map(e => e.id), ...Object.values(snapshot.queues).flat().map(e => e.id)]));
+    if (deferred.length) { this.recoveryHeld = true; this.deferHub = true; }
+    this.deferredHub.clear();
+    for (const env of deferred) this.deferredHub.set(env.id, structuredClone(env));
     this.queues.clear();
     for (const [id, queue] of Object.entries(snapshot.queues ?? {})) this.queues.set(id, queue.map((e) => ({ ...e, ...(e.to ? { to: [...e.to] } : {}) })));
     this.prefaces.clear();
@@ -521,7 +597,7 @@ export class Bus {
 
   queuedBacklogIds(id: PeerId): Set<number> {
     const ids = new Set<number>();
-    const retained = [...(this.queues.get(id) ?? []), ...(this.journal?.unresolved(id).filter(row => row.state !== "queued").flatMap(row => row.originals) ?? [])];
+    const retained = [...this.pendingEnvelopes(id), ...(this.journal?.unresolved(id).filter(row => row.state !== "queued").flatMap(row => row.originals) ?? [])];
     for (const env of retained) {
       const backlog = env.refs?.backlog;
       if (env.from !== HUB || env.kind !== "task" || !Array.isArray(backlog) || backlog.length > 64) continue;
@@ -591,8 +667,52 @@ export class Bus {
     this.prefaces.set(id, !now ? { ...env, body: uniqueMemoryLines(env.body) } : now.id === env.id ? { ...now, body: uniqueMemoryLines(now.body) } : { ...env, body: keepNotes(mergePrefaces(env.body, now.body), NOTES_KEPT) });
   }
 
-  /** Returns the peers the envelope was queued for. */
+  /** Stopped-runtime reset only: audit every deferred recipient without publishing or releasing work. */
+  discardDeferredHub(reason: string): string[] {
+    if (this.peers.size || this.flushingHub || this.replayingHub || !this.journal || this.storageError) throw new Error("deferred reset requires a stopped, readable delivery journal");
+    const pending = [...this.deferredHub];
+    const settled: string[] = [];
+    try {
+      this.journal.transaction(() => {
+        for (const [, env] of pending) for (const peer of new Set(env.to ?? [])) {
+          const id = `q:${peer}:${env.id}`;
+          this.journal!.createDelivery({ id, peer, state: "queued", createdAt: env.ts, originals: [env], out: [env] });
+          const row = this.journal!.get(id)!;
+          this.journal!.resolve(id, row.revision, "discard", reason, row.revision, "user");
+          settled.push(id);
+        }
+        this.deferredHub.clear();
+        this.persist();
+      });
+    } catch (error) {
+      this.deferredHub.clear(); for (const [id, env] of pending) this.deferredHub.set(id, env);
+      throw error;
+    }
+    return settled;
+  }
+
+  /** Accepted pending work, including notices withheld from the recovery integrity view. */
+  pendingEnvelopes(peer: PeerId): Envelope[] {
+    return [...(this.queues.get(peer) ?? []), ...[...this.deferredHub.values()].filter(e => e.to?.includes(peer))];
+  }
+
+  /** Returns the peers the envelope was accepted for, including durable deferred notices. */
   publish(env: Envelope): PeerId[] {
+    if (this.storageError) throw new Error("delivery journal unavailable");
+    if (this.seen.has(env.id) || this.deferredHub.has(env.id)) return [];
+    if (this.recoveryHeld && (this.deferHub || this.replayingHub) && env.from === HUB && env.priority !== "fyi" && env.hop <= MAX_HOP) {
+      if (this.deferredHub.size >= MAX_DEFERRED_HUB) throw new RecoveryDeferredHubError();
+      const targets = this.audience(env);
+      const copy = structuredClone({ ...env, to: targets });
+      this.deferredHub.set(copy.id, copy);
+      try { this.persist(); }
+      catch (error) { this.deferredHub.delete(copy.id); throw error; }
+      return targets;
+    }
+    return this.publishNow(env);
+  }
+
+  private publishNow(env: Envelope): PeerId[] {
     if (this.storageError) throw new Error("delivery journal unavailable");
     if (this.seen.has(env.id)) return [];
     this.seen.set(env.id, env);
@@ -627,7 +747,7 @@ export class Bus {
     } } finally { this.suppressDrain = false; }
     if (this.journal) {
       this.persist();
-      this.onQueues?.();
+      if (!this.flushingHub) this.onQueues?.();
       for (const id of targets) {
         const peer = this.peers.get(id);
         if (!this.held(id) && env.priority === "important" && peer?.steer && this.stateOf(id) === "busy") void this.steerQueued(id, env);
@@ -670,7 +790,7 @@ export class Bus {
 
   /** A recently published envelope, for resolving `reply_to`. */
   get(id: string): Envelope | undefined {
-    return this.seen.get(id);
+    return this.seen.get(id) ?? this.deferredHub.get(id);
   }
 
   /** The envelopes most recently handed to a peer, used to distinguish a received request from an unread queue. */
@@ -685,10 +805,10 @@ export class Bus {
    */
   withdraw(envelopeId: string): boolean {
     this.markWithdrawn(envelopeId);
-    let removed = false;
+    let removed = this.deferredHub.delete(envelopeId);
     for (const queue of this.queues.values()) {
       const i = queue.findIndex((e) => e.id === envelopeId);
-      if (i !== -1) removed = queue.splice(i, 1).length > 0;
+      if (i !== -1) { queue.splice(i, 1); removed = true; }
     }
     if (removed) this.onQueues?.();
     this.persist();
@@ -698,8 +818,15 @@ export class Bus {
   /** Revoke pending feed copies only; accepted/dispatching journal records and native turns are untouched. */
   revokeSupervision(peer: PeerId): number {
     const queue = this.queues.get(peer);
-    if (!queue && !this.preparing.has(peer)) return 0;
     let removed = 0;
+    for (const [id, env] of this.deferredHub) {
+      if (!env.refs?.supervision || !env.to?.includes(peer)) continue;
+      const remaining = env.to.filter(target => target !== peer);
+      if (remaining.length) this.deferredHub.set(id, { ...env, to: remaining });
+      else this.deferredHub.delete(id);
+      removed++;
+    }
+    if (!queue && !this.preparing.has(peer)) { if (removed) this.persist(); return removed; }
     const discarded = new Set<string>();
     for (let i = (queue?.length ?? 0) - 1; i >= 0; i--) {
       const env = queue![i]!;
@@ -785,9 +912,11 @@ export class Bus {
     }
     if (queuedEnv.priority === "important" && this.peers.get(id)?.pullOnly) {
       // Advisory only (issue #398): the envelope stays queued for `pull`; the hook must never affect it.
-      try { this.opts.onImportantQueued?.(id, { queued: queue.length, important: queue.filter((e) => e.priority === "important").length }); } catch { /* a nudge never stops an enqueue */ }
+      const counts = { queued: queue.length, important: queue.filter((e) => e.priority === "important").length };
+      const nudge = () => { try { this.opts.onImportantQueued?.(id, counts); } catch { /* a nudge never stops an enqueue */ } };
+      if (this.flushingHub) this.deferredNudges.push(nudge); else nudge();
     }
-    this.onQueues?.();
+    if (!this.flushingHub) this.onQueues?.();
     if (!this.suppressDrain) this.persist();
     if (!this.suppressDrain) void this.drain(id);
   }
@@ -1049,6 +1178,7 @@ export class Bus {
   }
 
   private emit(e: BusEvent): void {
+    if (this.flushingHub) { this.deferredEvents.push(e); return; }
     for (const tap of this.taps) tap(e);
   }
 }

package/src/hub/cohorts.ts

@@ -102,7 +102,7 @@ export class Cohorts {
    * in, records owner changes (each bumps the revision and voids that member's intent), and lifts a silent cohort that
    * an owner without verified facts joins. Returns what happened, for the notices.
    */
-  join(task: Task, others: Task[], gen: (t: Task) => number, handed: (t: Task) => number = () => Date.now()): { cohort: Cohort; formed: boolean; lifted: boolean } | undefined {
+  join(task: Task, others: Task[], gen: (t: Task) => number, handed: (t: Task) => number = () => Date.now(), allowSilence = true): { cohort: Cohort; formed: boolean; lifted: boolean } | undefined {
     this.gc();
     const all = [task, ...others].filter((t) => t.owner);
     const found = [...new Set(all.map((t) => this.of(t.id)).filter((c): c is Cohort => !!c))];
@@ -133,7 +133,7 @@ export class Cohorts {
     }
     if (changed) cohort.revision++;
     const owners = [...new Set([...cohort.members.values()].map((m) => m.owner))];
-    if (formed) cohort.silent = this.d.silence(owners);
+    if (formed) cohort.silent = allowSilence && this.d.silence(owners);
     else if (cohort.silent && changed && !this.d.silence(owners)) cohort.silent = false;
     // Lifted: a silent cohort (or a silent one merged into this) is no longer silent, and its members must hear it.
     return { cohort, formed, lifted: wasSilent && !cohort.silent };

package/src/hub/config-apply.ts

@@ -0,0 +1,242 @@
+import type { HubConfig } from "./daemon.ts";
+import { ALL_MACHINE_LOCAL, configRepositoryPresent, configTracked } from "./config-trust.ts";
+import { SUPPORTED_PEERS, PLANNER_PEERS } from "./peer-catalog.ts";
+import { CLASSES } from "./board.ts";
+import { permissionDefaults } from "./permission-mode.ts";
+import { peerStartConfig, terminalTemplate } from "./start-mode.ts";
+import { catalogAssignments } from "./roles.ts";
+import { resolveProfile } from "./profiles.ts";
+import { taskSweepConfig } from "./task-sweep.ts";
+import { projectionConfig } from "./text-projection.ts";
+
+export type ApplyClass = "live" | "next use" | "restart";
+export interface ApplyRule { applies: ApplyClass; reason?: string }
+export interface ConfigChange extends ApplyRule { key: string; before: unknown; after: unknown }
+export interface ConfigLayer { name: "config.json" | "config.local.json"; raw: Record<string, unknown> }
+export interface ReloadGuard { key: string; path: readonly string[]; risk: "safe" | "raises"; floor?: string | boolean | number; store: "runtime" | "config" | "routing" }
+export interface ConfigAuthorizationInput {
+  key: string;
+  before: unknown;
+  after: unknown;
+  source: "config" | "routing";
+  tracked: boolean | undefined;
+  authority: "ordinary" | "settings" | "terminal";
+  /** The daemon supplies this only for the selected setting or an explicitly confirmed reload key. */
+  confirmed?: boolean;
+  /** Root proved the destination equals an unchanged, effective startup declaration in this origin. */
+  acceptedFallback?: boolean;
+  /** The prospective settled planner/conductor holder sets change, even if the raw role list shrinks. */
+  settledHolderChange?: boolean;
+  guard?: ReloadGuard;
+}
+export interface ConfigAuthorizationDecision { key: string; allowed: boolean; guarded: boolean; reason: string }
+
+/** Pure per-leaf authority. Schema validation and named-key selection precede this decision. */
+export function authorizeConfigLeaf(input: ConfigAuthorizationInput): ConfigAuthorizationDecision {
+  const { key, before, after } = input;
+  const result = (allowed: boolean, guarded: boolean, reason: string): ConfigAuthorizationDecision => ({ key, allowed, guarded, reason });
+  if (same(before, after)) return result(true, false, "unchanged");
+  const supplied = input.guard;
+  const guard = supplied && (key === supplied.key || key === `${supplied.store === "routing" ? "routing." : ""}${supplied.path.join(".")}`) ? supplied : undefined;
+  const machine = input.source === "config" && ALL_MACHINE_LOCAL.some(path => key === path || key.startsWith(`${path}.`));
+  const strings = (value: unknown): value is string[] => Array.isArray(value) && value.every(item => typeof item === "string");
+  const subset = (smaller: unknown, larger: unknown) => strings(larger) && (smaller === undefined || strings(smaller) && smaller.every(item => larger.includes(item)));
+  const numeric = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
+  let tightening = false;
+  if (guard?.floor !== undefined && same(after, guard.floor)) tightening = true;
+  if (key.startsWith("tasks.wip_limits.") && numeric(before) && numeric(after) && after <= before) tightening = true;
+  if (key === "routing.constraints.pii" && before === "off" && after === "local_only") tightening = true;
+  if (key === "routing.signals.pii_screen" && before === "off" && after === "local") tightening = true;
+  if (key === "routing.signals.pii_patterns" && strings(after) && (before === undefined || strings(before) && before.every(pattern => after.includes(pattern)))) tightening = true;
+  if (key.startsWith("roles.") && subset(after, before)) tightening = true;
+  if (key.startsWith("capabilities.") && strings(after) && (before === undefined || subset(after, before))) tightening = true;
+  if (["limits.sender_per_min", "limits.pair_per_min", "limits.important_per_hour"].includes(key)
+    && numeric(before) && numeric(after) && after > 0 && (before === 0 || after <= before)) tightening = true;
+  if (key === "limits.repeat_window_s" && numeric(before) && numeric(after) && after >= before) tightening = true;
+  if (key === "conductor.feed") {
+    const levels = ["off", "own", "all"];
+    if (typeof before === "string" && typeof after === "string" && levels.includes(before) && levels.includes(after) && levels.indexOf(after) < levels.indexOf(before)) tightening = true;
+  }
+  if (["inference.enabled", "inference.triage", "review.adaptive"].includes(key) && before === true && after === false) tightening = true;
+  if (key === "review.min_reviews" && numeric(before) && numeric(after) && after >= before) tightening = true;
+  if (tightening && !input.settledHolderChange) return result(true, false, "semantic tightening");
+  if (guard?.risk === "safe" && !machine) return result(true, false, "safe registered setting");
+  if (input.acceptedFallback && !machine) {
+    const person = input.authority === "terminal" || input.authority === "settings" && !!guard;
+    return result(person && input.confirmed === true, true, "restoring an unchanged effective startup value needs this key to be explicitly confirmed");
+  }
+  // Every other policy change is conservative: person intent never turns tracked or unknown code into host authority.
+  if (input.tracked !== false) return result(false, true, input.tracked ? "guarded source is tracked; retain the running value" : "guarded source trust is unknown; retain the running value");
+  if (input.authority === "ordinary") return result(false, true, "guarded change needs a selected setting or a confirmed terminal reload");
+  if (input.authority === "settings" && !guard) return result(false, true, "nonregistered policy requires a confirmed terminal reload");
+  if (input.confirmed !== true) return result(false, true, "guarded change needs explicit confirmation for this key");
+  return result(true, true, guard ? "confirmed registered setting" : "confirmed terminal reload");
+}
+type TrustLayer = ConfigLayer | { name: "routing.toml" | "routing.local.toml"; raw: Record<string, unknown> };
+type Authority = "ordinary" | "settings" | "terminal";
+type Check = (value: unknown, key: string) => void;
+const fail = (key: string, reason = "invalid value"): never => { throw new Error(`${key}: ${reason}`); };
+const object = (value: unknown, key: string): Record<string, unknown> => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return fail(key, "must be an object");
+  return value as Record<string, unknown>;
+};
+const bool: Check = (v, k) => { if (typeof v !== "boolean") fail(k, "must be a boolean"); };
+const text: Check = (v, k) => { if (typeof v !== "string" || v.length > 16_384 || /[\x00-\x1f\x7f]/.test(v)) fail(k, "must be bounded text"); };
+const number = (min = 0, max = Number.MAX_SAFE_INTEGER, integer = false): Check => (v, k) => {
+  if (typeof v !== "number" || !Number.isFinite(v) || v < min || v > max || integer && !Number.isSafeInteger(v)) fail(k, "number outside bounds");
+};
+const words = (values: readonly string[]): Check => (v, k) => { if (typeof v !== "string" || !values.includes(v)) fail(k, "unknown choice"); };
+const strings: Check = (v, k) => { if (!Array.isArray(v) || v.length > 1024) return fail(k, "must be a bounded string list"); for (const x of v) text(x, k); };
+const argv: Check = (v, k) => { strings(v, k); if (!(v as string[]).length || (v as string[]).some(x => !x)) fail(k, "must be a nonempty argv"); };
+const shapes = new WeakMap<Check, { fields?: Record<string, Check>; item?: Check; keys?: readonly string[] }>();
+const map = (check: Check, keys?: readonly string[]): Check => {
+  const fn: Check = (v, k) => { for (const [key, value] of Object.entries(object(v, k))) {
+    if (["__proto__", "constructor", "prototype"].includes(key) || keys && !keys.includes(key)) fail(`${k}.${key}`, "unknown key"); check(value, `${k}.${key}`);
+  } };
+  shapes.set(fn, { item: check, keys }); return fn;
+};
+const block = (schema: Record<string, Check>): Check => {
+  const fn: Check = (v, k) => { for (const [key, value] of Object.entries(object(v, k))) {
+    if (!Object.hasOwn(schema, key)) fail(`${k}.${key}`, "unknown key"); if (value !== undefined) schema[key]!(value, `${k}.${key}`);
+  } };
+  shapes.set(fn, { fields: schema }); return fn;
+};
+const peerMap = (check: Check) => map(check, SUPPORTED_PEERS);
+const timerSeconds = number(1, 2_147_483_647 / 1000), timerMinutes = number(1, 2_147_483_647 / 60_000);
+const schema: Record<string, Check> = {
+  watchdog_ms: number(1, 2_147_483_647), kimi_cmd: argv, qwen_cmd: argv, jcode_cmd: argv, codex_bin: text, jcode_home: text, jcode_provider_profile: text,
+  permission_modes: v => { permissionDefaults(v); }, protect_instruction_files: bool,
+  batch_max: number(1, 100_000, true), batch_ms: number(0, 2_147_483_647), queue_cap: number(1, 1_000_000, true),
+  memory: block({ enabled: bool, worker_url: text, inject_tokens: number(0, 1_000_000, true), brief_items: number(0, 10_000, true), native: bool,
+    short_ttl_days: number(1, 3650, true), sync_interval_min: number(0, 1440, true), suggest_edges: bool }),
+  roster: peerMap(bool), roles: map(strings), planner: words(PLANNER_PEERS), profile: words(["dev", "research", "writing", "general"]),
+  profile_overrides: (v, k) => { map(() => {})(v, k); const fields = object(v, k); for (const name of ["classes", "role_text", "catalog_roles"]) if (fields[name] !== undefined) map(() => {})(fields[name], `${k}.${name}`); resolveProfile("dev", v); },
+  catalog_roles: (v, k) => { map(() => {})(v, k); catalogAssignments(v); },
+  pii: block({ paths: strings }), data: block({ readonly: strings }),
+  text_projection: v => { projectionConfig(v); },
+  conductor: block({ feed: words(["own", "all", "off"]), approval_wait_s: number(0, 2_147_483_647 / 1000) }),
+  budget: block({ gate: number(0, 1), stale_min: timerMinutes, poll_min: timerMinutes, checkpoint_timeout_s: timerSeconds, kimi_tokens_5h: number(0), wait_max_min: number(0) }),
+  context: block({ gate: number(0, 1), stale_min: timerMinutes }),
+  inference: block({ enabled: bool, digest_min_items: number(1, 100_000, true), digest_min_chars: number(1, 10_000_000, true), triage: bool }),
+  omniroute: block({ urls: strings, api_key_file: text, access_hosts: strings, cf_client_id_file: text, cf_client_secret_file: text }),
+  pi: block({ enabled: bool, auto_start: bool, cmd: argv, backend: words(["auto", "dgx", "mlx"]), dgx_coding: text, dgx_fast: text, max_steps: number(1, 1_000_000, true) }),
+  mlx: block({ enabled: bool, provider: words(["legacy", "ollama"]), host: text, runtimeDir: text, modelPath: text, bin: text, port: number(1, 65535, true), model: text, sourceModel: text,
+    contextWindow: number(1), maxInputTokens: number(1), maxTokens: number(1), maxConcurrency: number(1, 1024, true) }),
+  local: block({ deny: strings, bash_network: (v, k) => { if (v !== "direct") bool(v, k); }, network_allow: strings, max_steps: number(1, 1_000_000, true), read_allow: strings }),
+  approvals: block({ timeout_s: timerSeconds, notify: bool }), tasks: block({ release_after_min: number(0), wip_limits: map(number(0, 32, true)) }),
+  task_sweep: (v, k) => { block({ enabled: bool, auto_reassign: bool, interval_s: timerSeconds, unaccepted_min: timerMinutes, idle_min: timerMinutes, review_min: timerMinutes, ready_min: timerMinutes, ladder_min: timerMinutes })(v, k); taskSweepConfig(v); },
+  checks: (v, k) => { for (const [key, value] of Object.entries(object(v, k))) {
+    if (value === undefined) continue;
+    if (key === "timeout_s") timerSeconds(value, `${k}.${key}`);
+    else if (key === "runner") words(["container"])(value, `${k}.${key}`);
+    else if (/^[a-z][a-z0-9_]{0,47}$/.test(key)) text(value, `${k}.${key}`); else fail(`${k}.${key}`, "unknown key");
+  } },
+  snapshots: block({ enabled: bool, keep: number(1, 1_000_000, true) }), research: block({ enabled: bool }), bench: block({ enabled: bool }),
+  peers: (v, k) => { map(block({ start_mode: words(["tui", "headless"]) }), ["pi", "codex", "kimi"])(v, k); peerStartConfig(v); },
+  terminal: (v, k) => { block({ open: strings })(v, k); terminalTemplate(object(v, k).open); },
+  limits: block({ sender_per_min: number(0), pair_per_min: number(0), important_per_hour: number(0), repeat_window_s: number(0) }),
+  review: block({ adaptive: bool, min_reviews: number(1, Number.MAX_SAFE_INTEGER, true) }), recovery: block({ auto_resume_after_crash: bool }),
+  capabilities: map(strings), coordination: words(["advisory", "turn-free"]), experiments: block({ stale_notices: words(["drop", "deliver"]) }),
+};
+export function validateRawConfig(raw: unknown): asserts raw is Record<string, unknown> { block(schema)(raw, "config"); }
+export function validateEffectiveConfig(value: unknown): asserts value is HubConfig {
+  const raw = { ...object(value, "config") };
+  delete raw.ignored; delete raw.retired; delete raw.permission_default_sources;
+  validateRawConfig(raw);
+  const profile = resolveProfile(raw.profile, raw.profile_overrides);
+  for (const key of Object.keys(object(raw.checks, "checks"))) if (!["timeout_s", "runner", ...CLASSES, ...Object.keys(profile.classes)].includes(key)) fail(`checks.${key}`, "unknown task class");
+  if (object(raw.mlx, "mlx").enabled === false && object(raw.pi, "pi").backend === "mlx") fail("pi.backend", "conflicts with disabled mlx");
+}
+
+const restart: Record<string, string> = {
+  "pi.dgx_coding": "Published Pi relay model catalogue requires a new daemon relay",
+  "pi.dgx_fast": "Published Pi relay model catalogue requires a new daemon relay",
+  "routing.pi": "Pi relay context and model publication are bound to the running relay",
+  memory: "Open memory consumers, selected profile, client and sync timer must be quiesced together",
+  omniroute: "Credentials and gateway clients are bound to relay ownership", mlx: "Model runtime ownership and device resources belong to this daemon",
+  checks: "Bounded runner and completion-check contracts are constructed together",
+  pii: "Existing native sessions retain their startup privacy boundary", data: "Existing native sessions retain their startup read-only policy",
+  "local.deny": "Existing native sessions retain their sandbox deny policy", "local.read_allow": "Existing native sessions retain their sandbox read grants",
+  "local.bash_network": "Existing sandbox and egress proxy contracts require a new instance", "local.network_allow": "Existing egress proxy ownership requires a new instance",
+  profile: "Session tool schemas and profile contracts are bound at startup", profile_overrides: "Session tool schemas and profile contracts are bound at startup",
+  text_projection: "Converter and cache ownership are bound at startup", terminal: "Terminal provider is supplied by the daemon lifecycle", bench: "Benchmark execution environment is selected before work starts",
+};
+const live = new Set(["permission", "roster", "roles", "planner", "conductor", "protect_instruction_files", "task_sweep", "capabilities", "research", "snapshots", "tasks.wip_limits", "approvals.notify"]);
+const nextMemory = new Set(["memory.inject_tokens", "memory.brief_items", "memory.suggest_edges"]);
+/** Closed top-level schema; leaf overrides retain the existing session/runtime boundaries. */
+export function configApply(key: string): ApplyRule {
+  const top = key.split(".")[0]!;
+  if (!(Object.hasOwn(schema, top) || top === "permission" || top === "routing")) return fail(key, "unknown configuration key");
+  if (top !== "routing" && top !== "permission" && key.includes(".")) {
+    const special: Record<string, readonly string[]> = {
+      task_sweep: ["enabled", "auto_reassign", "interval_s", "unaccepted_min", "idle_min", "review_min", "ready_min", "ladder_min"],
+      checks: ["timeout_s", "runner", ...CLASSES], terminal: ["open"],
+    };
+    let check = schema[top];
+    for (const [index, part] of key.split(".").slice(1).entries()) {
+      const shape = check && shapes.get(check);
+      if (shape?.fields) { if (!Object.hasOwn(shape.fields, part)) return fail(key, "unknown configuration key"); check = shape.fields[part]; }
+      else if (shape?.item) { if (shape.keys && !shape.keys.includes(part)) return fail(key, "unknown configuration key"); check = shape.item; }
+      else if (index === 0 && (special[top]?.includes(part) || top === "checks" && /^[a-z][a-z0-9_]{0,47}$/.test(part))) break;
+      else if (["permission_modes", "catalog_roles", "profile_overrides", "text_projection", "peers"].includes(top)) break;
+      else return fail(key, "unknown configuration key");
+    }
+  }
+  if (top === "routing" && !key.startsWith("routing.pi") && key !== "routing") {
+    return { applies: ["classes", "stay_switch", "signals", "constraints", "hub_routes", "max_switch_prefill_tokens"].includes(key.split(".")[1]!) ? "live" : "next use" };
+  }
+  if (nextMemory.has(key)) return { applies: "next use" };
+  for (const [path, reason] of Object.entries(restart)) if (key === path || key.startsWith(`${path}.`)) return { applies: "restart", reason };
+  if ([...live].some(path => key === path || key.startsWith(`${path}.`))) return { applies: "live" };
+  return { applies: "next use" };
+}
+const canonical = (v: unknown): unknown => Array.isArray(v) ? v.map(canonical) : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map(k => [k, canonical((v as Record<string, unknown>)[k])])) : v;
+const same = (a: unknown, b: unknown): boolean => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+const at = (raw: unknown, path: readonly string[]): unknown => path.reduce<unknown>((v, k) => v && typeof v === "object" && Object.hasOwn(v, k) ? (v as Record<string, unknown>)[k] : undefined, raw);
+export function configChanges(running: HubConfig, next: HubConfig): ConfigChange[] {
+  const changes: ConfigChange[] = [];
+  const walk = (before: unknown, after: unknown, key: string) => {
+    if (same(before, after)) return;
+    if (before && after && typeof before === "object" && typeof after === "object" && !Array.isArray(before) && !Array.isArray(after)) {
+      for (const child of new Set([...Object.keys(before), ...Object.keys(after)])) walk(at(before, [child]), at(after, [child]), key ? `${key}.${child}` : child);
+    } else changes.push({ key, before, after, ...configApply(key) });
+  };
+  const clean = (v: HubConfig) => Object.fromEntries(Object.entries(v).filter(([key]) => !["ignored", "retired", "permission_default_sources"].includes(key)));
+  walk(clean(running), clean(next), ""); return changes.sort((a, b) => a.key.localeCompare(b.key));
+}
+
+/** Legacy all-or-nothing authority helper; daemon reload uses authorizeConfigLeaf for scoped publication. */
+export function assertReloadTrust(cwd: string, layers: readonly TrustLayer[], previousLayers: readonly TrustLayer[], guardedRules: readonly ReloadGuard[], authority: Authority, defaults?: object): void {
+  const complete = [...layers, ...previousLayers.filter(prior => !layers.some(layer => layer.name === prior.name)).map(prior => ({ ...prior, raw: {} }))];
+  for (const layer of complete) {
+    const prior = previousLayers.find(p => p.name === layer.name)?.raw;
+    const routing = layer.name.endsWith(".toml");
+    const paths = new Map<string, { path: readonly string[]; floor?: unknown; machine: boolean; registered?: boolean }>();
+    if (!routing) for (const key of ALL_MACHINE_LOCAL) {
+      const path = key.split("."), value = at(layer.raw, path), old = at(prior, path);
+      const children = new Set([...(value && typeof value === "object" && !Array.isArray(value) ? Object.keys(value) : []), ...(old && typeof old === "object" && !Array.isArray(old) ? Object.keys(old) : [])]);
+      if (children.size) for (const child of children) paths.set(`${key}.${child}`, { path: [...path, child], machine: true });
+      else paths.set(key, { path, machine: true });
+    }
+    for (const rule of guardedRules) if (rule.risk === "raises" && rule.store === (routing ? "routing" : "config")) {
+      const key = rule.path.join(".");
+      paths.set(key, { path: rule.path, floor: rule.floor, registered: true, machine: !routing && ALL_MACHINE_LOCAL.some(p => key === p || key.startsWith(`${p}.`)) });
+    }
+    for (const [key, guard] of paths) {
+      const value = at(layer.raw, guard.path), old = at(prior, guard.path);
+      if (same(value, old)) continue;
+      const inherit = guard.registered && value === undefined && old !== undefined;
+      if (!inherit && guard.machine && defaults && same(value, at(defaults, guard.path))) continue;
+      // Removal can expose a lower layer: registry inherit is guarded just like a direct raise.
+      if (!guard.machine && value !== undefined && same(value, guard.floor)) continue;
+      // Empty machine-local declarations choose no program/path and are stripped at startup.
+      if (!inherit && guard.machine && (value === undefined || value === null || value === "" || Array.isArray(value) && !value.length)) continue;
+      let tracked = configTracked(cwd, layer.name);
+      if (!guard.machine && tracked === undefined && !configRepositoryPresent(cwd)) tracked = false;
+      if (tracked !== false) fail(`${layer.name}:${key}`, tracked ? "guarded change is tracked" : "guarded source trust is unknown");
+      if (guard.machine && authority === "settings" && !guard.registered) fail(`${layer.name}:${key}`, "non-editable machine policy requires terminal authority");
+      if (value !== undefined && guard.floor !== undefined && same(value, guard.floor)) continue;
+      if (authority === "ordinary") fail(`${layer.name}:${key}`, "guarded change requires settings or terminal authority");
+    }
+  }
+}