zeitlich 0.2.41 → 0.2.42

package/src/lib/session/session.ts

@@ -6,11 +6,14 @@ import {
 } from "@temporalio/workflow";
 import type { SessionExitReason } from "../types";
 import type { SessionConfig, ZeitlichSession } from "./types";
+import { resolveSessionLifecycle } from "./types";
 import type {
+  SandboxCapability,
   SandboxCreateOptions,
   SandboxOps,
   SandboxSnapshot,
 } from "../sandbox/types";
+import type { SandboxInit, SubagentSandboxShutdown } from "../lifecycle";
 import type {
   AgentState,
   AgentStateManager,
@@ -79,41 +82,89 @@ export async function createSession<
   T extends ToolMap,
   M = unknown,
   TContent = string,
+  TInit extends SandboxInit | undefined = undefined,
+  TShutdown extends SubagentSandboxShutdown | undefined = undefined,
 >(
-  config: SessionConfig<T, M, TContent> & { sandboxOps: SandboxOps }
+  config: SessionConfig<T, M, TContent, TInit, TShutdown> & {
+    sandboxOps: NonNullable<
+      SessionConfig<T, M, TContent, TInit, TShutdown>["sandboxOps"]
+    >;
+  }
 ): Promise<ZeitlichSession<M, true>>;
 export async function createSession<
   T extends ToolMap,
   M = unknown,
   TContent = string,
->(config: SessionConfig<T, M, TContent>): Promise<ZeitlichSession<M, false>>;
+  TInit extends SandboxInit | undefined = undefined,
+  TShutdown extends SubagentSandboxShutdown | undefined = undefined,
+>(
+  config: SessionConfig<T, M, TContent, TInit, TShutdown>
+): Promise<ZeitlichSession<M, false>>;
+// Implementation. The overloads above narrow the public contract per
+// `SessionRequiredCaps<TInit, TShutdown>`. The impl signature uses the
+// `never` cap floor — the structurally-narrowest shape that every
+// adapter (including Daytona/Bedrock) satisfies — so each overload's
+// possibly-narrow `sandboxOps` is assignable here. Gated method calls
+// inside the body go through `wideOps()` below, which casts the
+// narrow-typed binding to the wide shape. This is structurally safe:
+// the runtime gates each gated call on `sandboxMode === …` /
+// `resolvedShutdown === …`, and the type system has already ruled out
+// any (mode, shutdown, adapter) cell that would invoke a missing
+// method.
 export async function createSession<
   T extends ToolMap,
   M = unknown,
   TContent = string,
->({
-  agentName,
-  maxTurns = 50,
-  metadata = {},
-  runAgent,
-  threadOps,
-  buildContextMessage,
-  subagents,
-  skills,
-  tools = {} as T,
-  processToolsInParallel = true,
-  hooks = {},
-  appendSystemPrompt = true,
-  threadKey,
-  sandboxOps,
-  thread: threadInit,
-  sandbox: sandboxInit,
-  sandboxShutdown = "destroy",
-  onSandboxReady,
-  onSessionExit,
-  virtualFs: virtualFsConfig,
-  virtualFsOps,
-}: SessionConfig<T, M, TContent>): Promise<ZeitlichSession<M, boolean>> {
+>(
+  config: Omit<
+    SessionConfig<T, M, TContent, SandboxInit | undefined, undefined>,
+    "sandboxOps"
+  > & {
+    sandboxOps?: SandboxOps<SandboxCreateOptions, unknown, never>;
+  }
+): Promise<ZeitlichSession<M, boolean>> {
+  const {
+    agentName,
+    maxTurns = 50,
+    metadata = {},
+    runAgent,
+    threadOps,
+    buildContextMessage,
+    subagents,
+    skills,
+    tools = {} as T,
+    processToolsInParallel = true,
+    hooks = {},
+    appendSystemPrompt = true,
+    threadKey,
+    sandboxOps,
+    thread: threadInit,
+    sandbox: sandboxInit,
+    sandboxShutdown,
+    onSandboxReady,
+    onSessionExit,
+    virtualFs: virtualFsConfig,
+    virtualFsOps,
+  } = config;
+
+  /**
+   * The narrow-typed `sandboxOps` binding cast to its wide
+   * (`SandboxCapability`) form. The overload signatures +
+   * `SessionRequiredCaps` SSOT have already ruled out `(sandbox.mode,
+   * sandboxShutdown, adapter)` combinations where a referenced method
+   * would be missing on the proxy, and each gated call site below is
+   * guarded by an `if (sandboxOps)` / `sandboxOps &&` runtime check,
+   * so the cast is structurally safe. `wideOps` returns the wide-cap
+   * shape; callers use it after their own runtime guard establishes
+   * that `sandboxOps` is defined.
+   */
+  type WideSandboxOps = SandboxOps<
+    SandboxCreateOptions,
+    unknown,
+    SandboxCapability
+  >;
+  const wideOps = (): WideSandboxOps =>
+    sandboxOps as unknown as WideSandboxOps;
   // ---------------------------------------------------------------------------
   // Thread resolution
   // ---------------------------------------------------------------------------
@@ -219,7 +270,18 @@ export async function createSession<
       );
 
       // --- Sandbox lifecycle: create, continue, fork, from-snapshot, or inherit ---
-      const sandboxMode = sandboxInit?.mode;
+      // Resolve `sandbox` / `sandboxShutdown` defaults through the SSOT
+      // so the runtime dispatch below and the type-level
+      // `SessionRequiredCaps` cannot disagree on what the documented
+      // defaults are. Both surfaces consult `resolveSessionLifecycle`
+      // (or its type-level equivalent) before checking individual
+      // mode/shutdown values.
+      const lifecycle = resolveSessionLifecycle(
+        sandboxInit,
+        sandboxShutdown
+      );
+      const sandboxMode: SandboxInit["mode"] | undefined = lifecycle.mode;
+      const resolvedShutdown: SubagentSandboxShutdown = lifecycle.shutdown;
       let sandboxId: string | undefined;
       let sandboxOwned = false;
       let baseSnapshot: SandboxSnapshot | undefined;
@@ -248,8 +310,8 @@ export async function createSession<
         }
         sandboxId = (sandboxInit as { mode: "continue"; sandboxId: string })
           .sandboxId;
-        if (sandboxShutdown === "pause-until-parent-close") {
-          await sandboxOps.resumeSandbox(sandboxId);
+        if (resolvedShutdown === "pause-until-parent-close") {
+          await wideOps().resumeSandbox(sandboxId);
         }
         sandboxOwned = true;
       } else if (sandboxMode === "fork") {
@@ -264,7 +326,7 @@ export async function createSession<
           sandboxId: string;
           options?: SandboxCreateOptions;
         };
-        sandboxId = await sandboxOps.forkSandbox(
+        sandboxId = await wideOps().forkSandbox(
           forkInit.sandboxId,
           forkInit.options
         );
@@ -281,7 +343,7 @@ export async function createSession<
           snapshot: SandboxSnapshot;
           options?: SandboxCreateOptions;
         };
-        sandboxId = await sandboxOps.restoreSandbox(
+        sandboxId = await wideOps().restoreSandbox(
           restoreInit.snapshot,
           restoreInit.options
         );
@@ -308,10 +370,10 @@ export async function createSession<
         sandboxId &&
         sandboxOwned &&
         freshlyCreated &&
-        sandboxShutdown === "snapshot" &&
+        resolvedShutdown === "snapshot" &&
         sandboxOps
       ) {
-        baseSnapshot = await sandboxOps.snapshotSandbox(sandboxId);
+        baseSnapshot = await wideOps().snapshotSandbox(sandboxId);
       }
 
       if (sandboxId && sandboxOwned && onSandboxReady) {
@@ -571,19 +633,19 @@ export async function createSession<
         await callSessionEnd(exitReason, stateManager.getTurns());
 
         if (sandboxOwned && sandboxId && sandboxOps) {
-          switch (sandboxShutdown) {
+          switch (resolvedShutdown) {
             case "destroy":
               await sandboxOps.destroySandbox(sandboxId);
               break;
             case "pause":
             case "pause-until-parent-close":
-              await sandboxOps.pauseSandbox(sandboxId);
+              await wideOps().pauseSandbox(sandboxId);
               break;
             case "keep":
             case "keep-until-parent-close":
               break;
             case "snapshot":
-              exitSnapshot = await sandboxOps.snapshotSandbox(sandboxId);
+              exitSnapshot = await wideOps().snapshotSandbox(sandboxId);
               await sandboxOps.destroySandbox(sandboxId);
               break;
           }

package/src/lib/session/types.ts

@@ -7,7 +7,12 @@ import type {
 import type { Hooks } from "../hooks/types";
 import type { SubagentConfig } from "../subagent/types";
 import type { Skill } from "../skills/types";
-import type { SandboxOps, SandboxSnapshot } from "../sandbox/types";
+import type {
+  SandboxCapability,
+  SandboxCreateOptions,
+  SandboxOps,
+  SandboxSnapshot,
+} from "../sandbox/types";
 import type { VirtualFsOps } from "../virtual-fs/types";
 import type { RunAgentActivity } from "../model/types";
 import type {
@@ -137,17 +142,171 @@ export type PrefixedThreadOps<TPrefix extends string, TContent = string> = {
   [K in keyof ThreadOps<TContent> as `${TPrefix}${Capitalize<K & string>}`]: ThreadOps<TContent>[K];
 };
 
+// ============================================================================
+// Session sandbox-lifecycle decision table (SSOT)
+//
+// `createSession` (`src/lib/session/session.ts`) dispatches gated
+// sandbox methods based on `(sandbox.mode, sandboxShutdown)`. When a
+// caller omits either field, the session uses the documented defaults
+// (`sandbox: { mode: "new" }` and `sandboxShutdown: "destroy"`),
+// which trigger only base ops (`createSandbox` / `destroySandbox`).
+//
+// Two surfaces have to agree on what gated methods may fire for a
+// given config:
+//
+//   1. The runtime — what the session dispatches per `(mode,
+//      shutdown)` pair.
+//   2. The type level — what caps `sandboxOps` has to advertise.
+//
+// `SessionRequiredCaps<TInit, TShutdown>` is the SSOT for the type
+// level. `resolveSessionLifecycle(init, shutdown)` (in `session.ts`,
+// re-exported below) is the runtime mirror. Adding a new branch to
+// `session.ts` requires extending **both**; the
+// `(sandbox.mode × sandboxShutdown × adapter)` matrix in
+// `src/lib/sandbox/capability-types.test.ts` enforces agreement.
+// ============================================================================
+
+/**
+ * Caps the session's sandbox-init dispatch may invoke for a given
+ * `(mode, shutdown)`. Mirror of `src/lib/session/session.ts:241-313`.
+ *
+ * The conditional branches are written non-distributively (each cap
+ * checked against the input `M` / `S` rather than over a union) so
+ * that the *omitted* case (defaults: M = "new", S = "destroy") flows
+ * through to `never`, not to "I don't know, assume everything."
+ */
+type _SessionInitCaps<M, S> =
+  | (M extends "fork" ? "fork" : never)
+  | (M extends "from-snapshot" ? "restore" : never)
+  | (M extends "continue"
+      ? S extends "pause-until-parent-close"
+        ? "resume"
+        : never
+      : never);
+
+/**
+ * Caps the session's exit dispatch may invoke. `"inherit"` mode keeps
+ * `sandboxOwned = false` so exit-shutdown caps NEVER fire — mirror of
+ * `src/lib/session/session.ts:598-615`.
+ */
+type _SessionExitCaps<M, S> = M extends "inherit"
+  ? never
+  :
+      | (S extends "snapshot" ? "snapshot" : never)
+      | (S extends "pause" | "pause-until-parent-close" ? "pause" : never);
+
+/**
+ * Cap captured on entry for `mode: "new"` + `shutdown: "snapshot"` (the
+ * seeding-base-snapshot path). Mirror of
+ * `src/lib/session/session.ts:316-317`.
+ */
+type _SessionSeedCaps<M, S> = M extends "new"
+  ? S extends "snapshot"
+    ? "snapshot"
+    : never
+  : never;
+
+/**
+ * Resolves an omitted `sandbox` field to the runtime default
+ * `{ mode: "new" }`, and an omitted `sandboxShutdown` field to the
+ * runtime default `"destroy"`. The two `_Resolve…` helpers are the
+ * sole bridge between "user didn't set the field" and the SSOT below
+ * — keeping the defaults out of the conditional table itself.
+ */
+type _ResolveInit<TInit> = [TInit] extends [undefined]
+  ? { mode: "new" }
+  : Exclude<TInit, undefined> extends infer Defined
+    ? // If the user passed `SandboxInit | undefined` (the wide default),
+      // collapse `undefined` to the runtime default.
+      undefined extends TInit
+      ? Defined | { mode: "new" }
+      : Defined
+    : never;
+
+type _ResolveShutdown<TShutdown> = [TShutdown] extends [undefined]
+  ? "destroy"
+  : Exclude<TShutdown, undefined> extends infer Defined
+    ? undefined extends TShutdown
+      ? Defined | "destroy"
+      : Defined
+    : never;
+
+/**
+ * Sandbox capabilities a session actually invokes on its
+ * `sandboxOps`, derived from the literal types of the surrounding
+ * `sandbox` and `sandboxShutdown` fields.
+ *
+ * `TInit` / `TShutdown` default to `undefined` so an un-parameterised
+ * `SessionRequiredCaps` resolves to the caps the runtime *defaults*
+ * (`{ mode: "new" }` + `"destroy"`) actually require — i.e.
+ * `never`. This lets a narrow adapter (e.g. `proxyDaytonaSandboxOps`)
+ * satisfy `sandboxOps?: SandboxOps<…, SessionRequiredCaps<…>>` when
+ * the caller doesn't pin literals, matching what's runtime-safe.
+ *
+ * Pin literals via `as const` or by ascribing `SessionConfig<…, TInit,
+ * TShutdown>` to tighten the requirement on a per-call basis.
+ */
+export type SessionRequiredCaps<
+  TInit extends SandboxInit | undefined = undefined,
+  TShutdown extends SubagentSandboxShutdown | undefined = undefined,
+> = _ResolveInit<TInit> extends infer M
+  ? _ResolveShutdown<TShutdown> extends infer S
+    ? M extends { mode: infer Mode }
+      ? S extends SubagentSandboxShutdown
+        ?
+            | _SessionInitCaps<Mode, S>
+            | _SessionExitCaps<Mode, S>
+            | _SessionSeedCaps<Mode, S>
+        : never
+      : never
+    : never
+  : never;
+
+/**
+ * Runtime mirror of `SessionRequiredCaps`. Returns the names of the
+ * gated `sandboxOps` methods the session will invoke for a given
+ * `(sandboxInit, sandboxShutdown)` pair (after resolving documented
+ * defaults). Mirror of the dispatch in
+ * `src/lib/session/session.ts:241-313` and `:598-615`.
+ *
+ * Both surfaces consult this same table — the `(mode × shutdown ×
+ * adapter)` matrix in `src/lib/sandbox/capability-types.test.ts`
+ * enforces agreement.
+ */
+export function resolveSessionLifecycle(
+  init: SandboxInit | undefined,
+  shutdown: SubagentSandboxShutdown | undefined
+): { mode: SandboxInit["mode"]; shutdown: SubagentSandboxShutdown } {
+  const resolvedInit: SandboxInit = init ?? { mode: "new" };
+  const resolvedShutdown: SubagentSandboxShutdown = shutdown ?? "destroy";
+  return {
+    mode: resolvedInit.mode,
+    shutdown: resolvedShutdown,
+  };
+}
+
 /**
  * Configuration for a Zeitlich agent session.
  *
  * @typeParam T - Tool map
  * @typeParam M - SDK-native message type returned by the model invoker
  * @typeParam TContent - SDK-native content type for human messages (defaults to `string`)
+ * @typeParam TInit - Literal type of `sandbox` (a {@link SandboxInit}
+ *   variant or `undefined`). Defaults to the wide union; pin it via
+ *   `as const` on the call site to narrow the cap requirement on
+ *   `sandboxOps`.
+ * @typeParam TShutdown - Literal type of `sandboxShutdown`. Defaults
+ *   to the wide union; pin it via `as const` on the call site to
+ *   narrow the cap requirement on `sandboxOps`.
  */
 export interface SessionConfig<
   T extends ToolMap,
   M = unknown,
   TContent = string,
+  TInit extends SandboxInit | undefined = SandboxInit | undefined,
+  TShutdown extends
+    | SubagentSandboxShutdown
+    | undefined = SubagentSandboxShutdown | undefined,
 > {
   /** The name of the agent, should be unique within the workflows */
   agentName: string;
@@ -203,8 +362,25 @@ export interface SessionConfig<
   // Sandbox lifecycle
   // ---------------------------------------------------------------------------
 
-  /** Sandbox lifecycle operations (optional — omit for agents that don't need a sandbox) */
-  sandboxOps?: SandboxOps;
+  /**
+   * Sandbox lifecycle operations (optional — omit for agents that don't
+   * need a sandbox).
+   *
+   * The `TCaps` argument is derived from {@link SessionRequiredCaps}
+   * over the literal types of the surrounding `sandbox` and
+   * `sandboxShutdown` fields. With the default wide
+   * `TInit` / `TShutdown`, this resolves to the full
+   * {@link SandboxCapability} union (current behaviour). When the
+   * caller pins those literals via `as const`, the cap requirement
+   * tightens so a narrow adapter (e.g. Daytona's
+   * `SandboxOps<…, never>`) can satisfy combinations that don't need
+   * a gated method.
+   */
+  sandboxOps?: SandboxOps<
+    SandboxCreateOptions,
+    unknown,
+    SessionRequiredCaps<TInit, TShutdown> & SandboxCapability
+  >;
   /**
    * Sandbox initialization strategy.
    *
@@ -215,14 +391,14 @@ export interface SessionConfig<
    *
    * When omitted and `sandboxOps` is provided, defaults to `{ mode: "new" }`.
    */
-  sandbox?: SandboxInit;
+  sandbox?: TInit;
   /**
    * What to do with the sandbox when this session exits.
    *
    * Defaults to `"destroy"` when omitted.
    * Has no effect when the sandbox is inherited (`sandbox.mode === "inherit"`).
    */
-  sandboxShutdown?: SubagentSandboxShutdown;
+  sandboxShutdown?: TShutdown;
   /**
    * Called as soon as the sandbox is created (or resumed/forked), before the
    * agent loop starts. Useful for signalling sandbox readiness to a parent.

package/src/lib/subagent/handler.ts

@@ -6,16 +6,19 @@ import {
   ApplicationFailure,
   executeChild,
 } from "@temporalio/workflow";
+import type { Duration } from "@temporalio/common";
 import { getShortId } from "../thread/id";
 import type { ToolHandlerResponse, RouterContext } from "../tool-router";
 import type { JsonValue } from "../state/types";
 import type {
   InferSubagentResult,
+  ResolvedSubagentSandboxConfig,
   SubagentConfig,
   SubagentFnResult,
   SubagentSandboxConfig,
   SubagentWorkflowInput,
 } from "./types";
+import { resolveSubagentLifecycle } from "./types";
 import type { SubagentArgs } from "./tool";
 import type { z } from "zod";
 import type {
@@ -23,9 +26,33 @@ import type {
   SandboxInit,
   SubagentSandboxShutdown,
 } from "../lifecycle";
-import type { SandboxOps, SandboxSnapshot } from "../sandbox/types";
+import type {
+  SandboxCreateOptions,
+  SandboxOps,
+  SandboxSnapshot,
+} from "../sandbox/types";
 import { childSandboxReadySignal } from "./signals";
 
+/**
+ * Methods the parent's subagent handler invokes on a subagent's `proxy`.
+ * Kept narrow so the handler's internal maps accept `SandboxOps<…, never>`
+ * (e.g. Daytona) and `SandboxOps<…, "snapshot">` (e.g. E2B for
+ * snapshot-driven continuations) alike.
+ *
+ * `destroySandbox` is base — always available.
+ * `deleteSandboxSnapshot` is only called for continuations that produce
+ * snapshots; it's stored separately and only populated when present on
+ * the cfg-specific proxy.
+ */
+type ParentDestroyOps = Pick<
+  SandboxOps<SandboxCreateOptions, unknown, never>,
+  "destroySandbox"
+>;
+type ParentDeleteSnapshotOps = Pick<
+  SandboxOps<SandboxCreateOptions, unknown, "snapshot">,
+  "deleteSandboxSnapshot"
+>;
+
 /**
  * Default `workflowRunTimeout` applied to every subagent child workflow
  * unless overridden via `SubagentConfig.workflowOptions.workflowRunTimeout`.
@@ -40,19 +67,11 @@ import { childSandboxReadySignal } from "./signals";
  * still catching hangs; agents that legitimately need longer should set an
  * explicit `workflowOptions.workflowRunTimeout`.
  */
-export const DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT = "1h";
-
-/** Normalized sandbox config after resolving the union. */
-interface ResolvedSandboxConfig {
-  source: "none" | "inherit" | "own";
-  init: "per-call" | "once";
-  continuation: "continue" | "fork" | "snapshot";
-  shutdown?: SubagentSandboxShutdown;
-}
+export const DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT: Duration = "1h";
 
 function resolveSandboxConfig(
   config?: SubagentSandboxConfig
-): ResolvedSandboxConfig {
+): ResolvedSubagentSandboxConfig {
   if (!config || config === "none") {
     return { source: "none", init: "per-call", continuation: "fork" };
   }
@@ -96,11 +115,31 @@ export function createSubagentHandler<
 } {
   const { taskQueue: parentTaskQueue } = workflowInfo();
 
-  /** Sandbox ops proxy per subagent, built eagerly from `sandbox.proxy` factories. */
-  const agentSandboxOps = new Map<string, SandboxOps>();
+  /**
+   * Sandbox ops proxy per subagent, built eagerly from `sandbox.proxy`
+   * factories.
+   *
+   * Split into two maps so each accepts only the cap-narrowed slice the
+   * parent actually consumes. `destroyOps` accepts every adapter (base
+   * `destroySandbox` is always present); `deleteSnapshotOps` is only
+   * populated for `continuation: "snapshot"` configs, and the
+   * `SubagentSandboxConfig` type guarantees the proxy carries
+   * `deleteSandboxSnapshot` when that continuation is selected.
+   */
+  const agentDestroyOps = new Map<string, ParentDestroyOps>();
+  const agentDeleteSnapshotOps = new Map<string, ParentDeleteSnapshotOps>();
   for (const cfg of subagents) {
-    if (cfg.sandbox && cfg.sandbox !== "none") {
-      agentSandboxOps.set(cfg.agentName, cfg.sandbox.proxy(cfg.agentName));
+    const cfgSandbox = cfg.sandbox;
+    if (!cfgSandbox || cfgSandbox === "none") continue;
+    if (cfgSandbox.continuation === "snapshot") {
+      // Pull the proxy here so the per-branch narrowing keeps
+      // `deleteSandboxSnapshot` in the inferred return type.
+      const proxy = cfgSandbox.proxy(cfg.agentName);
+      agentDestroyOps.set(cfg.agentName, proxy);
+      agentDeleteSnapshotOps.set(cfg.agentName, proxy);
+    } else {
+      const proxy = cfgSandbox.proxy(cfg.agentName);
+      agentDestroyOps.set(cfg.agentName, proxy);
     }
   }
 
@@ -182,7 +221,7 @@ export function createSubagentHandler<
 
     if (
       sandboxCfg.source !== "none" &&
-      !agentSandboxOps.has(config.agentName)
+      !agentDestroyOps.has(config.agentName)
     ) {
       throw ApplicationFailure.create({
         message: `Subagent "${config.agentName}" uses a sandbox but no \`sandbox.proxy\` is configured on its SubagentConfig`,
@@ -272,7 +311,6 @@ export function createSubagentHandler<
       if (baseSnap) {
         sandbox = { mode: "from-snapshot", snapshot: baseSnap };
       }
-      sandboxShutdownOverride = "snapshot";
     } else if (sandboxCfg.source === "own") {
       const isLazy = sandboxCfg.init === "once";
 
@@ -318,31 +356,16 @@ export function createSubagentHandler<
           sandboxId: baseSandboxId,
         };
       }
+    }
 
-      // Ensure the sandbox survives for future continuation/fork:
-      // - first lazy call (creator): pause-until-parent-close so parent can clean up
-      // - continuation=continue: sandbox must survive for next call
-      // - lazy+fork (non-creator): template must survive for future forks
-      //
-      // Skip the override when the user already configured a *-until-parent-close
-      // shutdown — that already guarantees survival.
-      const userShutdown = sandboxCfg.shutdown;
-      const alreadySurvives =
-        userShutdown === "pause-until-parent-close" ||
-        userShutdown === "keep-until-parent-close" ||
-        userShutdown === "pause" ||
-        userShutdown === "keep";
-
-      const mustSurvive =
-        isLazyCreator ||
-        sandboxCfg.continuation === "continue" ||
-        (isLazy && sandboxCfg.continuation === "fork");
-
-      if (mustSurvive && !alreadySurvives) {
-        sandboxShutdownOverride = isLazyCreator
-          ? "pause-until-parent-close"
-          : "pause";
-      }
+    // Resolve the lifecycle decision (auto-inject pause/snapshot, etc.)
+    // through the SSOT — same table the type-level `SubagentRequiredCaps`
+    // reads. Adding a new branch here means changing both. The matrix
+    // in `src/lib/sandbox/capability-types.test.ts` enforces the
+    // type-level / runtime agreement.
+    {
+      const lifecycle = resolveSubagentLifecycle(sandboxCfg, isLazyCreator);
+      sandboxShutdownOverride = lifecycle.shutdownOverride;
     }
 
     const workflowInput: SubagentWorkflowInput = {
@@ -555,7 +578,7 @@ export function createSubagentHandler<
     pendingDestroys.clear();
     await Promise.all(
       entries.map(async ({ agentName, sandboxId }) => {
-        const ops = agentSandboxOps.get(agentName);
+        const ops = agentDestroyOps.get(agentName);
         if (!ops) {
           log.warn(
             "Skipping sandbox destroy — no sandbox.proxy registered for agent",
@@ -587,7 +610,7 @@ export function createSubagentHandler<
 
     await Promise.all(
       tagged.map(async ({ agentName, snapshot }) => {
-        const ops = agentSandboxOps.get(agentName);
+        const ops = agentDeleteSnapshotOps.get(agentName);
         if (!ops) {
           log.warn(
             "Skipping snapshot delete — no sandbox.proxy registered for agent",