@kodelyth/acpx 2026.5.39 → 2026.5.42

package/src/service.test.ts

@@ -0,0 +1,802 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { runtimeRegistry } = vi.hoisted(() => ({
+  runtimeRegistry: new Map<string, { runtime: unknown; healthy?: () => boolean }>(),
+}));
+const { prepareAcpxCodexAuthConfigMock } = vi.hoisted(() => ({
+  prepareAcpxCodexAuthConfigMock: vi.fn(
+    async ({ pluginConfig }: { pluginConfig: unknown }) => pluginConfig,
+  ),
+}));
+const { cleanupKlawOwnedAcpxProcessTreeMock } = vi.hoisted(() => ({
+  cleanupKlawOwnedAcpxProcessTreeMock: vi.fn(
+    async (): Promise<{
+      inspectedPids: number[];
+      terminatedPids: number[];
+      skippedReason?: string;
+    }> => ({
+      inspectedPids: [],
+      terminatedPids: [],
+    }),
+  ),
+}));
+const { reapStaleKlawOwnedAcpxOrphansMock } = vi.hoisted(() => ({
+  reapStaleKlawOwnedAcpxOrphansMock: vi.fn(
+    async (): Promise<{
+      inspectedPids: number[];
+      terminatedPids: number[];
+      skippedReason?: string;
+    }> => ({
+      inspectedPids: [],
+      terminatedPids: [],
+    }),
+  ),
+}));
+const { acpxRuntimeConstructorMock, createAgentRegistryMock, createFileSessionStoreMock } =
+  vi.hoisted(() => ({
+    acpxRuntimeConstructorMock: vi.fn(function AcpxRuntime(options: unknown) {
+      return {
+        cancel: vi.fn(async () => {}),
+        close: vi.fn(async () => {}),
+        doctor: vi.fn(async () => ({ ok: true, message: "ok" })),
+        ensureSession: vi.fn(async () => ({
+          backend: "acpx",
+          runtimeSessionName: "agent:codex:acp:test",
+          sessionKey: "agent:codex:acp:test",
+        })),
+        getCapabilities: vi.fn(async () => ({ controls: [] })),
+        getStatus: vi.fn(async () => ({ summary: "ready" })),
+        isHealthy: vi.fn(() => true),
+        prepareFreshSession: vi.fn(async () => {}),
+        probeAvailability: vi.fn(async () => {}),
+        runTurn: vi.fn(async function* () {}),
+        setConfigOption: vi.fn(async () => {}),
+        setMode: vi.fn(async () => {}),
+        __options: options,
+      };
+    }),
+    createAgentRegistryMock: vi.fn(() => ({})),
+    createFileSessionStoreMock: vi.fn(() => ({})),
+  }));
+
+vi.mock("../runtime-api.js", () => ({
+  getAcpRuntimeBackend: (id: string) => runtimeRegistry.get(id),
+  registerAcpRuntimeBackend: (entry: { id: string; runtime: unknown; healthy?: () => boolean }) => {
+    runtimeRegistry.set(entry.id, entry);
+  },
+  unregisterAcpRuntimeBackend: (id: string) => {
+    runtimeRegistry.delete(id);
+  },
+}));
+
+vi.mock("./runtime.js", () => ({
+  ACPX_BACKEND_ID: "acpx",
+  AcpxRuntime: acpxRuntimeConstructorMock,
+  createAgentRegistry: createAgentRegistryMock,
+  createFileSessionStore: createFileSessionStoreMock,
+}));
+
+vi.mock("./codex-auth-bridge.js", () => ({
+  prepareAcpxCodexAuthConfig: prepareAcpxCodexAuthConfigMock,
+}));
+
+vi.mock("./process-reaper.js", () => ({
+  cleanupKlawOwnedAcpxProcessTree: cleanupKlawOwnedAcpxProcessTreeMock,
+  reapStaleKlawOwnedAcpxOrphans: reapStaleKlawOwnedAcpxOrphansMock,
+}));
+
+import { getAcpRuntimeBackend } from "../runtime-api.js";
+import type { KlawPluginServiceContext } from "../runtime-api.js";
+import { createAcpxRuntimeService } from "./service.js";
+
+const tempDirs: string[] = [];
+const previousEnv = {
+  KLAW_ACPX_RUNTIME_STARTUP_PROBE: process.env.KLAW_ACPX_RUNTIME_STARTUP_PROBE,
+  KLAW_SKIP_ACPX_RUNTIME: process.env.KLAW_SKIP_ACPX_RUNTIME,
+  KLAW_SKIP_ACPX_RUNTIME_PROBE: process.env.KLAW_SKIP_ACPX_RUNTIME_PROBE,
+};
+
+function restoreEnv(name: keyof typeof previousEnv): void {
+  const value = previousEnv[name];
+  if (value === undefined) {
+    delete process.env[name];
+  } else {
+    process.env[name] = value;
+  }
+}
+
+async function makeTempDir(): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "klaw-acpx-service-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(async () => {
+  runtimeRegistry.clear();
+  prepareAcpxCodexAuthConfigMock.mockClear();
+  cleanupKlawOwnedAcpxProcessTreeMock.mockClear();
+  reapStaleKlawOwnedAcpxOrphansMock.mockClear();
+  acpxRuntimeConstructorMock.mockClear();
+  createAgentRegistryMock.mockClear();
+  createFileSessionStoreMock.mockClear();
+  restoreEnv("KLAW_ACPX_RUNTIME_STARTUP_PROBE");
+  restoreEnv("KLAW_SKIP_ACPX_RUNTIME");
+  restoreEnv("KLAW_SKIP_ACPX_RUNTIME_PROBE");
+  for (const dir of tempDirs.splice(0)) {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+function createServiceContext(workspaceDir: string): KlawPluginServiceContext {
+  return {
+    workspaceDir,
+    stateDir: path.join(workspaceDir, ".klaw-plugin-state"),
+    config: {},
+    logger: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    },
+  };
+}
+
+function createMockRuntime(overrides: Record<string, unknown> = {}) {
+  return {
+    ensureSession: vi.fn(),
+    runTurn: vi.fn(),
+    cancel: vi.fn(),
+    close: vi.fn(),
+    probeAvailability: vi.fn(async () => {}),
+    isHealthy: vi.fn(() => true),
+    doctor: vi.fn(async () => ({ ok: true, message: "ok" })),
+    ...overrides,
+  };
+}
+
+function createStartupTraceRecorder() {
+  const measured: string[] = [];
+  const details: Array<{
+    name: string;
+    metrics: ReadonlyArray<readonly [string, number | string]>;
+  }> = [];
+  return {
+    measured,
+    details,
+    startupTrace: {
+      measure: async <T>(name: string, run: () => T | Promise<T>): Promise<T> => {
+        measured.push(name);
+        return await run();
+      },
+      detail: (name: string, metrics: ReadonlyArray<readonly [string, number | string]>) => {
+        details.push({ name, metrics });
+      },
+    },
+  };
+}
+
+function readFirstRuntimeFactoryInput(runtimeFactory: { mock: { calls: Array<Array<unknown>> } }) {
+  const [call] = runtimeFactory.mock.calls;
+  if (!call) {
+    throw new Error("Expected runtimeFactory to be called");
+  }
+  const [input] = call;
+  if (typeof input !== "object" || input === null) {
+    throw new Error("Expected runtimeFactory to be called with an options object");
+  }
+  return input as {
+    pluginConfig: {
+      timeoutSeconds?: number;
+      probeAgent?: string;
+    };
+  };
+}
+
+describe("createAcpxRuntimeService", () => {
+  it("registers and unregisters the embedded backend", async () => {
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const runtime = createMockRuntime();
+    const service = createAcpxRuntimeService({
+      runtimeFactory: () => runtime as never,
+    });
+
+    await service.start(ctx);
+
+    expect(getAcpRuntimeBackend("acpx")?.runtime).toBe(runtime);
+
+    await service.stop?.(ctx);
+
+    expect(getAcpRuntimeBackend("acpx")).toBeUndefined();
+  });
+
+  it("skips the startup probe and does not advertise backend health when explicitly disabled", async () => {
+    process.env.KLAW_ACPX_RUNTIME_STARTUP_PROBE = "0";
+    delete process.env.KLAW_SKIP_ACPX_RUNTIME_PROBE;
+    const workspaceDir = await makeTempDir();
+    const stateDir = path.join(workspaceDir, "custom-state");
+    const ctx = createServiceContext(workspaceDir);
+    const probeAvailability = vi.fn(async () => {
+      await fs.access(stateDir);
+    });
+    const runtime = createMockRuntime({
+      doctor: async () => ({ ok: true, message: "ok" }),
+      isHealthy: () => false,
+      probeAvailability,
+    });
+    const service = createAcpxRuntimeService({
+      pluginConfig: { stateDir },
+      runtimeFactory: () => runtime as never,
+    });
+
+    await service.start(ctx);
+
+    await fs.access(stateDir);
+    expect(probeAvailability).not.toHaveBeenCalled();
+    expect(getAcpRuntimeBackend("acpx")?.healthy).toBeUndefined();
+
+    await service.stop?.(ctx);
+  });
+
+  it("waits for the embedded runtime startup probe before resolving by default", async () => {
+    delete process.env.KLAW_ACPX_RUNTIME_STARTUP_PROBE;
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    let releaseProbe!: () => void;
+    const probeStarted = vi.fn();
+    const probeAvailability = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          probeStarted();
+          releaseProbe = resolve;
+        }),
+    );
+    const runtime = createMockRuntime({
+      probeAvailability,
+      isHealthy: () => true,
+    });
+    const service = createAcpxRuntimeService({
+      runtimeFactory: () => runtime as never,
+    });
+
+    const startPromise = service.start(ctx) as Promise<void>;
+    await vi.waitFor(() => {
+      expect(probeStarted).toHaveBeenCalledOnce();
+    });
+
+    let resolved = false;
+    void startPromise.then(() => {
+      resolved = true;
+    });
+    await Promise.resolve();
+
+    expect(resolved).toBe(false);
+    releaseProbe();
+    await startPromise;
+
+    expect(resolved).toBe(true);
+    expect(ctx.logger.info).toHaveBeenCalledWith("embedded acpx runtime backend ready");
+
+    await service.stop?.(ctx);
+  });
+
+  it("emits ACPX-owned startup trace subspans", async () => {
+    delete process.env.KLAW_ACPX_RUNTIME_STARTUP_PROBE;
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const trace = createStartupTraceRecorder();
+    ctx.startupTrace = trace.startupTrace;
+    const runtime = createMockRuntime();
+    const service = createAcpxRuntimeService({
+      runtimeFactory: () => runtime as never,
+    });
+
+    await service.start(ctx);
+
+    expect(trace.measured).toEqual([
+      "config.resolve",
+      "config.prepare-codex-auth",
+      "filesystem.prepare",
+      "gateway-instance-id",
+      "process-leases.reap",
+      "runtime.create",
+      "backend.register",
+      "probe.availability",
+    ]);
+    expect(trace.details).toEqual([
+      {
+        name: "probe-policy",
+        metrics: [
+          ["startupProbeEnabledCount", 1],
+          ["probeAgent", "default"],
+        ],
+      },
+      {
+        name: "probe.result",
+        metrics: [["healthyCount", 1]],
+      },
+    ]);
+
+    await service.stop?.(ctx);
+  });
+
+  it("reaps stale ACPX process leases from the generated wrapper root at startup", async () => {
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const runtime = createMockRuntime();
+    const processCleanupDeps = { sleep: vi.fn(async () => {}) };
+    await fs.mkdir(path.join(ctx.stateDir, "acpx"), { recursive: true });
+    await fs.writeFile(path.join(ctx.stateDir, "gateway-instance-id"), "gw-test\n");
+    await fs.writeFile(
+      path.join(ctx.stateDir, "acpx", "process-leases.json"),
+      JSON.stringify({
+        version: 1,
+        leases: [
+          {
+            leaseId: "lease-1",
+            gatewayInstanceId: "gw-test",
+            sessionKey: "agent:codex:acp:test",
+            wrapperRoot: path.join(ctx.stateDir, "acpx"),
+            wrapperPath: path.join(ctx.stateDir, "acpx", "codex-acp-wrapper.mjs"),
+            rootPid: 101,
+            commandHash: "hash",
+            startedAt: 1,
+            state: "open",
+          },
+        ],
+      }),
+    );
+    cleanupKlawOwnedAcpxProcessTreeMock.mockResolvedValueOnce({
+      inspectedPids: [101, 102],
+      terminatedPids: [101, 102],
+    });
+    const service = createAcpxRuntimeService({
+      runtimeFactory: () => runtime as never,
+      processCleanupDeps,
+    });
+
+    await service.start(ctx);
+
+    expect(cleanupKlawOwnedAcpxProcessTreeMock).toHaveBeenCalledWith({
+      rootPid: 101,
+      expectedLeaseId: "lease-1",
+      expectedGatewayInstanceId: "gw-test",
+      wrapperRoot: path.join(ctx.stateDir, "acpx"),
+      deps: processCleanupDeps,
+    });
+    expect(ctx.logger.info).toHaveBeenCalledWith("reaped 2 stale Klaw-owned ACPX processes");
+
+    await service.stop?.(ctx);
+  });
+
+  it("runs wrapper-root orphan cleanup before dropping pending ACPX leases", async () => {
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const runtime = createMockRuntime();
+    const processCleanupDeps = { sleep: vi.fn(async () => {}) };
+    const wrapperRoot = path.join(ctx.stateDir, "acpx");
+    await fs.mkdir(wrapperRoot, { recursive: true });
+    await fs.writeFile(path.join(ctx.stateDir, "gateway-instance-id"), "gw-test\n");
+    await fs.writeFile(
+      path.join(wrapperRoot, "process-leases.json"),
+      JSON.stringify({
+        version: 1,
+        leases: [
+          {
+            leaseId: "lease-pending",
+            gatewayInstanceId: "gw-test",
+            sessionKey: "agent:codex:acp:test",
+            wrapperRoot,
+            wrapperPath: path.join(wrapperRoot, "codex-acp-wrapper.mjs"),
+            rootPid: 0,
+            commandHash: "hash",
+            startedAt: 1,
+            state: "open",
+          },
+        ],
+      }),
+    );
+    reapStaleKlawOwnedAcpxOrphansMock.mockResolvedValueOnce({
+      inspectedPids: [201, 202],
+      terminatedPids: [201, 202],
+    });
+    const service = createAcpxRuntimeService({
+      runtimeFactory: () => runtime as never,
+      processCleanupDeps,
+    });
+
+    await service.start(ctx);
+
+    expect(cleanupKlawOwnedAcpxProcessTreeMock).not.toHaveBeenCalled();
+    expect(reapStaleKlawOwnedAcpxOrphansMock).toHaveBeenCalledWith({
+      wrapperRoot,
+      deps: processCleanupDeps,
+    });
+    expect(ctx.logger.info).toHaveBeenCalledWith("reaped 2 stale Klaw-owned ACPX processes");
+    const leaseFile = JSON.parse(
+      await fs.readFile(path.join(wrapperRoot, "process-leases.json"), "utf8"),
+    );
+    expect(leaseFile.leases[0].state).toBe("closed");
+
+    await service.stop?.(ctx);
+  });
+
+  it("keeps startup quiet when no process leases are open", async () => {
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const runtime = createMockRuntime();
+    const service = createAcpxRuntimeService({
+      runtimeFactory: () => runtime as never,
+    });
+
+    await service.start(ctx);
+
+    expect(cleanupKlawOwnedAcpxProcessTreeMock).not.toHaveBeenCalled();
+    expect(ctx.logger.warn).not.toHaveBeenCalled();
+
+    await service.stop?.(ctx);
+  });
+
+  it("registers the backend lazily without importing ACPX runtime when startup probe is disabled", async () => {
+    process.env.KLAW_ACPX_RUNTIME_STARTUP_PROBE = "0";
+    delete process.env.KLAW_SKIP_ACPX_RUNTIME_PROBE;
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const service = createAcpxRuntimeService();
+
+    await service.start(ctx);
+
+    const backend = getAcpRuntimeBackend("acpx");
+    if (!backend) {
+      throw new Error("expected ACPX runtime backend");
+    }
+    const backendRuntime = backend.runtime as {
+      ensureSession(input: { agent: string; mode: string; sessionKey: string }): Promise<unknown>;
+    };
+    expect(typeof backendRuntime.ensureSession).toBe("function");
+    expect(backend.healthy).toBeUndefined();
+    expect(acpxRuntimeConstructorMock).not.toHaveBeenCalled();
+
+    await backendRuntime.ensureSession({
+      agent: "codex",
+      mode: "oneshot",
+      sessionKey: "agent:codex:acp:test",
+    });
+
+    expect(acpxRuntimeConstructorMock).toHaveBeenCalledOnce();
+    expect(backend.healthy).toBeUndefined();
+
+    await service.stop?.(ctx);
+  });
+
+  it("adapts lazy runTurn-only default runtimes for startTurn callers", async () => {
+    process.env.KLAW_ACPX_RUNTIME_STARTUP_PROBE = "0";
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const runTurn = vi.fn(async function* () {
+      yield {
+        type: "text_delta" as const,
+        stream: "output" as const,
+        text: "legacy progress",
+      };
+      yield {
+        type: "done" as const,
+        stopReason: "end_turn",
+      };
+    });
+    acpxRuntimeConstructorMock.mockImplementationOnce(function AcpxRuntime(options: unknown) {
+      return {
+        ...createMockRuntime({
+          runTurn,
+        }),
+        getCapabilities: vi.fn(async () => ({ controls: [] })),
+        getStatus: vi.fn(async () => ({ summary: "ready" })),
+        prepareFreshSession: vi.fn(async () => {}),
+        setConfigOption: vi.fn(async () => {}),
+        setMode: vi.fn(async () => {}),
+        __options: options,
+      };
+    });
+    const service = createAcpxRuntimeService();
+
+    await service.start(ctx);
+
+    const backend = getAcpRuntimeBackend("acpx");
+    if (!backend) {
+      throw new Error("expected ACPX runtime backend");
+    }
+    const backendRuntime = backend.runtime as {
+      startTurn(input: {
+        handle: { sessionKey: string; backend: string; runtimeSessionName: string };
+        text: string;
+        mode: string;
+        requestId: string;
+      }): {
+        events: AsyncIterable<unknown>;
+        result: Promise<unknown>;
+      };
+    };
+    const turn = backendRuntime.startTurn({
+      handle: {
+        sessionKey: "agent:codex:acp:test",
+        backend: "acpx",
+        runtimeSessionName: "agent:codex:acp:test",
+      },
+      text: "hello",
+      mode: "prompt",
+      requestId: "turn-1",
+    });
+    await expect(turn.result).resolves.toEqual({
+      status: "completed",
+      stopReason: "end_turn",
+    });
+    const events = [];
+    for await (const event of turn.events) {
+      events.push(event);
+    }
+
+    expect(events).toEqual([
+      {
+        type: "text_delta",
+        stream: "output",
+        text: "legacy progress",
+      },
+    ]);
+    expect(runTurn).toHaveBeenCalledOnce();
+
+    await service.stop?.(ctx);
+  });
+
+  it("passes the plugin timeout to the default acpx runtime constructor", async () => {
+    process.env.KLAW_ACPX_RUNTIME_STARTUP_PROBE = "0";
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const service = createAcpxRuntimeService({
+      pluginConfig: { timeoutSeconds: 0.001 },
+    });
+
+    await service.start(ctx);
+
+    const backend = getAcpRuntimeBackend("acpx");
+    if (!backend) {
+      throw new Error("expected ACPX runtime backend");
+    }
+    const backendRuntime = backend.runtime as {
+      ensureSession(input: { agent: string; mode: string; sessionKey: string }): Promise<unknown>;
+    };
+
+    await backendRuntime.ensureSession({
+      agent: "codex",
+      mode: "oneshot",
+      sessionKey: "agent:codex:acp:test",
+    });
+
+    const [options] = acpxRuntimeConstructorMock.mock.calls[0] ?? [];
+    expect(options).toHaveProperty("timeoutMs", 1);
+
+    await service.stop?.(ctx);
+  });
+
+  it("runs the embedded runtime probe at startup when explicitly enabled and reports health", async () => {
+    process.env.KLAW_ACPX_RUNTIME_STARTUP_PROBE = "1";
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const probeAvailability = vi.fn(async () => {});
+    const runtime = createMockRuntime({
+      probeAvailability,
+      isHealthy: () => true,
+    });
+    const service = createAcpxRuntimeService({
+      runtimeFactory: () => runtime as never,
+    });
+
+    await service.start(ctx);
+
+    expect(probeAvailability).toHaveBeenCalledOnce();
+    expect(getAcpRuntimeBackend("acpx")?.healthy?.()).toBe(true);
+
+    await service.stop?.(ctx);
+  });
+
+  it("bounds the opt-in embedded runtime startup probe wait with the configured timeout", async () => {
+    process.env.KLAW_ACPX_RUNTIME_STARTUP_PROBE = "1";
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const probeAvailability = vi.fn(() => new Promise<void>(() => {}));
+    const runtime = createMockRuntime({
+      probeAvailability,
+      isHealthy: () => false,
+    });
+    const service = createAcpxRuntimeService({
+      pluginConfig: { timeoutSeconds: 0.001 },
+      runtimeFactory: () => runtime as never,
+    });
+
+    await service.start(ctx);
+
+    expect(probeAvailability).toHaveBeenCalledOnce();
+    expect(getAcpRuntimeBackend("acpx")?.healthy?.()).toBe(false);
+    expect(ctx.logger.warn).toHaveBeenCalledWith(
+      "embedded acpx runtime setup failed: embedded acpx runtime backend startup probe timed out after 0.001s",
+    );
+
+    await service.stop?.(ctx);
+  });
+
+  it("passes the default runtime timeout to the embedded runtime factory", async () => {
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const runtime = createMockRuntime();
+    const runtimeFactory = vi.fn(() => runtime as never);
+    const service = createAcpxRuntimeService({
+      runtimeFactory,
+    });
+
+    await service.start(ctx);
+
+    expect(readFirstRuntimeFactoryInput(runtimeFactory).pluginConfig.timeoutSeconds).toBe(120);
+
+    await service.stop?.(ctx);
+  });
+
+  it("forwards a configured probeAgent to the runtime factory so the probe does not hardcode the default", async () => {
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const runtime = {
+      ensureSession: vi.fn(),
+      runTurn: vi.fn(),
+      cancel: vi.fn(),
+      close: vi.fn(),
+      probeAvailability: vi.fn(async () => {}),
+      isHealthy: vi.fn(() => true),
+      doctor: vi.fn(async () => ({ ok: true, message: "ok" })),
+    };
+    const runtimeFactory = vi.fn(() => runtime as never);
+    const service = createAcpxRuntimeService({
+      pluginConfig: { probeAgent: "opencode" },
+      runtimeFactory,
+    });
+
+    await service.start(ctx);
+
+    expect(readFirstRuntimeFactoryInput(runtimeFactory).pluginConfig.probeAgent).toBe("opencode");
+
+    await service.stop?.(ctx);
+  });
+
+  it("uses the first allowed ACP agent as the default probe agent", async () => {
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    ctx.config = {
+      acp: {
+        allowedAgents: ["  OpenCode  ", "codex"],
+      },
+    };
+    const runtime = createMockRuntime();
+    const runtimeFactory = vi.fn(() => runtime as never);
+    const service = createAcpxRuntimeService({
+      runtimeFactory,
+    });
+
+    await service.start(ctx);
+
+    expect(readFirstRuntimeFactoryInput(runtimeFactory).pluginConfig.probeAgent).toBe("opencode");
+
+    await service.stop?.(ctx);
+  });
+
+  it("keeps explicit probeAgent ahead of acp.allowedAgents", async () => {
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    ctx.config = {
+      acp: {
+        allowedAgents: ["opencode"],
+      },
+    };
+    const runtime = createMockRuntime();
+    const runtimeFactory = vi.fn(() => runtime as never);
+    const service = createAcpxRuntimeService({
+      pluginConfig: { probeAgent: "codex" },
+      runtimeFactory,
+    });
+
+    await service.start(ctx);
+
+    expect(readFirstRuntimeFactoryInput(runtimeFactory).pluginConfig.probeAgent).toBe("codex");
+
+    await service.stop?.(ctx);
+  });
+
+  it("warns when legacy compatibility config is explicitly ignored", async () => {
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const runtime = createMockRuntime();
+    const service = createAcpxRuntimeService({
+      pluginConfig: {
+        queueOwnerTtlSeconds: 30,
+        strictWindowsCmdWrapper: false,
+      },
+      runtimeFactory: () => runtime as never,
+    });
+
+    await service.start(ctx);
+
+    expect(ctx.logger.warn).toHaveBeenCalledWith(
+      "embedded acpx runtime ignores legacy compatibility config: queueOwnerTtlSeconds, strictWindowsCmdWrapper=false",
+    );
+
+    await service.stop?.(ctx);
+  });
+
+  it("lets the skip env override the opt-in embedded runtime startup probe without advertising health", async () => {
+    process.env.KLAW_ACPX_RUNTIME_STARTUP_PROBE = "1";
+    process.env.KLAW_SKIP_ACPX_RUNTIME_PROBE = "1";
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const probeAvailability = vi.fn(async () => {});
+    const runtime = createMockRuntime({
+      doctor: async () => ({ ok: false, message: "nope" }),
+      isHealthy: () => false,
+      probeAvailability,
+    });
+    const service = createAcpxRuntimeService({
+      runtimeFactory: () => runtime as never,
+    });
+
+    await service.start(ctx);
+
+    expect(probeAvailability).not.toHaveBeenCalled();
+    expect(getAcpRuntimeBackend("acpx")?.runtime).toBe(runtime);
+    expect(getAcpRuntimeBackend("acpx")?.healthy).toBeUndefined();
+
+    await service.stop?.(ctx);
+  });
+
+  it("formats non-string doctor details without losing object payloads", async () => {
+    process.env.KLAW_ACPX_RUNTIME_STARTUP_PROBE = "1";
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const runtime = createMockRuntime({
+      doctor: async () => ({
+        ok: false,
+        message: "probe failed",
+        details: [{ code: "ACP_CLOSED", agent: "codex" }, new Error("stdin closed")],
+      }),
+      isHealthy: () => false,
+    });
+    const service = createAcpxRuntimeService({
+      runtimeFactory: () => runtime as never,
+    });
+
+    await service.start(ctx);
+
+    expect(ctx.logger.warn).toHaveBeenCalledWith(
+      'embedded acpx runtime backend probe failed: probe failed ({"code":"ACP_CLOSED","agent":"codex"}; stdin closed)',
+    );
+
+    await service.stop?.(ctx);
+  });
+
+  it("can skip the embedded runtime backend via env", async () => {
+    process.env.KLAW_SKIP_ACPX_RUNTIME = "1";
+    const workspaceDir = await makeTempDir();
+    const ctx = createServiceContext(workspaceDir);
+    const runtimeFactory = vi.fn(() => {
+      throw new Error("runtime factory should not run when ACPX is skipped");
+    });
+    const service = createAcpxRuntimeService({
+      runtimeFactory: runtimeFactory as never,
+    });
+
+    await service.start(ctx);
+
+    expect(runtimeFactory).not.toHaveBeenCalled();
+    expect(getAcpRuntimeBackend("acpx")).toBeUndefined();
+    expect(ctx.logger.info).toHaveBeenCalledWith(
+      "skipping embedded acpx runtime backend (KLAW_SKIP_ACPX_RUNTIME=1)",
+    );
+  });
+});