@tanstack/ai-sandbox 0.2.3 → 0.3.0

package/src/align.ts

@@ -0,0 +1,297 @@
+/**
+ * Replay-from-zero with log alignment: the mechanism that makes a resumed
+ * journal read idempotent.
+ *
+ * A host translates journal bytes 0..1000 and appends the resulting chunks, then
+ * dies. A successor re-reads the journal **from byte 0** and re-translates it,
+ * producing the same chunks again. This transform reads what is already in the
+ * event log, verifies that the replay reproduces it, suppresses that prefix, and
+ * passes only the remainder downstream to be appended.
+ *
+ * Why this shape rather than the offset-upsert the design sketched:
+ *
+ * - `StreamDurability.append` does not accept caller-supplied offsets, and
+ *   `UpsertableStreamDurability.upsert` is deliberately **not** used here:
+ *   `memoryStream.upsert` rejects any offset it did not mint itself, and
+ *   `durableStream` has no `upsert` at all (its offsets embed a
+ *   backend-assigned cursor). The journal path therefore only ever *appends*,
+ *   and this function's whole job is deciding where that append starts. Do not
+ *   "simplify" it into an `upsert` — the recommended production adapter cannot
+ *   accept one.
+ * - Even if it could, re-translation is only reproducible because
+ *   `createRunScopedIdGen` makes it so. The dedupe boundary therefore has to be
+ *   *derived from the log*, not tracked beside it — which also means there is no
+ *   window in which a checkpoint and the log can disagree, because the log is
+ *   the checkpoint.
+ * - The log stays append-only with strictly increasing offsets. That is what
+ *   `durableStream`'s backend enforces and what the client's offset de-dup
+ *   (`ai-client`'s `seen` set) relies on — the client is NOT tolerant of a
+ *   duplicated text or tool-argument delta.
+ *
+ * Divergence is a bug, not a condition to recover from, so it throws.
+ */
+import { EventType } from '@tanstack/ai'
+import {
+  chunkFingerprint,
+  chunkFingerprintIgnoringThreadId,
+  chunkThreadId,
+} from './chunk-identity'
+import type { InternalLogger } from '@tanstack/ai/adapter-internals'
+import type { StreamChunk, StreamDurability } from '@tanstack/ai'
+
+/**
+ * Default bound on consecutive stored chunks alignment will skip as out-of-band.
+ *
+ * A bound is what keeps this a tolerance rather than a search. Unbounded, a
+ * genuine determinism regression would make alignment scan forward through the
+ * whole log looking for a fingerprint that happens to match, suppress
+ * everything it passed, and deliver a stream whose prefix and suffix disagree —
+ * the exact failure {@link JournalReplayDivergedError} exists to prevent. 64 is
+ * well above any realistic burst of bridged console events between two
+ * translated chunks and well below a log length where a false match becomes
+ * plausible.
+ */
+export const DEFAULT_MAX_OUT_OF_BAND_SKIP = 64
+
+/**
+ * The out-of-band predicate for the harness adapters.
+ *
+ * `ai-codex` and `ai-claude-code` splice `createBridgeEventChannel`'s stream
+ * into their translated output with `mergeChunkStreams`. That channel is the
+ * only producer on the path and it emits exclusively `EventType.CUSTOM` chunks
+ * (`bridge-events.ts:53-63`), fired by LIVE bridged-tool execution. A replay
+ * runs no tools, so those chunks exist in the log and not in the replay.
+ *
+ * Structural rather than a list of event names on purpose: a new bridged tool
+ * inventing a new `name` must not silently reintroduce the divergence.
+ */
+export function isBridgeCustomChunk(chunk: StreamChunk): boolean {
+  return chunk.type === EventType.CUSTOM
+}
+
+/**
+ * The replay produced a different chunk than the log already holds at that
+ * index. Means translation stopped being deterministic — a `genId` that is not
+ * run-scoped, a translator that consults the clock, or a journal that was
+ * rewritten. Fail loud: suppressing the mismatch would deliver a stream whose
+ * prefix and suffix disagree about message identity.
+ */
+export class JournalReplayDivergedError extends Error {
+  constructor(
+    readonly index: number,
+    readonly stored: string,
+    readonly replayed: string,
+  ) {
+    super(
+      `journal replay diverged at index ${index}: stored ${stored} but replayed ${replayed}`,
+    )
+    this.name = 'JournalReplayDivergedError'
+  }
+}
+
+/**
+ * The replay reproduced the stored chunk EXACTLY except for its `threadId`.
+ *
+ * A distinct diagnosis because the cause and the fix are entirely different from
+ * a real divergence. The adapters resolve `threadId` as
+ * `options.threadId ?? this.generateId()`, and that id lands in every emitted
+ * chunk — so an attach route that drives a run without passing the run record's
+ * `threadId` mints a fresh one, and the very first chunk (`RUN_STARTED`) fails
+ * alignment. The agent behaved identically; only the id moved. Reported as a
+ * generic divergence, that sends the reader hunting for non-determinism in the
+ * translator, which is the wrong place entirely.
+ *
+ * A SUBCLASS of {@link JournalReplayDivergedError}, deliberately: this is still a
+ * divergence and still fatal, so a consumer already branching on the general
+ * class keeps working. The two are not collapsed — a genuine content divergence
+ * throws the base class, so `instanceof JournalReplayThreadIdMismatchError`
+ * separates a config mistake from a determinism bug in exactly one check.
+ */
+export class JournalReplayThreadIdMismatchError extends JournalReplayDivergedError {
+  constructor(
+    index: number,
+    stored: string,
+    replayed: string,
+    readonly storedThreadId: string | undefined,
+    readonly replayedThreadId: string | undefined,
+  ) {
+    super(index, stored, replayed)
+    this.name = 'JournalReplayThreadIdMismatchError'
+    this.message =
+      `journal replay diverged at index ${index} ONLY by threadId: stored ${JSON.stringify(storedThreadId)} but replayed ${JSON.stringify(replayedThreadId)}. ` +
+      `Every other field of the chunk is identical, so the agent did NOT behave differently — the attaching run generated a new threadId instead of reusing the run record's. ` +
+      `Pass the run record's threadId (RunRecord.threadId, which sandboxRunDriver hands to drive({ runId, threadId, signal })) into chat() on the attach route; ` +
+      `without it the adapter falls back to generateId() and every chunk carries an id the stored log cannot match.`
+  }
+}
+
+/**
+ * Classify a mismatch before throwing.
+ *
+ * The `threadId`-only case is recognized by comparing the two chunks a SECOND
+ * time with `threadId` excluded: equal there and unequal under the real
+ * fingerprint means `threadId` is the only field that moved. Cheap, because it
+ * runs only on the failure path, and precise, because it is derived from the same
+ * fingerprint function rather than a hand-written field diff.
+ */
+function divergenceError(
+  index: number,
+  storedChunk: StreamChunk,
+  replayedChunk: StreamChunk,
+  stored: string,
+  replayed: string,
+): JournalReplayDivergedError {
+  const storedThreadId = chunkThreadId(storedChunk)
+  const replayedThreadId = chunkThreadId(replayedChunk)
+  if (
+    storedThreadId !== replayedThreadId &&
+    chunkFingerprintIgnoringThreadId(storedChunk) ===
+      chunkFingerprintIgnoringThreadId(replayedChunk)
+  ) {
+    return new JournalReplayThreadIdMismatchError(
+      index,
+      stored,
+      replayed,
+      storedThreadId,
+      replayedThreadId,
+    )
+  }
+  return new JournalReplayDivergedError(index, stored, replayed)
+}
+
+export interface AlignToStoredLogOptions<TOffset extends string = string> {
+  /**
+   * The run's event log. Read from the beginning; never written here.
+   *
+   * Generic in the offset type, defaulted to `string`, for the same reason
+   * {@link RunDeps} is: a branded-cursor backend's `StreamDurability<TOffset>`
+   * is not assignable to `StreamDurability<string>`.
+   *
+   * Narrowed to `snapshot` — the only member this transform touches, as the
+   * function docs below spell out — so the capability-bus view of a log
+   * (`SandboxDurabilityLog`, which omits the offset-invariant `read`) can be
+   * passed straight through by `alignedIfAttaching`. A full `StreamDurability`
+   * still satisfies it, so no existing caller changes.
+   */
+  durability: Pick<StreamDurability<TOffset>, 'snapshot'>
+  /** Optional sink for the alignment summary. */
+  logger?: InternalLogger
+  /**
+   * Recognizes a stored chunk that the replay CANNOT reproduce, so alignment
+   * skips it instead of throwing.
+   *
+   * Absent by default, which keeps strict positional comparison: any stored
+   * chunk the replay does not produce is a determinism bug and fails loudly.
+   * Pass {@link isBridgeCustomChunk} on the harness attach path, where the
+   * previous host spliced live bridged-tool events into the log.
+   *
+   * The predicate is applied to the STORED chunk, never to the replayed one. A
+   * skipped entry is suppressed, not re-appended, so the client's view is
+   * unchanged: it already received that chunk under its own offset.
+   */
+  isOutOfBand?: (chunk: StreamChunk) => boolean
+  /**
+   * Maximum CONSECUTIVE stored chunks that may be skipped as out-of-band before
+   * alignment gives up. Reset by every match. Defaults to
+   * {@link DEFAULT_MAX_OUT_OF_BAND_SKIP}. Ignored when `isOutOfBand` is absent.
+   */
+  maxOutOfBandSkip?: number
+}
+
+/**
+ * Suppress the chunks already present in the event log and yield the rest.
+ *
+ * The stored prefix is read exactly once, eagerly, before the first replay
+ * chunk is pulled. Both halves of that matter:
+ *
+ * - **Exactly once**, because a second read mid-stream would race the appends
+ *   the caller is making downstream of this transform and could classify a
+ *   chunk this very run just appended as an already-stored one, dropping it.
+ * - **Via `snapshot()`, never `read()`**. `read` *tails*: it returns only when
+ *   the log is terminalized with `close()` or the caller aborts. A takeover's
+ *   log is open by definition — the host that would have closed it is the host
+ *   that died — so `for await (… of read('-1'))` would never finish, and on an
+ *   empty log `memoryStream` rejects a from-start join outright once its
+ *   first-chunk deadline elapses. `snapshot()` is the bounded read: it resolves
+ *   with what is stored right now, including while the log is still open, and
+ *   resolves to `[]` for a run with nothing stored.
+ */
+export async function* alignToStoredLog<TOffset extends string = string>(
+  chunks: AsyncIterable<StreamChunk>,
+  options: AlignToStoredLogOptions<TOffset>,
+): AsyncIterable<StreamChunk> {
+  const entries = await options.durability.snapshot()
+  const stored = entries.map((entry) => chunkFingerprint(entry.chunk))
+
+  const isOutOfBand = options.isOutOfBand
+  const maxSkip = options.maxOutOfBandSkip ?? DEFAULT_MAX_OUT_OF_BAND_SKIP
+
+  let cursor = 0
+  let suppressed = 0
+  let skipped = 0
+  let forwarded = 0
+
+  for await (const chunk of chunks) {
+    // Past the end of the stored log: everything from here is new.
+    if (cursor >= stored.length) {
+      forwarded += 1
+      yield chunk
+      continue
+    }
+
+    const actual = chunkFingerprint(chunk)
+    let consecutiveSkips = 0
+    for (;;) {
+      // `entries` and `stored` are the same length by construction; both are
+      // bound because the predicate needs the CHUNK while the comparison needs
+      // its fingerprint.
+      const entry = entries[cursor]
+      const expected = stored[cursor]
+      if (entry === undefined || expected === undefined) {
+        forwarded += 1
+        yield chunk
+        break
+      }
+      if (expected === actual) {
+        cursor += 1
+        suppressed += 1
+        break
+      }
+      // Mismatch. Only a stored chunk the replay provably cannot reproduce may
+      // be skipped, and only `maxSkip` of them in a row.
+      if (isOutOfBand === undefined || !isOutOfBand(entry.chunk)) {
+        throw divergenceError(cursor, entry.chunk, chunk, expected, actual)
+      }
+      if (consecutiveSkips >= maxSkip) {
+        throw divergenceError(cursor, entry.chunk, chunk, expected, actual)
+      }
+      cursor += 1
+      consecutiveSkips += 1
+      skipped += 1
+    }
+  }
+
+  // Trailing stored entries. Out-of-band ones are expected (a bridged tool's
+  // last event lands after the final translated chunk); anything else means the
+  // journal no longer accounts for chunks the log already delivered, which
+  // nothing downstream can repair.
+  while (cursor < stored.length) {
+    const entry = entries[cursor]
+    if (
+      entry === undefined ||
+      isOutOfBand === undefined ||
+      !isOutOfBand(entry.chunk)
+    ) {
+      throw new Error(
+        `journal replay is shorter than the stored log: ${stored.length - cursor} stored chunk(s) from index ${cursor} were not reproduced`,
+      )
+    }
+    cursor += 1
+    skipped += 1
+  }
+
+  options.logger?.provider(
+    `journal alignment: suppressed ${suppressed} stored chunk(s), skipped ${skipped} out-of-band, forwarded ${forwarded}`,
+    { suppressed, skipped, forwarded },
+  )
+}

package/src/attach-preflight.ts

@@ -0,0 +1,292 @@
+/**
+ * The gate that turns a HOPELESS attach into an error instead of an infinite
+ * wait.
+ *
+ * `journalFollowCommand` creates the journal before tailing it (`: >> file`),
+ * because `tail -f` on a missing path prints a diagnostic and EXITS rather than
+ * waiting — a defect that made a legitimate attach racing the driver's first
+ * write deliver zero lines. But creating the file has a cost: an attach for a
+ * `runId` that never had a journal creates an EMPTY one and tails it forever. No
+ * `{"__exit":N}` sentinel can ever arrive, so the caller waits indefinitely with
+ * no error, no timeout, and no log line — for what is the single most likely
+ * mistake on this path (a stale link, a typo, a run whose journal was cleaned up
+ * after completing).
+ *
+ * Absence of the journal alone cannot decide the question, which is exactly why
+ * `: >> file` exists: "not written YET" and "will never be written" look
+ * identical on the filesystem. The RUN RECORD is what distinguishes them, and it
+ * is authoritative — `runs.get(runId)` says whether the run exists at all,
+ * whether it is terminal, and (via `detachedSince`) whether anyone is expected
+ * to be driving it. So the policy is:
+ *
+ * | journal   | record                  | decision                              |
+ * | --------- | ----------------------- | ------------------------------------- |
+ * | exists    | (not consulted)         | attach, under the reader's own bound  |
+ * | absent    | unknown (`null`)        | fail fast, `'unknown-run'`            |
+ * | absent    | terminal                | fail fast, `'terminal-run'`           |
+ * | absent    | running / interrupted   | BOUNDED wait, then `'journal-timeout'`|
+ * | unusable  | running / interrupted   | BOUNDED wait, then `'journal-timeout'`|
+ *
+ * Four deliberate choices in that table:
+ *
+ * 1. **An existing journal short-circuits this gate**, before the store is read
+ *    at all — because gating it would make a perfectly readable journal
+ *    unreadable whenever a store lost its record. It does NOT mean the read is
+ *    unbounded: this module used to justify the short-circuit with "a journal
+ *    that exists either carries a sentinel or is still being appended to, neither
+ *    hangs", and that trichotomy was FALSE. `journalFollowCommand`'s first act is
+ *    `: >> file`, so the reader itself manufactures the third state — a file that
+ *    exists, receives nothing, and can never receive a sentinel — and the same
+ *    state is independently reachable by SIGKILL/OOM of the agent's shell before
+ *    its `printf`. The bound for it lives where it belongs, on the read:
+ *    `journal-reader.ts` fails a follow/poll that receives no bytes at all within
+ *    {@link DEFAULT_ATTACH_JOURNAL_WAIT_MS} with `'journal-stalled'`.
+ * 2. **A terminal record with no journal fails rather than waiting.** Nothing
+ *    will ever be appended: the run is over and `journalCleanupCommand` deletes a
+ *    terminal run's files by design. Its transcript lives in the event log, which
+ *    the resume response serves independently of this path.
+ * 3. **A live or detached record waits, but not forever.** A driver that has
+ *    claimed the run and not yet written its first line is the normal case, not
+ *    the unlucky one, so failing fast here would break the very race
+ *    `journalFollowCommand` was fixed to tolerate. `detachedSince` does NOT
+ *    change the decision — a detached run's journal is exactly what a successor
+ *    is supposed to read, and a driver that died before its first write leaves an
+ *    identical filesystem state — but it IS reported in the timeout message,
+ *    since "detached with no journal after N ms" and "attached with no journal
+ *    after N ms" point at different causes.
+ * 4. **An UNUSABLE probe falls through to the bounded wait; it does not skip the
+ *    gate.** This module used to fail open here — `if (existence === 'unknown')
+ *    return` — on the reasoning that a diagnostic gate must not break an attach
+ *    that would otherwise have worked. That reasoning inverted the actual risk.
+ *    Returning handed control to a reader whose very first act CREATES the
+ *    journal (`journalFollowCommand`'s `: >> file`) and then tails it forever, so
+ *    the fail-open path did not preserve a working attach — it manufactured the
+ *    exact infinite wait this module exists to prevent. Worse, it was
+ *    self-perpetuating: the file it created made `test -f` succeed from then on,
+ *    so every LATER attach short-circuited at choice 1 and hung too, permanently,
+ *    long after the transient probe failure had cleared. An unanswerable probe is
+ *    precisely when a deadline matters most, so an unusable probe is re-polled
+ *    (it may recover) and, failing that, times out. The store checks still run
+ *    first and need no probe, so an unknown or terminal `runId` still fails fast.
+ */
+import { isTerminalRunStatus } from '@tanstack/ai'
+import { journalExistsCommand } from './journal'
+import type { JournalPaths } from './journal'
+import type { SandboxHandle } from './contracts'
+import type { InternalLogger } from '@tanstack/ai/adapter-internals'
+import type { RunRecord, RunStore } from '@tanstack/ai'
+
+/**
+ * How long an attach waits for a live run's journal to appear before failing.
+ *
+ * User-relevant, hence exported: this bounds how long an attach REQUEST can sit
+ * before it answers, so an application that fronts the attach route with its own
+ * timeout needs to know the number. Generous relative to the gap between a
+ * driver claiming a run and its first journal write (a `spawn` plus one line),
+ * and short relative to any sane HTTP timeout. Override per run with
+ * `SandboxDurabilityOptions.attachWaitMs`.
+ */
+export const DEFAULT_ATTACH_JOURNAL_WAIT_MS = 10_000
+
+/**
+ * How often the bounded wait re-probes for the journal. Not user-facing: it
+ * trades a `test -f` per interval for attach latency, and neither number is
+ * something an application tunes.
+ */
+export const DEFAULT_ATTACH_PROBE_INTERVAL_MS = 100
+
+/**
+ * Which of the three hopeless-attach cases was hit. Exported so a consumer can
+ * branch (a 404 for `'unknown-run'`, a 410 for `'terminal-run'`, a 504 for
+ * `'journal-timeout'`) instead of matching on message text.
+ */
+export type AttachUnavailableReason =
+  | 'unknown-run'
+  | 'terminal-run'
+  | 'journal-timeout'
+  /**
+   * The journal EXISTS but produced no bytes at all within the deadline, so no
+   * sentinel can be coming and the follow would tail an empty (or abandoned)
+   * file forever. Raised by `journal-reader.ts`, not by the preflight: the
+   * preflight cannot see this state, because `test -f` succeeds for it.
+   *
+   * A 504 at an attach route, exactly like `'journal-timeout'`, which is why it
+   * shares {@link JournalAttachUnavailableError} — but a distinct value, because
+   * the cause is different: `'journal-timeout'` means nobody created the
+   * journal, `'journal-stalled'` means somebody did and then stopped (a
+   * SIGKILLed agent shell, a destroyed sandbox, a reader that created the file
+   * itself on a fail-open path).
+   */
+  | 'journal-stalled'
+
+/**
+ * An attach cannot succeed, and waiting longer would not change that.
+ *
+ * One class with a {@link AttachUnavailableReason} discriminant rather than three
+ * classes: every consumer of this path handles all three cases at the same seam
+ * (the attach route), so one `instanceof` plus a `switch (error.reason)` is the
+ * shape that is actually written, while the message names the specific case for a
+ * human reading a log.
+ */
+export class JournalAttachUnavailableError extends Error {
+  constructor(
+    readonly runId: string,
+    readonly reason: AttachUnavailableReason,
+    detail: string,
+  ) {
+    super(`cannot attach to run ${runId}: ${detail}`)
+    this.name = 'JournalAttachUnavailableError'
+  }
+}
+
+/** Existence of the journal, or `'unknown'` when the probe itself failed. */
+type JournalExistence = 'yes' | 'no' | 'unknown'
+
+export interface AwaitAttachableJournalOptions {
+  /** The run's journal paths, as {@link journalPaths} derived them. */
+  paths: JournalPaths
+  /** Run id, for the store lookup and the error messages. */
+  runId: string
+  /**
+   * The authoritative run record store. Omitted only by a caller with no store
+   * wired, which loses the unknown/terminal classification but keeps the bound.
+   */
+  runs?: RunStore
+  /** Bounded wait. Defaults to {@link DEFAULT_ATTACH_JOURNAL_WAIT_MS}. */
+  waitMs?: number
+  /** Re-probe interval. Defaults to {@link DEFAULT_ATTACH_PROBE_INTERVAL_MS}. */
+  probeIntervalMs?: number
+  /**
+   * The consumer's abort. An aborted wait returns rather than throwing: the
+   * caller stopped caring, which is not a diagnosis about the run.
+   */
+  signal?: AbortSignal
+  logger?: InternalLogger
+}
+
+/**
+ * Shell `test -f`, never `handle.fs.exists` — `journal.ts` rule 3: on
+ * local-process the two resolve `/tmp` differently, so `fs.exists` would probe a
+ * path the journal was never written to and report `false` for every run.
+ */
+async function probeJournal(
+  handle: SandboxHandle,
+  options: AwaitAttachableJournalOptions,
+): Promise<JournalExistence> {
+  try {
+    const result = await handle.process.exec(
+      journalExistsCommand(options.paths),
+    )
+    return result.exitCode === 0 ? 'yes' : 'no'
+  } catch (error) {
+    options.logger?.provider(
+      `attach preflight: journal existence probe failed for run ${options.runId}; re-probing under the bounded wait rather than attaching blind`,
+      { runId: options.runId, error },
+    )
+    return 'unknown'
+  }
+}
+
+/**
+ * `null` means the store answered "no such run" — a real, actionable fact.
+ * `undefined` means there is no answer to be had (no store, or `get` threw), and
+ * the caller must not treat that as "unknown run".
+ */
+async function readRecord(
+  options: AwaitAttachableJournalOptions,
+): Promise<RunRecord | null | undefined> {
+  if (options.runs === undefined) return undefined
+  try {
+    return await options.runs.get(options.runId)
+  } catch (error) {
+    options.logger?.errors(
+      `attach preflight: reading the run record failed for run ${options.runId}`,
+      { runId: options.runId, error },
+    )
+    return undefined
+  }
+}
+
+function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  if (ms <= 0) return Promise.resolve()
+  return new Promise<void>((resolve) => {
+    const timer = setTimeout(finish, ms)
+    function finish(): void {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', finish)
+      resolve()
+    }
+    signal?.addEventListener('abort', finish, { once: true })
+  })
+}
+
+function describeRecord(record: RunRecord): string {
+  return record.detachedSince === undefined
+    ? `status '${record.status}' with a viewer attached`
+    : `status '${record.status}', detached since ${new Date(record.detachedSince).toISOString()}`
+}
+
+/**
+ * Resolve once the run's journal can be tailed, or reject with a
+ * {@link JournalAttachUnavailableError} explaining why it never will be.
+ *
+ * Call this BEFORE the first follow/poll read of an attach, never on a fresh
+ * run: a fresh run's journal is created by its own `journaledCommand` spawn,
+ * which has not happened yet, so gating it would fail every new run.
+ */
+export async function awaitAttachableJournal(
+  handle: SandboxHandle,
+  options: AwaitAttachableJournalOptions,
+): Promise<void> {
+  const existence = await probeJournal(handle, options)
+  if (existence === 'yes') return
+
+  const record = await readRecord(options)
+  if (record === null) {
+    throw new JournalAttachUnavailableError(
+      options.runId,
+      'unknown-run',
+      `no run record exists and the journal (${options.paths.journal}) has never been written, so nothing will ever be appended to it. ` +
+        `The runId is unknown to the RunStore — it is mistyped, from another deployment, or its record has been evicted.`,
+    )
+  }
+  if (record !== undefined && isTerminalRunStatus(record.status)) {
+    throw new JournalAttachUnavailableError(
+      options.runId,
+      'terminal-run',
+      `the run is already '${record.status}' and its journal (${options.paths.journal}) does not exist, so nothing will ever be appended to it. ` +
+        `A terminal run's transcript lives in its event log, not in a journal — serve the log instead of attaching.`,
+    )
+  }
+
+  // NOTE: no fail-open branch here. An `existence === 'unknown'` probe falls
+  // through into the bounded wait below — see choice 4 in the module doc for why
+  // returning was worse than timing out, not safer.
+  const waitMs = options.waitMs ?? DEFAULT_ATTACH_JOURNAL_WAIT_MS
+  const probeIntervalMs =
+    options.probeIntervalMs ?? DEFAULT_ATTACH_PROBE_INTERVAL_MS
+  const deadline = Date.now() + waitMs
+  let lastExistence: JournalExistence = existence
+  for (;;) {
+    const remaining = deadline - Date.now()
+    if (remaining <= 0) {
+      throw new JournalAttachUnavailableError(
+        options.runId,
+        'journal-timeout',
+        `the run record says ${record === undefined ? 'nothing (no run store is wired)' : describeRecord(record)}, ` +
+          (lastExistence === 'unknown'
+            ? `and its journal (${options.paths.journal}) could not be probed at all within ${waitMs}ms — every '${journalExistsCommand(options.paths)}' failed. ` +
+              `Attaching anyway would create that journal and tail it forever, so this fails instead. Check that the sandbox is still alive and that its exec transport works.`
+            : `but its journal (${options.paths.journal}) did not appear within ${waitMs}ms. ` +
+              `Either the driver died before writing its first line, or the journal directory does not match the one the agent was started with.`),
+      )
+    }
+    // The consumer gave up (client gone, lease lost). Returning hands control
+    // back to the reader, whose own AbortSignal handling ends the read — a
+    // caller's abort is not a diagnosis about the run.
+    if (options.signal?.aborted) return
+    await sleep(Math.min(probeIntervalMs, remaining), options.signal)
+    lastExistence = await probeJournal(handle, options)
+    if (lastExistence === 'yes') return
+  }
+}

package/src/capabilities.ts

@@ -1,26 +1,19 @@
 /**
- * Capability tokens the sandbox layer provides/consumes through the
- * `@tanstack/ai` middleware capability system.
+ * Capability tokens the sandbox layer owns and provides.
  *
  * - `SandboxCapability` is PROVIDED by `withSandbox` and REQUIRED by harness
  *   adapters (`requires: [SandboxCapability]`).
- * - `SandboxStoreCapability` / `LocksCapability` are OPTIONALLY required by
- *   `withSandbox`. v1 falls back to in-memory defaults; the future persistence
- *   package PROVIDES durable implementations.
+ * - `SandboxInstanceStoreCapability` lives in
+ *   `./instance-store` (same package). `LocksCapability` / `withLocks` live in
+ *   `@tanstack/ai/locks` and are not re-exported here.
  */
 import { createCapability } from '@tanstack/ai'
 import type { SandboxHandle } from './contracts'
-import type { LockStore, SandboxStore } from './store'
 import type { SandboxPolicy } from './policy'
 import type { ToolBridgeProvisioner } from './tool-bridge'
 
 export const SandboxCapability = createCapability<SandboxHandle>()('sandbox')
 
-export const SandboxStoreCapability =
-  createCapability<SandboxStore>()('sandbox-store')
-
-export const LocksCapability = createCapability<LockStore>()('locks')
-
 /**
  * The active sandbox policy, provided by `withSandbox` from the definition.
  * Harness adapters read it to map allow/ask/deny rules onto their native
@@ -40,8 +33,6 @@ export const ToolBridgeProvisionerCapability =
 
 /** Destructured accessors for adapters: `getSandbox(ctx)` reads the handle. */
 export const [getSandbox, provideSandbox] = SandboxCapability
-export const [getSandboxStore, provideSandboxStore] = SandboxStoreCapability
-export const [getLocks, provideLocks] = LocksCapability
 export const [getSandboxPolicy, provideSandboxPolicy] = SandboxPolicyCapability
 export const [getToolBridgeProvisioner, provideToolBridgeProvisioner] =
   ToolBridgeProvisionerCapability