@staix/agent-hub 0.34.0 → 0.35.0

package/src/adapters/channel-peer.ts

@@ -1,4 +1,4 @@
-import { BasePeer, type PeerAdapter, type PeerStandbySession, type PeerTakeoverClaim } from "../hub/peers.ts";
+import { BasePeer, type PeerAdapter, type PeerOwnerAttachment, type PeerStandbySession, type PeerTakeoverClaim } from "../hub/peers.ts";
 import type { Envelope } from "../hub/envelope.ts";
 import { definitionOf } from "./registry.ts";
 import type { StartForm } from "./registry-types.ts";
@@ -12,6 +12,12 @@ export interface ChannelSocket {
   close(code?: number, reason?: string): void;
 }
 
+const MAX_PID = 2_147_483_647;
+/** A client-reported pid, bounded the way the daemon bounds it at hello; anything else is unknown, never a guess. */
+const boundedPid = (value: unknown): number | undefined => Number.isSafeInteger(value) && (value as number) > 0 && (value as number) <= MAX_PID ? value as number : undefined;
+/** A native session id that is shown only when it is a short plain token (the agy decoder accepts UUIDs); a longer or odd value is not shown at all, never trimmed into one. */
+const NATIVE_SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+
 /** A peer that lives in another process and attaches over the control WS (the Claude channel plugin). */
 export class WsPeer extends BasePeer {
   private static readonly MAX_STANDBY_SESSIONS = 8;
@@ -31,6 +37,8 @@ export class WsPeer extends BasePeer {
   private readonly standbys = new Map<ChannelSocket, PeerStandbySession>();
   private nativeTurnSession: string | undefined;
   private nativeActive = false;
+  /** The owner facts of the current socket, written once when its attach completes and dropped with that socket (#1310). The native session is read live from `nativeSession`, which the same events clear. */
+  private ownerFacts: { socket: ChannelSocket; ownerPid?: number; attachedAt: number } | undefined;
   /** The attached session said it cannot show channel pushes (issue #205): the bus keeps its queue for `inbox`. */
   pullOnly = false;
   attachMode: "channel" | "tools-only" = "tools-only";
@@ -68,6 +76,18 @@ export class WsPeer extends BasePeer {
     return [...this.standbys.values()].map(session => ({ ...session }));
   }
   get managedLaunchId(): string | undefined { return this.attached ? this.sock?.data.launchId : undefined; }
+  /**
+   * Who holds this peer now, for display only (#1310). Absent while a newer hello is claiming (the peer reads as offline until its preface ends), while offline and after a detach, so a claimant or a
+   * previous owner is never shown as attached. `ownerPid` is the current socket's bounded client pid, `attachedAt` is when its attach completed (not the hello), and `nativeSessionId` appears only
+   * after the host bound a verified native session (`bindNativeSession`, from the daemon's checked native-facts path) and only when it is a short plain token.
+   */
+  get ownerAttachment(): PeerOwnerAttachment | undefined {
+    const facts = this.ownerFacts;
+    if (!facts || facts.socket !== this.sock || !this.attached) return undefined;
+    const native = (this as { nativeSession?: string }).nativeSession;
+    return { ...(facts.ownerPid !== undefined ? { ownerPid: facts.ownerPid } : {}), attachedAt: facts.attachedAt,
+      ...(typeof native === "string" && NATIVE_SESSION_ID.test(native) ? { nativeSessionId: native } : {}) };
+  }
 
   /** A session that shows pushes holds the peer or is arriving: a session without them must not take it (issue #205). */
   get channelHeld(): boolean {
@@ -127,9 +147,12 @@ export class WsPeer extends BasePeer {
     if (this.sock) this.setState("offline"); // unresolved work belongs to the previous connection
     this.sock?.close(4000, "replaced");
     this.sock = sock;
+    // Replaced in the same synchronous step as the socket, so a previous owner's pid or time can never be read beside the new socket (#1310).
+    this.ownerFacts = { socket: sock, ...(boundedPid(sock.data.clientPid) !== undefined ? { ownerPid: boundedPid(sock.data.clientPid) } : {}), attachedAt: Date.now() };
     this.generation = crypto.randomUUID();
     this.delivered.clear();
     this.nativeTurnSession = undefined;
+    delete (this as { nativeSession?: string }).nativeSession;
     this.nativeActive = false;
     this.pullOnly = this.claimedPullOnly; // before idle: the idle transition drains
     this.attachMode = this.pullOnly ? "tools-only" : "channel";
@@ -153,7 +176,9 @@ export class WsPeer extends BasePeer {
     if (this.claimed === sock) { this.claimed = undefined; this.settleAttachmentWaiters(false); }
     if (this.sock !== sock) return;
     this.sock = undefined;
+    this.ownerFacts = undefined;
     this.steer = undefined;
+    delete (this as { nativeSession?: string }).nativeSession;
     this.nativeActive = false;
     this.pullOnly = false;
     this.setState("offline");
@@ -166,7 +191,9 @@ export class WsPeer extends BasePeer {
     this.standbys.clear();
     this.claimed = undefined;
     this.sock = undefined;
+    this.ownerFacts = undefined;
     this.steer = undefined;
+    delete (this as { nativeSession?: string }).nativeSession;
     this.nativeActive = false;
     this.pullOnly = false;
     this.setState("offline");
@@ -183,6 +210,10 @@ export class WsPeer extends BasePeer {
   }
   owns(sock: ChannelSocket): boolean { return this.sock === sock; }
   ownsSocket(socket: object): boolean { return this.sock === socket; }
+  bindNativeSession(session: string): void {
+    if (!this.sock || !session) return;
+    Object.defineProperty(this, "nativeSession", { value: session, writable: true, configurable: true, enumerable: true });
+  }
   nativeStarted(session: string): void {
     if (!this.sock) return;
     this.nativeTurnSession = session;
@@ -205,6 +236,7 @@ export class WsPeer extends BasePeer {
   async start(): Promise<void> {}
   async stop(): Promise<void> {
     this.settleAttachmentWaiters(false);
+    this.ownerFacts = undefined;
     this.sock?.close();
     for (const socket of this.standbys.keys()) socket.close();
     this.standbys.clear();

package/src/adapters/claude-implementer.ts

@@ -1,3 +1,5 @@
+import type { ModelOverrideSelection } from "./registry-types.ts";
+import { isNativeModelToken } from "./model-token.ts";
 import { randomUUID } from "node:crypto";
 import { lstatSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -38,6 +40,8 @@ export interface ClaudeImplementerOptions {
   watchdogMs: number;
   /** Declared `model` of this instance (#844): one validated word passed as `--model`; unset leaves the native default and the argv unchanged. */
   model?: string;
+  /** Host-only choice sampled once at the next turn/review boundary. */
+  getModelOverride?: () => ModelOverrideSelection;
   mode?: "ask" | "ask-when-needed";
   /** Exact host-reported transcript evidence only; unknown/read errors retain the recorded UUID. */
   transcriptPersisted?(task: number, sessionId: string): boolean | "unknown";
@@ -188,16 +192,24 @@ export class ClaudeImplementerPeer extends BasePeer {
     }
     const generation = this.generation; this.deliveryId = deliveryId; this.inputReleased = false;
     this.abort = new AbortController(); this.setState("busy");
+    let selection: ModelOverrideSelection | undefined, modelFailure: Error | undefined;
+    try {
+      selection = this.options.getModelOverride?.();
+      if (selection?.model !== undefined && !isNativeModelToken(selection.model)) throw new Error("invalid model");
+    } catch { modelFailure = new Error("runtime model selection unavailable; check the peer model setting and retry"); }
     if (deliveryId) this.delivery({ id: deliveryId, state: "accepted" });
     // Register the run identity before any synchronous failure can publish idle.
-    const running: Promise<void> = Promise.resolve().then(() => this.run(groups, generation, running));
+    const running: Promise<void> = Promise.resolve().then(() => this.run(groups, generation, running, selection, modelFailure));
     this.running = running;
     void running.finally(() => { if (this.running === running) this.running = undefined; }).catch(() => {});
   }
-  private async run(groups: { task?: number; envs: Envelope[] }[], generation: number, running: Promise<void>): Promise<void> {
+  private async run(groups: { task?: number; envs: Envelope[] }[], generation: number, running: Promise<void>, selection?: ModelOverrideSelection, modelFailure?: Error): Promise<void> {
     const current = () => generation === this.generation && !this.abort?.signal.aborted;
     let failureReason: string | undefined;
     try {
+      if (modelFailure) throw modelFailure;
+      const model = selection?.model ?? this.options.model;
+      let modelApplied = false;
       for (let group of groups) {
         failureReason = undefined;
         if (!current() || !this.binding?.()) throw new Error("Claude implementer admission changed");
@@ -224,7 +236,7 @@ export class ClaudeImplementerPeer extends BasePeer {
           AGENTHUB_INSTANCE_ID: this.options.instanceId, AGENTHUB_LAUNCH_ID: launchId, AGENTHUB_HOOK_PURPOSE: "permission", AGENTHUB_PERMISSION_TOOL: "1" };
         const mcp = JSON.stringify({ mcpServers: { "agent-hub": { command: process.execPath, args: ["run", this.options.server], env } } });
         let result = false, failed = false;
-        const child = new OwnedPrintChild({ peer: this.id, command: this.command!, args: claudeImplementerArgs(turn, mcp, settings, this.options.systemPrompt, this.options.model), cwd: this.options.cwd,
+        const child = new OwnedPrintChild({ peer: this.id, command: this.command!, args: claudeImplementerArgs(turn, mcp, settings, this.options.systemPrompt, model), cwd: this.options.cwd,
           input: group.envs.map(frame).join("\n\n"), env, current, stop: this.options.stopChild,
           onSpawn: () => {
             try {
@@ -234,6 +246,7 @@ export class ClaudeImplementerPeer extends BasePeer {
               void this.cancel("Claude implementer admission changed before child start", "idle").catch(() => {});
               return;
             }
+            if (!modelApplied) { modelApplied = true; try { selection?.applied(); } catch { /* Status acknowledgement never grants child authority. */ } }
             this.childAbort = new AbortController();
             const launch: OwnedToolsLaunch = Object.freeze({ permissionHook: true, launchId, generation: `${generation}:${launchId}`, sessionId: turn.sessionId, signal: this.childAbort.signal, ...(group.task !== undefined ? { task: group.task } : {}) });
             this.active = launch;

package/src/adapters/codex-appserver.ts

@@ -1,3 +1,5 @@
+import type { ModelOverrideSelection } from "./registry-types.ts";
+import { isNativeModelToken } from "./model-token.ts";
 import { spawn, type ChildProcess } from "node:child_process";
 import type { Server, ServerWebSocket } from "bun";
 import { renderDigest, replyAudience, replyParent, type Envelope, type PeerId } from "../hub/envelope.ts";
@@ -25,6 +27,10 @@ function confirmsReadOnlySandbox(value: unknown): boolean {
 /** A counter Codex reported: a finite non-negative number, otherwise 0 (an absent kind is not a negative delta). */
 const counter = (value: unknown): number => { const n = Number(value); return Number.isFinite(n) && n >= 0 ? n : 0; };
 export interface CodexOptions {
+  /** Host-only choice sampled once at the next turn/review boundary. */
+  getModelOverride?: () => ModelOverrideSelection;
+  /** Successful explicit native-client choice; never acknowledgement of a hub override revision. */
+  onNativeModelApplied?: (model: string) => void;
   /** Port the TUI attaches to: `codex --enable tui_app_server --remote ws://127.0.0.1:<proxyPort>`. */
   proxyPort: number;
   permissionMode?: PermissionMode;
@@ -78,12 +84,18 @@ export interface CodexOptions {
   log?: (line: string) => void;
 }
 
+interface ModelStartOrder { thread: string; sequence: number; changing: boolean }
 interface Link {
   launchId?: string;
   tui: ServerWebSocket<Link>;
   up: WebSocket;
   backlog: string[]; // TUI frames that arrived before the upstream socket opened
   approvalIds: Set<string | number>; // intercepted native ids stay tombstoned for this socket lifetime
+  modelStarts: Map<string | number, ModelStartOrder & { epoch: number; nativeStarted?: true; selection?: ModelOverrideSelection; explicit?: string; clientModel: boolean } | null>;
+  /** One drained rejection candidate, never an unbounded history while another request hangs. */
+  rejectedModelSelection?: { selection: ModelOverrideSelection; epoch: number; thread: string };
+  /** Untracked/reused requests cannot prove a sticky default until a later explicit model ACK. */
+  modelUnknownAfter?: number;
   tracked: Map<string | number, string>; // request id -> method, for thread/start and thread/resume
   /** Correlated native initial policy, retained even before this instance gains the planner role. */
   readOnlyThread?: string;
@@ -106,6 +118,8 @@ export class CodexPeer extends BasePeer {
   get actionGated(): boolean { return this.opts.actionGate !== undefined; }
   private readonly nativeApprovalPolicies = new Map<string, unknown>();
   private readonly overriddenApprovals = new Set<string>();
+  private readonly nativeModels = new Map<string, { sequence: number; model?: string }>();
+  private modelStartSequence = 0;
   private readonly restoringApprovals = new Map<string | number, string>();
   private proc: ChildProcess | undefined;
   private server: Server<Link> | undefined;
@@ -136,7 +150,7 @@ export class CodexPeer extends BasePeer {
   }
   private unboundAccepted = false;
   private nextId = -1;
-  private readonly pending = new Map<number, { resolve: (result?: any) => void; reject: (e: Error, failureCause?: DeliveryFailureCause) => void; deliveryId?: string; kind?: "deliver" | "steer"; expectedTurnId?: string; afterTurn?: () => void; invalidate?: (reason: string, failureCause?: DeliveryFailureCause) => void }>();
+  private readonly pending = new Map<number, { resolve: (result?: any) => void; reject: (e: Error, failureCause?: DeliveryFailureCause) => void; deliveryId?: string; kind?: "deliver" | "steer"; modelStart?: ModelStartOrder; expectedTurnId?: string; afterTurn?: () => void; invalidate?: (reason: string, failureCause?: DeliveryFailureCause) => void }>();
   private usageTimer: ReturnType<typeof setInterval> | undefined;
   private injected: Envelope | undefined; // the hub envelope that started the current turn, if any
   private answering: Envelope[] = []; // everything delivered or steered into the current turn: who its answer is for
@@ -189,6 +203,7 @@ export class CodexPeer extends BasePeer {
   }
 
   async start(): Promise<void> {
+    this.nativeModels.clear(); this.modelStartSequence = 0;
     const upstream = this.opts.upstreamUrl ?? (await this.spawnAppServer());
     try {
       this.server = Bun.serve<Link>({
@@ -255,10 +270,19 @@ export class CodexPeer extends BasePeer {
       if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} is not injectable` });
       return Promise.reject(new Error(`${this.id} is not injectable`));
     }
-    const text = this.render(envs);
     const id = this.nextId--, epoch = this.deliveryEpoch, session = this.contextEpoch;
     this.setState("busy"); // claim the turn now so the bus stops draining
     return new Promise<void>((resolve, reject) => {
+      let selection: ModelOverrideSelection | undefined;
+      try {
+        selection = this.opts.getModelOverride?.();
+        if (selection?.model !== undefined && !isNativeModelToken(selection.model)) throw new Error("runtime model must be one bounded native token");
+      } catch (error) {
+        this.setState("idle");
+        if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: "runtime model selection unavailable" });
+        reject(error); return;
+      }
+      const modelStart: ModelStartOrder = { thread: this.threadId, sequence: ++this.modelStartSequence, changing: selection?.model !== undefined };
       let invalidated = false;
       const retiredAtCancel = new Set<string>();
       const invalidate = (reason: string, failureCause?: DeliveryFailureCause) => {
@@ -270,7 +294,7 @@ export class CodexPeer extends BasePeer {
         reject(new Error(reason));
       };
       this.pending.set(id, {
-        deliveryId, kind: "deliver", invalidate,
+        deliveryId, kind: "deliver", modelStart, invalidate,
         resolve: (result) => {
           const nativeTurn = typeof result?.turn?.id === "string" ? result.turn.id : undefined;
           if (invalidated || epoch !== this.deliveryEpoch || session !== this.contextEpoch || link !== this.link) {
@@ -279,6 +303,8 @@ export class CodexPeer extends BasePeer {
               (!retiredAtCancel.has(nativeTurn) || this.retiredTurns.has(nativeTurn))) this.retireTurn(nativeTurn);
             return;
           }
+          const acceptedModel = this.acceptModelStart(modelStart, selection?.model, true);
+          if (acceptedModel) try { selection?.applied(acceptedModel.model); } catch { /* Native acceptance remains authoritative. */ }
           this.primed = true;
           this.injected = replyParent(envs);
           this.answering = [...envs];
@@ -307,14 +333,17 @@ export class CodexPeer extends BasePeer {
         const pending = this.pending.get(id); this.pending.delete(id);
         pending?.reject(new Error(`${this.id} is not injectable`)); return;
       }
+      const text = this.render(envs, true);
       link.up.send(
-        JSON.stringify({ method: "turn/start", id, params: this.applyPermissionPolicy({ threadId: this.threadId, input: [{ type: "text", text }] }, id) }),
+        JSON.stringify({ method: "turn/start", id, params: this.applyPermissionPolicy({ threadId: this.threadId, input: [{ type: "text", text }], ...(selection?.model === undefined ? {} : { model: selection.model }) }, id) }),
       );
     });
   }
 
-  private render(envs: Envelope[]): string {
-    return this.primed || !this.opts.preamble ? renderDigest(envs, this.primed) : `${this.opts.preamble}\n\n${renderDigest(envs, false)}`;
+  private render(envs: Envelope[], record = false): string {
+    const base = this.primed ? "" : this.opts.preamble ?? "";
+    const preamble = record ? this.turnRecordPrompt(base) : base;
+    return preamble ? `${preamble}\n\n${renderDigest(envs, this.primed)}` : renderDigest(envs, this.primed);
   }
 
   /** `important` while a turn runs: feed it into that turn. Rejects when there is no steerable turn or app-server refuses. */
@@ -494,7 +523,7 @@ export class CodexPeer extends BasePeer {
 
   private attach(tui: ServerWebSocket<Link>, upstream: string): void {
     const up = new WebSocket(upstream);
-    const link: Link = { tui, up, backlog: [], tracked: new Map(), approvalIds: new Set(), ...(tui.data.launchId ? { launchId: tui.data.launchId } : {}) };
+    const link: Link = { tui, up, backlog: [], tracked: new Map(), modelStarts: new Map(), approvalIds: new Set(), ...(tui.data.launchId ? { launchId: tui.data.launchId } : {}) };
     this.claimedTui = link;
     tui.data = link;
     up.onopen = () => {
@@ -505,6 +534,7 @@ export class CodexPeer extends BasePeer {
   }
 
   private detach(link: Link): void {
+    link.rejectedModelSelection = undefined;
     this.abortActionWaits(link);
     link.up.close();
     if (this.claimedTui === link) this.claimedTui = undefined;
@@ -588,6 +618,35 @@ export class CodexPeer extends BasePeer {
     if (thread !== undefined && !failed && this.permissionMode === "ask") this.overriddenApprovals.delete(thread);
   }
 
+  private nativeModelHint(thread: string): string | undefined {
+    const known = this.nativeModels.get(thread);
+    if (!known?.model || (this.link?.modelUnknownAfter ?? 0) >= known.sequence) return undefined;
+    const unsettled = [...this.pending.values()].flatMap(value => value.modelStart ? [value.modelStart] : []);
+    for (const value of this.link?.modelStarts.values() ?? []) if (value) unsettled.push(value);
+    if (unsettled.some(value => value.thread === thread && value.changing && value.sequence > known.sequence)) return undefined;
+    return known.model;
+  }
+
+  /** Shared by hub and forwarded starts: response arrival order never rewrites a later accepted start. */
+  private acceptModelStart(start: ModelStartOrder, model: string | undefined, inherit: boolean): { model?: string } | undefined {
+    // Even an older successful start protects its shared capture from pre-start retirement.
+    if (this.link) this.link.rejectedModelSelection = undefined;
+    if ((this.nativeModels.get(start.thread)?.sequence ?? 0) >= start.sequence) return undefined;
+    const actual = model ?? (inherit ? this.nativeModelHint(start.thread) : undefined);
+    this.nativeModels.set(start.thread, { sequence: start.sequence, ...(actual === undefined ? {} : { model: actual }) });
+    // ponytail: keep at most 128 thread receipts; older defaults are unknown until native model readback is added.
+    if (this.nativeModels.size > 128) this.nativeModels.delete(this.nativeModels.keys().next().value!);
+    return actual === undefined ? {} : { model: actual };
+  }
+
+  private retireRejectedModelSelection(link: Link): void {
+    const candidate = link.rejectedModelSelection;
+    if (!candidate || link !== this.link || candidate.epoch !== this.contextEpoch || candidate.thread !== this.threadId ||
+        link.modelStarts.size || [...this.pending.values()].some(value => value.modelStart)) return;
+    link.rejectedModelSelection = undefined;
+    try { candidate.selection.rejected?.(); } catch { /* Retirement never changes the native rejection. */ }
+  }
+
   private fromTui(link: Link, raw: string): void {
     const msg = parse(raw);
     if (msg?.id !== undefined && !msg.method && link.approvalIds.has(msg.id)) return;
@@ -597,6 +656,30 @@ export class CodexPeer extends BasePeer {
     if (msg?.method === "turn/interrupt" && link === this.link) this.abortActionWaits(link, typeof msg.params?.turnId === "string" ? msg.params.turnId : undefined);
     if (msg?.method === "turn/start" && msg.params && link === this.link) {
       const thread = typeof msg.params.threadId === "string" ? msg.params.threadId : this.threadId;
+      // An explicit native choice wins. A missing client model may use the already captured host override.
+      let selection: ModelOverrideSelection | undefined;
+      const explicit = msg.params.model !== undefined;
+      if (!explicit) {
+        try {
+          selection = this.opts.getModelOverride?.();
+          if (selection?.model !== undefined && !isNativeModelToken(selection.model)) throw new Error("invalid model");
+        } catch {
+          if (msg.id !== undefined) link.tui.send(JSON.stringify({ id: msg.id, error: { code: -32000, message: "runtime model selection unavailable; check the peer model setting and retry" } }));
+          return;
+        }
+        if (selection?.model !== undefined) { msg.params = { ...msg.params, model: selection.model }; raw = JSON.stringify(msg); }
+      }
+      const modelStart: ModelStartOrder = { thread, sequence: ++this.modelStartSequence, changing: explicit || selection?.model !== undefined };
+      if (typeof msg.id === "string" || typeof msg.id === "number") {
+        if (link.modelStarts.has(msg.id)) {
+          link.modelStarts.set(msg.id, null); // reused outstanding id cannot identify an accepted model revision
+          link.modelUnknownAfter = modelStart.sequence;
+        }
+        // ponytail: at most 64 in-flight ACKs per link; overflow keeps defaults unknown until a later explicit model ACK.
+        else if (link.modelStarts.size < 64) link.modelStarts.set(msg.id, { ...modelStart, epoch: this.contextEpoch, clientModel: explicit,
+          ...(selection ? { selection } : {}), ...(explicit && isNativeModelToken(msg.params.model) ? { explicit: msg.params.model } : {}) });
+        else link.modelUnknownAfter = modelStart.sequence;
+      } else link.modelUnknownAfter = modelStart.sequence;
       // A resumed TUI can echo the sticky hub overlay. The restoring turn must use the kept baseline.
       const restoring = this.overriddenApprovals.has(thread) && this.nativeApprovalPolicies.has(thread);
       if (msg.params.approvalPolicy != null && !restoring) this.nativeApprovalPolicies.set(thread, msg.params.approvalPolicy);
@@ -632,8 +715,30 @@ export class CodexPeer extends BasePeer {
       this.pending.delete(msg.id);
       if (msg.error) p?.reject(new Error(msg.error.message ?? "app-server rejected the request"));
       else p?.resolve(msg.result);
+      if (msg.error) this.retireRejectedModelSelection(link);
       return; // ours: the TUI never asked for it
     }
+    if (msg.id !== undefined && !msg.method && link.modelStarts.has(msg.id)) {
+      const selected = link.modelStarts.get(msg.id);
+      // A reused id has no trustworthy response correlation. Keep its tombstone until reattach;
+      // the first reply cannot prove that all duplicate requests rejected before native execution.
+      if (selected !== null) link.modelStarts.delete(msg.id);
+      if (selected && link === this.link && selected.epoch === this.contextEpoch && selected.thread === this.threadId) {
+        if (msg.error) {
+          // The final rejecting request may have an explicit client model and no selection.
+          // Retain only one still-unaccepted candidate until the known outstanding receipts drain.
+          if (selected.selection && !selected.nativeStarted && (this.nativeModels.get(selected.thread)?.sequence ?? 0) < selected.sequence)
+            link.rejectedModelSelection = { selection: selected.selection, epoch: selected.epoch, thread: selected.thread };
+        } else {
+          const acceptedModel = this.acceptModelStart(selected, selected.explicit ?? selected.selection?.model, !selected.clientModel);
+          if (acceptedModel) try {
+            if (selected.explicit !== undefined) this.opts.onNativeModelApplied?.(selected.explicit);
+            else selected.selection?.applied(acceptedModel.model);
+          } catch { /* Native acceptance remains authoritative. */ }
+        }
+      }
+      if (msg.error) this.retireRejectedModelSelection(link);
+    }
     if (typeof msg.result?.userAgent === "string") this.version = /^[^/\s]+\/(\d+\.\d+\.\d+(?:-[\w.]+)?)/.exec(msg.result.userAgent)?.[1] ?? this.version;
     const tracked = msg.id !== undefined && !msg.method ? link.tracked.get(msg.id) : undefined;
     if (tracked && link.tracked.delete(msg.id)) {
@@ -743,6 +848,7 @@ export class CodexPeer extends BasePeer {
     this.turnDeliveries.clear(); this.unboundDeliveries.clear();
     this.tokenTotal = undefined; this.tokenKinds = undefined;
     this.freshThread = fresh;
+    link.rejectedModelSelection = undefined;
     this.link = link;
     this.threadId = threadId;
     this.onDoing?.("reset");
@@ -840,6 +946,10 @@ export class CodexPeer extends BasePeer {
       return;
     }
     if (method === "turn/started") {
+      link.rejectedModelSelection = undefined;
+      // The notification has no request id. Conservatively protect every outstanding capture on
+      // this bound thread rather than retiring a possibly accepted selection on a later RPC error.
+      for (const start of link.modelStarts.values()) if (start && start.thread === this.threadId) start.nativeStarted = true;
       const nativeTurn = params.turn?.id ?? `unknown:${Date.now()}`;
       this.unboundAccepted = false;
       this.activeTurns.add(nativeTurn);
@@ -890,7 +1000,7 @@ export class CodexPeer extends BasePeer {
       this.deltas.clear();
       // Addressed like every other adapter's answer (issue #3): each sender it answers, including one steered in;
       // the bus maps a condensed delivery's `digest` back to the senders it replaced, a steer beside it or not.
-      if (this.lastAnswer) this.onMessage?.(this.lastAnswer, inReplyTo ? { inReplyTo, to } : {});
+      if (this.lastAnswer) this.finalAnswer(this.lastAnswer, inReplyTo ? { inReplyTo, to } : {}, params.turn?.status === "completed");
       this.lastAnswer = "";
       this.setState("idle");
     }

package/src/adapters/codex-review-isolation.ts

@@ -1,3 +1,4 @@
+import { isNativeModelToken } from "./model-token.ts";
 import { DENY_NAMES, DENY_SEGMENTS } from "@staix/agent-mem/platform";
 import { assessVersion, COMPAT } from "./compat.ts";
 import { createHash } from "node:crypto";
@@ -182,6 +183,7 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
   // #722: the proof leg being run, so a refusal names a class and never text from the native CLI. `timedOut` is set by `run` only.
   let leg: ReviewerCauseClass = "binary", timedOut = false;
   try {
+    if (ctx.modelOverride !== undefined && !isNativeModelToken(ctx.modelOverride)) throw new Error("invalid runtime model token");
     const cwd = realPath(ctx.cwd), env = peerChildEnv(ctx.peer), bound = resolveCommand(ctx, cwd);
     const initialBinaryMetadata = bound.files.map(metadata).join(";");
     // Hash content once per receipt, then fence the identity with dev/ino/size/mtime/ctime metadata.
@@ -282,7 +284,7 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
     if (!current()) throw new Error("binary or config changed during proof");
     const cleanupRoot = root;
     const launchProfile = digest(toml({ profile, servers, policy }));
-    return { command: bound.command, args: ["exec", "--ephemeral", "--ignore-user-config", "--ignore-rules", "--json", "--color", "never", "-C", cwd, ...policy, ...permissions, ...mcp, "-c", `developer_instructions=${toml(ctx.systemPrompt)}`, "-"], env,
+    return { command: bound.command, args: ["exec", ...(ctx.modelOverride === undefined ? [] : ["-m", ctx.modelOverride]), "--ephemeral", "--ignore-user-config", "--ignore-rules", "--json", "--color", "never", "-C", cwd, ...policy, ...permissions, ...mcp, "-c", `developer_instructions=${toml(ctx.systemPrompt)}`, "-"], env,
       current: () => { try { return current(); } catch { return false; } },
       cleanup: () => rmSync(cleanupRoot, { recursive: true, force: true }),
       isolation: { backend: "codex", version, binary: `sha256:${binaryHash}`, profile: `sha256:${launchProfile}`, readOnly: true, strictMcp: true, ephemeral: true,

package/src/adapters/compat.ts

@@ -49,18 +49,23 @@ export const COMPAT = {
     parse: out => plain(out.trim()),
     trustNote: "Every launch still builds the private config, exact two-tool agent file and task-bound MCP; the native tool allowlist behaviour of an untested version is not re-proven.",
     receipt: "docs/verification/2026-11-06-kimi-251-reviewer-compat.md" },
+  // The interactive TUI's native-turn and background readbacks are a separate contract from headless ACP and reviewer isolation.
+  "kimi-tui": { label: "Kimi TUI completion facts", verified: ["2.5.2"], gate: "contract", probe: ["kimi", "--version"],
+    parse: out => plain(out.trim()),
+    trustNote: "Only 2.5.2 has a live receipt for turn.prompt/turn.ended/prompt completion rows, background task inventory and launcher-bound plugin hooks. Another version keeps completion receipts disabled.",
+    receipt: "docs/verification/2026-11-08-kimi-tui-completion-1282.md" },
   jcode: { label: "Jcode", verified: ["0.98.1", "0.99.0", "0.99.1"], line: { min: "0.98.0", below: "1.0.0" }, gate: "contract", probe: ["jcode", "--quiet", "version", "--json"], config: "jcode_cmd",
     parse: out => { try { const v = JSON.parse(out).semver; return typeof v === "string" ? plain(v) : undefined; } catch { return undefined; } },
     trustNote: "The ACP, serve and MCP contract was verified on 0.98.1 and 0.99.1 and steering on 0.99.0 and 0.99.1; an untested version may change them.",
     receipt: "docs/verification/2026-10-26-jcode-0.99.1.md" },
-  agy: { label: "agy", verified: ["1.4.2", "1.4.7", "1.4.12"], line: { min: "1.4.0", below: "1.5.0" }, gate: "contract", probe: ["agy", "--version"],
+  agy: { label: "agy", verified: ["1.4.2", "1.4.7", "1.4.12", "1.5.3"], line: { min: "1.4.0", below: "1.5.0" }, gate: "contract", probe: ["agy", "--version"],
     parse: out => plain(out.trim()),
-    trustNote: "Only 1.4.2, 1.4.7 and 1.4.12 are T0-verified; the plugin MCP and hook contract of another version is unverified.",
-    receipt: "docs/verification/2026-11-03-agy-1.4.12-launcher-nonce.md" },
-  qwen: { label: "Qwen Code", verified: ["0.25.0", "0.26.0", "0.26.1", "0.26.4", "0.26.5", "0.26.8"], gate: "contract", probe: ["qwen", "--version"], config: "qwen_cmd",
+    trustNote: "Exact 1.5.3 repeats the account-free CLI/plugin MCP, hooks, normal close and actual-launcher nonce legs; existing 1.4.x verified receipts remain unchanged. Other 1.5.x versions, real model/account behavior, headless ACP and native permission mappings remain unverified.",
+    receipt: "docs/verification/2026-11-08-agy-1.5.3.md" },
+  qwen: { label: "Qwen Code", verified: ["0.25.0", "0.26.0", "0.26.1", "0.26.4", "0.26.5", "0.26.8", "0.26.9"], gate: "contract", probe: ["qwen", "--version"], config: "qwen_cmd",
     parse: out => plain(out.trim()),
-    trustNote: "Native ACP identity, mode ids and permission callbacks were re-checked without inference on 0.26.4, 0.26.5 and 0.26.8 (macOS arm64 and Linux x86_64); real model turns remain unverified. Another version may change those contracts.",
-    receipt: "docs/verification/2026-11-06-qwen-0268-acp.md" },
+    trustNote: "Native ACP identity, mode ids and permission callbacks were re-checked without inference on 0.26.4, 0.26.5 and 0.26.8 (macOS arm64 and Linux x86_64); exact 0.26.9 repeats those account-free probes on macOS arm64. Real model turns and Linux repetition of 0.26.9 remain unverified. Another version may change those contracts.",
+    receipt: "docs/verification/2026-11-08-qwen-0269-acp.md" },
   // Receipt: docs/verification/2026-10-25-qwen-dual-output-t0.md. The dual-output contract (input file, event file, can_use_tool control requests) is its own entry:
   // the ACP receipts of the headless `qwen` entry say nothing about it, so that entry is not widened and this one carries no `line`.
   "qwen-dual": { label: "Qwen Code dual-output TUI", verified: ["0.26.1"], gate: "contract", probe: ["qwen", "--version"], config: "qwen_cmd",

package/src/adapters/definitions/builtin-metadata.ts

@@ -23,6 +23,7 @@ import { CLAUDE_DISPLAY, CODEX_DISPLAY, KIMI_DISPLAY, PI_DISPLAY, LOCAL_DISPLAY,
 import { CLAUDE_RECOVERY_SESSION, CODEX_RECOVERY_SESSION, KIMI_RECOVERY_SESSION, PI_RECOVERY_SESSION, LOCAL_RECOVERY_SESSION, JCODE_RECOVERY_SESSION } from "./native-recovery.ts";
 import { claudeWindows, codexWindows } from "./native-quota.ts";
 import { claudeContext, codexContext, acpContextValue, jcodeContextValue } from "./native-context.ts";
+import { KIMI_TUI_FACTS_HOOK } from "../kimi-tui-facts.ts";
 import type { AdapterDefinition } from "../registry-types.ts";
 import type { PeerAdapter } from "../../hub/peers.ts";
 
@@ -60,6 +61,7 @@ const CLAUDE_REVIEWER_VARIANT: AdapterDefinition = {
 /** #525 R5a: no idle child; the host binds an owned worktree and one native session per task. */
 const CLAUDE_IMPLEMENTER_VARIANT: AdapterDefinition = {
   api: 1, kind: "claude", displayName: "Claude Code implementer", family: "claude", transport: "hub-native",
+  modelOverride: { boundary: "turn" },
   roles: Object.freeze(["implementer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
   start: { create: createClaudeImplementer, daemonPort: "claude-implementer", forms: headlessForms, defaultForm: "headless", conductorStartable: true, hubSwitches: [], ownedFlags: [] },
   identity: { mcp: "env", currentChild: true }, instances: { mode: "headless", roles: ["implementer", "verifier"], modelSelect: true },
@@ -92,6 +94,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     reviewerVariant: CODEX_REVIEWER_VARIANT,
     projection: { roleRank: 1, startRank: 1, helpRank: 1, plannerEligible: true },
     api: 1, kind: "codex", questionWaitMs: 45000, displayName: "Codex", family: "codex", transport: "codex-appserver",
+    modelOverride: { boundary: "turn" },
     roles: Object.freeze(["implementer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
     start: { create: createCodex, daemonPort: "codex-appserver", forms: dualForms, defaultForm: "tui", launch: codexNativeLaunch, version: codexObservedVersion, ...CODEX_LAUNCH_POLICY, conductorStartable: true, upStart: { allowed: true, default: true },
       unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--remote", "--remote-auth-token-env", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]) },
@@ -105,6 +108,8 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     reviewerVariant: KIMI_REVIEWER_VARIANT,
     projection: { roleRank: 2, startRank: 2, helpRank: 2, plannerEligible: true },
     api: 1, kind: "kimi", questionWaitMs: 45000, displayName: "Kimi Code", family: "kimi", transport: "acp",
+    modelOverride: { boundary: "turn", acp: { admission: { nativeIdentity: true }, agentName: "Kimi Code CLI", version: "2.5.2",
+      setter: "set_config_option", modelUpdate: "config_option_update", receipt: "docs/verification/2026-11-08-kimi-252-model-setter-1317.md" } },
     roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
     start: { create: createKimi, acpCommand: kimiAcpCommand, explicitHeadlessMode: true, planCommand: () => "ahub kimi", daemonPort: "acp", forms: dualForms, defaultForm: "tui", conductorStartable: true, upStart: { allowed: true }, hubSwitches: [], ownedFlags: [] },
     // ACP sessions carry headless identity; the existing CLI alone owns the TUI's project MCP entry.
@@ -114,12 +119,13 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     permission: { grants: { ask: "Kimi asks as it does on its own", "ask-when-needed": "Kimi's yolo mode: it asks only where it judges it must", "never-ask": "Kimi's auto mode: nothing asks" },
       unmanagedForms: Object.freeze(["tui"] as const), unmanagedStatusNote: "Kimi approves tools in its own TUI; no hub permission mode", unmanagedNote: "Kimi approves tools and selects its permission mode in its own TUI; no hub permission mode" },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "acp", ...KIMI_RECOVERY_SESSION, crashPlan: kimiCrashPlan },
-    turnEnd: "adapter", settle: { signal: "prompt-response" }, budget: { account: "kimi", resetSoftTokensOnResume: true, context: { source: "acp_usage_update", read: acpContextValue } }, capabilities: { watch: true }, hooks: { recallPlatform: "kimi", recallSource: "kimi" },
+    turnEnd: "adapter", settle: { signal: "prompt-response" }, budget: { account: "kimi", resetSoftTokensOnResume: true, context: { source: "acp_usage_update", read: acpContextValue } }, capabilities: { watch: true }, hooks: { factsHook: KIMI_TUI_FACTS_HOOK, recallPlatform: "kimi", recallSource: "kimi" },
     cli: { command: "kimi", entry: { lifecycleAdmission: true, execute: runKimiEntry }, preview: previewKimi, usage: [["ahub kimi [--print-command] [--mode tui|headless] [--model <alias>]", "default: Kimi's own TUI, pull-only via hub_inbox; no push, steer, watchdog, console approvals or automatic quota handoff. Select headless for ACP"]], launchConfigKeys: ["kimi_cmd", "peers.kimi.start_mode"], stopNotice: form => form === "tui" ? "Kimi belongs to its own TUI terminal; end it in that terminal" : "", startWords: form => ["kimi", "--mode", form] }, display: KIMI_DISPLAY,
   },
   {
     projection: { roleRank: 4, startRank: 0, helpRank: 6, plannerEligible: false },
     api: 1, kind: "pi", questionWaitMs: 300000, title: "hub", titlePersistence: "native", enabledSwitchStartOnly: true, displayName: "Pi", family: "pi", transport: "hub-native",
+    modelOverride: { boundary: "turn" },
     roles: implementerRoles, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: true },
     start: { create: createPi, exclusiveStartRefusal: "Pi start is in progress; inspect status before retrying", refreshTools: true, explicitHeadlessMode: true, daemonPort: "pi-rpc", forms: dualForms, defaultForm: "tui", conductorStartable: true, upStart: { allowed: true }, autoStart: "pi.auto_start", conductorStartArgs: piConductorStartArgs, hubSwitches: [], ownedFlags: [] },
     identity: { mcp: "env" }, instances: { mode: "headless" },
@@ -133,6 +139,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
   {
     projection: { roleRank: 3, helpRank: 7, plannerEligible: false },
     api: 1, kind: "local", questionWaitMs: 300000, title: "hub", displayName: "Local worker", family: "local", transport: "hub-native",
+    modelOverride: { boundary: "turn" },
     roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: true, hubSandboxed: true },
     start: { create: createLocal, reconfigureWhileAttached: true, refreshTools: true, daemonPort: "local-worker", forms: headlessForms, defaultForm: "headless", conductorStartable: true, upStart: { allowed: true }, hubSwitches: [], ownedFlags: [] },
     identity: { mcp: "env" }, instances: { mode: "headless" },