@staix/agent-hub 0.12.44 → 0.12.45

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/claude-channel.ts

@@ -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)`);
     }
   }
@@ -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 };

package/src/adapters/codex-appserver.ts

@@ -488,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 {

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

package/src/adapters/conformance/enrollment.ts

@@ -0,0 +1,43 @@
+import type { AdapterDefinition } from "../registry-types.ts";
+
+/** Stable generic ACP legs; both actual test registration and enrollment validation consume this catalog. */
+export const ACP_LEGS = Object.freeze(["native-approval-rpc", "native-mode-ack", "native-quota", "watchdog-generation"] as const);
+export type AcpLeg = typeof ACP_LEGS[number];
+/** No unsupported key or non-generic ACP engine can silently escape an executable catalog leg. */
+export function assertAcpLegEnrollment(definitions: readonly AdapterDefinition[], unsupportedLegs: Readonly<Record<string, string>> = {}): void {
+  const acp = new Map(definitions.filter(definition => definition.transport === "acp").map(definition => [definition.kind, definition]));
+  for (const [key, reason] of Object.entries(unsupportedLegs)) {
+    const separator = key.lastIndexOf(":"), kind = key.slice(0, separator), leg = key.slice(separator + 1);
+    if (separator < 1 || !acp.has(kind) || !(ACP_LEGS as readonly string[]).includes(leg)) throw new Error(`${key}: stale or unknown unsupported ACP leg`);
+    if (typeof reason !== "string" || !reason.trim()) throw new Error(`${key}: unsupported ACP leg requires a concrete reason`);
+  }
+  for (const definition of acp.values()) if (definition.start.daemonPort !== "acp") {
+    for (const leg of ACP_LEGS) {
+      const key = `${definition.kind}:${leg}`;
+      if (!Object.hasOwn(unsupportedLegs, key)) throw new Error(`${key}: non-generic ACP engine requires an explicit skipped-leg reason`);
+    }
+  }
+}
+export function definitionIdentities(definitions: readonly AdapterDefinition[]): { id: string; definition: AdapterDefinition }[] {
+  return definitions.flatMap(definition => [{ id: definition.kind, definition },
+    ...(definition.reviewerVariant ? [{ id: `${definition.kind}:reviewer`, definition: definition.reviewerVariant }] : [])]);
+}
+export function assertEnrollment(definitions: readonly AdapterDefinition[], enrolled: readonly string[], unsupported: Readonly<Record<string, string>>, unsupportedLegs: Readonly<Record<string, string>> = {}, coherence?: (definition: AdapterDefinition) => void): void {
+  assertAcpLegEnrollment(definitions, unsupportedLegs);
+  const rows = definitionIdentities(definitions), identities = new Set(rows.map(row => row.id));
+  if (identities.size !== rows.length) throw new Error("duplicate conformance definition identity");
+  if (new Set(enrolled).size !== enrolled.length) throw new Error("duplicate conformance enrollment");
+  for (const id of enrolled) if (!identities.has(id)) throw new Error(`${id}: enrolled fixture has no registry definition`);
+  for (const [id, reason] of Object.entries(unsupported)) {
+    if (!identities.has(id)) throw new Error(`${id}: unsupported reason has no registry definition`);
+    if (!reason.trim()) throw new Error(`${id}: unsupported needs a concrete reason`);
+    if (enrolled.includes(id)) throw new Error(`${id}: cannot be both enrolled and unsupported`);
+  }
+  for (const { id, definition } of rows) {
+    try { coherence?.(definition); }
+    catch (error) { throw new Error(`${id}: ${(error as Error).message}`); }
+    if (!enrolled.includes(id) && !Object.hasOwn(unsupported, id)) throw new Error(`${id}: no conformance fixture or unsupported reason`);
+    if (definition.transport === "acp" && !enrolled.includes(id)) throw new Error(`${id}: every ACP definition must run the ACP legs`);
+    if (id.endsWith(":reviewer") && !definition.reviewer) throw new Error(`${id}: reviewer variant lacks reviewer policy`);
+  }
+}

package/src/adapters/conformance/factories.ts

@@ -0,0 +1,17 @@
+import type { AdapterDefinition, CreateContext, DaemonPorts } from "../registry-types.ts";
+import type { PeerAdapter } from "../../hub/peers.ts";
+import { join } from "node:path";
+
+/** The supplied definition creates its actual adapter, with only this fixture's transport options. */
+export function createFromDefinition<T extends PeerAdapter>(definition: AdapterDefinition, daemon: DaemonPorts): T {
+  if (!definition.start.create) throw new Error(`${definition.kind}: no driven native factory; use its external-hello fixture`);
+  const options = Object.values(daemon)[0] as { cwd: string; stateDir?: string; mcpServers?: CreateContext["mcpServers"] };
+  return definition.start.create({ instance: definition.kind, projectRoot: options.cwd, stateDir: options.stateDir ?? join(options.cwd, "state"),
+    kindConfig: {}, permission: "ask", mcpServers: options.mcpServers ?? [], daemon }) as T;
+}
+/** Explicit watchdog seam on the factory-created implementation, replacing direct test subclasses. */
+export function expire(peer: PeerAdapter): void {
+  const watched = peer as PeerAdapter & { onWatchdog(): void };
+  if (typeof watched.onWatchdog !== "function") throw new Error(`${peer.id}: no watchdog seam`);
+  watched.onWatchdog();
+}

package/src/adapters/conformance/fake-paths.ts

@@ -0,0 +1,12 @@
+import { fileURLToPath } from "node:url";
+
+/** Shipped assets are resolved without importing or executing their native protocol loops. */
+export const fakePaths = Object.freeze({
+  acpServer: fileURLToPath(new URL("./fakes/acp-server.ts", import.meta.url)),
+  appServer: fileURLToPath(new URL("./fakes/app-server.ts", import.meta.url)),
+  modelServer: fileURLToPath(new URL("./fakes/model-server.ts", import.meta.url)),
+  piRpc: fileURLToPath(new URL("./fakes/pi-rpc.ts", import.meta.url)),
+  jcodeAgent: fileURLToPath(new URL("./fakes/jcode-agent.ts", import.meta.url)),
+  codexBin: fileURLToPath(new URL("./fakes/codex-bin.ts", import.meta.url)),
+  acpWatchdog: fileURLToPath(new URL("./fakes/acp-watchdog-agent.ts", import.meta.url)),
+});