@bastani/atomic 0.5.23 → 0.5.24

package/dist/sdk/providers/claude.d.ts

@@ -196,6 +196,11 @@ export declare function extractAssistantText(msgs: ReadonlyArray<{
  * ```
  */
 export declare function claudeQuery(options: ClaudeQueryOptions): Promise<SessionMessage[]>;
+/**
+ * Merge two `disallowedTools` lists, preserving caller entries and appending
+ * any extras that aren't already present. Exported for unit testing.
+ */
+export declare function mergeDisallowedTools(existing: string[] | undefined, extras: string[]): string[];
 /**
  * Synthetic client wrapper for Claude stages.
  * Auto-starts the Claude CLI in the tmux pane during `start()`.
@@ -232,7 +237,7 @@ export declare class ClaudeSessionWrapper {
      * Send a prompt to Claude and wait for the response.
      *
      * The `_options` parameter exists for signature compatibility with
-     * {@link HeadlessClaudeSessionWrapper.query} (which forwards SDK options
+     * {@link HeadlessClaudeSessionWrapper#query} (which forwards SDK options
      * like `agent`, `permissionMode`, etc. to the Agent SDK). In the
      * interactive pane path these options don't apply — we're driving the
      * `claude` CLI binary, not the SDK — so they are silently ignored.
@@ -250,7 +255,7 @@ export declare class HeadlessClaudeClientWrapper {
      * Headless Claude stages don't pre-allocate a session — each `query()` call
      * to {@link HeadlessClaudeSessionWrapper} spawns a fresh Agent SDK run that
      * emits its own `session_id`. We still return an empty string here so the
-     * method signature matches {@link ClaudeClientWrapper.start}.
+     * method signature matches {@link ClaudeClientWrapper#start}.
      */
     start(): Promise<string>;
     stop(): Promise<void>;

package/dist/sdk/providers/claude.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../../src/sdk/providers/claude.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../../src/sdk/providers/claude.ts"],"names":[],"mappings":"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"}

package/dist/sdk/providers/opencode.d.ts

@@ -1,9 +1,25 @@
 /**
- * OpenCode workflow source validation.
+ * OpenCode workflow source validation + headless env helper.
  *
  * Checks that OpenCode workflow source files use the runtime-managed
- * `s.client` and `s.session` instead of manual SDK client creation.
+ * `s.client` and `s.session` instead of manual SDK client creation, and
+ * exports the `OPENCODE_CLIENT` override used to keep the interactive
+ * `question` tool out of headless stages.
  */
+/**
+ * Client identifier passed to SDK-spawned OpenCode subprocesses in headless
+ * stages.
+ *
+ * OpenCode only registers its interactive `question` tool when
+ * `OPENCODE_CLIENT` is one of `"app" | "cli" | "desktop"` (see
+ * `packages/opencode/src/tool/registry.ts` upstream — the `questionEnabled`
+ * gate). In unattended runs nobody is attached to answer, so we identify
+ * ourselves as `"sdk"` to keep the tool off the registry entirely. This
+ * mirrors how the upstream ACP integration excludes the tool by default
+ * (`packages/opencode/src/cli/cmd/acp.ts` sets `OPENCODE_CLIENT=acp`).
+ */
+export declare const HEADLESS_OPENCODE_CLIENT_ID = "sdk";
+export declare function withHeadlessOpencodeEnv<T>(fn: () => Promise<T>): Promise<T>;
 /**
  * Validate an OpenCode workflow source file for common mistakes.
  */

package/dist/sdk/providers/opencode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"opencode.d.ts","sourceRoot":"","sources":["../../../src/sdk/providers/opencode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,eAAO,MAAM,wBAAwB,+DAenC,CAAC"}
+{"version":3,"file":"opencode.d.ts","sourceRoot":"","sources":["../../../src/sdk/providers/opencode.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AAuBjD,wBAAsB,uBAAuB,CAAC,CAAC,EAC7C,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAmBZ;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB,+DAenC,CAAC"}

package/dist/sdk/runtime/executor.d.ts

@@ -219,5 +219,10 @@ export declare function watchCopilotSessionForHIL(session: CopilotHILSessionSurf
  * Exported for unit testing.
  */
 export declare function watchCopilotSessionForElicitation(session: CopilotHILSessionSurface, onHIL: (waiting: boolean) => void): () => void;
+/**
+ * Append tool names to a Copilot `excludedTools` list without duplicating
+ * entries the caller already supplied. Exported for unit testing.
+ */
+export declare function mergeExcludedTools(existing: string[] | undefined, extras: string[]): string[];
 export declare function runOrchestrator(): Promise<void>;
 //# sourceMappingURL=executor.d.ts.map

package/dist/sdk/runtime/executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/sdk/runtime/executor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/sdk/runtime/executor.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.5.23",
+  "version": "0.5.24",
   "description": "Configuration management CLI and SDK for coding agents",
   "type": "module",
   "license": "MIT",

package/src/sdk/providers/claude.ts

@@ -24,7 +24,7 @@ import {
   type SDKUserMessage,
   type Options as SDKOptions,
 } from "@anthropic-ai/claude-agent-sdk";
-import { sendKeysAndSubmit } from "../runtime/tmux.ts";
+import { sendKeysAndSubmit, waitForPaneReady } from "../runtime/tmux.ts";
 import { escBash } from "../runtime/executor.ts";
 import { watch, unlink, mkdir, writeFile } from "node:fs/promises";
 import { existsSync, writeFileSync } from "node:fs";
@@ -283,10 +283,18 @@ async function spawnClaudeWithPrompt(
     argvPrompt,
   ].join(" ");
 
+  // Wait for the pane's shell to finish init and activate its line editor
+  // (starship `❯` / bare zsh `>`). Sending keys before this point lets zsh's
+  // TCSAFLUSH on ZLE startup discard the buffered `\r`, so the command ends
+  // up displayed at the prompt but never submitted. This wait was dropped in
+  // eca267b0 alongside the post-submit pane-scrape — we only needed to drop
+  // the latter.
+  await waitForPaneReady(paneId, readyTimeoutMs);
+
   await sendKeysAndSubmit(paneId, cmd);
 
   // SDK-native readiness signal: wait for Claude to create its JSONL file
-  // at the known UUID path. No pane scraping, no paneLooksReady check.
+  // at the known UUID path.
   await waitForSessionFileAt(sessionId, readyTimeoutMs);
 }
 
@@ -912,6 +920,21 @@ export async function claudeQuery(options: ClaudeQueryOptions): Promise<SessionM
 // Synthetic wrappers — uniform s.client / s.session API for Claude stages
 // ---------------------------------------------------------------------------
 
+/**
+ * Merge two `disallowedTools` lists, preserving caller entries and appending
+ * any extras that aren't already present. Exported for unit testing.
+ */
+export function mergeDisallowedTools(
+  existing: string[] | undefined,
+  extras: string[],
+): string[] {
+  const merged = [...(existing ?? [])];
+  for (const tool of extras) {
+    if (!merged.includes(tool)) merged.push(tool);
+  }
+  return merged;
+}
+
 /**
  * Synthetic client wrapper for Claude stages.
  * Auto-starts the Claude CLI in the tmux pane during `start()`.
@@ -971,7 +994,7 @@ export class ClaudeSessionWrapper {
    * Send a prompt to Claude and wait for the response.
    *
    * The `_options` parameter exists for signature compatibility with
-   * {@link HeadlessClaudeSessionWrapper.query} (which forwards SDK options
+   * {@link HeadlessClaudeSessionWrapper#query} (which forwards SDK options
    * like `agent`, `permissionMode`, etc. to the Agent SDK). In the
    * interactive pane path these options don't apply — we're driving the
    * `claude` CLI binary, not the SDK — so they are silently ignored.
@@ -1004,7 +1027,7 @@ export class HeadlessClaudeClientWrapper {
    * Headless Claude stages don't pre-allocate a session — each `query()` call
    * to {@link HeadlessClaudeSessionWrapper} spawns a fresh Agent SDK run that
    * emits its own `session_id`. We still return an empty string here so the
-   * method signature matches {@link ClaudeClientWrapper.start}.
+   * method signature matches {@link ClaudeClientWrapper#start}.
    */
   async start(): Promise<string> {
     return "";
@@ -1041,18 +1064,40 @@ export class HeadlessClaudeSessionWrapper {
     prompt: string | AsyncIterable<SDKUserMessage>,
     options?: Partial<SDKOptions>,
   ): Promise<SessionMessage[]> {
+    // Auto-deny the `AskUserQuestion` tool in headless runs. Without this, the
+    // agent can call it and the SDK query will sit blocked forever since no
+    // human is attached to answer.
+    const sdkOpts = options ?? {};
+    const headlessSdkOpts: Partial<SDKOptions> = {
+      ...sdkOpts,
+      disallowedTools: mergeDisallowedTools(sdkOpts.disallowedTools, [
+        "AskUserQuestion",
+      ]),
+    };
+
     let sdkSessionId = "";
-    for await (const msg of sdkQuery({ prompt, options: options ?? {} })) {
-      if (msg.type === "result") {
-        sdkSessionId = String((msg as Record<string, unknown>).session_id ?? "");
+    try {
+      for await (const msg of sdkQuery({ prompt, options: options ?? {} })) {
+        if (msg.type === "result") {
+          sdkSessionId = String(
+            (msg as Record<string, unknown>).session_id ?? "",
+          );
+        }
       }
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(`Claude SDK query failed: ${detail}`);
     }
-    // Read the transcript to return native SessionMessage[]
-    if (sdkSessionId) {
-      this._lastSessionId = sdkSessionId;
-      return getSessionMessages(sdkSessionId, { dir: process.cwd() });
+    if (!sdkSessionId) {
+      throw new Error(
+        "Claude SDK query completed without a `result` message — " +
+          "likely a stream idle timeout, aborted request, or upstream API error. " +
+          "Set CLAUDE_ENABLE_STREAM_WATCHDOG=1 (and tune CLAUDE_STREAM_IDLE_TIMEOUT_MS / " +
+          "API_TIMEOUT_MS) so the CLI surfaces a concrete failure instead of exiting silently.",
+      );
     }
-    return [];
+    this._lastSessionId = sdkSessionId;
+    return getSessionMessages(sdkSessionId, { dir: process.cwd() });
   }
 
   async disconnect(): Promise<void> {}

package/src/sdk/providers/headless-hil-policy.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Tests for the headless human-in-the-loop (HIL) auto-deny policy.
+ *
+ * In unattended runs (headless stages), no human is attached to answer
+ * interactive questions from the agent. If the SDK's ask-user tool is
+ * not disabled, a query will sit blocked forever. These tests verify
+ * each provider's headless integration blocks the relevant tool.
+ */
+
+import { test, expect, describe } from "bun:test";
+import { mergeDisallowedTools } from "./claude.ts";
+import {
+  HEADLESS_OPENCODE_CLIENT_ID,
+  withHeadlessOpencodeEnv,
+} from "./opencode.ts";
+import { mergeExcludedTools } from "../runtime/executor.ts";
+
+// ---------------------------------------------------------------------------
+// Claude — disallowedTools: ["AskUserQuestion"]
+// ---------------------------------------------------------------------------
+
+describe("mergeDisallowedTools (Claude)", () => {
+  test("adds AskUserQuestion when no existing disallow list", () => {
+    expect(mergeDisallowedTools(undefined, ["AskUserQuestion"])).toEqual([
+      "AskUserQuestion",
+    ]);
+  });
+
+  test("preserves caller-supplied entries", () => {
+    expect(
+      mergeDisallowedTools(["Bash", "WebFetch"], ["AskUserQuestion"]),
+    ).toEqual(["Bash", "WebFetch", "AskUserQuestion"]);
+  });
+
+  test("does not duplicate AskUserQuestion if caller already disallowed it", () => {
+    expect(
+      mergeDisallowedTools(["AskUserQuestion", "Bash"], ["AskUserQuestion"]),
+    ).toEqual(["AskUserQuestion", "Bash"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Copilot — excludedTools: ["ask_user"]
+// ---------------------------------------------------------------------------
+
+describe("mergeExcludedTools (Copilot)", () => {
+  test("adds ask_user when no existing excluded list", () => {
+    expect(mergeExcludedTools(undefined, ["ask_user"])).toEqual(["ask_user"]);
+  });
+
+  test("preserves caller-supplied entries", () => {
+    expect(mergeExcludedTools(["bash"], ["ask_user"])).toEqual([
+      "bash",
+      "ask_user",
+    ]);
+  });
+
+  test("does not duplicate ask_user if caller already excluded it", () => {
+    expect(mergeExcludedTools(["ask_user", "bash"], ["ask_user"])).toEqual([
+      "ask_user",
+      "bash",
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// OpenCode — OPENCODE_CLIENT override excludes the question tool
+// ---------------------------------------------------------------------------
+//
+// Upstream (`packages/opencode/src/tool/registry.ts`) gates the question
+// tool on `["app","cli","desktop"].includes(OPENCODE_CLIENT)`. The SDK
+// spawns `opencode serve` via cross-spawn and inherits `process.env` at
+// fork time, so scoping the override around `createOpencode()` is
+// sufficient to keep the tool off the registry.
+
+describe("withHeadlessOpencodeEnv", () => {
+  test("sets OPENCODE_CLIENT to the headless id while fn runs", async () => {
+    const seen: string | undefined = await withHeadlessOpencodeEnv(async () =>
+      process.env.OPENCODE_CLIENT,
+    );
+    expect(seen).toBe(HEADLESS_OPENCODE_CLIENT_ID);
+  });
+
+  test("restores prior value when it was set before", async () => {
+    const before = process.env.OPENCODE_CLIENT;
+    process.env.OPENCODE_CLIENT = "preexisting";
+    try {
+      await withHeadlessOpencodeEnv(async () => {});
+      expect(process.env.OPENCODE_CLIENT).toBe("preexisting");
+    } finally {
+      if (before === undefined) delete process.env.OPENCODE_CLIENT;
+      else process.env.OPENCODE_CLIENT = before;
+    }
+  });
+
+  test("unsets the variable when it was unset before", async () => {
+    const before = process.env.OPENCODE_CLIENT;
+    delete process.env.OPENCODE_CLIENT;
+    try {
+      await withHeadlessOpencodeEnv(async () => {});
+      expect(
+        Object.prototype.hasOwnProperty.call(process.env, "OPENCODE_CLIENT"),
+      ).toBe(false);
+    } finally {
+      if (before === undefined) delete process.env.OPENCODE_CLIENT;
+      else process.env.OPENCODE_CLIENT = before;
+    }
+  });
+
+  test("restores prior value even when fn throws", async () => {
+    const before = process.env.OPENCODE_CLIENT;
+    process.env.OPENCODE_CLIENT = "preexisting";
+    try {
+      await expect(
+        withHeadlessOpencodeEnv(async () => {
+          throw new Error("boom");
+        }),
+      ).rejects.toThrow("boom");
+      expect(process.env.OPENCODE_CLIENT).toBe("preexisting");
+    } finally {
+      if (before === undefined) delete process.env.OPENCODE_CLIENT;
+      else process.env.OPENCODE_CLIENT = before;
+    }
+  });
+
+  test("is not one of the values that would enable the question tool", () => {
+    // Guard against accidental future edits: picking "cli", "app", or
+    // "desktop" here would silently re-enable the interactive question tool
+    // and make headless stages hang again.
+    expect(["app", "cli", "desktop"]).not.toContain(
+      HEADLESS_OPENCODE_CLIENT_ID,
+    );
+  });
+
+  test("concurrent uses do not leak the override after both unwind", async () => {
+    // Race regression: without a reference counter, the second concurrent
+    // stage reads the first's already-overridden value as its "prior" and
+    // restores "sdk" instead of the true original on unwind.
+    const before = process.env.OPENCODE_CLIENT;
+    delete process.env.OPENCODE_CLIENT;
+    try {
+      let releaseA!: () => void;
+      let releaseB!: () => void;
+      const waitA = new Promise<void>((r) => {
+        releaseA = r;
+      });
+      const waitB = new Promise<void>((r) => {
+        releaseB = r;
+      });
+
+      const a = withHeadlessOpencodeEnv(async () => {
+        await waitA;
+      });
+      const b = withHeadlessOpencodeEnv(async () => {
+        await waitB;
+      });
+
+      // Release A first, then B — the order that exposes the naive bug.
+      releaseA();
+      releaseB();
+      await Promise.all([a, b]);
+
+      expect(
+        Object.prototype.hasOwnProperty.call(process.env, "OPENCODE_CLIENT"),
+      ).toBe(false);
+    } finally {
+      if (before === undefined) delete process.env.OPENCODE_CLIENT;
+      else process.env.OPENCODE_CLIENT = before;
+    }
+  });
+});

package/src/sdk/providers/opencode.ts

@@ -1,12 +1,72 @@
 /**
- * OpenCode workflow source validation.
+ * OpenCode workflow source validation + headless env helper.
  *
  * Checks that OpenCode workflow source files use the runtime-managed
- * `s.client` and `s.session` instead of manual SDK client creation.
+ * `s.client` and `s.session` instead of manual SDK client creation, and
+ * exports the `OPENCODE_CLIENT` override used to keep the interactive
+ * `question` tool out of headless stages.
  */
 
 import { createProviderValidator } from "../types.ts";
 
+/**
+ * Client identifier passed to SDK-spawned OpenCode subprocesses in headless
+ * stages.
+ *
+ * OpenCode only registers its interactive `question` tool when
+ * `OPENCODE_CLIENT` is one of `"app" | "cli" | "desktop"` (see
+ * `packages/opencode/src/tool/registry.ts` upstream — the `questionEnabled`
+ * gate). In unattended runs nobody is attached to answer, so we identify
+ * ourselves as `"sdk"` to keep the tool off the registry entirely. This
+ * mirrors how the upstream ACP integration excludes the tool by default
+ * (`packages/opencode/src/cli/cmd/acp.ts` sets `OPENCODE_CLIENT=acp`).
+ */
+export const HEADLESS_OPENCODE_CLIENT_ID = "sdk";
+
+/**
+ * Run `fn` with `process.env.OPENCODE_CLIENT` set to
+ * `HEADLESS_OPENCODE_CLIENT_ID`, restoring the prior value afterward. The
+ * SDK spawns `opencode serve` via `cross-spawn` and inherits the parent's
+ * env at spawn time, so scoping the override around `createOpencode(...)`
+ * is enough to influence the subprocess without leaking into later work.
+ *
+ * A reference counter keeps the override in place while any concurrent
+ * headless spawn is still running — otherwise two parallel stages can
+ * race, and the second one restores the first one's already-overridden
+ * value as if it were the original. The captured "pre-override" state is
+ * only read on the outermost entry and only replayed on the outermost
+ * exit.
+ *
+ * Prior value handling is explicit so we distinguish "was unset" from
+ * "was set to empty string".
+ */
+let headlessEnvDepth = 0;
+let headlessEnvHadPrior = false;
+let headlessEnvPrior: string | undefined;
+
+export async function withHeadlessOpencodeEnv<T>(
+  fn: () => Promise<T>,
+): Promise<T> {
+  if (headlessEnvDepth === 0) {
+    headlessEnvHadPrior = Object.prototype.hasOwnProperty.call(
+      process.env,
+      "OPENCODE_CLIENT",
+    );
+    headlessEnvPrior = process.env.OPENCODE_CLIENT;
+  }
+  headlessEnvDepth++;
+  try {
+    process.env.OPENCODE_CLIENT = HEADLESS_OPENCODE_CLIENT_ID;
+    return await fn();
+  } finally {
+    headlessEnvDepth--;
+    if (headlessEnvDepth === 0) {
+      if (headlessEnvHadPrior) process.env.OPENCODE_CLIENT = headlessEnvPrior;
+      else delete process.env.OPENCODE_CLIENT;
+    }
+  }
+}
+
 /**
  * Validate an OpenCode workflow source file for common mistakes.
  */

package/src/sdk/runtime/executor.ts

@@ -53,6 +53,7 @@ import {
   HeadlessClaudeClientWrapper,
   HeadlessClaudeSessionWrapper,
 } from "../providers/claude.ts";
+import { withHeadlessOpencodeEnv } from "../providers/opencode.ts";
 import { OrchestratorPanel } from "./panel.tsx";
 import { GraphFrontierTracker } from "./graph-inference.ts";
 import { buildSnapshot, writeSnapshot } from "./status-writer.ts";
@@ -1176,6 +1177,21 @@ interface SharedRunnerState {
   failedRegistry: Set<string>;
 }
 
+/**
+ * Append tool names to a Copilot `excludedTools` list without duplicating
+ * entries the caller already supplied. Exported for unit testing.
+ */
+export function mergeExcludedTools(
+  existing: string[] | undefined,
+  extras: string[],
+): string[] {
+  const merged = [...(existing ?? [])];
+  for (const tool of extras) {
+    if (!merged.includes(tool)) merged.push(tool);
+  }
+  return merged;
+}
+
 /**
  * Create the provider-specific client and session for a stage.
  * Called by the session runner after server readiness is confirmed.
@@ -1217,10 +1233,22 @@ async function initProviderClientAndSession<A extends AgentType>(
         ? new CopilotClient({ ...copilotClientOpts })
         : new CopilotClient({ ...copilotClientOpts, cliUrl: serverUrl });
       await client.start();
-      const session = await client.createSession({
+      // In headless stages, add `ask_user` to the session's excludedTools so
+      // the agent cannot call the interactive question tool — there is no
+      // human attached to answer and the SDK would otherwise sit blocked.
+      const sessionConfig = {
         onPermissionRequest: approveAll,
         ...copilotSessionOpts,
-      });
+        ...(headless
+          ? {
+              excludedTools: mergeExcludedTools(
+                copilotSessionOpts.excludedTools,
+                ["ask_user"],
+              ),
+            }
+          : {}),
+      };
+      const session = await client.createSession(sessionConfig);
       if (!headless) {
         await client.setForegroundSessionId(session.sessionId);
       }
@@ -1230,13 +1258,22 @@ async function initProviderClientAndSession<A extends AgentType>(
       const ocSessionOpts = sessionOpts as StageSessionOptions<"opencode">;
       if (headless) {
         const { createOpencode } = await import("@opencode-ai/sdk/v2");
-        const oc = await createOpencode({ port: 0 });
-        const sessionResult = await oc.client.session.create(ocSessionOpts);
-        return {
-          client: oc.client,
-          session: sessionResult.data!,
-          cleanup: () => oc.server.close(),
-        } as Result;
+        // Scope OPENCODE_CLIENT=sdk around the SDK spawn so the subprocess
+        // inherits it at fork time. OpenCode only registers its interactive
+        // `question` tool when OPENCODE_CLIENT is "app"/"cli"/"desktop", so
+        // identifying as "sdk" keeps the tool out of the registry entirely
+        // — otherwise an unattended stage can hang forever on question.asked
+        // (the tool's execute calls Question.ask directly and never consults
+        // the session permission ruleset).
+        return await withHeadlessOpencodeEnv(async () => {
+          const oc = await createOpencode({ port: 0 });
+          const sessionResult = await oc.client.session.create(ocSessionOpts);
+          return {
+            client: oc.client,
+            session: sessionResult.data!,
+            cleanup: () => oc.server.close(),
+          } as Result;
+        });
       }
       const { createOpencodeClient } = await import("@opencode-ai/sdk/v2");
       const ocClientOpts = clientOpts as StageClientOptions<"opencode">;
@@ -1622,10 +1659,14 @@ function createSessionRunner(
       // session id. This is what workflows pass to `s.save(s.sessionId)`
       // to disambiguate their own transcript when several sessions run
       // in parallel under the same workflow.
-      const providerSessionId = resolveProviderSessionId(
-        shared.agent,
-        providerSession,
-      );
+      //
+      // Exposed as a getter (not a snapshot) because headless Claude stages
+      // don't know their SDK-assigned `session_id` until the first `query()`
+      // completes — `HeadlessClaudeSessionWrapper._lastSessionId` starts empty
+      // and is populated when the SDK emits a `result` event. A snapshot
+      // captured at stage creation would leave `s.sessionId === ""` forever,
+      // so `s.save(s.sessionId)` would always throw "empty Claude session id"
+      // even though the query completed successfully.
       const ctx: SessionContext = {
         client: providerClient,
         session: providerSession,
@@ -1633,7 +1674,9 @@ function createSessionRunner(
         agent: shared.agent,
         sessionDir,
         paneId,
-        sessionId: providerSessionId,
+        get sessionId() {
+          return resolveProviderSessionId(shared.agent, providerSession);
+        },
         save,
         transcript: transcriptFn,
         getMessages: getMessagesFn,