@actagent/acpx 2026.6.2

package/src/config.test.ts

@@ -0,0 +1,296 @@
+// ACPX tests cover config plugin behavior.
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { resolveAcpxPluginConfig, resolveAcpxPluginRoot } from "./config.js";
+
+const requireFromTest = createRequire(import.meta.url);
+const TSX_IMPORT = requireFromTest.resolve("tsx");
+
+function expectedMcpServerArgs(params: { sourceEntry: string; distEntry: string }): string[] {
+  const distEntry = path.resolve(params.distEntry);
+  if (fs.existsSync(distEntry)) {
+    return [distEntry];
+  }
+  return ["--import", TSX_IMPORT, path.resolve(params.sourceEntry)];
+}
+
+describe("embedded acpx plugin config", () => {
+  it("resolves workspace stateDir and cwd by default", () => {
+    const workspaceDir = path.resolve("/tmp/actagent-acpx");
+    const resolved = resolveAcpxPluginConfig({
+      rawConfig: undefined,
+      workspaceDir,
+    });
+
+    expect(resolved.cwd).toBe(workspaceDir);
+    expect(resolved.stateDir).toBe(path.join(workspaceDir, "state"));
+    expect(resolved.permissionMode).toBe("approve-reads");
+    expect(resolved.nonInteractivePermissions).toBe("fail");
+    expect(resolved.timeoutSeconds).toBe(120);
+    expect(resolved.agents).toStrictEqual({});
+  });
+
+  it("keeps explicit timeoutSeconds config", () => {
+    const resolved = resolveAcpxPluginConfig({
+      rawConfig: {
+        timeoutSeconds: 300,
+      },
+      workspaceDir: "/tmp/actagent-acpx",
+    });
+
+    expect(resolved.timeoutSeconds).toBe(300);
+  });
+
+  it("keeps explicit probeAgent config", () => {
+    const resolved = resolveAcpxPluginConfig({
+      rawConfig: {
+        probeAgent: "claude",
+      },
+      workspaceDir: "/tmp/actagent-acpx",
+    });
+
+    expect(resolved.probeAgent).toBe("claude");
+  });
+
+  it("accepts agent command overrides", () => {
+    const resolved = resolveAcpxPluginConfig({
+      rawConfig: {
+        agents: {
+          claude: { command: "claude --acp" },
+          codex: { command: "codex custom-acp" },
+        },
+      },
+      workspaceDir: "/tmp/actagent-acpx",
+    });
+
+    expect(resolved.agents).toEqual({
+      claude: "claude --acp",
+      codex: "codex custom-acp",
+    });
+  });
+
+  it("combines agent command with args array", () => {
+    const resolved = resolveAcpxPluginConfig({
+      rawConfig: {
+        agents: {
+          claude: {
+            command: "node",
+            args: ["/path/to/adapter.mjs", "--verbose"],
+          },
+          codex: {
+            command: "codex-acp",
+            args: ["--model", "gpt-5"],
+          },
+        },
+      },
+      workspaceDir: "/tmp/actagent-acpx",
+    });
+
+    expect(resolved.agents).toEqual({
+      claude: "node /path/to/adapter.mjs --verbose",
+      codex: "codex-acp --model gpt-5",
+    });
+  });
+
+  it("quotes agent args that need to survive command-line parsing as one token", () => {
+    const resolved = resolveAcpxPluginConfig({
+      rawConfig: {
+        agents: {
+          custom: {
+            command: "node",
+            args: ["/tmp/My Adapter.mjs", "--flag=value with spaces", "owner's-choice"],
+          },
+        },
+      },
+      workspaceDir: "/tmp/actagent-acpx",
+    });
+
+    expect(resolved.agents).toEqual({
+      custom: "node '/tmp/My Adapter.mjs' '--flag=value with spaces' 'owner'\"'\"'s-choice'",
+    });
+  });
+
+  it("handles agent command without args (backward compat)", () => {
+    const resolved = resolveAcpxPluginConfig({
+      rawConfig: {
+        agents: {
+          simple: { command: "simple-acp" },
+        },
+      },
+      workspaceDir: "/tmp/actagent-acpx",
+    });
+
+    expect(resolved.agents).toEqual({
+      simple: "simple-acp",
+    });
+  });
+
+  it("leaves probeAgent undefined by default so the runtime picks its built-in probe agent", () => {
+    const resolved = resolveAcpxPluginConfig({
+      rawConfig: undefined,
+      workspaceDir: "/tmp/actagent-acpx",
+    });
+
+    expect(resolved.probeAgent).toBeUndefined();
+  });
+
+  it("carries an explicit probeAgent through to the resolved plugin config, trimmed and lowercased", () => {
+    const resolved = resolveAcpxPluginConfig({
+      rawConfig: {
+        probeAgent: "  OpenCode  ",
+      },
+      workspaceDir: "/tmp/actagent-acpx",
+    });
+
+    expect(resolved.probeAgent).toBe("opencode");
+  });
+
+  it("rejects an empty probeAgent string", () => {
+    expect(() =>
+      resolveAcpxPluginConfig({
+        rawConfig: {
+          probeAgent: "",
+        },
+        workspaceDir: "/tmp/actagent-acpx",
+      }),
+    ).toThrow(/probeAgent must be a non-empty string/);
+  });
+
+  it("injects the built-in plugin-tools MCP server only when explicitly enabled", () => {
+    const resolved = resolveAcpxPluginConfig({
+      rawConfig: {
+        pluginToolsMcpBridge: true,
+      },
+      workspaceDir: "/tmp/actagent-acpx",
+    });
+
+    const server = resolved.mcpServers["actagent-plugin-tools"];
+    expect(server).toEqual({
+      command: process.execPath,
+      args: expectedMcpServerArgs({
+        sourceEntry: "src/mcp/plugin-tools-serve.ts",
+        distEntry: "dist/mcp/plugin-tools-serve.js",
+      }),
+    });
+  });
+
+  it("injects the built-in ACTAgent tools MCP server only when explicitly enabled", () => {
+    const resolved = resolveAcpxPluginConfig({
+      rawConfig: {
+        actAgentToolsMcpBridge: true,
+      },
+      workspaceDir: "/tmp/actagent-acpx",
+    });
+
+    const server = resolved.mcpServers["actagent-tools"];
+    expect(server).toEqual({
+      command: process.execPath,
+      args: expectedMcpServerArgs({
+        sourceEntry: "src/mcp/actagent-tools-serve.ts",
+        distEntry: "dist/mcp/actagent-tools-serve.js",
+      }),
+    });
+  });
+
+  it("resolves the plugin root from shared dist chunk paths", () => {
+    const moduleUrl = new URL("../../../dist/extensions/acpx/service-shared.js", import.meta.url)
+      .href;
+
+    expect(resolveAcpxPluginRoot(moduleUrl)).toBe(path.resolve("extensions/acpx"));
+  });
+
+  it("keeps the runtime json schema in sync with the manifest config schema", () => {
+    const pluginRoot = resolveAcpxPluginRoot();
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(pluginRoot, "actagent.plugin.json"), "utf8"),
+    ) as { configSchema?: unknown };
+
+    expect(manifest.configSchema).toStrictEqual({
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        cwd: {
+          type: "string",
+          minLength: 1,
+        },
+        stateDir: {
+          type: "string",
+          minLength: 1,
+        },
+        permissionMode: {
+          type: "string",
+          enum: ["approve-all", "approve-reads", "deny-all"],
+        },
+        nonInteractivePermissions: {
+          type: "string",
+          enum: ["deny", "fail"],
+        },
+        pluginToolsMcpBridge: {
+          type: "boolean",
+        },
+        actAgentToolsMcpBridge: {
+          type: "boolean",
+        },
+        strictWindowsCmdWrapper: {
+          type: "boolean",
+        },
+        timeoutSeconds: {
+          type: "number",
+          minimum: 0.001,
+          default: 120,
+        },
+        queueOwnerTtlSeconds: {
+          type: "number",
+          minimum: 0,
+        },
+        probeAgent: {
+          type: "string",
+          minLength: 1,
+        },
+        mcpServers: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            properties: {
+              command: {
+                type: "string",
+                minLength: 1,
+                description: "Command to run the MCP server",
+              },
+              args: {
+                type: "array",
+                items: { type: "string" },
+                description: "Arguments to pass to the command",
+              },
+              env: {
+                type: "object",
+                additionalProperties: { type: "string" },
+                description: "Environment variables for the MCP server",
+              },
+            },
+            required: ["command"],
+          },
+        },
+        agents: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            properties: {
+              command: {
+                type: "string",
+                minLength: 1,
+              },
+              args: {
+                type: "array",
+                items: { type: "string" },
+              },
+            },
+            required: ["command"],
+          },
+        },
+      },
+    });
+  });
+});

package/src/config.ts

@@ -0,0 +1,290 @@
+/**
+ * Resolves ACPX plugin config from raw user configuration. It locates the
+ * plugin root, injects optional MCP bridge servers, and applies runtime defaults.
+ */
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { formatPluginConfigIssue } from "actagent/plugin-sdk/extension-shared";
+import { normalizeLowercaseStringOrEmpty } from "actagent/plugin-sdk/string-coerce-runtime";
+import { AcpxPluginConfigSchema, DEFAULT_ACPX_TIMEOUT_SECONDS } from "./config-schema.js";
+import type {
+  AcpxPluginConfig,
+  AcpxPermissionMode,
+  AcpxNonInteractivePermissionPolicy,
+  McpServerConfig,
+  AcpxMcpServer,
+  ResolvedAcpxPluginConfig,
+} from "./config-schema.js";
+export { type ResolvedAcpxPluginConfig } from "./config-schema.js";
+
+const ACPX_PLUGIN_TOOLS_MCP_SERVER_NAME = "actagent-plugin-tools";
+const ACPX_ACTAGENT_TOOLS_MCP_SERVER_NAME = "actagent-tools";
+const requireFromHere = createRequire(import.meta.url);
+
+function isAcpxPluginRoot(dir: string): boolean {
+  return (
+    fs.existsSync(path.join(dir, "actagent.plugin.json")) &&
+    fs.existsSync(path.join(dir, "package.json"))
+  );
+}
+
+function resolveNearestAcpxPluginRoot(moduleUrl: string): string {
+  let cursor = path.dirname(fileURLToPath(moduleUrl));
+  for (let i = 0; i < 3; i += 1) {
+    // Bundled entries live at the plugin root while source files still live under src/.
+    if (isAcpxPluginRoot(cursor)) {
+      return cursor;
+    }
+    const parent = path.dirname(cursor);
+    if (parent === cursor) {
+      break;
+    }
+    cursor = parent;
+  }
+  return path.resolve(path.dirname(fileURLToPath(moduleUrl)), "..");
+}
+
+function resolveWorkspaceAcpxPluginRoot(currentRoot: string): string | null {
+  if (
+    path.basename(currentRoot) !== "acpx" ||
+    path.basename(path.dirname(currentRoot)) !== "extensions" ||
+    path.basename(path.dirname(path.dirname(currentRoot))) !== "dist"
+  ) {
+    return null;
+  }
+  const workspaceRoot = path.resolve(currentRoot, "..", "..", "..", "extensions", "acpx");
+  return isAcpxPluginRoot(workspaceRoot) ? workspaceRoot : null;
+}
+
+function resolveRepoAcpxPluginRoot(currentRoot: string): string | null {
+  const workspaceRoot = path.join(currentRoot, "extensions", "acpx");
+  return isAcpxPluginRoot(workspaceRoot) ? workspaceRoot : null;
+}
+
+function resolveAcpxPluginRootFromACTAgentLayout(moduleUrl: string): string | null {
+  let cursor = path.dirname(fileURLToPath(moduleUrl));
+  for (let i = 0; i < 5; i += 1) {
+    const candidates = [
+      path.join(cursor, "extensions", "acpx"),
+      path.join(cursor, "dist", "extensions", "acpx"),
+      path.join(cursor, "dist-runtime", "extensions", "acpx"),
+    ];
+    for (const candidate of candidates) {
+      if (isAcpxPluginRoot(candidate)) {
+        return candidate;
+      }
+    }
+    const parent = path.dirname(cursor);
+    if (parent === cursor) {
+      break;
+    }
+    cursor = parent;
+  }
+  return null;
+}
+/** Resolve the ACPX plugin root across source, dist, and dist-runtime layouts. */
+export function resolveAcpxPluginRoot(moduleUrl: string = import.meta.url): string {
+  const resolvedRoot = resolveNearestAcpxPluginRoot(moduleUrl);
+  // In a live repo checkout, dist/ can be rebuilt out from under the running gateway.
+  // Prefer the stable source plugin root when a built extension is running beside it.
+  return (
+    resolveWorkspaceAcpxPluginRoot(resolvedRoot) ??
+    resolveRepoAcpxPluginRoot(resolvedRoot) ??
+    // Shared dist/dist-runtime chunks can load this module outside the plugin tree.
+    // Scan common ACTAgent layouts before falling back to the nearest path guess.
+    resolveAcpxPluginRootFromACTAgentLayout(moduleUrl) ??
+    resolvedRoot
+  );
+}
+
+const DEFAULT_PERMISSION_MODE: AcpxPermissionMode = "approve-reads";
+const DEFAULT_NON_INTERACTIVE_POLICY: AcpxNonInteractivePermissionPolicy = "fail";
+const DEFAULT_QUEUE_OWNER_TTL_SECONDS = 0.1;
+const DEFAULT_STRICT_WINDOWS_CMD_WRAPPER = true;
+
+type ParseResult =
+  | { ok: true; value: AcpxPluginConfig | undefined }
+  | { ok: false; message: string };
+
+function parseAcpxPluginConfig(value: unknown): ParseResult {
+  if (value === undefined) {
+    return { ok: true, value: undefined };
+  }
+  const parsed = AcpxPluginConfigSchema.safeParse(value);
+  if (!parsed.success) {
+    return { ok: false, message: formatPluginConfigIssue(parsed.error.issues[0]) };
+  }
+  return {
+    ok: true,
+    value: parsed.data as AcpxPluginConfig,
+  };
+}
+
+function resolveACTAgentRoot(currentRoot: string): string {
+  if (
+    path.basename(currentRoot) === "acpx" &&
+    path.basename(path.dirname(currentRoot)) === "extensions"
+  ) {
+    const parent = path.dirname(path.dirname(currentRoot));
+    if (path.basename(parent) === "dist") {
+      return path.dirname(parent);
+    }
+    return parent;
+  }
+  return path.resolve(currentRoot, "..");
+}
+
+function resolveTsxImportSpecifier(): string {
+  try {
+    return requireFromHere.resolve("tsx");
+  } catch {
+    return "tsx";
+  }
+}
+
+function shellQuoteCommandArg(arg: string): string {
+  if (!/[\s'"\\$|&;<>{}()*?[\]~`]/.test(arg)) {
+    return arg;
+  }
+  return `'${arg.replace(/'/g, "'\"'\"'")}'`;
+}
+
+function resolvePluginToolsMcpServerConfig(moduleUrl: string = import.meta.url): McpServerConfig {
+  const pluginRoot = resolveAcpxPluginRoot(moduleUrl);
+  const actAgentRoot = resolveACTAgentRoot(pluginRoot);
+  const distEntry = path.join(actAgentRoot, "dist", "mcp", "plugin-tools-serve.js");
+  if (fs.existsSync(distEntry)) {
+    return {
+      command: process.execPath,
+      args: [distEntry],
+    };
+  }
+  const sourceEntry = path.join(actAgentRoot, "src", "mcp", "plugin-tools-serve.ts");
+  return {
+    command: process.execPath,
+    args: ["--import", resolveTsxImportSpecifier(), sourceEntry],
+  };
+}
+
+function resolveACTAgentToolsMcpServerConfig(moduleUrl: string = import.meta.url): McpServerConfig {
+  const pluginRoot = resolveAcpxPluginRoot(moduleUrl);
+  const actAgentRoot = resolveACTAgentRoot(pluginRoot);
+  const distEntry = path.join(actAgentRoot, "dist", "mcp", "actagent-tools-serve.js");
+  if (fs.existsSync(distEntry)) {
+    return {
+      command: process.execPath,
+      args: [distEntry],
+    };
+  }
+  const sourceEntry = path.join(actAgentRoot, "src", "mcp", "actagent-tools-serve.ts");
+  return {
+    command: process.execPath,
+    args: ["--import", resolveTsxImportSpecifier(), sourceEntry],
+  };
+}
+
+function resolveConfiguredMcpServers(params: {
+  mcpServers?: Record<string, McpServerConfig>;
+  pluginToolsMcpBridge: boolean;
+  actAgentToolsMcpBridge: boolean;
+  moduleUrl?: string;
+}): Record<string, McpServerConfig> {
+  const resolved = { ...params.mcpServers };
+  if (params.pluginToolsMcpBridge && resolved[ACPX_PLUGIN_TOOLS_MCP_SERVER_NAME]) {
+    throw new Error(
+      `mcpServers.${ACPX_PLUGIN_TOOLS_MCP_SERVER_NAME} is reserved when pluginToolsMcpBridge=true`,
+    );
+  }
+  if (params.actAgentToolsMcpBridge && resolved[ACPX_ACTAGENT_TOOLS_MCP_SERVER_NAME]) {
+    throw new Error(
+      `mcpServers.${ACPX_ACTAGENT_TOOLS_MCP_SERVER_NAME} is reserved when actAgentToolsMcpBridge=true`,
+    );
+  }
+  if (params.pluginToolsMcpBridge) {
+    resolved[ACPX_PLUGIN_TOOLS_MCP_SERVER_NAME] = resolvePluginToolsMcpServerConfig(
+      params.moduleUrl,
+    );
+  }
+  if (params.actAgentToolsMcpBridge) {
+    resolved[ACPX_ACTAGENT_TOOLS_MCP_SERVER_NAME] = resolveACTAgentToolsMcpServerConfig(
+      params.moduleUrl,
+    );
+  }
+  return resolved;
+}
+
+/** Convert ACTAgent MCP server config into ACPX runtime MCP server entries. */
+export function toAcpMcpServers(mcpServers: Record<string, McpServerConfig>): AcpxMcpServer[] {
+  return Object.entries(mcpServers).map(([name, server]) => ({
+    name,
+    command: server.command,
+    args: [...(server.args ?? [])],
+    env: Object.entries(server.env ?? {}).map(([envName, value]) => ({
+      name: envName,
+      value,
+    })),
+  }));
+}
+
+/** Validate and normalize raw ACPX plugin config for runtime startup. */
+export function resolveAcpxPluginConfig(params: {
+  rawConfig: unknown;
+  workspaceDir?: string;
+  moduleUrl?: string;
+}): ResolvedAcpxPluginConfig {
+  const parsed = parseAcpxPluginConfig(params.rawConfig);
+  if (!parsed.ok) {
+    throw new Error(parsed.message);
+  }
+  const normalized = parsed.value ?? {};
+  const workspaceDir = params.workspaceDir?.trim() || process.cwd();
+  const fallbackCwd = workspaceDir;
+  const cwd = path.resolve(normalized.cwd?.trim() || fallbackCwd);
+  const stateDir = path.resolve(normalized.stateDir?.trim() || path.join(workspaceDir, "state"));
+  const pluginToolsMcpBridge = normalized.pluginToolsMcpBridge === true;
+  const actAgentToolsMcpBridge = normalized.actAgentToolsMcpBridge === true;
+  const mcpServers = resolveConfiguredMcpServers({
+    mcpServers: normalized.mcpServers,
+    pluginToolsMcpBridge,
+    actAgentToolsMcpBridge,
+    moduleUrl: params.moduleUrl,
+  });
+  const agents = Object.fromEntries(
+    Object.entries(normalized.agents ?? {}).map(([name, entry]) => {
+      const cmd = entry.command.trim();
+      const cmdArgs = entry.args ?? [];
+      const fullCommand =
+        cmdArgs.length > 0 ? `${cmd} ${cmdArgs.map(shellQuoteCommandArg).join(" ")}` : cmd;
+      return [normalizeLowercaseStringOrEmpty(name), fullCommand];
+    }),
+  );
+
+  // Lowercase probeAgent so lookups match the registry keys built above, which
+  // also go through normalizeLowercaseStringOrEmpty. Without this, a user who
+  // writes `probeAgent: "OpenCode"` would silently miss the stored "opencode"
+  // key.
+  const probeAgent = normalizeLowercaseStringOrEmpty(normalized.probeAgent) || undefined;
+
+  return {
+    cwd,
+    stateDir,
+    probeAgent,
+    permissionMode: normalized.permissionMode ?? DEFAULT_PERMISSION_MODE,
+    nonInteractivePermissions:
+      normalized.nonInteractivePermissions ?? DEFAULT_NON_INTERACTIVE_POLICY,
+    pluginToolsMcpBridge,
+    actAgentToolsMcpBridge,
+    strictWindowsCmdWrapper:
+      normalized.strictWindowsCmdWrapper ?? DEFAULT_STRICT_WINDOWS_CMD_WRAPPER,
+    timeoutSeconds: normalized.timeoutSeconds ?? DEFAULT_ACPX_TIMEOUT_SECONDS,
+    queueOwnerTtlSeconds: normalized.queueOwnerTtlSeconds ?? DEFAULT_QUEUE_OWNER_TTL_SECONDS,
+    legacyCompatibilityConfig: {
+      strictWindowsCmdWrapper: normalized.strictWindowsCmdWrapper,
+      queueOwnerTtlSeconds: normalized.queueOwnerTtlSeconds,
+    },
+    mcpServers,
+    agents,
+  };
+}

package/src/manifest.test.ts

@@ -0,0 +1,22 @@
+// ACPX tests cover manifest plugin behavior.
+import fs from "node:fs";
+import { describe, expect, it } from "vitest";
+
+type AcpxPackageManifest = {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+};
+
+const packageJson = JSON.parse(
+  fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+) as AcpxPackageManifest;
+
+describe("acpx package manifest", () => {
+  it("keeps runtime dependencies in the package manifest", () => {
+    expect(packageJson.dependencies?.acpx).toBeTypeOf("string");
+    expect(packageJson.dependencies?.acpx).not.toBe("");
+    expect(packageJson.dependencies?.["@zed-industries/codex-acp"]).toBe("0.15.0");
+    expect(packageJson.dependencies?.["@agentclientprotocol/claude-agent-acp"]).toBe("0.39.0");
+    expect(packageJson.devDependencies?.["@agentclientprotocol/claude-agent-acp"]).toBeUndefined();
+  });
+});

package/src/process-lease.test.ts

@@ -0,0 +1,90 @@
+// ACPX tests cover process lease plugin behavior.
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  createAcpxProcessLeaseStore,
+  ACTAGENT_ACPX_LEASE_ID_ARG,
+  ACTAGENT_ACPX_LEASE_ID_ENV,
+  ACTAGENT_GATEWAY_INSTANCE_ID_ARG,
+  ACTAGENT_GATEWAY_INSTANCE_ID_ENV,
+  withAcpxLeaseEnvironment,
+  type AcpxProcessLease,
+} from "./process-lease.js";
+
+function makeLease(index: number): AcpxProcessLease {
+  return {
+    leaseId: `lease-${index}`,
+    gatewayInstanceId: "gateway-test",
+    sessionKey: `agent:codex:acp:${index}`,
+    wrapperRoot: "/tmp/actagent/acpx",
+    wrapperPath: "/tmp/actagent/acpx/codex-acp-wrapper.mjs",
+    rootPid: 1000 + index,
+    commandHash: `hash-${index}`,
+    startedAt: index,
+    state: "open",
+  };
+}
+
+describe("createAcpxProcessLeaseStore", () => {
+  it("serializes concurrent lease saves without dropping records", async () => {
+    const stateDir = await mkdtemp(path.join(tmpdir(), "actagent-acpx-leases-"));
+    try {
+      const store = createAcpxProcessLeaseStore({ stateDir });
+      await Promise.all(Array.from({ length: 25 }, (_, index) => store.save(makeLease(index))));
+
+      const leases = await store.listOpen("gateway-test");
+      expect(leases.map((lease) => lease.leaseId).toSorted()).toEqual(
+        Array.from({ length: 25 }, (_, index) => `lease-${index}`).toSorted(),
+      );
+    } finally {
+      await rm(stateDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("withAcpxLeaseEnvironment", () => {
+  it("adds lease environment and wrapper args on POSIX", () => {
+    const command = withAcpxLeaseEnvironment({
+      command: "node /tmp/actagent/acpx/codex-acp-wrapper.mjs",
+      leaseId: "lease-test",
+      gatewayInstanceId: "gateway-test",
+      platform: "darwin",
+    });
+
+    expect(command).toBe(
+      [
+        "env",
+        `${ACTAGENT_ACPX_LEASE_ID_ENV}=lease-test`,
+        `${ACTAGENT_GATEWAY_INSTANCE_ID_ENV}=gateway-test`,
+        "node /tmp/actagent/acpx/codex-acp-wrapper.mjs",
+        ACTAGENT_ACPX_LEASE_ID_ARG,
+        "lease-test",
+        ACTAGENT_GATEWAY_INSTANCE_ID_ARG,
+        "gateway-test",
+      ].join(" "),
+    );
+  });
+
+  it("keeps Windows logs keyed by lease id with wrapper args", () => {
+    const command = withAcpxLeaseEnvironment({
+      command: "node C:/actagent/acpx/codex-acp-wrapper.mjs",
+      leaseId: "lease-test",
+      gatewayInstanceId: "gateway-test",
+      platform: "win32",
+    });
+
+    expect(command).toBe(
+      [
+        "node C:/actagent/acpx/codex-acp-wrapper.mjs",
+        ACTAGENT_ACPX_LEASE_ID_ARG,
+        "lease-test",
+        ACTAGENT_GATEWAY_INSTANCE_ID_ARG,
+        "gateway-test",
+      ].join(" "),
+    );
+    expect(command).not.toContain(`${ACTAGENT_ACPX_LEASE_ID_ENV}=`);
+    expect(command).not.toContain(`${ACTAGENT_GATEWAY_INSTANCE_ID_ENV}=`);
+  });
+});