@byok-sdk/client 0.3.0 → 0.4.0

package/dist/bin/byok-agent.js

@@ -5,7 +5,7 @@ import { readFileSync, promises, linkSync, fstatSync, lstatSync, unlinkSync, con
 import path20, { isAbsolute, join } from 'path';
 import os from 'os';
 import { DEVICE_ASSERTION_AUDIENCE_MAX_BYTES, DEVICE_ASSERTION_DEFAULT_TTL_MS, DEVICE_ASSERTION_MAX_TTL_MS, nonceSigningBytes, CapabilityDeclarationSchema, hasCapability, DeviceAssertionClaimsSchema, deviceAssertionSigningInput, DEVICE_ASSERTION_SCHEMA_ID } from '@byok-sdk/core';
-import { TASK_STATES, ToolsetIdSchema, BYOK_PAIR_PATH, BYOK_CHALLENGE_PATH, BYOK_TOKEN_PATH, partitionAgentEvents, TASK_TRANSITIONS, encodeEnvelope, createEnvelope, byokBlobUrlPath, BYOK_BLOBS_PATH, byokBlobFinalizePath, checkResultDocument, MAX_MESSAGES_PER_BATCH, BYOK_CAPABILITIES_PATH, BYOK_PRESENCE_PATH, RuntimeIdSchema, RESULT_DOCUMENT_MAX_BYTES, PROTOCOL_VERSION, decodeEnvelope, BYOK_MESSAGES_PATH, MessagesSendResponseSchema, BYOK_EVENTS_PATH, parseMessage, UnknownMessageTypeError, BYOK_WS_PATH } from '@byok-sdk/protocol';
+import { TASK_STATES, CONFIGURED_TOOLSETS_MAX_ITEMS, ToolsetIdSchema, BYOK_PAIR_PATH, BYOK_CHALLENGE_PATH, BYOK_TOKEN_PATH, partitionAgentEvents, TASK_TRANSITIONS, encodeEnvelope, createEnvelope, byokBlobUrlPath, BYOK_BLOBS_PATH, byokBlobFinalizePath, checkResultDocument, MAX_MESSAGES_PER_BATCH, BYOK_CAPABILITIES_PATH, BYOK_PRESENCE_PATH, RuntimeIdSchema, RESULT_DOCUMENT_MAX_BYTES, PROTOCOL_VERSION, decodeEnvelope, BYOK_MESSAGES_PATH, MessagesSendResponseSchema, BYOK_EVENTS_PATH, parseMessage, UnknownMessageTypeError, BYOK_WS_PATH } from '@byok-sdk/protocol';
 import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import 'readline';
@@ -15,6 +15,52 @@ import { createRequire } from 'module';
 import { createInterface } from 'readline/promises';
 
 // src/types.ts
+function frozenStrings(values) {
+  return values === void 0 ? void 0 : Object.freeze([...values]);
+}
+function frozenPolicy(policy) {
+  const allowTools = policy.allowTools === void 0 ? void 0 : Object.freeze([...policy.allowTools]);
+  const denyTools = policy.denyTools === void 0 ? void 0 : Object.freeze([...policy.denyTools]);
+  return Object.freeze({
+    mode: policy.mode,
+    ...allowTools === void 0 ? {} : { allowTools },
+    ...denyTools === void 0 ? {} : { denyTools },
+    ...policy.workspaceRoot === void 0 ? {} : { workspaceRoot: policy.workspaceRoot },
+    ...policy.network === void 0 ? {} : { network: policy.network }
+  });
+}
+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 }
+    })
+  });
+}
+function sealRuntimeOperationManifest(manifest) {
+  return Object.freeze({
+    taskId: manifest.taskId,
+    runtimeId: manifest.runtimeId,
+    descriptor: freezeRuntimeAdapterDescriptor(manifest.descriptor),
+    policy: frozenPolicy(manifest.policy),
+    requiredToolsetIds: Object.freeze([...manifest.requiredToolsetIds]),
+    ...manifest.dispatchSelection === void 0 ? {} : { dispatchSelection: Object.freeze({ ...manifest.dispatchSelection }) },
+    ...manifest.sessionRef === void 0 ? {} : { sessionRef: manifest.sessionRef },
+    workspace: Object.freeze({ ...manifest.workspace }),
+    forwardedEnvironmentNames: Object.freeze([...manifest.forwardedEnvironmentNames])
+  });
+}
 var PolicyUnsupportedError = class extends Error {
   constructor(message) {
     super(message);
@@ -22,7 +68,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);
@@ -30,6 +76,112 @@ var SteerUnsupportedError = class extends Error {
     this.runtimeId = runtimeId;
   }
 };
+
+// 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";
+}
+function isRuntimeDisposalFailure(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return candidate[RUNTIME_DISPOSAL_FAILURE_BRAND] === true && isRuntimeDisposalStage(candidate.stage) && typeof candidate.message === "string" && candidate.message.length > 0;
+}
+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;
+}
+function retryableFromDisposition(disposition) {
+  switch (disposition) {
+    case "retryable":
+      return true;
+    case "non-retryable":
+      return false;
+  }
+}
+function projectRuntimeExecutionFailure(failure) {
+  return {
+    reason: failure.message,
+    retryable: retryableFromDisposition(failure.retry)
+  };
+}
+var RUNTIME_ADAPTER_CONTRACT_VIOLATION_REASON = Object.freeze({
+  start: "runtime adapter contract violation during start",
+  run: "runtime adapter contract violation during run"
+});
+function projectRuntimeBoundaryFailure(value, expectedPhase) {
+  if (isRuntimeExecutionFailure(value) && value.phase === expectedPhase) {
+    return { ...projectRuntimeExecutionFailure(value), contractViolation: false };
+  }
+  return {
+    reason: RUNTIME_ADAPTER_CONTRACT_VIOLATION_REASON[expectedPhase],
+    retryable: false,
+    contractViolation: true
+  };
+}
+var GIT_ERROR_CATEGORIES = [
+  "git-unavailable",
+  "git-timeout",
+  "git-output-limit",
+  "git-command-failed",
+  "workspace-root-invalid",
+  "workspace-root-conflict",
+  "workspace-not-owned",
+  "repository-root-mismatch",
+  "repository-invalid",
+  "lease-busy",
+  "ledger-invalid"
+];
+var GIT_WORKSPACE_PHASES = [
+  "preparing",
+  "active",
+  "completed",
+  "failed",
+  "cancelled",
+  "interrupted",
+  "salvage"
+];
 var GitWorkspaceError = class extends Error {
   constructor(category, message = category) {
     super(message);
@@ -945,6 +1097,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;
@@ -957,16 +1258,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));
@@ -1001,6 +1308,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
@@ -1019,15 +1330,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;
@@ -1113,6 +1439,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();
@@ -1183,8 +1510,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();
@@ -1196,49 +1532,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,
@@ -1248,62 +1561,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) {
@@ -1319,12 +1706,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);
@@ -1354,7 +1769,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");
@@ -1566,7 +1981,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) {
@@ -1618,16 +2041,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));
@@ -1683,6 +2112,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
@@ -1702,15 +2135,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;
@@ -1761,6 +2209,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();
@@ -1772,18 +2221,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 {
@@ -1795,54 +2263,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(path20.join(os.tmpdir(), "byok-mcp-"));
@@ -1851,12 +2338,23 @@ var ClaudeAdapter = class {
       const mcpConfigPath = path20.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,
@@ -1876,8 +2374,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",
@@ -1889,40 +2405,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
     );
   }
   /**
@@ -1957,8 +2504,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(
@@ -1983,6 +2529,7 @@ var ClaudeSession = class {
   mcpConfigDir;
   modelId;
   correlation = createToolUseCorrelation();
+  closeAttempt;
   get events() {
     const client = this.client;
     const correlation = this.correlation;
@@ -1991,17 +2538,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);
               }
@@ -2032,7 +2602,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}`
@@ -2056,8 +2626,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()`
@@ -2274,14 +2853,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;
     });
@@ -2311,7 +2891,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
@@ -2324,13 +2904,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) {
@@ -2381,8 +2973,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 {
@@ -2431,61 +3032,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() {
@@ -2533,37 +3173,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;
@@ -2587,7 +3259,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 }));
         }
       });
     });
@@ -2597,9 +3275,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 };
 }
@@ -2626,8 +3307,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;
@@ -2638,11 +3323,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();
@@ -2687,7 +3397,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)");
     }
@@ -2698,7 +3415,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}`
@@ -2708,6 +3425,7 @@ var CodexSession = class {
     const resumeRef = this.sessionRef;
     let sessionRef;
     let runner;
+    const terminal = {};
     try {
       ({ sessionRef, runner } = await runCodexTurn({
         command: this.command,
@@ -2722,25 +3440,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-
@@ -2776,8 +3523,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(
@@ -2842,7 +3588,7 @@ var ApprovalRegistry = class {
    * `requestApproval` timeout and `finish()` fail-closed cleanup
    * (`task-runner.ts`) — resolves a decision this device made on its own.
    * The one exception, a server-sent wire `task.approve`/`task.reject`
-   * relayed through `TaskContext.approvalChannel.resolve`
+   * relayed through `RuntimeOperationStartInput.approvalChannel.resolve`
    * (`task-runner.ts`'s `handleOffer`), passes `'wire'` explicitly.
    */
   resolve(approvalId, decision, reason, origin = "local") {
@@ -3473,7 +4219,10 @@ var PresencePublisher = class {
         {
           method: "PUT",
           headers: { "content-type": "application/json" },
-          body: JSON.stringify({ level: "online" })
+          body: JSON.stringify({
+            level: "online",
+            ...this.opts.configuredToolsets === void 0 ? {} : { configuredToolsets: this.opts.configuredToolsets }
+          })
         },
         this.opts.auth
       );
@@ -3667,12 +4416,12 @@ var AnotherControlServerRunningError = class extends Error {
   }
 };
 var MAX_HALF_OPEN_CONNECTIONS = 8;
-function errorMessage2(err) {
+function errorMessage3(err) {
   return err instanceof Error ? err.message : String(err);
 }
 function toControlErrorShape(err) {
   if (err instanceof ControlError) return { code: err.code, message: err.message };
-  return { code: "internal_error", message: errorMessage2(err) };
+  return { code: "internal_error", message: errorMessage3(err) };
 }
 function probeUnixSocketAlive(socketPath) {
   return new Promise((resolve) => {
@@ -3879,12 +4628,19 @@ async function startControlServer(opts) {
     }
     throw err;
   }
+  let stopServingPromise;
+  async function stopServing() {
+    stopServingPromise ??= (async () => {
+      for (const socket of sockets) socket.destroy();
+      await new Promise((resolve) => server.close(() => resolve()));
+    })();
+    await stopServingPromise;
+  }
   let closed = false;
   async function close() {
     if (closed) return;
     closed = true;
-    for (const socket of sockets) socket.destroy();
-    await new Promise((resolve) => server.close(() => resolve()));
+    await stopServing();
     if (process.platform !== "win32") {
       await promises.rm(endpoint, { force: true }).catch(() => {
       });
@@ -3892,7 +4648,7 @@ async function startControlServer(opts) {
     await promises.rm(tokenPath, { force: true }).catch(() => {
     });
   }
-  return { endpoint, close };
+  return { endpoint, stopServing, close };
 }
 function deterministicJitterMs(input) {
   const ratio = input.ratio ?? 0.2;
@@ -4186,6 +4942,7 @@ var WsTransport = class {
         deviceId: this.opts.deviceId,
         productId: this.opts.productId,
         runtimes: this.opts.runtimes,
+        configuredToolsets: this.opts.configuredToolsets === void 0 ? void 0 : [...this.opts.configuredToolsets],
         cursor: this.opts.getCursor?.()
       });
       socket.send(encodeEnvelope(hello));
@@ -4275,6 +5032,7 @@ var ConnectionManager = class {
       productId: opts.productId,
       capabilities: opts.capabilities,
       runtimes: opts.runtimes,
+      configuredToolsets: opts.configuredToolsets,
       getCursor: () => this.cursor,
       onEnvelope: (envelope) => this.deliver(envelope),
       onStateChange: (state) => {
@@ -4397,7 +5155,7 @@ var ConnectionManager = class {
    * already-delivered seqs (see its own doc comment) so the failed seq's own
    * redelivery can get through — but that same frozen watermark also means
    * every OTHER seq above it rides along on every re-poll too. Without this,
-   * a seq already mid-flight (e.g. a `task.offer` whose `adapter.start()`
+   * a seq already mid-flight (e.g. a `task.offer` whose prepared operation start()
    * hasn't resolved yet) would be re-enqueued into `processingChain` on
    * every such re-poll, piling up duplicate copies that — once the first
    * finally resolves and the chain unwinds through them — run its handler
@@ -5273,6 +6031,12 @@ var RECLAIM_FILENAME = `${DAEMON_OWNER_FILENAME}.reclaim`;
 var MAX_OWNER_BYTES = 4096;
 var RECLAIM_MALFORMED_GRACE_MS = 3e4;
 var SELF_PROCESS_STARTED_AT = new Date(Date.now() - process.uptime() * 1e3).toISOString();
+function endOwnershipProbe(socket, response) {
+  socket.on("error", () => {
+  });
+  if (response === void 0) socket.end();
+  else socket.end(response);
+}
 var STORE_MUTEX_ID_PREFIX = "byok-store-mutex-v1:";
 var STORE_MUTEX_PROBE_TIMEOUT_MS = 1e3;
 var STORE_MUTEX_SOCKET_FILENAME = "mutex.sock";
@@ -5379,7 +6143,7 @@ async function portIsBound(port) {
   });
 }
 async function createLivenessListener() {
-  const server = createServer((socket) => socket.end());
+  const server = createServer((socket) => endOwnershipProbe(socket));
   const port = await new Promise((resolve, reject) => {
     server.once("error", reject);
     server.listen({ host: "127.0.0.1", port: 0, exclusive: true }, () => {
@@ -5464,7 +6228,7 @@ async function acquireStoreMutex(canonicalStoreDir) {
     }
     await clearStaleStoreMutexSocket(endpoint, identity);
   }
-  const server = createServer((socket) => socket.end(`${STORE_MUTEX_ID_PREFIX}${identity}
+  const server = createServer((socket) => endOwnershipProbe(socket, `${STORE_MUTEX_ID_PREFIX}${identity}
 `));
   try {
     await new Promise((resolve, reject) => {
@@ -5606,7 +6370,7 @@ function toRuntimeInfoCapabilities(caps) {
     resume: caps.resume,
     approvalInteractive: caps.approvalInteractive,
     ...caps.mcpToolsets === void 0 ? {} : { mcpToolsets: caps.mcpToolsets },
-    permissionModes: caps.permissionModes
+    permissionModes: [...caps.permissionModes]
   };
 }
 var CursorStore = class {
@@ -5846,6 +6610,9 @@ var DaemonObserver = class {
   noteGitWorkspace(event) {
     this.emit({ kind: "git-workspace", ts: nowIso(), ...event });
   }
+  noteRuntimeDisposalFailure(event) {
+    this.emit({ kind: "runtime-disposal-failed", ts: nowIso(), ...event });
+  }
   /**
    * Finding F4: wired from `TaskRunnerDeps.onApprovalDispatched`, called
    * synchronously by `TaskRunner.dispatchApproval` BEFORE its own
@@ -7499,20 +8266,20 @@ function isKnownRuntimeId(id) {
 var DEFAULT_RUNTIME_PREFERENCE = ["claude", "codex", "pi"];
 function orderByPreference(candidates, preference) {
   const rank = new Map(preference.map((id, index) => [id, index]));
-  return [...candidates].sort((a, b) => (rank.get(a.id) ?? preference.length) - (rank.get(b.id) ?? preference.length));
+  return [...candidates].sort((a, b) => (rank.get(a.descriptor.id) ?? preference.length) - (rank.get(b.descriptor.id) ?? preference.length));
 }
-function adapterSupportsMode(adapter, mode) {
-  return adapter.capabilities().permissionModes.includes(mode);
+function adapterSupportsMode(descriptor, mode) {
+  return descriptor.capabilities.permissionModes.includes(mode);
 }
-function adapterSupportsMcpToolsets(adapter) {
-  return adapter.capabilities().mcpToolsets === true;
+function adapterSupportsMcpToolsets(descriptor) {
+  return descriptor.capabilities.mcpToolsets === true;
 }
 function withoutRequiredToolsets(payload) {
   if (!("requiredToolsets" in payload)) return payload;
   const { requiredToolsets, ...offer } = payload;
   return offer;
 }
-function errorMessage3(err) {
+function errorMessage4(err) {
   return err instanceof Error ? err.message : String(err);
 }
 function raceSettleFirst(fn, timeoutMs) {
@@ -7565,7 +8332,7 @@ async function openArtifact(workspaceDir, name) {
   try {
     handle = await promises.open(candidate, constants.O_RDONLY | O_NOFOLLOW);
   } catch (err) {
-    return { ok: false, reason: `artifact "${name}" could not be opened: ${errorMessage3(err)}` };
+    return { ok: false, reason: `artifact "${name}" could not be opened: ${errorMessage4(err)}` };
   }
   try {
     const st = await handle.stat();
@@ -7577,7 +8344,7 @@ async function openArtifact(workspaceDir, name) {
   } catch (err) {
     await handle.close().catch(() => {
     });
-    return { ok: false, reason: `artifact "${name}" could not be verified: ${errorMessage3(err)}` };
+    return { ok: false, reason: `artifact "${name}" could not be verified: ${errorMessage4(err)}` };
   }
   return { ok: true, handle };
 }
@@ -7591,13 +8358,13 @@ var TaskRunner = class {
    * Finding F4 (cancel lost during the offer-processing window): a
    * `task.cancel` for a taskId that hasn't finished `handleOffer` yet (still
    * awaiting adapter detection / instruction resolution / workspace setup /
-   * `adapter.start()`) has no `this.tasks` entry to land on — it used to be
+   * prepared operation `start()`) has no `this.tasks` entry to land on — it used to be
    * silently dropped, and the runtime session `handleOffer` was about to
    * register would then run an unsupervised ("zombie") turn nobody asked
    * for anymore. Recording the taskId here lets `handleOffer` consult it at
    * the two points where it can still safely react (see its body): before
    * claiming at all (decline instead of ever starting a session), and right
-   * after `adapter.start()` resolves but before this task is registered as
+   * after the prepared operation resolves but before this task is registered as
    * active (tear the just-started session down immediately, before its
    * event loop ever pumps a single event). Consumed (deleted) at whichever
    * checkpoint handles it; a cancel for a taskId that's already active,
@@ -7623,12 +8390,12 @@ var TaskRunner = class {
    * checkpoint-2 cancel-teardown, or successful registration into
    * `this.tasks`). Bounded eviction on `pendingCancelled` (below) must never
    * remove an entry for a taskId in this set: doing so is exactly the bug —
-   * block task A in `adapter.start()`, deliver A's own `task.cancel` (so
+   * block task A in prepared-operation `start()`, deliver A's own `task.cancel` (so
    * `pendingCancelled` gets an entry for A while A is still in-flight),
    * then deliver `MAX_TRACKED_TASK_IDS` more cancels for unrelated taskIds
    * nobody ever offered — under naive oldest-wins eviction, A's entry (the
    * single oldest) gets evicted purely because of unrelated churn, so when
-   * `adapter.start()` finally resolves, checkpoint 2 finds no cancel marker
+   * the prepared operation finally resolves, checkpoint 2 finds no cancel marker
    * and the already-cancelled task starts a real session. See
    * `evictPendingCancelled` below for the fix, and
    * `task-runner-bounded-collections.test.ts` for a test mirroring this
@@ -7648,7 +8415,7 @@ var TaskRunner = class {
    * explicitly relies on redelivered handlers being idempotent for exactly
    * this reason). `handleOffer` must treat a redelivered offer for a taskId
    * that's already active (`this.tasks`) or already finished (this set) as
-   * a no-op — never a second `adapter.start()` call, which would orphan the
+   * a no-op — never a second prepared-operation `start()` call, which would orphan the
    * first session.
    *
    * M3-B: unbounded otherwise — a long-lived daemon that's finished many
@@ -7717,10 +8484,9 @@ var TaskRunner = class {
     this.stoppingOffers = true;
   }
   /**
-   * M4 Phase 2: best-effort shutdown of every currently ACTIVE task, for the
-   * control socket's `shutdown` RPC. Mirrors `handleCancel`'s best-effort
-   * `session.interrupt()` style (an interrupt failure is swallowed; the
-   * terminal message is sent either way) but reports `task.fail` rather than
+   * Shutdown of every currently ACTIVE task for the control socket's
+   * `shutdown` RPC. Soft interrupt remains bounded, but each task's
+   * authoritative close receipt must settle successfully. Reports `task.fail` rather than
    * `task.cancelled` — these tasks aren't ending because the SERVER
    * cancelled them, they're ending because this device is shutting down.
    * `retryable: true` throughout: nothing about the task/policy itself was
@@ -7774,28 +8540,13 @@ var TaskRunner = class {
    * unconditionally, so a hung `interrupt()` (a misbehaving adapter) can
    * never block `task.fail` from being sent at all.
    *
-   * New in this batch — hard-kill escalation: when `interrupt()` does NOT
-   * settle within that same grace window, `session.close()` is tried next
-   * (ALSO raced against `timeoutMs`, for the identical reason: a hung
-   * `close()` must not be able to block this forever either — which matters
-   * far more here than it used to for the pre-existing graceful-shutdown-only
-   * caller, since THAT path is additionally bounded by an outer deadline
-   * (`SHUTDOWN_TASK_TEARDOWN_DEADLINE_MS`/`DaemonConfig.shutdownGraceMs`,
-   * `create-daemon.ts`), while resource-limit enforcement fires during
-   * ordinary operation with no such outer bound watching it). `close()` is
-   * every adapter's harder teardown primitive — an actual process-level kill
-   * (SIGTERM, or `taskkill /F` on Windows — see e.g.
-   * `ClaudeProcessClient.kill()`/`PiRpcClient.kill()`) as opposed to pi's own
-   * soft in-band `interrupt()` (an RPC `abort` message that leaves the
-   * process alive and resumable) — so escalating to it is the closest thing
-   * to a "hard kill" the `Session` interface exposes. `finish()` below calls
-   * `session.close()` again regardless (documented idempotent) — this isn't
-   * a substitute for that, only an earlier, bounded attempt at actually
-   * stopping a stuck runtime before this method gives up and reports failure
-   * anyway.
+   * After the bounded soft interrupt, `finish()` always awaits the authoritative
+   * `Session.close()` receipt. A failed receipt retains active/Git ownership;
+   * shutdown surfaces the rejection while resource enforcement leaves local
+   * evidence for a later retry.
    *
    * Re-checks task identity (`this.tasks.get(...) === active`) immediately
-   * before sending `task.fail`: the interrupt/hard-kill race above has await
+   * before sending `task.fail`: the interrupt race above has await
    * points during which a DIFFERENT path (a racing `task.cancel`/
    * `task.reject`, or the session completing normally on its own) may have
    * already finished this exact task and sent its own terminal message.
@@ -7804,20 +8555,25 @@ var TaskRunner = class {
    * identity-check guard for the same class of race.
    */
   async teardownActiveTask(active, reason, retryable) {
+    if (active.finalizationStarted) return this.finish(active.taskId);
+    if (!this.reserveSemanticTerminal(active)) return active.semanticTerminalSettled ?? false;
     active.beingTornDown = true;
     await this.observeGit(active, "salvage");
     const timeoutMs = this.deps.shutdownInterruptTimeoutMs ?? DEFAULT_SHUTDOWN_INTERRUPT_TIMEOUT_MS;
-    const interrupted = await raceSettleFirst(() => active.session.interrupt(), timeoutMs);
-    if (!interrupted) {
-      await raceSettleFirst(() => active.session.close(), timeoutMs);
-    }
-    if (this.tasks.get(active.taskId) !== active) return;
+    await raceSettleFirst(() => active.session.interrupt(), timeoutMs);
+    if (this.tasks.get(active.taskId) !== active) return true;
     this.deps.send(createEnvelope("task.fail", { reason, retryable }, { taskId: active.taskId }));
-    await this.finish(active.taskId);
+    return this.finish(active.taskId);
   }
   /** Graceful-shutdown caller of {@link teardownActiveTask} — see `shutdownActiveTasks`'s own doc comment. `retryable: true`: nothing about the task/policy itself was ever at fault, only this device's own availability right now. */
   async shutdownTask(active, reason) {
-    await this.teardownActiveTask(active, `daemon shutting down: ${reason}`, true);
+    const disposed = await this.teardownActiveTask(active, `daemon shutting down: ${reason}`, true);
+    if (!disposed) {
+      throw new RuntimeDisposalFailure({
+        stage: "quiescence",
+        reason: `${active.adapter.descriptor.id} runtime ownership remains active after shutdown disposal failed`
+      });
+    }
   }
   /**
    * M5 batch-3 (workstream 2): shared entry point for both resource-limit
@@ -7937,15 +8693,33 @@ var TaskRunner = class {
         this.decline(taskId, resolvedMcp.reason, true);
         return;
       }
+      const decision = computeEffectivePolicy(payload.policy, this.deps.permissionDefaults);
+      if (!decision.ok) {
+        this.decline(taskId, decision.reason ?? "policy rejected", false);
+        return;
+      }
+      const offered = withoutRequiredToolsets(payload);
       const requestedRuntime = payload.dispatchSelection?.runtimeId ?? payload.runtime;
       const pick = await this.pickAdapter(requestedRuntime, payload.policy.mode, requiredToolsets !== void 0);
       if (!pick.ok) {
         this.decline(taskId, pick.reason, pick.retryable);
         return;
       }
-      const decision = computeEffectivePolicy(payload.policy, this.deps.permissionDefaults);
-      if (!decision.ok) {
-        this.decline(taskId, decision.reason ?? "policy rejected", false);
+      let prepared;
+      try {
+        prepared = await pick.adapter.prepare({
+          offer: offered,
+          policy: decision.policy,
+          descriptor: pick.descriptor,
+          requiredToolsetIds: requiredToolsets ?? [],
+          ...resolvedMcp?.ok ? { mcpServers: resolvedMcp.servers } : {}
+        });
+      } catch (error) {
+        this.decline(taskId, `runtime preparation failed: ${errorMessage4(error)}`, true);
+        return;
+      }
+      if (prepared.kind === "reject") {
+        this.decline(taskId, prepared.reason, prepared.retryable);
         return;
       }
       let known = void 0;
@@ -7980,6 +8754,7 @@ var TaskRunner = class {
           }
         } else {
           workspaceDir = path20.join(this.deps.workspaceRoot, taskId);
+          gitWorkspaceId = randomUUID();
         }
         try {
           gitLease = await gitManager.acquireLease(workspaceDir, payload.sessionRef);
@@ -7995,6 +8770,26 @@ var TaskRunner = class {
         this.decline(taskId, "workspace mode is unavailable", true);
         return;
       }
+      const env = buildRuntimeEnv({
+        ambient: process.env,
+        requirements: pick.descriptor.environmentRequirements,
+        locallyAllowedNames: this.deps.runtimeEnvironment?.[pick.descriptor.id]?.allow
+      });
+      const manifest = sealRuntimeOperationManifest({
+        taskId,
+        runtimeId: pick.descriptor.id,
+        descriptor: pick.descriptor,
+        policy: decision.policy,
+        requiredToolsetIds: requiredToolsets ?? [],
+        ...offered.dispatchSelection === void 0 ? {} : { dispatchSelection: offered.dispatchSelection },
+        ...known === void 0 || payload.sessionRef === void 0 ? {} : { sessionRef: payload.sessionRef },
+        workspace: {
+          workspaceDir,
+          ...gitWorkspaceId === void 0 ? {} : { workspaceId: gitWorkspaceId },
+          ...gitBaseline === void 0 ? {} : { baseline: gitBaseline }
+        },
+        forwardedEnvironmentNames: Object.freeze(Object.keys(env).sort())
+      });
       this.deps.send(
         createEnvelope(
           "task.claim",
@@ -8010,7 +8805,7 @@ var TaskRunner = class {
             // (the merely REQUESTED runtime): this is what closes the gap
             // where an auto-selected task left the server never learning
             // which runtime actually ran.
-            runtime: isKnownRuntimeId(pick.adapter.id) ? pick.adapter.id : void 0,
+            runtime: isKnownRuntimeId(manifest.descriptor.id) ? manifest.descriptor.id : void 0,
             // S0/D-4 (`task.claim.capabilities`, docs/protocol.md §2.4): the
             // selected adapter's own capability self-report, carried on the
             // same message that establishes the task↔runtime binding. The
@@ -8027,7 +8822,7 @@ var TaskRunner = class {
             // Gating them would silently strip a custom steer-capable
             // adapter's own truth and leave the server fail-closing on it
             // forever.
-            capabilities: toRuntimeInfoCapabilities(pick.adapter.capabilities())
+            capabilities: toRuntimeInfoCapabilities(manifest.descriptor.capabilities)
           },
           { taskId }
         )
@@ -8038,7 +8833,7 @@ var TaskRunner = class {
         if (plainWorkspaceNeedsResolve) workspaceDir = await this.resolveWorkspaceDir(taskId, known?.workspaceDir);
       } catch (err) {
         gitLease?.release();
-        await this.fail(taskId, `failed to resolve instruction blob: ${errorMessage3(err)}`, true);
+        await this.fail(taskId, `failed to resolve instruction blob: ${errorMessage4(err)}`, true);
         return;
       }
       if (this.deps.gitWorkspaceManager && gitLease) {
@@ -8047,7 +8842,7 @@ var TaskRunner = class {
           if (gitExisting) {
             observation = await this.deps.gitWorkspaceManager.validateExisting(workspaceDir);
           } else {
-            const workspaceId2 = randomUUID();
+            const workspaceId2 = gitWorkspaceId ?? randomUUID();
             const now2 = (/* @__PURE__ */ new Date()).toISOString();
             gitWorkspaceId = workspaceId2;
             await this.deps.gitWorkspaceStore?.upsert({
@@ -8098,30 +8893,11 @@ var TaskRunner = class {
           return;
         }
       }
-      const ctx = {
-        workspaceDir,
-        policy: decision.policy,
+      const startInput = {
+        manifest,
+        instruction: gitWorkspaceId ? prependGitWorkspaceGuidance(resolvedInstruction) : resolvedInstruction,
+        env,
         ...resolvedMcp?.ok ? { mcpServers: resolvedMcp.servers } : {},
-        ...gitWorkspaceId ? { gitWorkspace: { workspaceId: gitWorkspaceId, baseline: gitBaseline } } : {},
-        // M5: no longer `process.env` verbatim (see `environment.ts`'s own
-        // module doc comment for the credential-leak gap that closed) —
-        // built fresh per task from the SPECIFIC adapter `pickAdapter`
-        // above already selected, so this always runs after adapter
-        // selection: `pick.adapter.environmentRequirements?.()` (undefined
-        // ⇒ platform baseline only, fail-closed) plus this device's own
-        // `runtimeEnvironment` override, keyed by that same adapter's `id`.
-        env: buildRuntimeEnv({
-          ambient: process.env,
-          requirements: pick.adapter.environmentRequirements?.(),
-          locallyAllowedNames: this.deps.runtimeEnvironment?.[pick.adapter.id]?.allow
-        }),
-        // M4 Phase 3: adapter-agnostic and cheap to always populate — only an
-        // adapter whose runtime genuinely supports an out-of-band approval
-        // pause (claude, today) ever reads this. `resolve` is a closure over
-        // `taskId` (not a pre-bound approvalId): it looks up whichever
-        // approval is CURRENTLY pending for this task at call time, since one
-        // task/session can face several approval requests, one at a time,
-        // over its life. See `types.ts`'s `ApprovalChannel` doc comment.
         approvalChannel: {
           taskId,
           storeDir: this.deps.storeDir,
@@ -8137,45 +8913,19 @@ var TaskRunner = class {
           }
         }
       };
-      const effectiveOffer = {
-        ...withoutRequiredToolsets(payload),
-        instruction: gitWorkspaceId ? prependGitWorkspaceGuidance(resolvedInstruction) : resolvedInstruction,
-        // Never forward a sessionRef this device has no recorded workspace
-        // for (stale, from another device, or simply made up) — an adapter
-        // that tries to resume an id it never minted fails outright (pi:
-        // "No session found matching '<id>'", exit 1, empirically confirmed)
-        // instead of silently starting fresh, so an unresolvable sessionRef
-        // must look identical to "none supplied" by the time it reaches the
-        // adapter, not get forwarded as a resume attempt doomed to fail.
-        sessionRef: known ? payload.sessionRef : void 0
-      };
       let session;
       try {
-        session = await pick.adapter.start(effectiveOffer, ctx);
+        session = await prepared.operation.start(startInput);
       } catch (err) {
-        const retryable = !(err instanceof PolicyUnsupportedError);
-        await this.updateGitPhaseBestEffort(gitWorkspaceId, "failed", "repository-invalid");
-        gitLease?.release();
-        await this.fail(taskId, `adapter failed to start: ${errorMessage3(err)}`, retryable);
-        return;
-      }
-      if (this.pendingCancelled.has(taskId)) {
-        const reason = this.pendingCancelled.get(taskId);
-        this.pendingCancelled.delete(taskId);
-        try {
-          await session.interrupt();
-        } catch {
-        }
-        try {
-          await session.close();
-        } catch {
+        const failure = projectRuntimeBoundaryFailure(err, "start");
+        if (failure.contractViolation) {
+          console.error("[byok/client] runtime adapter start() returned an untyped failure", err);
         }
+        await this.updateGitPhaseBestEffort(gitWorkspaceId, "failed", "repository-invalid");
         gitLease?.release();
-        await this.updateGitPhaseBestEffort(gitWorkspaceId, "cancelled");
-        this.deps.send(createEnvelope("task.cancelled", { reason }, { taskId }));
+        await this.fail(taskId, failure.reason, failure.retryable);
         return;
       }
-      this.deps.send(createEnvelope("task.started", {}, { taskId }));
       const active = {
         taskId,
         adapter: pick.adapter,
@@ -8192,6 +8942,21 @@ var TaskRunner = class {
         approvalQueue: [],
         outputBytesSoFar: 0
       };
+      if (this.pendingCancelled.has(taskId)) {
+        const reason = this.pendingCancelled.get(taskId);
+        this.pendingCancelled.delete(taskId);
+        this.tasks.set(taskId, active);
+        this.reserveSemanticTerminal(active);
+        try {
+          await session.interrupt();
+        } catch {
+        }
+        await this.updateGitPhaseBestEffort(gitWorkspaceId, "cancelled");
+        this.deps.send(createEnvelope("task.cancelled", { reason }, { taskId }));
+        await this.finish(taskId);
+        return;
+      }
+      this.deps.send(createEnvelope("task.started", {}, { taskId }));
       this.tasks.set(taskId, active);
       if (payload.limits?.maxDurationMs !== void 0) {
         this.armMaxDurationTimer(active, payload.limits.maxDurationMs);
@@ -8249,6 +9014,7 @@ var TaskRunner = class {
   async pump(active) {
     try {
       for await (const event of active.session.events) {
+        if (this.tasks.get(active.taskId) !== active || active.beingTornDown) return;
         if (this.tasks.get(active.taskId) !== active) return;
         active.outputBytesSoFar += estimateEventBytes(event);
         if (active.outputBytesSoFar > this.maxTaskOutputBytes) {
@@ -8271,7 +9037,7 @@ var TaskRunner = class {
             try {
               await active.session.resolveApproval(approved, reason);
             } catch (err) {
-              await this.fail(taskId, `failed to resume session after approval decision: ${errorMessage3(err)}`, false);
+              await this.fail(taskId, `failed to resume session after approval decision: ${errorMessage4(err)}`, false);
             }
           });
           continue;
@@ -8283,6 +9049,7 @@ var TaskRunner = class {
           const outcome = await this.resolveResultDocument(active, finalOutput);
           if (!outcome.deliver) return;
           await this.observeGit(active, "completed");
+          if (this.tasks.get(active.taskId) !== active || active.beingTornDown) return;
           if (outcome.document !== void 0 && !this.hasResultDocumentCapability()) {
             await this.fail(
               active.taskId,
@@ -8291,6 +9058,7 @@ var TaskRunner = class {
             );
             return;
           }
+          if (!this.reserveSemanticTerminal(active)) return;
           this.deps.send(
             createEnvelope(
               "task.complete",
@@ -8326,11 +9094,17 @@ var TaskRunner = class {
         active.batcher.push(event);
       }
       if (this.tasks.get(active.taskId) !== active || active.beingTornDown) return;
-      await this.fail(active.taskId, "runtime session ended without completing the task", true);
+      const failure = projectRuntimeBoundaryFailure(void 0, "run");
+      console.error("[byok/client] runtime adapter events iterable ended without terminal authority");
+      await this.fail(active.taskId, failure.reason, failure.retryable);
     } catch (err) {
       if (this.tasks.get(active.taskId) !== active || active.beingTornDown) return;
       active.batcher.flush();
-      await this.fail(active.taskId, `runtime error: ${errorMessage3(err)}`, true);
+      const failure = projectRuntimeBoundaryFailure(err, "run");
+      if (failure.contractViolation) {
+        console.error("[byok/client] runtime adapter events iterable returned an untyped failure", err);
+      }
+      await this.fail(active.taskId, failure.reason, failure.retryable);
     }
   }
   /**
@@ -8369,7 +9143,7 @@ var TaskRunner = class {
     try {
       bytes = await opened.handle.readFile();
     } catch (err) {
-      this.reportArtifactError(active, name, `failed to read artifact "${name}": ${errorMessage3(err)}`);
+      this.reportArtifactError(active, name, `failed to read artifact "${name}": ${errorMessage4(err)}`);
       return;
     } finally {
       await opened.handle.close().catch(() => {
@@ -8386,7 +9160,7 @@ var TaskRunner = class {
       const blobRef = await this.deps.blobClient.uploadArtifact(bytes, contentType);
       this.deps.send(createEnvelope("task.artifact", { name, contentType, blobRef }, { taskId: active.taskId }));
     } catch (err) {
-      this.reportArtifactError(active, name, `failed to upload artifact "${name}": ${errorMessage3(err)}`);
+      this.reportArtifactError(active, name, `failed to upload artifact "${name}": ${errorMessage4(err)}`);
     }
   }
   /** Loud, non-silent artifact failure (finding F7): logged, and folded into this task's own progress stream as an `error` AgentEvent rather than swallowed — the task itself can still complete normally, but the omission is now visible. */
@@ -8400,6 +9174,14 @@ var TaskRunner = class {
       this.setPendingCancelled(taskId, reason);
       return;
     }
+    if (active.finalizationStarted) {
+      await this.finish(taskId);
+      return;
+    }
+    if (!this.reserveSemanticTerminal(active)) {
+      await active.semanticTerminalSettled;
+      return;
+    }
     try {
       await active.session.interrupt();
     } catch {
@@ -8428,7 +9210,7 @@ var TaskRunner = class {
    *
    * `inFlightOffers` is naturally tiny (bounded by this device's real
    * concurrent-offer-processing count — normally single digits, driven by
-   * how many `task.offer`s are simultaneously mid-`adapter.start()` — nowhere
+   * how many `task.offer`s are simultaneously mid-prepared-operation start() — nowhere
    * near `MAX_TRACKED_TASK_IDS`), so this scan is cheap in practice: it
    * finds a safe entry at or near the front almost always. The only case
    * where NO entry is safe to evict is every single tracked cancel
@@ -8781,7 +9563,7 @@ var TaskRunner = class {
         this.deps.onStaleApprovalDecision?.(taskId, "approve");
         return;
       }
-      await this.fail(taskId, `failed to resume session after approval: ${errorMessage3(err)}`, false);
+      await this.fail(taskId, `failed to resume session after approval: ${errorMessage4(err)}`, false);
       return;
     }
     this.clearPendingApproval(resolvedId, "approve", void 0);
@@ -8812,6 +9594,10 @@ var TaskRunner = class {
   async handleReject(taskId, reason, approvalId) {
     const active = this.tasks.get(taskId);
     if (!active) return;
+    if (active.finalizationStarted) {
+      await this.finish(taskId);
+      return;
+    }
     if (approvalId !== void 0 && approvalId !== active.pendingApprovalId) {
       this.deps.onStaleApprovalDecision?.(
         taskId,
@@ -8830,6 +9616,10 @@ var TaskRunner = class {
       }
     }
     this.clearPendingApproval(resolvedId, "reject", reason);
+    if (!this.reserveSemanticTerminal(active)) {
+      await active.semanticTerminalSettled;
+      return;
+    }
     try {
       await active.session.interrupt();
     } catch {
@@ -8844,6 +9634,14 @@ var TaskRunner = class {
   }
   async fail(taskId, reason, retryable) {
     const active = this.tasks.get(taskId);
+    if (active?.finalizationStarted) {
+      await this.finish(taskId);
+      return;
+    }
+    if (active && !this.reserveSemanticTerminal(active)) {
+      await active.semanticTerminalSettled;
+      return;
+    }
     if (active) await this.observeGit(active, "salvage");
     this.deps.send(createEnvelope("task.fail", { reason, retryable }, { taskId }));
     await this.finish(taskId);
@@ -8903,7 +9701,7 @@ var TaskRunner = class {
     } catch (err) {
       await this.fail(
         active.taskId,
-        `${RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX}: the configured resultDocument.extract threw: ${errorMessage3(err)}`,
+        `${RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX}: the configured resultDocument.extract threw: ${errorMessage4(err)}`,
         false
       );
       return { deliver: false };
@@ -8978,32 +9776,64 @@ var TaskRunner = class {
   }
   async finish(taskId) {
     const active = this.tasks.get(taskId);
-    if (!active) return;
-    if (active.maxDurationTimer) {
-      clearTimeout(active.maxDurationTimer);
-      active.maxDurationTimer = void 0;
-    }
-    active.batcher.stop();
-    this.tasks.delete(taskId);
-    this.addFinishedTaskId(taskId);
-    const queued = active.approvalQueue.splice(0);
-    for (const request of queued) {
-      request.resolve({
-        approved: false,
-        reason: `task ${taskId} finished before this queued approval request could be dispatched`
-      });
-    }
-    if (active.pendingApprovalId !== void 0) {
-      try {
-        this.deps.approvalRegistry.resolve(active.pendingApprovalId, "reject", `task ${taskId} finished`);
-      } catch {
+    if (!active) return true;
+    if (!active.finalizationStarted) {
+      active.finalizationStarted = true;
+      active.beingTornDown = true;
+      if (active.maxDurationTimer) {
+        clearTimeout(active.maxDurationTimer);
+        active.maxDurationTimer = void 0;
+      }
+      active.batcher.stop();
+      this.addFinishedTaskId(taskId);
+      const queued = active.approvalQueue.splice(0);
+      for (const request of queued) {
+        request.resolve({
+          approved: false,
+          reason: `task ${taskId} finished before this queued approval request could be dispatched`
+        });
+      }
+      if (active.pendingApprovalId !== void 0) {
+        try {
+          this.deps.approvalRegistry.resolve(active.pendingApprovalId, "reject", `task ${taskId} finished`);
+        } catch {
+        }
       }
     }
-    if (active.gitLease) active.gitLease.release();
+    const attempt = active.disposalAttempt ?? active.session.close();
+    active.disposalAttempt = attempt;
     try {
-      await active.session.close();
-    } catch {
+      await attempt;
+    } catch (caught) {
+      if (active.disposalAttempt === attempt) active.disposalAttempt = void 0;
+      const failure = isRuntimeDisposalFailure(caught) ? caught : new RuntimeDisposalFailure({
+        stage: "quiescence",
+        reason: `${active.adapter.descriptor.id} session.close() returned an untyped disposal failure`
+      }, { cause: caught });
+      console.error(`[byok/client] runtime disposal failed for task ${taskId}: ${failure.message}`);
+      this.deps.onRuntimeDisposalFailure?.({
+        taskId,
+        runtimeId: active.adapter.descriptor.id,
+        stage: failure.stage,
+        reason: failure.message
+      });
+      active.resolveSemanticTerminalSettled?.(false);
+      return false;
     }
+    if (this.tasks.get(taskId) !== active) return true;
+    active.gitLease?.release();
+    this.tasks.delete(taskId);
+    active.resolveSemanticTerminalSettled?.(true);
+    return true;
+  }
+  reserveSemanticTerminal(active) {
+    if (active.semanticTerminalReserved || active.finalizationStarted) return false;
+    active.semanticTerminalReserved = true;
+    active.beingTornDown = true;
+    active.semanticTerminalSettled = new Promise((resolve) => {
+      active.resolveSemanticTerminalSettled = resolve;
+    });
+    return true;
   }
   /** M3-B: bounded insert for `finishedTaskIds` — see its class-level doc comment and `MAX_TRACKED_TASK_IDS`. Evicts the oldest (first-inserted) entry once over cap, same idiom as `ConnectionHub.checkAndRecordDuplicate` (packages/server/src/hub.ts). */
   addFinishedTaskId(taskId) {
@@ -9056,18 +9886,19 @@ var TaskRunner = class {
           retryable: false
         };
       }
-      const adapter = this.deps.adapters.find((a) => a.id === requestedRuntime);
+      const adapter = this.deps.adapters.find((a) => a.descriptor.id === requestedRuntime);
       if (!adapter) {
         return { ok: false, reason: `unknown runtime "${requestedRuntime}"`, retryable: false };
       }
-      if (!adapterSupportsMode(adapter, policyMode)) {
+      const descriptor = freezeRuntimeAdapterDescriptor(adapter.descriptor);
+      if (!adapterSupportsMode(descriptor, policyMode)) {
         return {
           ok: false,
           reason: `runtime "${requestedRuntime}" cannot express permission mode "${policyMode}"`,
           retryable: false
         };
       }
-      if (requiresMcpToolsets && !adapterSupportsMcpToolsets(adapter)) {
+      if (requiresMcpToolsets && !adapterSupportsMcpToolsets(descriptor)) {
         return {
           ok: false,
           reason: `runtime "${requestedRuntime}" cannot project required MCP toolsets`,
@@ -9082,15 +9913,16 @@ var TaskRunner = class {
           retryable: true
         };
       }
-      return { ok: true, adapter };
+      return { ok: true, adapter, descriptor };
     }
-    const eligible = allowlist ? this.deps.adapters.filter((a) => allowlist.includes(a.id)) : this.deps.adapters;
+    const eligible = allowlist ? this.deps.adapters.filter((a) => allowlist.includes(a.descriptor.id)) : this.deps.adapters;
     const candidates = orderByPreference(eligible, this.deps.runtimePreference ?? DEFAULT_RUNTIME_PREFERENCE);
     for (const adapter of candidates) {
-      if (!adapterSupportsMode(adapter, policyMode)) continue;
-      if (requiresMcpToolsets && !adapterSupportsMcpToolsets(adapter)) continue;
+      const descriptor = freezeRuntimeAdapterDescriptor(adapter.descriptor);
+      if (!adapterSupportsMode(descriptor, policyMode)) continue;
+      if (requiresMcpToolsets && !adapterSupportsMcpToolsets(descriptor)) continue;
       const detected = await adapter.detect();
-      if (detected.present) return { ok: true, adapter };
+      if (detected.present) return { ok: true, adapter, descriptor };
     }
     return {
       ok: false,
@@ -9135,27 +9967,27 @@ async function detectRuntimes(adapters) {
   const detections = await Promise.all(adapters.map(async (adapter) => ({ adapter, detected: await adapter.detect() })));
   const runtimes = [];
   for (const { adapter, detected } of detections) {
-    if (!detected.present || !isRuntimeId(adapter.id)) continue;
-    const info = { id: adapter.id };
+    if (!detected.present || !isRuntimeId(adapter.descriptor.id)) continue;
+    const info = { id: adapter.descriptor.id };
     if (detected.version !== void 0) info.version = detected.version;
     if (detected.authPresent !== void 0) info.authPresent = detected.authPresent;
-    info.capabilities = toRuntimeInfoCapabilities(adapter.capabilities());
+    info.capabilities = toRuntimeInfoCapabilities(adapter.descriptor.capabilities);
     runtimes.push(info);
   }
   return runtimes;
 }
 function computeCapabilities(adapters) {
   const flags = [];
-  if (adapters.some((adapter) => adapter.capabilities().steer)) flags.push("steer");
+  if (adapters.some((adapter) => adapter.descriptor.capabilities.steer)) flags.push("steer");
   flags.push("blob-upload");
   flags.push("approval-targeting");
   const selectionAdapters = adapters.filter(
-    (adapter) => ALL_RUNTIME_IDS.includes(adapter.id)
+    (adapter) => ALL_RUNTIME_IDS.includes(adapter.descriptor.id)
   );
-  if (selectionAdapters.length > 0 && selectionAdapters.every((adapter) => adapter.supportsDispatchSelection === true)) {
+  if (selectionAdapters.length > 0 && selectionAdapters.every((adapter) => adapter.descriptor.supportsDispatchSelection === true)) {
     flags.push("dispatch-selection");
   }
-  if (adapters.some((adapter) => adapter.capabilities().mcpToolsets === true)) {
+  if (adapters.some((adapter) => adapter.descriptor.capabilities.mcpToolsets === true)) {
     flags.push("toolset-selection");
   }
   return flags;
@@ -9215,7 +10047,6 @@ function validatePiByokLauncherConfig(launcher) {
     throw new Error("DaemonConfig.piByokLauncher.args must contain only non-empty single-line strings");
   }
 }
-var MAX_LOCAL_MCP_TOOLSETS = 64;
 var MAX_LOCAL_MCP_SERVERS_PER_TOOLSET = 16;
 var MAX_LOCAL_MCP_ARGS = 64;
 var MAX_LOCAL_MCP_TOKEN_CHARS = 4096;
@@ -9228,8 +10059,10 @@ function resolveMcpToolsets(configured) {
     throw new Error("DaemonConfig.mcpToolsets must be an object keyed by logical toolset id");
   }
   const toolsetEntries = Object.entries(configured);
-  if (toolsetEntries.length > MAX_LOCAL_MCP_TOOLSETS) {
-    throw new Error(`DaemonConfig.mcpToolsets may contain at most ${MAX_LOCAL_MCP_TOOLSETS} toolsets`);
+  if (toolsetEntries.length > CONFIGURED_TOOLSETS_MAX_ITEMS) {
+    throw new Error(
+      `DaemonConfig.mcpToolsets may contain at most ${CONFIGURED_TOOLSETS_MAX_ITEMS} toolsets`
+    );
   }
   const resolved = /* @__PURE__ */ new Map();
   for (const [toolsetId, rawToolset] of toolsetEntries) {
@@ -9342,6 +10175,9 @@ function createDaemonWithAdapters(config, adapters, overrides = {}) {
 }
 function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProbe) {
   const mcpToolsets = resolveMcpToolsets(config.mcpToolsets);
+  const configuredToolsets = Object.freeze(
+    [...mcpToolsets?.keys() ?? []].sort()
+  );
   if (config.piByokLauncher !== void 0) {
     validatePiByokLauncherConfig(config.piByokLauncher);
   }
@@ -9648,12 +10484,13 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
           dirty: event.observation ? { staged: event.observation.staged, unstaged: event.observation.unstaged, untracked: event.observation.untracked, conflicted: event.observation.conflicted } : void 0,
           errorCategory: event.errorCategory
         }),
+        onRuntimeDisposalFailure: (event) => observer.noteRuntimeDisposalFailure(event),
         // M4 Phase 3: the SAME `ApprovalRegistry` instance the control
         // socket's own `approvals.list`/`approvals.resolve` methods already
         // share (see that field's own construction above) — `TaskRunner
         // .requestApproval` registers into it directly, so a decision arriving
         // via either the server wire or the local CLI resolves the identical
-        // entry. `storeDir`/`productId` let `TaskContext.approvalChannel`
+        // entry. `storeDir`/`productId` let the prepared operation approval channel
         // (populated per-task by `TaskRunner`) tell an out-of-process helper
         // (`bin/byok-approval-mcp.ts`) exactly which control socket to dial.
         approvalRegistry,
@@ -9705,6 +10542,7 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
         productId: config.productId,
         capabilities,
         runtimes,
+        configuredToolsets,
         auth,
         cursorStore,
         // Finding F3: return (not void-and-forget) so ConnectionManager can
@@ -9791,6 +10629,7 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
           presencePublisher ??= new PresencePublisher({
             serverUrl: config.serverUrl,
             auth,
+            configuredToolsets,
             ...presenceCadence,
             onDegraded: (reason) => console.warn(`[byok/client] ${reason}`)
           });
@@ -9884,8 +10723,7 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
     await attempt(() => auth.stop(), true);
     connectionState = "closed";
     await attempt(async () => {
-      await controlServerHandle?.close();
-      controlServerHandle = void 0;
+      await controlServerHandle?.stopServing();
     }, true);
     if (mutationBarrierComplete && daemonOwnerLease) {
       await attempt(() => operationalHealth.markCleanStop(), false);
@@ -9894,6 +10732,12 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
         daemonOwnerLease = void 0;
       }, false);
     }
+    if (daemonOwnerLease === void 0) {
+      await attempt(async () => {
+        await controlServerHandle?.close();
+        controlServerHandle = void 0;
+      }, false);
+    }
     if (errors.length === 1) throw errors[0];
     if (errors.length > 1) {
       throw new AggregateError(errors, "daemon shutdown completed with errors");
@@ -9973,7 +10817,7 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
       deviceId: auth.deviceId,
       transport: connectionState,
       activeTasks,
-      runtimeIds: adapters.map((adapter) => adapter.id),
+      runtimeIds: adapters.map((adapter) => adapter.descriptor.id),
       // M4 Phase 4 (part B.3): queue watermarks come from TaskRunner's own
       // active-task map (distinct from `observer.tasks()` above, which is
       // derived from the envelope feed) — see `TaskRunner.getQueueWatermarks`'s
@@ -10181,7 +11025,7 @@ function createDaemon(config) {
   return createDaemonWithAdapters(config, buildDefaultAdapters(config));
 }
 var MAX_CONTROL_TOKEN_BYTES = 256;
-function errorMessage4(err) {
+function errorMessage5(err) {
   return err instanceof Error ? err.message : String(err);
 }
 function sameFileState3(left, right) {
@@ -10234,7 +11078,7 @@ async function connectControlClient(opts) {
     }
     token = read;
   } catch (err) {
-    return { ok: false, reason: `could not read the control token: ${errorMessage4(err)}` };
+    return { ok: false, reason: `could not read the control token: ${errorMessage5(err)}` };
   }
   if (!token) {
     return { ok: false, reason: "control token file is empty" };
@@ -10244,7 +11088,7 @@ async function connectControlClient(opts) {
     const client = await connectAndHandshake(endpoint, token, opts);
     return { ok: true, client };
   } catch (err) {
-    return { ok: false, reason: `daemon control socket not reachable: ${errorMessage4(err)}` };
+    return { ok: false, reason: `daemon control socket not reachable: ${errorMessage5(err)}` };
   }
 }
 function connectAndHandshake(endpoint, token, opts) {
@@ -10863,19 +11707,7 @@ function quote(text) {
 function redactedByteCountPlaceholder(text) {
   return `[redacted: ${Buffer.byteLength(text, "utf8")} bytes]`;
 }
-var STABLE_GIT_ERROR_CATEGORIES = /* @__PURE__ */ new Set([
-  "git-unavailable",
-  "git-timeout",
-  "git-output-limit",
-  "git-command-failed",
-  "workspace-root-invalid",
-  "workspace-root-conflict",
-  "workspace-not-owned",
-  "repository-root-mismatch",
-  "repository-invalid",
-  "lease-busy",
-  "ledger-invalid"
-]);
+var STABLE_GIT_ERROR_CATEGORIES = new Set(GIT_ERROR_CATEGORIES);
 function stableGitErrorCategory(value) {
   return value !== void 0 && STABLE_GIT_ERROR_CATEGORIES.has(value) ? value : void 0;
 }
@@ -10941,6 +11773,8 @@ function formatDaemonEventLine(event, options = {}) {
       return `${prefix} shutdown-complete reason=${quote(event.reason)}${event.undeliveredOutboxCount !== void 0 ? ` undeliveredOutboxCount=${event.undeliveredOutboxCount}` : ""}`;
     case "stale-approval-decision":
       return `${prefix} stale-approval-decision taskId=${event.taskId} decision=${event.decision}${event.reason ? ` reason=${quote(event.reason)}` : ""}`;
+    case "runtime-disposal-failed":
+      return `${prefix} runtime-disposal-failed taskId=${event.taskId} runtime=${event.runtimeId} stage=${event.stage} reason=${quote(event.reason)}`;
     case "git-workspace": {
       const parts = [
         `${prefix} git-workspace taskId=${event.taskId}`,
@@ -11219,8 +12053,8 @@ async function probeRuntimes(adapters, options = {}) {
       let resume = false;
       let permissionModes = [];
       try {
-        id = boundedSingleLine(adapter.id, MAX_RUNTIME_ID_CHARS);
-        const caps = adapter.capabilities();
+        id = boundedSingleLine(adapter.descriptor.id, MAX_RUNTIME_ID_CHARS);
+        const caps = adapter.descriptor.capabilities;
         steer = caps.steer === true;
         resume = caps.resume === true;
         permissionModes = caps.permissionModes.slice(0, MAX_PERMISSION_MODES).map((mode) => boundedSingleLine(mode, MAX_PERMISSION_MODE_CHARS));
@@ -12085,19 +12919,7 @@ function valueByteSize(value) {
 function placeholderFor(size) {
   return size === void 0 ? "[redacted]" : `[redacted: ${size} bytes]`;
 }
-var STABLE_GIT_ERROR_CATEGORIES2 = /* @__PURE__ */ new Set([
-  "git-unavailable",
-  "git-timeout",
-  "git-output-limit",
-  "git-command-failed",
-  "workspace-root-invalid",
-  "workspace-root-conflict",
-  "workspace-not-owned",
-  "repository-root-mismatch",
-  "repository-invalid",
-  "lease-busy",
-  "ledger-invalid"
-]);
+var STABLE_GIT_ERROR_CATEGORIES2 = new Set(GIT_ERROR_CATEGORIES);
 function stableGitErrorCategory2(value) {
   return typeof value === "string" && STABLE_GIT_ERROR_CATEGORIES2.has(value) ? value : void 0;
 }
@@ -12196,6 +13018,8 @@ function redactForAudit(event) {
       return { ...base, reason: event.reason, undeliveredOutboxCount: event.undeliveredOutboxCount };
     case "stale-approval-decision":
       return { ...base, taskId: event.taskId, decision: event.decision, reasonSize: byteSize(event.reason) };
+    case "runtime-disposal-failed":
+      return { ...base, taskId: event.taskId, runtimeId: event.runtimeId, stage: event.stage, reason: event.reason };
     case "device-assertion":
       return event.result === "issued" ? {
         ...base,
@@ -12344,6 +13168,15 @@ function reconstructDaemonEvent(raw) {
         reason: reasonSize === void 0 ? void 0 : placeholderFor(reasonSize)
       };
     }
+    case "runtime-disposal-failed":
+      return {
+        kind: "runtime-disposal-failed",
+        ts,
+        taskId: str(raw.taskId),
+        runtimeId: str(raw.runtimeId),
+        stage: str(raw.stage),
+        reason: str(raw.reason)
+      };
     case "device-assertion": {
       if (raw.result === "issued") {
         return {
@@ -12616,20 +13449,8 @@ async function runStartCommand(config, deps) {
     throw err;
   }
 }
-var STABLE_GIT_PHASES = /* @__PURE__ */ new Set(["preparing", "active", "completed", "failed", "cancelled", "interrupted", "salvage"]);
-var STABLE_GIT_ERROR_CATEGORIES3 = /* @__PURE__ */ new Set([
-  "git-unavailable",
-  "git-timeout",
-  "git-output-limit",
-  "git-command-failed",
-  "workspace-root-invalid",
-  "workspace-root-conflict",
-  "workspace-not-owned",
-  "repository-root-mismatch",
-  "repository-invalid",
-  "lease-busy",
-  "ledger-invalid"
-]);
+var STABLE_GIT_PHASES = new Set(GIT_WORKSPACE_PHASES);
+var STABLE_GIT_ERROR_CATEGORIES3 = new Set(GIT_ERROR_CATEGORIES);
 function nonNegativeSafeInteger(value) {
   return value !== void 0 && Number.isSafeInteger(value) && value >= 0 ? value : void 0;
 }
@@ -13128,19 +13949,7 @@ async function runUnpairCommand(daemon, deps = {}) {
 }
 
 // src/bin/commands/workspaces.ts
-var STABLE_ERROR_CATEGORIES = /* @__PURE__ */ new Set([
-  "git-unavailable",
-  "git-timeout",
-  "git-output-limit",
-  "git-command-failed",
-  "workspace-root-invalid",
-  "workspace-root-conflict",
-  "workspace-not-owned",
-  "repository-root-mismatch",
-  "repository-invalid",
-  "lease-busy",
-  "ledger-invalid"
-]);
+var STABLE_ERROR_CATEGORIES = new Set(GIT_ERROR_CATEGORIES);
 function abbreviateCommit(value) {
   if (!value) return "-";
   return value.length > 8 ? value.slice(0, 8) : value;