@tanstack/ai-sandbox 0.2.3 → 0.3.0

package/src/runner.ts

@@ -6,8 +6,27 @@
  *
  * This is intentionally transport-minimal: a stdout NDJSON pipe. Multi-client
  * reconnect / replay belongs to the persistence/EventLog layer, not here.
+ *
+ * The `journal` option adds a second, opt-in transport: instead of holding the
+ * agent's stdout pipe directly, the host redirects it into an append-only file
+ * inside the sandbox and tails that file. See `journal.ts` for why (host death
+ * cannot SIGPIPE the agent, and a later host can resume the same file from byte
+ * 0). `spawnNdjson`'s signature and unjournaled behavior are unchanged; every
+ * existing caller keeps working exactly as before.
  */
+import {
+  journalCleanupCommand,
+  journalPaths,
+  journalStderrReadCommand,
+  journaledCommand,
+  parseExitSentinel,
+} from './journal'
+import { readJournal } from './journal-reader'
+import { decodeBase64Stream } from './journal-bytes'
+import { awaitAttachableJournal } from './attach-preflight'
+import type { JournalPaths } from './journal'
 import type { ProcessOptions, SandboxHandle } from './contracts'
+import type { RunStore } from '@tanstack/ai'
 
 export interface SpawnNdjsonOptions extends ProcessOptions {
   /**
@@ -20,6 +39,97 @@ export interface SpawnNdjsonOptions extends ProcessOptions {
    * e.g. the agent prompt for `claude -p`. Avoids putting the prompt in argv.
    */
   input?: string
+  /**
+   * Route the agent's stdout through an in-sandbox journal rather than holding
+   * its pipe directly.
+   *
+   * This is what makes a run survive host death: with nothing piped, there is
+   * no reader whose disappearance can SIGPIPE the agent, and a later host reads
+   * the same file from byte 0. Opt-in so every existing caller (and every
+   * existing test) is unaffected.
+   */
+  journal?: JournalOptions
+}
+
+/** Journaling configuration for {@link spawnNdjson}. */
+export interface JournalOptions {
+  /** Run id the journal path is derived from. Must match across hosts. */
+  runId: string
+  /** Journal directory. Defaults to `/tmp/tanstack-runs`. */
+  dir?: string
+  /**
+   * Read an EXISTING journal instead of starting the agent. The read still
+   * begins at byte 0 — the alignment step, not the reader, decides what has
+   * already been delivered.
+   */
+  attach?: boolean
+  /** Poll interval for providers that cannot follow. */
+  pollIntervalMs?: number
+  /**
+   * Run record store, consulted ONLY on an attach and only when the journal is
+   * absent, to tell "not written yet" from "will never be written" (see
+   * `attach-preflight.ts`). Optional so an attach with no store wired keeps the
+   * bounded wait while losing the unknown/terminal classification.
+   */
+  runs?: RunStore
+  /**
+   * Bounded wait for a live run's journal to appear on an attach, AND — on every
+   * path, attach or fresh — the bound on the read's first byte
+   * (`ReadJournalOptions.firstByteTimeoutMs`). One knob for both because they
+   * bound the same question from two sides: the preflight covers "the file does
+   * not exist", the read covers "the file exists but nothing is writing to it",
+   * and a caller that widens one always means to widen the other.
+   *
+   * Defaults to `DEFAULT_ATTACH_JOURNAL_WAIT_MS`.
+   */
+  attachWaitMs?: number
+}
+
+type JournaledOptions = SpawnNdjsonOptions & { journal: JournalOptions }
+
+function isJournaled(options: SpawnNdjsonOptions): options is JournaledOptions {
+  return options.journal !== undefined
+}
+
+function resolvePaths(options: JournaledOptions) {
+  return journalPaths(options.journal.runId, options.journal.dir)
+}
+
+/**
+ * Strip the runner-only options, leaving what `handle.process.spawn` accepts.
+ *
+ * `signal` is deliberately KEPT: on the UNJOURNALED path the host holds the
+ * agent's stdout pipe, so a client disconnect should take the process down with
+ * it. The journaled path must not forward it — see
+ * {@link toJournaledSpawnOptions}.
+ */
+function toProcessOptions(options: SpawnNdjsonOptions): ProcessOptions {
+  const { onNonJsonLine, input, journal, ...rest } = options
+  void onNonJsonLine
+  void input
+  void journal
+  return rest
+}
+
+/**
+ * The journaled agent's spawn options: {@link toProcessOptions} MINUS `signal`.
+ *
+ * The request's signal must never reach the agent process on this path. Providers
+ * DO act on it at spawn time — local-process registers it to `killTree` the
+ * process group, and daytona and docker honor it too — so forwarding it means a
+ * client disconnect kills the journaled agent. The agent then writes no exit
+ * sentinel, and a successor host takes over a run that is already dead: the exact
+ * opposite of the guarantee documented on {@link startJournaledAgent}, and of the
+ * reason the journal is a file rather than a pipe.
+ *
+ * The signal is still honored for the READ. `readJournalNdjson` forwards it to
+ * `readJournal` and `awaitAttachableJournal` on its own, so a disconnecting
+ * client stops tailing immediately. Only the agent spawn outlives the request.
+ */
+function toJournaledSpawnOptions(options: JournaledOptions): ProcessOptions {
+  const { signal, ...rest } = toProcessOptions(options)
+  void signal
+  return rest
 }
 
 /** Split a stream of arbitrary string chunks into complete lines. */
@@ -40,16 +150,250 @@ export async function* toLines(
   if (buffer.length > 0) yield buffer
 }
 
+/**
+ * Start the agent with its stdout (and the `{"__exit":N}` sentinel) redirected
+ * into the journal, then return.
+ *
+ * Deliberately does NOT wait for the process and does NOT read its stdout: the
+ * whole point of journaling is that the host holds no handle on the agent's
+ * output, so a host that dies mid-run cannot take the agent down with it (no
+ * pipe to SIGPIPE). The spawned process is left running in the sandbox; the
+ * sentinel line the wrapper appends on exit is how anyone — this host or a
+ * successor — learns it finished. Stdin is still written directly to the
+ * spawned process, exactly as the unjournaled path does, since that transport
+ * is unaffected by where stdout goes.
+ */
+export async function startJournaledAgent(
+  handle: SandboxHandle,
+  command: string,
+  options: JournaledOptions,
+): Promise<void> {
+  const paths = resolvePaths(options)
+  const proc = await handle.process.spawn(
+    journaledCommand(command, paths),
+    toJournaledSpawnOptions(options),
+  )
+  if (options.input !== undefined) {
+    await proc.stdin.write(options.input)
+    await proc.stdin.end()
+  }
+}
+
+/** Chars of stderr attached to a non-zero-exit error, on both paths. */
+const STDERR_ERROR_CHARS = 1000
+
+async function* singleValue(value: string): AsyncIterable<string> {
+  yield value
+}
+
+/**
+ * Read the tail of a run's stderr sidecar, for the error message only.
+ *
+ * Returns `''` on ANY failure — a provider whose `exec` rejects, a sidecar that
+ * no longer exists, a base64 frame the provider truncated. The caller is on its
+ * way to throwing the real failure (the agent's non-zero exit), and losing a
+ * diagnostic suffix must never replace that error with a cleanup error. Decoding
+ * is deliberately lossy: `journalStderrReadCommand` reads the LAST N bytes, so
+ * byte 0 of the frame can sit mid-character.
+ */
+async function readStderrTail(
+  handle: SandboxHandle,
+  paths: JournalPaths,
+): Promise<string> {
+  try {
+    const result = await handle.process.exec(journalStderrReadCommand(paths))
+    const decoder = new TextDecoder()
+    let text = ''
+    for await (const bytes of decodeBase64Stream(singleValue(result.stdout))) {
+      text += decoder.decode(bytes, { stream: true })
+    }
+    text += decoder.decode()
+    return text.trim()
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * Delete a terminal run's journal. Best effort by construction: see
+ * {@link journalCleanupCommand} for why a failure here cannot be allowed to fail
+ * a run that has already finished.
+ */
+async function cleanupJournal(
+  handle: SandboxHandle,
+  paths: JournalPaths,
+): Promise<void> {
+  try {
+    await handle.process.exec(journalCleanupCommand(paths))
+  } catch {
+    // The sandbox may already be gone, `/tmp` may be read-only, the provider's
+    // `exec` may reject. Nothing about a completed run depends on the files
+    // still existing OR on them being gone, so there is nothing to report.
+  }
+}
+
+/**
+ * Read a run's journal and yield each line parsed as JSON.
+ *
+ * Always reads from byte 0 — the alignment step (a later phase), not this
+ * reader, decides what a client has already seen. Stops at the `{"__exit":N}`
+ * sentinel, and throws for a non-zero N so the calling adapter's existing
+ * `catch` turns it into a `RUN_ERROR`, the same observable outcome the
+ * unjournaled path produces from a non-zero `wait()`. There is nothing to
+ * `wait()` on here: the host holds a `tail`, not the agent process, so the
+ * sentinel line IS the exit code.
+ *
+ * The sentinel is also what bounds journal growth: reaching it means the run is
+ * terminal, and a terminal run's record is the event log, so both journal files
+ * are deleted before this iterable finishes. The ordering below is load-bearing
+ * and is asserted, not merely commented:
+ *
+ * - The sentinel is captured and the loop is `break`-ed, so the source's
+ *   `finally` kills the `tail` BEFORE the `rm` runs — the reader is stopped, then
+ *   its input is deleted, never the other way round.
+ * - `exitCode` stays `undefined` if the journal stream ends without a sentinel.
+ *   NOTHING is deleted on that path either way — the run may be mid-flight and a
+ *   successor host may still need every byte — but the two causes are then
+ *   separated by `options.signal.aborted`: an aborted consumer returns quietly,
+ *   while a stream that died on its own (killed `tail`, destroyed sandbox, torn
+ *   pipe) THROWS. Returning for both is how a truncated read used to reach the
+ *   client as a normally-completing run.
+ * - A non-zero sentinel deletes too. The run is terminal either way.
+ * - The stderr sidecar is read BEFORE the deletion that destroys it, so a
+ *   non-zero exit carries up to {@link STDERR_ERROR_CHARS} chars of the agent's
+ *   own diagnostics, exactly as the unjournaled path below does. That closes the
+ *   "Known regression" this function used to document; the read is bounded and
+ *   failure-swallowing (see {@link readStderrTail}), so it cannot turn a run
+ *   failure into a cleanup failure.
+ *
+ * On an ATTACH (`journal.attach === true`) the read is preceded by
+ * {@link awaitAttachableJournal}, which fails fast for a runId the store does not
+ * know or has already terminalized and otherwise waits a BOUNDED time for a live
+ * run's journal to appear. Without it, an attach to a runId with no journal
+ * created an empty one (`journalFollowCommand` does that deliberately) and tailed
+ * it forever — no sentinel, no error, no timeout.
+ *
+ * One case this does NOT bound: a run that reaches its sentinel while DETACHED
+ * has no host reading it, so nothing observes the sentinel and nothing here
+ * runs. Sweeping those is `pruneJournals`' job (`journal-sweep.ts`): it consults
+ * the run store's status for each journal it finds and deletes only the terminal
+ * ones, from a cron the application schedules rather than from a run.
+ */
+export async function* readJournalNdjson(
+  handle: SandboxHandle,
+  options: JournaledOptions,
+): AsyncIterable<unknown> {
+  const paths = resolvePaths(options)
+  // ATTACH ONLY, and before the first read. `journalFollowCommand` CREATES the
+  // journal it tails, so an attach for a runId that never had one would
+  // otherwise create an empty file and tail it forever with no sentinel ever
+  // arriving. A fresh run must not be gated: its journal is created by its own
+  // `journaledCommand` spawn, which `spawnNdjson` has just issued.
+  if (options.journal.attach === true) {
+    await awaitAttachableJournal(handle, {
+      paths,
+      runId: options.journal.runId,
+      ...(options.journal.runs === undefined
+        ? {}
+        : { runs: options.journal.runs }),
+      ...(options.journal.attachWaitMs === undefined
+        ? {}
+        : { waitMs: options.journal.attachWaitMs }),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    })
+  }
+  let exitCode: number | undefined
+  for await (const { line } of readJournal(handle, {
+    paths,
+    fromByte: 0,
+    runId: options.journal.runId,
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+    ...(options.journal.pollIntervalMs === undefined
+      ? {}
+      : { pollIntervalMs: options.journal.pollIntervalMs }),
+    ...(options.journal.attachWaitMs === undefined
+      ? {}
+      : { firstByteTimeoutMs: options.journal.attachWaitMs }),
+  })) {
+    const trimmed = line.trim()
+    if (trimmed === '') continue
+    // The sentinel test comes FIRST and is nonce-checked, so an agent line that
+    // merely looks like a sentinel is delivered as the event it is instead of
+    // truncating the run (see `parseExitSentinel`).
+    const sentinel = parseExitSentinel(trimmed, paths)
+    if (sentinel !== null) {
+      exitCode = sentinel
+      break
+    }
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(trimmed)
+    } catch {
+      options.onNonJsonLine?.(trimmed)
+      continue
+    }
+    yield parsed
+  }
+
+  // The stream ended with no sentinel. Two very different causes share this
+  // shape, and collapsing them is how a torn-down read used to be recorded as a
+  // short but SUCCESSFUL run:
+  //
+  // - The CONSUMER aborted (lease lost, client gone, host shutting down). Not a
+  //   failure and not terminal: return, having deleted nothing, because a
+  //   successor host may still need every byte. `pipeToRunLog`'s post-loop check
+  //   turns this into `'aborted'`.
+  // - The read DIED (the `tail` was killed, the sandbox was destroyed, the pipe
+  //   was torn down). The iterable ends without an error, so returning here made
+  //   the adapter emit a normally-completing but silently TRUNCATED run — in a
+  //   function whose documented job is to throw so the adapter converts it to a
+  //   `RUN_ERROR`. `signal.aborted` is what tells the two apart, and the throw
+  //   matches the shape the unjournaled path already uses for a bad exit.
+  if (exitCode === undefined) {
+    if (options.signal?.aborted === true) return
+    throw new Error(
+      `Agent journal stream for run ${options.journal.runId} ended without an exit sentinel ` +
+        `(${paths.journal}). The run was NOT observed to finish: the tail was torn down, ` +
+        `the sandbox went away, or the agent's shell died before writing its sentinel. ` +
+        `Both journal files are left in place for a successor host.`,
+    )
+  }
+
+  const stderr = exitCode === 0 ? '' : await readStderrTail(handle, paths)
+  await cleanupJournal(handle, paths)
+  if (exitCode !== 0) {
+    throw new Error(
+      `Agent process exited with code ${exitCode}` +
+        (stderr ? `: ${stderr.slice(0, STDERR_ERROR_CHARS)}` : ''),
+    )
+  }
+}
+
 /**
  * Spawn `command` in the sandbox and yield each stdout line parsed as JSON.
- * Resolves the spawn handle's exit via `wait()` after stdout closes; a non-zero
- * exit with no events surfaced is the adapter's concern to detect.
+ *
+ * Without `options.journal`, behavior is byte-identical to before: resolves
+ * the spawn handle's exit via `wait()` after stdout closes; a non-zero exit
+ * with no events surfaced is the adapter's concern to detect.
+ *
+ * With `options.journal`, the agent's stdout is redirected into an in-sandbox
+ * journal (unless `journal.attach` is set, meaning a run already in flight)
+ * and then read back from byte 0 — one code path for a fresh run and an
+ * attach, both going through {@link readJournalNdjson}.
  */
 export async function* spawnNdjson(
   handle: SandboxHandle,
   command: string,
   options: SpawnNdjsonOptions = {},
 ): AsyncIterable<unknown> {
+  if (isJournaled(options)) {
+    if (options.journal.attach !== true) {
+      await startJournaledAgent(handle, command, options)
+    }
+    yield* readJournalNdjson(handle, options)
+    return
+  }
+
   const { onNonJsonLine, input, ...processOptions } = options
   const proc = await handle.process.spawn(command, processOptions)
 
@@ -93,7 +437,7 @@ export async function* spawnNdjson(
     const stderr = stderrChunks.join('').trim()
     throw new Error(
       `Agent process exited with code ${exitCode}` +
-        (stderr ? `: ${stderr.slice(0, 1000)}` : ''),
+        (stderr ? `: ${stderr.slice(0, STDERR_ERROR_CHARS)}` : ''),
     )
   }
 }

package/src/sandbox.ts

@@ -9,11 +9,13 @@
 import { bootstrapWorkspace } from './bootstrap'
 import { resolveAllSecrets } from './secrets'
 import { computeSandboxKey } from './key'
-import { InMemoryLockStore, InMemorySandboxStore } from './store'
+import { InMemoryLockStore } from '@tanstack/ai/locks'
+import type { LockStore } from '@tanstack/ai/locks'
 import type { SandboxFileHookEvent } from '@tanstack/ai'
+import { InMemorySandboxInstanceStore } from './instance-store'
+import type { SandboxInstanceStore } from './instance-store'
 import type { SandboxHandle, SandboxProvider } from './contracts'
 import type { SandboxKeyInput } from './key'
-import type { LockStore, SandboxStore } from './store'
 import type { SandboxPolicy } from './policy'
 import type { WorkspaceDefinition } from './workspace'
 
@@ -69,7 +71,7 @@ export interface SandboxEnsureContext {
   threadId: string
   runId: string
   /** Persistence seam; falls back to an in-memory store when absent. */
-  store?: SandboxStore
+  store?: SandboxInstanceStore
   /** Lock seam; falls back to an in-memory lock when absent. */
   locks?: LockStore
   tenant?: { userId?: string; orgId?: string }
@@ -109,9 +111,16 @@ function parseMaxAgeMs(value: string | undefined): number | undefined {
   return undefined
 }
 
+/**
+ * Bound for the unfenced teardown `destroy` call (see `destroy` below). Long
+ * enough that a slow provider API still completes, short enough that a wedged
+ * one cannot pin the process forever.
+ */
+const DESTROY_TIMEOUT_MS = 60 * 1000
+
 // Process-lifetime fallbacks shared across all definitions so concurrent
 // ensures for the same key serialize even without an injected store/lock.
-const fallbackStore = new InMemorySandboxStore()
+const fallbackStore = new InMemorySandboxInstanceStore()
 const fallbackLocks = new InMemoryLockStore()
 
 export function defineSandbox(config: SandboxConfig): SandboxDefinition {
@@ -242,10 +251,31 @@ export function defineSandbox(config: SandboxConfig): SandboxDefinition {
     const key = computeSandboxKey(keyInputFor(ctx))
     const existing = await store.get(key)
     if (!existing) return
-    await config.provider.destroy({
-      id: existing.providerSandboxId,
-      signal: ctx.signal,
-    })
+    /*
+     * TEARDOWN IS DELIBERATELY NOT FENCED BY `ctx.signal`.
+     *
+     * `destroy` runs on every teardown path INCLUDING the one caused by that
+     * very signal aborting, so forwarding it hands the provider a signal that is
+     * already aborted: a provider that honors it does nothing and returns
+     * successfully, and `store.delete` below then removes the only pointer to a
+     * live, billed sandbox. `SandboxInstanceStore` has no `list` (see the note
+     * at the top of `reclaim.ts`), so that sandbox is unreachable from then on.
+     *
+     * Same reasoning as `close()` never being fenced by the run claim (see
+     * `fenceDurability` in `claim.ts`): cleanup must outlive whatever cancelled
+     * the work. A fresh controller with its own bounded timeout keeps the call
+     * from hanging forever without letting the caller's abort cancel it.
+     */
+    const teardown = new AbortController()
+    const timer = setTimeout(() => teardown.abort(), DESTROY_TIMEOUT_MS)
+    try {
+      await config.provider.destroy({
+        id: existing.providerSandboxId,
+        signal: teardown.signal,
+      })
+    } finally {
+      clearTimeout(timer)
+    }
     await store.delete(key)
   }
 

package/src/shell.ts

@@ -59,8 +59,23 @@ export interface BootstrapShell {
 export interface BootstrapShellOptions {
   /** Working directory to start the shell in (passed as ProcessOptions.cwd). */
   cwd?: string
+  /**
+   * Belt-and-braces deadline for a single `run()` to see its sentinel. The
+   * primary termination condition is the stdout stream ending (see
+   * {@link createBootstrapShell}); this only catches a shell that is alive,
+   * silent, and never going to answer. Generous by default because setup steps
+   * legitimately run for a long time (`npm install`, image pulls).
+   */
+  commandTimeoutMs?: number
 }
 
+/** Default {@link BootstrapShellOptions.commandTimeoutMs} — 30 minutes. */
+const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60 * 1000
+
+/** Race marker for the per-command deadline. A symbol cannot collide with a
+ *  literal stdout line (a line of text `'timeout'` would). */
+const TIMED_OUT = Symbol('bootstrap-shell-timeout')
+
 /**
  * Spawn one `sh` process and return a {@link BootstrapShell} that drives it
  * via the sentinel-echo protocol.
@@ -87,18 +102,35 @@ export async function createBootstrapShell(
    * the iterator open. Buffer chunks into lines manually.
    */
   const lineBuffer: Array<string> = []
-  let pending: Array<(line: string) => void> = []
+  // `null` means "the stdout stream ended" — distinct from an empty line, which
+  // `sh` emits constantly. Collapsing the two is what let a dead shell feed an
+  // infinite supply of `''` into a sentinel-hunting loop.
+  let pending: Array<(line: string | null) => void> = []
   let streamDone = false
+  let streamError: unknown
 
   /** Feed the stdout async-iterable into the shared line queue. */
   async function drainStdout(): Promise<void> {
     let partial = ''
-    for await (const chunk of proc.stdout) {
-      partial += chunk
-      const parts = partial.split('\n')
-      // All but the last element are complete lines.
-      for (let i = 0; i < parts.length - 1; i++) {
-        const line = parts[i] as string
+    try {
+      for await (const chunk of proc.stdout) {
+        partial += chunk
+        const parts = partial.split('\n')
+        // All but the last element are complete lines.
+        for (let i = 0; i < parts.length - 1; i++) {
+          const line = parts[i] as string
+          const resolver = pending.shift()
+          if (resolver !== undefined) {
+            resolver(line)
+          } else {
+            lineBuffer.push(line)
+          }
+        }
+        partial = parts[parts.length - 1] as string
+      }
+      // Flush any trailing partial line.
+      if (partial.length > 0) {
+        const line = partial
         const resolver = pending.shift()
         if (resolver !== undefined) {
           resolver(line)
@@ -106,39 +138,40 @@ export async function createBootstrapShell(
           lineBuffer.push(line)
         }
       }
-      partial = parts[parts.length - 1] as string
-    }
-    // Flush any trailing partial line.
-    if (partial.length > 0) {
-      const line = partial
-      const resolver = pending.shift()
-      if (resolver !== undefined) {
-        resolver(line)
-      } else {
-        lineBuffer.push(line)
+    } catch (error) {
+      // A throw while iterating stdout (transport reset, provider stream error)
+      // must NOT leave waiters parked on a promise nobody resolves. Record it so
+      // `run()` can name the cause, and fall through to the `finally` that
+      // unblocks everyone.
+      streamError = error
+    } finally {
+      streamDone = true
+      // Unblock any remaining waiters with the end-of-stream marker.
+      for (const resolver of pending) {
+        resolver(null)
       }
+      pending = []
     }
-    streamDone = true
-    // Resolve any remaining waiters with an empty sentinel so they unblock.
-    for (const resolver of pending) {
-      resolver('')
-    }
-    pending = []
   }
 
-  // Start draining immediately; do NOT await — runs concurrently.
+  /*
+   * Start draining immediately; do NOT await — runs concurrently. The `try/catch`
+   * inside `drainStdout` means this promise never rejects, so there is no
+   * unhandled rejection while nothing is awaiting it, and `dispose()` can await
+   * it unconditionally.
+   */
   const drainPromise = drainStdout()
 
-  /** Read the next line from the shared queue. */
-  function nextLine(): Promise<string> {
+  /** Read the next line from the shared queue, or `null` once stdout ended. */
+  function nextLine(): Promise<string | null> {
     const buffered = lineBuffer.shift()
     if (buffered !== undefined) {
       return Promise.resolve(buffered)
     }
     if (streamDone) {
-      return Promise.resolve('')
+      return Promise.resolve(null)
     }
-    return new Promise<string>((resolve) => {
+    return new Promise<string | null>((resolve) => {
       pending.push(resolve)
     })
   }
@@ -162,18 +195,53 @@ export async function createBootstrapShell(
 
     const outputLines: Array<string> = []
 
-    // Read lines until we find the sentinel.
-    for (;;) {
-      const line = await nextLine()
-      if (line.startsWith(`${sentinel} `)) {
-        const codeStr = line.slice(sentinel.length + 1).trim()
-        const exitCode = parseInt(codeStr, 10)
-        return {
-          exitCode: Number.isFinite(exitCode) ? exitCode : 1,
-          stdout: outputLines.join('\n'),
+    /*
+     * Read lines until we find the sentinel — but the wait MUST be able to end
+     * without one. `sh` can exit before it ever prints the sentinel (a missing
+     * binary, an OOM kill, the provider reaping the sandbox mid-bootstrap), and
+     * a loop whose only exit is the sentinel then spins on end-of-stream
+     * forever, pushing into `outputLines` until the host process dies of memory
+     * exhaustion. Two independent terminators:
+     *   1. `nextLine()` yields `null` the moment stdout is done — the real fix,
+     *      it fires as soon as the shell is gone.
+     *   2. A deadline, for a shell that stays alive and simply never answers.
+     */
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const deadline = new Promise<typeof TIMED_OUT>((resolve) => {
+      timer = setTimeout(
+        () => resolve(TIMED_OUT),
+        opts.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS,
+      )
+    })
+
+    try {
+      for (;;) {
+        const line = await Promise.race([nextLine(), deadline])
+        if (line === TIMED_OUT) {
+          throw new Error(
+            `bootstrap shell: timed out after ${
+              opts.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS
+            }ms waiting for the sentinel of command: ${command}`,
+          )
+        }
+        if (line === null) {
+          throw new Error(
+            `bootstrap shell: the shell exited before the sentinel was printed; command: ${command}`,
+            streamError === undefined ? undefined : { cause: streamError },
+          )
+        }
+        if (line.startsWith(`${sentinel} `)) {
+          const codeStr = line.slice(sentinel.length + 1).trim()
+          const exitCode = parseInt(codeStr, 10)
+          return {
+            exitCode: Number.isFinite(exitCode) ? exitCode : 1,
+            stdout: outputLines.join('\n'),
+          }
         }
+        outputLines.push(line)
       }
-      outputLines.push(line)
+    } finally {
+      clearTimeout(timer)
     }
   }