@gleapai/kai-bridge 0.2.0

package/runner/acp-runner.mjs

@@ -0,0 +1,671 @@
+#!/usr/bin/env node
+// Kai Code ACP runner — ONE driver for every harness that speaks the
+// Agent Client Protocol (https://agentclientprotocol.com).
+//
+// Same contract argv as the engine-specific runners (parseRunnerArgs)
+// plus `--harness claude|codex`; same JSONL event stream out. The
+// harness adapter (claude-agent-acp, codex-acp, …) runs as a child over
+// stdio; we are the ACP *client*: open a session in the workspace with
+// the persona + MCP servers, send the prompt, translate `session/update`
+// into contract events (lib/acp/mapper.mjs), answer permission requests
+// (build = allow; question / plan hand-off = end the turn), and close
+// with a `result` whose token split comes from the harness's own
+// transcript (lib/acp/transcripts.mjs) — the only place the per-model
+// cache buckets exist.
+//
+// This is the cloud runner AND the local bridge's executor: nothing in
+// here assumes E2B beyond the default runner dir.
+
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Readable, Writable } from "node:stream";
+
+import { ClientSideConnection, ndJsonStream } from "@agentclientprotocol/sdk";
+
+import {
+  KAI_RESOLUTION_ANALYST_AGENT_NAME,
+  captureRepoBaselines,
+  createUsageTracker,
+  debugLog,
+  emit,
+  emitSync,
+  isArtifactWriterAgent,
+  parseRunnerArgs,
+  revertRepoMutations,
+  setTracePrefix,
+  startHeartbeat,
+  traceLog,
+} from "./lib/contract.mjs";
+import { deriveEngineSlug, getHarness, isNativeAnthropic, pickSessionMode, resolveHarnessId } from "./lib/acp/harnesses.mjs";
+import { createAcpMapper, permissionPolicy } from "./lib/acp/mapper.mjs";
+import { aggregateUsageRows, lastRootContextSnapshot } from "./lib/acp/transcripts.mjs";
+import { needsWireProxy, startWireProxy } from "./lib/wire-proxy.mjs";
+
+setTracePrefix("acp");
+
+const ARGS = parseRunnerArgs(process.argv.slice(2));
+const {
+  agent: AGENT,
+  isPlanMode: IS_PLAN_MODE,
+  subagentModel: SUBAGENT_MODEL,
+  workDir: WORK_DIR,
+  maxSteps: MAX_STEPS,
+  effort: EFFORT,
+  sessionId: SESSION_ID,
+  maxBudgetUsd: MAX_BUDGET_USD,
+  task: TASK,
+  feedback: FEEDBACK,
+  questionAnswers: QUESTION_ANSWERS,
+  attachments: ATTACHMENTS,
+  customSystemPrompt: CUSTOM_SYSTEM_PROMPT,
+  mcpServers: MCP_SERVERS,
+  modelPricing: MODEL_PRICING,
+  maxContextTokens: MAX_CONTEXT_TOKENS,
+  maxOutputTokens: MAX_OUTPUT_TOKENS,
+  backgroundModel: BACKGROUND_MODEL,
+  providerOrders: PROVIDER_ORDERS,
+} = ARGS;
+const MODEL = String(ARGS.model || "anthropic/claude-sonnet-4-6");
+const ENGINE_MODEL = ARGS.engineModel;
+const HARNESS_ID = resolveHarnessId(ARGS.argv.harness, MODEL);
+const HARNESS = getHarness(HARNESS_ID);
+const IS_ARTIFACT_WRITER = isArtifactWriterAgent(AGENT);
+
+if (!TASK) {
+  emitSync({ type: "error", message: "runner: missing --task-b64 argument" });
+  process.exit(1);
+}
+
+const RUNNER_DIR = dirname(fileURLToPath(import.meta.url));
+const PERSONA_DIR = process.env.KAI_PERSONA_DIR || "/opt/gleap-runners/personas";
+const PERSONA_AGENTS = new Set(["kai-documentarian", "kai-asker", "kai-researcher", KAI_RESOLUTION_ANALYST_AGENT_NAME]);
+const SCRATCH_DIR = join(tmpdir(), `kai-acp-${process.pid}`);
+mkdirSync(SCRATCH_DIR, { recursive: true });
+// Harness config dir lives OUTSIDE the repo tree and survives across
+// turns of the same session (resume + transcript) — keyed by session.
+const STATE_ROOT = process.env.KAI_ACP_STATE_DIR || join(tmpdir(), "kai-acp-state");
+
+const GIT_HANDOFF_PROMPT =
+  "Never run `git add`, `git commit`, or `git push` — the Gleap host " +
+  "creates commits and pull requests from your working tree after the " +
+  "turn ends. Leave all changes uncommitted.";
+const GIT_HANDOFF_DISALLOWED = [
+  "Bash(git add:*)",
+  "Bash(git commit:*)",
+  "Bash(git push:*)",
+];
+// Gateway wire (OpenRouter skin): the CLI's native AskUserQuestion /
+// ExitPlanMode tools don't exist for unrecognised model ids, so the
+// ask_user MCP bridge stands in (carried over from the retired claude-runner.mjs).
+const IS_GATEWAY_CLAUDE = HARNESS_ID === "claude" && !isNativeAnthropic(MODEL);
+// Codex has no native question tool either (elicitation only covers
+// approvals), so it gets the same bridge — that is literally what
+// ask-user-mcp.mjs was written for. Without it a Codex turn that is
+// told to ask the user something just skips the ask.
+const NEEDS_ASK_USER_MCP = IS_GATEWAY_CLAUDE || HARNESS_ID === "codex";
+const ASK_USER_SERVER_KEY = "kai_user";
+const ASK_USER_MCP_PATH = process.env.KAI_ASK_USER_MCP_PATH || join(RUNNER_DIR, "tools", "ask-user-mcp.mjs");
+// Todo bridge for EVERY harness: Claude's own task tools (TaskCreate/…)
+// vanish from resumed BYO sessions (the CLI's deferred-tool
+// reconciliation removes them on resume when the user's ambient
+// claude.ai connector set is loaded — upstream bug), and Codex has no
+// todo tool at all. `todo_write` calls are folded onto the canonical
+// TodoWrite path by the mapper, which emits the dashboard `todos`
+// events either way.
+const TODO_SERVER_KEY = "kai_todos";
+const TODO_MCP_PATH = process.env.KAI_TODO_MCP_PATH || join(RUNNER_DIR, "tools", "todo-mcp.mjs");
+const TODO_NOTE =
+  "Track multi-step work as a live todo list with the `todo_write` tool " +
+  `from the \`${TODO_SERVER_KEY}\` MCP server: pass the FULL updated list ` +
+  "(todos: [{content, status: pending|in_progress|completed}]) whenever a " +
+  "step starts or finishes — the user's dashboard renders it live. Use it " +
+  "INSTEAD of TodoWrite / TaskCreate / TaskUpdate, which may be " +
+  "unavailable in this environment.";
+// Harnesses prefix MCP tool names differently (Claude: `mcp__kai_user__ask_user`,
+// Codex: server-scoped) — the note names the tool + server, and the
+// mapper's `ask_user` suffix match catches every spelling.
+const ASK_USER_TOOL_REF = `\`ask_user\` tool from the \`${ASK_USER_SERVER_KEY}\` MCP server`;
+const GATEWAY_QUESTION_NOTE =
+  "The AskUserQuestion tool is NOT available in this environment — " +
+  `where instructions mention it, use the ${ASK_USER_TOOL_REF} ` +
+  "instead. To ask the user clarifying questions, call that " +
+  "tool with your structured questions and END YOUR TURN — the answers " +
+  "arrive in the next user message. Never ask questions as plain text.";
+const GATEWAY_PLAN_GUARD =
+  "The ExitPlanMode tool is NOT available in this environment either. " +
+  "To finalise a plan: end your turn with the complete plan as your " +
+  "final message — do NOT attempt to write plan files anywhere (file " +
+  "writes are declined in plan mode; the platform captures the plan " +
+  "from your final message). Your final message is shown to the user " +
+  "verbatim as the plan: never mention declined tool calls, permission " +
+  "errors, or where you tried to save it. " +
+  `If you asked questions via the ${ASK_USER_TOOL_REF}, ` +
+  "do NOT also finalise the plan in the same turn — wait for " +
+  "the answers first.";
+// Tool allow-lists (Claude permission rules). Plan mode and artifact
+// writers (kai-asker / researcher / documentarian: `.kai/` outputs only,
+// never repo edits) run under the CLI's own gating with these rules;
+// build mode bypasses permissions — the worktree IS the boundary.
+// AskUserQuestion / ExitPlanMode deliberately NOT here: a bare allow-list
+// entry bypasses the SDK's canUseTool, and claude-agent-acp delivers both
+// through canUseTool (AskUserQuestion → form elicitation, ExitPlanMode →
+// permission request). The question tool is offered because we advertise
+// `elicitation.form` on initialize.
+const NONWRITE_TOOLS_ALLOWED = ["Read", "Grep", "Glob", "Task", "TodoWrite", "WebFetch", "WebSearch", "ToolSearch"];
+const READONLY_BASH_ALLOWED = [
+  "cat", "head", "tail", "wc", "stat", "ls", "find", "grep", "rg", "git log", "git diff", "git show", "git status",
+  "git ls-files", "git grep", "git rev-parse", "git branch", "sed -n", "awk", "jq", "sort", "uniq", "cut", "tr",
+  "diff", "nl", "basename", "dirname", "realpath", "file",
+].map((c) => `Bash(${c}:*)`);
+const absRule = (p) => `//${String(p).replace(/^\/+/, "")}`;
+const KAI_WRITE_ALLOWED = [
+  `Write(${absRule(WORK_DIR)}/.kai/**)`,
+  `Edit(${absRule(WORK_DIR)}/.kai/**)`,
+  `MultiEdit(${absRule(WORK_DIR)}/.kai/**)`,
+  "Write(.kai/**)",
+  "Edit(.kai/**)",
+  "MultiEdit(.kai/**)",
+];
+const DOC_EXPLORER_AGENT_NAME = "kai-doc-explorer";
+const DOC_EXPLORER_DESCRIPTION =
+  "Help-center research subagent. Investigates ONE user-facing feature " +
+  "area across the cloned repositories (read-only) and returns a " +
+  "structured findings dossier with file citations and quoted strings.";
+
+const PLAN_QUESTION_GUARD =
+  "When you call AskUserQuestion in plan mode, do NOT also call " +
+  "ExitPlanMode or write a plan file in the same turn. End the turn " +
+  "with the AskUserQuestion call and wait for the user's answer; " +
+  "finalise the plan only on a subsequent turn after questions are answered.";
+
+// ── Prompt + persona ──────────────────────────────────────────────────
+function renderAnswersBlock() {
+  if (!Array.isArray(QUESTION_ANSWERS) || QUESTION_ANSWERS.length === 0) return "";
+  const lines = QUESTION_ANSWERS.map((a, i) => `${i + 1}. ${Array.isArray(a) ? a.join(", ") : String(a)}`);
+  return `Answers to your questions:\n${lines.join("\n")}`;
+}
+
+/** Download attachments into scratch so the agent can Read them. */
+async function downloadAttachments() {
+  const saved = [];
+  if (!Array.isArray(ATTACHMENTS) || ATTACHMENTS.length === 0) return saved;
+  const dir = join(SCRATCH_DIR, "attachments");
+  mkdirSync(dir, { recursive: true });
+  for (const [i, att] of ATTACHMENTS.entries()) {
+    if (!att?.url) continue;
+    const safeName = String(att.name || `attachment-${i}`).replace(/[^a-zA-Z0-9._-]/g, "_");
+    const target = join(dir, `${i}-${safeName}`);
+    try {
+      const res = await fetch(att.url, { signal: AbortSignal.timeout(60_000) });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      writeFileSync(target, Buffer.from(await res.arrayBuffer()));
+      saved.push({ path: target, type: att.type, name: att.name });
+      traceLog("attachment.saved", { name: att.name });
+    } catch (err) {
+      traceLog("attachment.failed", { name: att.name, error: err?.message ?? String(err) });
+    }
+  }
+  return saved;
+}
+
+function buildPrompt(savedAttachments = []) {
+  const sections = [];
+  const answers = renderAnswersBlock();
+  if (FEEDBACK) {
+    sections.push(FEEDBACK);
+    if (answers) sections.push(answers);
+  } else if (answers) {
+    sections.push(answers);
+    sections.push("Continue the task using these answers.");
+  } else {
+    sections.push(TASK);
+  }
+  if (savedAttachments.length > 0) {
+    const list = savedAttachments.map((a) => `- ${a.path} (${a.type})`).join("\n");
+    sections.push(`The user attached the following files — read them with the Read tool:\n${list}`);
+  }
+  return sections.join("\n\n");
+}
+
+function buildAppendSystemPrompt() {
+  const sections = [];
+  if (PERSONA_AGENTS.has(AGENT)) {
+    // Codex has its own compiled personas; Claude + Cursor share the Claude set.
+    const personaPath = join(PERSONA_DIR, HARNESS_ID === "codex" ? "codex" : "claude", `${AGENT}.md`);
+    if (existsSync(personaPath)) {
+      const body = readFileSync(personaPath, "utf8").trim();
+      if (body) sections.push(body);
+    } else {
+      traceLog("persona.missing", { agent: AGENT, path: personaPath });
+    }
+  }
+  if (NEEDS_ASK_USER_MCP && !IS_ARTIFACT_WRITER) sections.push(GATEWAY_QUESTION_NOTE);
+  if (IS_PLAN_MODE) sections.push(NEEDS_ASK_USER_MCP ? GATEWAY_PLAN_GUARD : PLAN_QUESTION_GUARD);
+  if (!IS_PLAN_MODE) sections.push(GIT_HANDOFF_PROMPT);
+  // After the safety guards (their leading position is load-bearing for
+  // cursor's prompt-prefix mode) but before project instructions.
+  if (!IS_ARTIFACT_WRITER) sections.push(TODO_NOTE);
+  // Project instructions ALWAYS last so the cached prefix stays stable.
+  if (CUSTOM_SYSTEM_PROMPT && CUSTOM_SYSTEM_PROMPT.trim()) sections.push(CUSTOM_SYSTEM_PROMPT.trim());
+  return sections.join("\n\n");
+}
+
+/** Host MCP servers → ACP `mcpServers` (stdio + http both supported). */
+function buildAcpMcpServers() {
+  const out = [];
+  if (NEEDS_ASK_USER_MCP && existsSync(ASK_USER_MCP_PATH)) {
+    out.push({ name: ASK_USER_SERVER_KEY, command: process.execPath, args: [ASK_USER_MCP_PATH], env: [] });
+  }
+  if (!IS_ARTIFACT_WRITER && existsSync(TODO_MCP_PATH)) {
+    out.push({ name: TODO_SERVER_KEY, command: process.execPath, args: [TODO_MCP_PATH], env: [] });
+  }
+  for (const server of MCP_SERVERS || []) {
+    if (!server || typeof server !== "object") continue;
+    const name = String(server.name || server.id || "").replace(/[^a-zA-Z0-9_-]/g, "_");
+    if (!name) continue;
+    if (server.transport === "http" && server.url) {
+      out.push({
+        type: "http",
+        name,
+        url: String(server.url),
+        headers: Object.entries(server.headers || {}).map(([k, v]) => ({ name: k, value: String(v) })),
+      });
+    } else if (server.command) {
+      out.push({
+        name,
+        command: String(server.command),
+        args: Array.isArray(server.args) ? server.args.map(String) : [],
+        env: Object.entries(server.env || {}).map(([k, v]) => ({ name: k, value: String(v) })),
+      });
+    }
+  }
+  return out;
+}
+
+function buildAllowedTools(mcpAllowed) {
+  if (IS_PLAN_MODE) return [...NONWRITE_TOOLS_ALLOWED, ...READONLY_BASH_ALLOWED, ...mcpAllowed];
+  if (IS_ARTIFACT_WRITER) return [...NONWRITE_TOOLS_ALLOWED, ...READONLY_BASH_ALLOWED, ...KAI_WRITE_ALLOWED, ...mcpAllowed];
+  return undefined;
+}
+
+/** Documentarian fan-out: the read-only research subagent, by name. */
+function buildAgents() {
+  if (AGENT !== "kai-documentarian" || HARNESS_ID !== "claude") return undefined;
+  const explorerPath = join(PERSONA_DIR, "claude", `${DOC_EXPLORER_AGENT_NAME}.md`);
+  if (!existsSync(explorerPath)) {
+    traceLog("persona.missing", { agent: DOC_EXPLORER_AGENT_NAME, path: explorerPath });
+    return undefined;
+  }
+  const def = {
+    description: DOC_EXPLORER_DESCRIPTION,
+    prompt: readFileSync(explorerPath, "utf8"),
+    tools: ["Read", "Grep", "Glob", "Bash", "WebFetch", "WebSearch"],
+  };
+  if (SUBAGENT_MODEL && isNativeAnthropic(SUBAGENT_MODEL) === isNativeAnthropic(MODEL)) {
+    def.model = deriveEngineSlug(SUBAGENT_MODEL);
+  }
+  return { [DOC_EXPLORER_AGENT_NAME]: def };
+}
+
+function buildDisallowedTools() {
+  const list = IS_PLAN_MODE || IS_ARTIFACT_WRITER ? [] : [...GIT_HANDOFF_DISALLOWED];
+  for (const server of MCP_SERVERS || []) {
+    const key = String(server?.name || server?.id || "").replace(/[^a-zA-Z0-9_-]/g, "_");
+    for (const tool of [...(server?.disabledTools ?? []), ...(server?.gatedTools ?? [])]) {
+      list.push(`mcp__${key}__${String(tool).replace(/[^a-zA-Z0-9_-]/g, "_")}`);
+    }
+  }
+  return list;
+}
+
+// ── Main ──────────────────────────────────────────────────────────────
+async function main() {
+  // One config dir per harness (NOT per session): the agent mints the
+  // session id on turn 1, and the resume turn must find the same
+  // transcript + settings under it.
+  // `KAI_ACP_CONFIG_DIR` = the local bridge pointing at a BYO profile
+  // (the user's own `claude` / `codex` login dir).
+  const configDir = process.env.KAI_ACP_CONFIG_DIR || join(STATE_ROOT, HARNESS_ID);
+  mkdirSync(configDir, { recursive: true });
+  // `KAI_ACP_CONFIG_DIR_AMBIENT=1` = configDir is the CLI's own default
+  // dir (the user's ambient login). Claude must then NOT get an explicit
+  // CLAUDE_CONFIG_DIR: on macOS the CLI keeps OAuth in the keychain only
+  // while the env var is unset — exporting it (even set to the default
+  // path) flips credential lookup to `.credentials.json` and a real
+  // login probes as signed-out. Transcripts still read from configDir.
+  const configDirAmbient = process.env.KAI_ACP_CONFIG_DIR_AMBIENT === "1";
+  const appendSystemPrompt = buildAppendSystemPrompt();
+  const savedAttachments = await downloadAttachments();
+  let instructionsPath;
+  if (HARNESS_ID === "codex" && appendSystemPrompt) {
+    instructionsPath = join(SCRATCH_DIR, "instructions.md");
+    writeFileSync(instructionsPath, appendSystemPrompt);
+  }
+
+  const ctx = {
+    runnerDir: RUNNER_DIR,
+    configDir,
+    configDirAmbient,
+    workDir: WORK_DIR,
+    model: MODEL,
+    engineModel: ENGINE_MODEL,
+    subagentModel: SUBAGENT_MODEL,
+    backgroundModel: BACKGROUND_MODEL,
+    maxContextTokens: MAX_CONTEXT_TOKENS,
+    maxOutputTokens: MAX_OUTPUT_TOKENS,
+    effort: EFFORT,
+    maxSteps: MAX_STEPS,
+    isPlanMode: IS_PLAN_MODE,
+    isArtifactWriter: IS_ARTIFACT_WRITER,
+    appendSystemPrompt,
+    instructionsPath,
+    disallowedTools: buildDisallowedTools(),
+    allowedTools: buildAllowedTools([
+      // The injected todo bridge must survive plan mode's allow-list.
+      `mcp__${TODO_SERVER_KEY}`,
+      ...(MCP_SERVERS || []).map((srv) => `mcp__${String(srv?.name || srv?.id || "").replace(/[^a-zA-Z0-9_-]/g, "_")}`).filter((k) => k !== "mcp__"),
+    ]),
+    agents: buildAgents(),
+    // Codex takes MCP servers from ctx via config.toml, not from
+    // session/new (sessionMcpServers is [] there) — so the ask_user
+    // bridge has to ride in here for it. Claude picks the same server
+    // up from buildAcpMcpServers() via session/new instead.
+    mcpServers:
+      HARNESS_ID === "codex"
+        ? [
+            ...(NEEDS_ASK_USER_MCP && existsSync(ASK_USER_MCP_PATH)
+              ? [{ name: ASK_USER_SERVER_KEY, command: process.execPath, args: [ASK_USER_MCP_PATH] }]
+              : []),
+            ...(!IS_ARTIFACT_WRITER && existsSync(TODO_MCP_PATH)
+              ? [{ name: TODO_SERVER_KEY, command: process.execPath, args: [TODO_MCP_PATH] }]
+              : []),
+            ...(MCP_SERVERS || []),
+          ]
+        : MCP_SERVERS || [],
+    maxBudgetUsd: MAX_BUDGET_USD,
+    additionalDirectories: savedAttachments.length > 0 ? [join(SCRATCH_DIR, "attachments")] : [],
+    resumeSessionId: SESSION_ID,
+    sessionId: SESSION_ID,
+    turnStartedAt: new Date().toISOString(),
+  };
+
+  // BYO login (bridge): the harness authenticates from its own config
+  // dir; no Gleap key is required or present.
+  const byoLogin = process.env.KAI_ACP_BYO_LOGIN === "1";
+  ctx.byoLogin = byoLogin;
+  const required = byoLogin ? null : HARNESS.requiredEnv(ctx);
+  if (required && !process.env[required]) {
+    emitSync({ type: "error", message: `acp-runner: ${required} is not set for harness ${HARNESS_ID}` });
+    process.exit(1);
+  }
+
+  // Gateway wire: interpose the local proxy when this model needs
+  // provider pinning / a compat shim / byte capture (KAI_WIRE_DEBUG=1).
+  let wire = null;
+  const wireDebug = process.env.KAI_WIRE_DEBUG === "1";
+  const engineSlug = ENGINE_MODEL || MODEL;
+  if (IS_GATEWAY_CLAUDE && needsWireProxy({ engineModel: engineSlug, providerOrders: PROVIDER_ORDERS, debug: wireDebug })) {
+    wire = await startWireProxy({
+      engineModel: engineSlug,
+      providerOrders: PROVIDER_ORDERS,
+      debug: wireDebug,
+      captureDir: join(SCRATCH_DIR, "wire"),
+      log: (event, data) => traceLog(event, data),
+    });
+    ctx.wireBaseUrl = wire.baseUrl;
+  }
+
+  const { cmd, args } = HARNESS.command(ctx);
+  const env = HARNESS.env(ctx);
+  traceLog("spawn", { harness: HARNESS_ID, cmd, model: MODEL, engineModel: ENGINE_MODEL, plan: IS_PLAN_MODE });
+  const child = spawn(cmd, args, { cwd: WORK_DIR, env, stdio: ["pipe", "pipe", "pipe"] });
+  child.stderr.on("data", (d) => traceLog("agent.stderr", { line: String(d).trim().slice(0, 2000) }));
+  const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+
+  const tracker = createUsageTracker(MODEL_PRICING);
+  let inFlight = true;
+  const stopHeartbeat = startHeartbeat(() => inFlight);
+  let conn;
+  let acpSessionId = null;
+  let cancelRequested = null;
+
+  const mcpServerIds = {};
+  for (const server of MCP_SERVERS || []) {
+    const key = String(server?.name || server?.id || "").replace(/[^a-zA-Z0-9_-]/g, "_");
+    if (key) mcpServerIds[key] = String(server.id || server.name || key);
+  }
+  // Plan files: pin the CLI's plansDirectory to scratch so the hand-off can
+  // read the newest plan even when ExitPlanMode only references it by path.
+  const plansDir = join(SCRATCH_DIR, "plans");
+  mkdirSync(plansDir, { recursive: true });
+  ctx.plansDir = plansDir;
+  // The CLI honours plansDirectory from settings.json but not reliably from
+  // the programmatic settings tier (2.1.241 wrote to <CLAUDE_CONFIG_DIR>/plans),
+  // so scan both and take the newest plan written during THIS turn.
+  const turnStartedMs = Date.now();
+  const readNewestPlan = () => {
+    let best = null;
+    for (const dir of [plansDir, join(configDir, "plans")]) {
+      try {
+        for (const f of readdirSync(dir)) {
+          if (!f.endsWith(".md")) continue;
+          const m = statSync(join(dir, f)).mtimeMs;
+          if (m >= turnStartedMs - 1000 && (!best || m > best.m)) best = { p: join(dir, f), m };
+        }
+      } catch {
+        /* dir absent */
+      }
+    }
+    try {
+      return best ? readFileSync(best.p, "utf8") : "";
+    } catch {
+      return "";
+    }
+  };
+  const mapper = createAcpMapper({
+    emit,
+    isPlanMode: IS_PLAN_MODE,
+    mcpServerIds,
+    readPlanFile: readNewestPlan,
+    allowTool: permissionPolicy({ isPlanMode: IS_PLAN_MODE, isArtifactWriter: IS_ARTIFACT_WRITER, workDir: WORK_DIR }),
+    onTurnShouldEnd: (reason) => {
+      cancelRequested = reason;
+      if (conn && acpSessionId) conn.cancel({ sessionId: acpSessionId }).catch(() => {});
+    },
+    onContextSnapshot: (model, tokens, window) => {
+      tracker.noteContextSnapshot(model ?? MODEL, tokens, window);
+    },
+  });
+
+  conn = new ClientSideConnection(
+    () => ({
+      async requestPermission(params) {
+        const optionId = mapper.handlePermission(params);
+        if (optionId == null) return { outcome: { outcome: "cancelled" } };
+        // No reject option offered but the policy says no → cancel this
+        // tool use only (the adapter treats cancelled as "not allowed").
+        if (optionId === "__reject__") return { outcome: { outcome: "cancelled" } };
+        return { outcome: { outcome: "selected", optionId } };
+      },
+      async sessionUpdate(params) {
+        mapper.handleUpdate(params.update);
+      },
+      // AskUserQuestion arrives as a form elicitation (claude-agent-acp only
+      // offers the tool when the client advertises `elicitation.form`). We
+      // never answer inline: the question ends the turn and the dashboard's
+      // answers come back as the next user message (same as today).
+      async createElicitation(params) {
+        mapper.handleElicitation(params);
+        return { action: "cancel" };
+      },
+    }),
+    stream,
+  );
+
+  const init = await conn.initialize({
+    protocolVersion: 1,
+    clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false, elicitation: { form: {} } },
+    clientInfo: { name: "kai-acp-runner", version: "0.1.0" },
+  });
+  traceLog("initialized", { agent: init.agentInfo, auth: (init.authMethods || []).map((m) => m.id) });
+
+  // API-key auth where the adapter asks for it (codex-acp advertises
+  // `api-key`; claude-agent-acp needs nothing with the key in env).
+  const apiKeyMethod = byoLogin ? null : (init.authMethods || []).find((m) => /api[-_]?key/i.test(String(m.id)));
+  if (apiKeyMethod) {
+    try {
+      await conn.authenticate({ methodId: apiKeyMethod.id });
+    } catch (err) {
+      traceLog("authenticate.failed", { method: apiKeyMethod.id, error: String(err?.message ?? err) });
+    }
+  }
+
+  const mcpServers = HARNESS.sessionMcpServers(ctx, buildAcpMcpServers());
+  // Resume only when the harness can actually find the prior session on
+  // disk — the FIRST turn of a session ships a session id too, and a
+  // resume against nothing fails after seconds of adapter retries.
+  const canResume =
+    !!SESSION_ID &&
+    !!init.agentCapabilities?.sessionCapabilities?.resume &&
+    (HARNESS.hasResumableSession ? HARNESS.hasResumableSession(ctx) : true);
+  let sessionResponse;
+  let resumed = false;
+  if (canResume) {
+    try {
+      sessionResponse = await conn.resumeSession({ sessionId: SESSION_ID, cwd: WORK_DIR, mcpServers, _meta: HARNESS.sessionMeta(ctx) });
+      resumed = !!sessionResponse;
+    } catch (err) {
+      traceLog("resume.failed", { error: String(err?.message ?? err) });
+    }
+  }
+  if (!sessionResponse) {
+    // The fallback must be a CLEAN start: `_meta` built with the resume id
+    // still in it makes claude-agent-acp re-run the query against the
+    // missing transcript and hang the session/new call indefinitely.
+    sessionResponse = await conn.newSession({
+      cwd: WORK_DIR,
+      mcpServers,
+      ...(ctx.additionalDirectories.length > 0 ? { additionalDirectories: ctx.additionalDirectories } : {}),
+      _meta: HARNESS.sessionMeta({ ...ctx, resumeSessionId: null }),
+    });
+  }
+  // codex-acp's `session/load` response is an empty object per the ACP
+  // spec (the id is the one we asked for) — reading `.sessionId` off it
+  // left every later call with `sessionId: undefined` → "Invalid params"
+  // and the whole resumed turn failed.
+  acpSessionId = sessionResponse.sessionId ?? (resumed ? SESSION_ID : null);
+  ctx.sessionId = acpSessionId;
+  traceLog("session", { sessionId: acpSessionId, resumed });
+
+  // Permission mode via ACP (`session/set_mode`). claude-agent-acp ignores
+  // `options.permissionMode` (it re-applies its own default after our
+  // options), so this is the call that actually puts the agent in plan /
+  // dontAsk / bypassPermissions. Verified on 0.70.0 + CLI 2.1.241.
+  const desiredMode = pickSessionMode(HARNESS.sessionModePreference?.(ctx) ?? [], sessionResponse.modes?.availableModes);
+  if (desiredMode) {
+    try {
+      await conn.setSessionMode({ sessionId: acpSessionId, modeId: desiredMode });
+      traceLog("session.mode", { modeId: desiredMode });
+    } catch (err) {
+      traceLog("session.mode.failed", { modeId: desiredMode, error: String(err?.message ?? err) });
+    }
+  }
+
+  // Artifact writers must leave the repo untouched: snapshot before,
+  // revert anything outside `.kai/` after (belt-and-braces under the
+  // permission rules — shell redirections can still write).
+  const baselines = IS_ARTIFACT_WRITER ? captureRepoBaselines(WORK_DIR) : null;
+  // Harnesses without a system-prompt channel (Cursor) get the persona as
+  // a prefix of the first prompt.
+  const promptPrefix = HARNESS.promptPrefix?.(ctx) || "";
+  const prompt = (promptPrefix ? `${promptPrefix}\n\n---\n\n` : "") + buildPrompt(savedAttachments);
+  let stopReason = "end_turn";
+  let promptError = null;
+  try {
+    const res = await conn.prompt({ sessionId: acpSessionId, prompt: [{ type: "text", text: prompt }] });
+    stopReason = res?.stopReason ?? "end_turn";
+  } catch (err) {
+    promptError = err;
+  }
+  inFlight = false;
+  stopHeartbeat?.();
+
+  const finished = mapper.finish();
+  if (IS_ARTIFACT_WRITER) {
+    try {
+      const reverted = revertRepoMutations(WORK_DIR, baselines);
+      if (reverted.length > 0) debugLog("artifact.revert", { repos: reverted });
+    } catch (err) {
+      traceLog("artifact.revert.failed", { error: err?.message ?? String(err) });
+    }
+  }
+
+  // Billing-grade usage from the harness transcript.
+  let usageRows = [];
+  let contextWindow = null;
+  try {
+    const collected = HARNESS.collectTurnUsage(ctx);
+    usageRows = collected.rows || [];
+    contextWindow = collected.contextWindow ?? null;
+    traceLog("usage.transcript", { path: collected.path, rows: usageRows.length });
+  } catch (err) {
+    traceLog("usage.transcript.failed", { error: String(err?.message ?? err) });
+  }
+  for (const row of aggregateUsageRows(usageRows)) {
+    tracker.record(
+      HARNESS.canonicalModel(ctx, row.model),
+      {
+        // Tracker convention: `inputTokens` = FRESH (uncached) input; it
+        // reports the combined figure itself.
+        inputTokens: row.inputTokens,
+        cachedInputTokens: row.cachedInputTokens,
+        cacheWriteInputTokens: row.cacheWriteInputTokens,
+        outputTokens: row.outputTokens,
+      },
+      { countTurn: true, aggregate: true },
+    );
+  }
+  const snap = lastRootContextSnapshot(usageRows);
+  if (snap) {
+    tracker.noteContextSnapshot(
+      HARNESS.canonicalModel(ctx, snap.model),
+      snap.tokens,
+      finished.usage?.size ?? contextWindow ?? MAX_CONTEXT_TOKENS ?? undefined,
+    );
+  }
+  // The adapter's USD is the CLI's own figure — authoritative on the
+  // native Anthropic wire only; gateway turns are priced from tokens.
+  if (typeof finished.usage?.costUsd === "number" && HARNESS_ID === "claude" && isNativeAnthropic(MODEL)) {
+    tracker.setProviderCostUsd(finished.usage.costUsd);
+  }
+
+  try {
+    child.kill("SIGTERM");
+  } catch {
+    /* already gone */
+  }
+
+  if (promptError && !cancelRequested) {
+    const diag = wire?.diagnostics();
+    if (diag) traceLog("wire.failure", diag);
+    emitSync({ type: "error", message: `acp-runner: ${String(promptError?.message ?? promptError)}` });
+    emitSync(tracker.buildResultEvent({ sessionId: acpSessionId }));
+    process.exit(1);
+  }
+  if (stopReason === "refusal") {
+    emit({ type: "error", message: "The model declined to continue (refusal)." });
+  }
+  const resultMessage = IS_PLAN_MODE && !finished.planEmitted && !finished.questionAsked ? finished.lastText : "";
+  if (IS_PLAN_MODE && resultMessage) emit({ type: "plan", message: resultMessage });
+  emitSync(tracker.buildResultEvent({ message: resultMessage, sessionId: acpSessionId }));
+  debugLog("done", { stopReason, cancelRequested, steps: usageRows.length });
+  process.exit(0);
+}
+
+main().catch((err) => {
+  emitSync({ type: "error", message: `acp-runner: ${String(err?.stack ?? err)}` });
+  process.exit(1);
+});