akm-cli 0.9.0-rc.1 → 0.9.0-rc.2

package/dist/integrations/harnesses/opencode-sdk/sdk-runner.js

@@ -6,10 +6,10 @@
  *
  * Uses the embedded `@opencode-ai/sdk` instead of `Bun.spawn`. Requires no
  * agent CLI binary to be installed. The user provides an OpenAI-compatible
- * endpoint (or inherits from config.llm) for the SDK.
+ * endpoint (or inherits from the selected fallback LLM engine) for the SDK.
  *
  * This is the runtime surface of the {@link OpencodeSdkHarness} (`id =
- * 'opencode-sdk'`). It is the dispatch path for `sdkMode` profiles; it exposes
+ * 'opencode-sdk'`). It is the dispatch path for SDK runner specs; it exposes
  * no native session logs of its own (`capabilities.sessionLogs = false`).
  *
  * ## Per-call cwd and env (redesign addendum R2, open seam decision 1)
@@ -29,19 +29,12 @@
  *
  *   - **env is PER-SERVER (keyed registry).** The SDK exposes NO per-call or
  *     per-session env surface; the only way env reaches tool child processes
- *     is the `opencode serve` process environment, which
- *     `createOpencodeServer` copies from `process.env` **synchronously**
- *     (its `spawn` call runs before its first `await`, so the snapshot is
- *     taken inside our call frame). {@link getOrStartServer} therefore keys
- *     servers by a hash of the FULL env binding entries (keys AND values —
- *     two bindings that share keys but differ in values must not share a
- *     server), overlays the bindings onto `process.env` for exactly the
- *     synchronous prefix of the `createOpencode` call, and restores the
- *     previous values before awaiting. JavaScript's single-threaded event
- *     loop makes that overlay window atomic: no concurrently-running akm
- *     code can observe the mutated environment. Units with the same
- *     bindings share one server; units with none share the default server
- *     (byte-identical to the pre-R2 singleton behavior).
+ *     is the `opencode serve` process environment. {@link getOrStartServer}
+ *     snapshots and materializes the complete child environment for each
+ *     dispatch, passes it directly to the managed spawn (never mutating
+ *     `process.env`), and hashes that exact canonical environment for registry
+ *     identity. Identical child material shares one server; any material
+ *     difference receives a separate server.
  *
  * This is what removed the workflow engine's `env_unsupported` hard-fail for
  * the sdk runner: injection genuinely reaches the child, because tool
@@ -50,9 +43,9 @@
  * Registry hygiene (peer-review fixes):
  *
  *   - **Ports.** `createOpencodeServer` binds a FIXED default port (4096),
- *     so coexisting registry entries would contend for the same bind. The
- *     default key keeps the SDK default; every env-keyed entry is started on
- *     its own OS-assigned free port (see {@link startServer}).
+ *     so coexisting registry entries would contend for the same bind. Every
+ *     entry is started on its own reserved OS-assigned port (see
+ *     {@link startServer}).
  *   - **Shutdown.** {@link closeServer} closes resolved servers
  *     SYNCHRONOUSLY — it runs from `process.once('exit')`, where Bun never
  *     drains microtasks, so a `.then()`-based close would orphan every
@@ -64,7 +57,8 @@
  * cannot free a process the child is keeping alive (a deadlock that hangs the
  * caller after an otherwise-successful run). The registry is therefore drained
  * PROACTIVELY at the end of a dispatching command: the workflow engine calls
- * `disposeDispatchResources()` (→ {@link closeServer}) in its run `finally`.
+ * `disposeDispatchResources()` (→ {@link closeServer}) in composition-root and
+ * workflow `finally` blocks.
  * The `process.once('exit')` hook stays as the last-resort backstop for paths
  * that never reach that drain.
  *
@@ -84,17 +78,16 @@
  *     ({@link SERVER_KILL_GRACE_MS}) that escalates to SIGKILL and is cleared
  *     on cooperative exit, so stubborn children cannot survive parent exit and
  *     stale timers cannot signal a reused PID;
- *   - the spawn (and its `process.env` snapshot) stays in the SYNCHRONOUS
- *     prefix of the factory call, preserving the env-overlay contract above.
+ *   - the spawn receives the immutable per-dispatch environment directly, so
+ *     asynchronous factory setup cannot race a temporary process-wide overlay.
  */
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { resolveSecret } from "../../../core/config/config.js";
 import { DEFAULT_AGENT_TIMEOUT_MS } from "../../agent/config.js";
 import { resolveModel } from "../../agent/model-aliases.js";
-// Server registry — one server per env-binding signature, started lazily and
-// reused across calls. The default (no env bindings) key is "" and behaves
-// exactly like the pre-R2 process-wide singleton.
+// Server registry — one server per complete server-material signature. Caller
+// deadlines race the shared promise independently; they never become startup
+// configuration inherited by later callers.
 const _servers = new Map();
 // Resolved servers by registry key, mirrored from `_servers` as each start
 // promise settles. This exists so closeServer() can close started servers
@@ -106,6 +99,8 @@ const _resolvedServers = new Map();
 // tracked so two coexisting servers in this process can never be assigned
 // the same port.
 const _serverPorts = new Map();
+// Serializes probe-and-reserve so concurrent starts cannot claim one port.
+let _portAllocationTail = Promise.resolve();
 /** The port `createOpencodeServer` binds when none is passed (SDK 1.2.20). */
 const DEFAULT_SDK_PORT = 4096;
 // Test override: when set, every call uses this server (all keys) and no real
@@ -127,11 +122,9 @@ export function __setTestServer(server) {
 /**
  * Test-only seam: replace the `createOpencode` factory so the env-keyed
  * server registry (module doc, *Per-call cwd and env*) can be exercised
- * without the real SDK. The fake MUST read whatever `process.env` state it
- * cares about in its SYNCHRONOUS prefix — exactly like the real
- * `createOpencodeServer`, whose `spawn` snapshot happens before its first
- * await — because the runner restores the env overlay as soon as the factory
- * call returns its promise. Pass `null` to clear.
+ * without the real SDK. The complete child environment is supplied as
+ * `options.env`, so async factories observe the same immutable values as the
+ * production spawn. Pass `null` to clear.
  */
 export function __setServerFactory(factory) {
     _serverFactory = factory;
@@ -145,44 +138,38 @@ export function __setServerFactory(factory) {
  * `opencode serve` children (leaking processes AND keeping their ports
  * bound for the next invocation).
  */
-export function closeServer() {
-    for (const [key, pending] of _servers) {
+export async function closeServer() {
+    const closes = [];
+    for (const [key, entry] of _servers) {
         const resolved = _resolvedServers.get(key);
         if (resolved) {
             // Synchronous close — safe from the 'exit' hook.
             try {
-                resolved.server.close();
+                closes.push(Promise.resolve(resolved.server.close()));
             }
             catch {
                 /* ignore */
             }
         }
         else {
-            // Still starting: close on arrival. This branch can never complete
-            // inside the 'exit' hook (no microtasks there), but it keeps
-            // mid-start test teardown leak-free.
-            pending
-                .then((s) => {
-                try {
-                    s.server.close();
-                }
-                catch {
-                    /* ignore */
-                }
-            })
-                .catch(() => { });
+            // Still starting: cancel the real managed spawn immediately. A custom
+            // factory may ignore the signal; the registry settlement handler closes
+            // any late result without awaiting it and pinning shutdown indefinitely.
+            entry.controller.abort();
         }
     }
     _servers.clear();
     _resolvedServers.clear();
     _serverPorts.clear();
     try {
-        _testServer?.server.close();
+        if (_testServer)
+            closes.push(Promise.resolve(_testServer.server.close()));
     }
     catch {
         /* ignore */
     }
     _testServer = null;
+    await Promise.allSettled(closes);
 }
 /**
  * Convert an `AgentDispatchRequest.tools` policy into the SDK's tool-allowlist
@@ -241,12 +228,14 @@ function toolsToSdkAllowlist(tools) {
  * and config-root alias tables apply here.
  */
 export function buildSdkConfig(profile, llmConfig) {
-    // Resolve endpoint and model: profile fields take precedence over config.llm
-    const endpoint = profile.endpoint ?? llmConfig?.endpoint;
-    const apiKey = resolveSecret(profile.apiKey ?? llmConfig?.apiKey);
-    const model = profile.model
-        ? resolveModel(profile.model, "opencode-sdk", profile.modelAliases, profile.globalModelAliases)
+    const endpoint = llmConfig?.endpoint;
+    const apiKey = llmConfig?.apiKey;
+    const profileModel = profile.model
+        ? profile.modelIsExact
+            ? profile.model
+            : resolveModel(profile.model, "opencode-sdk", profile.modelAliases, profile.globalModelAliases)
         : undefined;
+    const model = profileModel ?? llmConfig?.model;
     const sdkConfig = {};
     if (model)
         sdkConfig.model = model;
@@ -256,48 +245,74 @@ export function buildSdkConfig(profile, llmConfig) {
             "akm-custom": {
                 npm: "@ai-sdk/openai-compatible",
                 options: {
-                    baseURL: endpoint?.replace(/\/chat\/completions$/, "").replace(/\/$/, ""),
+                    baseURL: canonicalProviderBase(endpoint) ?? undefined,
                     ...(apiKey ? { apiKey } : {}),
                 },
             },
         };
-        // Use the custom provider's model if not already qualified
-        if (model && !model.includes("/")) {
-            sdkConfig.model = `akm-custom/${model}`;
-        }
+        // The first path segment selects the OpenCode provider. Model IDs may
+        // themselves contain slashes, but still belong to this custom endpoint.
+        if (model)
+            sdkConfig.model = model.startsWith("akm-custom/") ? model : `akm-custom/${model}`;
     }
     return sdkConfig;
 }
-/**
- * Stable key for the env-keyed server registry: sha256 over the SORTED
- * binding entries (keys AND values — see module doc), "" when no bindings.
- */
-function envServerKey(env) {
-    if (!env || Object.keys(env).length === 0)
-        return "";
-    const entries = Object.entries(env).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-    return createHash("sha256").update(JSON.stringify(entries)).digest("hex");
+/** Digest the executable and exact environment received by the child. */
+function serverRegistryKey(profile, env) {
+    const material = { bin: profile.bin, env };
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalize(material)))
+        .digest("hex");
 }
-/**
- * Overlay `env` onto `process.env`, returning a restore function. The
- * overlay is intended to live only for the SYNCHRONOUS prefix of the server
- * factory call (module doc): mutation → factory() → restore happens in one
- * uninterruptible event-loop turn, so no other code observes it.
- */
-function overlayProcessEnv(env) {
-    const previous = new Map();
-    for (const [key, value] of Object.entries(env)) {
-        previous.set(key, process.env[key]);
-        process.env[key] = value;
+function buildServerEnv(profile, config, bindings, envSource) {
+    const env = {};
+    const inheritedNames = new Set([
+        "HOME",
+        "PATH",
+        "USER",
+        "LANG",
+        "LC_ALL",
+        "TERM",
+        "TMPDIR",
+        "SYSTEMROOT",
+        "COMSPEC",
+        "PATHEXT",
+        "WINDIR",
+        "TEMP",
+        "TMP",
+        ...(profile.envPassthrough ?? []),
+    ]);
+    for (const key of inheritedNames) {
+        const value = envSource[key];
+        if (value !== undefined)
+            env[key] = value;
     }
-    return () => {
-        for (const [key, prior] of previous) {
-            if (prior === undefined)
-                delete process.env[key];
-            else
-                process.env[key] = prior;
-        }
-    };
+    for (const [key, value] of Object.entries(bindings ?? {}))
+        env[key] = value;
+    env.OPENCODE_CONFIG_CONTENT = JSON.stringify(config);
+    return env;
+}
+function canonicalProviderBase(endpoint) {
+    if (!endpoint)
+        return null;
+    try {
+        const url = new URL(endpoint);
+        url.pathname = url.pathname.replace(/\/chat\/completions$/, "").replace(/\/$/, "");
+        return url.toString().replace(/\/$/, "");
+    }
+    catch {
+        return endpoint.replace(/\/chat\/completions$/, "").replace(/\/$/, "");
+    }
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, child]) => [key, canonicalize(child)]));
+    }
+    return value;
 }
 /**
  * Ask the OS for a currently-free localhost port (bind :0, read the assigned
@@ -307,33 +322,44 @@ function overlayProcessEnv(env) {
  * acceptable here because the failure mode is a clean `spawn_failed` on the
  * next dispatch, not corruption.
  */
-async function allocateFreePort() {
-    const { createServer } = await import("node:net");
-    const taken = new Set(_serverPorts.values());
-    for (let attempt = 0; attempt < 10; attempt++) {
-        const port = await new Promise((resolve, reject) => {
-            const probe = createServer();
-            probe.unref();
-            probe.on("error", reject);
-            probe.listen(0, "127.0.0.1", () => {
-                const address = probe.address();
-                probe.close(() => {
-                    if (address && typeof address === "object")
-                        resolve(address.port);
-                    else
-                        reject(new Error("could not read the probe socket's port"));
+async function allocateFreePort(registryKey) {
+    let release;
+    const previous = _portAllocationTail;
+    _portAllocationTail = new Promise((resolve) => {
+        release = resolve;
+    });
+    await previous;
+    try {
+        const { createServer } = await import("node:net");
+        const taken = new Set(_serverPorts.values());
+        for (let attempt = 0; attempt < 10; attempt++) {
+            const port = await new Promise((resolve, reject) => {
+                const probe = createServer();
+                probe.unref();
+                probe.on("error", reject);
+                probe.listen(0, "127.0.0.1", () => {
+                    const address = probe.address();
+                    probe.close(() => {
+                        if (address && typeof address === "object")
+                            resolve(address.port);
+                        else
+                            reject(new Error("could not read the probe socket's port"));
+                    });
                 });
             });
-        });
-        if (port !== DEFAULT_SDK_PORT && !taken.has(port))
-            return port;
+            if (port !== DEFAULT_SDK_PORT && !taken.has(port)) {
+                _serverPorts.set(registryKey, port);
+                return port;
+            }
+        }
+        throw new Error("could not allocate a free port for the OpenCode SDK server");
+    }
+    finally {
+        release();
     }
-    throw new Error("could not allocate a free port for the OpenCode SDK server");
 }
 /** Grace between SIGTERM and SIGKILL when closing a managed server child. */
 const SERVER_KILL_GRACE_MS = 2_000;
-/** How long the managed spawn waits for the server's listening handshake. */
-const SERVER_START_TIMEOUT_MS = 5_000;
 // Test seam: override the argv used to spawn the server child ("opencode"
 // plus serve flags by default) so the managed-spawn lifecycle (handshake,
 // unref, SIGTERM→SIGKILL escalation) is testable without the real binary.
@@ -345,7 +371,7 @@ export function __setServeCommand(argv) {
 /**
  * Spawn-owning replacement for the SDK's `createOpencode` (module doc,
  * *Managed server spawn*). Mirrors `createOpencodeServer`'s contract — the
- * `spawn` (and its `process.env` snapshot) happens in the SYNCHRONOUS prefix,
+ * `spawn` receives the factory's immutable environment directly,
  * `OPENCODE_CONFIG_CONTENT` carries the config, the handshake parses the
  * "opencode server listening on <url>" line — but manages the child so its
  * handle can never pin akm's event loop:
@@ -359,11 +385,9 @@ async function createManagedOpencode(options) {
         throw new Error("OpenCode SDK not available. Install @opencode-ai/sdk or configure a CLI agent instead.");
     }));
     const port = options.port ?? DEFAULT_SDK_PORT;
-    const argv = _serveCommand ?? ["opencode", "serve", "--hostname=127.0.0.1", `--port=${port}`];
-    // Synchronous prefix: the env snapshot (incl. any binding overlay in the
-    // caller's frame) is taken HERE, before the first await below.
+    const argv = _serveCommand ?? [options.bin ?? "opencode", "serve", "--hostname=127.0.0.1", `--port=${port}`];
     const proc = spawn(argv[0], argv.slice(1), {
-        env: { ...process.env, OPENCODE_CONFIG_CONTENT: JSON.stringify(options.config ?? {}) },
+        env: options.env,
         stdio: ["ignore", "pipe", "pipe"],
     });
     let closeStarted = false;
@@ -405,17 +429,13 @@ async function createManagedOpencode(options) {
     };
     const url = await new Promise((resolve, reject) => {
         let output = "";
-        let timer;
         let settled = false;
         const cleanupStartup = () => {
-            if (timer !== undefined) {
-                clearTimeout(timer);
-                timer = undefined;
-            }
             proc.stdout?.off("data", onStdoutData);
             proc.stderr?.off("data", onStderrData);
             proc.off("exit", onExit);
             proc.off("error", onError);
+            options.startupSignal.removeEventListener("abort", onAbort);
         };
         const fail = (err) => {
             if (settled)
@@ -459,13 +479,15 @@ async function createManagedOpencode(options) {
         const onError = (err) => {
             fail(err instanceof Error ? err : new Error(String(err)));
         };
-        timer = setTimeout(() => {
-            fail(new Error(`Timeout waiting for the OpenCode server to start after ${SERVER_START_TIMEOUT_MS}ms`));
-        }, SERVER_START_TIMEOUT_MS);
+        const onAbort = () => fail(new Error("OpenCode server startup cancelled because no callers are waiting"));
         proc.stdout?.on("data", onStdoutData);
         proc.stderr?.on("data", onStderrData);
         proc.on("exit", onExit);
         proc.on("error", onError);
+        if (options.startupSignal.aborted)
+            onAbort();
+        else
+            options.startupSignal.addEventListener("abort", onAbort, { once: true });
     });
     // Handshake done: from here on the child must never hold akm open. Its
     // lifetime is managed explicitly (closeServer → closeManaged), not by the
@@ -475,77 +497,83 @@ async function createManagedOpencode(options) {
     proc.unref();
     return { client: createOpencodeClient({ baseUrl: url }), server: { close: closeManaged } };
 }
-async function startServer(profile, llmConfig, env, registryKey) {
+async function startServer(profile, sdkConfig, env, registryKey, startupSignal) {
     const factory = _serverFactory ?? createManagedOpencode;
-    const sdkConfig = buildSdkConfig(profile, llmConfig);
-    const options = Object.keys(sdkConfig).length > 0 ? { config: sdkConfig } : {};
-    // Port discipline: `createOpencodeServer` defaults to a FIXED port (4096),
-    // so two coexisting servers — the default one plus any env-keyed one —
-    // would contend for the same bind and the second start would fail. The
-    // default key keeps the SDK default (byte-identical to the pre-R2
-    // singleton); every other registry entry gets its own OS-assigned free
-    // port, allocated BEFORE the env overlay below (allocation awaits).
-    if (registryKey !== "") {
-        const port = await allocateFreePort();
-        _serverPorts.set(registryKey, port);
-        options.port = port;
-    }
-    // Env injection (module doc): the SDK's createOpencodeServer snapshots
-    // process.env synchronously (its spawn precedes its first await), so the
-    // overlay only needs to survive the factory's synchronous prefix. Restore
-    // BEFORE awaiting, so nothing else ever runs under the mutated env.
-    let pending;
-    if (env && Object.keys(env).length > 0) {
-        const restore = overlayProcessEnv(env);
-        try {
-            pending = factory(options);
-        }
-        finally {
-            restore();
-        }
-    }
-    else {
-        pending = factory(options);
-    }
-    const server = await pending;
+    const options = {
+        bin: profile.bin,
+        ...(Object.keys(sdkConfig).length > 0 ? { config: sdkConfig } : {}),
+        env,
+        startupSignal,
+    };
+    // Every cached server receives a separately reserved port. This avoids both
+    // inter-entry contention and collisions with an unrelated process on 4096.
+    options.port = await allocateFreePort(registryKey);
+    if (startupSignal.aborted)
+        throw new Error("OpenCode server startup cancelled because no callers are waiting");
+    const server = await factory(options);
     if (!server)
         throw new Error("Failed to initialise OpenCode SDK server.");
     if (!_exitHookInstalled) {
         _exitHookInstalled = true;
         process.once("exit", () => {
-            closeServer();
+            void closeServer();
         });
     }
     return server;
 }
 /**
- * Get (or lazily start) the server for this call's env bindings. Servers are
- * keyed by {@link envServerKey}; concurrent callers of the same key share one
+ * Get (or lazily start) the server for this call's complete server material.
+ * Concurrent callers of the same key share one
  * start (the registry stores the in-flight promise). A failed start is
  * evicted so the next call can retry instead of caching the error forever.
  */
-async function getOrStartServer(profile, llmConfig, env) {
+function getOrStartServer(profile, llmConfig, env, envSource = process.env) {
     if (_testServer)
-        return _testServer;
-    const key = envServerKey(env);
-    let pending = _servers.get(key);
-    if (!pending) {
-        pending = startServer(profile, llmConfig, env, key);
-        _servers.set(key, pending);
-        pending.then((server) => {
-            // Mirror into the synchronously-closable registry (see closeServer)
-            // — but only while this start is still the live entry (closeServer
-            // may have cleared the registry mid-start).
-            if (_servers.get(key) === pending)
+        return { promise: Promise.resolve(_testServer), release() { } };
+    const sdkConfig = buildSdkConfig(profile, llmConfig);
+    const serverEnv = buildServerEnv(profile, sdkConfig, env, envSource);
+    const key = serverRegistryKey(profile, serverEnv);
+    let entry = _servers.get(key);
+    if (!entry) {
+        const controller = new AbortController();
+        entry = {
+            promise: startServer(profile, sdkConfig, serverEnv, key, controller.signal),
+            controller,
+            waiters: 0,
+        };
+        const started = entry;
+        _servers.set(key, started);
+        started.promise.then((server) => {
+            if (_servers.get(key) === started) {
+                started.server = server;
                 _resolvedServers.set(key, server);
+            }
+            else {
+                void server.server.close();
+            }
         }, () => {
-            if (_servers.get(key) === pending) {
+            if (_servers.get(key) === started) {
                 _servers.delete(key);
                 _serverPorts.delete(key);
             }
         });
     }
-    return pending;
+    entry.waiters++;
+    let released = false;
+    return {
+        promise: entry.promise,
+        release() {
+            if (released)
+                return;
+            released = true;
+            entry.waiters--;
+            if (entry.waiters === 0 && !entry.server && _servers.get(key) === entry) {
+                _servers.delete(key);
+                _serverPorts.delete(key);
+                entry.controller.abort();
+            }
+        },
+    };
 }
 /**
  * Extract best-effort token usage from a prompt response. Only numeric
@@ -572,10 +600,20 @@ const SDK_SESSION_DELETE_TIMEOUT_MS = 5_000;
 async function raceSdkOperation(operation, opts) {
     let timer;
     let onAbort;
+    let raceFinished = false;
     const racers = [operation];
+    void operation.then((value) => {
+        if (raceFinished && opts.onLateSettle)
+            void Promise.resolve(opts.onLateSettle({ status: "fulfilled", value })).catch(() => { });
+    }, (reason) => {
+        if (raceFinished && opts.onLateSettle)
+            void Promise.resolve(opts.onLateSettle({ status: "rejected", reason })).catch(() => { });
+    });
     if (opts.timeoutMs !== null) {
         racers.push(new Promise((resolve) => {
             timer = opts.setTimeoutFn(() => resolve(SDK_OPERATION_TIMED_OUT), opts.timeoutMs ?? 0);
+            if (typeof timer !== "number")
+                timer.unref?.();
         }));
     }
     if (opts.signal) {
@@ -591,6 +629,7 @@ async function raceSdkOperation(operation, opts) {
         return racers.length === 1 ? await operation : await Promise.race(racers);
     }
     finally {
+        raceFinished = true;
         if (timer !== undefined)
             opts.clearTimeoutFn(timer);
         if (opts.signal && onAbort)
@@ -621,6 +660,11 @@ async function deleteSessionBestEffort(client, sessionId, query, setTimeoutFn, c
 }
 export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
     const start = Date.now();
+    const timeoutMs = opts.timeoutMs !== undefined ? opts.timeoutMs : DEFAULT_AGENT_TIMEOUT_MS;
+    const deadline = timeoutMs === null ? null : start + timeoutMs;
+    const remainingTimeoutMs = () => (deadline === null ? null : Math.max(0, deadline - Date.now()));
+    const setTimeoutImpl = opts.setTimeoutFn ?? setTimeout;
+    const clearTimeoutImpl = opts.clearTimeoutFn ?? clearTimeout;
     if (opts.signal?.aborted) {
         return {
             ok: false,
@@ -633,32 +677,63 @@ export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
         };
     }
     let client;
-    try {
-        ({ client } = await getOrStartServer(profile, llmConfig, opts.env));
+    if (_testServer) {
+        client = _testServer.client;
     }
-    catch (e) {
-        return {
-            ok: false,
-            stdout: "",
-            stderr: String(e),
-            durationMs: Date.now() - start,
-            exitCode: 1,
-            reason: "spawn_failed",
-            error: String(e),
-        };
+    else {
+        const startupHandle = getOrStartServer(profile, llmConfig, opts.env, opts.envSource);
+        try {
+            const startup = await raceSdkOperation(startupHandle.promise, {
+                timeoutMs: remainingTimeoutMs(),
+                setTimeoutFn: setTimeoutImpl,
+                clearTimeoutFn: clearTimeoutImpl,
+                signal: opts.signal,
+            });
+            if (startup === SDK_OPERATION_ABORTED) {
+                return {
+                    ok: false,
+                    stdout: "",
+                    stderr: "",
+                    durationMs: Date.now() - start,
+                    exitCode: null,
+                    reason: "aborted",
+                    error: `opencode-sdk agent "${profile.name}" aborted by caller signal during server startup`,
+                };
+            }
+            if (startup === SDK_OPERATION_TIMED_OUT) {
+                return {
+                    ok: false,
+                    stdout: "",
+                    stderr: "",
+                    durationMs: Date.now() - start,
+                    exitCode: null,
+                    reason: "timeout",
+                    error: `opencode-sdk agent "${profile.name}" timed out during server startup after ${timeoutMs}ms`,
+                };
+            }
+            client = startup.client;
+        }
+        catch (e) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: String(e),
+                durationMs: Date.now() - start,
+                exitCode: 1,
+                reason: "spawn_failed",
+                error: String(e),
+            };
+        }
+        finally {
+            startupHandle.release();
+        }
     }
     // #564 bug fix (3): enforce a hard timeout like the CLI path (runAgent).
     // Previously runOpencodeSdk() awaited SDK calls with no timeout, so a stalled
     // local-model endpoint or wedged server could block the caller indefinitely.
-    // We resolve the same budget runAgent uses (opts.timeoutMs override →
-    // profile.timeoutMs → DEFAULT_AGENT_TIMEOUT_MS) and race both session.create
-    // and session.prompt against it. null disables the timer (parity with
-    // runAgent's "no timeout" contract). Session cleanup is separately bounded
-    // by a short best-effort timer so timeout/abort results cannot be pinned in
-    // the finally path by a hung delete call.
-    const timeoutMs = opts.timeoutMs !== undefined ? opts.timeoutMs : (profile.timeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS);
-    const setTimeoutImpl = opts.setTimeoutFn ?? setTimeout;
-    const clearTimeoutImpl = opts.clearTimeoutFn ?? clearTimeout;
+    // The same absolute deadline covers server startup, session creation, and
+    // prompting. null disables every dispatch timer. Session cleanup remains a
+    // separately bounded best-effort operation.
     // Per-call working directory (module doc): forwarded as the SDK's
     // `query.directory` on every session call, so worktree-isolated units run
     // in their own checkout without a per-cwd server.
@@ -670,10 +745,15 @@ export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
     let sessionId;
     try {
         const created = await raceSdkOperation(client.session.create({ body: { title: "akm" }, ...(query ? { query } : {}) }), {
-            timeoutMs,
+            timeoutMs: remainingTimeoutMs(),
             setTimeoutFn: setTimeoutImpl,
             clearTimeoutFn: clearTimeoutImpl,
             signal: abortSignal,
+            onLateSettle: (late) => {
+                if (late.status === "fulfilled" && late.value.data?.id) {
+                    void deleteSessionBestEffort(client, late.value.data.id, query, setTimeoutImpl, clearTimeoutImpl);
+                }
+            },
         });
         if (created === SDK_OPERATION_ABORTED) {
             return {
@@ -736,10 +816,13 @@ export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
     let result;
     try {
         const prompted = await raceSdkOperation(client.session.prompt({ path: { id: sessionId }, body, ...(query ? { query } : {}) }), {
-            timeoutMs,
+            timeoutMs: remainingTimeoutMs(),
             setTimeoutFn: setTimeoutImpl,
             clearTimeoutFn: clearTimeoutImpl,
             signal: abortSignal,
+            onLateSettle: () => {
+                void deleteSessionBestEffort(client, sessionId, query, setTimeoutImpl, clearTimeoutImpl);
+            },
         });
         if (prompted === SDK_OPERATION_ABORTED) {
             result = {