@staix/agent-hub 0.18.0 → 0.20.0

package/src/adapters/acp.ts

@@ -10,6 +10,7 @@ export { QwenIdentityError } from "./definitions/qwen-native.ts";
 import { BasePeer } from "../hub/peers.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { AcpOwnedGroup } from "./acp-owned-group.ts";
+import type { StartForm } from "./registry-types.ts";
 
 export interface PermissionOption {
   optionId: string;
@@ -163,6 +164,9 @@ function jsonObject(text: string | undefined): object | undefined {
 
 /** ACP client (JSON-RPC 2.0, newline-delimited, over the child's stdio). One session, one prompt in flight. */
 export class AcpPeer extends BasePeer {
+  readonly deliveryOnly: boolean = true;
+  readonly hubOwned: boolean = true;
+  readonly form: StartForm = "headless";
   private permissionMode: PermissionMode;
   private readonly nativePolicy: AcpOptions["nativePolicy"];
   private modeUnknown = false;
@@ -256,6 +260,10 @@ export class AcpPeer extends BasePeer {
   recoveryMetadata(): Record<string, unknown> {
     return { launch: { kind: "acp", ...(this.opts.launchModel ? { model: this.opts.launchModel } : {}) }, ...(this.sessionId ? { sessionId: this.sessionId } : {}) };
   }
+  get nativeSession(): string | undefined {
+    const session = this.recoveryMetadata().sessionId;
+    return typeof session === "string" ? session : undefined;
+  }
 
   async start(): Promise<void> {
     if (this.opts.requireOwnedGroup && this.proc) throw new Error("Configured ACP still has a process; stop it before starting another");

package/src/adapters/agy/entry.ts

@@ -37,7 +37,7 @@ function runAgyTui(argv: string[], cwd: string, env: NodeJS.ProcessEnv): Promise
 /** #607: agy 1.4.x attaches the plugin MCP server at the first prompt, so the hub tools are listed from the second turn. */
 export const AGY_LAUNCH_NOTICE = "Antigravity: pull-only TUI; native permissions unmanaged, no hub sandbox; hub tools appear from the second turn (send any first prompt, then ask for hub work)";
 
-/** agy auto-updates, so the 1.4.x line launches; only 1.4.2 has a T0 receipt and other patches warn (#589). */
+/** agy auto-updates, so the 1.4.x line launches; only 1.4.2 and 1.4.7 have a T0 receipt and other patches warn (#589). */
 export function agyVersionGate(stdout: string): { ok: true; message?: string } | { ok: false; message: string } {
   // #691: the verified versions, the compatible line and the person's trust live in compat.ts.
   const verdict = assessVersion("agy", COMPAT.agy.parse(stdout));

package/src/adapters/channel-peer.ts

@@ -1,6 +1,7 @@
 import { BasePeer, type PeerAdapter } from "../hub/peers.ts";
 import type { Envelope } from "../hub/envelope.ts";
 import { definitionOf } from "./registry.ts";
+import type { StartForm } from "./registry-types.ts";
 
 /** Only the control socket operations the peer owns; authentication remains in the daemon. */
 export interface ChannelSocket {
@@ -12,6 +13,7 @@ export interface ChannelSocket {
 
 /** A peer that lives in another process and attaches over the control WS (the Claude channel plugin). */
 export class WsPeer extends BasePeer {
+  readonly form: StartForm = "tui";
   private generation = crypto.randomUUID();
   // Checkpoints become stale at hello/claim, before asynchronous recall finishes and attach changes delivery generation.
   private claimGeneration = crypto.randomUUID();
@@ -23,7 +25,7 @@ export class WsPeer extends BasePeer {
   private delivered = new Set<string>();
   private sock: ChannelSocket | undefined;
   private claimed: ChannelSocket | undefined;
-  private nativeSession: string | undefined;
+  private nativeTurnSession: string | undefined;
   private nativeActive = false;
   /** The attached session said it cannot show channel pushes (issue #205): the bus keeps its queue for `inbox`. */
   pullOnly = false;
@@ -66,7 +68,7 @@ export class WsPeer extends BasePeer {
     this.sock = sock;
     this.generation = crypto.randomUUID();
     this.delivered.clear();
-    this.nativeSession = undefined;
+    this.nativeTurnSession = undefined;
     this.nativeActive = false;
     this.pullOnly = this.claimedPullOnly; // before idle: the idle transition drains
     // Native TUI readback in #493 proves important channel input can be consumed before the turn ends.
@@ -112,13 +114,13 @@ export class WsPeer extends BasePeer {
   owns(sock: ChannelSocket): boolean { return this.sock === sock; }
   nativeStarted(session: string): void {
     if (!this.sock) return;
-    this.nativeSession = session;
+    this.nativeTurnSession = session;
     this.nativeActive = true;
     this.setState("busy");
   }
   nativeStopped(session: string): boolean {
-    if (!this.sock || (this.nativeSession !== undefined && this.nativeSession !== session)) return false;
-    this.nativeSession = session;
+    if (!this.sock || (this.nativeTurnSession !== undefined && this.nativeTurnSession !== session)) return false;
+    this.nativeTurnSession = session;
     this.nativeActive = false;
     this.setState("idle");
     return true;

package/src/adapters/claude-channel.ts

@@ -400,9 +400,13 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
       || !args.input || typeof args.input !== "object" || Array.isArray(args.input)
       || typeof args.tool_use_id !== "string" || !args.tool_use_id.length || args.tool_use_id.length > 256) return deny("invalid native permission request");
     try {
-      // Keep original arguments only in this native request closure; the host returns a decision, not replacements.
-      const res = await hub.request({ t: "permission_request", tool: args?.tool_name, input: args?.input }, 3_605_000);
-      return res.ok === true && res.behavior === "allow" ? text(JSON.stringify({ behavior: "allow", updatedInput: args?.input })) : deny(typeof res.message === "string" ? res.message : "permission denied");
+      // Only this fixed client capability permits host wrapper grants; older clients keep person approval.
+      const res = await hub.request({ t: "permission_request", tool: args?.tool_name, input: args?.input, wrapperProtocol: 1 }, 3_605_000);
+      if (res.ok !== true || res.behavior !== "allow") return deny(typeof res.message === "string" ? res.message : "permission denied");
+      if (res.wrapperProtocol !== undefined && res.wrapperProtocol !== 1) return deny("unsupported host execution response");
+      const updated = res.wrapperProtocol === 1 ? res.updatedInput : undefined;
+      if (res.wrapperProtocol === 1 && (args.tool_name !== "Bash" || !updated || typeof updated !== "object" || Array.isArray(updated) || typeof updated.command !== "string")) return deny("invalid host execution response");
+      return text(JSON.stringify({ behavior: "allow", updatedInput: updated ?? args?.input }));
     } catch { return deny("hub permission unavailable"); }
   }
   if (name === "hub_delivery_done" && channel) {

package/src/adapters/claude-implementer.ts

@@ -23,6 +23,8 @@ export interface ClaudeImplementerOptions {
   factsHook: string;
   systemPrompt: string;
   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;
   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";
@@ -38,10 +40,10 @@ export interface ClaudeImplementerOptions {
   prove?(): Promise<() => boolean>;
 }
 export interface ImplementerTurn { sessionId: string; resume: boolean; persistent: boolean }
-export function claudeImplementerArgs(turn: ImplementerTurn, mcp: string, settings: string, prompt: string): string[] {
+export function claudeImplementerArgs(turn: ImplementerTurn, mcp: string, settings: string, prompt: string, model?: string): string[] {
   return ["-p", "--output-format", "stream-json", "--verbose", turn.resume ? "--resume" : "--session-id", turn.sessionId,
     ...(!turn.persistent ? ["--no-session-persistence"] : []), "--strict-mcp-config", "--mcp-config", mcp, "--setting-sources", "", "--settings", settings,
-    "--permission-mode", "default", "--permission-prompts", "host", "--permission-prompt-tool", "mcp__agent-hub__hub_permission_request",
+    ...(model ? ["--model", model] : []), "--permission-mode", "default", "--permission-prompts", "host", "--permission-prompt-tool", "mcp__agent-hub__hub_permission_request",
     "--allowedTools", ...IMPLEMENTER_HUB_TOOL_NAMES.map(name => `mcp__agent-hub__${name}`), "--append-system-prompt", prompt];
 }
 
@@ -70,6 +72,7 @@ export async function proveClaudeImplementer(peer: string, command: readonly str
 /** One owned print child at a time. Idle holds no native process; task continuity is ids-only on disk. */
 export class ClaudeImplementerPeer extends BasePeer {
   readonly hubNative = true;
+  readonly hubOwned: boolean = true;
   private generation = 0;
   private owned: OwnedPrintChild | undefined;
   private running: Promise<void> | undefined;
@@ -184,7 +187,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), cwd: this.options.cwd,
+        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,
           input: group.envs.map(frame).join("\n\n"), env, current, stop: this.options.stopChild,
           onSpawn: () => {
             try {

package/src/adapters/codex-appserver.ts

@@ -2,7 +2,7 @@ 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";
 import type { PermissionMode } from "../hub/permission-mode.ts";
-import { BasePeer } from "../hub/peers.ts";
+import { BasePeer, type FrontendProxyPort } from "../hub/peers.ts";
 import { codexContext, type ContextReading } from "../hub/context-window.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import type { ContextReader } from "./registry-types.ts";
@@ -82,6 +82,7 @@ const TRACKED = new Set(["thread/start", "thread/resume"]);
  * TUI's, and their responses are swallowed.
  */
 export class CodexPeer extends BasePeer {
+  readonly frontendProxy: FrontendProxyPort;
   private permissionMode: PermissionMode;
   private readonly actionWaits = new Map<AbortController, { link: Link; turn: string | undefined }>();
   get actionGated(): boolean { return this.opts.actionGate !== undefined; }
@@ -136,6 +137,13 @@ export class CodexPeer extends BasePeer {
   ) {
     super(id, opts.watchdogMs);
     this.permissionMode = opts.permissionMode ?? "ask";
+    const owner = this;
+    this.frontendProxy = {
+      get url() { return owner.proxyUrl; },
+      get attached() { return owner.proxyAttached; },
+      setStartupPermissionMode: this.setStartupPermissionMode.bind(this),
+      clearPermissionMode: this.clearPermissionMode.bind(this),
+    };
   }
 
   recoveryMetadata(): Record<string, unknown> {
@@ -149,6 +157,7 @@ export class CodexPeer extends BasePeer {
   get thread(): string {
     return this.threadId;
   }
+  get nativeSession(): string | undefined { return this.threadId || undefined; }
 
   get proxyUrl(): string {
     return `ws://127.0.0.1:${this.server?.port ?? this.opts.proxyPort}`;
@@ -694,6 +703,7 @@ export class CodexPeer extends BasePeer {
       link.up.send(JSON.stringify({ method: "thread/revert", id, params: { threadId: this.threadId, beforeTurnId: turnId } }));
     });
   }
+  revertTurn(nativeTurn: string): Promise<void> { return this.revert(nativeTurn); }
 
   /** account/rateLimits/read through the TUI's connection, with a hub id so the answer never reaches the TUI. */
   private readUsage(): void {

package/src/adapters/compat.ts

@@ -21,48 +21,62 @@ export interface CompatPolicy {
   parse: (stdout: string) => string | undefined;
   /** What runtime checks still decide after trust (isolation) or what stays unverified (contract). */
   trustNote: string;
+  /** The last receipt in docs/verification whose model-free procedure a new version repeats (#843). */
+  receipt: string;
   /** The config key that selects this kind's executable, when one exists. */
-  config?: "codex_bin" | "jcode_cmd" | "qwen_cmd";
+  config?: "codex_bin" | "jcode_cmd" | "qwen_cmd" | "pi.cmd";
 }
 
 const plain = (text: string) => text.length <= 64 && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(text) ? text : undefined;
 export const COMPAT = {
-  // Receipt: docs/verification/2026-10-23-headless-claude-permissions.md
-  "claude-implementer": { label: "Claude headless implementer", verified: ["2.1.309"], gate: "contract", probe: ["claude", "--version"],
+  // Receipt: docs/verification/2026-10-26-pi-140-compat.md
+  pi: { label: "Pi", verified: ["1.4.0"], gate: "contract", probe: ["pi", "--version"], config: "pi.cmd",
+    parse: out => plain(out.trim()),
+    trustNote: "The model-free extension load, RPC session identity and managed tool receipt path were checked on 1.4.0. Permissions remain host-owned; account-backed inference and another version's extension contract are unverified.",
+    receipt: "docs/verification/2026-10-26-pi-140-compat.md" },
+  // Transport receipts: docs/verification/2026-10-23-headless-claude-permissions.md; 2.1.310: docs/verification/2026-10-26-claude-implementer-2.1.310.md; host-wrapper receipt below repeats with them.
+  "claude-implementer": { label: "Claude headless implementer", verified: ["2.1.309", "2.1.310"], gate: "contract", probe: ["claude", "--version"],
     parse: out => plain(out.trim().replace(/ \(Claude Code\)$/, "")),
-    trustNote: "The native prompt-tool allow, deny, MCP error/disconnect and hook-failure fallthrough have an isolated receipt. No dontAsk/bypass fallback exists; another version's permission behavior is unverified." },
+    trustNote: "The native prompt-tool transport and host-wrapper rewrite, environment isolation and replay contract have isolated receipts. No dontAsk/bypass fallback exists; another version's permission or rewrite behavior is unverified.",
+    receipt: "docs/verification/2026-10-26-headless-claude-shell-context.md" },
   // 0.163.0 receipt: docs/verification/2026-10-22-codex-reviewer-isolation.md; 0.164.0 receipt: docs/verification/2026-10-24-codex-0164-reviewer-isolation.md
   "codex-review": { label: "Codex reviewer (codex-cli)", verified: ["0.146.0", "0.163.0", "0.164.0"], gate: "isolation", probe: ["codex", "--version"], config: "codex_bin",
     parse: out => plain(out.trim().replace(/^codex-cli /, "")),
-    trustNote: "Every launch still proves the MCP inventory, Apps/plugins/hooks disabled, sandbox read/write denial and the binary fence; a failed leg still refuses. Trust covers only the source-level claims those probes cannot see (docs/verification/2026-10-19-reviewer-isolation.md)." },
-  // Kimi 2.3.0 / Qwen 0.26.0 receipt: docs/verification/2026-10-22-kimi-qwen-compat.md; Kimi 2.3.1: docs/verification/2026-10-25-kimi-231-reviewer-compat.md
-  "kimi-review": { label: "Kimi reviewer (kimi-code)", verified: ["2.2.0", "2.3.0", "2.3.1"], gate: "isolation", probe: ["kimi", "--version"],
+    trustNote: "Every launch still proves the MCP inventory, Apps/plugins/hooks disabled, sandbox read/write denial and the binary fence; a failed leg still refuses. Trust covers only the source-level claims those probes cannot see (docs/verification/2026-10-19-reviewer-isolation.md).",
+    receipt: "docs/verification/2026-10-24-codex-0164-reviewer-isolation.md" },
+  // Kimi 2.3.0 / Qwen 0.26.0 receipt: docs/verification/2026-10-22-kimi-qwen-compat.md; Kimi 2.3.1: docs/verification/2026-10-25-kimi-231-reviewer-compat.md; Kimi 2.3.2: docs/verification/2026-10-26-kimi-232-reviewer-compat.md
+  "kimi-review": { label: "Kimi reviewer (kimi-code)", verified: ["2.2.0", "2.3.0", "2.3.1", "2.3.2"], gate: "isolation", probe: ["kimi", "--version"],
     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." },
-  jcode: { label: "Jcode", verified: ["0.98.1", "0.99.0"], line: { min: "0.98.0", below: "1.0.0" }, gate: "contract", probe: ["jcode", "--quiet", "version", "--json"], config: "jcode_cmd",
+    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-10-26-kimi-232-reviewer-compat.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 steering on 0.99.0; an untested version may change them." },
-  agy: { label: "agy", verified: ["1.4.2"], line: { min: "1.4.0", below: "1.5.0" }, gate: "contract", probe: ["agy", "--version"],
+    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"], line: { min: "1.4.0", below: "1.5.0" }, gate: "contract", probe: ["agy", "--version"],
     parse: out => plain(out.trim()),
-    trustNote: "Only 1.4.2 is T0-verified; the plugin MCP and hook contract of another version is unverified." },
-  qwen: { label: "Qwen Code", verified: ["0.25.0", "0.26.0"], gate: "contract", probe: ["qwen", "--version"], config: "qwen_cmd",
+    trustNote: "Only 1.4.2 and 1.4.7 are T0-verified; the plugin MCP and hook contract of another version is unverified.",
+    receipt: "docs/verification/2026-10-26-agy-1.4.7.md" },
+  qwen: { label: "Qwen Code", verified: ["0.25.0", "0.26.0", "0.26.1"], gate: "contract", probe: ["qwen", "--version"], config: "qwen_cmd",
     parse: out => plain(out.trim()),
-    trustNote: "Native ACP identity and mode ids have dated receipts; 0.26.0 permission callbacks were checked without inference. Another version may change those contracts." },
+    trustNote: "Native ACP identity, mode ids and permission callbacks were re-checked without inference on 0.26.1; its two ACP fixes were judged not to change the hub contract. Another version may change those contracts.",
+    receipt: "docs/verification/2026-10-26-qwen-0261-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",
     parse: out => plain(out.trim()),
-    trustNote: "The dual-output file contract (submit and confirmation_response input, user/assistant/stream_event/control events, session_start identity) was verified on 0.26.1 only. A hub deny ends the turn without any Qwen event, and no external stop of a running turn exists; another version may change either." },
+    trustNote: "The dual-output file contract (submit and confirmation_response input, user/assistant/stream_event/control events, session_start identity) was verified on 0.26.1 only. A hub deny ends the turn without any Qwen event, and no external stop of a running turn exists; another version may change either.",
+    receipt: "docs/verification/2026-10-25-qwen-dual-output-t0.md" },
 } as const satisfies Record<string, CompatPolicy>;
 export type CompatId = keyof typeof COMPAT;
-type CommandConfig = { codex_bin: string; jcode_cmd: string[]; qwen_cmd: string[] };
+type CommandConfig = { codex_bin: string; jcode_cmd: string[]; qwen_cmd: string[]; pi?: { cmd: string[] } };
 /** The configured executables the native gates use; the rest probe their PATH default. */
 export function configuredCommands(config: CommandConfig): Partial<Record<CompatId, readonly string[]>> {
   const out: Partial<Record<CompatId, readonly string[]>> = {};
   for (const [id, policy] of Object.entries(COMPAT) as [CompatId, CompatPolicy][]) {
     if (!policy.config) continue;
-    const value = config[policy.config];
-    out[id] = typeof value === "string" ? [value] : value;
+    const value = policy.config === "pi.cmd" ? config.pi?.cmd : config[policy.config];
+    if (value !== undefined) out[id] = typeof value === "string" ? [value] : value;
   }
   return out;
 }

package/src/adapters/conformance/enrollment.ts

@@ -4,7 +4,7 @@ import { isFixedBuiltinDefinition } from "../registry.ts";
 /** Stable generic ACP legs; both actual test registration and enrollment validation consume this catalog. */
 export const ACP_LEGS = Object.freeze(["native-approval-rpc", "native-mode-ack", "native-quota", "watchdog-generation"] as const);
 export type AcpLeg = typeof ACP_LEGS[number];
-/** Reserved until 2b supplies the restrictive ACP product members; not an executable ACP leg yet. */
+/** Mandatory product invariant, asserted for generic and owned ACP factories rather than skipped protocol legs. */
 export const ACP_PORTS_LEG = "restrictive-ports";
 export const NATIVE_PROOF_PORTS_LEG = "native-proof-ports";
 /** No unsupported key or non-generic ACP engine can silently escape an executable catalog leg. */
@@ -18,8 +18,9 @@ export function assertAcpLegEnrollment(definitions: readonly AdapterDefinition[]
       if (!row || !isFixedBuiltinDefinition(row.definition)) throw new Error(`${key}: only fixed builtin proof legs may be nonapplicable`);
       continue;
     }
-    if (separator < 1 || !acp.has(kind) || !(ACP_LEGS as readonly string[]).includes(leg) && leg !== ACP_PORTS_LEG) throw new Error(`${key}: stale or unknown unsupported ACP leg`);
-    if (leg === ACP_PORTS_LEG && reason !== "ports added in 2b") throw new Error(`${key}: reserved ACP ports leg requires reason ports added in 2b`);
+    if (separator < 1 || !acp.has(kind)) throw new Error(`${key}: stale or unknown unsupported ACP leg`);
+    if (leg === ACP_PORTS_LEG) throw new Error(`${key}: mandatory ACP restrictive ports leg cannot be unsupported`);
+    if (!(ACP_LEGS as readonly string[]).includes(leg)) throw new Error(`${key}: stale or unknown unsupported ACP leg`);
   }
   for (const definition of acp.values()) if (definition.start.daemonPort !== "acp") {
     for (const leg of ACP_LEGS) {
@@ -50,7 +51,6 @@ export function assertEnrollment(definitions: readonly AdapterDefinition[], enro
   }
   for (const { id, definition } of rows) {
     if (isFixedBuiltinDefinition(definition) && !Object.hasOwn(unsupportedLegs, `${id}:${NATIVE_PROOF_PORTS_LEG}`)) throw new Error(`${id}: native proof ports need an explicit nonapplicable reason`);
-    if (definition.transport === "acp" && !Object.hasOwn(unsupportedLegs, `${id}:${ACP_PORTS_LEG}`)) throw new Error(`${id}: ACP restrictive ports require the reserved 2b reason`);
     if (!enrolled.includes(id) && !Object.hasOwn(unsupported, id)) throw new Error(`${id}: no conformance fixture or unsupported reason`);
     if (definition.transport === "acp" && !enrolled.includes(id)) throw new Error(`${id}: every ACP definition must run the ACP legs`);
     if (id.endsWith(":reviewer") && !definition.reviewer) throw new Error(`${id}: reviewer variant lacks reviewer policy`);

package/src/adapters/conformance/factories.ts

@@ -1,7 +1,7 @@
 import type { AdapterDefinition, CreateContext, DaemonPorts } from "../registry-types.ts";
 import type { PeerAdapter } from "../../hub/peers.ts";
 import { join } from "node:path";
-import { assertNativeProofPorts } from "./kit.ts";
+import { assertAcpProductPorts, assertNativeProofPorts } from "./kit.ts";
 
 /** The supplied definition creates its actual adapter, with only this fixture's transport options. */
 export function createFromDefinition<T extends PeerAdapter>(definition: AdapterDefinition, daemon: DaemonPorts): T {
@@ -10,6 +10,7 @@ export function createFromDefinition<T extends PeerAdapter>(definition: AdapterD
   const product = definition.start.create({ instance: definition.kind, projectRoot: options.cwd, stateDir: options.stateDir ?? join(options.cwd, "state"),
     kindConfig: {}, permission: "ask", mcpServers: options.mcpServers ?? [], daemon }) as T;
   assertNativeProofPorts(definition, product);
+  assertAcpProductPorts(definition, product);
   return product;
 }
 /** Explicit watchdog seam on the factory-created implementation, replacing direct test subclasses. */

package/src/adapters/conformance/fakes/pi-rpc.ts

@@ -1,6 +1,7 @@
 import { createInterface } from "node:readline";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
+if (process.argv.includes("--version")) { console.log("1.4.0"); process.exit(0); }
 const option = (flag: string) => process.argv.includes(flag) ? process.argv[process.argv.indexOf(flag) + 1] : undefined;
 const empty = process.argv.includes("--empty-session");
 const dir = option("--session-dir")!;

package/src/adapters/conformance/kit.ts

@@ -24,6 +24,15 @@ export interface AdapterConformance {
   create(): Promise<ConformanceFixture>;
 }
 
+/** Every ACP factory product keeps the transport's restrictive delivery and ownership contract. */
+export function assertAcpProductPorts(definition: AdapterDefinition | undefined, product: PeerAdapter): void {
+  if (definition?.transport !== "acp") return;
+  for (const port of ["deliveryOnly", "hubOwned"] as const) {
+    if (product[port] !== true) throw new Error(`${definition.kind}: ACP restrictive port ${port} must be true`);
+  }
+  if (product.form !== "headless") throw new Error(`${definition.kind}: ACP restrictive port form must be headless`);
+}
+
 /** Presence itself is forbidden on a foreign product: even an undefined native proof port must fail the kit. */
 export function assertNativeProofPorts(definition: AdapterDefinition | undefined, product: PeerAdapter): void {
   if (isFixedBuiltinDefinition(definition)) return;
@@ -38,6 +47,7 @@ export function registerConformance(adapter: AdapterConformance): void {
     const f = await adapter.create();
     try {
       assertNativeProofPorts(adapter.definition, f.peer);
+      assertAcpProductPorts(adapter.definition, f.peer);
       expect(f.peer.id).toBe(adapter.kind);
       expect(f.peer.state).toBe("idle");
       const envelope: Envelope = newEnvelope("user", "conformance ping", { to: [adapter.kind] });

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

@@ -85,8 +85,8 @@ const CLAUDE_IMPLEMENTER_VARIANT: AdapterDefinition = {
   api: 1, kind: "claude", displayName: "Claude Code implementer", family: "claude", transport: "hub-native",
   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"] },
-  permission: { grants: { ask: "every write, edit and shell command asks", "ask-when-needed": "file tools inside the owned worktree may run automatically; shell and protected paths ask" } },
+  identity: { mcp: "env", currentChild: true }, instances: { mode: "headless", roles: ["implementer", "verifier"], modelSelect: true },
+  permission: { grants: { ask: "every write, edit and shell command asks", "ask-when-needed": "file tools, proven read-only shell commands and bound task commands inside the owned worktree may run automatically; protected paths and other commands ask" } },
   session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: false, launchKind: "claude-implementer", crashPlan: () => ({ resume: {}, how: "Claude implementer resumes its recorded per-task sessions" }) },
   turnEnd: "adapter", budget: { account: "claude" },
   cli: { command: "claude", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY,

package/src/adapters/definitions/native-factories.ts

@@ -34,8 +34,13 @@ export function createQwenDual(ctx: CreateContext): PeerAdapter {
 export function createPi(ctx: CreateContext): PeerAdapter {
   if (!("pi" in ctx.daemon)) throw new Error("Pi requires its Pi transport options");
   if (ctx.permission === "read-only") throw new Error("Pi has no verified read-only permission mapping");
-  const { PiPeer } = require("../pi.ts") as typeof import("../pi.ts");
-  return new PiPeer(ctx.instance, ctx.daemon.pi);
+  const { PiPeer, PiVersionRefusal, piVersionAsync } = require("../pi.ts") as typeof import("../pi.ts");
+  const options = ctx.daemon.pi;
+  return new PiPeer(ctx.instance, options, async () => {
+    const verdict = await piVersionAsync(options.cmd ?? ["pi"], options.cwd);
+    if (!verdict.ok) throw new PiVersionRefusal(verdict);
+    if (verdict.note) options.log?.(verdict.note);
+  });
 }
 
 export function createLocal(ctx: CreateContext): PeerAdapter {

package/src/adapters/definitions/reviewer-variants.ts

@@ -19,9 +19,9 @@ function reviewerVariant(kind: string, displayName: string, reviewer: NonNullabl
     reviewer, cli: { command: kind, startWords: () => [] }, display,
   };
 }
-const codexVariant = reviewerVariant("codex", "Codex reviewer", { backend: codexReviewerBackend, defaultPool: true, declaration: "explicit" }, CODEX_DISPLAY);
+const codexVariant = reviewerVariant("codex", "Codex reviewer", { backend: codexReviewerBackend, defaultPool: true, declaration: "explicit", scope: "code" }, CODEX_DISPLAY);
 export const CODEX_REVIEWER_VARIANT: AdapterDefinition = { ...codexVariant, start: { ...codexVariant.start, create: createCodexReviewer } };
-export const KIMI_REVIEWER_VARIANT = reviewerVariant("kimi", "Kimi reviewer", { backend: kimiReviewerBackend, defaultPool: true, declaration: "explicit" }, KIMI_DISPLAY);
+export const KIMI_REVIEWER_VARIANT = reviewerVariant("kimi", "Kimi reviewer", { backend: kimiReviewerBackend, defaultPool: true, declaration: "explicit", scope: "code" }, KIMI_DISPLAY);
 /** Data-only declared placeholder for route explanations; no factory, backend or native argv. */
 export const AGY_REVIEWER_VARIANT: AdapterDefinition = {
   ...reviewerVariant("agy", "agy reviewer", { defaultPool: false, declaration: "automatic", unavailable: "agy is an implementer peer (#485)" }, { palette: { fg: "#6558a6", bg: "#f1effa" } }),

package/src/adapters/local-worker.ts

@@ -77,6 +77,8 @@ const system = (cwd: string, preamble = "") =>
 /** Hub-native agent loop: the hub owns every model call, so it can choose the model per call (L2) and the gateway (L3). */
 export class LocalPeer extends BasePeer {
   readonly hubNative = true;
+  readonly deliveryOnly: boolean = true;
+  readonly hubOwned: boolean = true;
   private readonly history: ChatMessage[] = [];
   private readonly sessionId = `agent-hub-local-${randomUUID()}`;
   private readonly routes: HubRouteRuntime;

package/src/adapters/pi.ts

@@ -2,15 +2,17 @@ import { buildPiLaunch } from "../pi/launch.ts";
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { spawn, type ChildProcess, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { renderDigest, replyAudience, replyParent, type Envelope, type PeerId } from "../hub/envelope.ts";
 import { BasePeer } from "../hub/peers.ts";
-import { stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
+import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
+import { assessVersion, COMPAT, type CompatVerdict } from "./compat.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 import { PiSessionBookmarkMismatch, validatePiSession } from "../pi/session.ts";
 import { ApprovalWaitStop, toolResultFailed, type ApprovalProvenance } from "../local/tools.ts";
 import { piToolStepCeiling, type PiToolStepCeiling } from "../pi/ceiling.ts";
 import type { ExecutionBudgetDecision, ExecutionUnit } from "../hub/execution-budget.ts";
+import type { StartForm } from "./registry-types.ts";
 
 export interface PiModelDescriptor { id: string; name?: string; contextWindow?: number; maxTokens?: number; reasoning?: boolean; }
 export interface PiToolSchema { name: string; description?: string; parameters: Record<string, unknown>; }
@@ -56,6 +58,39 @@ export interface PiOptions {
   signature?: typeof processSignature;
 }
 export interface PiTuiLaunch { cmd: string; args: string[]; env: NodeJS.ProcessEnv; }
+
+/** Only the host's parsed version verdict may cross the generic startup-error boundary. */
+export class PiVersionRefusal extends Error {
+  constructor(verdict: Extract<CompatVerdict, { ok: false }>) { super(verdict.reason); }
+}
+
+/** Bounded, non-blocking probe of the exact configured native command, including wrapper arguments. */
+export function piVersionAsync(command: readonly string[], cwd: string, timeoutMs = 10_000): Promise<CompatVerdict> {
+  const [bin, ...prefix] = command;
+  if (!bin) return Promise.resolve(assessVersion("pi", undefined));
+  return new Promise(resolve => {
+    let proc: ChildProcess;
+    try { proc = spawn(bin, [...prefix, "--version"], { cwd, env: peerChildEnv("pi"), detached: true, stdio: ["ignore", "pipe", "ignore"] }); }
+    catch { resolve(assessVersion("pi", undefined)); return; }
+    let output = "", bytes = 0, done = false;
+    const finish = async (code: number | null) => {
+      if (done) return; done = true; clearTimeout(timer);
+      try { await stopOwnedProcess(proc, { group: true }); }
+      catch { resolve(assessVersion("pi", undefined)); return; }
+      resolve(assessVersion("pi", code === 0 && bytes <= 64 * 1024 ? COMPAT.pi.parse(output) : undefined));
+    };
+    const timer = setTimeout(() => { void finish(null); }, timeoutMs);
+    proc.once("spawn", () => trackGroup(proc));
+    proc.stdout!.on("data", (chunk: Buffer) => {
+      if (done) return;
+      bytes += chunk.length;
+      if (bytes > 64 * 1024) { void finish(null); return; }
+      output += chunk.toString("utf8");
+    });
+    proc.once("error", () => { void finish(null); });
+    proc.once("close", code => { void finish(code); });
+  });
+}
 type RpcMessage = { type?: string; id?: string | number; command?: string; success?: boolean; data?: any; [key: string]: any };
 type VerifiedEmptyResume = { sessionId: string };
 type TerminalOwnerObservation = { pid: number; signature: string; sessionId: string; sessionFile: string; ownerToken: string; checkedAt: number };
@@ -65,6 +100,7 @@ function ownerStillAlive(pid: number, signature: string | undefined): boolean {
 
 export class PiPeer extends BasePeer {
   readonly hubNative = true;
+  readonly hubOwned: boolean = true;
   private proc?: ChildProcessWithoutNullStreams;
   private server?: ReturnType<typeof Bun.serve>;
   private buffer = "";
@@ -132,7 +168,8 @@ export class PiPeer extends BasePeer {
   private tuiQueue: Record<string, unknown>[] = [];
   private tuiWaiters: Array<{ resolve: (command: Record<string, unknown> | undefined) => void; timer: ReturnType<typeof setTimeout> }> = [];
 
-  constructor(id: PeerId, private readonly opts: PiOptions) { super(id, opts.watchdogMs); }
+  /** 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); }
   get tuiLaunch(): PiTuiLaunch | undefined { return this._tuiLaunch; }
   get pendingResume(): { sessionId?: string; sessionFile?: string } {
     if (this.canReuseVerifiedEmptyResume()) return { sessionId: this.verifiedEmptyResume!.sessionId };
@@ -167,6 +204,10 @@ export class PiPeer extends BasePeer {
     const file = this.sessionFile && (exists || !empty) ? this.sessionFile : undefined;
     return { launch: { kind: "pi", cwd: this.opts.cwd, mode: this.opts.mode, backend: this.opts.backend, ...(this.opts.model ? { model: this.opts.model } : {}), ...(file ? { sessionFile: file } : {}) }, ...(this.sessionId ? { sessionId: this.sessionId } : {}), ...(file ? { sessionFile: file } : {}) };
   }
+  get nativeSession(): string | undefined {
+    const session = this.recoveryMetadata().sessionId;
+    return typeof session === "string" ? session : undefined;
+  }
 
   /** Verify the live source before choosing ID-only restoration. Never infer emptiness from a missing file. */
   async captureResume(): Promise<Record<string, unknown>> {
@@ -344,6 +385,7 @@ export class PiPeer extends BasePeer {
   }
 
   private async startImpl(): Promise<void> {
+    if (this.preflight) await this.preflight();
     this.terminalOwnerObservation = undefined;
     this.stopping = false;
     this.rosterDetached = false; this.rosterUnownedRun = false;
@@ -466,6 +508,7 @@ export class PiPeer extends BasePeer {
     return pending.map((call) => call.settled);
   }
   get mode(): "headless" | "tui" { return this.opts.mode; }
+  get form(): StartForm { return this.opts.mode; }
 
   /** Withdraw hub admission without shutting down a person's Pi TUI or its bridge. */
   async detachForRoster(): Promise<void> {

package/src/adapters/qwen-dual.ts

@@ -82,6 +82,17 @@ export function qwenDualNamesStateDir(input: unknown, stateDir: string): boolean
   return seen(input, 0);
 }
 
+/**
+ * #517: Qwen tells the model that one of its background shells finished with a `user` event of its own, which is neither the hub's submit nor the person typing. Qwen may fold
+ * several finished shells into one event, each its own envelope, separated by one blank line (8 of the 48 in the live event files do). The shape is exact: the text is wholly
+ * one or more complete envelopes and nothing else, so a person's text that merely contains or resembles one is still a person's prompt. Nothing inside an envelope is read
+ * beyond its header lines, so nothing in it can steer the adapter.
+ */
+const NOTIFICATION = String.raw`<task-notification>\n<task-id>bg_[0-9a-f]{4,32}<\/task-id>\n<kind>[a-z_-]{1,32}<\/kind>\n<status>[a-z_-]{1,32}<\/status>\n(?:(?!<task-notification>|<\/task-notification>)[\s\S])*<\/task-notification>`;
+const QWEN_TASK_NOTIFICATIONS = new RegExp(`^${NOTIFICATION}(?:\\n\\n${NOTIFICATION})*$`);
+const NOTIFICATION_CAP = 64 * 1024;
+export function isQwenTaskNotification(text: string): boolean { return text.length <= NOTIFICATION_CAP && QWEN_TASK_NOTIFICATIONS.test(text); }
+
 /** `qwen --version` against the dual-output compat entry. Never throws: a refusal is a reason. */
 export async function qwenDualVersionAsync(cmd: readonly string[], cwd: string): Promise<{ ok: true; version: string; note?: string } | { ok: false; reason: string }> {
   const [bin, ...prefix] = cmd.filter(word => word !== "--acp");
@@ -416,6 +427,17 @@ export class QwenDualPeer extends BasePeer {
     if (!this.stopping && !this.detached && this.state === "offline") this.setState("idle");
   }
 
+  /**
+   * Judged on the raw event, not on `promptText`, which joins every text block and drops the rest: an event is Qwen's own notice only when its content is exactly one text block
+   * and that block is wholly the strict envelope. A text split across blocks, or a block with anything else beside it (an image, a second text), is a person's prompt.
+   */
+  private isNotificationEvent(event: Json): boolean {
+    const content = event.message?.content;
+    if (!Array.isArray(content) || content.length !== 1) return false;
+    const block = content[0];
+    return !!block && typeof block === "object" && block.type === "text" && typeof block.text === "string" && isQwenTaskNotification(block.text);
+  }
+
   private promptText(event: Json): string | undefined {
     const content = event.message?.content;
     if (typeof content === "string") return content;
@@ -425,6 +447,9 @@ export class QwenDualPeer extends BasePeer {
   }
 
   private onUser(event: Json): void {
+    // Qwen's own background-shell notice (#517) is part of whatever turn is running and never the person typing, so it ends no hub turn and holds no queue. It changes nothing else:
+    // an idle peer stays idle (Qwen may answer it or not, and a peer that waited for an answer that never comes would block its queue), and a running turn keeps its owner.
+    if (this.isNotificationEvent(event)) return;
     const text = this.promptText(event);
     if (text === undefined) return; // a tool result echoed back, not a prompt
     const turn = this.turn;

package/src/adapters/registry-types.ts

@@ -210,7 +210,9 @@ export interface AdapterDefinition {
   /** Declaration admission only; execution-root and runtime owner proof remain host responsibilities. */
   instances?: { mode: "external" | "headless"; roles?: readonly string[];
     /** Each declared instance runs its own native data home (`jcode_home`) and may pass its own provider, model and profile names (#685). Fixed builtins only. */
-    nativeHome?: true };
+    nativeHome?: true;
+    /** A declared headless instance of this definition may pass one validated `model` word to its native child (#844). Fixed builtins only. */
+    modelSelect?: true };
   attach?: {
     /** The authenticated external hello may claim this id; independent of MCP configuration shape. */
     externalHello?: boolean;
@@ -309,7 +311,9 @@ export interface AdapterDefinition {
   /** #525: fixed builtin variant for declared headless implementer instances. */
   headlessVariant?: AdapterDefinition;
   /** Fixed host backend; runtime isolation proof is required before bus admission. */
-  reviewer?: { backend?: ReviewerBackend; defaultPool: boolean; unavailable?: string; declaration: "automatic" | "explicit" };
+  reviewer?: { backend?: ReviewerBackend; defaultPool: boolean; unavailable?: string; declaration: "automatic" | "explicit";
+    /** #852: what a reviewer of this kind reads. `code`: the code only, its sandbox cannot run tests or read CI. Unset means `full`. Fixed builtins only. */
+    scope?: "full" | "code" };
 }
 
 /** Explicit project declarations, passed by the bound host. No process-global instance registration. */

package/src/adapters/registry.ts

@@ -259,6 +259,7 @@ export function assertNativeCapabilityScope(definition: AdapterDefinition): void
     ["cli.entry", declared(definition.cli, "entry")],
     ["cli.preview", declared(definition.cli, "preview")],
     ["cli.usage", declared(definition.cli, "usage")],
+    ["instances.modelSelect", declared(definition.instances, "modelSelect")], // #844: a fixed-builtin assumption, one validated model word per declared headless instance
   ];
   const field = restricted.find(([, present]) => present)?.[0];
   if (field) throw new Error(`${field} is restricted to fixed builtin adapter definitions`);

package/src/adapters/reviewer-print.ts

@@ -156,6 +156,7 @@ const reviewTask = (env: Envelope): number | undefined => {
 
 export class ReviewerPrintPeer extends BasePeer {
   readonly hubNative = true;
+  readonly hubOwned: boolean = true;
   private generation = 0;
   private child: OwnedPrintChild | undefined;
   private childCleanup: (() => Promise<void>) | undefined;