@staix/agent-hub 0.12.44 → 0.13.0

package/src/adapters/adapter-api.ts

@@ -0,0 +1,2 @@
+/** Version of the public, person-authorized adapter definition contract. */
+export const ADAPTER_API = 1;

package/src/adapters/agy/definition.ts

@@ -1,3 +1,4 @@
+import { runAgyEntry } from "./entry.ts";
 import type { AdapterDefinition, LaunchContext, LaunchPlan } from "../registry-types.ts";
 import { AGY_REVIEWER_VARIANT } from "../definitions/reviewer-variants.ts";
 import { AGY_FACTS_HOOK } from "./hooks.ts";
@@ -15,6 +16,7 @@ function agyLaunch(ctx: LaunchContext): LaunchPlan {
 export const AGY_DEFINITION: AdapterDefinition = {
   api: 1,
   kind: "agy",
+  projection: { roleRank: 7, helpRank: 4, plannerEligible: false },
   displayName: "Antigravity",
   family: "agy",
   transport: "ws-pull",
@@ -50,7 +52,7 @@ export const AGY_DEFINITION: AdapterDefinition = {
     recoveryRefusal: () => "Antigravity session continuity and resume are unavailable until native behavior is verified",
   },
   turnEnd: "native-hook",
-  cli: { command: "agy", authority: "person", startWords: () => ["agy"] },
+  cli: { command: "agy", entry: { lifecycleAdmission: true, execute: runAgyEntry }, usage: [["ahub agy [--print-command | --dry-run] [args...]", "optional Antigravity CLI 1.4.x TUI (1.4.2 verified) in this terminal (roster.agy, default off): pull-only via hub_inbox, implementer/verifier only; native permissions unmanaged, no hub sandbox"]], authority: "person", startWords: () => ["agy"] },
   display: DISPLAY,
   routing: { allowedRoles: ["implementer", "verifier"] },
   reviewer: { defaultPool: false, declaration: "automatic", unavailable: "agy is an implementer peer (#485)" },

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",
@@ -157,6 +164,8 @@ const offline = () => detached ?? "hub is not running for this project (start it
  * Surfaced on the next tool result; the pull itself still happens only through hub_inbox.
  */
 let pendingQueued: { queued: number; important: number } | undefined;
+/** Marks a tool result whose text already states the queued count (#221), so the fresh-count block does not repeat it. Symbol keys never reach the client. */
+const QUEUED_COUNTED = Symbol("queuedCounted");
 /** Fresh own-peer counts accompany all tool modes; only old plain sessions use advisory queued nudges. */
 async function withPendingHint<T>(result: T, recommendInbox = true): Promise<T> {
   const r = result as { content?: { type: string; text?: string }[] };
@@ -169,23 +178,28 @@ async function withPendingHint<T>(result: T, recommendInbox = true): Promise<T>
   };
   if (hub && r.content) {
     let freshCounts = false;
+    let hint = "";
     try {
       const response = await hub.request({ t: "delivery_holds" }, 1000);
+      // A hold that refuses pulls (#221): hub_inbox would only be refused again, so the counts stay and the advice goes.
+      hint = response?.ok ? renderHeldHint(response.held, Date.now(), !deliveryOnly) : "";
       if (response?.ok && Number.isSafeInteger(response.queued) && response.queued >= 0
         && Number.isSafeInteger(response.important) && response.important >= 0 && response.important <= response.queued) {
         freshCounts = true;
         pendingQueued = undefined; // A current zero must never resurrect an earlier queued nudge.
         if (response.important > 0) {
-          const next = !recommendInbox ? "" : toolsMode
+          const next = !recommendInbox || hint ? "" : toolsMode
             ? ": use hub_inbox on a pull-capable peer session; otherwise finish the current turn to receive queued deliveries"
             : ": call hub_inbox before starting long local work";
-          appendQueued(`(${response.queued} queued hub message(s), ${response.important} important hub message(s) waiting${next})`);
+          // One queued count per result (#221): a hub_inbox result that already says how many remain unread adds only the important count.
+          const counted = (result as { [QUEUED_COUNTED]?: boolean })[QUEUED_COUNTED] === true;
+          appendQueued(counted ? `(${response.important} important hub message(s) waiting${next})` : `(${response.queued} queued hub message(s), ${response.important} important hub message(s) waiting${next})`);
         }
       }
-      const hint = response?.ok ? renderHeldHint(response.held, Date.now(), !deliveryOnly) : "";
       if (hint) r.content.push({ type: "text", text: hint });
     } catch { /* advisory metadata can never change a saved tool result or its effect classification */ }
-    if (!freshCounts && recommendInbox && !channel && !toolsMode && pendingQueued && pendingQueued.important > 0) {
+    // A pre-#493 daemon sends held rows without counts; the legacy nudge must not advise a read the hold refuses (#221).
+    if (!freshCounts && !hint && recommendInbox && !channel && !toolsMode && pendingQueued && pendingQueued.important > 0) {
       appendQueued(`(${pendingQueued.important} important hub message(s) waiting: call hub_inbox before starting long local work)`);
     }
   }
@@ -244,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) => {
@@ -368,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 ?? {};
@@ -375,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" });
@@ -384,14 +399,19 @@ 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);
-    return text(out.length ? out.join("\n\n") : "(no queued hub messages)");
+    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") {
     const { text: body, to, reply_to } = (args ?? {}) as { text?: string; to?: string[]; reply_to?: string };
@@ -418,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;
@@ -488,6 +497,7 @@ export class CodexPeer extends BasePeer {
   get proxyAttached(): boolean { return !!this.link && this.link.up.readyState === WebSocket.OPEN; }
 
   getPermissionMode(): PermissionMode { return this.permissionMode; }
+  get permissionModeState(): PermissionMode { return this.getPermissionMode(); }
 
   /** Reconcile the daemon's current choice after startup, before the returned proxy URL has a TUI. */
   setStartupPermissionMode(mode: PermissionMode): void {
@@ -583,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;
@@ -647,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/conformance/acp.ts

@@ -0,0 +1,114 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { AcpPeer } from "../acp.ts";
+import { newEnvelope } from "../../hub/envelope.ts";
+import type { DeliveryReceipt } from "../../hub/peers.ts";
+import { processTable } from "../../hub/child-process.ts";
+import { until } from "./kit.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
+import { fakePaths } from "./fake-paths.ts";
+import { createFromDefinition, expire } from "./factories.ts";
+import { ACP_LEGS, assertAcpLegEnrollment, type AcpLeg } from "./enrollment.ts";
+
+export interface AcpConformanceOptions {
+  definition: AdapterDefinition;
+  agentArgs?: readonly string[];
+  unsupported?: Partial<Record<AcpLeg, string>>;
+  permissionPrompts?: { accepted: string; foreign: string };
+  startupModeAcknowledgement?: boolean;
+  modeAcknowledgement?: string;
+  quotaLabel?: string;
+  watchdogLabel?: string;
+}
+/** No protocol is run at import; callers explicitly select supported fake protocol legs. */
+export function registerAcpConformance(options: AcpConformanceOptions): void {
+    const { definition } = options, kind = definition.kind, fake = fakePaths.acpServer;
+    if (definition.transport !== "acp") throw new Error(kind + ": ACP conformance requires an ACP definition");
+    const reasons = Object.fromEntries(Object.entries(options.unsupported ?? {}).map(([leg, reason]) => [kind + ":" + leg, reason!]));
+    assertAcpLegEnrollment([definition], reasons);
+    if (!options.unsupported?.["native-mode-ack"] && !options.modeAcknowledgement) throw new Error(kind + ": mode acknowledgement fixture must be explicit");
+  // The catalog chooses every real registration or explicit unsupported outcome; no kind is filtered away.
+  const registrations: Record<AcpLeg, (kind: string) => void> = {
+    "native-approval-rpc": kind => {
+      test(`P4 ${kind}: real permission RPC approves exact hub identity once and asks on a lookalike`, async () => {
+        const dir = mkdtempSync(join(tmpdir(), "conformance-approval-")), asked: string[] = [], replies: string[] = [];
+        const peer = createFromDefinition<AcpPeer>(definition, { acp: { cwd: dir, cmd: [process.execPath, fake, ...(options.agentArgs ?? [])],
+          mcpServers: [{ name: "agent-hub", command: "unused", args: [], env: [] }],
+          autoApprove: title => title === "mcp__agent-hub__hub_task_list" || title === "mcp__agent-hub__hub_send",
+          onPermission: async request => { asked.push(request.title); return "no"; } } });
+        peer.onMessage = text => { replies.push(text); };
+        try {
+          await peer.start();
+          await peer.deliver([newEnvelope("user", options.permissionPrompts?.accepted ?? "PERMISSION HUBTOOL")]);
+          await until(() => replies.length === 1 && peer.state === "idle", "autoapproved permission settled");
+          expect(replies[0]).toEndWith("permission=yes"); expect(asked).toEqual([]);
+          await peer.deliver([newEnvelope("user", options.permissionPrompts?.foreign ?? "PERMISSION SPOOF")]);
+          await until(() => replies.length === 2 && peer.state === "idle", "lookalike permission settled");
+          expect(asked).toHaveLength(1); expect(replies[1]).toEndWith("permission=no");
+          await peer.setPermissionMode("never-ask"); expect(peer.permissionModeState).toBe("never-ask");
+          await peer.setPermissionMode("ask"); expect(peer.permissionModeState).toBe("ask");
+        } finally { await peer.stop(); rmSync(dir, { recursive: true, force: true }); }
+      }, 20_000);
+    },
+    "native-mode-ack": kind => {
+      const modeAcknowledgement = options.modeAcknowledgement;
+      if (!modeAcknowledgement) throw new Error(kind + ": mode acknowledgement fixture must be explicit");
+      test(`P4 ${kind}: unconfirmed mode change goes unknown/offline despite a late acknowledgement`, async () => {
+        const dir = mkdtempSync(join(tmpdir(), "conformance-mode-")), pid = join(dir, "pid"), ack = join(dir, "ack");
+        const peer = createFromDefinition<AcpPeer>(definition, { acp: { cwd: dir, cmd: [process.execPath, fake, ...(options.agentArgs ?? []), "--ignore-term", "--mode-delay-ms", "200", "--mode-ack-record", ack, "--record-pid", pid],
+          permissionModeTimeoutMs: 40 } });
+        try {
+          // Qwen reconciles its default at startup; Kimi's unchanged ask default needs no initial request.
+          if (options.startupModeAcknowledgement) await expect(peer.start()).rejects.toThrow("unknown");
+          else { await peer.start(); await expect(peer.setPermissionMode("never-ask")).rejects.toThrow("unknown"); }
+          expect(peer.permissionModeState).toBe("unknown"); expect(peer.state).toBe("offline");
+          expect(readFileSync(ack, "utf8").trim()).toBe(modeAcknowledgement);
+          const owned = Number(readFileSync(pid, "utf8")), table = processTable();
+          expect(table).toBeDefined(); expect(table!.some(row => row.pid === owned || row.pgid === owned)).toBe(false);
+          await expect(peer.setPermissionMode("ask")).rejects.toThrow("unknown");
+          await expect(peer.deliver([newEnvelope("user", "must not start")])).rejects.toThrow("offline");
+        } finally { await peer.stop(); rmSync(dir, { recursive: true, force: true }); }
+      }, 20_000);
+    },
+    "native-quota": kind => {
+      test(`P4 ${options.quotaLabel ?? kind}: confirmed pre-activity quota pause settles failed_safe, not an ordinary failure`, async () => {
+        const dir = mkdtempSync(join(tmpdir(), "conformance-quota-")), receipts: DeliveryReceipt[] = [], order: string[] = [], failures: string[] = [];
+        const peer = createFromDefinition<AcpPeer>(definition, { acp: { cwd: dir, cmd: [process.execPath, fake, ...(options.agentArgs ?? []), "--quota-refusal"],
+          onQuotaRefusal: () => { order.push("paused"); return true; }, onTurnFailure: (_envs, reason) => { failures.push(reason); } } });
+        peer.onDelivery = receipt => { receipts.push(receipt); order.push(receipt.state); };
+        try {
+          await peer.start(); await peer.deliver([newEnvelope("user", "QUOTA_REFUSAL")], "quota");
+          await until(() => receipts.length > 0, "quota refusal receipt");
+          expect(order).toEqual(["paused", "failed_safe"]); expect(receipts[0]).toMatchObject({ id: "quota", state: "failed_safe", quota: true }); expect(failures).toEqual([]);
+        } finally { await peer.stop(); rmSync(dir, { recursive: true, force: true }); }
+      });
+    },
+    "watchdog-generation": kind => {
+      test(`P4 ${options.watchdogLabel ?? kind}: watchdog cancellation fences the consumed late native result by turn generation`, async () => {
+        const dir = mkdtempSync(join(tmpdir(), "conformance-watchdog-")), receipts: DeliveryReceipt[] = [], messages: string[] = [];
+        const peer = createFromDefinition<AcpPeer>(definition, { acp: { cwd: dir, cmd: [process.execPath, fakePaths.acpWatchdog, ...(options.agentArgs ?? [])] } });
+        peer.onDelivery = receipt => { receipts.push(receipt); }; peer.onMessage = text => { messages.push(text); };
+        try {
+          await peer.start(); await peer.deliver([newEnvelope("user", "ACK_SLOW")], "old");
+          await until(() => receipts.some(receipt => receipt.state === "accepted"), "native acceptance before explicit expiry");
+          expire(peer);
+          await until(() => receipts.some(receipt => receipt.state === "needs_review"), "watchdog uncertainty");
+          // The fake responds to this mode request after sending the old prompt result on the same stdio stream.
+          await peer.setPermissionMode("ask");
+          expect(receipts.map(receipt => receipt.state)).toEqual(["accepted", "needs_review"]);
+          expect(messages).toEqual([]); expect(peer.state).toBe("offline");
+        } finally { await peer.stop(); rmSync(dir, { recursive: true, force: true }); }
+      });
+    },
+  };
+
+  for (const leg of ACP_LEGS) {
+    const reason = options.unsupported?.[leg];
+    if (reason !== undefined) test(`P4 ${kind}: ${leg} explicitly unsupported by its native transport`, () => {
+      expect(reason.trim()).not.toBeEmpty();
+    });
+    else registrations[leg](kind);
+}
+}