@staix/agent-hub 0.12.43 → 0.12.45

package/src/adapters/claude-channel.ts

@@ -13,7 +13,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { ControlClient, stateDirFor } from "../hub/control-client.ts";
 import { VERSION } from "../version.ts";
-import { ACTIONABLE_MESSAGE_INSTRUCTION, CONDUCTOR_TOOLS, CONDUCTOR_TOOL_NAMES, DEFAULT_ROLES, roleContract, TASK_TOOL_NAMES, TASK_TOOLS, profileTaskTools } from "../hub/hub-tools.ts";
+import { ACTIONABLE_MESSAGE_INSTRUCTION, projectConductorTools, projectToolList, CONDUCTOR_TOOL_NAMES, DEFAULT_ROLES, roleContract, TASK_TOOL_NAMES, TASK_TOOLS, profileTaskTools } from "../hub/hub-tools.ts";
 import { frame, replyParent, sanitize, HUB_MESSAGE_INSTRUCTION, type Envelope } from "../hub/envelope.ts";
 import { renderHeldHint } from "../hub/delivery-hints.ts";
 
@@ -46,8 +46,8 @@ function roles(): Record<string, string[]> {
   };
   const configured = { ...DEFAULT_ROLES, ...read("config.json"), ...read("config.local.json") };
   try {
-    const declarations = readInstanceConfig(projectRoot).instances;
-    for (const id of Object.keys(declarations ?? {})) configured[id] = effectiveInstanceRoles(id, declarations, configured);
+    const { instances: declarations, catalog } = readInstanceConfig(projectRoot);
+    for (const id of Object.keys(declarations ?? {})) configured[id] = effectiveInstanceRoles(id, declarations, configured, catalog);
   } catch { /* Invalid declarations authorize no extra role; the daemon remains the write authority. */ }
   return configured;
 }
@@ -157,6 +157,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 +171,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)`);
     }
   }
@@ -318,7 +325,7 @@ async function buildToolList() { return toolListFor(await activeLifecycle(stateD
 
 function toolListFor(lifecycle: Awaited<ReturnType<typeof activeLifecycle>>) {
   return {
-  tools: [
+  tools: projectToolList([
     {
       name: "hub_send",
       description:
@@ -355,8 +362,8 @@ function toolListFor(lifecycle: Awaited<ReturnType<typeof activeLifecycle>>) {
             : []),
         ]),
     ...profileTaskTools(profile, lifecycle?.stages, lifecycle?.criteria).filter(tool => (lifecycle !== undefined || tool.name !== "hub_sdlc_record") && (!deliveryOnly || tool.name !== "hub_delivery_retry")),
-    ...CONDUCTOR_TOOLS,
-  ],
+    ...projectConductorTools(lifecycle?.startPeers),
+  ], lifecycle?.readOnly),
   };
 }
 
@@ -391,7 +398,9 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
     // 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 result = text(out.length ? out.join("\n\n") : "(no queued hub messages)");
+    if (notice.endsWith("remain unread)")) 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 };
@@ -406,7 +415,7 @@ async function callTool(req: { params: { name: string; arguments?: Record<string
   if (TASK_TOOL_NAMES.has(name) || CONDUCTOR_TOOL_NAMES.has(name)) {
     if (!hub) return text(offline());
     const res = await hub.request({ t: "task", op: name, args: args ?? {} });
-    return text(res.ok ? res.text : `error: ${res.error}`);
+    return { ...text(res.ok ? res.text : `error: ${res.error}`), ...(res.ok ? {} : { isError: true }) };
   }
   return text(`unknown tool ${name}`);
 }

package/src/adapters/codex-appserver.ts

@@ -5,6 +5,9 @@ import type { PermissionMode } from "../hub/permission-mode.ts";
 import { BasePeer } from "../hub/peers.ts";
 import { codexContext, type ContextReading } from "../hub/context-window.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
+import type { ContextReader } from "./registry-types.ts";
+
+const UNIDENTIFIED_CANCELLATION_NOTICE = "Codex cancelled turn has no verified native id; reattach the native session before further hub delivery";
 
 export interface CodexOptions {
   /** Port the TUI attaches to: `codex --enable tui_app_server --remote ws://127.0.0.1:<proxyPort>`. */
@@ -26,6 +29,8 @@ export interface CodexOptions {
   /** Tokens the thread used since the previous update (see `tokenTotal` for how they are counted). */
   onTokens?: (added: number) => void;
   onContext?: (reading: ContextReading) => void;
+  /** The definition's native occupancy reader; standalone proxies retain the native default. */
+  contextReader?: ContextReader;
   /** The native id of each turn as it starts, after the peer turned busy (issue #33: `ahub undo --context`). */
   onTurn?: (turnId: string) => void;
   /** Each thread the TUI starts (`fresh`) or resumes, as it is adopted (#215: which turns belong to which thread). */
@@ -90,6 +95,10 @@ export class CodexPeer extends BasePeer {
   /** Cancellation tombstones last until that exact native completion or session replacement. */
   private readonly retiredTurns = new Set<string>();
   private unidentifiedCancellation = false;
+  /** Fixed operator guidance only; native identifiers and agent text never enter status. */
+  get statusNotice(): { code: "unidentified-cancellation"; message: string } | undefined {
+    return this.unidentifiedCancellation ? { code: "unidentified-cancellation", message: UNIDENTIFIED_CANCELLATION_NOTICE } : undefined;
+  }
   private unboundAccepted = false;
   private nextId = -1;
   private readonly pending = new Map<number, { resolve: (result?: any) => void; reject: (e: Error) => void; deliveryId?: string; kind?: "deliver" | "steer"; expectedTurnId?: string; afterTurn?: () => void; invalidate?: (reason: string) => void }>();
@@ -342,7 +351,7 @@ export class CodexPeer extends BasePeer {
       // ponytail: after one unidentifiable cancellation, lifecycle attribution requires a session reattach.
       // Never guess that an unnamed late report or a later named start belongs to a new turn.
       this.unidentifiedCancellation = true;
-      this.opts.log?.("Codex cancelled turn has no verified native id; reattach the native session before further hub delivery");
+      this.opts.log?.(UNIDENTIFIED_CANCELLATION_NOTICE);
     }
     for (const turnId of known) this.retireTurn(turnId);
     for (const pending of pendingStarts) pending.invalidate?.("Codex turn watchdog timeout before native acceptance was confirmed");
@@ -479,6 +488,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 {
@@ -634,7 +644,8 @@ export class CodexPeer extends BasePeer {
     if (this.unidentifiedCancellation) return; // native traffic is still forwarded to its TUI; hub attribution is fenced
     const unknownTurn = () => [...this.activeTurns].some(id => id.startsWith("unknown:"));
     if (method === "thread/tokenUsage/updated") {
-      this.opts.onContext?.(codexContext(params.tokenUsage, this.threadId, Date.now()));
+      const reader = this.opts.contextReader;
+      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 added = this.tokenTotal === undefined ? (this.freshThread ? total : 0) : Math.max(0, total - this.tokenTotal);
@@ -707,3 +718,7 @@ function parse(raw: string): any {
     return undefined;
   }
 }
+
+export function isCodexPeer(value: unknown): value is CodexPeer {
+  return value instanceof CodexPeer;
+}

package/src/adapters/configured-acp.ts

@@ -0,0 +1,124 @@
+import { basename } from "node:path";
+import { types } from "node:util";
+import { AcpPeer } from "./acp.ts";
+import type { AdapterDefinition } from "./registry-types.ts";
+import type { PermissionMode } from "../hub/permission-mode.ts";
+import { shellQuote } from "../cli/shell-quote.ts";
+
+export interface ConfiguredAcpAdapterConfig {
+  transport: "acp";
+  command: string;
+  args?: readonly string[];
+  displayName: string;
+  roles: readonly string[];
+  identity?: { name: string; version: string };
+  permission?: Partial<Record<PermissionMode, string>>;
+  readOnly?: string;
+}
+const fail = (field: string, reason: string): never => { throw new Error(`${field}: ${reason}`); };
+/** Core command namespace is reserved; configured kinds cannot shadow operational CLI actions. */
+export const CONFIGURED_ACP_RESERVED_COMMANDS = Object.freeze(["help", "version", "completion", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "recovery-run", "upgrade", "restart", "recovery", "models", "say", "queue", "watch", "tail", "budget", "backlog", "release", "board", "sdlc", "task", "review", "remember", "ask", "route", "pause", "resume", "stop", "permission", "roster", "settings", "permit", "pet", "status", "logs", "export", "bench", "memory", "goal", "research", "report", "facts", "check-path", "turns", "undo", "kill", "reset", "role", "doctor"]);
+const MODES = ["ask", "ask-when-needed", "never-ask"];
+const ROLES = ["planner", "implementer", "verifier", "reviewer"];
+function fields(raw: unknown, at: string): Record<string, PropertyDescriptor> {
+  if (!raw || typeof raw !== "object" || types.isProxy(raw) || Array.isArray(raw) || ![Object.prototype, null].includes(Object.getPrototypeOf(raw)) || Object.getOwnPropertySymbols(raw).length) return fail(at, "must be a plain own-data object");
+  const result: Record<string, PropertyDescriptor> = Object.assign(Object.create(null), Object.getOwnPropertyDescriptors(raw));
+  if (Object.values(result).some(d => !Object.hasOwn(d, "value") || !d.enumerable)) return fail(at, "enumerable data fields required");
+  return result;
+}
+function text(raw: unknown, at: string, max = 4096): string {
+  if (typeof raw !== "string" || !raw.trim() || Buffer.byteLength(raw) > max || /[\p{Cc}\p{Cf}]/u.test(raw)) return fail(at, `must be nonempty control-free text of at most ${max} bytes`);
+  return raw;
+}
+function list(raw: unknown, at: string, max: number): string[] {
+  if (!Array.isArray(raw) || types.isProxy(raw) || Object.getPrototypeOf(raw) !== Array.prototype || Object.getOwnPropertySymbols(raw).length) return fail(at, "must be a string array");
+  const descriptors: Record<string, PropertyDescriptor> = Object.assign(Object.create(null), Object.getOwnPropertyDescriptors(raw));
+  const length = descriptors.length?.value;
+  if (!Number.isSafeInteger(length) || length > max || Object.keys(descriptors).length !== length + 1) return fail(at, "array is sparse or too large");
+  return Array.from({ length }, (_, index) => {
+    const d = descriptors[String(index)];
+    if (!d || !Object.hasOwn(d, "value") || !d.enumerable) return fail(at, "array data fields required");
+    return text(d.value, `${at}.${index}`);
+  });
+}
+function freeze<T>(value: T): T {
+  if (value && typeof value === "object") { for (const item of Object.values(value)) freeze(item); Object.freeze(value); }
+  return value;
+}
+
+/** Pure local declaration compiler; file provenance and runtime process ownership remain host checks. */
+export function configuredAcpDefinitions(raw: unknown, builtinKinds: readonly string[]): readonly AdapterDefinition[] {
+  if (raw === undefined) return Object.freeze([]);
+  const declarations = fields(raw, "adapters");
+  if (Object.keys(declarations).length > 64) return fail("adapters", "at most 64 configured kinds supported");
+  const reserved = new Set([...builtinKinds, ...CONFIGURED_ACP_RESERVED_COMMANDS, "user", "hub", "digest", "constructor", "prototype", "__proto__"]);
+  return Object.freeze(Object.entries(declarations).map(([kind, descriptor]) => {
+    const at = `adapters.${kind}`;
+    if (!/^[a-z][a-z0-9-]{0,31}$/.test(kind) || reserved.has(kind)) return fail(at, "kind is invalid, reserved or collides with a builtin");
+    const input = fields(descriptor.value, at);
+    if (Object.keys(input).some(key => !["transport", "command", "args", "displayName", "roles", "identity", "permission", "readOnly"].includes(key))) return fail(at, "unknown or privileged field");
+    if (input.transport?.value !== "acp") return fail(`${at}.transport`, "must be acp");
+    const command = text(input.command?.value, `${at}.command`), args = input.args ? list(input.args.value, `${at}.args`, 128) : [];
+    // The supported contract is a foreground owned stdio process, never an attachment/proxy selector.
+    if ([command, ...args].some(arg => /^--(?:leader|attach|connect|remote)(?:-|=|$)/.test(arg))) return fail(`${at}.args`, "attach/leader selectors are unsupported; command must run foreground owned ACP stdio");
+    const displayName = text(input.displayName?.value, `${at}.displayName`, 256), roles = list(input.roles?.value, `${at}.roles`, ROLES.length);
+    if (roles.includes("conductor")) return fail(`${at}.roles`, "conductor requires explicit project role policy, not adapter defaults");
+    if (!roles.length || new Set(roles).size !== roles.length || roles.some(role => !ROLES.includes(role))) return fail(`${at}.roles`, "roles must be nonempty, known and unique");
+    let identity: ConfiguredAcpAdapterConfig["identity"];
+    if (input.identity) {
+      const value = fields(input.identity.value, `${at}.identity`);
+      if (Object.keys(value).some(key => !["name", "version"].includes(key))) return fail(`${at}.identity`, "unknown identity field");
+      identity = { name: text(value.name?.value, `${at}.identity.name`, 256), version: text(value.version?.value, `${at}.identity.version`, 256) };
+    }
+    const grokContract = kind === "grok" || /^grok(?:\.exe)?$/i.test(basename(command)) || identity?.name.toLowerCase() === "grok";
+    const noLeader = args.indexOf("--no-leader"), endOptions = args.indexOf("--");
+    if (grokContract && (noLeader < 0 || (endOptions >= 0 && noLeader > endOptions) || args.some(arg => arg.startsWith("--no-leader=")))) {
+      return fail(`${at}.args`, "Grok requires explicit --no-leader before argv termination; valued opt-outs are unsupported");
+    }
+    let modes: ConfiguredAcpAdapterConfig["permission"];
+    if (input.permission) {
+      const value = fields(input.permission.value, `${at}.permission`);
+      modes = {};
+      for (const [mode, d] of Object.entries(value)) {
+        if (!MODES.includes(mode)) return fail(`${at}.permission.${mode}`, "unknown hub mode");
+        modes[mode as PermissionMode] = text(d.value, `${at}.permission.${mode}`, 256);
+      }
+      if (!Object.keys(modes).length) modes = undefined; // `permission: {}` maps nothing: unmanaged, exactly like an omitted map
+    }
+    const readOnly = input.readOnly ? text(input.readOnly.value, `${at}.readOnly`, 256) : undefined;
+    const nativePolicy = freeze({ ...(modes ? { modes } : {}), ...(readOnly ? { readOnly } : {}) });
+    const argv = freeze([command, ...args]);
+    identity = identity && freeze(identity);
+    const definition: AdapterDefinition = {
+      api: 1, kind, family: kind, displayName, transport: "acp", roles, optional: true, defaultOnRoster: false,
+      trust: { onPrem: false, hubSandboxed: false }, identity: { mcp: "acp-session" }, instances: { mode: "headless" },
+      start: {
+        daemonPort: "acp", forms: ["headless"], defaultForm: "headless", conductorStartable: true, hubSwitches: [], ownedFlags: [],
+        exclusiveStartRefusal: "configured ACP start already in progress; retry after it settles",
+        preflight: request => request.form !== undefined && request.form !== "headless" ? `${kind}: configured ACP supports headless only`
+          : !identity ? `${kind}: native identity is unverified; configure the observed name/version pin before starting` : undefined,
+        launch: context => {
+          if (context.form !== "headless") throw new Error(`${kind}: configured ACP supports headless only`);
+          return { cmd: command, args: [...args], metadata: { packageEntrypoint: context.entrypoint, argv: [...argv], command: argv.map(shellQuote).join(" "), env: {} } };
+        },
+        create: context => {
+          if (!("acp" in context.daemon)) throw new Error(`${kind}: ACP transport options required`);
+          if (context.permission === "read-only" && !readOnly) throw new Error(`${kind}: read-only native mode is not configured`);
+          if (!identity) throw new Error(`${kind}: native identity is unverified; configure the observed name/version pin before starting`);
+          return new AcpPeer(context.instance, { ...context.daemon.acp, kind, cmd: [...argv], qwen025: false,
+            expectedAgent: identity, requireLoadSessionEcho: true, requireOwnedGroup: true,
+            permissionMode: context.permission === "read-only" ? "ask" : context.permission,
+            nativePolicy: { ...nativePolicy, lockedReadOnly: context.permission === "read-only" }, mcpServers: context.mcpServers });
+        },
+        conductorStartArgs: args => args.length ? new Error("configured ACP starts accept no launch overrides") : {},
+      },
+      permission: { genericAcp: nativePolicy, grants: Object.fromEntries(MODES.map(mode => [mode, modes?.[mode as PermissionMode] ? `${kind}: asks native ACP to select configured ${mode} mode; native tool policy applies; NO hub sandbox` : `${kind}: no configured native mapping for ${mode}; NO hub sandbox`])), ...(!modes || !Object.keys(modes).length ? { unmanaged: `${kind}: native policy unmanaged; no configured permission map; NO hub sandbox` } : {}) },
+      // ponytail: configured ACP has no verified controlled-recovery driver. Add catalog-bound restoration
+      // with native session/group receipts before enabling controlled recovery; explicit/crash load stays fenced.
+      session: { idField: "sessionId", currentId: peer => { const id = peer.recoveryMetadata?.().sessionId; return typeof id === "string" ? id : undefined; }, launchKind: "acp", resumeById: true, recoveryRefusal: () => "configured ACP has no verified controlled-recovery driver; stop it explicitly and restart with its recorded native session id" },
+      turnEnd: "adapter", cli: { command: kind, launchConfigKeys: [`adapters.${kind}.command`, `adapters.${kind}.args`], startWords: () => [kind] },
+      display: { palette: { fg: "white", bg: "black" } },
+    };
+    return freeze(definition);
+  }));
+}

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);
+}
+}

package/src/adapters/conformance/codex.ts

@@ -0,0 +1,191 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { CodexPeer } from "../codex-appserver.ts";
+import { newEnvelope } from "../../hub/envelope.ts";
+import type { DeliveryReceipt } from "../../hub/peers.ts";
+import { startFakeAppServer } from "./fakes/app-server.ts";
+import { processTable } from "../../hub/child-process.ts";
+import { until } from "./kit.ts";
+import { fakePaths } from "./fake-paths.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
+import { createFromDefinition, expire } from "./factories.ts";
+
+/** Register only when called; native protocol and processes stay inside the test bodies. */
+export function registerCodexConformance(definition: AdapterDefinition, { label = definition.displayName }: { label?: string } = {}): void {
+  if (definition.start.daemonPort !== "codex-appserver") throw new Error(definition.kind + ": conformance requires codex-appserver transport factory");
+  async function fixture(fake: Pick<ReturnType<typeof startFakeAppServer>, "url" | "requests" | "stop"> = startFakeAppServer()) {
+    const dir = mkdtempSync(join(tmpdir(), "conformance-codex-")), messages: string[] = [], receipts: DeliveryReceipt[] = [], usage: boolean[] = [];
+    const peer = createFromDefinition<CodexPeer>(definition, { codex: { cwd: dir, upstreamUrl: fake.url, appPort: 0, proxyPort: 0, onUsage: (_reading, hard) => { usage.push(hard); } } });
+    peer.onMessage = text => { messages.push(text); }; peer.onDelivery = receipt => { receipts.push(receipt); };
+    await peer.start();
+    const seen: any[] = [], tui = new WebSocket(peer.proxyUrl);
+    tui.onmessage = event => seen.push(JSON.parse(String(event.data)));
+    await new Promise<void>((resolve, reject) => { tui.onopen = () => resolve(); tui.onerror = () => reject(new Error("fake Codex TUI connection")); });
+    tui.send(JSON.stringify({ id: 1, method: "initialize", params: { clientInfo: { name: "conformance-tui" } } }));
+    await until(() => seen.some(row => row.id === 1), "Codex initialize consumed");
+    tui.send(JSON.stringify({ id: 2, method: "thread/start", params: { approvalPolicy: "untrusted" } }));
+    await until(() => peer.state === "idle", "Codex thread adopted");
+    return { peer, fake, messages, receipts, usage, tui, seen, async close() { try { tui.close(); await peer.stop(); } finally { fake.stop(); rmSync(dir, { recursive: true, force: true }); } } };
+}
+
+test(`P4 ${label}: permission overlays reach real turn RPC and ask restores the native baseline`, async () => {
+  const f = await fixture();
+  try {
+    for (const [mode, policy] of [["never-ask", "never"], ["ask", "untrusted"], ["ask-when-needed", "on-request"], ["ask", "untrusted"]] as const) {
+      await f.peer.setPermissionMode(mode);
+      const completed = f.messages.length;
+      await f.peer.deliver([newEnvelope("user", `mode ${mode}`)]);
+      await until(() => f.messages.length > completed && f.peer.state === "idle", "Codex policy turn settled");
+      expect(f.fake.requests.filter(row => row.method === "turn/start").at(-1).params.approvalPolicy).toBe(policy);
+    }
+  } finally { await f.close(); }
+});
+
+test(`P4 ${label}: rejected admission is failed_safe; accepted quota failure remains needs_review`, async () => {
+  const f = await fixture();
+  try {
+    const refusal = f.peer.deliver([newEnvelope("user", "REFUSE_TURN")], "refusal").catch(error => error);
+    await refusal;
+    await until(() => f.receipts.some(receipt => receipt.id === "refusal"), "definitive rejection receipt");
+    expect(f.receipts.find(receipt => receipt.id === "refusal")?.state).toBe("failed_safe");
+    await until(() => f.peer.state === "idle", "Codex refusal releases occupancy");
+    await f.peer.deliver([newEnvelope("user", "QUOTA")], "quota");
+    await until(() => f.receipts.some(receipt => receipt.id === "quota" && receipt.state === "needs_review"), "accepted quota failure");
+    expect(f.usage).toContain(true);
+    expect(f.receipts.filter(receipt => receipt.id === "quota").map(receipt => receipt.state)).toEqual(["accepted", "needs_review"]);
+    expect(f.messages).toEqual([]);
+  } finally { await f.close(); }
+});
+
+test(`P4 ${label}: watchdog fences a late result after observed native acceptance`, async () => {
+  const f = await fixture();
+  try {
+    await f.peer.deliver([newEnvelope("user", "SLOW:100")], "old");
+    await until(() => f.receipts.some(receipt => receipt.state === "accepted"), "Codex native acceptance");
+    expire(f.peer);
+    // Forwarded turn/completed is a transport consumption barrier, not a guessed grace delay.
+    await until(() => f.seen.some(row => row.method === "turn/completed"), "late result consumed");
+    expect(f.messages).toEqual([]);
+    expect(f.receipts.map(receipt => receipt.state)).toEqual(["accepted", "needs_review"]);
+    expect(f.peer.state).toBe("idle");
+  } finally { await f.close(); }
+});
+
+test(`P4 ${label}: stopping owns the launcher's group and its native app-server child`, async () => {
+  const dir = mkdtempSync(join(tmpdir(), "conformance-codex-group-")), bin = join(dir, "codex"), launcher = join(dir, "launcher.pid"), native = join(dir, "native.pid");
+  const quote = (value: string) => "'" + value.replaceAll("'", "'\\''") + "'";
+  writeFileSync(bin, `#!/bin/sh\necho $$ > ${quote(launcher)}\ntrap '' TERM\n${quote(process.execPath)} ${quote(fakePaths.codexBin)} "$@" &\necho $! > ${quote(native)}\nwhile :; do sleep 1; done\n`, { mode: 0o755 });
+  const reservation = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: () => new Response() });
+  const appPort = reservation.port!; reservation.stop(true);
+  const peer = createFromDefinition<CodexPeer>(definition, { codex: { cwd: dir, bin, appPort, proxyPort: 0 } });
+  try {
+    await peer.start();
+    const leader = Number(readFileSync(launcher, "utf8")), child = Number(readFileSync(native, "utf8"));
+    const before = processTable(); expect(before).toBeDefined();
+    expect(before!.some(row => row.pid === child && row.pgid === leader)).toBe(true);
+    await peer.stop();
+    const after = processTable(); expect(after).toBeDefined();
+    expect(after!.some(row => row.pid === child || row.pid === leader || row.pgid === leader)).toBe(false);
+  } finally { await peer.stop(); rmSync(dir, { recursive: true, force: true }); }
+}, 20_000);
+
+/** Every release and the consuming-proxy barrier are controlled by the test, never by wall-clock sleeps. */
+function controlledAppServer() {
+  const requests: any[] = [];
+  let socket: { send(data: string): unknown } | undefined;
+  const send = (message: unknown) => { if (!socket) throw new Error("controlled app-server not attached"); socket.send(JSON.stringify(message)); };
+  const server = Bun.serve({ hostname: "127.0.0.1", port: 0,
+    fetch(request, server) { return server.upgrade(request) ? undefined : new Response("not a websocket", { status: 400 }); },
+    websocket: { message(ws, raw) {
+      socket = ws;
+      const request = JSON.parse(String(raw)); requests.push(request);
+      if (request.method === "initialize") send({ id: request.id, result: { userAgent: "fake-codex/0.154.0" } });
+      else if (request.method === "thread/start" || request.method === "thread/resume") send({ id: request.id, result: { thread: { id: request.params.threadId ?? "th1" }, approvalPolicy: "untrusted" } });
+      else if (request.method === "account/rateLimits/read") send({ id: request.id, result: { rateLimits: {} } });
+      else if (request.method === "conformance/barrier") send({ id: request.id, result: {} });
+    } },
+  });
+  return { url: `ws://127.0.0.1:${server.port}`, requests, stop: () => server.stop(true), send,
+    note(method: string, params: Record<string, unknown>) { send({ method, params: { threadId: "th1", ...params } }); },
+  };
+}
+async function barrier(f: Awaited<ReturnType<typeof fixture>>, id: number): Promise<void> {
+  f.tui.send(JSON.stringify({ id, method: "conformance/barrier", params: {} }));
+  await until(() => f.seen.some(row => row.id === id), "ordered controlled-app-server barrier consumed");
+}
+
+test(`P4 ${label}: accepted-before-start watchdog tombstone survives delayed native start until exact completion`, async () => {
+  const native = controlledAppServer(), f = await fixture(native);
+  try {
+    const delivery = f.peer.deliver([newEnvelope("user", "old accepted prompt")], "old-accepted");
+    await until(() => native.requests.some(row => row.method === "turn/start"), "native turn request observed");
+    const request = native.requests.find(row => row.method === "turn/start");
+    native.send({ id: request.id, result: { turn: { id: "retired" } } });
+    await delivery; // The fake has deliberately emitted no turn/started.
+    expire(f.peer);
+    native.note("turn/started", { turn: { id: "retired" } });
+    native.note("item/completed", { turnId: "retired", item: { id: "old-answer", type: "agentMessage", text: "must not publish" } });
+    await barrier(f, 50);
+    expect(f.peer.state).toBe("idle"); expect(f.messages).toEqual([]);
+    expect(f.receipts.map(receipt => receipt.state)).toEqual(["accepted", "needs_review"]);
+    native.note("turn/completed", { turn: { id: "retired", status: "completed" } });
+    await barrier(f, 51);
+    expect(f.messages).toEqual([]); expect(f.receipts).toHaveLength(2);
+  } finally { await f.close(); }
+});
+
+for (const acceptance of [true, false]) test(`P4 ${label}: invalidated pending ${acceptance ? "acceptance" : "refusal"} never contaminates a newer personal turn or duplicates uncertainty`, async () => {
+  const native = controlledAppServer(), f = await fixture(native);
+  try {
+    const delivery = f.peer.deliver([newEnvelope("user", "cancelled audience")], "pending").catch(error => error as Error);
+    await until(() => native.requests.some(row => row.method === "turn/start"), "pending start observed");
+    const request = native.requests.find(row => row.method === "turn/start");
+    native.note("turn/started", { turn: { id: "old-pending" } });
+    await barrier(f, 60);
+    expire(f.peer);
+    expect((await delivery as Error).message).toContain("watchdog");
+    expect(f.receipts.map(receipt => receipt.state)).toEqual(["needs_review"]);
+    native.note("turn/started", { turn: { id: "personal-current" } });
+    await barrier(f, 61);
+    expect(f.peer.state).toBe("busy");
+    native.send(acceptance ? { id: request.id, result: { turn: { id: "old-pending" } } } : { id: request.id, error: { message: "turn rejected" } });
+    native.note("item/completed", { turnId: "old-pending", item: { id: "old-answer", type: "agentMessage", text: "stale answer" } });
+    native.note("turn/completed", { turn: { id: "old-pending", status: "completed" } });
+    await barrier(f, 62);
+    expect(f.peer.state).toBe("busy"); expect(f.messages).toEqual([]);
+    expect(f.receipts.map(receipt => receipt.state)).toEqual(["needs_review"]);
+    const replies: unknown[] = [];
+    f.peer.onMessage = (text, options) => { f.messages.push(text); replies.push(options?.inReplyTo); };
+    native.note("item/completed", { turnId: "personal-current", item: { id: "current-answer", type: "agentMessage", text: "current personal answer" } });
+    native.note("turn/completed", { turn: { id: "personal-current", status: "completed" } });
+    await barrier(f, 63);
+    expect(f.messages).toEqual(["current personal answer"]); expect(replies).toEqual([undefined]);
+    expect(f.peer.state).toBe("idle"); expect(f.receipts).toHaveLength(1);
+  } finally { await f.close(); }
+});
+
+test(`P4 ${label}: legacy unnamed turn works until cancellation makes its identity ambiguous`, async () => {
+  const native = controlledAppServer(), f = await fixture(native);
+  try {
+    native.note("turn/started", { turn: {} });
+    native.note("item/completed", { turnId: "legacy", item: { id: "legacy-answer", type: "agentMessage", text: "legacy answer" } });
+    native.note("turn/completed", { turn: { id: "legacy", status: "completed" } });
+    await barrier(f, 70);
+    expect(f.messages).toEqual(["legacy answer"]); expect(f.peer.state).toBe("idle");
+    native.note("turn/started", { turn: {} }); await barrier(f, 71);
+    expire(f.peer); expect(f.peer.state).toBe("offline");
+    native.note("turn/started", { turn: { id: "unattributable-late" } });
+    native.note("item/completed", { item: { id: "late", type: "agentMessage", text: "unattributable answer" } });
+    native.note("turn/completed", { turn: { id: "unattributable-late", status: "completed" } });
+    await barrier(f, 72);
+    expect(f.messages).toEqual(["legacy answer"]); expect(f.peer.state).toBe("offline");
+    // Adopting a verified session again is the explicit boundary that clears the attribution ceiling.
+    f.tui.send(JSON.stringify({ id: 73, method: "thread/resume", params: { threadId: "th1" } }));
+    await until(() => f.seen.some(row => row.id === 73), "session reattachment consumed");
+    expect(f.peer.state).toBe("idle");
+  } finally { await f.close(); }
+});
+
+}