@byok-sdk/client 0.3.0 → 0.4.0

package/dist/adapters/index.js

@@ -6,9 +6,80 @@ import { fileURLToPath } from 'url';
 import os from 'os';
 import 'readline';
 
-// src/adapters/pi/pi-adapter.ts
+// src/runtime-failure.ts
+var RUNTIME_EXECUTION_FAILURE_BRAND = /* @__PURE__ */ Symbol.for("@byok-sdk/client/RuntimeExecutionFailure/v1");
+var RUNTIME_DISPOSAL_FAILURE_BRAND = /* @__PURE__ */ Symbol.for("@byok-sdk/client/RuntimeDisposalFailure/v1");
+var RuntimeDisposalFailure = class extends Error {
+  stage;
+  constructor(input, options) {
+    if (!isRuntimeDisposalStage(input.stage) || typeof input.reason !== "string" || input.reason.length === 0) {
+      throw new TypeError("invalid RuntimeDisposalFailure input");
+    }
+    super(input.reason, options);
+    this.name = "RuntimeDisposalFailure";
+    this.stage = input.stage;
+    Object.defineProperty(this, RUNTIME_DISPOSAL_FAILURE_BRAND, { value: true });
+    Object.freeze(this);
+  }
+};
+function isRuntimeDisposalStage(value) {
+  return value === "signal" || value === "quiescence" || value === "cleanup";
+}
+var RuntimeExecutionFailure = class extends Error {
+  phase;
+  category;
+  retry;
+  constructor(input, options) {
+    if (!isRuntimeFailurePhase(input.phase) || !isRuntimeFailureCategory(input.category) || !isRuntimeRetryDisposition(input.retry) || typeof input.reason !== "string" || input.reason.length === 0) {
+      throw new TypeError("invalid RuntimeExecutionFailure input");
+    }
+    super(input.reason, options);
+    this.name = "RuntimeExecutionFailure";
+    this.phase = input.phase;
+    this.category = input.category;
+    this.retry = input.retry;
+    Object.defineProperty(this, RUNTIME_EXECUTION_FAILURE_BRAND, { value: true });
+    Object.freeze(this);
+  }
+};
+function isRuntimeFailurePhase(value) {
+  return value === "start" || value === "run";
+}
+function isRuntimeFailureCategory(value) {
+  return value === "semantic" || value === "infrastructure" || value === "authority";
+}
+function isRuntimeRetryDisposition(value) {
+  return value === "retryable" || value === "non-retryable";
+}
+function isRuntimeExecutionFailure(value) {
+  if (typeof value !== "object" || value === null) return false;
+  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;
+}
 
 // src/types.ts
+function frozenStrings(values) {
+  return values === void 0 ? void 0 : Object.freeze([...values]);
+}
+function freezeRuntimeAdapterDescriptor(descriptor) {
+  const baseNames = frozenStrings(descriptor.environmentRequirements.baseNames);
+  const credentialNames = frozenStrings(descriptor.environmentRequirements.credentialNames);
+  return Object.freeze({
+    id: descriptor.id,
+    supportsDispatchSelection: descriptor.supportsDispatchSelection === true,
+    capabilities: Object.freeze({
+      steer: descriptor.capabilities.steer === true,
+      resume: descriptor.capabilities.resume === true,
+      approvalInteractive: descriptor.capabilities.approvalInteractive === true,
+      ...descriptor.capabilities.mcpToolsets === void 0 ? {} : { mcpToolsets: descriptor.capabilities.mcpToolsets === true },
+      permissionModes: Object.freeze([...descriptor.capabilities.permissionModes])
+    }),
+    environmentRequirements: Object.freeze({
+      ...baseNames === void 0 ? {} : { baseNames },
+      ...credentialNames === void 0 ? {} : { credentialNames }
+    })
+  });
+}
 var PolicyUnsupportedError = class extends Error {
   constructor(message) {
     super(message);
@@ -16,7 +87,7 @@ var PolicyUnsupportedError = class extends Error {
   }
 };
 var SteerUnsupportedError = class extends Error {
-  /** The `RuntimeAdapter.id` that cannot steer (e.g. `claude`, `codex`). */
+  /** The `RuntimeAdapter.descriptor.id` that cannot steer (e.g. `claude`, `codex`). */
   runtimeId;
   constructor(runtimeId, message) {
     super(message);
@@ -267,6 +338,155 @@ var AsyncQueue = class {
     };
   }
 };
+var DEFAULT_TERM_GRACE_MS = 750;
+var DEFAULT_KILL_GRACE_MS = 2e3;
+var POLL_MS = 20;
+var terminationRequested = /* @__PURE__ */ new WeakSet();
+var terminationRequestFailed = /* @__PURE__ */ new WeakSet();
+function withOwnedProcessTree(options) {
+  return {
+    ...options,
+    ...process.platform === "win32" ? { windowsHide: true } : { detached: true }
+  };
+}
+function positivePid(child, label) {
+  const pid = child.pid;
+  if (pid === void 0) return void 0;
+  if (!Number.isSafeInteger(pid) || pid <= 0 || pid === process.pid) {
+    throw new RuntimeDisposalFailure({
+      stage: "signal",
+      reason: `${label} runtime process has an unsafe owned pid`
+    });
+  }
+  return pid;
+}
+function groupExists(pid, label) {
+  try {
+    process.kill(-pid, 0);
+    return true;
+  } catch (cause) {
+    const code = cause.code;
+    if (code === "ESRCH") return false;
+    if (code === "EPERM") return true;
+    throw new RuntimeDisposalFailure({
+      stage: "quiescence",
+      reason: `${label} runtime process-group state could not be verified`
+    }, { cause });
+  }
+}
+function signalGroup(pid, signal, label) {
+  try {
+    process.kill(-pid, signal);
+  } catch (cause) {
+    const code = cause.code;
+    if (code === "ESRCH" || code === "EPERM") return;
+    throw new RuntimeDisposalFailure({
+      stage: "signal",
+      reason: `${label} runtime process group ${pid} could not receive ${signal} (${code ?? "unknown"})`
+    }, { cause });
+  }
+}
+async function waitUntil(predicate, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (predicate()) {
+    if (Date.now() >= deadline) return false;
+    await new Promise((resolve) => {
+      setTimeout(resolve, POLL_MS);
+    });
+  }
+  return true;
+}
+async function waitWithDeadline(promise, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        resolve(false);
+      }
+    }, timeoutMs);
+    void promise.then(
+      () => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timer);
+          resolve(true);
+        }
+      },
+      () => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timer);
+          resolve(false);
+        }
+      }
+    );
+  });
+}
+function requestOwnedProcessTreeTermination(options) {
+  if (options.isClosed()) return;
+  const pid = positivePid(options.child, options.label);
+  if (pid === void 0) return;
+  if (process.platform === "win32") {
+    const result = spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true });
+    if (result.error) {
+      throw new RuntimeDisposalFailure({
+        stage: "signal",
+        reason: `${options.label} runtime process tree could not be terminated`
+      }, { cause: result.error });
+    }
+    terminationRequested.add(options.child);
+    if (result.status !== 0) terminationRequestFailed.add(options.child);
+    return;
+  }
+  signalGroup(pid, "SIGTERM", options.label);
+  terminationRequested.add(options.child);
+}
+async function disposeOwnedProcessTree(options) {
+  const pid = positivePid(options.child, options.label);
+  const termGraceMs = options.termGraceMs ?? DEFAULT_TERM_GRACE_MS;
+  const killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+  if (pid === void 0) {
+    if (await waitWithDeadline(options.waitClosed(), killGraceMs)) return;
+    throw new RuntimeDisposalFailure({
+      stage: "quiescence",
+      reason: `${options.label} runtime process did not settle after spawn failure`
+    });
+  }
+  if (process.platform === "win32") {
+    if (!options.isClosed() && !terminationRequested.has(options.child)) requestOwnedProcessTreeTermination(options);
+    if (await waitWithDeadline(options.waitClosed(), killGraceMs)) return;
+    if (terminationRequestFailed.has(options.child)) {
+      throw new RuntimeDisposalFailure({
+        stage: "signal",
+        reason: `${options.label} runtime process tree could not be terminated`
+      });
+    }
+    throw new RuntimeDisposalFailure({
+      stage: "quiescence",
+      reason: `${options.label} runtime process tree did not close before the disposal deadline`
+    });
+  }
+  if (groupExists(pid, options.label) && !terminationRequested.has(options.child)) {
+    signalGroup(pid, "SIGTERM", options.label);
+    terminationRequested.add(options.child);
+  }
+  if (!await waitUntil(() => groupExists(pid, options.label), termGraceMs)) {
+    signalGroup(pid, "SIGKILL", options.label);
+    if (!await waitUntil(() => groupExists(pid, options.label), killGraceMs)) {
+      throw new RuntimeDisposalFailure({
+        stage: "quiescence",
+        reason: `${options.label} runtime process group remained live after SIGKILL`
+      });
+    }
+  }
+  if (!await waitWithDeadline(options.waitClosed(), killGraceMs)) {
+    throw new RuntimeDisposalFailure({
+      stage: "quiescence",
+      reason: `${options.label} runtime root did not emit close after its process group exited`
+    });
+  }
+}
 
 // src/adapters/pi/rpc-client.ts
 var STDERR_RING_CAPACITY = 20;
@@ -279,16 +499,22 @@ var PiRpcClient = class {
   eventQueue = new AsyncQueue();
   closed = false;
   exitError;
+  closedPromise;
+  resolveClosed;
+  disposalAttempt;
   /** Bounded tail of recent stderr lines — pi discarded this entirely before (nothing ever read `child.stderr`), which is exactly why finding #1 (`Error: Unknown option: --session-id`, exit 1) had to be root-caused by hand instead of reading it off a thrown error. See `buildExitError`. */
   stderrRing = [];
   /** Count of pi RPC message types `PiSession` (pi-adapter.ts) has told us have no `AgentEvent` mapping and aren't routine bookkeeping — see `recordUnmappedFrame`. */
   unmappedFrameCounts = /* @__PURE__ */ new Map();
   constructor(options) {
     const spawnFn = options.spawnFn ?? spawn;
-    this.child = spawnFn(options.command, options.args, {
+    this.child = spawnFn(options.command, options.args, withOwnedProcessTree({
       cwd: options.cwd,
       env: options.env,
       stdio: ["pipe", "pipe", "pipe"]
+    }));
+    this.closedPromise = new Promise((resolve) => {
+      this.resolveClosed = resolve;
     });
     this.child.stdout.setEncoding("utf8");
     this.child.stdout.on("data", (chunk) => this.onData(chunk));
@@ -323,6 +549,10 @@ var PiRpcClient = class {
   get events() {
     return this.eventQueue;
   }
+  /** Local transport diagnostic retained when the process closes; consumers must classify it explicitly. */
+  get terminalError() {
+    return this.exitError;
+  }
   /**
    * Record a pi RPC message `type` that `PiSession` (pi-adapter.ts) decided
    * has no `AgentEvent` mapping and isn't routine bookkeeping (see
@@ -341,15 +571,30 @@ var PiRpcClient = class {
       );
     }
   }
-  /** Best-effort teardown. SIGTERM on POSIX; `taskkill /T /F` on Windows to also reap child processes pi itself spawned (e.g. bash). */
+  /** Immediate process-tree termination request. `dispose()` is the settlement receipt. */
   kill() {
-    if (this.closed) return;
-    const pid = this.child.pid;
-    if (process.platform === "win32" && pid !== void 0) {
-      spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"]);
-    } else {
-      this.child.kill("SIGTERM");
+    requestOwnedProcessTreeTermination(this.processTreeOptions());
+  }
+  waitClosed() {
+    return this.closedPromise;
+  }
+  dispose() {
+    if (!this.disposalAttempt) {
+      const attempt = disposeOwnedProcessTree(this.processTreeOptions());
+      this.disposalAttempt = attempt.catch((error) => {
+        this.disposalAttempt = void 0;
+        throw error;
+      });
     }
+    return this.disposalAttempt;
+  }
+  processTreeOptions() {
+    return {
+      child: this.child,
+      waitClosed: () => this.closedPromise,
+      isClosed: () => this.closed,
+      label: "pi"
+    };
   }
   onData(chunk) {
     this.buffer += chunk;
@@ -435,6 +680,7 @@ var PiRpcClient = class {
     if (this.closed) return;
     this.closed = true;
     this.exitError = err;
+    this.resolveClosed();
     for (const [, waiter] of this.pending) waiter.reject(err);
     this.pending.clear();
     this.eventQueue.end();
@@ -505,8 +751,17 @@ var PiAdapter = class {
     this.options = options;
   }
   options;
-  id = "pi";
-  supportsDispatchSelection = true;
+  descriptor = freezeRuntimeAdapterDescriptor({
+    id: "pi",
+    supportsDispatchSelection: true,
+    capabilities: {
+      steer: true,
+      resume: true,
+      approvalInteractive: false,
+      permissionModes: ["auto", "readonly"]
+    },
+    environmentRequirements: { credentialNames: PROVIDER_CREDENTIAL_ENV_NAMES }
+  });
   async detect() {
     try {
       const bin = this.resolveBin();
@@ -518,49 +773,26 @@ var PiAdapter = class {
       return { present: false };
     }
   }
-  capabilities() {
-    return { steer: true, resume: true, approvalInteractive: false, permissionModes: ["auto", "readonly"] };
-  }
-  /**
-   * M5: pi authenticates to its ~30 supported providers via env-var API
-   * keys — `detect()`'s own `authPresent` probe above checks this identical
-   * list — so these MUST keep flowing into pi's spawned process or pi auth
-   * breaks entirely. `KNOWN_PROVIDER_ENV_VARS` above is the single source
-   * of truth, reused here rather than duplicated. No `baseNames`: nothing
-   * in this adapter or `rpc-client.ts` reads a pi-specific config-discovery
-   * variable beyond the platform baseline (`daemon/environment.ts`).
-   */
-  environmentRequirements() {
-    return { credentialNames: PROVIDER_CREDENTIAL_ENV_NAMES };
-  }
-  async start(task, ctx) {
-    if (typeof task.instruction !== "string") {
-      throw new PolicyUnsupportedError("pi adapter only supports string instructions in M0 (no blob-ref fetch yet)");
-    }
-    const mapping = mapPermissionPolicyToPiArgs(ctx.policy);
+  async prepare(input) {
+    const mapping = mapPermissionPolicyToPiArgs(input.policy);
     if (!mapping.ok) {
-      throw new PolicyUnsupportedError(mapping.reason ?? "policy rejected by pi adapter");
+      return { kind: "reject", reason: mapping.reason ?? "policy rejected by pi adapter", retryable: false };
     }
     const bin = this.resolveBin();
-    const resumeSessionId = task.sessionRef;
-    const piArgs = ["--mode", "rpc", ...resumeSessionId ? ["--session", resumeSessionId] : [], ...mapping.args];
-    const selection = task.dispatchSelection;
+    const selection = input.offer.dispatchSelection;
+    const pinnedSelection = selection === void 0 ? void 0 : Object.freeze({ ...selection });
     let command = bin.command;
-    let args = piArgs;
-    if (selection !== void 0) {
-      if (selection.lane !== "byok" || selection.runtimeId !== "pi") {
-        throw new PolicyUnsupportedError(
-          `pi adapter cannot execute ${selection.lane} selection for runtime ${selection.runtimeId}`
-        );
+    let launcherArgs;
+    if (pinnedSelection !== void 0) {
+      if (pinnedSelection.lane !== "byok" || pinnedSelection.runtimeId !== "pi") {
+        return { kind: "reject", reason: `pi adapter cannot execute ${pinnedSelection.lane} selection for runtime ${pinnedSelection.runtimeId}`, retryable: false };
       }
       const launcher = this.options.byokLauncher;
       if (launcher === void 0) {
-        throw new PolicyUnsupportedError(
-          "pi BYOK selection requires a configured credential-custody launcher"
-        );
+        return { kind: "reject", reason: "pi BYOK selection requires a configured credential-custody launcher", retryable: false };
       }
       command = launcher.command;
-      args = [
+      launcherArgs = [
         ...launcher.args ?? [],
         "--pi-bin",
         bin.command,
@@ -570,62 +802,136 @@ var PiAdapter = class {
         launcher.sessionDir,
         ...launcher.secretServicePrefix ? ["--secret-service-prefix", launcher.secretServicePrefix] : [],
         "--provider",
-        selection.providerId,
+        pinnedSelection.providerId,
         "--model",
-        selection.modelId,
-        "--",
-        ...piArgs
+        pinnedSelection.modelId
       ];
     }
-    const rpc = new PiRpcClient({
-      command,
-      args,
-      cwd: ctx.workspaceDir,
-      env: selection === void 0 ? ctx.env : withoutProviderCredentials(ctx.env),
-      spawnFn: this.options.spawnFn
-    });
-    const response = await rpc.send({ type: "prompt", message: task.instruction });
-    if (response.success === false) {
-      rpc.kill();
-      throw new Error(typeof response.error === "string" ? response.error : "pi rejected the initial prompt");
-    }
-    let sessionRef;
-    if (resumeSessionId) {
-      sessionRef = resumeSessionId;
-    } else {
-      try {
-        sessionRef = await resolveFreshSessionId(rpc);
-      } catch (err) {
-        rpc.kill();
-        throw err;
+    return {
+      kind: "prepared",
+      operation: {
+        start: async (startInput) => {
+          const manifestSelection = startInput.manifest.dispatchSelection;
+          if (!sameDispatchSelection(manifestSelection, pinnedSelection)) {
+            throw new RuntimeExecutionFailure({
+              phase: "start",
+              category: "authority",
+              retry: "non-retryable",
+              reason: "prepared pi operation received a manifest with different runtime selection"
+            });
+          }
+          if (typeof startInput.instruction !== "string") {
+            throw new RuntimeExecutionFailure({
+              phase: "start",
+              category: "authority",
+              retry: "non-retryable",
+              reason: "prepared pi operation requires a resolved string instruction"
+            });
+          }
+          const resumeSessionId = startInput.manifest.sessionRef;
+          const piArgs = ["--mode", "rpc", ...resumeSessionId ? ["--session", resumeSessionId] : [], ...mapping.args];
+          const args = launcherArgs === void 0 ? piArgs : [...launcherArgs, "--", ...piArgs];
+          let rpc;
+          try {
+            rpc = new PiRpcClient({
+              command,
+              args,
+              cwd: startInput.manifest.workspace.workspaceDir,
+              env: manifestSelection === void 0 ? startInput.env : withoutProviderCredentials(startInput.env),
+              spawnFn: this.options.spawnFn
+            });
+          } catch (cause) {
+            throw new RuntimeExecutionFailure({
+              phase: "start",
+              category: "infrastructure",
+              retry: "retryable",
+              reason: "pi runtime process could not be spawned"
+            }, { cause });
+          }
+          let response;
+          try {
+            response = await rpc.send({ type: "prompt", message: startInput.instruction });
+          } catch (cause) {
+            rpc.kill();
+            throw new RuntimeExecutionFailure({
+              phase: "start",
+              category: "infrastructure",
+              retry: "retryable",
+              reason: `pi initial prompt transport failed: ${errorMessage(cause)}`
+            }, { cause });
+          }
+          if (response.success === false) {
+            rpc.kill();
+            throw new RuntimeExecutionFailure({
+              phase: "start",
+              category: "semantic",
+              retry: "non-retryable",
+              reason: typeof response.error === "string" ? response.error : "pi rejected the initial prompt"
+            });
+          }
+          let sessionRef;
+          try {
+            sessionRef = await resolveAuthoritativeSessionId(rpc);
+          } catch (err) {
+            rpc.kill();
+            throw err;
+          }
+          if (resumeSessionId !== void 0 && sessionRef !== resumeSessionId) {
+            rpc.kill();
+            throw new RuntimeExecutionFailure({
+              phase: "start",
+              category: "authority",
+              retry: "non-retryable",
+              reason: "pi resumed a different authoritative session than requested"
+            });
+          }
+          return new PiSession(sessionRef, rpc, manifestSelection);
+        }
       }
-    }
-    return new PiSession(sessionRef, rpc, selection);
+    };
   }
   resolveBin() {
     return (this.options.resolveBin ?? resolvePiBin)();
   }
 };
-async function resolveFreshSessionId(rpc) {
+function sameDispatchSelection(left, right) {
+  if (left === void 0 || right === void 0) return left === right;
+  return left.lane === right.lane && left.runtimeId === right.runtimeId && left.providerId === right.providerId && left.modelId === right.modelId;
+}
+async function resolveAuthoritativeSessionId(rpc) {
   let state;
   try {
     state = await rpc.send({ type: "get_state" });
   } catch (err) {
-    throw new Error(`pi did not yield an authoritative session id (get_state failed): ${errorMessage(err)}`, {
+    if (isRuntimeExecutionFailure(err)) throw err;
+    throw new RuntimeExecutionFailure({
+      phase: "start",
+      category: "infrastructure",
+      retry: "retryable",
+      reason: `pi transport ended before yielding an authoritative session id: ${errorMessage(err)}`
+    }, {
       cause: err
     });
   }
   if (state.success === false) {
     const reason = typeof state.error === "string" ? state.error : "get_state reported failure";
-    throw new Error(`pi did not yield an authoritative session id (get_state failed): ${reason}`);
+    throw new RuntimeExecutionFailure({
+      phase: "start",
+      category: "authority",
+      retry: "non-retryable",
+      reason: `pi did not yield an authoritative session id: ${reason}`
+    });
   }
   const data = state.data;
   if (typeof data?.sessionId === "string" && data.sessionId.length > 0) {
     return data.sessionId;
   }
-  throw new Error(
-    "pi did not yield an authoritative session id (get_state succeeded but reported no sessionId) \u2014 cannot mint a resumable session"
-  );
+  throw new RuntimeExecutionFailure({
+    phase: "start",
+    category: "authority",
+    retry: "non-retryable",
+    reason: "pi get_state reported no authoritative session id"
+  });
 }
 var PiSession = class {
   constructor(sessionRef, rpc, selection) {
@@ -641,12 +947,40 @@ var PiSession = class {
     return {
       [Symbol.asyncIterator]() {
         const inner = rpc.events[Symbol.asyncIterator]();
+        let terminalFailure;
         return {
           async next() {
             for (; ; ) {
-              const { value, done } = await inner.next();
-              if (done) return { value: void 0, done: true };
+              if (terminalFailure) throw terminalFailure;
+              let result;
+              try {
+                result = await inner.next();
+              } catch (cause) {
+                throw new RuntimeExecutionFailure({
+                  phase: "run",
+                  category: "infrastructure",
+                  retry: "retryable",
+                  reason: "pi runtime event transport failed"
+                }, { cause });
+              }
+              const { value, done } = result;
+              if (done) {
+                throw new RuntimeExecutionFailure({
+                  phase: "run",
+                  category: "infrastructure",
+                  retry: "retryable",
+                  reason: "pi runtime process ended before agent_settled"
+                }, { cause: rpc.terminalError });
+              }
               const mapped = mapPiMessageToAgentEvent(value);
+              if (value.type === "auto_retry_end" && value.success === false) {
+                terminalFailure = new RuntimeExecutionFailure({
+                  phase: "run",
+                  category: "semantic",
+                  retry: "non-retryable",
+                  reason: "pi exhausted its native retry policy"
+                });
+              }
               if (mapped) return { value: mapped, done: false };
               if (!ROUTINE_PI_EVENT_TYPES.has(value.type)) {
                 rpc.recordUnmappedFrame(value.type);
@@ -676,7 +1010,7 @@ var PiSession = class {
     await this.rpc.send({ type: "abort" });
   }
   async close() {
-    this.rpc.kill();
+    await this.rpc.dispose();
   }
   async resolveApproval() {
     throw new Error("pi adapter does not support approval resume: pi never emits needs_approval in M0/M1");
@@ -888,7 +1222,15 @@ function mapResult(msg) {
     diagnostic ? `claude result frame had a missing/invalid is_error flag (got ${JSON.stringify(msg.is_error)}) \u2014 treating as failure, fail-closed; diagnostic content on the frame: ${truncateResultDiagnostic(diagnostic)}` : `claude result frame had a missing/invalid is_error flag (got ${JSON.stringify(msg.is_error)}) \u2014 treating as failure, fail-closed`
   );
   const events = usageEvent ? [usageEvent, { type: "error", message }] : [{ type: "error", message }];
-  return { events };
+  return {
+    events,
+    terminalFailure: new RuntimeExecutionFailure({
+      phase: "run",
+      category: msg.is_error === true ? "semantic" : "authority",
+      retry: "non-retryable",
+      reason: msg.is_error === true ? "claude reported terminal task failure" : "claude emitted a malformed terminal result frame"
+    })
+  };
 }
 var RESULT_DIAGNOSTIC_MAX_CHARS = 2e3;
 function truncateResultDiagnostic(text) {
@@ -940,16 +1282,22 @@ var ClaudeProcessClient = class {
   eventQueue = new AsyncQueue();
   closed = false;
   exitError;
+  closedPromise;
+  resolveClosed;
+  disposalAttempt;
   stderrRing = [];
   unmappedFrameCounts = /* @__PURE__ */ new Map();
   sessionId;
   initWaiter;
   constructor(options) {
     const spawnFn = options.spawnFn ?? spawn;
-    this.child = spawnFn(options.command, options.args, {
+    this.child = spawnFn(options.command, options.args, withOwnedProcessTree({
       cwd: options.cwd,
       env: options.env,
       stdio: ["pipe", "pipe", "pipe"]
+    }));
+    this.closedPromise = new Promise((resolve) => {
+      this.resolveClosed = resolve;
     });
     this.child.stdout.setEncoding("utf8");
     this.child.stdout.on("data", (chunk) => this.onData(chunk));
@@ -1005,6 +1353,10 @@ var ClaudeProcessClient = class {
   get events() {
     return this.eventQueue;
   }
+  /** Local transport diagnostic retained when the process closes; consumers classify it at the session boundary. */
+  get terminalError() {
+    return this.exitError;
+  }
   /**
    * Record a claude stream-json frame/subtype/content-block label that
    * `ClaudeSession`'s event iterator (`../claude-adapter.ts`) decided has
@@ -1024,15 +1376,30 @@ var ClaudeProcessClient = class {
       );
     }
   }
-  /** Best-effort teardown. SIGTERM on POSIX; `taskkill /T /F` on Windows to also reap child processes claude itself spawned (e.g. Bash) — mirrors pi's cross-platform `kill()` exactly. Empirically confirmed on this (POSIX) machine: a running claude process exits cleanly within ~1s of SIGTERM (observed exit code 143 = 128+SIGTERM, i.e. claude catches and handles the signal itself rather than needing a harder kill). */
+  /** Immediate process-tree termination request. `dispose()` is the settlement receipt. */
   kill() {
-    if (this.closed) return;
-    const pid = this.child.pid;
-    if (process.platform === "win32" && pid !== void 0) {
-      spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"]);
-    } else {
-      this.child.kill("SIGTERM");
+    requestOwnedProcessTreeTermination(this.processTreeOptions());
+  }
+  waitClosed() {
+    return this.closedPromise;
+  }
+  dispose() {
+    if (!this.disposalAttempt) {
+      const attempt = disposeOwnedProcessTree(this.processTreeOptions());
+      this.disposalAttempt = attempt.catch((error) => {
+        this.disposalAttempt = void 0;
+        throw error;
+      });
     }
+    return this.disposalAttempt;
+  }
+  processTreeOptions() {
+    return {
+      child: this.child,
+      waitClosed: () => this.closedPromise,
+      isClosed: () => this.closed,
+      label: "claude"
+    };
   }
   onData(chunk) {
     this.buffer += chunk;
@@ -1083,6 +1450,7 @@ var ClaudeProcessClient = class {
     if (this.closed) return;
     this.closed = true;
     this.exitError = err;
+    this.resolveClosed();
     this.initWaiter?.reject(err);
     this.initWaiter = void 0;
     this.eventQueue.end();
@@ -1094,18 +1462,37 @@ var APPROVAL_TOOL_NAME = "approval_prompt";
 var APPROVAL_MCP_SERVER_NAME = "byokapproval";
 var execFileAsync2 = promisify(execFile);
 var DETECT_TIMEOUT_MS2 = 5e3;
+function errorMessage2(err) {
+  return err instanceof Error ? err.message : String(err);
+}
 async function cleanupMcpConfigDir(dir) {
   if (!dir) return;
-  await promises.rm(dir, { recursive: true, force: true }).catch(() => {
-  });
+  try {
+    await promises.rm(dir, { recursive: true, force: true });
+  } catch (cause) {
+    throw new RuntimeDisposalFailure({
+      stage: "cleanup",
+      reason: "claude task-scoped MCP configuration could not be removed"
+    }, { cause });
+  }
 }
 var ClaudeAdapter = class {
   constructor(options = {}) {
     this.options = options;
   }
   options;
-  supportsDispatchSelection = true;
-  id = "claude";
+  descriptor = freezeRuntimeAdapterDescriptor({
+    id: "claude",
+    supportsDispatchSelection: true,
+    capabilities: {
+      steer: false,
+      resume: true,
+      approvalInteractive: true,
+      mcpToolsets: true,
+      permissionModes: ["auto", "readonly", "plan", "confirm"]
+    },
+    environmentRequirements: { credentialNames: [] }
+  });
   async detect() {
     const bin = this.resolveBin();
     try {
@@ -1117,54 +1504,73 @@ var ClaudeAdapter = class {
       return { present: false };
     }
   }
-  capabilities() {
+  async prepare(input) {
+    const mapping = mapPermissionPolicyToClaudeArgs(input.policy);
+    if (!mapping.ok) return { kind: "reject", reason: mapping.reason ?? "policy rejected by claude adapter", retryable: false };
+    let modelId;
+    try {
+      modelId = subscriptionModel(input.offer.dispatchSelection, "claude");
+    } catch (error) {
+      return { kind: "reject", reason: error instanceof Error ? error.message : String(error), retryable: false };
+    }
+    if (mapping.needsApprovalMcp && Object.prototype.hasOwnProperty.call(input.mcpServers ?? {}, APPROVAL_MCP_SERVER_NAME)) {
+      return { kind: "reject", reason: `MCP server name "${APPROVAL_MCP_SERVER_NAME}" is reserved by the claude approval channel`, retryable: false };
+    }
+    let bin;
+    try {
+      bin = this.resolveBin();
+    } catch (error) {
+      return { kind: "reject", reason: error instanceof Error ? error.message : String(error), retryable: true };
+    }
+    let approvalMcpBin;
+    if (mapping.needsApprovalMcp) {
+      try {
+        approvalMcpBin = (this.options.resolveApprovalMcpBin ?? resolveApprovalMcpBin)();
+      } catch (error) {
+        return { kind: "reject", reason: error instanceof Error ? error.message : String(error), retryable: true };
+      }
+    }
     return {
-      steer: false,
-      resume: true,
-      approvalInteractive: true,
-      mcpToolsets: true,
-      permissionModes: ["auto", "readonly", "plan", "confirm"]
+      kind: "prepared",
+      operation: {
+        start: (startInput) => this.startPrepared(startInput, mapping, modelId, bin, approvalMcpBin)
+      }
     };
   }
-  /**
-   * M5: deliberate product-boundary decision, not an oversight — byok's
-   * current ToS posture for claude is login-state-only (`claude auth
-   * login`'s own OAuth session — see `probeAuthPresent` below), so this
-   * adapter declares NO credential env vars at all; env-based API-key
-   * passthrough for claude is a separate, still-pending product decision.
-   * A product that genuinely needs it can opt in locally per-device via
-   * `DaemonConfig.runtimeEnvironment.claude.allow` (`create-daemon.ts`).
-   * `baseNames` is empty too: nothing in this adapter reads a
-   * claude-specific config-discovery variable (e.g. `CLAUDE_CONFIG_DIR`)
-   * today — if a future version of this adapter starts reading one, it
-   * belongs here, not left to rely on the platform baseline alone.
-   */
-  environmentRequirements() {
-    return { credentialNames: [] };
-  }
-  async start(task, ctx) {
-    if (typeof task.instruction !== "string") {
-      throw new PolicyUnsupportedError("claude adapter only supports string instructions in M2 (no blob-ref fetch yet)");
-    }
-    const mapping = mapPermissionPolicyToClaudeArgs(ctx.policy);
-    if (!mapping.ok) {
-      throw new PolicyUnsupportedError(mapping.reason ?? "policy rejected by claude adapter");
+  async startPrepared(startInput, initialMapping, modelId, bin, approvalMcpBin) {
+    if (!initialMapping.ok) throw new RuntimeExecutionFailure({
+      phase: "start",
+      category: "authority",
+      retry: "non-retryable",
+      reason: "prepared claude permission mapping was invalid"
+    });
+    if (typeof startInput.instruction !== "string") {
+      throw new RuntimeExecutionFailure({
+        phase: "start",
+        category: "authority",
+        retry: "non-retryable",
+        reason: "prepared claude operation requires a resolved string instruction"
+      });
     }
-    const modelId = subscriptionModel(task, "claude");
+    const mapping = { ...initialMapping, args: [...initialMapping.args] };
     let mcpConfigDir;
-    const taskMcpServers = ctx.mcpServers ?? {};
+    const taskMcpServers = startInput.mcpServers ?? {};
     const needsMcpConfig = mapping.needsApprovalMcp || Object.keys(taskMcpServers).length > 0;
     if (mapping.needsApprovalMcp) {
-      if (!ctx.approvalChannel) {
-        throw new PolicyUnsupportedError(
-          'claude adapter requires policy.mode "confirm" to be started with an approval channel (TaskContext.approvalChannel) \u2014 none was provided'
-        );
-      }
-      if (Object.prototype.hasOwnProperty.call(taskMcpServers, APPROVAL_MCP_SERVER_NAME)) {
-        throw new PolicyUnsupportedError(
-          `MCP server name "${APPROVAL_MCP_SERVER_NAME}" is reserved by the claude approval channel`
-        );
+      if (!startInput.approvalChannel) {
+        throw new RuntimeExecutionFailure({
+          phase: "start",
+          category: "authority",
+          retry: "non-retryable",
+          reason: 'claude adapter requires policy.mode "confirm" to be started with an approval channel'
+        });
       }
+      if (!approvalMcpBin) throw new RuntimeExecutionFailure({
+        phase: "start",
+        category: "authority",
+        retry: "non-retryable",
+        reason: "prepared claude approval MCP binary was not resolved"
+      });
     }
     if (needsMcpConfig) {
       mcpConfigDir = await promises.mkdtemp(path3.join(os.tmpdir(), "byok-mcp-"));
@@ -1173,12 +1579,23 @@ var ClaudeAdapter = class {
       const mcpConfigPath = path3.join(mcpConfigDir, "mcp-config.json");
       const mcpServers = { ...taskMcpServers };
       if (mapping.needsApprovalMcp) {
-        const approvalChannel = ctx.approvalChannel;
-        if (!approvalChannel) throw new Error("unreachable: approval channel checked above");
-        const approvalMcpBin = (this.options.resolveApprovalMcpBin ?? resolveApprovalMcpBin)();
+        const approvalChannel = startInput.approvalChannel;
+        if (!approvalChannel) throw new RuntimeExecutionFailure({
+          phase: "start",
+          category: "authority",
+          retry: "non-retryable",
+          reason: "prepared claude approval channel was not available"
+        });
+        const preparedApprovalMcpBin = approvalMcpBin;
+        if (!preparedApprovalMcpBin) throw new RuntimeExecutionFailure({
+          phase: "start",
+          category: "authority",
+          retry: "non-retryable",
+          reason: "prepared claude approval MCP binary was not resolved"
+        });
         mcpServers[APPROVAL_MCP_SERVER_NAME] = {
-          command: approvalMcpBin.command,
-          args: approvalMcpBin.args,
+          command: preparedApprovalMcpBin.command,
+          args: preparedApprovalMcpBin.args,
           env: {
             BYOK_STORE_DIR: approvalChannel.storeDir,
             BYOK_PRODUCT_ID: approvalChannel.productId,
@@ -1198,8 +1615,26 @@ var ClaudeAdapter = class {
         "--strict-mcp-config"
       ];
     }
-    const bin = this.resolveBin();
-    const resumeSessionId = task.sessionRef;
+    const resumeSessionId = startInput.manifest.sessionRef;
+    let manifestModelId;
+    try {
+      manifestModelId = subscriptionModel(startInput.manifest.dispatchSelection, "claude");
+    } catch (cause) {
+      throw new RuntimeExecutionFailure({
+        phase: "start",
+        category: "authority",
+        retry: "non-retryable",
+        reason: "prepared claude operation received an invalid runtime selection manifest"
+      }, { cause });
+    }
+    if (manifestModelId !== modelId) {
+      throw new RuntimeExecutionFailure({
+        phase: "start",
+        category: "authority",
+        retry: "non-retryable",
+        reason: "prepared claude operation received a manifest with different runtime selection"
+      });
+    }
     const args = [
       "-p",
       "--input-format",
@@ -1211,40 +1646,71 @@ var ClaudeAdapter = class {
       // "Error: When using --print, --output-format=stream-json requires
       // --verbose", before spawning any model call.
       "--verbose",
-      ...modelId ? ["--model", modelId] : [],
+      ...manifestModelId ? ["--model", manifestModelId] : [],
       ...resumeSessionId ? ["--resume", resumeSessionId] : [],
       ...mapping.args
     ];
-    const client = new ClaudeProcessClient({
-      command: bin.command,
-      args,
-      cwd: ctx.workspaceDir,
-      env: withoutProviderCredentials(ctx.env),
-      spawnFn: this.options.spawnFn
-    });
-    client.writeUserMessage(task.instruction);
+    let client;
+    try {
+      client = new ClaudeProcessClient({
+        command: bin.command,
+        args,
+        cwd: startInput.manifest.workspace.workspaceDir,
+        env: withoutProviderCredentials(startInput.env),
+        spawnFn: this.options.spawnFn
+      });
+    } catch (cause) {
+      await cleanupMcpConfigDir(mcpConfigDir);
+      throw new RuntimeExecutionFailure({
+        phase: "start",
+        category: "infrastructure",
+        retry: "retryable",
+        reason: "claude runtime process could not be spawned"
+      }, { cause });
+    }
+    try {
+      client.writeUserMessage(startInput.instruction);
+    } catch (cause) {
+      client.kill();
+      await cleanupMcpConfigDir(mcpConfigDir);
+      throw new RuntimeExecutionFailure({
+        phase: "start",
+        category: "infrastructure",
+        retry: "retryable",
+        reason: "claude initial instruction transport failed"
+      }, { cause });
+    }
     let sessionRef;
     try {
       sessionRef = await client.waitForInit();
     } catch (err) {
       client.kill();
       await cleanupMcpConfigDir(mcpConfigDir);
-      throw err;
+      if (isRuntimeExecutionFailure(err)) throw err;
+      throw new RuntimeExecutionFailure({
+        phase: "start",
+        category: "infrastructure",
+        retry: "retryable",
+        reason: `claude exited before yielding an authoritative session id: ${errorMessage2(err)}`
+      }, { cause: err });
     }
     if (resumeSessionId !== void 0 && sessionRef !== resumeSessionId) {
       client.kill();
       await cleanupMcpConfigDir(mcpConfigDir);
-      throw new Error(
-        `claude --resume echoed a different session id than requested (requested ${resumeSessionId}, got ${sessionRef}) \u2014 refusing to continue in a possibly-wrong session (fail-closed)`
-      );
+      throw new RuntimeExecutionFailure({
+        phase: "start",
+        category: "authority",
+        retry: "non-retryable",
+        reason: `claude --resume echoed a different session id than requested (requested ${resumeSessionId}, got ${sessionRef})`
+      });
     }
     return new ClaudeSession(
       sessionRef,
       client,
-      ctx.workspaceDir,
-      ctx.approvalChannel,
+      startInput.manifest.workspace.workspaceDir,
+      startInput.approvalChannel,
       mcpConfigDir,
-      modelId
+      manifestModelId
     );
   }
   /**
@@ -1279,8 +1745,7 @@ var ClaudeAdapter = class {
     return (this.options.resolveBin ?? resolveClaudeBin)();
   }
 };
-function subscriptionModel(task, runtimeId) {
-  const selection = task.dispatchSelection;
+function subscriptionModel(selection, runtimeId) {
   if (selection === void 0) return void 0;
   if (selection.lane !== "subscription" || selection.runtimeId !== runtimeId) {
     throw new PolicyUnsupportedError(
@@ -1305,6 +1770,7 @@ var ClaudeSession = class {
   mcpConfigDir;
   modelId;
   correlation = createToolUseCorrelation();
+  closeAttempt;
   get events() {
     const client = this.client;
     const correlation = this.correlation;
@@ -1313,17 +1779,40 @@ var ClaudeSession = class {
       [Symbol.asyncIterator]() {
         const inner = client.events[Symbol.asyncIterator]();
         let pending = [];
+        let terminalFailure;
         let turnSettled = false;
         return {
           async next() {
             for (; ; ) {
               const buffered = pending.shift();
               if (buffered) return { value: buffered, done: false };
-              if (turnSettled) return { value: void 0, done: true };
-              const { value, done } = await inner.next();
-              if (done) return { value: void 0, done: true };
+              if (turnSettled) {
+                if (terminalFailure) throw terminalFailure;
+                return { value: void 0, done: true };
+              }
+              let raw;
+              try {
+                raw = await inner.next();
+              } catch (cause) {
+                throw new RuntimeExecutionFailure({
+                  phase: "run",
+                  category: "infrastructure",
+                  retry: "retryable",
+                  reason: "claude runtime event transport failed"
+                }, { cause });
+              }
+              const { value, done } = raw;
+              if (done) {
+                throw new RuntimeExecutionFailure({
+                  phase: "run",
+                  category: "infrastructure",
+                  retry: "retryable",
+                  reason: "claude runtime process ended before a terminal result frame"
+                }, { cause: client.terminalError });
+              }
               if (value.type === "result") turnSettled = true;
               const mapped = mapClaudeMessageToAgentEvents(value, correlation, { workspaceDir });
+              terminalFailure = mapped.terminalFailure ?? terminalFailure;
               if (mapped.unmappedLabel) {
                 client.recordUnmappedFrame(mapped.unmappedLabel);
               }
@@ -1354,7 +1843,7 @@ var ClaudeSession = class {
     if (typeof task.instruction !== "string") {
       throw new PolicyUnsupportedError("claude adapter only supports string instructions in M2 (no blob-ref fetch yet)");
     }
-    const requestedModel = subscriptionModel(task, "claude");
+    const requestedModel = subscriptionModel(task.dispatchSelection, "claude");
     if (requestedModel !== void 0 && requestedModel !== this.modelId) {
       throw new PolicyUnsupportedError(
         `claude persistent session cannot change model from ${this.modelId ?? "(legacy default)"} to ${requestedModel}`
@@ -1378,8 +1867,17 @@ var ClaudeSession = class {
     this.client.kill();
   }
   async close() {
-    this.client.kill();
-    await cleanupMcpConfigDir(this.mcpConfigDir);
+    if (!this.closeAttempt) {
+      const attempt = (async () => {
+        await this.client.dispose();
+        await cleanupMcpConfigDir(this.mcpConfigDir);
+      })();
+      this.closeAttempt = attempt.catch((error) => {
+        this.closeAttempt = void 0;
+        throw error;
+      });
+    }
+    await this.closeAttempt;
   }
   /**
    * M4 Phase 3: routes into the out-of-band approval channel `start()`
@@ -1596,14 +2094,15 @@ var CodexProcessRunner = class {
   exitSignal = null;
   closedPromise;
   resolveClosed;
+  disposalAttempt;
   constructor(options) {
     this.onEvent = options.onEvent;
     const spawnFn = options.spawnFn ?? spawn;
-    this.child = spawnFn(options.command, options.args, {
+    this.child = spawnFn(options.command, options.args, withOwnedProcessTree({
       cwd: options.cwd,
       env: options.env,
       stdio: ["ignore", "pipe", "pipe"]
-    });
+    }));
     this.closedPromise = new Promise((resolve) => {
       this.resolveClosed = resolve;
     });
@@ -1633,7 +2132,7 @@ var CodexProcessRunner = class {
     return this.closed;
   }
   /**
-   * Best-effort teardown. SIGTERM on POSIX: SIGINT was empirically confirmed
+   * Immediate tree termination request. SIGTERM on POSIX: SIGINT was empirically confirmed
    * to be silently ignored by `codex exec` (a real, direct test — a 60s
    * shell `sleep` ran to full, unaffected completion despite SIGINT sent at
    * t=4s) — a genuine, evidence-based correction to this task's own initial
@@ -1646,13 +2145,25 @@ var CodexProcessRunner = class {
    * `../pi/rpc-client.ts`'s own cross-platform convention.
    */
   kill() {
-    if (this.closed) return;
-    const pid = this.child.pid;
-    if (process.platform === "win32" && pid !== void 0) {
-      spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"]);
-    } else {
-      this.child.kill("SIGTERM");
+    requestOwnedProcessTreeTermination(this.processTreeOptions());
+  }
+  dispose() {
+    if (!this.disposalAttempt) {
+      const attempt = disposeOwnedProcessTree(this.processTreeOptions());
+      this.disposalAttempt = attempt.catch((error) => {
+        this.disposalAttempt = void 0;
+        throw error;
+      });
     }
+    return this.disposalAttempt;
+  }
+  processTreeOptions() {
+    return {
+      child: this.child,
+      waitClosed: () => this.closedPromise,
+      isClosed: () => this.closed,
+      label: "codex"
+    };
   }
   /** Builds a descriptive error folding in the exit code/signal and the stderr tail — mirrors `PiRpcClient.buildExitError`'s reasoning: a post-mortem on a failed start/resume should never need separately re-running codex by hand with a raw JSONL logger to learn why. */
   buildExitError(context) {
@@ -1703,8 +2214,17 @@ var CodexAdapter = class {
     this.options = options;
   }
   options;
-  supportsDispatchSelection = true;
-  id = "codex";
+  descriptor = freezeRuntimeAdapterDescriptor({
+    id: "codex",
+    supportsDispatchSelection: true,
+    capabilities: {
+      steer: false,
+      resume: true,
+      approvalInteractive: false,
+      permissionModes: ["auto", "readonly"]
+    },
+    environmentRequirements: { credentialNames: [] }
+  });
   async detect() {
     const bin = this.resolveBin();
     try {
@@ -1753,61 +2273,100 @@ ${result.stderr}`);
 ${withStreams.stderr ?? ""}`);
     }
   }
-  capabilities() {
-    return { steer: false, resume: true, approvalInteractive: false, permissionModes: ["auto", "readonly"] };
-  }
-  /**
-   * M5: same deliberate posture as the claude adapter (see its own doc
-   * comment) — codex authenticates via its own `codex login`-managed
-   * ChatGPT OAuth session (`probeAuthPresent` above), not an env var, so
-   * there is no credential env var this adapter needs forwarded; env-based
-   * API-key passthrough remains a separate, pending product decision. No
-   * `baseNames` either: nothing in this adapter reads a codex-specific
-   * config-discovery variable (e.g. `CODEX_HOME`) today.
-   */
-  environmentRequirements() {
-    return { credentialNames: [] };
-  }
-  async start(task, ctx) {
-    if (typeof task.instruction !== "string") {
-      throw new PolicyUnsupportedError("codex adapter only supports string instructions in M2 (no blob-ref fetch yet)");
+  async prepare(input) {
+    const mapping = mapPermissionPolicyToCodexArgs(input.policy);
+    if (!mapping.ok) return { kind: "reject", reason: mapping.reason ?? "policy rejected by codex adapter", retryable: false };
+    let modelId;
+    try {
+      modelId = subscriptionModel2(input.offer.dispatchSelection);
+    } catch (error) {
+      return { kind: "reject", reason: error instanceof Error ? error.message : String(error), retryable: false };
     }
-    const mapping = mapPermissionPolicyToCodexArgs(ctx.policy);
-    if (!mapping.ok) {
-      throw new PolicyUnsupportedError(mapping.reason ?? "policy rejected by codex adapter");
+    let command;
+    try {
+      command = this.resolveBin().command;
+    } catch (error) {
+      return { kind: "reject", reason: error instanceof Error ? error.message : String(error), retryable: true };
+    }
+    return {
+      kind: "prepared",
+      operation: {
+        start: (startInput) => this.startPrepared(startInput, mapping.args, modelId, command)
+      }
+    };
+  }
+  async startPrepared(startInput, policyArgs, modelId, command) {
+    if (typeof startInput.instruction !== "string") {
+      throw new RuntimeExecutionFailure({
+        phase: "start",
+        category: "authority",
+        retry: "non-retryable",
+        reason: "prepared codex operation requires a resolved string instruction"
+      });
     }
-    const modelId = subscriptionModel2(task);
-    const bin = this.resolveBin();
     const queue = new AsyncQueue();
+    const terminal = {};
     const recordUnmapped = makeUnmappedFrameRecorder(/* @__PURE__ */ new Map());
-    const workspaceDir = await resolveRealWorkspaceDir(ctx.workspaceDir);
-    const runtimeEnv = withoutProviderCredentials(ctx.env);
+    let workspaceDir;
+    try {
+      workspaceDir = await resolveRealWorkspaceDir(startInput.manifest.workspace.workspaceDir);
+    } catch (cause) {
+      throw new RuntimeExecutionFailure({
+        phase: "start",
+        category: "infrastructure",
+        retry: "retryable",
+        reason: "codex runtime workspace could not be resolved"
+      }, { cause });
+    }
+    const runtimeEnv = withoutProviderCredentials(startInput.env);
+    let manifestModelId;
+    try {
+      manifestModelId = subscriptionModel2(startInput.manifest.dispatchSelection);
+    } catch (cause) {
+      throw new RuntimeExecutionFailure({
+        phase: "start",
+        category: "authority",
+        retry: "non-retryable",
+        reason: "prepared codex operation received an invalid runtime selection manifest"
+      }, { cause });
+    }
+    if (manifestModelId !== modelId) {
+      throw new RuntimeExecutionFailure({
+        phase: "start",
+        category: "authority",
+        retry: "non-retryable",
+        reason: "prepared codex operation received a manifest with different runtime selection"
+      });
+    }
     const { sessionRef, runner } = await runCodexTurn({
-      command: bin.command,
-      resumeRef: task.sessionRef,
-      instruction: task.instruction,
-      modelId,
-      policyArgs: mapping.args,
-      cwd: ctx.workspaceDir,
+      command,
+      resumeRef: startInput.manifest.sessionRef,
+      instruction: startInput.instruction,
+      modelId: manifestModelId,
+      policyArgs: [...policyArgs],
+      cwd: startInput.manifest.workspace.workspaceDir,
       env: runtimeEnv,
       spawnFn: this.options.spawnFn,
       workspaceDir,
       queue,
       recordUnmapped,
-      expectedSessionRef: task.sessionRef,
-      preparedGit: ctx.gitWorkspace !== void 0
+      expectedSessionRef: startInput.manifest.sessionRef,
+      preparedGit: startInput.manifest.workspace.workspaceId !== void 0,
+      failurePhase: "start",
+      terminal
     });
     return new CodexSession({
       sessionRef,
-      command: bin.command,
+      command,
       workspaceDir,
-      env: ctx.env,
+      env: startInput.env,
       spawnFn: this.options.spawnFn,
       queue,
       recordUnmapped,
       initialRunner: runner,
-      preparedGit: ctx.gitWorkspace !== void 0,
-      modelId
+      preparedGit: startInput.manifest.workspace.workspaceId !== void 0,
+      modelId: manifestModelId,
+      terminal
     });
   }
   resolveBin() {
@@ -1855,37 +2414,69 @@ async function runCodexTurn(params) {
     rejectFirstLine = reject;
   });
   let turnEnded = false;
-  const runner = new CodexProcessRunner({
-    command: params.command,
-    args: argv,
-    cwd: params.cwd,
-    env: params.env,
-    spawnFn: params.spawnFn,
-    onEvent: (evt) => {
-      if (!firstLineSettled) {
-        firstLineSettled = true;
-        if (evt.type === "thread.started" && typeof evt.thread_id === "string" && evt.thread_id.length > 0) {
-          resolveFirstLine(evt.thread_id);
-        } else {
-          rejectFirstLine(
-            new Error(`codex did not yield thread.started as its first event (got ${JSON.stringify(evt).slice(0, 200)})`)
-          );
+  let runner;
+  try {
+    runner = new CodexProcessRunner({
+      command: params.command,
+      args: argv,
+      cwd: params.cwd,
+      env: params.env,
+      spawnFn: params.spawnFn,
+      onEvent: (evt) => {
+        if (!firstLineSettled) {
+          firstLineSettled = true;
+          if (evt.type === "thread.started" && typeof evt.thread_id === "string" && evt.thread_id.length > 0) {
+            resolveFirstLine(evt.thread_id);
+          } else {
+            rejectFirstLine(
+              new RuntimeExecutionFailure({
+                phase: params.failurePhase,
+                category: "authority",
+                retry: "non-retryable",
+                reason: `codex did not yield thread.started as its first event (got ${JSON.stringify(evt).slice(0, 200)})`
+              })
+            );
+          }
+          return;
+        }
+        const mapped = mapCodexEventToAgentEvents(evt, params.workspaceDir);
+        for (const agentEvent of mapped) {
+          if (agentEvent.type === "turn_end") turnEnded = true;
+          params.queue.push(agentEvent);
+        }
+        if (evt.type === "turn.failed") {
+          params.terminal.failure = new RuntimeExecutionFailure({
+            phase: "run",
+            category: "semantic",
+            retry: "non-retryable",
+            reason: "codex reported terminal task failure"
+          });
+          params.queue.end();
+        }
+        if (mapped.length === 0 && !isRoutineCodexEvent(evt)) {
+          params.recordUnmapped(unmappedFrameKey(evt));
         }
-        return;
-      }
-      const mapped = mapCodexEventToAgentEvents(evt, params.workspaceDir);
-      for (const agentEvent of mapped) {
-        if (agentEvent.type === "turn_end") turnEnded = true;
-        params.queue.push(agentEvent);
-      }
-      if (mapped.length === 0 && !isRoutineCodexEvent(evt)) {
-        params.recordUnmapped(unmappedFrameKey(evt));
       }
-    }
-  });
+    });
+  } catch (cause) {
+    throw new RuntimeExecutionFailure({
+      phase: params.failurePhase,
+      category: "infrastructure",
+      retry: "retryable",
+      reason: "codex runtime process could not be spawned"
+    }, { cause });
+  }
+  params.onRunnerCreated?.(runner);
   void runner.waitClosed().then(() => {
-    if (turnEnded) return;
-    params.queue.push({ type: "error", message: runner.buildExitError("codex exited without completing the turn").message });
+    if (turnEnded || params.terminal.failure) return;
+    const cause = runner.buildExitError("codex exited without completing the turn");
+    params.terminal.failure = new RuntimeExecutionFailure({
+      phase: "run",
+      category: "infrastructure",
+      retry: "retryable",
+      reason: cause.message
+    }, { cause });
+    params.queue.push({ type: "error", message: cause.message });
     params.queue.end();
   });
   let sessionRef;
@@ -1909,7 +2500,13 @@ async function runCodexTurn(params) {
       void runner.waitClosed().then(() => {
         if (!settled) {
           settled = true;
-          reject(runner.buildExitError("codex exited before yielding an authoritative thread id"));
+          const cause = runner.buildExitError("codex exited before yielding an authoritative thread id");
+          reject(new RuntimeExecutionFailure({
+            phase: params.failurePhase,
+            category: "infrastructure",
+            retry: "retryable",
+            reason: cause.message
+          }, { cause }));
         }
       });
     });
@@ -1919,9 +2516,12 @@ async function runCodexTurn(params) {
   }
   if (params.expectedSessionRef !== void 0 && sessionRef !== params.expectedSessionRef) {
     runner.kill();
-    throw new Error(
-      `codex exec resume echoed a different thread id than requested (requested ${params.expectedSessionRef}, got ${sessionRef}) \u2014 refusing to continue in a possibly-wrong session (fail-closed)`
-    );
+    throw 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})`
+    });
   }
   return { sessionRef, runner };
 }
@@ -1948,8 +2548,12 @@ var CodexSession = class {
   recordUnmapped;
   preparedGit;
   modelId;
+  terminal;
   currentRunner;
+  ownedRunners = /* @__PURE__ */ new Set();
+  followUpAttempts = /* @__PURE__ */ new Set();
   closed = false;
+  closeAttempt;
   constructor(options) {
     this.sessionRef = options.sessionRef;
     this.command = options.command;
@@ -1960,11 +2564,36 @@ var CodexSession = class {
     this.recordUnmapped = options.recordUnmapped;
     this.preparedGit = options.preparedGit;
     this.modelId = options.modelId;
+    this.terminal = options.terminal;
     this.currentRunner = options.initialRunner;
+    this.ownedRunners.add(options.initialRunner);
     void this.forgetRunnerOnceClosed(options.initialRunner);
   }
   get events() {
-    return this.queue;
+    const queue = this.queue;
+    const session = this;
+    return {
+      [Symbol.asyncIterator]() {
+        const inner = queue[Symbol.asyncIterator]();
+        return {
+          async next() {
+            let result;
+            try {
+              result = await inner.next();
+            } catch (cause) {
+              throw new RuntimeExecutionFailure({
+                phase: "run",
+                category: "infrastructure",
+                retry: "retryable",
+                reason: "codex runtime event transport failed"
+              }, { cause });
+            }
+            if (result.done && session.terminal.failure) throw session.terminal.failure;
+            return result;
+          }
+        };
+      }
+    };
   }
   async forgetRunnerOnceClosed(runner) {
     await runner.waitClosed();
@@ -2009,7 +2638,14 @@ var CodexSession = class {
    * stale id even after codex had moved on) — it just can now only ever be
    * the SAME id this call asked to resume, never a silently-different one.
    */
-  async followUp(task) {
+  followUp(task) {
+    const attempt = this.runFollowUp(task);
+    this.followUpAttempts.add(attempt);
+    void attempt.finally(() => this.followUpAttempts.delete(attempt)).catch(() => {
+    });
+    return attempt;
+  }
+  async runFollowUp(task) {
     if (typeof task.instruction !== "string") {
       throw new PolicyUnsupportedError("codex adapter only supports string instructions in M2 (no blob-ref fetch yet)");
     }
@@ -2020,7 +2656,7 @@ var CodexSession = class {
     if (!mapping.ok) {
       throw new PolicyUnsupportedError(mapping.reason ?? "policy rejected by codex adapter");
     }
-    const requestedModel = subscriptionModel2(task);
+    const requestedModel = subscriptionModel2(task.dispatchSelection);
     if (requestedModel !== void 0 && requestedModel !== this.modelId) {
       throw new PolicyUnsupportedError(
         `codex persistent session cannot change model from ${this.modelId ?? "(legacy default)"} to ${requestedModel}`
@@ -2030,6 +2666,7 @@ var CodexSession = class {
     const resumeRef = this.sessionRef;
     let sessionRef;
     let runner;
+    const terminal = {};
     try {
       ({ sessionRef, runner } = await runCodexTurn({
         command: this.command,
@@ -2044,25 +2681,54 @@ var CodexSession = class {
         queue: this.queue,
         recordUnmapped: this.recordUnmapped,
         expectedSessionRef: resumeRef,
-        preparedGit: this.preparedGit
+        preparedGit: this.preparedGit,
+        failurePhase: "run",
+        terminal,
+        onRunnerCreated: (created) => {
+          this.ownedRunners.add(created);
+          void this.forgetRunnerOnceClosed(created);
+        }
       }));
     } catch (err) {
       this.queue.end();
+      this.terminal = {
+        failure: isRuntimeExecutionFailure(err) ? err : new RuntimeExecutionFailure({
+          phase: "run",
+          category: "authority",
+          retry: "non-retryable",
+          reason: "codex follow-up violated the runtime adapter contract"
+        }, { cause: err })
+      };
       throw err;
     }
+    if (this.closed) {
+      await runner.dispose();
+      throw new Error("codex session closed while follow-up was starting");
+    }
+    this.terminal = terminal;
     this.sessionRef = sessionRef;
     this.currentRunner = runner;
-    void this.forgetRunnerOnceClosed(runner);
   }
   /** Best-effort abort of the current turn. SIGTERM's the currently-running child, if any — see `process-runner.ts`'s `kill()` doc comment for why SIGTERM (not SIGINT) and why this is safe: the underlying codex thread survives and stays resumable, confirmed empirically. A no-op when no turn is currently in flight. */
   async interrupt() {
     this.currentRunner?.kill();
   }
   async close() {
-    if (this.closed) return;
-    this.closed = true;
-    this.currentRunner?.kill();
-    this.queue.end();
+    if (!this.closeAttempt) {
+      this.closed = true;
+      this.queue.end();
+      const attempt = (async () => {
+        const runners = [...this.ownedRunners];
+        await Promise.all(runners.map((runner) => runner.dispose()));
+        for (const runner of runners) this.ownedRunners.delete(runner);
+        await Promise.allSettled([...this.followUpAttempts]);
+      })();
+      this.closeAttempt = attempt.catch((error) => {
+        this.closeAttempt = void 0;
+        throw error;
+      });
+    }
+    await this.closeAttempt;
   }
   /**
    * `codex exec` has no in-band channel to inject text into an already-
@@ -2098,8 +2764,7 @@ var CodexSession = class {
     );
   }
 };
-function subscriptionModel2(task) {
-  const selection = task.dispatchSelection;
+function subscriptionModel2(selection) {
   if (selection === void 0) return void 0;
   if (selection.lane !== "subscription" || selection.runtimeId !== "codex") {
     throw new PolicyUnsupportedError(
@@ -2109,6 +2774,6 @@ function subscriptionModel2(task) {
   return selection.modelId;
 }
 
-export { ClaudeAdapter, CodexAdapter, PI_PACKAGE_NAME, PiAdapter };
+export { ClaudeAdapter, CodexAdapter, PI_PACKAGE_NAME, PiAdapter, RuntimeDisposalFailure, RuntimeExecutionFailure };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map