@tanstack/ai-sandbox 0.2.4 → 0.3.0

package/dist/esm/journal.d.ts

@@ -0,0 +1,542 @@
+/**
+ * The agent output journal: an append-only NDJSON file INSIDE the sandbox that
+ * the agent's stdout is redirected to, and that the host tails.
+ *
+ * This module is pure string composition — no I/O — so every shell fragment the
+ * feature depends on is unit-testable without a sandbox, and a successor host
+ * derives byte-identical commands from the `runId` alone.
+ *
+ * Three rules are encoded here and must not be relaxed:
+ *
+ * 1. **No pipe from the agent.** The agent's stdout is *redirected*, never
+ *    piped. `agent | tee file` gives the agent a reader whose disappearance
+ *    SIGPIPEs it — precisely the host-death failure this feature exists to
+ *    prevent. Redirection leaves nothing to break.
+ * 2. **Every read silences stderr; only the BOUNDED read base64-frames its
+ *    output.** `2>/dev/null` is on both: Daytona's `exec` folds stderr into
+ *    stdout (`stderr: ''`, by contract) and Sprites' fast path does too, so a
+ *    `tail` diagnostic would otherwise splice itself into the event bytes.
+ *    Silencing it inside the sandbox means there is nothing left to fold.
+ *
+ *    base64, however, is only on {@link journalReadCommand}. It cannot be on
+ *    {@link journalFollowCommand}: `base64` fully buffers its stdout when that
+ *    is a pipe rather than a tty, so `tail -f file | base64` emits NOTHING
+ *    until the ~4KB libc stdio buffer fills or `base64`'s stdin closes — and
+ *    `tail -f`'s stdin never closes until the reader kills it, by which point
+ *    the consumer has stopped reading. Measured on GNU coreutils 8.32 `base64`
+ *    (0 bytes delivered over 12s) and on busybox 1.36.1 `base64` in Alpine
+ *    (identical), so it is a property of stdio, not of a provider or an OS.
+ *    `stdbuf -o0` does not fix it portably (absent from busybox entirely) and
+ *    re-`exec`ing `base64` per line costs a fork per journal event.
+ *
+ *    Dropping it from the follow path is safe because the bounded read keeps
+ *    every property base64 was chosen for where that path needs them, and the
+ *    follow path needs none of them: `2>/dev/null` already prevents the
+ *    stderr splice, the journal is line-delimited JSON (a raw newline can only
+ *    ever be a record separator — inside a JSON string it is `\n`), and
+ *    `journal-bytes.ts` reassembles bytes across chunk boundaries and yields
+ *    only newline-terminated lines. The follow path therefore consumes
+ *    `SpawnHandle.stdout` exactly as `runner.ts` already consumes the agent's
+ *    own stdout, i.e. it relies on the same provider decoding contract the
+ *    package already depends on rather than a stricter one.
+ * 3. **The journal is touched ONLY through the shell.** On local-process,
+ *    `fs.write` resolves `/tmp` under the sandbox root while a shell redirect
+ *    hits the real host `/tmp`. Both halves agree with each other only as long
+ *    as nothing uses `fs.*` here — hence {@link journalExistsCommand} rather
+ *    than `handle.fs.exists`.
+ *
+ * The composed commands below are handed to two different execution
+ * mechanisms depending on provider, not always `sh -c`: daytona hands the raw
+ * string to `executeCommand` with an `export`-prefixed env, and cloudflare
+ * hands it to a Durable Object RPC. Redirection, `mkdir -p`, `tail`, and
+ * `base64` all still work because both paths are shell-interpreted
+ * downstream — the doc comment intentionally does not claim every provider
+ * wraps the command in `sh -c` itself.
+ */
+/** Default journal directory. `/tmp` is the convention the harness adapters already use. */
+export declare const DEFAULT_JOURNAL_DIR = "/tmp/tanstack-runs";
+/**
+ * Key of the sentinel object the journaled command appends after the agent
+ * exits. It tells a *new* host the agent finished, with no pid probe and no
+ * provider-specific liveness API — which matters because `pid` is `-1` on five
+ * of six providers.
+ */
+export declare const EXIT_SENTINEL_KEY = "__exit";
+/**
+ * Key carrying the per-run sentinel nonce that makes the sentinel
+ * DISTINGUISHABLE from agent output.
+ *
+ * **Why the nonce exists.** `journaledCommand` redirects the agent's stdout and
+ * the sentinel `printf` into the SAME file with no framing, so on the wire an
+ * agent's own line is indistinguishable from the shell's. Without a nonce, any
+ * agent that ever prints a JSON object carrying `__exit` — echoing a fixture,
+ * `cat`-ing a file, dumping diagnostics — makes {@link parseJournalExit} report a
+ * MID-FLIGHT run as finished, and `reapOne` then drives that run to terminal and
+ * reclaims its sandbox out from under a live agent. A confident wrong answer is
+ * strictly worse than the `'unknown'` every other failure on that path returns.
+ *
+ * **What the nonce is.** A domain-separated SHA-256 of the runId (see
+ * {@link journalPaths}), NOT process-random. It has to be recomputable by a
+ * SUCCESSOR host from the run record alone — that is this module's stated
+ * contract ("a successor host derives byte-identical commands from the `runId`
+ * alone"), and the reaper's probe runs in a different process from the one that
+ * composed the command, with nothing but the runId to go on. A process-random
+ * nonce would make every journal written by a dead host unreadable.
+ *
+ * **The residual, stated honestly.** Because it is derived rather than secret,
+ * an agent that knows its own runId AND reimplements this derivation could still
+ * emit a matching line. What the nonce removes is the entire accidental class —
+ * which is the class that actually occurs — and it removes it completely. Closing
+ * the deliberate case needs a secret the successor host can also read, i.e. a
+ * nonce persisted on the run record; that is a `RunStore` schema change, not a
+ * change to this pure-composition module. Two further mitigations narrow the
+ * deliberate case: {@link parseJournalExit} takes the LAST matching sentinel in
+ * the window rather than the first (the shell always writes the real one after
+ * the agent's own output), and a matching sentinel whose code is not an integer
+ * is refused rather than coerced to 0.
+ */
+export declare const EXIT_SENTINEL_NONCE_KEY = "__nonce";
+/** Absolute in-sandbox paths for one run's journal. */
+export interface JournalPaths {
+    /** Directory both files live in; created by {@link journaledCommand}. */
+    dir: string;
+    /** Append-only NDJSON file the agent's stdout is redirected to. */
+    journal: string;
+    /** Separate file the agent's stderr goes to; NEVER mixed into the journal. */
+    stderr: string;
+    /**
+     * Per-run nonce the exit sentinel carries, so agent stdout cannot forge it.
+     * See {@link EXIT_SENTINEL_NONCE_KEY}. Carried alongside the paths because
+     * every producer and every reader of the sentinel already threads a
+     * `JournalPaths` through, and the two must agree or the run reads as
+     * unterminated.
+     */
+    nonce: string;
+}
+/**
+ * The exact sentinel LINE (no trailing newline) `journaledCommand` appends for
+ * `exitCode`.
+ *
+ * Exported because a test or a fake host that seeds a journal by hand has to
+ * write the same bytes the shell would; hand-writing `{"__exit":0}` produces a
+ * line the reader now correctly refuses. Key order matches the `printf` format
+ * below, and both are asserted against each other in `journal.test.ts`.
+ */
+export declare function exitSentinelLine(paths: JournalPaths, exitCode: number): string;
+/**
+ * Map a runId to a filename-safe token that is INJECTIVE: distinct runIds
+ * must never produce the same token, because the journal is looked up by
+ * this token alone and a collision means two runs would share one journal —
+ * one run's takeover replaying another run's transcript.
+ *
+ * Encoding rather than rejecting keeps the mapping total: a client may choose
+ * any `runId`, and a run that cannot be journaled would be a run that cannot be
+ * made durable. The encoding is a pure function of the input, which is what lets
+ * a successor host recompute the same path from the run record alone.
+ *
+ * The scheme is a straightforward escaping over `_`: any character matching
+ * `[A-Za-z0-9.-]` passes through literally; everything else — INCLUDING a
+ * literal `_` — is replaced by `_` followed by two lowercase hex digits per
+ * UTF-8 byte. Because `_` itself is never a safe (pass-through) character,
+ * every `_` in the output unambiguously starts a two-hex-digit escape; a
+ * left-to-right scan can always tell literal from escape. That is what makes
+ * the mapping injective: two different inputs can never parse to the same
+ * output, because the (unimplemented, but well-defined) decoder is
+ * deterministic — if it were not injective, running that decoder on a shared
+ * output would have to yield both original strings, which is impossible for a
+ * deterministic function.
+ *
+ * This is a DELIBERATE change from a prior scheme that also treated `_` as
+ * safe. That made the encoding non-injective: `_` doubled as both a literal
+ * and the escape prefix, so an escaped byte could read back as a literal
+ * escape sequence typed by someone else. Concretely, under the old scheme
+ * `encodeRunId('@')` and `encodeRunId('_40')` both produced `'_40'` — `@` is
+ * `0x40` and gets escaped to `_40`, while the literal characters `_`, `4`, `0`
+ * were all "safe" and passed through unchanged. This change breaks that
+ * collision by escaping `_` like any other unsafe character.
+ *
+ * BREAKING CHANGE for existing journals: a journal file written under the
+ * old scheme (where a literal `_` in the runId was left unescaped) will not
+ * be found by this scheme, because a runId containing `_` now encodes
+ * differently. Durability has not shipped publicly yet (this repo has no
+ * released version with `encodeRunId` in it), so there is no compatibility
+ * obligation and no changeset is warranted — there is nothing in the wild to
+ * migrate.
+ *
+ * EXPORTED for adapters that derive their OWN in-sandbox paths from a `runId`
+ * (`ai-codex`'s prompt file and MCP bridge config, `ai-claude-code`'s prompt
+ * file). Durability makes `runId` caller-chosen, so an unencoded interpolation
+ * lets a `/` produce a directory-bearing path, `..` escape the workdir, and an
+ * over-long id fail the spawn with `ENAMETOOLONG` — the same hazards
+ * {@link journalPaths} already routes through here. Reuse this rather than
+ * writing a second encoder: a divergent copy would reintroduce the
+ * non-injectivity documented above.
+ */
+export declare function encodeRunId(runId: string): string;
+/**
+ * Reverse of {@link encodeRunId}, for a filename as `ls -1` reports it.
+ *
+ * `runId` on the success arm is a STORE KEY, never a path component. The
+ * encoding is total over client-chosen strings, so a perfectly valid decode can
+ * be `'..'`, `'.hidden'`, or `'a/b'` — a caller that interpolates it into a
+ * path would escape the journal directory. Look it up in the run store; do not
+ * join it onto anything.
+ */
+export type DecodedJournalRunId = 
+/** The name decoded to exactly one runId. */
+{
+    kind: 'runId';
+    runId: string;
+}
+/**
+ * The name is length-capped output of {@link encodeRunId}, whose truncating
+ * branch is LOSSY. The original runId is unrecoverable — KEEP the file.
+ */
+ | {
+    kind: 'truncated';
+}
+/** Not output this module could have produced. KEEP the file. */
+ | {
+    kind: 'malformed';
+};
+/**
+ * Recover the `runId` behind a journal filename — FAIL CLOSED.
+ *
+ * The consumer of this function DELETES files, so every arm that is not a
+ * proven-correct decode must be one the caller keeps. There is no "probably
+ * fine" arm.
+ *
+ * `name` is the filename as {@link journalListCommand} reports it, extension
+ * included. The extension is required, not optional: `.` is a pass-through-safe
+ * character, so a runId of `'x.ndjson'` encodes to the token `x.ndjson` and the
+ * file `x.ndjson.ndjson`. A function that stripped an extension only "if
+ * present" could not tell those two strings apart. Requiring it keeps that
+ * sharp edge here instead of in every caller that would otherwise reach for
+ * `name.split('.')[0]`.
+ *
+ * **Why `truncated` is a distinct refusal and not a decode.** `encodeRunId`
+ * caps its output at {@link MAX_ENCODED_NAME_LENGTH} by replacing the tail with
+ * `-` plus a SHA-256 prefix. That branch discards bytes, so the encoding is not
+ * invertible there — and because `-` is itself a pass-through-safe character,
+ * the truncated form is syntactically indistinguishable from a legitimately
+ * encoded id. Decoding it anyway would yield a plausible but WRONG runId; the
+ * store would not recognise it, a sweep would read that as "no such run", and
+ * it would delete the journal of a run that may still be mid-flight. So any
+ * name that *could* be the truncated form is refused, at the cost of never
+ * sweeping journals of runIds long enough to hash — a bounded leak, versus
+ * data loss on a live run.
+ *
+ * The truncation check runs BEFORE the character scan on purpose: truncating at
+ * a fixed byte offset can cut an `_hh` escape in half, so a truncated name may
+ * also be malformed, and the more specific diagnosis is the useful one.
+ *
+ * The rest is the inverse of the escaping scheme: `[A-Za-z0-9.-]` is a literal
+ * ASCII byte, `_` must be followed by EXACTLY two hex digits (either case),
+ * and anything else — a bare `_`, a one-digit escape, `/`, `\`, a space — is
+ * malformed. The resulting bytes go through a `fatal: true` `TextDecoder`, so
+ * an escape sequence that is not valid UTF-8 is a refusal rather than a string
+ * silently peppered with U+FFFD (which would be a *different* runId than any
+ * encoder input, i.e. exactly the wrong-runId deletion this guards against).
+ */
+export declare function decodeJournalRunId(name: string): DecodedJournalRunId;
+/**
+ * Derive both journal paths for a run. Pure; no I/O.
+ *
+ * **`runId` MUST be unique per run.** The journal is append-only by design (a
+ * takeover depends on a prefix a previous host delivered still being there), and
+ * {@link DEFAULT_JOURNAL_DIR} is a fixed absolute path that outlives any single
+ * sandbox, test, or process. So a reused `runId` does not start a fresh journal
+ * — it appends to the old one, behind the old run's `{"__exit":N}` sentinel. A
+ * streaming reader stops at the first sentinel it reaches — and a reused runId
+ * derives the SAME nonce, so the old run's sentinel matches — meaning the new run
+ * appears to emit nothing at all, or to fail with the previous run's exit code.
+ * (The nonce is per-run, not per-attempt: it defends against the AGENT forging a
+ * sentinel, not against a caller reusing an id.) This is not
+ * enforced here on purpose: refusing to append would break the takeover the
+ * append-only rule exists for. Callers derive `runId` from something unique
+ * (the adapters use a timestamp plus a random suffix); a test that hardcodes a
+ * literal `runId` will observe a stale run's journal on its second execution.
+ */
+export declare function journalPaths(runId: string, dir?: string): JournalPaths;
+/**
+ * Wrap an agent command so its stdout lands in the journal, its stderr lands in
+ * the sidecar file, and an `{"__exit":N,"__nonce":"…"}` sentinel is appended once
+ * it exits.
+ *
+ * The nonce is what keeps the sentinel apart from the agent's own stdout, which
+ * lands in the very same file with no framing — see
+ * {@link EXIT_SENTINEL_NONCE_KEY}. It is interpolated as a bare hex token inside
+ * a single-quoted `printf` FORMAT string, which is safe by construction:
+ * {@link deriveExitSentinelNonce} emits `[0-9a-f]` only, so there is no quote to
+ * escape and no `%` for `printf` to interpret.
+ *
+ * `command` is interpolated raw: callers build real shell text (the Claude Code
+ * and Codex adapters append `< promptFile`, for instance), so quoting it would
+ * break them. Every path this module contributes IS quoted.
+ *
+ * `>>` rather than `>` on purpose: truncating would let a stray re-spawn destroy
+ * a prefix a previous host already translated and delivered.
+ */
+export declare function journaledCommand(command: string, paths: JournalPaths): string;
+/**
+ * Following read, for `process.spawn` only. Never pass this to `exec`:
+ * `ProcessOptions` has no timeout, so a following `exec` blocks until the
+ * sandbox or the RPC times out.
+ *
+ * Deliberately pipes into NOTHING. `tail -f` flushes each append as it sees it,
+ * so it is the one stage in this pipeline that streams; adding any filter puts
+ * that filter's stdio buffer between the agent and the host and the follow
+ * strategy stops following (see rule 2 in the module doc for the measurements).
+ * The host turns these raw bytes into positioned lines with
+ * `journal-bytes.ts`.
+ *
+ * It also creates the journal before tailing it, because `tail -f` on a path
+ * that does not exist yet prints a diagnostic and EXITS rather than waiting —
+ * so the reader would deliver zero lines for a run whose journal simply had not
+ * been created yet. The reader and the agent are two independent spawns and
+ * nothing orders them, so that race is the normal case, not the unlucky one.
+ * `: >> file` is a builtin no-op plus an O_CREAT|O_APPEND open: it creates the
+ * file when absent and, critically, does NOT truncate one that already has a
+ * prefix a previous host already delivered. `;` rather than `&&` throughout, so
+ * a prep step that fails still lets the `tail` run and fail the way it used to
+ * rather than turning a read into a silent no-op. (`tail -F` would also retry,
+ * but `-F` is a GNU/busybox extension, not POSIX, and this file only emits
+ * POSIX shell.)
+ */
+export declare function journalFollowCommand(paths: JournalPaths, fromByte: number): string;
+/**
+ * Bounded read: `-f` dropped so it always terminates, and base64-framed because
+ * it can be — `exec` closes `base64`'s stdin, which flushes it, and the whole
+ * result arrives as one already-complete `ExecResult.stdout` string. This is the
+ * Cloudflare path, whose `spawn` cannot be killed and whose `exec` drops the
+ * AbortSignal, making a following read unstoppable there.
+ */
+export declare function journalReadCommand(paths: JournalPaths, fromByte: number): string;
+/**
+ * Existence probe. A shell `test -f`, not `handle.fs.exists`: see rule 3 in the
+ * module doc — on local-process the two resolve `/tmp` differently.
+ */
+export declare function journalExistsCommand(paths: Pick<JournalPaths, 'journal'>): string;
+/**
+ * Bounded read of the stderr SIDECAR (not the journal), so a non-zero exit can
+ * carry the agent's own diagnostics instead of a bare exit code.
+ *
+ * `exec`-only, like {@link journalReadCommand}, and base64-framed for the same
+ * reason: `exec` closes the encoder's stdin so it flushes, and the frame keeps a
+ * provider that folds stderr into stdout from splicing its own text into the
+ * bytes. Unlike the journal, the sidecar is NOT line-delimited JSON — an agent
+ * writes whatever it likes there, including partial lines and raw control bytes
+ * — so framing is what makes it safe to hand to a single `ExecResult.stdout`.
+ *
+ * `tail -c -N` (the LAST N bytes) rather than the first: the read has to be
+ * bounded, because a runaway agent's sidecar can be arbitrarily large and this
+ * runs on the host, and a crash's cause is at the end of stderr, not the start.
+ * The cost is that the first character can be a truncated UTF-8 sequence; the
+ * caller decodes lossily rather than failing, since this text is diagnostic.
+ */
+export declare function journalStderrReadCommand(paths: JournalPaths, maxBytes?: number): string;
+/**
+ * Delete both of a run's journal files.
+ *
+ * **Ordering is the whole contract here, not the `rm`.** This may only run once
+ * the run is TERMINAL — i.e. after the `{"__exit":N}` sentinel has been observed
+ * — and must never run on an abort. The three claims that make the deletion safe:
+ *
+ * 1. **Terminal means the event log holds the whole run.** The journal exists so
+ *    a successor host can replay a run from byte 0 and re-derive the chunks a
+ *    dead host never got to append. Once the sentinel has been read and the
+ *    replay has been forwarded, the log — not the journal — is the record. A late
+ *    takeover therefore aligns against the log: `align.ts`'s `alignToStoredLog`
+ *    takes a `StreamDurability` and an `AsyncIterable<StreamChunk>`, has no
+ *    `SandboxHandle` and no {@link JournalPaths} in its signature, and reads the
+ *    prefix with `durability.snapshot()`. It *cannot* read the journal, so
+ *    deleting one that is terminal cannot break it.
+ * 2. **A non-zero exit is terminal too.** `{"__exit":7}` is as final as
+ *    `{"__exit":0}`; the run failed, it is not resumable, and the failure is
+ *    already on its way to the client as a `RUN_ERROR`. Keeping a failed run's
+ *    journal would leak exactly the runs most likely to be numerous.
+ * 3. **An abort is NOT terminal.** A consumer that stops early (lease lost,
+ *    client gone, host shutting down) may be handing the run off to a successor
+ *    host that still needs every byte, so an aborted read must leave both files
+ *    alone.
+ *
+ * Shell `rm`, never `handle.fs.remove`: rule 3 in the module doc. On
+ * local-process `/tmp` resolves under the sandbox root through `fs.*` but to the
+ * host's real `/tmp` through the shell, so an `fs.remove` would delete a
+ * different path than the one `journaledCommand` wrote — i.e. nothing, silently.
+ *
+ * `-f` so a journal that is already gone (a provider that reaped `/tmp`, a
+ * successor that cleaned up first) is a success, not an error. Callers treat the
+ * whole thing as best effort regardless: a failed cleanup must never fail a run
+ * that has already completed.
+ *
+ * **What this does NOT bound:** a run that reaches its sentinel while DETACHED
+ * has no host reading its journal, so nothing ever observes the sentinel and
+ * nothing calls this. Bounding it is `pruneJournals`' job (`journal-sweep.ts`):
+ * a sweep over {@link DEFAULT_JOURNAL_DIR} that deletes only the journals whose
+ * runs the store says are terminal. It runs from a cron the application
+ * schedules, not from a run, so such a journal survives until that sweep — on a
+ * `keepAlive` sandbox, indefinitely without one.
+ */
+export declare function journalCleanupCommand(paths: JournalPaths): string;
+/**
+ * List the journal directory, one entry per line.
+ *
+ * **`2>/dev/null` is load-bearing, not tidiness.** Daytona's `exec` folds
+ * stderr into stdout by contract and the Sprites fast path does the same, so on
+ * a directory that does not exist yet — the normal state before the first run —
+ * an `ls: cannot access '/tmp/tanstack-runs': No such file or directory`
+ * diagnostic would arrive as if it were a LINE OF OUTPUT. The sweep would then
+ * hand that sentence to {@link decodeJournalRunId} and, if it decoded, delete
+ * whatever it named. Silencing it inside the sandbox means a missing directory
+ * produces zero lines, which is the truth.
+ *
+ * `-1` so one entry occupies one line: `ls` only defaults to columns on a tty,
+ * but `exec`'s stdout is not always a pipe on every provider and the flag costs
+ * nothing.
+ *
+ * **Dot-files are not listed**, by `ls` default. A runId beginning with `.`
+ * encodes to a hidden filename (`.` passes through the encoder), so its journal
+ * is invisible to a sweep and leaks rather than being deleted. That is the safe
+ * direction of the two and the reason this is documented rather than fixed with
+ * `-a`, which would also introduce `.` and `..` as entries.
+ */
+export declare function journalListCommand(dir?: string): string;
+/** One listed journal file with its modification time. */
+export interface JournalDirEntry {
+    /** Filename as listed, extension included; feed to {@link decodeJournalRunId}. */
+    name: string;
+    /** Modification time in milliseconds since the epoch. */
+    mtimeMs: number;
+}
+/**
+ * Outcome of {@link parseJournalMtimeListing}. Deliberately NOT an array: see
+ * that function's doc for why an empty list must not be the failure value.
+ */
+export type JournalMtimeListing = 
+/** The mechanism ran. `entries` is complete — possibly, and meaningfully, empty. */
+{
+    kind: 'listed';
+    entries: Array<JournalDirEntry>;
+}
+/**
+ * The listing did not run (no `stat -c`, or the directory is absent). Nothing
+ * is known about the directory's contents — in particular NOT that it is
+ * empty, and NOT that anything in it is old.
+ */
+ | {
+    kind: 'unavailable';
+};
+/**
+ * List the journal directory WITH modification times, so a sweep can leave
+ * recently-touched journals alone.
+ *
+ * **Neither `find -newermt` nor `find -printf` may be used here.** Both are GNU
+ * extensions, absent from BusyBox 1.37 — the `alpine:3` shell every docker-
+ * provider journal test runs in — and absent from MINGW64's `find`. Measured
+ * working on BusyBox 1.37, GNU coreutils, and MINGW64: `stat -c "%Y %n"`, which
+ * is what this emits. (`touch -d <ts> ref` plus `find ! -newer ref` also works
+ * on all three, but it needs a writable reference file OUTSIDE the journal
+ * directory — inside, `ls -1` would report the reference as an entry — and a
+ * write is a side effect this pure-composition module has no business having.)
+ *
+ * **The directory is passed as its own first operand on purpose.** It is a
+ * self-witness. `stat` reports every operand it can and only *then* exits
+ * non-zero, so:
+ *
+ * - populated directory → witness line + one line per file, exit 0
+ * - EMPTY directory → witness line only, exit 1 (the unexpanded glob is an
+ *   operand `stat` cannot stat)
+ * - `stat` without `-c` support → NO output at all, exit 1
+ *
+ * That is what makes "no files" distinguishable from "the mechanism is
+ * unavailable", and it has to be distinguishable because BusyBox exits 1 with
+ * EMPTY stdout on an unrecognised flag. A caller that ignored the exit code and
+ * took an empty parse as an empty directory would conclude every journal is
+ * absent; one that then inferred "therefore nothing is recent" would delete the
+ * whole directory. Hence {@link parseJournalMtimeListing} returns
+ * `{ kind: 'unavailable' }` rather than `[]`, and the exit code is not consulted
+ * at all — the witness line, not the status, is the evidence.
+ *
+ * Note the glob shares `ls`'s dot-file blindness (same fail-safe consequence),
+ * and that `stat` cannot distinguish a file from a subdirectory here; a stray
+ * subdirectory is caught downstream, because its name will not decode.
+ */
+export declare function journalMtimeListCommand(dir?: string): string;
+/**
+ * Parse {@link journalMtimeListCommand}'s stdout.
+ *
+ * Line-based, space-split parsing is unambiguous here: an encoded filename can
+ * only contain `[A-Za-z0-9.-]` and `_hh` escapes (see {@link encodeRunId}), so
+ * it can never contain a space or a newline, and `%Y` is digits. A line that
+ * does not fit the shape — including a directory prefix that is not `dir` — is
+ * dropped rather than guessed at.
+ */
+export declare function parseJournalMtimeListing(text: string, dir?: string): JournalMtimeListing;
+/**
+ * Bounded read of the END of a run's journal, purely to learn whether the agent
+ * reached its `{"__exit":N}` sentinel.
+ *
+ * **This exists so a reaper does not have to drive the run to find out.**
+ * Entering `pipeToRunLog` to check writes a terminal status and calls
+ * `durability.close()` on every path, including for a healthy mid-flight run —
+ * recording it as `'completed'`, which drops it out of `listReclaimable`
+ * forever. This probe is read-only and provider-neutral, and it is what makes a
+ * reclaim candidate safe to drive.
+ *
+ * The command is the byte-identical idiom to {@link journalStderrReadCommand},
+ * pointed at the journal instead of the sidecar: `tail -c -N` (the LAST N
+ * bytes, because the sentinel is at the end), `2>/dev/null` so a missing
+ * journal cannot splice a diagnostic into the bytes on a provider that folds
+ * stderr into stdout, and base64 framing. Verified on BusyBox 1.37.
+ *
+ * base64 is correct HERE and forbidden on {@link journalFollowCommand} for the
+ * reason rule 2 in the module doc measures: the encoder fully buffers a piped
+ * stdout, which is harmless when `exec` closes its stdin and fatal when the
+ * producer is `tail -f`. This read is bounded and terminates, so it never
+ * streams.
+ */
+export declare function journalExitProbeCommand(paths: JournalPaths, maxBytes?: number): string;
+/**
+ * Is ONE journal line this run's genuine exit sentinel? The exit code if so,
+ * `null` for anything else — including a line that carries
+ * {@link EXIT_SENTINEL_KEY} but not this run's nonce, which is agent output and
+ * nothing more.
+ *
+ * FAIL CLOSED at every step, because the consumers of a non-`null` answer stop
+ * the run and reclaim its sandbox:
+ *
+ * - not JSON, or not an object → `null`. This is also what absorbs the partial
+ *   first line a byte-bounded `tail -c -N` can start in the middle of.
+ * - no `__nonce`, or a `__nonce` that is not exactly `paths.nonce` → `null`. An
+ *   agent line cannot be told from the shell's without this (see
+ *   {@link EXIT_SENTINEL_NONCE_KEY}).
+ * - a matching nonce but a non-integer `__exit` → `null`, NOT `0`. The old code
+ *   coerced a non-number to `0`, which turned a garbled sentinel into a reported
+ *   SUCCESS. Nothing that reaches here legitimately can be non-integer: the only
+ *   writer is `printf '…%d…' "$?"`.
+ *
+ * Exported so the streaming reader (`runner.ts`) applies exactly the same test,
+ * line by line, that the reaper's bounded tail probe applies — one definition of
+ * "the run ended", not two that can drift.
+ */
+export declare function parseExitSentinel(line: string, paths: JournalPaths): number | null;
+/**
+ * Find the exit sentinel in a decoded journal tail; `null` when it is absent,
+ * which is the mid-flight (or never-started) case.
+ *
+ * **Scanned from the END, and the nonce is REQUIRED.** Both matter, and both are
+ * corrections:
+ *
+ * - The shell appends the real sentinel AFTER the command's own output, so the
+ *   genuine one is always the last matching line in the window. Taking the first
+ *   match let an agent line that happened to look like a sentinel win over the
+ *   truth that followed it.
+ * - `paths.nonce` must match, or the line is not a sentinel at all. Without that,
+ *   a mid-flight run whose agent printed any JSON object containing `__exit` read
+ *   as `finished`, and the reaper destroyed a live sandbox on the strength of it.
+ *
+ * `paths` rather than a bare nonce string so callers pass the object they already
+ * hold and cannot pair a tail with another run's nonce.
+ */
+export declare function parseJournalExit(text: string, paths: JournalPaths): number | null;