@byok-sdk/client 0.14.0 → 0.15.0

package/README.md

@@ -1,5 +1,20 @@
 # @byok-sdk/client
 
+## Diagnostics and recovery integration
+
+Use the SDK-maintained [downstream guide](https://github.com/Ancienttwo/byok-sdk/blob/main/docs/agent-diagnostics-integration.md)
+to build diagnostic UI and local repair flows. `byok-agent doctor --json` is
+the current read-only CLI entrypoint; `--fix --yes` only quarantines confirmed-corrupt
+operational health state with the daemon stopped. It does not repair an Agent
+or rebuild its journal. The guide includes integration limits and acceptance
+scenarios; qualify them against the exact SDK artifact shipped by your product.
+
+The public `diagnoseDevice` API accepts the host's actual adapters.
+`repairDeviceEnrollmentMetadata` (or the named CLI `--repair restore-enrollment-metadata`
+action) restores missing/valid-stale non-secret enrollment metadata from its
+existing OS authority, with confirmation, exact expected tenant/device and
+exclusive store ownership. It does not renew credentials or prove Agent readiness.
+
 ## Exact provider-profile admission
 
 When `DaemonConfig.piByokLauncher` is configured, the daemon advertises the

package/dist/adapters/codex/codex-adapter.d.ts

@@ -1,7 +1,9 @@
+import { type SdkHelperHostConfig } from '../../sdk-reserved-helper-host';
 import { type RuntimeAdapter, type RuntimeDetectResult, type RuntimeAdapterPrepareInput, type RuntimeAdapterPrepareResult } from '../../types';
 import { type ResolvedBin } from './resolve-bin';
 import { type SpawnFn } from './process-runner';
 export interface CodexAdapterOptions {
+    sdkHelperHost?: SdkHelperHostConfig;
     /** Override bin resolution — tests substitute the fake-codex fixture script. */
     resolveBin?: () => ResolvedBin;
     /** Override process spawning — tests substitute a fake spawn. */

package/dist/adapters/codex/process-runner.d.ts

@@ -1,3 +1,4 @@
+import { RuntimeExecutionFailure } from '../../runtime-failure';
 import { spawn } from 'node:child_process';
 export type SpawnFn = typeof spawn;
 /**
@@ -14,11 +15,13 @@ export interface CodexRawEvent {
 export interface CodexProcessOptions {
     command: string;
     args: string[];
+    instruction?: string;
     cwd: string;
     env: NodeJS.ProcessEnv;
     spawnFn?: SpawnFn;
     /** Called once per parsed JSONL line, in arrival order. */
     onEvent: (evt: CodexRawEvent) => void;
+    onFailure?: (error: RuntimeExecutionFailure) => void;
     /**
      * DI seam scoped to ADOPTION only (`../process-tree.ts`'s
      * `adoptOwnedProcessTree`), so the win32 job-object branch is exercisable
@@ -31,6 +34,9 @@ export interface CodexProcessOptions {
         assign(pid: number): Promise<void>;
     };
 }
+export declare const CODEX_MAX_FRAME_BYTES: number;
+export declare const CODEX_MAX_DEFERRED_BYTES: number;
+export declare const CODEX_MAX_STDERR_BYTES: number;
 /**
  * Spawns and streams ONE `codex exec` / `codex exec resume` invocation — i.e.
  * exactly one turn.
@@ -38,32 +44,24 @@ export interface CodexProcessOptions {
  * Unlike pi (a single long-lived RPC server process for a whole session's
  * lifetime — see `../pi/rpc-client.ts`), `codex exec` is a one-shot batch
  * process per turn with no persistent request/response channel: it takes its
- * prompt as an argv positional, streams JSONL to stdout for the one turn
+ * prompt from stdin with the documented `-` positional, streams JSONL to stdout for the one turn
  * it's running, and exits. `../codex-adapter.ts`'s `CodexSession` constructs
  * a fresh `CodexProcessRunner` for every turn (the initial `start()` and
  * every later `followUp()`), forwarding each one's lines into the same
  * long-lived event queue.
  *
- * stdin is deliberately never piped to the child (`stdio: ['ignore', 'pipe',
- * 'pipe']`): `codex exec --help` documents that a piped, non-TTY stdin is
- * read and appended to the prompt as a `<stdin>` block even when a prompt was
- * ALSO given as an argv positional, and empirically every single real
- * invocation made while building this adapter logged "Reading additional
- * input from stdin..." on stderr regardless of whether a prompt argument was
- * given. Leaving `stdio: ['pipe', ...]` open for stdin and never closing it
- * risks codex blocking on that read forever — exactly the hang class this
- * task was built to avoid (the pi adapter's own `agent_end`/`agent_settled`
- * mismatch left a task stuck `Running` forever in the M0/M1 GLM run).
- * `'ignore'` presents immediate EOF instead, which was verified live with a
- * dedicated Node `child_process` probe before this was written: no hang,
- * clean completion at normal model latency. This adapter never needs to
- * SEND codex anything over stdin — there is no in-band steer/approval
- * protocol (see `../codex-adapter.ts`'s `steer`/`resolveApproval`).
+ * Prompt stdin is closed with EOF immediately after writing. This is a one-shot
+ * input channel; steer and approvals are not multiplexed over it.
  */
 export declare class CodexProcessRunner {
     private readonly child;
     private readonly onEvent;
-    private buffer;
+    private readonly frameChunks;
+    private frameBytes;
+    private deferredBytes;
+    private stderrBytes;
+    private transportFailure;
+    private readonly onFailure;
     private readonly stderrRing;
     private closed;
     private exitCode;
@@ -133,6 +131,7 @@ export declare class CodexProcessRunner {
      * plus an empty stderr tail would bury the only reason anyone can act on.
      */
     buildExitError(context: string): Error;
+    private failTransport;
     private onData;
     private parseLine;
     private onStderr;

package/dist/adapters/detect-outcome.d.ts

@@ -0,0 +1,18 @@
+import type { RuntimeDetectResult } from '../types';
+type ProbeFailure = Exclude<RuntimeDetectResult, {
+    kind: 'available';
+}>;
+type VersionProbeResult = ProbeFailure | {
+    kind: 'available';
+    stdout: string;
+    stderr: string;
+};
+/** OS/process codes only. Arbitrary messages, streams and resolver paths never escape. */
+export declare function classifyDetectError(error: unknown): ProbeFailure;
+/**
+ * This probe owns both the deadline and the version child. A killed child is
+ * not by itself timeout evidence (execFile also kills on output overflow).
+ * Resolve only at execFile completion; SIGKILL bounds a TERM-ignoring probe.
+ */
+export declare function probeRuntimeVersion(command: string, timeoutMs: number): Promise<VersionProbeResult>;
+export {};

package/dist/adapters/index.d.ts

@@ -1,6 +1,6 @@
 export type { RuntimeAdapter, RuntimeAdapterDescriptor, RuntimeAdapterPrepareInput, RuntimeAdapterPrepareResult, RuntimeAdapterRejectedOperation, RuntimeAdapterPreparedOperation, PreparedRuntimeOperation, RuntimeOperationManifest, RuntimeOperationStartInput, RuntimeCapabilities, RuntimeDetectResult, } from '../types';
 export type { RuntimeEnvironmentRequirements } from '../daemon/environment';
-export { RuntimeDisposalFailure, RuntimeExecutionFailure } from '../runtime-failure';
+export { RuntimeDisposalFailure, RuntimeExecutionFailure, RuntimeStartupDisposalFailure } from '../runtime-failure';
 export type { RuntimeDisposalFailureInput, RuntimeDisposalStage, RuntimeExecutionFailureInput, RuntimeFailureCategory, RuntimeFailurePhase, RuntimeRetryDisposition, } from '../runtime-failure';
 export { PiAdapter } from './pi/pi-adapter';
 export type { PiAdapterOptions, PiByokLauncherConfig } from './pi/pi-adapter';

package/dist/adapters/index.js

@@ -5,6 +5,7 @@ import path5, { isAbsolute } from 'path';
 import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import 'readline';
+import { randomBytes } from 'crypto';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -181,6 +182,48 @@ function isRuntimeExecutionFailure(value) {
   const candidate = value;
   return candidate[RUNTIME_EXECUTION_FAILURE_BRAND] === true && isRuntimeFailurePhase(candidate.phase) && isRuntimeFailureCategory(candidate.category) && isRuntimeRetryDisposition(candidate.retry) && typeof candidate.message === "string" && candidate.message.length > 0;
 }
+var RuntimeStartupDisposalFailure = class extends Error {
+  retryDisposal;
+  constructor(retryDisposal, options) {
+    super("runtime startup failed and process ownership remains quarantined", options);
+    this.name = "RuntimeStartupDisposalFailure";
+    this.retryDisposal = retryDisposal;
+    Object.defineProperty(this, /* @__PURE__ */ Symbol.for("@byok-sdk/client/RuntimeStartupDisposalFailure/v1"), { value: true });
+    Object.freeze(this);
+  }
+};
+function classifyDetectError(error) {
+  const code = error !== null && typeof error === "object" ? error.code : void 0;
+  if (code === "ENOENT") return { kind: "not-found" };
+  if (code === "EACCES" || code === "EPERM" || code === "ENOEXEC") return { kind: "not-executable" };
+  return { kind: "probe-failed" };
+}
+async function probeRuntimeVersion(command, timeoutMs) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new TypeError("invalid runtime probe timeout");
+  return new Promise((resolve) => {
+    let timer;
+    let timedOut = false;
+    try {
+      const child = execFile(command, ["--version"], { encoding: "utf8" }, (error, stdout, stderr) => {
+        if (timer) clearTimeout(timer);
+        if (error?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") resolve({ kind: "probe-failed" });
+        else if (timedOut) resolve({ kind: "timeout" });
+        else if (error) resolve(classifyDetectError(error));
+        else resolve({ kind: "available", stdout, stderr });
+      });
+      timer = setTimeout(() => {
+        timedOut = true;
+        child.stdout?.destroy();
+        child.stderr?.destroy();
+        child.kill("SIGKILL");
+      }, timeoutMs);
+      timer.unref?.();
+    } catch (error) {
+      if (timer) clearTimeout(timer);
+      resolve(classifyDetectError(error));
+    }
+  });
+}
 
 // src/types.ts
 function frozenStrings(values) {
@@ -1231,12 +1274,13 @@ var PiAdapter = class {
   async detect() {
     try {
       const bin = this.resolveBin();
-      const { stdout, stderr } = await execFileAsync(bin.command, ["--version"], { timeout: DETECT_TIMEOUT_MS });
-      const version = stdout.trim() || stderr.trim();
+      const probe = await probeRuntimeVersion(bin.command, DETECT_TIMEOUT_MS);
+      if (probe.kind !== "available") return probe;
+      const version = probe.stdout.trim() || probe.stderr.trim();
       const authPresent = PROVIDER_CREDENTIAL_ENV_NAMES.some((name) => process.env[name] !== void 0);
-      return { present: true, version, authPresent };
-    } catch {
-      return { present: false };
+      return { kind: "available", version, authPresent };
+    } catch (error) {
+      return classifyDetectError(error);
     }
   }
   async prepare(input) {
@@ -1657,7 +1701,8 @@ var DIST_SCRIPT_BY_KIND = Object.freeze({
   "agent-message-mcp": "byok-agent-message-mcp.js",
   "agent-memory-mcp": "byok-agent-memory-mcp.js",
   "approval-mcp": "byok-approval-mcp.js",
-  "agent-team-mcp": "byok-agent-team-mcp.js"
+  "agent-team-mcp": "byok-agent-team-mcp.js",
+  "mcp-env": "byok-mcp-env.js"
 });
 function assertExecutable(executable) {
   if (!path5.isAbsolute(executable) || /[\u0000\r\n]/u.test(executable)) {
@@ -1675,8 +1720,11 @@ function resolveSdkReservedHelperBin(kind, host) {
       source: "self-executable"
     });
   }
+  const entryDir = path5.dirname(fileURLToPath(import.meta.url));
+  const entryKind = path5.basename(entryDir);
+  const distDir = entryKind === "adapters" || entryKind === "bin" ? path5.dirname(entryDir) : entryDir;
   const script = path5.join(
-    path5.dirname(fileURLToPath(import.meta.url)),
+    distDir,
     "bin",
     DIST_SCRIPT_BY_KIND[kind]
   );
@@ -2290,14 +2338,15 @@ var ClaudeAdapter = class {
     environmentRequirements: { credentialNames: [] }
   });
   async detect() {
-    const bin = this.resolveBin();
     try {
-      const { stdout } = await execFileAsync2(bin.command, ["--version"], { timeout: DETECT_TIMEOUT_MS2 });
-      const version = stdout.trim();
+      const bin = this.resolveBin();
+      const probe = await probeRuntimeVersion(bin.command, DETECT_TIMEOUT_MS2);
+      if (probe.kind !== "available") return probe;
+      const version = probe.stdout.trim();
       const authPresent = await this.probeAuthPresent(bin.command);
-      return { present: true, version, authPresent };
-    } catch {
-      return { present: false };
+      return { kind: "available", version, authPresent };
+    } catch (error) {
+      return classifyDetectError(error);
     }
   }
   async prepare(input) {
@@ -2916,10 +2965,18 @@ function unmappedFrameKey(evt) {
   return evt.type;
 }
 var STDERR_RING_CAPACITY3 = 20;
+var CODEX_MAX_FRAME_BYTES = 1024 * 1024;
+var CODEX_MAX_DEFERRED_BYTES = 4 * 1024 * 1024;
+var CODEX_MAX_STDERR_BYTES = 64 * 1024;
 var CodexProcessRunner = class {
   child;
   onEvent;
-  buffer = "";
+  frameChunks = [];
+  frameBytes = 0;
+  deferredBytes = 0;
+  stderrBytes = 0;
+  transportFailure;
+  onFailure;
   stderrRing = [];
   closed = false;
   exitCode = null;
@@ -2942,11 +2999,12 @@ var CodexProcessRunner = class {
   deferredEvents = [];
   constructor(options) {
     this.onEvent = options.onEvent;
+    this.onFailure = options.onFailure;
     const spawnFn = options.spawnFn ?? spawn;
     this.child = spawnFn(options.command, options.args, withOwnedProcessTree({
       cwd: options.cwd,
       env: options.env,
-      stdio: ["ignore", "pipe", "pipe"]
+      stdio: [options.instruction === void 0 ? "ignore" : "pipe", "pipe", "pipe"]
     }));
     this.closedPromise = new Promise((resolve) => {
       this.resolveClosed = resolve;
@@ -2954,7 +3012,6 @@ var CodexProcessRunner = class {
     this.adopted = this.adoptOwnedTree(options);
     this.adopted.catch(() => {
     });
-    this.child.stdout.setEncoding("utf8");
     this.child.stdout.on("data", (chunk) => this.onData(chunk));
     this.child.stderr.setEncoding("utf8");
     this.child.stderr.on("data", (chunk) => this.onStderr(chunk));
@@ -2963,6 +3020,12 @@ var CodexProcessRunner = class {
       this.exitSignal = signal;
       this.finishClosing();
     });
+    if (options.instruction !== void 0) {
+      this.child.stdin.on("error", () => {
+        this.failTransport("codex prompt stdin failed before delivery");
+      });
+      this.child.stdin.end(options.instruction, "utf8");
+    }
     this.child.on("error", () => {
       this.finishClosing();
     });
@@ -3048,12 +3111,19 @@ var CodexProcessRunner = class {
       throw failure;
     }
     this.adoption = "adopted";
+    this.deferredBytes = 0;
     for (const evt of this.deferredEvents.splice(0)) this.onEvent(evt);
   }
   /** Arrival-order delivery, held back until the tree is backstopped (see `deferredEvents`). */
-  deliver(evt) {
+  deliver(evt, bytes) {
+    if (this.transportFailure) return;
     if (this.adoption === "failed") return;
     if (this.adoption === "pending") {
+      if (this.deferredBytes + bytes > CODEX_MAX_DEFERRED_BYTES) {
+        this.failTransport("codex pre-adoption event buffer exceeded its byte budget");
+        return;
+      }
+      this.deferredBytes += bytes;
       this.deferredEvents.push(evt);
       return;
     }
@@ -3070,6 +3140,7 @@ var CodexProcessRunner = class {
    * plus an empty stderr tail would bury the only reason anyone can act on.
    */
   buildExitError(context) {
+    if (this.transportFailure) return this.transportFailure;
     if (this.adoptionFailure !== void 0) return this.adoptionFailure;
     const parts = [`${context} (exit code=${this.exitCode}, signal=${this.exitSignal})`];
     if (this.stderrRing.length > 0) {
@@ -3077,18 +3148,45 @@ var CodexProcessRunner = class {
     }
     return new Error(parts.join("; "));
   }
-  onData(chunk) {
-    this.buffer += chunk;
-    let newlineIndex = this.buffer.indexOf("\n");
-    while (newlineIndex !== -1) {
-      let line = this.buffer.slice(0, newlineIndex);
-      this.buffer = this.buffer.slice(newlineIndex + 1);
-      if (line.endsWith("\r")) line = line.slice(0, -1);
-      if (line.length > 0) this.parseLine(line);
-      newlineIndex = this.buffer.indexOf("\n");
-    }
+  failTransport(reason) {
+    if (this.transportFailure) return;
+    this.transportFailure = new RuntimeExecutionFailure({
+      phase: "run",
+      category: "infrastructure",
+      retry: "non-retryable",
+      reason
+    });
+    this.frameChunks.length = 0;
+    this.frameBytes = 0;
+    this.deferredEvents.length = 0;
+    this.deferredBytes = 0;
+    this.onFailure?.(this.transportFailure);
+    this.kill();
   }
-  parseLine(line) {
+  onData(chunk) {
+    if (this.transportFailure) return;
+    let offset = 0;
+    while (offset < chunk.length) {
+      const newline = chunk.indexOf(10, offset);
+      const end = newline === -1 ? chunk.length : newline;
+      const bytes = end - offset;
+      if (this.frameBytes + bytes > CODEX_MAX_FRAME_BYTES) {
+        this.failTransport("codex raw JSONL frame exceeded its byte budget");
+        return;
+      }
+      if (bytes > 0) this.frameChunks.push(Buffer.from(chunk.subarray(offset, end)));
+      this.frameBytes += bytes;
+      if (newline === -1) return;
+      const frame = Buffer.concat(this.frameChunks, this.frameBytes);
+      this.frameChunks.length = 0;
+      this.frameBytes = 0;
+      const line = frame.toString("utf8").replace(/\r$/, "");
+      if (line.length > 0) this.parseLine(line, frame.length);
+      if (this.transportFailure) return;
+      offset = newline + 1;
+    }
+  }
+  parseLine(line, bytes) {
     let parsed;
     try {
       parsed = JSON.parse(line);
@@ -3098,14 +3196,18 @@ var CodexProcessRunner = class {
     if (!parsed || typeof parsed !== "object" || typeof parsed.type !== "string") {
       return;
     }
-    this.deliver(parsed);
+    this.deliver(parsed, bytes);
   }
   onStderr(chunk) {
-    for (const rawLine of chunk.split("\n")) {
+    const bounded = Buffer.from(chunk).subarray(-CODEX_MAX_STDERR_BYTES).toString("utf8");
+    for (const rawLine of bounded.split("\n")) {
       const line = rawLine.trim();
       if (line.length === 0) continue;
       this.stderrRing.push(line);
-      if (this.stderrRing.length > STDERR_RING_CAPACITY3) this.stderrRing.shift();
+      this.stderrBytes += Buffer.byteLength(line);
+      while (this.stderrRing.length > STDERR_RING_CAPACITY3 || this.stderrBytes > CODEX_MAX_STDERR_BYTES) {
+        this.stderrBytes -= Buffer.byteLength(this.stderrRing.shift());
+      }
     }
   }
 };
@@ -3138,14 +3240,15 @@ var CodexAdapter = class {
     environmentRequirements: { credentialNames: [] }
   });
   async detect() {
-    const bin = this.resolveBin();
     try {
-      const versionResult = await execFileAsync3(bin.command, ["--version"], { timeout: DETECT_TIMEOUT_MS3 });
-      const version = versionResult.stdout.trim() || versionResult.stderr.trim();
+      const bin = this.resolveBin();
+      const probe = await probeRuntimeVersion(bin.command, DETECT_TIMEOUT_MS3);
+      if (probe.kind !== "available") return probe;
+      const version = probe.stdout.trim() || probe.stderr.trim();
       const authPresent = await this.probeAuthPresent(bin);
-      return { present: true, version, authPresent };
-    } catch {
-      return { present: false };
+      return { kind: "available", version, authPresent };
+    } catch (error) {
+      return classifyDetectError(error);
     }
   }
   /**
@@ -3288,7 +3391,7 @@ ${withStreams.stderr ?? ""}`);
         reason: "prepared codex operation received a manifest with different runtime selection"
       });
     }
-    const mcpConfigArgs = codexMcpConfigArgs(startInput.mcpServers, preparedMcpGrants);
+    const mcpConfigArgs = codexMcpConfigArgs(startInput.mcpServers, runtimeEnv, this.options.sdkHelperHost, preparedMcpGrants);
     const { sessionRef, runner } = await runCodexTurn({
       command,
       resumeRef: startInput.manifest.sessionRef,
@@ -3304,6 +3407,7 @@ ${withStreams.stderr ?? ""}`);
       expectedSessionRef: startInput.manifest.sessionRef,
       preparedGit: startInput.manifest.workspace.workspaceId !== void 0,
       failurePhase: "start",
+      signal: startInput.signal,
       terminal
     });
     return new CodexSession({
@@ -3311,6 +3415,7 @@ ${withStreams.stderr ?? ""}`);
       command,
       workspaceDir,
       env: startInput.env,
+      mcpEnvironment: Object.fromEntries(Object.entries(runtimeEnv).filter(([key]) => key.startsWith("BYOK_MCP_PAYLOAD_"))),
       spawnFn: this.options.spawnFn,
       queue,
       recordUnmapped,
@@ -3363,16 +3468,18 @@ function codexMcpToolApprovalArgs(name, tools) {
   }
   return args;
 }
-function codexMcpConfigArgs(servers, grants = []) {
+function codexMcpConfigArgs(servers, env, helperHost, grants = []) {
   if (servers === void 0 || Object.keys(servers).length === 0) return [];
   const grantedTools = new Map(grants.map((grant) => [grant.server, grant.tools]));
   const args = ["--ignore-user-config"];
   for (const [name, server] of Object.entries(servers).sort(([left], [right]) => left.localeCompare(right))) {
-    args.push("-c", `mcp_servers.${name}.command=${JSON.stringify(server.command)}`);
-    if (server.args !== void 0) args.push("-c", `mcp_servers.${name}.args=${JSON.stringify([...server.args])}`);
-    for (const [key, value] of Object.entries(server.env ?? {}).sort(([left], [right]) => left.localeCompare(right))) {
-      args.push("-c", `mcp_servers.${name}.env.${key}=${JSON.stringify(value)}`);
-    }
+    const key = `BYOK_MCP_PAYLOAD_${randomBytes(16).toString("hex").toUpperCase()}`;
+    env[key] = JSON.stringify(server);
+    const helper = resolveSdkReservedHelperBin("mcp-env", helperHost);
+    args.push("-c", `mcp_servers.${name}.command=${JSON.stringify(helper.command)}`);
+    args.push("-c", `mcp_servers.${name}.args=${JSON.stringify([...helper.args])}`);
+    args.push("-c", `mcp_servers.${name}.env.BYOK_MCP_ENV_KEY=${JSON.stringify(key)}`);
+    args.push("-c", `mcp_servers.${name}.env_vars=${JSON.stringify([key])}`);
     const granted = grantedTools.get(name);
     if (granted !== void 0) args.push(...codexMcpToolApprovalArgs(name, granted));
   }
@@ -3400,7 +3507,7 @@ function buildArgv(resumeRef, policyArgs, instruction, modelId, preparedGit = fa
     ...modelId ? ["--model", modelId] : [],
     ...preparedGit ? [] : ["--skip-git-repo-check"],
     ...policyArgs,
-    instruction
+    "-"
   ];
 }
 async function runCodexTurn(params) {
@@ -3424,9 +3531,18 @@ async function runCodexTurn(params) {
     runner = new CodexProcessRunner({
       command: params.command,
       args: argv,
+      instruction: params.instruction,
       cwd: params.cwd,
       env: params.env,
       spawnFn: params.spawnFn,
+      onFailure: (failure) => {
+        if (!firstLineSettled) {
+          firstLineSettled = true;
+          rejectFirstLine(failure);
+        }
+        params.terminal.failure = failure;
+        params.queue.end();
+      },
       onEvent: (evt) => {
         if (!firstLineSettled) {
           firstLineSettled = true;
@@ -3493,6 +3609,16 @@ async function runCodexTurn(params) {
     params.queue.end();
   });
   let sessionRef;
+  const abortStartup = () => rejectFirstLine(new RuntimeExecutionFailure({
+    phase: params.failurePhase,
+    category: "infrastructure",
+    retry: "non-retryable",
+    reason: "codex startup cancelled or exceeded its deadline"
+  }));
+  const startupTimer = setTimeout(abortStartup, 3e4);
+  startupTimer.unref?.();
+  params.signal?.addEventListener("abort", abortStartup, { once: true });
+  if (params.signal?.aborted) abortStartup();
   try {
     sessionRef = await new Promise((resolve, reject) => {
       let settled = false;
@@ -3524,20 +3650,31 @@ async function runCodexTurn(params) {
       });
     });
   } catch (err) {
-    runner.kill();
+    await disposeFailedStartup(runner, err);
     throw err;
+  } finally {
+    clearTimeout(startupTimer);
+    params.signal?.removeEventListener("abort", abortStartup);
   }
   if (params.expectedSessionRef !== void 0 && sessionRef !== params.expectedSessionRef) {
-    runner.kill();
-    throw new RuntimeExecutionFailure({
+    const failure = new RuntimeExecutionFailure({
       phase: params.failurePhase,
       category: "authority",
       retry: "non-retryable",
       reason: `codex exec resume echoed a different thread id than requested (requested ${params.expectedSessionRef}, got ${sessionRef})`
     });
+    await disposeFailedStartup(runner, failure);
+    throw failure;
   }
   return { sessionRef, runner };
 }
+async function disposeFailedStartup(runner, cause) {
+  try {
+    await runner.dispose();
+  } catch (disposalFailure) {
+    throw new RuntimeStartupDisposalFailure(() => runner.dispose(), { cause: new AggregateError([cause, disposalFailure]) });
+  }
+}
 var CodexSession = class {
   /**
    * NOT `readonly` (cross-model review finding): `followUp()` below
@@ -3573,6 +3710,7 @@ var CodexSession = class {
    * recomputed from anything a later turn supplies, so a follow-up can never
    * widen this session's MCP authority.
    */
+  mcpEnvironment;
   mcpConfigArgs;
   terminal;
   currentRunner;
@@ -3592,6 +3730,7 @@ var CodexSession = class {
     this.modelId = options.modelId;
     this.terminal = options.terminal;
     this.mcpConfigArgs = options.mcpConfigArgs;
+    this.mcpEnvironment = Object.freeze({ ...options.mcpEnvironment });
     this.currentRunner = options.initialRunner;
     this.ownedRunners.add(options.initialRunner);
     void this.forgetRunnerOnceClosed(options.initialRunner);
@@ -3704,7 +3843,7 @@ var CodexSession = class {
         // frozen MCP config replayed verbatim — see `mcpConfigArgs`.
         policyArgs: [...mapping.args, ...this.mcpConfigArgs],
         cwd: this.workspaceDir,
-        env: withoutProviderCredentials(this.env),
+        env: { ...withoutProviderCredentials(this.env), ...this.mcpEnvironment },
         spawnFn: this.spawnFn,
         workspaceDir: this.workspaceDir,
         queue: this.queue,
@@ -3803,6 +3942,6 @@ function subscriptionModel2(selection) {
   return selection.modelId;
 }
 
-export { ClaudeAdapter, CodexAdapter, PI_PACKAGE_NAME, PiAdapter, RuntimeDisposalFailure, RuntimeExecutionFailure };
+export { ClaudeAdapter, CodexAdapter, PI_PACKAGE_NAME, PiAdapter, RuntimeDisposalFailure, RuntimeExecutionFailure, RuntimeStartupDisposalFailure };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map