@staix/agent-hub 0.34.1 → 0.35.0

package/src/adapters/kimi-wire-usage.ts

@@ -1,4 +1,4 @@
-import { closeSync, fstatSync, lstatSync, openSync, readSync, readdirSync, statSync } from "node:fs";
+import { closeSync, fstatSync, lstatSync, openSync, readSync as fsReadSync, readdirSync, statSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { join, sep } from "node:path";
 import { realPath } from "../hub/project.ts";
@@ -43,6 +43,10 @@ export type KimiWireRead =
   | { status: "ok"; rows: KimiWireRow[]; /** bytes remain unread because of the per-call bound: read again */ more: boolean }
   | { status: "unknown"; reason: KimiWireReason };
 
+export type KimiWireSlice =
+  | { status: "ok"; rows: KimiWireRow[]; more: boolean; commit(): void }
+  | { status: "unknown"; reason: KimiWireReason };
+
 /** What counts against `budget.kimi_tokens_5h`: new input, cache writes and output. Cache reads are recorded and shown, never counted. */
 export function kimiCountedTokens(row: Pick<KimiWireRow, "inputOther" | "inputCacheCreation" | "output">): number {
   return row.inputOther + row.inputCacheCreation + row.output;
@@ -88,6 +92,8 @@ export class KimiWireReader {
   private dir: string | undefined;
   private files = new Map<string, FileState>();
   private broken: KimiWireReason | undefined;
+  private bytes = 0;
+  private discovery = 0;
 
   constructor(options: KimiWireOptions) {
     this.home = options.home;
@@ -95,15 +101,34 @@ export class KimiWireReader {
     this.chunk = Math.max(LINE_CAP * 2, options.maxBytes ?? DEFAULT_CHUNK);
   }
 
+  private readBytes(fd: number, buffer: Buffer, offset: number, length: number, position: number): number {
+    const read = fsReadSync(fd, buffer, offset, length, position);
+    this.bytes += read;
+    return read;
+  }
+
   /** The rows written since the last successful read, sub-agents included. */
   read(): KimiWireRead {
+    const slice = this.readSlice();
+    if (slice.status === "unknown") return slice;
+    const { commit, ...read } = slice;
+    commit();
+    return read;
+  }
+
+  /** Numeric I/O observations for deterministic benchmarks; no path, row or native text. */
+  stats(): { bytes: number; discovery: number } { return { bytes: this.bytes, discovery: this.discovery }; }
+
+  /** A successful slice commits its offsets only after the caller has committed every row it returned. */
+  readSlice(): KimiWireSlice {
     if (this.broken) return { status: "unknown", reason: this.broken };
+    this.bytes = 0; this.discovery = 0;
     try {
-      const dir = this.resolve();
+      const dir = this.resolve(); this.discovery++;
       const next = new Map<string, FileState>();
       const rows: KimiWireRow[] = [];
       let more = false, budget = this.chunk;
-      const agents = this.agents(dir);
+      const agents = this.agents(dir); this.discovery++;
       for (const name of this.files.keys()) if (!agents.has(name)) throw new Unknown("missing");
       for (const [name, wire] of agents) {
         const previous = this.files.get(name);
@@ -114,8 +139,8 @@ export class KimiWireReader {
         budget -= result.read;
         more ||= result.more;
       }
-      this.files = next;
-      return { status: "ok", rows, more };
+      let committed = false;
+      return { status: "ok", rows, more, commit: () => { if (!committed) { this.files = next; committed = true; } } };
     } catch (error) {
       const reason: KimiWireReason = error instanceof Unknown ? error.reason : "io-error";
       if (!TRANSIENT.has(reason)) this.broken = reason; // the log no longer matches what was counted: stays unknown for this session
@@ -161,7 +186,7 @@ export class KimiWireReader {
       const buffer = Buffer.allocUnsafe(stat.size);
       let got = 0;
       while (got < stat.size) {
-        const n = readSync(fd, buffer, got, stat.size - got, got);
+        const n = this.readBytes(fd, buffer, got, stat.size - got, got);
         if (n <= 0) break;
         got += n;
       }
@@ -206,7 +231,7 @@ export class KimiWireReader {
       let got = 0;
       while (got < length) {
         let n: number;
-        try { n = readSync(fd, buffer, got, length - got, start + got); } catch { throw new Unknown("io-error"); }
+        try { n = this.readBytes(fd, buffer, got, length - got, start + got); } catch { throw new Unknown("io-error"); }
         if (n <= 0) throw new Unknown("shrunk");
         got += n;
       }
@@ -234,7 +259,7 @@ export class KimiWireReader {
       let got = 0;
       while (got < length) {
         let n: number;
-        try { n = readSync(fd, buffer, got, length - got, state.offset + got); } catch { throw new Unknown("io-error"); }
+        try { n = this.readBytes(fd, buffer, got, length - got, state.offset + got); } catch { throw new Unknown("io-error"); }
         if (n <= 0) break;
         got += n;
       }

package/src/adapters/local-worker.ts

@@ -1,4 +1,7 @@
+import type { ModelOverrideSelection } from "./registry-types.ts";
+import { isNativeModelToken } from "./model-token.ts";
 import { isReviewObserverExcluded, reviewCaptureExcluded } from "../hub/memory-policy.ts";
+import { DecisionPolicyChangedError, type DecisionHost } from "../models/route/decision.ts";
 import { HubRouteRuntime, type RouteEvent, type AdvisorEvent } from "../models/route/runtime.ts";
 import type { HubRoute } from "../models/route/config.ts";
 import type { RouteLabelEvent, RouteTurnOutcome } from "../models/route/labels.ts";
@@ -21,6 +24,8 @@ import type { ExecutionBudgetDecision } from "../hub/execution-budget.ts";
 import type { OwnedInputContext, OwnedInputObserver } from "./claude-print-child.ts";
 
 export interface LocalOptions {
+  /** Host-only choice sampled once at the next turn/review boundary. */
+  getModelOverride?: () => ModelOverrideSelection;
   profile?: import("../hub/profiles.ts").ProfileSelection;
   sdlcStages?: readonly string[];
   sdlcCriteria?: boolean;
@@ -33,6 +38,9 @@ export interface LocalOptions {
   /** Model alias sent straight to OmniRoute when no hub route is active or its call fails. */
   fixedModel: string;
   hubRoutes?: () => Record<string, HubRoute>;
+  /** Current host public-view screen for bounded decision evidence; absent means no text is released. */
+  routeEvidencePublic?: (text: string) => boolean;
+  routeDecisionContext?: DecisionHost["decisionContext"];
   /** routing.toml `stay_switch` for hub stage routes (#197). */
   staySwitch?: () => StaySwitchPolicy | undefined;
   onRoute?: (event: RouteEvent) => void;
@@ -116,6 +124,7 @@ export class LocalPeer extends BasePeer {
   private readonly warnedLegacyRoutes = new Set<string>();
   private routeEnvs: Envelope[] = [];
   private routePii = false;
+  private routeReviewScope: { excluded: boolean } | undefined;
   private routeTask?: number;
   private labelTurnId?: string;
   private turn = 0; // generation guard, as in acp.ts: a turn aborted by the watchdog must not touch the next one
@@ -153,6 +162,10 @@ export class LocalPeer extends BasePeer {
         return result;
       },
       onCampus: () => this.opts.omni.onCampus(),
+      decisionContext: () => this.decisionContext(),
+      publicDecisionText: text => this.opts.routeEvidencePublic?.(text) === true,
+      admitDecision: () => this.requireBudget(this.routeEnvs, "model_calls"),
+      onDecisionIssue: reason => this.opts.log?.(`decision route observation ${reason}; using the original heuristic; check adec serve and routing.toml policy settings, then retry`),
       staySwitch: () => this.opts.staySwitch?.(),
       onRoute: event => this.opts.onRoute?.(event),
       onAdvisor: event => this.opts.onAdvisor?.(event),
@@ -161,6 +174,13 @@ export class LocalPeer extends BasePeer {
     this.sandboxProfile = profile(opts.cwd, opts.tools.bashNetwork ?? false, opts.tools.readAllow, opts.tools.deny, opts.tools.readOnly);
   }
 
+  private decisionContext(): { pii: boolean; private: boolean; excluded: boolean } {
+    const current = this.opts.routeDecisionContext?.();
+    if (this.opts.routeDecisionContext && (!current || typeof current.private !== "boolean" || typeof current.excluded !== "boolean" || current.pii !== undefined && typeof current.pii !== "boolean")) throw new DecisionPolicyChangedError();
+    return { pii: this.routePii || current?.pii === true, private: this.routeEnvs.some(env => env.private === true) || current?.private === true,
+      excluded: this.routeEnvs.some(env => remoteEnvelope(env) || isReviewObserverExcluded(env)) || this.routeReviewScope?.excluded === true || current?.excluded === true };
+  }
+
   recoveryMetadata(): Record<string, unknown> {
     return { launch: { kind: "local", cwd: this.opts.cwd, model: this.opts.fixedModel, ...(this.opts.route ? { route: this.opts.route } : {}) }, sessionId: this.sessionId };
   }
@@ -202,11 +222,22 @@ export class LocalPeer extends BasePeer {
     this.activeDeliveryId = deliveryId;
     this.abort = new AbortController();
     this.setState("busy");
+    let selected: ModelOverrideSelection | undefined, modelFailure: Error | undefined;
+    try {
+      selected = this.opts.getModelOverride?.();
+      if (selected?.model !== undefined && !isNativeModelToken(selected.model)) throw new Error("invalid model");
+    } catch { modelFailure = new Error("runtime model selection unavailable; check the peer model setting and retry"); }
+    let modelApplied = false;
+    const captured = selected;
+    const selection = captured && { model: captured.model, applied: () => {
+      if (modelApplied || turn !== this.turn) return;
+      modelApplied = true; try { captured.applied(); } catch { /* Status acknowledgement is not model authority. */ }
+    } };
     if (deliveryId) this.delivery({ id: deliveryId, state: "accepted" });
     // The turn works on its own message list and joins the history only as a whole, so a failed or aborted turn can
     // never leave a tool call without its result (strict servers reject that history forever after).
     const msgs: ChatMessage[] = [{ role: "user", content: [envs.some(env => env.private || remoteEnvelope(env)) ? undefined : this.opts.titlePreface?.(), renderDigest(envs, true)].filter(Boolean).join("\n") }];
-    const progress = { sideEffects: 0, last: "" };
+    const progress = { sideEffects: 0, last: "", answerComplete: false };
     const requestedPolicy = this.opts.turnPolicy?.(envs);
     const policy = envs.some(env => env.private) ? { ...requestedPolicy, pii: true } : requestedPolicy;
     const remoteTurn = envs.some(remoteEnvelope);
@@ -217,11 +248,11 @@ export class LocalPeer extends BasePeer {
     // A PII turn speaks to the console user only, and privately: its answer must not be broadcast to cloud-hosted peers.
     // The task id travels with it, so the board can keep the text (`ahub task show`) while tail and log show a stub.
     const reply: EnvelopeOpts = { inReplyTo: replyParent(envs), to: replyAudience(envs), ...(policy?.pii ? { to: [USER], private: true, priority: "important" as const, ...(policy.task ? { refs: { task: policy.task } } : {}) } : {}) };
-    this.run(envs, turn, msgs, progress, policy, reply, reviewScope)
+    this.run(envs, turn, msgs, progress, policy, reply, reviewScope, selection, modelFailure)
       .then((answer) => {
         if (turn !== this.turn) return;
         if (preserveHistory && !reviewScope.excluded) this.commit(msgs); // Private, remote and review turns never enter later local capture through model history.
-        if (answer) this.onMessage?.(answer, reply);
+        if (answer) this.finalAnswer(answer, reply, progress.answerComplete);
         if (deliveryId && this.activeDeliveryId === deliveryId) this.delivery({ id: deliveryId, state: "completed" });
         completed = true;
       })
@@ -278,11 +309,14 @@ export class LocalPeer extends BasePeer {
     envs: Envelope[],
     turn: number,
     msgs: ChatMessage[],
-    progress: { sideEffects: number; last: string },
+    progress: { sideEffects: number; last: string; answerComplete: boolean },
     policy: { route?: string; fixedModel?: string; pii: boolean; task?: string } | undefined,
     reply: EnvelopeOpts,
     reviewScope: { excluded: boolean },
+    selection?: ModelOverrideSelection,
+    modelFailure?: Error,
   ): Promise<string> {
+    if (modelFailure) throw modelFailure;
     const { maxSteps = 30 } = this.opts;
     const turnSignal = this.abort!.signal;
     // Remote text/tool output is never memory evidence, even beside ordinary local work in the same turn.
@@ -294,22 +328,26 @@ export class LocalPeer extends BasePeer {
     }
     this.routeEnvs = envs;
     this.routePii = !!policy?.pii;
+    this.routeReviewScope = reviewScope;
+    if (turn !== this.turn || turnSignal.aborted) return "";
+    const fixedPrompt = this.turnRecordPrompt(system(this.opts.cwd, this.opts.preamble));
     const ctx = this.toolContext(envs, turnSignal, !!policy?.pii, reply);
     let usedTools = false;
     let captureInvocation = 0;
     for (let step = 0; step < maxSteps; step++) {
       this.elide(msgs);
-      const res = await this.call(msgs, policy, envs);
+      const res = await this.call(msgs, policy, envs, selection, fixedPrompt);
       if (turn !== this.turn) return "";
       this.touch();
       msgs.push(res.message);
       progress.last = res.message.content?.trim() || progress.last;
       if (!res.message.tool_calls?.length) {
-        const concluded = await this.conclude(msgs, policy, turn, step, maxSteps, progress.last, turnSignal, res.routeDecision);
+        const concluded = await this.conclude(msgs, policy, turn, step, maxSteps, progress.last, turnSignal, res.routeDecision, selection, fixedPrompt);
         if (turn !== this.turn) return "";
         if (concluded === undefined) continue;
-        if (usedTools && !reviewScope.excluded) capture?.summarize(concluded);
-        return concluded;
+        if (usedTools && !reviewScope.excluded) capture?.summarize(concluded.answer);
+        progress.answerComplete = concluded.complete;
+        return concluded.answer;
       }
       if (res.message.tool_calls.some(call => call.function.name.replace(/^mcp__[^ ]+__/, "") === "hub_review" && reviewCaptureExcluded(call.function.name, call.function.arguments))) reviewScope.excluded = true;
       const results: ChatMessage[] = [];
@@ -443,23 +481,24 @@ export class LocalPeer extends BasePeer {
   }
 
   /** Hub-owned in-process policy, with a fixed OmniRoute alias as fallback. */
-  private async call(turnMsgs: ChatMessage[], policy: { route?: string; fixedModel?: string; pii?: boolean; task?: string } | undefined, envs: Envelope[]): Promise<ChatResult> {
+  private async call(turnMsgs: ChatMessage[], policy: { route?: string; fixedModel?: string; pii?: boolean; task?: string } | undefined, envs: Envelope[], selection?: ModelOverrideSelection, fixedPrompt = system(this.opts.cwd, this.opts.preamble)): Promise<ChatResult> {
     const { omni } = this.opts;
-    const route = effectiveLocalRoute(this.opts.route, policy?.route, policy?.fixedModel);
+    const route = selection?.model === undefined ? effectiveLocalRoute(this.opts.route, policy?.route, policy?.fixedModel) : undefined;
     if (route && !route.startsWith("hub/") && !this.warnedLegacyRoutes.has(route)) {
       this.warnedLegacyRoutes.add(route);
       this.opts.log?.(`legacy route ${route} is deprecated and ignored; using fixed model`);
     }
-    const fixedModel = policy?.fixedModel ?? this.opts.fixedModel;
+    const fixedModel = selection?.model ?? policy?.fixedModel ?? this.opts.fixedModel;
     const task = policy?.task === undefined ? undefined : Number(policy.task);
     const tools = [...this.toolSchemas(), ...(this.opts.taskTool ? [...profileTaskTools(this.opts.profile, this.opts.sdlcStages, this.opts.sdlcCriteria).filter(tool => tool.name !== "hub_delivery_retry"), ...CONDUCTOR_TOOLS].concat(SESSION_TITLE_TOOL).map(asFunction) : [])];
     const signal = this.abort!.signal;
-    const messages: ChatMessage[] = [{ role: "system", content: system(this.opts.cwd, this.opts.preamble) }, ...this.history, ...turnMsgs];
+    const messages: ChatMessage[] = [{ role: "system", content: fixedPrompt }, ...this.history, ...turnMsgs];
     const routed = await this.hubCall(route, messages, policy, signal);
-    if (routed) return routed;
+    if (routed) { selection?.applied(); return routed; }
     await this.requireBudget(envs, "model_calls");
     this.releaseObserverInput(this.currentObserverInputContext, envs);
     const res = await omni.chat({ model: fixedModel, messages, tools }, { signal, ...(policy?.pii ? { onCampusOnly: true } : {}) });
+    selection?.applied();
     this.lastServedBy = `omniroute ${fixedModel} (provider ${res.provider ?? "?"})`;
     this.recordUsage(res, fixedModel, task);
     return res;
@@ -502,21 +541,21 @@ export class LocalPeer extends BasePeer {
     if (!route || !config) return undefined;
     try { return await this.routes.call(route, config, messages, this.routeScope(!!policy?.pii), !!policy?.pii, signal); }
     catch (error) {
-      if (signal.aborted || error instanceof ExecutionBudgetStop) throw error;
+      if (signal.aborted || error instanceof ExecutionBudgetStop || error instanceof DecisionPolicyChangedError) throw error;
       this.opts.log?.(`hub route ${route} unavailable; using fixed model`);
       return undefined;
     }
   }
 
-  private async conclude(msgs: ChatMessage[], policy: { route?: string; fixedModel?: string; pii: boolean } | undefined, turn: number, step: number, maxSteps: number, answer: string, signal: AbortSignal, decisionId?: string): Promise<string | undefined> {
-    const route = effectiveLocalRoute(this.opts.route, policy?.route, policy?.fixedModel), config = this.hubConfig(route);
-    if (!route || !config) return answer;
-    const messages: ChatMessage[] = [{ role: "system", content: system(this.opts.cwd, this.opts.preamble) }, ...this.history, ...msgs];
+  private async conclude(msgs: ChatMessage[], policy: { route?: string; fixedModel?: string; pii: boolean } | undefined, turn: number, step: number, maxSteps: number, answer: string, signal: AbortSignal, decisionId?: string, selection?: ModelOverrideSelection, fixedPrompt = system(this.opts.cwd, this.opts.preamble)): Promise<{ answer: string; complete: boolean } | undefined> {
+    const route = selection?.model === undefined ? effectiveLocalRoute(this.opts.route, policy?.route, policy?.fixedModel) : undefined, config = this.hubConfig(route);
+    if (!route || !config) return { answer, complete: true };
+    const messages: ChatMessage[] = [{ role: "system", content: fixedPrompt }, ...this.history, ...msgs];
     const feedback = await this.routes.review(route, config, messages, this.routeScope(!!policy?.pii, turn), !!policy?.pii, signal, decisionId);
-    if (turn !== this.turn || !feedback) return answer;
+    if (turn !== this.turn || !feedback) return { answer, complete: true };
     msgs.push({ role: "user", content: feedback });
     if (step + 1 >= maxSteps) this.opts.onLimit?.("steps");
-    return step + 1 < maxSteps ? undefined : `(review requested changes; step limit reached) ${answer}`;
+    return step + 1 < maxSteps ? undefined : { answer: `(review requested changes; step limit reached) ${answer}`, complete: false };
   }
 
   private observeTool(call: ToolCall, output: string, policy: { pii: boolean; task?: string } | undefined, nativeTurn: string): void {

package/src/adapters/model-token.ts

@@ -0,0 +1,3 @@
+/** #844 native model word: no spaces or leading dash, at most 128 ASCII bytes. */
+const NATIVE_WORD = /^[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,127}$/;
+export function isNativeModelToken(value: unknown): value is string { return typeof value === "string" && NATIVE_WORD.test(value); }

package/src/adapters/pi.ts

@@ -1,3 +1,5 @@
+import type { ModelOverrideSelection } from "./registry-types.ts";
+import { isNativeModelToken } from "./model-token.ts";
 import { buildPiLaunch } from "../pi/launch.ts";
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync } from "node:fs";
@@ -41,6 +43,8 @@ export interface PiOptions {
   hubStateDir?: string;
   cwd: string; stateDir: string; cmd?: string[]; mode: "headless" | "tui"; backend: "auto" | "dgx" | "mlx"; sessionFile?: string; sessionId?: string;
   model?: string;
+  /** Host-only choice sampled once at the next turn/review boundary. */
+  getModelOverride?: () => ModelOverrideSelection;
   relay: PiRelay; executeTool: (name: string, args: unknown, toolCallId: string, sessionId?: string, signal?: AbortSignal, context?: PiToolContext) => Promise<string | PiToolResult>; tools: PiToolSchema[];
   preamble?: string;
   /** Host-owned conditional instruction, sampled once per delivered turn. */
@@ -205,6 +209,8 @@ export class PiPeer extends BasePeer {
   private owner = randomUUID();
   private _tuiLaunch?: PiTuiLaunch;
   private requestedModel = "";
+  private baselineRequestedModel = "";
+  private runtimeModelSelected = false;
   private starting?: Promise<void>;
   private ownerClaimed = false;
   private ownerToken = "";
@@ -233,7 +239,7 @@ export class PiPeer extends BasePeer {
   private tuiWaiters: Array<{ resolve: (command: Record<string, unknown> | undefined) => void; timer: ReturnType<typeof setTimeout> }> = [];
 
   /** The fixed production factory supplies preflight separately, preserving transport option identity. */
-  constructor(id: PeerId, private readonly opts: PiOptions, private readonly preflight?: () => Promise<void>) { super(id, opts.watchdogMs); }
+  constructor(id: PeerId, private readonly opts: PiOptions, private readonly preflight?: () => Promise<void>) { super(id, opts.watchdogMs); this.baselineRequestedModel = opts.model ?? ""; }
   get tuiLaunch(): PiTuiLaunch | undefined { return this._tuiLaunch; }
   get pendingResume(): { sessionId?: string; sessionFile?: string } {
     if (this.canReuseVerifiedEmptyResume()) return { sessionId: this.verifiedEmptyResume!.sessionId };
@@ -754,14 +760,23 @@ export class PiPeer extends BasePeer {
     let attempted = false;
     let promptId: string | undefined;
     try {
-      const requested = await this.opts.selectModel?.(envs);
+      const selection = this.opts.getModelOverride?.();
+      if (selection?.model !== undefined && !isNativeModelToken(selection.model)) throw new Error("runtime model must be one bounded native token");
+      const baseline = await this.opts.selectModel?.(envs);
+      const requested = selection?.model ?? baseline ?? (this.baselineRequestedModel || undefined);
+      if (selection && selection.model === undefined && this.runtimeModelSelected && !requested) throw new Error(`baseline model unavailable; restore the peer model configuration and run ahub restart ${this.id} before retrying`);
       if (rosterEpoch !== this.rosterEpoch || !this.acceptingTools) throw new Error("Pi is off roster or stopped");
-      if (requested) await this.setRequestedModel(requested);
+      if (requested) {
+        if (selection?.model !== undefined) await this.applyRequestedModel(requested);
+        else await this.setRequestedModel(requested);
+        this.runtimeModelSelected = selection?.model !== undefined;
+      }
       if (rosterEpoch !== this.rosterEpoch || !this.acceptingTools) throw new Error("Pi is off roster or stopped");
       this.noteActivity();
       attempted = true;
       if (deliveryId) this.activeDeliveryIds.add(deliveryId);
-      const message = [envs.some(env => env.private || remoteEnvelope(env)) ? undefined : this.opts.titlePreface?.(), renderDigest(envs, true)].filter(Boolean).join("\n");
+      const recordPrompt = this.opts.mode === "tui" ? "" : this.turnRecordPrompt("");
+      const message = [recordPrompt, envs.some(env => env.private || remoteEnvelope(env)) ? undefined : this.opts.titlePreface?.(), renderDigest(envs, true)].filter(Boolean).join("\n");
       if (this.opts.mode === "tui") { const pending = this.sendTui({ type: "prompt", message }); promptId = this.pendingPromptId; await pending; }
       else await this.sendRpc({ type: "prompt", message });
       if (promptId !== undefined && promptId !== this.pendingPromptId) return;
@@ -770,6 +785,8 @@ export class PiPeer extends BasePeer {
         this.setState("offline");
         return;
       }
+      if (rosterEpoch !== this.rosterEpoch || !this.acceptingTools) throw new Error("Pi is off roster or stopped");
+      try { selection?.applied(); } catch { /* Only prompt acceptance proves this turn used the selected model or unchanged native default. */ }
       if (deliveryId && this.activeDeliveryIds.has(deliveryId)) this.delivery({ id: deliveryId, state: "accepted" });
     } catch (error) {
       if (promptId !== undefined && promptId !== this.pendingPromptId) return;
@@ -831,7 +848,12 @@ export class PiPeer extends BasePeer {
   }
 
   getRequestedModel(): string { return this.requestedModel; }
+  getBaselineRequestedModel(): string { return this.baselineRequestedModel; }
   async setRequestedModel(model: string): Promise<void> {
+    await this.applyRequestedModel(model);
+    this.baselineRequestedModel = model;
+  }
+  private async applyRequestedModel(model: string): Promise<void> {
     if (!this.acceptingTools) throw new Error("Pi is off roster or stopped");
     const slash = model.indexOf("/");
     const provider = "agent-hub-local";
@@ -971,7 +993,7 @@ export class PiPeer extends BasePeer {
       else if (error?.startsWith("execution budget")) this.onMessage?.(`Pi stopped at the execution budget: ${error}. Inspect partial work before continuing.`, reply);
       else if (approvalStopReason) this.onMessage?.(approvalStopReason, reply);
       else if (error) void this.opts.onTurnFailure?.(this.activeEnvs, error, ceiling);
-      else if (text) this.onMessage?.(text, reply);
+      else if (text) this.finalAnswer(text, reply);
       for (const id of this.activeDeliveryIds) this.delivery({ id, state: approvalStopReason ? "completed" : error || cancelled ? "needs_review" : "completed", ...(error || cancelled ? { reason: error || "Pi turn cancelled; partial effects are possible" } : {}) });
       this.activeDeliveryIds.clear();
       this.currentReply = undefined; this.activeEnvs = [];

package/src/adapters/registry-types.ts

@@ -1,3 +1,11 @@
+/** One host-latched runtime choice; applied binds the captured revision and boundary, never a later value. */
+export interface ModelOverrideSelection {
+  readonly model: string | undefined;
+  applied(nativeModel?: string): void;
+  /** Retire only this still-unacknowledged capture after a definitive native pre-start rejection. */
+  rejected?(): void;
+}
+
 import type { ClaudeImplementerOptions } from "./claude-implementer.ts";
 import type { ReviewerBackend, ReviewerPrintOptions } from "./reviewer-print.ts";
 import type { SettingDef } from "../hub/settings.ts";
@@ -126,7 +134,7 @@ export interface ContextReader {
 export type { Capability, CapabilityManifest, SideEffect } from "../hub/capabilities.ts";
 
 export interface NativeFactsInput {
-  event: "SessionStart" | "PreInvocation" | "PostInvocation" | "PreToolUse" | "PostToolUse" | "Stop";
+  event: "SessionStart" | "PreInvocation" | "PostInvocation" | "PreToolUse" | "PostToolUse" | "Stop" | "TurnStarted" | "StopFailure" | "Interrupt" | "SessionEnd" | "TaskStarted" | "Notification";
   phase: "session" | "start" | "pre" | "post" | "stop";
   sessionId: string;
   transcriptPath: string;
@@ -138,15 +146,36 @@ export interface NativeFactsInput {
   fullyIdle?: boolean;
   terminationReason?: string;
 }
+export interface NativeFactsReadOptions {
+  completion?: boolean;
+  sinceOffset?: number;
+  unchanged?: { size: number; mtimeMs: number };
+}
+export interface NativeFactsUsage {
+  id: string;
+  index: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  totalTokens: number;
+  at?: string;
+}
 export interface NativeFactsTranscript {
-  completion?: { id: string; index: number };
+  completion?: { id: string; index: number; reason?: "completed" | "failed" | "cancelled" };
+  started?: { id: string; index: number; origin: string };
+  background?: number;
   factIds: string[];
+  usage?: NativeFactsUsage[];
+  size?: number;
+  mtimeMs?: number;
+  scannedFrom?: number;
+  unchanged?: boolean;
 }
 /** Fixed native codec and bounded readback, never supplied by project configuration. */
 export interface NativeFactsPort {
   decode(event: string, input: unknown): NativeFactsInput | undefined;
   encode(event: string, text?: string): Record<string, unknown> | undefined;
-  read(session: string, transcript: string): NativeFactsTranscript;
+  read(session: string, transcript: string, options?: NativeFactsReadOptions): NativeFactsTranscript;
 }
 
 /** Only the frozen native seams are extensible; a definition cannot add an arbitrary daemon callback. */
@@ -300,6 +329,8 @@ export interface AdapterDefinition {
     validateEffective?(raw: Record<string, unknown>, fail: (key: string, reason: string) => never): void;
   };
   capabilities?: { manifest?(peer: PeerAdapter): Promise<CapabilityManifest>; watch?: boolean };
+  /** Fixed factory support only; the host still checks the actual native surface and form. */
+  modelOverride?: { readonly boundary: "turn"; readonly acp?: import("./acp-model-policy.ts").AcpModelPolicy };
   /** Stable host projection order and planner eligibility, independent of default task roles. */
   projection?: { roleRank?: number; startRank?: number; helpRank?: number; plannerEligible?: boolean };
   cli: {

package/src/adapters/registry.ts

@@ -243,6 +243,7 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
     ["titlePersistence", definition.titlePersistence !== undefined],
     ["questionWaitMs", definition.questionWaitMs !== undefined],
     ["settle", definition.settle !== undefined],
+    ["modelOverride", definition.modelOverride !== undefined],
     ["start.acpCommand", declared(definition.start, "acpCommand")],
     ["attach.admission", declared(definition.attach, "admission")],
     ["budget.resetSoftTokensOnResume", declared(definition.budget, "resetSoftTokensOnResume")],

package/src/adapters/reviewer-policy-watch.ts

@@ -0,0 +1,86 @@
+/** A fixed host producer's full policy check, never a verdict-authority cache. */
+export interface ReviewerPolicyProbe {
+  /** Boot/protocol failures revoke even when a child exits before its first periodic poll. */
+  readonly failure?: Promise<void>;
+  check(): Promise<boolean>;
+  stop(): Promise<void>;
+}
+export interface ReviewerPolicyWatch {
+  /** The caller attaches ownership before any timer or notification can run. */
+  start(): void;
+  /** Only an explicit owner retry may repeat a failed join. */
+  stop(retry?: boolean): Promise<void>;
+}
+export interface ReviewerPolicyWatchClock {
+  now(): number;
+  schedule(delayMs: number, run: () => void): () => void;
+}
+const POLICY_POLL_MS = 100;
+
+/** Serialized absolute cadence: an overdue check runs now, coalescing missed slots at its start. */
+export function createReviewerPolicyWatch(probe: ReviewerPolicyProbe, changed: () => void,
+  clock: Partial<ReviewerPolicyWatchClock> = {}): ReviewerPolicyWatch {
+  const now = clock.now ?? (() => performance.now());
+  const schedule = clock.schedule ?? ((delayMs: number, run: () => void) => {
+    const timer = setTimeout(run, delayMs); timer.unref?.();
+    return () => clearTimeout(timer);
+  });
+  let started = false, stopped = false, due = 0;
+  let cancelTimer: (() => void) | undefined, flight: Promise<void> | undefined;
+  let stopping: Promise<void> | undefined, stopFailed = false;
+  const sample = () => {
+    const value = now();
+    if (!Number.isFinite(value)) throw new Error("review policy clock unavailable");
+    return value;
+  };
+  const stop = (retry = false): Promise<void> => {
+    stopped = true;
+    cancelTimer?.(); cancelTimer = undefined;
+    if (retry && stopFailed) { stopping = undefined; stopFailed = false; }
+    if (!stopping) {
+      const pending = flight;
+      // Termination must settle a blocked check before joining that check; the reverse order can deadlock.
+      stopping = Promise.resolve().then(() => probe.stop()).then(async () => { await pending; });
+      void stopping.catch(() => { stopFailed = true; });
+    }
+    return stopping;
+  };
+  const fail = () => {
+    if (stopped) return;
+    void stop().catch(() => {}); // The owner retains and observes the same failed join.
+    try { changed(); } catch { /* The probe is already stopping; a notification cannot rearm it. */ }
+  };
+  const arm = () => {
+    if (stopped) return;
+    try { cancelTimer = schedule(Math.max(0, due - sample()), tick); }
+    catch { fail(); }
+  };
+  const tick = () => {
+    cancelTimer = undefined;
+    if (stopped) return;
+    if (flight) { fail(); return; }
+    try {
+      const at = sample();
+      if (at > due) due += Math.floor((at - due) / POLICY_POLL_MS) * POLICY_POLL_MS;
+    } catch { fail(); return; }
+    const pending = (async () => {
+      let current = false;
+      try { current = await probe.check() === true; } catch { /* A failed check is policy drift. */ }
+      if (stopped) return;
+      if (!current) { fail(); return; }
+      due += POLICY_POLL_MS;
+      arm();
+    })();
+    flight = pending;
+    void pending.finally(() => { if (flight === pending) flight = undefined; }).catch(() => {});
+  };
+  return {
+    start: () => {
+      if (started || stopped) return;
+      started = true;
+      if (probe.failure) void probe.failure.then(fail, fail);
+      try { due = sample() + POLICY_POLL_MS; arm(); } catch { fail(); }
+    },
+    stop,
+  };
+}