@staix/agent-hub 0.12.45 → 0.13.0

package/src/adapters/agy/entry.ts

@@ -1,4 +1,5 @@
 import { publicArg } from "../definitions/native-cli-preview-common.ts";
+import { assessVersion, COMPAT } from "../compat.ts";
 import { spawn, spawnSync } from "node:child_process";
 import { resolve } from "node:path";
 import type { NativeCliEntryContext } from "../definitions/native-cli-entry-types.ts";
@@ -38,10 +39,10 @@ export const AGY_LAUNCH_NOTICE = "Antigravity: pull-only TUI; native permissions
 
 /** agy auto-updates, so the 1.4.x line launches; only 1.4.2 has a T0 receipt and other patches warn (#589). */
 export function agyVersionGate(stdout: string): { ok: true; message?: string } | { ok: false; message: string } {
-  const version = stdout.trim();
-  if (version === "1.4.2") return { ok: true };
-  if (/^1\.4\.\d+$/.test(version)) return { ok: true, message: `agy ${version}: only 1.4.2 is T0-verified; launching on the 1.4.x line unverified` };
-  return { ok: false, message: "agy P1 requires the Antigravity CLI 1.4.x line (1.4.2 verified)" };
+  // #691: the verified versions, the compatible line and the person's trust live in compat.ts.
+  const verdict = assessVersion("agy", COMPAT.agy.parse(stdout));
+  if (!verdict.ok) return { ok: false, message: verdict.reason };
+  return verdict.note ? { ok: true, message: verdict.note } : { ok: true };
 }
 
 export async function runAgyEntry(ctx: NativeCliEntryContext): Promise<void> {

package/src/adapters/claude-channel.ts

@@ -22,9 +22,16 @@ import { renderHeldHint } from "../hub/delivery-hints.ts";
 // ControlClient verifies the manifest identity on every connection.
 const stateDir = process.env.AGENTHUB_STATE_DIR ?? stateDirFor(process.cwd());
 const projectRoot = process.env.AGENTHUB_PROJECT_DIR ?? process.cwd();
-const peerId = process.env.AGENTHUB_PEER_ID ?? "claude";
-/** tools mode: the same server, run by Kimi (ACP mcpServers) or Codex (mcp_servers override). Their messages arrive through their own adapters, so no channel here. Not the "tools-only" Claude below. */
+/** tools mode: the same server, run by Kimi (ACP mcpServers), Codex (mcp_servers override) or Jcode. Their messages arrive through their own adapters, so no channel here. Not the "tools-only" Claude below. */
 const toolsMode = process.env.AGENTHUB_MODE === "tools";
+/**
+ * #368: a tools-mode server acts as exactly the peer whose owned launch started it, and the project's Jcode MCP entry names none, so the
+ * id comes from the owned process env alone. With none (a person's own `jcode` run in this project outside the hub) it connects as nobody,
+ * refuses every tool with a reason, and never defaults to "jcode" or any other id. Only a plain Claude session defaults to "claude".
+ */
+const unidentified = toolsMode && !process.env.AGENTHUB_PEER_ID;
+const peerId = process.env.AGENTHUB_PEER_ID ?? (toolsMode ? "" : "claude");
+const UNIDENTIFIED = "agent-hub tools refused: this process was not started by the hub (no AGENTHUB_PEER_ID), so it has no peer identity. Start the agent with ahub jcode (or the hub's own start) to use hub tools.";
 // Exposure hint only; the daemon verifies the actual adapter before any retry mutation.
 const deliveryOnly = process.env.AGENTHUB_DELIVERY_ONLY === "true";
 /**
@@ -84,7 +91,7 @@ const MAX_RECONNECT_DELAY_MS = 30_000;
 const TERMINAL_CLOSES: Record<number, string> = {
   4401: "the hub refused the control token",
   4404: "the hub belongs to a different project or instance; restart this session from the intended project",
-  4403: `the hub refused the peer id "${peerId}" (reserved or malformed)`,
+  4403: `the hub refused "${peerId}": the id is reserved or malformed, or this process is not an owned launch of that peer (start it with ahub jcode)`,
   4409: `the peer id "${peerId}" is taken by a hub-managed adapter`,
   4430: "this Claude launch ended; start a new session with ahub claude, or use a plain session with hub_inbox",
   4426: "wire version mismatch with the running hub: update the agent-hub plugin (ahub setup) and restart this session",
@@ -251,7 +258,7 @@ async function connectLoop(): Promise<void> {
     let closeReason: string | undefined;
     try {
       const client = await ControlClient.connect(stateDir, { role: toolsMode ? "tools" : "peer", peer: peerId, ...(toolsMode ? {} : { channel }),
-        ...(!toolsMode && process.env.AGENTHUB_LAUNCH_ID ? { launchId: process.env.AGENTHUB_LAUNCH_ID } : {}),
+        ...(process.env.AGENTHUB_LAUNCH_ID ? { launchId: process.env.AGENTHUB_LAUNCH_ID } : {}),
         ...(!toolsMode && standingBy ? { standby: true } : {}),
         ...(process.env.AGENTHUB_PROJECT_DIR ? { projectRoot } : {}) });
       client.onPush = (msg) => {
@@ -375,6 +382,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 
 async function callTool(req: { params: { name: string; arguments?: Record<string, unknown> } }) {
   const { name, arguments: args } = req.params;
+  if (unidentified) return { ...text(UNIDENTIFIED), isError: true };
   if (name === "hub_delivery_done" && channel) {
     if (!hub) return text(offline());
     const a = args ?? {};
@@ -382,7 +390,7 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
     return text(result.ok ? "delivery completed" : `not completed: ${result.error}`);
   }
   if (name === "hub_inbox" && !toolsMode) {
-    let remote: string[] = [], notice = "";
+    let remote: string[] = [], notice = "", polling = "", counted = false;
     if (hub) {
       try {
         const res = await hub.request({ t: "inbox" });
@@ -391,15 +399,18 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
         else {
           pendingQueued = { queued: typeof res.waiting === "number" ? res.waiting : 0, important: typeof res.waitingImportant === "number" ? res.waitingImportant : 0 };
           remote = (res.envs as Envelope[]).map(frame);
-          if (res.waiting) notice = `(${res.waiting} queued hub message(s) remain unread)`;
+          if (Number.isSafeInteger(res.pollingAdvice?.count) && res.pollingAdvice.count >= 3 && Number.isSafeInteger(res.pollingAdvice?.minutes) && res.pollingAdvice.minutes >= 0 && res.pollingAdvice.minutes <= 10) polling = `[polling detected] ${res.pollingAdvice.count} empty reads in ${res.pollingAdvice.minutes} min with no assigned work: end your turn`;
+          // #713: a pull drains what fits one read; what is left is said plainly, with what to do about it. The count already says how many remain, so the pending hint adds only the important ones (#221).
+          if (res.waiting) { notice = `(${res.waiting} more waiting: call hub_inbox again before you start work)`; counted = true; }
         }
       } catch { notice = "not read: daemon inbox unavailable; inspect the connection before another read"; }
     } else notice = offline();
     // Only pushes without a journal delivery id enter this buffer. Pull completion belongs to the daemon.
     const out = [...inbox.splice(0), ...remote];
     if (notice) out.push(notice);
-    const result = text(out.length ? out.join("\n\n") : "(no queued hub messages)");
-    if (notice.endsWith("remain unread)")) Object.defineProperty(result, QUEUED_COUNTED, { value: true });
+    const body = out.length ? out.join("\n\n") : "(no queued hub messages)\nNothing is waiting. Do not poll: if you have no assigned task, report and end your turn; new work waits here for your next boundary.";
+    const result = text(polling ? `${body}\n${polling}` : body);
+    if (counted) Object.defineProperty(result, QUEUED_COUNTED, { value: true });
     return result;
   }
   if (name === "hub_send") {
@@ -427,4 +438,4 @@ await server.connect(new StdioServerTransport());
 // The host (Claude Code, Codex, Kimi) talks over stdin; once it is gone nothing can use this server, and a leftover would keep reconnecting.
 process.stdin.on("end", () => process.exit(0));
 process.stdin.on("close", () => process.exit(0));
-void connectLoop();
+if (unidentified) log(UNIDENTIFIED); else void connectLoop();

package/src/adapters/codex-appserver.ts

@@ -9,6 +9,8 @@ import type { ContextReader } from "./registry-types.ts";
 
 const UNIDENTIFIED_CANCELLATION_NOTICE = "Codex cancelled turn has no verified native id; reattach the native session before further hub delivery";
 
+/** 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 {
   /** Port the TUI attaches to: `codex --enable tui_app_server --remote ws://127.0.0.1:<proxyPort>`. */
   proxyPort: number;
@@ -28,6 +30,11 @@ export interface CodexOptions {
   onUsage?: (rateLimits: unknown, hard: boolean) => void;
   /** Tokens the thread used since the previous update (see `tokenTotal` for how they are counted). */
   onTokens?: (added: number) => void;
+  /**
+   * The same update as `onTokens`, split into the kinds Codex reports (#683 U1): the increase of each `total` counter since the previous
+   * update. Cached input is a part of `input`, and `reasoning` a part of `output` (Codex's own definition), so `total` is not their sum.
+   */
+  onTokenBreakdown?: (delta: { input: number; cachedInput: number; output: number; reasoning: number; total: number }) => void;
   onContext?: (reading: ContextReading) => void;
   /** The definition's native occupancy reader; standalone proxies retain the native default. */
   contextReader?: ContextReader;
@@ -89,6 +96,8 @@ export class CodexPeer extends BasePeer {
    * resumed thread's first update only sets the baseline: its total holds the history from before (issue #40).
    */
   private tokenTotal: number | undefined;
+  /** The per-kind counters of the last `total`, for the breakdown deltas (#683 U1). */
+  private tokenKinds: { input: number; cachedInput: number; output: number; reasoning: number } | undefined;
   private freshThread = false;
   private readonly activeTurns = new Set<string>();
   private deliveryEpoch = 0;
@@ -584,7 +593,7 @@ export class CodexPeer extends BasePeer {
     for (const ids of this.turnDeliveries.values()) for (const id of ids) this.delivery({ id, state: "needs_review", reason: "Codex native thread changed" });
     for (const id of this.unboundDeliveries) this.delivery({ id, state: "needs_review", reason: "Codex native thread changed" });
     this.turnDeliveries.clear(); this.unboundDeliveries.clear();
-    this.tokenTotal = undefined;
+    this.tokenTotal = undefined; this.tokenKinds = undefined;
     this.freshThread = fresh;
     this.link = link;
     this.threadId = threadId;
@@ -648,9 +657,16 @@ export class CodexPeer extends BasePeer {
       this.opts.onContext?.(reader ? reader.read(params.tokenUsage, this.threadId, Date.now()) : codexContext(params.tokenUsage, this.threadId, Date.now()));
       const total = Number(params.tokenUsage?.total?.totalTokens);
       if (!Number.isFinite(total)) return;
+      const previous = this.tokenKinds;
+      const kinds = { input: counter(params.tokenUsage?.total?.inputTokens), cachedInput: counter(params.tokenUsage?.total?.cachedInputTokens),
+        output: counter(params.tokenUsage?.total?.outputTokens), reasoning: counter(params.tokenUsage?.total?.reasoningOutputTokens) };
       const added = this.tokenTotal === undefined ? (this.freshThread ? total : 0) : Math.max(0, total - this.tokenTotal);
-      this.tokenTotal = total;
+      // The same baseline rule as the total: a thread that was resumed counts only what it adds from now on; a new one counts from zero.
+      const base = previous ?? (this.freshThread && this.tokenTotal === undefined ? { input: 0, cachedInput: 0, output: 0, reasoning: 0 } : undefined);
+      this.tokenTotal = total; this.tokenKinds = kinds;
       if (added > 0) this.opts.onTokens?.(added);
+      if (added > 0 && base) this.opts.onTokenBreakdown?.({ input: Math.max(0, kinds.input - base.input), cachedInput: Math.max(0, kinds.cachedInput - base.cachedInput),
+        output: Math.max(0, kinds.output - base.output), reasoning: Math.max(0, kinds.reasoning - base.reasoning), total: added });
       return;
     }
     if (method === "turn/started") {

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

@@ -1,4 +1,5 @@
 import { DENY_NAMES, DENY_SEGMENTS } from "@staix/agent-mem/platform";
+import { assessVersion, COMPAT } from "./compat.ts";
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
@@ -9,7 +10,9 @@ import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process
 import { realPath } from "../hub/project.ts";
 import type { ReviewerBackend, ReviewerLaunch, ReviewerPrepareContext } from "./reviewer-print.ts";
 
-const VERSION = "0.146.0", TOOLS = ["hub_review", "hub_task_show"];
+const TOOLS = ["hub_review", "hub_task_show"];
+/** A version refusal names only versions and a command, so the daemon may show it (#691). */
+class VersionRefusal extends Error {}
 const CAP = 128 * 1024, MAX_SERVERS = 64;
 const digest = (value: string | Buffer) => createHash("sha256").update(value).digest("hex");
 /** Conservative translation of the portable core's regex sources; unfamiliar syntax refuses the receipt. */
@@ -207,11 +210,14 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
       child.once("error", () => { failed = true; void finish(null); });
       child.once("close", code => { void finish(code); });
     });
-    if ((await run(["--version"])).trim() !== `codex-cli ${VERSION}`) throw new Error("native version has no isolation receipt");
+    // #691: the verified versions and the person's trust live in compat.ts; every proof below still runs after trust.
+    const verdict = assessVersion("codex-review", COMPAT["codex-review"].parse(await run(["--version"])));
+    if (!verdict.ok) throw new VersionRefusal(verdict.reason);
+    const version = verdict.version;
     if (Buffer.byteLength(ctx.mcpConfig) > CAP || ctx.privatePaths.length > 128) throw new Error("policy bounds exceeded");
     const hub = ownServer(ctx.mcpConfig);
     // Apps creates a runtime MCP server outside the configured inventory; independently pin and read back its gate.
-    const policy = ["--disable", "plugins", "--disable", "hooks", "--disable", "apps", "-c", 'web_search="disabled"', "-c", `projects=${toml({ [cwd]: { trust_level: "untrusted" } })}`];
+    const policy = ["-c", "notify=[]", "--disable", "plugins", "--disable", "hooks", "--disable", "apps", "-c", 'web_search="disabled"', "-c", `projects=${toml({ [cwd]: { trust_level: "untrusted" } })}`];
     proveDisabledFeatures(await run(["features", "list", ...policy]));
     const before = inventory(await run(["mcp", "list", "--json", ...policy]));
     if (before.some(row => row.name === "agent-hub")) throw new Error("ambient hub MCP collision");
@@ -268,11 +274,12 @@ async function prepare(ctx: ReviewerPrepareContext): Promise<ReviewerLaunch | {
     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,
       current: () => { try { return current(); } catch { return false; } },
       cleanup: () => rmSync(cleanupRoot, { recursive: true, force: true }),
-      isolation: { backend: "codex", version: VERSION, binary: `sha256:${binaryHash}`, profile: `sha256:${launchProfile}`, readOnly: true, strictMcp: true, ephemeral: true,
-        evidence: ["model-free-mcp-inventory-disabled-ambient", "hub-tools-exact-allowlist", "plugins-and-hooks-disabled", "apps-disabled-effective-feature-readback", "web-search-disabled", "project-untrusted", "native-public-read-private-deny-write-deny", "native-glob-and-symlink-private-deny", "portable-core-name-and-state-deny", "standard-host-credential-roots-denied", "binary-config-stable", "binary-hash-once-metadata-fence", "session-ephemeral"] } };
+      isolation: { backend: "codex", version, binary: `sha256:${binaryHash}`, profile: `sha256:${launchProfile}`, readOnly: true, strictMcp: true, ephemeral: true,
+        evidence: ["model-free-mcp-inventory-disabled-ambient", "hub-tools-exact-allowlist", "plugins-and-hooks-disabled", "legacy-notify-disabled", "apps-disabled-effective-feature-readback", "web-search-disabled", "project-untrusted", "native-public-read-private-deny-write-deny", "native-glob-and-symlink-private-deny", "portable-core-name-and-state-deny", "standard-host-credential-roots-denied", "binary-config-stable", "binary-hash-once-metadata-fence", "session-ephemeral"] } };
   } catch (error) {
     if (root) { try { rmSync(root, { recursive: true, force: true }); } catch { /* unavailable remains refused */ } }
     // Name only the path class of an unusable credential root so a stale ~/.docker link is fixable; never a path or contents.
+    if (error instanceof VersionRefusal) return { unavailable: error.message };
     if (error instanceof CredentialRootError) {
       const why = { dangling: "a dangling link", unreadable: "an unreadable path", unsupported: "unsupported syntax or overlapping the checkout" }[error.kind];
       return { unavailable: `Codex reviewer isolation receipt unavailable (credential root ${error.label} is ${why}; remove or repair it)` };

package/src/adapters/compat.ts

@@ -0,0 +1,140 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { hubHome } from "../hub/project.ts";
+
+/**
+ * #691: the one version policy for native agent CLIs. Every version gate asks `assessVersion`; no other file holds a
+ * version constant. `verified` lists versions with a receipt in docs/verification; `line` is a semver window assumed
+ * compatible (contract gates only); a person's trust lets an exact other version through on this machine. An isolation
+ * gate keeps every runtime proof after trust: trust only lifts the version pin.
+ */
+export type CompatGate = "contract" | "isolation";
+export interface CompatPolicy {
+  label: string;
+  verified: readonly string[];
+  line?: { min: string; below: string };
+  gate: CompatGate;
+  /** The default executable and the argv `ahub agents` uses to read the version. */
+  probe: readonly string[];
+  /** Turns the probe's stdout into a plain semver, or undefined. */
+  parse: (stdout: string) => string | undefined;
+  /** What runtime checks still decide after trust (isolation) or what stays unverified (contract). */
+  trustNote: string;
+  /** The config key that selects this kind's executable, when one exists. */
+  config?: "codex_bin" | "jcode_cmd" | "qwen_cmd";
+}
+
+const plain = (text: string) => text.length <= 64 && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(text) ? text : undefined;
+export const COMPAT = {
+  // 0.163.0 receipt: docs/verification/2026-10-22-codex-reviewer-isolation.md
+  "codex-review": { label: "Codex reviewer (codex-cli)", verified: ["0.146.0", "0.163.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-review": { label: "Kimi reviewer (kimi-code)", verified: ["2.2.0", "2.3.0"], 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",
+    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"],
+    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",
+    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." },
+} as const satisfies Record<string, CompatPolicy>;
+export type CompatId = keyof typeof COMPAT;
+type CommandConfig = { codex_bin: string; jcode_cmd: string[]; qwen_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;
+  }
+  return out;
+}
+export const isCompatId = (id: unknown): id is CompatId => typeof id === "string" && Object.hasOwn(COMPAT, id);
+
+export type CompatVerdict =
+  | { ok: true; state: "verified" | "in-line" | "trusted"; version: string; note?: string }
+  | { ok: false; state: "refused" | "unknown"; version?: string; reason: string };
+
+const parts = (v: string) => /^(\d+)\.(\d+)\.(\d+)$/.exec(v)?.slice(1).map(Number);
+const compare = (a: number[], b: number[]) => a[0]! - b[0]! || a[1]! - b[1]! || a[2]! - b[2]!;
+function inLine(version: string, line?: { min: string; below: string }): boolean {
+  const v = parts(version);
+  return !!line && !!v && compare(v, parts(line.min)!) >= 0 && compare(v, parts(line.below)!) < 0;
+}
+
+/** A refusal the daemon may show as is: it names only versions and a command. */
+export const VERSION_REFUSAL = "Version not verified: ";
+/** A window of one minor (1.4.0 up to 1.5.0) reads as "the 1.4.x line". */
+function lineText(line: { min: string; below: string }): string {
+  const [a, b] = [parts(line.min)!, parts(line.below)!];
+  return a[2] === 0 && b[2] === 0 && a[0] === b[0] && b[1] === a[1]! + 1 ? `the ${a[0]}.${a[1]}.x line` : `the line ${line.min} up to ${line.below}`;
+}
+export function describe(id: CompatId): string {
+  const p: CompatPolicy = COMPAT[id];
+  return `verified ${p.verified.join(", ")}${p.line ? `; compatible: ${lineText(p.line)}` : ""}`;
+}
+
+/** `trusted` defaults to this machine's record; tests and the CLI pass their own. */
+export function assessVersion(id: CompatId, observed: unknown, trusted: readonly TrustEntry[] = readTrust()): CompatVerdict {
+  const policy: CompatPolicy = COMPAT[id];
+  const version = typeof observed === "string" ? plain(observed) : undefined;
+  if (!version) return { ok: false, state: "unknown", reason: `${VERSION_REFUSAL}${policy.label} version unknown (${describe(id)}); check that the executable runs` };
+  if (policy.verified.includes(version)) return { ok: true, state: "verified", version };
+  if (trusted.some(entry => entry.id === id && entry.version === version)) return { ok: true, state: "trusted", version, note: `${policy.label} ${version} is untested; trusted on this machine by the person` };
+  if (policy.gate === "contract" && inLine(version, policy.line)) return { ok: true, state: "in-line", version, note: `${policy.label} ${version} is untested (${describe(id)}); launching on the compatible line` };
+  return { ok: false, state: "refused", version, reason: `${VERSION_REFUSAL}${policy.label} ${version} (${describe(id)}). Install a verified version, or accept this one on this machine with: ahub agents trust ${id} ${version}` };
+}
+
+export interface TrustEntry { id: CompatId; version: string; at: number }
+const MAX_TRUST = 64;
+export const trustFile = (home = hubHome()) => join(home, "agent-compat.json");
+
+const MAX_BYTES = 64 * 1024;
+/** An unreadable, linked, oversized or invalid record trusts nothing. */
+export function readTrust(file = trustFile()): TrustEntry[] {
+  let fd: number | undefined;
+  try {
+    // O_NONBLOCK: a FIFO planted at the record path must not stall a synchronous version gate; fstat refuses it.
+    fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const info = fstatSync(fd);
+    if (!info.isFile() || info.size > MAX_BYTES) return [];
+    const bytes = Buffer.alloc(info.size);
+    if (readSync(fd, bytes, 0, info.size, 0) !== info.size) return [];
+    const raw = JSON.parse(bytes.toString("utf8"));
+    if (raw?.schemaVersion !== 1 || !Array.isArray(raw.trusted) || raw.trusted.length > MAX_TRUST) return [];
+    const rows = raw.trusted.filter((row: unknown): row is TrustEntry => {
+      const r = row as TrustEntry;
+      return !!r && isCompatId(r.id) && typeof r.version === "string" && plain(r.version) === r.version && Number.isSafeInteger(r.at);
+    });
+    return rows.length === raw.trusted.length ? rows : [];
+  } catch { return []; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+
+/** Person-only (the CLI classifier refuses agent shells). Writes atomically; returns the new record. */
+export function writeTrust(id: CompatId, version: string, revoke: boolean, file = trustFile(), now = Date.now()): TrustEntry[] {
+  if (plain(version) !== version) throw new Error("trust needs an exact version such as 1.2.3");
+  const rows = readTrust(file).filter(row => !(row.id === id && row.version === version));
+  if (!revoke) rows.push({ id, version, at: now });
+  if (rows.length > MAX_TRUST) throw new Error(`at most ${MAX_TRUST} trusted versions; revoke some first`);
+  const parent = dirname(file);
+  mkdirSync(parent, { recursive: true, mode: 0o700 });
+  const dir = lstatSync(parent);
+  if (!dir.isDirectory() || dir.isSymbolicLink()) throw new Error("the hub home is not a plain directory; trust not written");
+  const target = lstatSync(file, { throwIfNoEntry: false });
+  if (target && !target.isFile()) throw new Error("the trust record is not a regular file; trust not written");
+  // A unique, exclusively created temporary file: an existing name or a planted link fails instead of being followed.
+  const temporary = join(parent, `.agent-compat.${randomUUID()}.tmp`);
+  writeFileSync(temporary, `${JSON.stringify({ schemaVersion: 1, trusted: rows }, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  try { renameSync(temporary, file); }
+  catch (error) { unlinkSync(temporary); throw error; }
+  return rows;
+}

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

@@ -159,7 +159,8 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     api: 1, kind: "jcode", displayName: "Jcode", family: "jcode", transport: "acp",
     roles: implementerRoles, optional: true, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: false },
     start: { create: createJcode, preflight: jcodeStartPreflight, daemonPort: "owned-acp", forms: dualForms, defaultForm: "tui", explicitHeadlessMode: true, conductorStartable: true, hubSwitches: [], ownedFlags: [] },
-    identity: { mcp: "project-file" },
+    // #685: an extra Jcode is a headless instance with its own native home, socket and state (instances.<id>.jcode_home).
+    identity: { mcp: "project-file" }, instances: { mode: "headless", nativeHome: true },
     permission: { unmanaged: "Jcode native policy is unmanaged; no hub mode mapping", grants: {
       ask: "no verified hub mode mapping; native policy only", "ask-when-needed": "no verified hub mode mapping; native policy only", "never-ask": "no verified hub mode mapping; native policy only" } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "jcode", ...JCODE_RECOVERY_SESSION, crashPlan: jcodeCrashPlan }, turnEnd: "adapter", budget: { account: "jcode" },

package/src/adapters/definitions/native-cli-doctor.ts

@@ -1,3 +1,4 @@
+import type { CompatId } from "../compat.ts";
 import type { DoctorCheck } from "../../cli/output.ts";
 
 // Fixed builtin doctor policy only. These projections neither execute probes nor extend AdapterDefinition.
@@ -33,17 +34,23 @@ export function nativeDoctorRecoveryIdentity(peer: { id: string; state: string;
 export type NativeDoctorOptionalProbe =
   | { kind: "source-identity"; name: string; command: string[]; detail: string }
   | { kind: "jcode-mcp"; name: string; home: string }
-  | { kind: "pinned-version"; name: string; command: string[]; expected: string; confirmed: string; unconfirmed: string };
+  | { kind: "pinned-version"; name: string; command: string[]; compat: CompatId; confirmed: string; unconfirmed: string };
 
 /** The host runs these existing checks in order; no process, filesystem or caller callback enters this planner. */
-export function nativeDoctorOptionalProbes(config: { roster: Readonly<Record<string, boolean | undefined>>; jcode_cmd: string[]; qwen_cmd: string[]; jcode_home?: string }): NativeDoctorOptionalProbe[] {
+export function nativeDoctorOptionalProbes(config: { roster: Readonly<Record<string, boolean | undefined>>; jcode_cmd: string[]; qwen_cmd: string[]; jcode_home?: string;
+  /** Declared extra instances (#685): a rostered Jcode instance's own home is inventoried like the base home. */
+  instances?: Readonly<Record<string, { kind: string; jcode_home?: string }>> }): NativeDoctorOptionalProbe[] {
   const probes: NativeDoctorOptionalProbe[] = [];
   if (config.roster.jcode === true) probes.push({ kind: "source-identity", name: "jcode", command: config.jcode_cmd,
     detail: "CLI/source identity only; provider, project MCP and native teardown require separate receipts; native policy unmanaged" });
   // #572 AC4: jcode cannot be told which MCP servers to load, so the host lists the ones its config files name.
   if (config.roster.jcode === true && config.jcode_home) probes.push({ kind: "jcode-mcp", name: "jcode MCP servers", home: config.jcode_home });
-  if (config.roster.qwen === true) probes.push({ kind: "pinned-version", name: "qwen", command: config.qwen_cmd, expected: "0.25.0",
-    confirmed: "CLI reports 0.25.0; native ACP identity/modes and provider access require a separate live check",
-    unconfirmed: "Qwen Code 0.25.0 executable not confirmed; provider and ACP readiness unknown" });
+  // #685: each extra instance has its own home, hence its own inventory. Names and homes only: no model source, URL or token.
+  for (const [id, declaration] of Object.entries(config.instances ?? {})) {
+    if (declaration.kind === "jcode" && declaration.jcode_home && config.roster[id] === true) probes.push({ kind: "jcode-mcp", name: `${id} MCP servers`, home: declaration.jcode_home });
+  }
+  if (config.roster.qwen === true) probes.push({ kind: "pinned-version", name: "qwen", command: config.qwen_cmd, compat: "qwen",
+    confirmed: "CLI version verified; native ACP identity/modes and provider access require a separate live check",
+    unconfirmed: "Qwen Code executable not confirmed; provider and ACP readiness unknown" });
   return probes;
 }

package/src/adapters/definitions/native-cli-entry-jcode.ts

@@ -51,7 +51,10 @@ export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
   if (rest.length || (one["--mode"] !== undefined && !["headless", "tui"].includes(one["--mode"]))) fail("usage: ahub jcode [--mode tui|headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>]");
   if (one["--session-id"] !== undefined && !qwenSessionId(one["--session-id"])) fail("invalid Jcode session identity");
   const control = readControl(stateDir);
+  // #685: `--as <id>` selects an extra Jcode instance; every request below names it, never the base peer.
+  const peer = ctx.instance ?? "jcode";
   const mode = one["--mode"] ?? (ctx.instance ? "headless" : control?.startModes?.jcode ?? startModeOf(ctx.projectConfig().peers, "jcode"));
+  if (ctx.instance && mode === "tui") fail(`${peer} is an extra Jcode instance: it runs headless on its own private server (ahub jcode --as ${peer}); the TUI belongs to the base jcode`);
   if (print && (mode === "headless" || !control?.features?.includes("native_tui_launch"))) {
     try { return console.log(JSON.stringify(launcherPreview("jcode", args, cwd, stateDir, unattendedEnv), null, 2)); }
     catch { return fail("cannot preview Jcode launch: invalid arguments or configuration (details withheld)"); }
@@ -66,10 +69,10 @@ export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
   hub.onClose = (code, reason) => { if (!abort.signal.aborted) abort.abort(); oldClose?.(code, reason); };
   try {
     const snapshot = (await hub.request({ t: "status" })).status;
-    const rostered = rosterInStatus(snapshot, "jcode");
-    if (rostered === undefined) fail("cannot read jcode's roster membership from the running hub; upgrade or restart it, then retry (nothing was started)");
-    if (!rostered) fail("jcode is off roster; add it with ahub roster add jcode");
-    const warning = retainedLaunchWarning(snapshot, "jcode", ctx.definition); if (warning) console.error(warning);
+    const rostered = rosterInStatus(snapshot, peer);
+    if (rostered === undefined) fail(`cannot read ${peer}'s roster membership from the running hub; upgrade or restart it, then retry (nothing was started)`);
+    if (!rostered) fail(`${peer} is off roster; add it with ahub roster add ${peer}`);
+    const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
     const options = { model: one["--model"], providerProfile: one["--provider-profile"], sessionId: one["--session-id"] };
     if (print) {
       if (!hub.features.includes("native_tui_launch") || mode !== "tui") return console.log(JSON.stringify(launcherPreview("jcode", args, cwd, stateDir, unattendedEnv), null, 2));
@@ -89,10 +92,10 @@ export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
     }
     const written = configureJcodeMcp(cwd, stateDir, bundleInStatus(snapshot) ?? resolve(cliDir, "../../plugins/agent-hub/server.js"));
     if (written.tracked) console.error(".jcode/mcp.json is tracked; review this local machine-path change before committing it");
-    const reply = await hub.request({ t: "start", peer: "jcode", args: { mode, ...options }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 65_000);
+    const reply = await hub.request({ t: "start", peer, args: { mode, ...options }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 65_000);
     if (interruptedWait()) return;
     if (!reply.ok) fail(reply.error);
-    if (mode === "headless") { console.log(reply.already ? "jcode is already attached" : "jcode attached (headless); native policy unmanaged, NO hub sandbox"); return; }
+    if (mode === "headless") { console.log(reply.already ? `${peer} is already attached` : `${peer} attached (headless); native policy unmanaged, NO hub sandbox`); return; }
     const ready = await waitForJcodeTui(hub, fail, abort.signal, options);
     if (interruptedWait() || !ready) return;
     // No managed terminal record: Jcode's controlled recovery is refused at plan time, so, like Kimi's TUI, it has

package/src/adapters/definitions/native-cli-jcode-mcp.ts

@@ -18,10 +18,17 @@ function document(file: string): Document {
   return value;
 }
 const map = (doc: Document): Document => (doc.mcpServers ?? doc.servers ?? {}) as Document;
-const owned = (entry: unknown, cwd: string): entry is Document => object(entry) && object(entry.env) && entry.env.AGENTHUB_MODE === "tools" && entry.env.AGENTHUB_PEER_ID === "jcode" && entry.env.AGENTHUB_PROJECT_DIR === cwd;
+/**
+ * The project's `.jcode/mcp.json` entry is shared by every Jcode in it, so it names no peer (#685): jcode gives an entry's own env
+ * precedence over the process env (probed on 0.99.0), so a hardcoded `AGENTHUB_PEER_ID: "jcode"` would make an extra instance's
+ * hub tools act as the base peer. Each owned launch path supplies its own id instead (peerChildEnv for serve and ACP, the TUI launch env).
+ * An entry written before this still hardcodes the id: `jcodeMcpReady` is false for it, and the launcher rewrites it.
+ */
+const owned = (entry: unknown, cwd: string): entry is Document => object(entry) && object(entry.env) && entry.env.AGENTHUB_MODE === "tools"
+  && (entry.env.AGENTHUB_PEER_ID === undefined || entry.env.AGENTHUB_PEER_ID === "jcode") && entry.env.AGENTHUB_PROJECT_DIR === cwd;
 
 export function jcodeMcpEntry(cwd: string, stateDir: string, bundle: string) {
-  return { command: "bun", args: ["run", bundle], shared: false, env: { AGENTHUB_MODE: "tools", AGENTHUB_DELIVERY_ONLY: "true", AGENTHUB_PEER_ID: "jcode", AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } };
+  return { command: "bun", args: ["run", bundle], shared: false, env: { AGENTHUB_MODE: "tools", AGENTHUB_DELIVERY_ONLY: "true", AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } };
 }
 /** The native loader reads later project files last. Never shadow a foreign definition. */
 function inspect(cwd: string): Document {

package/src/adapters/definitions/native-cli-preview-common.ts

@@ -23,6 +23,8 @@ export interface NativePreviewHelpers {
 export interface NativePreviewContext {
   tool: string; args: string[]; cwd: string; stateDir: string; cliDir: string; unattended: boolean;
   config: ReturnType<typeof loadConfig>; definition: AdapterDefinition; baseEnvNames: string[]; helpers: NativePreviewHelpers;
+  /** The declared extra instance a `--as <id>` launch selected; its own model fields belong in the preview (#685). */
+  instance?: string;
 }
 export interface NativePreviewMetadata { mode: "tui" | "headless"; mcp: { file: string; action: string; changed: boolean; tracked: boolean } }
 export type NativePreviewBuilder = (ctx: NativePreviewContext) => NativePreview;

package/src/adapters/definitions/native-cli-preview-jcode.ts

@@ -2,7 +2,7 @@ import type { Launch } from "../../cli/launch.ts";
 import { REDACTED, UNRESOLVED, nativeCommand, previewState, finishPreview, type NativePreviewContext, type NativePreview } from "./native-cli-preview-common.ts";
 
 export function previewJcode(ctx: NativePreviewContext): NativePreview {
-  const { args, config } = ctx;
+  const { args, config, instance } = ctx;
   const { jcodeCommand, jcodeTuiCommand, qwenSessionId, startModeOf } = ctx.helpers;
   const state = previewState(args, ctx.baseEnvNames), { unresolved, value } = state;
   let envNames = state.envNames;
@@ -11,7 +11,13 @@ export function previewJcode(ctx: NativePreviewContext): NativePreview {
   if (mode !== "headless" && mode !== "tui") throw new Error("invalid Jcode start mode");
   for (let i = 0; i < args.length; i += 2) if (!["--model", "--mode", "--provider-profile", "--session-id"].includes(args[i]!) || !args[i + 1]) throw new Error("unknown Jcode option");
   if (session !== undefined && !qwenSessionId(session)) throw new Error("invalid Jcode session identity");
-  const cmd = mode === "tui" ? jcodeTuiCommand(nativeCommand(config.jcode_cmd, ["jcode"]), UNRESOLVED, UNRESOLVED, model ? REDACTED : undefined, profile || config.jcode_provider_profile ? REDACTED : undefined) : jcodeCommand(nativeCommand(config.jcode_cmd, ["jcode"]), "acp", UNRESOLVED, UNRESOLVED, model ? REDACTED : undefined, profile || config.jcode_provider_profile ? REDACTED : undefined);
+  // The daemon starts an instance with its own declared provider, model and profile (a launch flag still wins, as in the start branch):
+  // preview the same flags. Values stay redacted, as the base Jcode's model and profile already are.
+  const declared = instance ? config.instances?.[instance] : undefined;
+  const provider = declared?.provider ? REDACTED : undefined, modelWord = model || declared?.model ? REDACTED : undefined;
+  const profileWord = profile || declared?.provider_profile || config.jcode_provider_profile ? REDACTED : undefined;
+  const cmd = mode === "tui" ? jcodeTuiCommand(nativeCommand(config.jcode_cmd, ["jcode"]), UNRESOLVED, UNRESOLVED, modelWord, profileWord, provider)
+    : jcodeCommand(nativeCommand(config.jcode_cmd, ["jcode"]), "acp", UNRESOLVED, UNRESOLVED, modelWord, profileWord, provider, instance ?? "jcode");
   launch = { cmd: cmd[0]!, args: cmd.slice(1) };
   unresolved.push({ field: "ownedDaemon", reason: "private daemon/socket and source-pinned native identity verified at start; preview starts nothing" });
   unresolved.push({ field: "hubTools", reason: "project MCP bridge required; native tool-call receipt remains unverified" });

package/src/adapters/definitions/native-cli-preview-qwen.ts

@@ -1,3 +1,4 @@
+import { describe } from "../compat.ts";
 import { join } from "node:path";
 import type { Launch } from "../../cli/launch.ts";
 import { REDACTED, UNRESOLVED, nativeCommand, previewState, finishPreview, type NativePreviewContext } from "./native-cli-preview-common.ts";
@@ -16,7 +17,7 @@ export function previewQwen(ctx: NativePreviewContext) {
   if (sessionId) unresolved.push({ field: "sessionId", reason: "requested through ACP session/load at start; preview does not load or expose it" });
   launch = adapter.start.launch!({ instance: tool, form: "headless", projectRoot: cwd, stateDir, entrypoint: join(cliDir, "main.js"),
     userArgs: [], unattended: false, env: {}, preview: true, nativeCommand: nativeCommand(config.qwen_cmd, ["qwen", "--acp"]), model: model ? REDACTED : undefined });
-  unresolved.push({ field: "nativeIdentity", reason: "Qwen Code 0.25.0 identity and permission modes are checked at ACP initialization; preview starts nothing" });
+  unresolved.push({ field: "nativeIdentity", reason: `Qwen Code (${describe("qwen")}) identity and permission modes are checked at ACP initialization; preview starts nothing` });
 
   return finishPreview(ctx, launch, envNames, unresolved, undefined);
 }

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

@@ -1,16 +1,20 @@
+import { assessVersion } from "../compat.ts";
 import type { PermissionMode } from "../../hub/permission-mode.ts";
 import type { Launch } from "../../cli/launch.ts";
 
 export const QWEN_MODE_IDS: Readonly<Record<PermissionMode, string>> = { ask: "default", "ask-when-needed": "auto-edit", "never-ask": "yolo" };
 
 export class QwenIdentityError extends Error {
-  constructor() { super("Qwen Code 0.25.0 native identity is not verified; check the executable and its advertised ACP version"); }
+  constructor(reason?: string) { super(reason ? `Qwen Code native identity is not verified: ${reason}` : "Qwen Code native identity is not verified; check the executable and its advertised ACP version"); }
 }
 
 export function qwenNativeIdentity(instance: string, production: boolean | undefined, init: unknown, kind?: string): boolean {
   const native = init as { agentInfo?: { name?: unknown; version?: unknown } } | null | undefined;
-  const verified = production === true && (kind ?? instance) === "qwen" && native?.agentInfo?.name === "qwen-code" && native?.agentInfo?.version === "0.25.0";
-  if (production && !verified) throw new QwenIdentityError();
+  const identity = production === true && (kind ?? instance) === "qwen" && native?.agentInfo?.name === "qwen-code";
+  // #691: a version refusal carries the compat reason (observed and verified versions, the trust command).
+  const version = identity ? assessVersion("qwen", native?.agentInfo?.version) : undefined;
+  if (production && !version?.ok) throw new QwenIdentityError(version && !version.ok ? version.reason : undefined);
+  const verified = !!version?.ok;
   return verified;
 }
 

package/src/adapters/definitions/qwen.ts

@@ -1,3 +1,4 @@
+import { describe } from "../compat.ts";
 import { runQwenEntry } from "./native-cli-entry-qwen.ts";
 import { previewQwen } from "./native-cli-preview-qwen.ts";
 import { QWEN_DISPLAY } from "./native-display.ts";
@@ -67,7 +68,7 @@ export const QWEN_DEFINITION: AdapterDefinition = {
   turnEnd: "adapter",
   budget: { account: "qwen" },
   capabilities: { watch: true },
-  cli: { command: "qwen", entry: { lifecycleAdmission: true, execute: runQwenEntry }, preview: previewQwen, usage: [["ahub qwen [--mode headless] [--model <alias>] [--session-id <id>] [--print-command]", "start optional Qwen Code 0.25.0 ACP (roster.qwen, default off)"]], launchConfigKeys: ["qwen_cmd"], startWords: () => ["qwen"] },
+  cli: { command: "qwen", entry: { lifecycleAdmission: true, execute: runQwenEntry }, preview: previewQwen, usage: [["ahub qwen [--mode headless] [--model <alias>] [--session-id <id>] [--print-command]", `start optional Qwen Code ACP (${describe("qwen")}; roster.qwen, default off)`]], launchConfigKeys: ["qwen_cmd"], startWords: () => ["qwen"] },
   display: QWEN_DISPLAY,
   hooks: { recallPlatform: "qwen" },
 };