@staix/agent-hub 0.12.32 → 0.12.34

package/src/cli/upgrade.ts

@@ -1,3 +1,4 @@
+import { definitionOf } from "../adapters/registry.ts";
 import { LIVE_TEST_PERSON_REFUSAL } from "./identity.ts";
 import { checkedSessionPath } from "./recovery-session-file.ts";
 import { canChooseFresh, decodeRestoreReceipt, restoreReceiptStatus } from "./upgrade-restore-state.ts";
@@ -32,6 +33,8 @@ export interface Inspection {
   blockers: string[];
   /** #215: for a stopped runtime, the operation whose committed restart snapshot its state dir holds (unreleased). */
   snapshot?: string;
+  /** The runtime may be positively stopped while its restart snapshot remains unreadable; never claim ownership. */
+  snapshotError?: { code: "recovery_deferred_hub"; message: string };
 }
 export interface PlannedProject {
   project: Project;
@@ -335,7 +338,7 @@ function missingRepair(op: RecoveryOperation, progress: ProjectProgress, peer: s
 function failedPeers(op: RecoveryOperation, progress: ProjectProgress, live: Record<string, Inspection | undefined> = {}): string[] {
   const planned = op.plan.projects.find((p) => p.project.id === progress.id);
   return Object.entries(progress.terminals).filter(([key, value]) => key.startsWith("restored:") && canChooseFresh(value)).map(([key]) => key.slice("restored:".length))
-    .filter((peer) => peer !== "pi" && ((!Object.hasOwn(progress.reattachments ?? {}, peer) && !Object.hasOwn(progress.repairedSessions ?? {}, peer)) || missingRepair(op, progress, peer)) && !progress.fresh?.[peer] && (!planned?.freshStart?.includes(peer) || missingRepair(op, progress, peer)) && !plannedAttached(op, progress, peer, live));
+    .filter((peer) => definitionOf(peer)?.session.personFresh === true && ((!Object.hasOwn(progress.reattachments ?? {}, peer) && !Object.hasOwn(progress.repairedSessions ?? {}, peer)) || missingRepair(op, progress, peer)) && !progress.fresh?.[peer] && (!planned?.freshStart?.includes(peer) || missingRepair(op, progress, peer)) && !plannedAttached(op, progress, peer, live));
 }
 
 /** Read-only scope classification; it confers no delegation authority. */
@@ -361,7 +364,7 @@ function plannedAttached(op: RecoveryOperation, progress: ProjectProgress, peer:
     ? resolveAcceptedBinding(planned, progress, peer as RecoveryNativePeer)
     : (planned?.terminals as { peer: string; sessionId: string }[] | undefined)?.find((t) => t.peer === peer);
   const current = state?.state === "running" ? state.peers.find((p) => p.id === peer && p.state !== "offline") : undefined;
-  return !!binding && (peer === "codex" ? current?.threadId : current?.sessionId) === binding.sessionId;
+  return !!binding && current?.[definitionOf(peer)?.session.idField ?? "sessionId"] === binding.sessionId;
 }
 
 /** Registry reads for planning must not create a registry or run migrations. */
@@ -442,7 +445,7 @@ function validateReceipt(id: string, op: RecoveryOperation): void {
     if (progress.reattachments === undefined) continue;
     if (!object(progress.reattachments)) throw new Error("invalid reattachment markers");
     for (const [peer, marker] of Object.entries(progress.reattachments)) {
-      if (!["codex", "pi", "claude"].includes(peer) || !object(marker) || Object.keys(marker).some(key => !["state", "at", "cause", "binding"].includes(key)) ||
+      if (definitionOf(peer)?.session.launchRecord !== true || !object(marker) || Object.keys(marker).some(key => !["state", "at", "cause", "binding"].includes(key)) ||
           !["ready", "attempted"].includes(String(marker.state)) || marker.cause !== "detached after restore" || typeof marker.at !== "number" || !Number.isFinite(marker.at) || marker.at < 0) throw new Error("invalid reattachment marker");
       const receipt = decodeRestoreReceipt({ state: "done", binding: marker.binding });
       if (receipt?.state !== "done" || receipt.binding.peer !== peer || receipt.binding.projectRoot !== op.plan.projects[index]?.project.root) throw new Error("reattachment binding does not match its peer and project");
@@ -464,7 +467,7 @@ function validateReceipt(id: string, op: RecoveryOperation): void {
   }
   if (op.blockedReattachment !== undefined) {
     const selected = op.blockedReattachment;
-    if (!object(selected) || Object.keys(selected).some(key => !["projectId", "peer"].includes(key)) || typeof selected.projectId !== "string" || !["codex", "pi", "claude"].includes(String(selected.peer)) ||
+    if (!object(selected) || Object.keys(selected).some(key => !["projectId", "peer"].includes(key)) || typeof selected.projectId !== "string" || definitionOf(String(selected.peer))?.session.launchRecord !== true ||
         !op.projects.some(project => project.id === selected.projectId && Object.hasOwn(project.reattachments ?? {}, selected.peer))) throw new Error("invalid blocked reattachment selector");
   }
 }
@@ -792,7 +795,7 @@ export async function reattachRecovery(id: string, peer: string, driver: Recover
   let op = readOperation<RecoveryOperation>(id, home);
   validateReceipt(id, op);
   const selection = () => {
-    if (!["codex", "pi", "claude"].includes(peer) || op.phase !== "blocked" || op.disposition || op.final || op.blockedReattachment?.peer !== peer) throw new Error("reattach is available only for the peer named by a blocked reattachment receipt");
+    if (definitionOf(peer)?.session.launchRecord !== true || op.phase !== "blocked" || op.disposition || op.final || op.blockedReattachment?.peer !== peer) throw new Error("reattach is available only for the peer named by a blocked reattachment receipt");
     const progress = op.projects.find(project => project.id === op.blockedReattachment!.projectId);
     const planned = op.plan.projects.find(project => project.project.id === progress?.id);
     const native = peer as RecoveryNativePeer;
@@ -817,7 +820,7 @@ export async function reattachRecovery(id: string, peer: string, driver: Recover
     };
     await target();
     attempted = true;
-    await driver.restore(planned, progress, op, native === "claude" ? "claude" : "native", save, native);
+    await driver.restore(planned, progress, op, definitionOf(native)?.transport === "claude-channel" ? "claude" : "native", save, native);
     // A done receipt is written by the runtime only after authenticated attachment and exact settlement.
     // Inspection peers may be unavailable; do not invent an attachment from a test or a stale status projection.
     const restored = decodeRestoreReceipt(progress.terminals[`restored:${native}`]);
@@ -913,7 +916,7 @@ export async function disposeRecovery(id: string, choice: { fresh: string } | {
     const next = nextActionsText(op, live);
     if ("fresh" in choice) {
       // `ahub pi` sends no fresh flag, and a restored hub refills a Pi start from its recorded resume (daemon startPeer).
-      if (choice.fresh === "pi") throw new Error(`pi: --fresh-session is not supported: a restored hub resumes Pi's recorded session, so a fresh one cannot be guaranteed; ${op.plan.projects.map(planned => piArchiveExit(planned, recoveryCommand(op, "dispose", STOP))).join("; ")}; ${next}`);
+      if (definitionOf(choice.fresh)?.session.personFresh === false) throw new Error(`pi: --fresh-session is not supported: a restored hub resumes Pi's recorded session, so a fresh one cannot be guaranteed; ${op.plan.projects.map(planned => piArchiveExit(planned, recoveryCommand(op, "dispose", STOP))).join("; ")}; ${next}`);
       if (op.disposition) throw new Error(`a stop-and-archive of this operation is partway; ${next}`);
       if (!targetReadsWaivers(op)) throw new Error(`--fresh-session is not available: target ${op.plan.version} cannot read recovery waivers, so it could not release a new session; ${next}`);
       // The new session is launched by resume, so it helps only where resume can get past what is live.

package/src/hub/budget.ts

@@ -1,3 +1,4 @@
+import { definitionOf } from "../adapters/registry.ts";
 import { Database } from "bun:sqlite";
 import type { PeerId } from "./envelope.ts";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
@@ -70,8 +71,6 @@ const WAIT_NOTE = "; keeps its work:";
 const WAITED_NOTE = "; waited, then the reset moved to";
 const waitedNote = (min: number, max: number) => `${WAITED_NOTE} ${min} min, beyond wait_max_min ${max}`;
 const FALLBACK_WINDOW_MINS = 300;
-/** Peers the coordinator never pauses: the local worker has no quota. */
-const EXEMPT = new Set<PeerId>(["local", "user", "hub"]);
 
 /**
  * Budget relay. Readings come from the adapters (Codex rate limits, Claude's status line, Kimi tokens) or from
@@ -156,7 +155,10 @@ export class Budget {
   /** `hard`: the peer cannot run another turn (its provider refused one), so there is nobody to ask for a checkpoint. */
   /** `at`: when the numbers were measured, for sources that arrive through a file (a leftover file is not a fresh reading). */
   report(peer: PeerId, windows: UsageWindow[], hard = false, at = this.now()): void {
-    if (EXEMPT.has(peer) || this.closed) return;
+    // Execution-budget instrumentation is independent of native quota accounting.
+    // Explicit quota exemption or absent budget metadata exempts registered kinds; external ids keep accounting.
+    const adapter = definitionOf(peer);
+    if (peer === "user" || peer === "hub" || adapter && (!adapter.budget || adapter.budget.quotaExempt === true) || this.closed) return;
     // An override ignores soft readings, not a provider that has actually refused another turn.
     if (hard && this.ignoreUntil.delete(peer)) {
       try { this.hooks.notify(`budget: ${peer} provider refused again; budget override ended`); } catch { /* a notice cannot prevent the hard pause */ }
@@ -356,30 +358,4 @@ export class Budget {
   }
 }
 
-/** Codex `rateLimits` snapshot (account/rateLimits/read, account/rateLimits/updated) -> windows. */
-export function codexWindows(rateLimits: any): UsageWindow[] {
-  const out: UsageWindow[] = [];
-  // The slot decides (primary = short window, secondary = long one) and the duration overrides it when present:
-  // readings are keyed by window id, so two windows must never both come out as "5h".
-  for (const [w, slot] of [[rateLimits?.primary, "5h"], [rateLimits?.secondary, "week"]] as const) {
-    if (!w || typeof w.usedPercent !== "number") continue;
-    const mins = typeof w.windowDurationMins === "number" ? w.windowDurationMins : undefined;
-    const id = mins === undefined ? slot : mins > 600 ? "week" : "5h";
-    if (out.some((o) => o.id === id)) continue; // both slots claim the same window: keep the first, never overwrite
-    out.push({ id, used: w.usedPercent / 100, ...(w.resetsAt ? { resetsAt: w.resetsAt * 1000 } : {}), ...(mins ? { windowMins: mins } : {}), source: "codex rateLimits" });
-  }
-  if (rateLimits?.rateLimitReachedType && !out.some((w) => w.used >= 1)) out.push({ id: "5h", used: 1, source: `codex ${rateLimits.rateLimitReachedType}` });
-  return out;
-}
-
-/** Claude Code status line `rate_limits` -> windows. */
-export function claudeWindows(rateLimits: any): UsageWindow[] {
-  const out: UsageWindow[] = [];
-  for (const [key, id, mins] of [["five_hour", "5h", 300], ["seven_day", "week", 10_080]] as const) {
-    const w = rateLimits?.[key];
-    if (!w || typeof w.used_percentage !== "number") continue;
-    const resets = Number(w.resets_at);
-    out.push({ id, used: w.used_percentage / 100, ...(resets ? { resetsAt: resets < 1e12 ? resets * 1000 : resets } : {}), windowMins: mins, source: "claude status line" });
-  }
-  return out;
-}
+export { codexWindows, claudeWindows } from "../adapters/definitions/native-quota.ts";

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;
@@ -273,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 {
@@ -296,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);
@@ -314,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;
@@ -341,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();
@@ -532,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;
@@ -602,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);
@@ -638,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);
@@ -681,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. */
@@ -696,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();
@@ -709,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]!;
@@ -796,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);
   }
@@ -1060,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/conductor.ts

@@ -1,10 +1,11 @@
+import { definitionOf, SUPPORTED_PEERS } from "../adapters/registry.ts";
 import { Database } from "bun:sqlite";
 import type { Task } from "./board.ts";
 import { CONDUCTOR_TOOL_NAMES } from "./hub-tools.ts";
 import { HUB, USER } from "./envelope.ts";
 import { OWNERSHIP_EVENTS, type TaskAssignmentRole } from "./tasks.ts";
 import { PreEffectToolRefusal } from "./tool-refusal.ts";
-import { isStartablePeer, type StartablePeer, type StartMode } from "./start-mode.ts";
+import type { StartMode } from "./start-mode.ts";
 import type { HubEvent } from "./events.ts";
 import type { SupervisionFeed } from "./supervision.ts";
 import type { Budget } from "./budget.ts";
@@ -103,6 +104,8 @@ export class ConductorHolds {
   close(): void { this.db.close(); }
 }
 
+type StartablePeer = typeof SUPPORTED_PEERS[number];
+
 export type ConductorStart = { peer: StartablePeer; mode: "headless" } | { peer: "claude" | "codex" | "pi"; mode: "tui"; command: string };
 /**
  * What a conductor's start of `peer` is (#269): the peer's own start mode, which a person sets. A `mode` argument may
@@ -111,10 +114,11 @@ export type ConductorStart = { peer: StartablePeer; mode: "headless" } | { peer:
 export function conductorStart(peer: unknown, mode: unknown, preview: (peer: "claude" | "codex" | "pi") => string, preEffect: boolean, startMode: (peer: StartablePeer) => StartMode): ConductorStart {
   const refuse = (text: string) => new (preEffect ? PreEffectToolRefusal : Error)(text);
   if (mode !== undefined && mode !== "headless" && mode !== "tui") throw refuse("mode must be headless or tui");
-  if (!isStartablePeer(peer)) throw refuse("only claude, codex, kimi, pi and local, plus opt-in qwen/jcode, may be started by the conductor");
-  const own = startMode(peer);
+  if (!(typeof peer === "string" && definitionOf(peer)?.start.conductorStartable)) throw refuse("only claude, codex, kimi, pi and local, plus opt-in qwen/jcode, may be started by the conductor");
+  const selected = peer as StartablePeer;
+  const own = startMode(selected);
   if (mode !== undefined && mode !== own) throw refuse(`${peer} starts ${own} here; a person sets a start mode (ahub settings), the conductor cannot choose one`);
-  return own === "tui" ? { peer: peer as "claude" | "codex" | "pi", mode: "tui", command: preview(peer as "claude" | "codex" | "pi") } : { peer, mode: "headless" };
+  return own === "tui" ? { peer: peer as "claude" | "codex" | "pi", mode: "tui", command: preview(peer as "claude" | "codex" | "pi") } : { peer: selected, mode: "headless" };
 }
 
 const numberOrNull = (v: unknown): number | null => typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null;

package/src/hub/config-apply.ts

@@ -1,6 +1,6 @@
 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 { ADAPTERS, SUPPORTED_PEERS, PLANNER_PEERS, START_MODE_PEERS } from "../adapters/registry.ts";
 import { CLASSES } from "./board.ts";
 import { permissionDefaults } from "./permission-mode.ts";
 import { peerStartConfig, terminalTemplate } from "./start-mode.ts";
@@ -103,7 +103,9 @@ const block = (schema: Record<string, Check>): Check => {
 };
 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 nativeValidators = { bool, text, strings, argv, number, words, block };
 const schema: Record<string, Check> = {
+  ...Object.assign({}, ...ADAPTERS.map(adapter => adapter.configuration?.schema?.(nativeValidators) ?? {})),
   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),
@@ -119,11 +121,9 @@ const schema: Record<string, Check> = {
   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)) }),
+  approvals: block({ timeout_s: timerSeconds, notify: bool }), tasks: block({ release_after_min: number(0), wip_limits: map(number(0, 32, true)), escalate_after: number(1, 10, 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;
@@ -132,7 +132,7 @@ const schema: Record<string, Check> = {
     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); },
+  peers: (v, k) => { map(block({ start_mode: words(["tui", "headless"]) }), START_MODE_PEERS)(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 }),
@@ -145,23 +145,19 @@ export function validateEffectiveConfig(value: unknown): asserts value is HubCon
   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");
+  for (const adapter of ADAPTERS) adapter.configuration?.validateEffective?.(raw, fail);
 }
 
 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",
+  ...Object.assign({}, ...ADAPTERS.map(adapter => adapter.configuration?.restartReasons ?? {})),
   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 live = new Set(["permission", "roster", "roles", "planner", "conductor", "protect_instruction_files", "task_sweep", "capabilities", "research", "snapshots", "tasks.wip_limits", "tasks.escalate_after", "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 {
@@ -182,7 +178,7 @@ export function configApply(key: string): ApplyRule {
       else return fail(key, "unknown configuration key");
     }
   }
-  if (top === "routing" && !key.startsWith("routing.pi") && key !== "routing") {
+  if (top === "routing" && !ADAPTERS.some(adapter => Object.keys(adapter.configuration?.restartReasons ?? {}).some(prefix => prefix.startsWith("routing.") && key.startsWith(prefix))) && 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" };

package/src/hub/config-reload.ts

@@ -1,3 +1,4 @@
+import { ADAPTERS } from "../adapters/registry.ts";
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -66,15 +67,19 @@ function validateRoutingRaw(value: unknown): void {
       const entry = table(item, `${key}.${name}`); text(entry[required], `${key}.${name}.${required}`); openValue(entry, `${key}.${name}`);
     }
   };
+  const nativeValidators = { bool, text, strings, argv: strings,
+    number: (min = 1, max = Number.MAX_SAFE_INTEGER, _integer = true) => (v: unknown, k: string) => numeric(v, k, min, max),
+    words: (values: readonly string[]) => (v: unknown, k: string) => choice(v, k, values),
+    block: (fields: Record<string, (v: unknown, k: string) => void>) => (v: unknown, k: string) => closed(v, k, fields),
+  };
   closed(value, "routing", {
-    local: (v, k) => closed(v, k, { route: text, fixed_model: text }),
+    ...Object.assign({}, ...ADAPTERS.map(adapter => adapter.configuration?.routingSchema?.(nativeValidators) ?? {})),
     targets: (v, k) => switchyard(v, k, "id"), routes: (v, k) => switchyard(v, k, "type"),
     // parseRouting delegates these tables to the existing parseHubRoutes validator.
     hub_routes: (v, k) => { table(v, k); },
     stay_switch: (v, k) => choice(v, k, ["off", "shadow", "enforce"]), max_switch_prefill_tokens: numeric,
     signals: (v, k) => closed(v, k, { pii_patterns: strings, long_context_tokens: numeric, pii_screen: (x, p) => choice(x, p, ["off", "local"]) }),
     constraints: (v, k) => closed(v, k, { pii: (x, p) => choice(x, p, ["local_only", "off"]), long_context: (x, p) => choice(x, p, ["skip_local", "off"]), budget_paused: (x, p) => choice(x, p, ["skip_peer", "off"]) }),
-    pi: (v, k) => closed(v, k, { dgx_max_context_tokens: numeric, mlx_max_context_tokens: numeric, efficient_wait_ms: (x, p) => numeric(x, p, 0, 119999) }),
     classes: (v, k) => { for (const [name, item] of Object.entries(table(v, k))) {
       if (!(CLASSES as readonly string[]).includes(name)) bad(`${k}.${name}`);
       closed(item, `${k}.${name}`, { peers, escalate_to: peers, route: text, fixed_model: text, local_allowed: bool, pi_backend: (x, p) => choice(x, p, ["dgx", "mlx"]) });

package/src/hub/context-window.ts

@@ -1,3 +1,6 @@
+import { nonnegative, positive } from "../adapters/definitions/native-context.ts";
+export { claudeContext, codexContext, acpContext } from "../adapters/definitions/native-context.ts";
+
 /** Native active-context occupancy, separate from accumulated billable usage (#185). */
 export interface ContextReading {
   source: "claude_statusline" | "codex_token_usage" | "acp_usage_update";
@@ -17,33 +20,6 @@ export interface ContextView {
 }
 export interface ContextConfig { gate: number; stale_min: number }
 export const DEFAULT_CONTEXT: ContextConfig = { gate: 0, stale_min: 30 };
-const nonnegative = (n: unknown): n is number => typeof n === "number" && Number.isFinite(n) && n >= 0;
-const positive = (n: unknown): n is number => nonnegative(n) && n > 0;
-const record = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v);
-const object = (v: unknown): Record<string, unknown> => record(v) ? v : {};
-export function claudeContext(value: unknown, sessionId: string, measuredAt: number): ContextReading {
-  const c = object(value);
-  const current = object(c.current_usage);
-  const parts = [current.input_tokens, current.cache_creation_input_tokens, current.cache_read_input_tokens];
-  const window = positive(c.context_window_size) ? c.context_window_size : null;
-  const sum = c.current_usage != null && parts.every(nonnegative) ? parts.reduce<number>((sum, n) => sum + (n as number), 0) : null;
-  const tokens = nonnegative(sum) ? sum : null;
-  const used = record(c.current_usage) && tokens !== null && nonnegative(c.used_percentage) && c.used_percentage <= 100 && window !== null ? c.used_percentage / 100 : null;
-  return { source: "claude_statusline", sessionId, measuredAt, tokens, window, used };
-}
-export function codexContext(value: unknown, sessionId: string, measuredAt: number): ContextReading {
-  const c = object(value), last = object(c.last);
-  const window = positive(c.modelContextWindow) ? c.modelContextWindow : null;
-  const tokens = nonnegative(last.totalTokens) ? last.totalTokens : null;
-  return { source: "codex_token_usage", sessionId, measuredAt, tokens, window, used: tokens !== null && window !== null ? Math.min(1, tokens / window) : null };
-}
-/** An ACP `usage_update` of the `{ used, size }` shape (Kimi 2.x): context occupancy, not consumption (#167, #285). */
-export function acpContext(usage: { used: number; size: number }, sessionId: string, measuredAt: number): ContextReading {
-  const window = positive(usage.size) ? usage.size : null;
-  const tokens = nonnegative(usage.used) ? usage.used : null;
-  // If a report ever shows used > size, the fraction clamps so a bar renders; tokens keeps the reported number.
-  return { source: "acp_usage_update", sessionId, measuredAt, tokens, window, used: tokens !== null && window !== null ? Math.min(1, tokens / window) : null };
-}
 export const unknownContext = (): ContextView => ({ source: null, measuredAt: null, tokens: null, window: null, used: null, freshness: "unknown" });
 /** Invalid/stale readings hide the value but never rearm a threshold already crossed. */
 export class ContextWindows {

package/src/hub/control-client.ts

@@ -8,7 +8,7 @@ export function stateDirFor(cwd: string): string {
 
 /** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets; 13 = turn-free facts (`facts` with tool, session and transcript binding, `silenced`) and per-recipient send results (issue #108). 14 = native context-window status and session-bound context checkpoint request ids (issue #185). 15 = conductor tools and permission deadlines/closed events (issues #190, #194). 16 = a Claude session without channel evidence: hello `channel: false` and `inbox` (issue #205). The plugin is installed apart from the daemon, so they can drift. */
 export const PROTOCOL = 16;
-export const DAEMON_FEATURES = ["task_cancel"] as const;
+export const DAEMON_FEATURES = ["task_cancel", "recovery_deferred_hub"] as const;
 /** Protocols a current coordinator may authenticate while upgrading a running source. */
 export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, 15, PROTOCOL] as const;