@staix/agent-hub 0.17.0 → 0.19.0

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/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];
 }
 
@@ -184,7 +186,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/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/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/definitions/builtin-metadata.ts

@@ -61,7 +61,7 @@ const dualForms = Object.freeze(["tui", "headless"] as const);
 const headlessForms = Object.freeze(["headless"] as const);
 const hubGrants = {
   ask: "every write, edit and shell command asks",
-  "ask-when-needed": "write and edit inside the project run without asking; shell and git writes still ask",
+  "ask-when-needed": "write, edit and proven bounded read-only shell commands inside the project run without asking; other shell commands and git writes still ask",
   "never-ask": "every tool runs without asking, inside the hub sandbox and path guard",
 };
 
@@ -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

@@ -36,7 +36,7 @@ export interface LocalOptions {
   turnId?: () => string | undefined;
   onApprovalStop?: (reason: string) => void;
   onTool?: (observation: ToolObservation, task?: string) => void;
-  tools: { deny: string[]; permit: ToolContext["permit"]; bashNetwork?: SandboxNetwork; readAllow?: string[]; readOnly?: string[] };
+  tools: { deny: string[]; permit: ToolContext["permit"]; shellExecutionCheck?: ToolContext["shellExecutionCheck"]; bashNetwork?: SandboxNetwork; readAllow?: string[]; readOnly?: string[] };
   capture?: Capture;
   /** Runs a hub task tool (hub_task_*, hub_review, hub_remember) as this peer. Absent = the tools are not offered. */
   taskTool?: (name: string, args: Record<string, unknown>, turn: { pii: boolean }) => Promise<string>;
@@ -290,11 +290,12 @@ export class LocalPeer extends BasePeer {
   }
 
   private toolContext(envs: Envelope[], turnSignal: AbortSignal, pii: boolean, reply: EnvelopeOpts): ToolContext {
+    const executionGeneration=this.turn;
     return {
       cwd: this.opts.cwd,
       deny: this.opts.tools.deny,
       readOnly: this.opts.tools.readOnly,
-      permit: async (title, tool, _signal, canonicalTarget, _observe, originalPath, input) => {
+      permit: async (title, tool, _signal, canonicalTarget, _observe, originalPath, input, policy) => {
         if (turnSignal.aborted) return "aborted";
         const generation = this.turn;
         let observed = false;
@@ -314,7 +315,7 @@ export class LocalPeer extends BasePeer {
           const finish = (decision: ToolApproval) => { turnSignal.removeEventListener("abort", onAbort); resolve(decision); };
           const onAbort = () => finish("aborted");
           turnSignal.addEventListener("abort", onAbort, { once: true });
-          this.opts.tools.permit(title, tool, turnSignal, canonicalTarget, observe, originalPath, input).then(finish, (error) => { turnSignal.removeEventListener("abort", onAbort); reject(error); });
+          this.opts.tools.permit(title, tool, turnSignal, canonicalTarget, observe, originalPath, input, policy).then(finish, (error) => { turnSignal.removeEventListener("abort", onAbort); reject(error); });
         });
         if (generation !== this.turn || (turnSignal.aborted && picked !== "expired")) return "aborted";
         // Legacy permit callbacks can represent a person's denial without provenance. A true
@@ -323,6 +324,7 @@ export class LocalPeer extends BasePeer {
         if (!observed && picked === "expired") observe({ source: "expired", answerEpoch: this.approvalAnswerEpoch ?? 0, eligibleExpiry: true });
         return picked;
       },
+      shellExecutionCheck: input=>turnSignal.aborted||executionGeneration!==this.turn?"aborted":this.opts.tools.shellExecutionCheck?.(input)??"valid",
       sandboxProfile: this.sandboxProfile,
       sandboxEnv: { ...proxyEnv(this.opts.tools.bashNetwork ?? false), AGENTHUB_PEER_ID: this.id },
       signal: turnSignal,

package/src/adapters/pi.ts

@@ -2,10 +2,11 @@ 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";
@@ -56,6 +57,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 };
@@ -132,7 +166,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 };
@@ -344,6 +379,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;

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/cli/agents.ts

@@ -4,19 +4,81 @@ import { assessVersion, COMPAT, describe, isCompatId, readTrust, trustFile, writ
 /** #691: what `ahub agents` and `ahub doctor` show for each gated native CLI. */
 export interface AgentVersionRow { id: CompatId; executable?: string; verdict: CompatVerdict; policy: string }
 
-/** `commands` carries the configured argv (codex_bin, jcode_cmd, qwen_cmd); the probe words follow it. */
+const PROBE_ENV = { JCODE_NO_TELEMETRY: "1", JCODE_DISABLE_CLAUDE_MCP: "1" };
+
+/** The one place that decides what is run for an id: the configured argv (including pi.cmd) plus the probe words. */
+function probeTarget(id: CompatId, commands: Partial<Record<CompatId, readonly string[]>>): { executable: string; args: string[] } | undefined {
+  const [defaultBin, ...words] = COMPAT[id].probe;
+  const [bin = defaultBin, ...prefix] = commands[id] ?? [defaultBin];
+  const executable = Bun.which(bin) ?? undefined;
+  return executable ? { executable, args: [...prefix, ...words] } : undefined;
+}
+
+function probeRow(id: CompatId, executable: string | undefined, stdout: string | undefined, trusted: ReturnType<typeof readTrust>): AgentVersionRow {
+  if (!executable) return { id, verdict: { ok: false, state: "unknown", reason: `${COMPAT[id].label} not found on PATH` }, policy: describe(id) };
+  return { id, executable, verdict: assessVersion(id, stdout === undefined ? undefined : COMPAT[id].parse(stdout), trusted), policy: describe(id) };
+}
+
+/** `commands` carries the configured argv (including pi.cmd); the probe words follow it. */
 export function agentVersions(commands: Partial<Record<CompatId, readonly string[]>> = {}): AgentVersionRow[] {
   const trusted = readTrust();
   return (Object.keys(COMPAT) as CompatId[]).map(id => {
-    const [defaultBin, ...words] = COMPAT[id].probe;
-    const [bin = defaultBin, ...prefix] = commands[id] ?? [defaultBin];
-    const executable = Bun.which(bin) ?? undefined;
-    if (!executable) return { id, verdict: { ok: false, state: "unknown", reason: `${COMPAT[id].label} not found on PATH` }, policy: describe(id) };
-    const result = spawnSync(executable, [...prefix, ...words], { encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024, env: { ...process.env, JCODE_NO_TELEMETRY: "1", JCODE_DISABLE_CLAUDE_MCP: "1" } });
-    return { id, executable, verdict: assessVersion(id, result.status === 0 ? COMPAT[id].parse(result.stdout ?? "") : undefined, trusted), policy: describe(id) };
+    const target = probeTarget(id, commands);
+    if (!target) return probeRow(id, undefined, undefined, trusted);
+    const result = spawnSync(target.executable, target.args, { encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024, env: { ...process.env, ...PROBE_ENV } });
+    return probeRow(id, target.executable, result.status === 0 ? result.stdout ?? "" : undefined, trusted);
   });
 }
 
+const PROBE_OUTPUT_CAP = 64 * 1024;
+/** After the probe process ends, how long a descendant that kept the pipe open may still be read before the reader is cancelled. */
+const PROBE_EXIT_GRACE_MS = 250;
+
+/**
+ * One bounded probe run. Output is read as a stream and counted as it arrives: past the cap the probe is killed and the
+ * reader cancelled, so a chatty or endless CLI never accumulates in memory. A deadline kills the probe and cancels the
+ * reader, and a descendant that inherited stdout cannot hold the reader past the grace after the probe's own exit.
+ * ponytail: only the probe process is killed, not its descendants; a stray one ends on its own or when its pipe closes.
+ * The upgrade is a process group via child_process (as `jcodeVersionAsync` does).
+ */
+async function runProbe(executable: string, args: readonly string[], timeoutMs: number, graceMs = PROBE_EXIT_GRACE_MS): Promise<string | undefined> {
+  const child = Bun.spawn([executable, ...args], { stdout: "pipe", stderr: "ignore", stdin: "ignore", env: { ...process.env, ...PROBE_ENV }, timeout: timeoutMs, killSignal: "SIGKILL" });
+  const reader = child.stdout.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0, overflow = false, cancelled = false;
+  const release = () => { if (cancelled) return; cancelled = true; void reader.cancel().catch(() => undefined); };
+  const pump = (async () => {
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) return;
+        total += value.byteLength;
+        if (total > PROBE_OUTPUT_CAP) { overflow = true; child.kill("SIGKILL"); release(); return; }
+        chunks.push(value);
+      }
+    } catch { /* a cancelled or failed read ends the probe with what was counted */ }
+  })();
+  const deadline = setTimeout(() => { child.kill("SIGKILL"); release(); }, timeoutMs + graceMs);
+  let grace: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const code = await child.exited;
+    grace = setTimeout(release, graceMs);
+    await pump;
+    return code === 0 && !overflow ? Buffer.concat(chunks).toString("utf8") : undefined;
+  } finally { clearTimeout(deadline); clearTimeout(grace); release(); }
+}
+
+/** #843 AC3: the same probe for the daemon, which must not block its event loop for up to ten seconds an id. */
+export async function agentVersionsAsync(commands: Partial<Record<CompatId, readonly string[]>> = {}, timeoutMs = 10_000, graceMs = PROBE_EXIT_GRACE_MS): Promise<AgentVersionRow[]> {
+  const trusted = readTrust();
+  return Promise.all((Object.keys(COMPAT) as CompatId[]).map(async id => {
+    const target = probeTarget(id, commands);
+    if (!target) return probeRow(id, undefined, undefined, trusted);
+    try { return probeRow(id, target.executable, await runProbe(target.executable, target.args, timeoutMs, graceMs), trusted); }
+    catch { return probeRow(id, target.executable, undefined, trusted); }
+  }));
+}
+
 export function runAgents(args: string[], commands: Partial<Record<CompatId, readonly string[]>>, fail: (message: string) => never): void {
   const [sub, id, version, ...rest] = args.filter(arg => arg !== "--json");
   if (sub === "trust") {

package/src/cli/claude-shell-wrapper.ts

@@ -0,0 +1,54 @@
+import { request } from "node:http";
+import { isAbsolute, basename } from "node:path";
+
+export const HOST_SHELL_PROTOCOL = Object.freeze({ chunkBytes: 16 * 1024, frameBytes: 24 * 1024, failure: 125, maximumMs: 3_600_000, refusal: "host shell execution refused" });
+
+async function output(stream: NodeJS.WriteStream, data: Buffer): Promise<void> {
+  await new Promise<void>((resolve, reject) => stream.write(data, error => error ? reject(error) : resolve()));
+}
+
+async function main(): Promise<number> {
+  const [socket, ticket, ...extra] = process.argv.slice(2);
+  if (!socket || !isAbsolute(socket) || socket.length > 4096 || !ticket || !/^[a-f0-9]{64}$/.test(ticket) || extra.length) throw new Error();
+  const body = JSON.stringify({ ticket });
+  const call = request({ socketPath: socket, path: "/execute", method: "POST", headers: { "content-type": "application/json", "content-length": Buffer.byteLength(body), connection: "close" } });
+  const connection = new Promise<import("node:http").IncomingMessage>((resolve, reject) => { call.once("response", resolve); call.once("error", reject); });
+  const opening = setTimeout(() => call.destroy(new Error()), 5000);
+  const total = setTimeout(() => call.destroy(new Error()), HOST_SHELL_PROTOCOL.maximumMs + 10_000);
+  let response: import("node:http").IncomingMessage | undefined;
+  try {
+    call.end(body); response = await connection; clearTimeout(opening);
+    if (response.statusCode !== 200 || response.headers["content-type"] !== "application/x-ndjson") throw new Error();
+    let pending = "", status: number | undefined;
+    for await (const raw of response) {
+      const chunk = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+      if (chunk.length > 1024 * 1024) throw new Error();
+      pending += chunk.toString("utf8");
+      for (let end; (end = pending.indexOf("\n")) >= 0;) {
+        if (end > HOST_SHELL_PROTOCOL.frameBytes) throw new Error();
+        const line = pending.slice(0, end); pending = pending.slice(end + 1);
+        if (!line || status !== undefined) throw new Error();
+        const frame = JSON.parse(line);
+        if (!frame || typeof frame !== "object" || Array.isArray(frame)) throw new Error();
+        const keys = Object.keys(frame).sort().join(",");
+        if (frame.type === "exit" && keys === "code,type" && Number.isSafeInteger(frame.code) && frame.code >= 0 && frame.code <= 255) { status = frame.code; continue; }
+        if (!["stdout", "stderr"].includes(frame.type) || keys !== "data,type" || typeof frame.data !== "string" || frame.data.length > 4 * Math.ceil(HOST_SHELL_PROTOCOL.chunkBytes / 3)) throw new Error();
+        const bytes = Buffer.from(frame.data, "base64");
+        if (bytes.length > HOST_SHELL_PROTOCOL.chunkBytes || bytes.toString("base64") !== frame.data) throw new Error();
+        await output(frame.type === "stdout" ? process.stdout : process.stderr, bytes);
+      }
+      if (pending.length > HOST_SHELL_PROTOCOL.frameBytes) throw new Error();
+    }
+    if (pending || status === undefined) throw new Error();
+    return status;
+  } finally { clearTimeout(opening); clearTimeout(total); response?.destroy(); call.destroy(); }
+}
+
+// The filename fence also keeps this inert if a host imports the protocol constants through a bundle.
+if (import.meta.main && basename(process.argv[1] ?? "") === "claude-shell-wrapper.ts") {
+  process.stdout.on("error", () => {}); process.stderr.on("error", () => {});
+  void main().then(code => { process.exitCode = code; }, async () => {
+    try { await output(process.stderr, Buffer.from(`${HOST_SHELL_PROTOCOL.refusal}\n`)); } catch { /* broken caller pipe */ }
+    process.exitCode = HOST_SHELL_PROTOCOL.failure;
+  });
+}

package/src/cli/console-state.ts

@@ -47,7 +47,8 @@ export interface ConsoleState {
   autoSelected?: boolean;
   input: string; editing: boolean; history: string[]; historyIndex: number;
   approvals: Approval[]; events: ConsoleEvent[]; peers: Record<string, any>; budget: Record<string, any>;
-  taskWip?: Record<string, { wip: number; wipLimit: number }>;
+  /** #784 AC3: the split of `wip` (active, review-wait, reserved); absent from an older hub. */
+  taskWip?: Record<string, { wip: number; wipLimit: number; active?: number; reviewWait?: number; reserved?: number }>;
   backlogView?: boolean;
   tasks: any[]; tasksKnown?: boolean; taskCounts?: Record<string, number>; queue: any[]; detail?: Detail; detailOffset: number; help: boolean; notice: string; noticeAt?: number; noticeTone?: Tone;
   peerFilter?: string; kindFilter?: string; project?: string;
@@ -348,6 +349,12 @@ export function budgetFields(budget: any, now: number): [string, unknown][] {
   });
   return [["quota", lines.length ? lines : typeof budget.note === "string" ? budget.note : "no reading"], ...(lines.length && typeof budget.note === "string" ? [["quota note", budget.note] as [string, unknown]] : [])];
 }
+/** #784 AC3: the Peers detail carries the planner WIP split as one line (`1 of 2: active 1, review-wait 0, reserved 0`); a hub that sends none adds nothing. */
+function peerDetailRow(s: ConsoleState, row: any): Record<string, unknown> {
+  const wip = s.taskWip?.[row.id];
+  const split = wip && [wip.active, wip.reviewWait, wip.reserved].every(n => Number.isSafeInteger(n)) ? `${wip.wip} of ${wip.wipLimit}: active ${wip.active}, review-wait ${wip.reviewWait}, reserved ${wip.reserved}` : undefined;
+  return { ...row, ...(split ? { "planner WIP": split } : {}) };
+}
 const detailLines = (detail: Detail, columns: number, now: number, task = false): Span[][] => {
   if (typeof detail === "string") return wrap(detail, columns).map(text => [span(text)]);
   const { budget, ...rest } = detail as Record<string, unknown>;
@@ -794,7 +801,7 @@ export function reduceConsole(state: ConsoleState, key: string, now = Date.now()
     if (s.panel === 3 || s.panel === 4) effects.push({ type: "show", panel: s.panel, id: String(row.id) });
     else if (s.panel === 2) { s.requestDetail = row.id; s.detailOffset = 0; } // the row is the selected request
     else if (s.panel === 7) { s.detail = { usagePeer: row.id }; s.detailOffset = 0; } // rendered live from s.usage, so a refresh updates it
-    else { s.detail = s.panel === 5 ? String(row.text) : { ...row }; s.detailOffset = 0; }
+    else { s.detail = s.panel === 5 ? String(row.text) : s.panel === 1 ? peerDetailRow(s, row) : { ...row }; s.detailOffset = 0; }
     return done();
   }
   if (s.mode === "panels" && item !== undefined && item !== null) {