@tanstack/ai-sandbox 0.2.3 → 0.3.0

package/dist/esm/testkit/durable-run-fields-conformance.js

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+//#region src/testkit/durable-run-fields-conformance.ts
+/**
+* Conformance for the DURABLE-RUN fields on a `RunStore`.
+*
+* These four fields (`sandboxKey`, `detachedSince`, `cancelRequested`,
+* `driverEpoch`) exist for durable sandboxed runs: detach on disconnect, takeover
+* by a later host, and the reaper. A chat-only app never writes them, so proving
+* them is NOT part of `runPersistenceConformance` in `@tanstack/ai-persistence`.
+* They live here, next to the takeover and reaper suites that depend on them.
+*
+* Run this when your app wires `withSandbox(sandbox, { runs, durability })`. The
+* fields round-trip through the REQUIRED `update`/`get` pair, so a backend can
+* pass every persistence case while silently dropping one of them, and the
+* failure then shows up as a run that looks permanently detached or a takeover
+* that cannot fence a superseded host.
+*
+* ```ts
+* import { runDurableRunFieldsConformance } from '@tanstack/ai-sandbox/testkit'
+* import { myPersistence } from './persistence'
+*
+* runDurableRunFieldsConformance('my postgres runs', () => myPersistence().stores.runs)
+* ```
+*/
+function runDurableRunFieldsConformance(name, makeStore) {
+	describe(`durable run fields conformance: ${name}`, () => {
+		it("round-trips the durable run fields, overwrites driverEpoch, and clears every one of them on explicit undefined", async () => {
+			const store = await makeStore();
+			await store.createOrResume({
+				runId: "fc-1",
+				threadId: "fc-t",
+				startedAt: 1
+			});
+			const fresh = await store.get("fc-1");
+			expect(fresh?.cancelRequested).toBeUndefined();
+			expect(fresh?.detachedSince).toBeUndefined();
+			expect(fresh?.sandboxKey).toBeUndefined();
+			expect(fresh?.driverEpoch).toBeUndefined();
+			await store.update("fc-1", {
+				sandboxKey: "sandbox-abc",
+				detachedSince: 500,
+				cancelRequested: true,
+				driverEpoch: 1
+			});
+			const afterFirstUpdate = await store.get("fc-1");
+			expect(afterFirstUpdate?.sandboxKey).toBe("sandbox-abc");
+			expect(afterFirstUpdate?.detachedSince).toBe(500);
+			expect(afterFirstUpdate?.cancelRequested).toBe(true);
+			expect(afterFirstUpdate?.driverEpoch).toBe(1);
+			await store.update("fc-1", { driverEpoch: 2 });
+			const afterEpochBump = await store.get("fc-1");
+			expect(afterEpochBump?.driverEpoch).toBe(2);
+			expect(afterEpochBump?.sandboxKey).toBe("sandbox-abc");
+			expect(afterEpochBump?.cancelRequested).toBe(true);
+			await store.update("fc-1", { detachedSince: void 0 });
+			const afterClear = await store.get("fc-1");
+			expect(afterClear?.detachedSince).toBeUndefined();
+			expect(afterClear?.sandboxKey).toBe("sandbox-abc");
+			expect(afterClear?.cancelRequested).toBe(true);
+			expect(afterClear?.driverEpoch).toBe(2);
+			await store.update("fc-1", { cancelRequested: false });
+			const afterExplicitFalse = await store.get("fc-1");
+			expect(afterExplicitFalse?.cancelRequested).toBe(false);
+			expect(afterExplicitFalse?.cancelRequested).not.toBeUndefined();
+			await store.update("fc-1", {
+				sandboxKey: "sandbox-xyz",
+				detachedSince: 900,
+				cancelRequested: true,
+				driverEpoch: 3
+			});
+			const beforeFullClear = await store.get("fc-1");
+			expect(beforeFullClear?.sandboxKey).toBe("sandbox-xyz");
+			expect(beforeFullClear?.detachedSince).toBe(900);
+			expect(beforeFullClear?.cancelRequested).toBe(true);
+			expect(beforeFullClear?.driverEpoch).toBe(3);
+			await store.update("fc-1", {
+				sandboxKey: void 0,
+				detachedSince: void 0,
+				cancelRequested: void 0,
+				driverEpoch: void 0
+			});
+			const afterFullClear = await store.get("fc-1");
+			expect(afterFullClear?.sandboxKey).toBeUndefined();
+			expect(afterFullClear?.detachedSince).toBeUndefined();
+			expect(afterFullClear?.cancelRequested).toBeUndefined();
+			expect(afterFullClear?.driverEpoch).toBeUndefined();
+			expect(afterFullClear?.status).toBe("running");
+			expect(afterFullClear?.startedAt).toBe(1);
+		});
+	});
+}
+//#endregion
+export { runDurableRunFieldsConformance };
+
+//# sourceMappingURL=durable-run-fields-conformance.js.map

package/dist/esm/testkit/durable-run-fields-conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-run-fields-conformance.js","names":[],"sources":["../../../src/testkit/durable-run-fields-conformance.ts"],"sourcesContent":["/**\n * Conformance for the DURABLE-RUN fields on a `RunStore`.\n *\n * These four fields (`sandboxKey`, `detachedSince`, `cancelRequested`,\n * `driverEpoch`) exist for durable sandboxed runs: detach on disconnect, takeover\n * by a later host, and the reaper. A chat-only app never writes them, so proving\n * them is NOT part of `runPersistenceConformance` in `@tanstack/ai-persistence`.\n * They live here, next to the takeover and reaper suites that depend on them.\n *\n * Run this when your app wires `withSandbox(sandbox, { runs, durability })`. The\n * fields round-trip through the REQUIRED `update`/`get` pair, so a backend can\n * pass every persistence case while silently dropping one of them, and the\n * failure then shows up as a run that looks permanently detached or a takeover\n * that cannot fence a superseded host.\n *\n * ```ts\n * import { runDurableRunFieldsConformance } from '@tanstack/ai-sandbox/testkit'\n * import { myPersistence } from './persistence'\n *\n * runDurableRunFieldsConformance('my postgres runs', () => myPersistence().stores.runs)\n * ```\n */\nimport { describe, expect, it } from 'vitest'\nimport type { RunStore } from '@tanstack/ai'\n\n/** Factory for the store under test. A fresh one per case keeps them isolated. */\nexport type MakeRunStore = () => RunStore | Promise<RunStore>\n\nexport function runDurableRunFieldsConformance(\n  name: string,\n  makeStore: MakeRunStore,\n): void {\n  describe(`durable run fields conformance: ${name}`, () => {\n    // One case, because the four fields share one failure mode: a backend that\n    // filters `undefined` out of its `SET` clause, or coerces an absent column to\n    // a falsy default, passes every other assertion while breaking detach and\n    // takeover. Splitting it per field would hide that they must all behave the\n    // same way through one `update`.\n    it('round-trips the durable run fields, overwrites driverEpoch, and clears every one of them on explicit undefined', async () => {\n      const store = await makeStore()\n\n      await store.createOrResume({\n        runId: 'fc-1',\n        threadId: 'fc-t',\n        startedAt: 1,\n      })\n\n      // 0. A fresh run that was never patched with these fields must read\n      // back as undefined -- not null, not false, not 0. A backend that\n      // coerces a NULL/absent column to a falsy default (e.g.\n      // `cancelRequested: false`) is claiming knowledge (\"explicitly not\n      // cancelled\") it does not have, and `toBeFalsy()` would not catch\n      // it since `false` is falsy too.\n      const fresh = await store.get('fc-1')\n      expect(fresh?.cancelRequested).toBeUndefined()\n      expect(fresh?.detachedSince).toBeUndefined()\n      expect(fresh?.sandboxKey).toBeUndefined()\n      expect(fresh?.driverEpoch).toBeUndefined()\n\n      // 1. All four fields round-trip through update -> get.\n      await store.update('fc-1', {\n        sandboxKey: 'sandbox-abc',\n        detachedSince: 500,\n        cancelRequested: true,\n        driverEpoch: 1,\n      })\n      const afterFirstUpdate = await store.get('fc-1')\n      expect(afterFirstUpdate?.sandboxKey).toBe('sandbox-abc')\n      expect(afterFirstUpdate?.detachedSince).toBe(500)\n      expect(afterFirstUpdate?.cancelRequested).toBe(true)\n      expect(afterFirstUpdate?.driverEpoch).toBe(1)\n\n      // 2. A monotonic driverEpoch bump overwrites, it is not ignored (a\n      // takeover host bumping the fencing token must actually stick).\n      await store.update('fc-1', { driverEpoch: 2 })\n      const afterEpochBump = await store.get('fc-1')\n      expect(afterEpochBump?.driverEpoch).toBe(2)\n      // Sibling fields untouched by an update that only names driverEpoch.\n      expect(afterEpochBump?.sandboxKey).toBe('sandbox-abc')\n      expect(afterEpochBump?.cancelRequested).toBe(true)\n\n      // 3. update({ detachedSince: undefined }) actually CLEARS the field.\n      // A backend whose SQL adapter filters `undefined` out of its `SET`\n      // clause leaves the old value, and every re-attached run then looks\n      // permanently detached to the reaper.\n      await store.update('fc-1', { detachedSince: undefined })\n      const afterClear = await store.get('fc-1')\n      expect(afterClear?.detachedSince).toBeUndefined()\n      // Clearing detachedSince must not clobber the other durable fields.\n      expect(afterClear?.sandboxKey).toBe('sandbox-abc')\n      expect(afterClear?.cancelRequested).toBe(true)\n      expect(afterClear?.driverEpoch).toBe(2)\n\n      // 4. cancelRequested: false written EXPLICITLY must round-trip as\n      // `false`, distinct from the fresh-run `undefined` checked in step 0.\n      // A backend storing this boolean in an integer/NULL-able column has\n      // to preserve the false/undefined distinction in both directions,\n      // not just collapse both to falsy.\n      await store.update('fc-1', { cancelRequested: false })\n      const afterExplicitFalse = await store.get('fc-1')\n      expect(afterExplicitFalse?.cancelRequested).toBe(false)\n      expect(afterExplicitFalse?.cancelRequested).not.toBeUndefined()\n\n      // 5. An explicit `undefined` clears EVERY durable field, not just\n      // `detachedSince`. Step 3 only exercised one of the four, so a backend\n      // half-converted to `'field' in patch` -- `in` for `detachedSince`,\n      // still `patch.field !== undefined` for the rest -- passed the whole\n      // suite while its clears silently no-opped. Step 4's explicit `false`\n      // also survives a `!== undefined` guard, so nothing else here bites\n      // either. Re-populate first, so each clear has a value to remove and\n      // an assertion that fails when the clear is dropped.\n      await store.update('fc-1', {\n        sandboxKey: 'sandbox-xyz',\n        detachedSince: 900,\n        cancelRequested: true,\n        driverEpoch: 3,\n      })\n      const beforeFullClear = await store.get('fc-1')\n      expect(beforeFullClear?.sandboxKey).toBe('sandbox-xyz')\n      expect(beforeFullClear?.detachedSince).toBe(900)\n      expect(beforeFullClear?.cancelRequested).toBe(true)\n      expect(beforeFullClear?.driverEpoch).toBe(3)\n\n      await store.update('fc-1', {\n        sandboxKey: undefined,\n        detachedSince: undefined,\n        cancelRequested: undefined,\n        driverEpoch: undefined,\n      })\n      const afterFullClear = await store.get('fc-1')\n      expect(afterFullClear?.sandboxKey).toBeUndefined()\n      expect(afterFullClear?.detachedSince).toBeUndefined()\n      expect(afterFullClear?.cancelRequested).toBeUndefined()\n      expect(afterFullClear?.driverEpoch).toBeUndefined()\n      // Clearing the durable fields is not a delete: the run row survives,\n      // and the fields the patch never named keep their values.\n      expect(afterFullClear?.status).toBe('running')\n      expect(afterFullClear?.startedAt).toBe(1)\n    })\n\n    // `findActiveRun` is REQUIRED on the RunStore contract — every backend that\n    // provides a `runs` store must satisfy these invariants (most-recent-running\n    // wins, thread-scoped, null when idle). Reconnect is built on it, and a\n    // backend that always answers `null` disables reconnect indistinguishably\n    // from one that is merely idle, so this must never degrade to a skip.\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,+BACd,MACA,WACM;CACN,SAAS,mCAAmC,cAAc;EAMxD,GAAG,kHAAkH,YAAY;GAC/H,MAAM,QAAQ,MAAM,UAAU;GAE9B,MAAM,MAAM,eAAe;IACzB,OAAO;IACP,UAAU;IACV,WAAW;GACb,CAAC;GAQD,MAAM,QAAQ,MAAM,MAAM,IAAI,MAAM;GACpC,OAAO,OAAO,eAAe,CAAC,CAAC,cAAc;GAC7C,OAAO,OAAO,aAAa,CAAC,CAAC,cAAc;GAC3C,OAAO,OAAO,UAAU,CAAC,CAAC,cAAc;GACxC,OAAO,OAAO,WAAW,CAAC,CAAC,cAAc;GAGzC,MAAM,MAAM,OAAO,QAAQ;IACzB,YAAY;IACZ,eAAe;IACf,iBAAiB;IACjB,aAAa;GACf,CAAC;GACD,MAAM,mBAAmB,MAAM,MAAM,IAAI,MAAM;GAC/C,OAAO,kBAAkB,UAAU,CAAC,CAAC,KAAK,aAAa;GACvD,OAAO,kBAAkB,aAAa,CAAC,CAAC,KAAK,GAAG;GAChD,OAAO,kBAAkB,eAAe,CAAC,CAAC,KAAK,IAAI;GACnD,OAAO,kBAAkB,WAAW,CAAC,CAAC,KAAK,CAAC;GAI5C,MAAM,MAAM,OAAO,QAAQ,EAAE,aAAa,EAAE,CAAC;GAC7C,MAAM,iBAAiB,MAAM,MAAM,IAAI,MAAM;GAC7C,OAAO,gBAAgB,WAAW,CAAC,CAAC,KAAK,CAAC;GAE1C,OAAO,gBAAgB,UAAU,CAAC,CAAC,KAAK,aAAa;GACrD,OAAO,gBAAgB,eAAe,CAAC,CAAC,KAAK,IAAI;GAMjD,MAAM,MAAM,OAAO,QAAQ,EAAE,eAAe,KAAA,EAAU,CAAC;GACvD,MAAM,aAAa,MAAM,MAAM,IAAI,MAAM;GACzC,OAAO,YAAY,aAAa,CAAC,CAAC,cAAc;GAEhD,OAAO,YAAY,UAAU,CAAC,CAAC,KAAK,aAAa;GACjD,OAAO,YAAY,eAAe,CAAC,CAAC,KAAK,IAAI;GAC7C,OAAO,YAAY,WAAW,CAAC,CAAC,KAAK,CAAC;GAOtC,MAAM,MAAM,OAAO,QAAQ,EAAE,iBAAiB,MAAM,CAAC;GACrD,MAAM,qBAAqB,MAAM,MAAM,IAAI,MAAM;GACjD,OAAO,oBAAoB,eAAe,CAAC,CAAC,KAAK,KAAK;GACtD,OAAO,oBAAoB,eAAe,CAAC,CAAC,IAAI,cAAc;GAU9D,MAAM,MAAM,OAAO,QAAQ;IACzB,YAAY;IACZ,eAAe;IACf,iBAAiB;IACjB,aAAa;GACf,CAAC;GACD,MAAM,kBAAkB,MAAM,MAAM,IAAI,MAAM;GAC9C,OAAO,iBAAiB,UAAU,CAAC,CAAC,KAAK,aAAa;GACtD,OAAO,iBAAiB,aAAa,CAAC,CAAC,KAAK,GAAG;GAC/C,OAAO,iBAAiB,eAAe,CAAC,CAAC,KAAK,IAAI;GAClD,OAAO,iBAAiB,WAAW,CAAC,CAAC,KAAK,CAAC;GAE3C,MAAM,MAAM,OAAO,QAAQ;IACzB,YAAY,KAAA;IACZ,eAAe,KAAA;IACf,iBAAiB,KAAA;IACjB,aAAa,KAAA;GACf,CAAC;GACD,MAAM,iBAAiB,MAAM,MAAM,IAAI,MAAM;GAC7C,OAAO,gBAAgB,UAAU,CAAC,CAAC,cAAc;GACjD,OAAO,gBAAgB,aAAa,CAAC,CAAC,cAAc;GACpD,OAAO,gBAAgB,eAAe,CAAC,CAAC,cAAc;GACtD,OAAO,gBAAgB,WAAW,CAAC,CAAC,cAAc;GAGlD,OAAO,gBAAgB,MAAM,CAAC,CAAC,KAAK,SAAS;GAC7C,OAAO,gBAAgB,SAAS,CAAC,CAAC,KAAK,CAAC;EAC1C,CAAC;CAOH,CAAC;AACH"}

package/dist/esm/testkit/journal-conformance.d.ts

@@ -0,0 +1,51 @@
+import { JournalPaths } from '../journal.js';
+import { SandboxHandle } from '../contracts.js';
+export interface JournalConformanceConfig {
+    /** Provider name, used in the describe title. */
+    name: string;
+    /** Create a live sandbox plus its teardown. */
+    createHandle: () => Promise<{
+        handle: SandboxHandle;
+        dispose: () => Promise<void>;
+    }>;
+    /**
+     * Declare that this provider cannot journal, with the reason. Registers a
+     * skipped case whose title carries the reason. Omit it and the suite runs.
+     */
+    unsupported?: {
+        reason: string;
+    };
+    /**
+     * Declare that this provider's reads take the POLL strategy rather than the
+     * FOLLOW one — i.e. `journalReadStrategy` answers `'poll'` for its handles,
+     * because it lacks `backgroundProcesses` or `killableProcesses`. The two follow
+     * cases then register as NAMED skips carrying the reason.
+     *
+     * Declare this ONLY when the provider really cannot follow. It is checked
+     * against a live handle in a case that always runs
+     * ({@link expectDeclaredStrategy}), so a wrong declaration fails the suite in
+     * either direction rather than quietly removing coverage.
+     */
+    followUnsupported?: {
+        reason: string;
+    };
+}
+/**
+ * Block until the run's journal file exists in the sandbox.
+ *
+ * Through the shell (`journalExistsCommand`), never `handle.fs.exists` — see
+ * rule 3 in `../journal.ts`: on local-process the two resolve `/tmp`
+ * differently, so an `fs` probe would report the wrong file.
+ *
+ * Exported for `./reaper-conformance.ts`, which needs the same bounded,
+ * shell-only wait before probing a still-producing run. Internal to the testkit;
+ * not part of the `./testkit` public surface.
+ */
+export declare function waitForJournal(handle: SandboxHandle, paths: JournalPaths): Promise<void>;
+/**
+ * Assert `createHandle` satisfies the journal conformance contract. Each `it`
+ * gets a fresh sandbox via `createHandle`/`dispose`, so implementations may
+ * share process state across calls without cross-test bleed only if
+ * `createHandle` returns an isolated sandbox.
+ */
+export declare function runJournalConformance(config: JournalConformanceConfig): void;

package/dist/esm/testkit/journal-conformance.js

@@ -0,0 +1,378 @@
+import { exitSentinelLine, journalExistsCommand, journalPaths, journalReadCommand, journaledCommand } from "../journal.js";
+import { journalReadStrategy, readJournal } from "../journal-reader.js";
+import { randomUUID } from "node:crypto";
+import { describe, expect, it } from "vitest";
+//#region src/testkit/journal-conformance.ts
+/**
+* Provider conformance for the agent output journal.
+*
+* The journal design rests on two provider-level claims: a command string is
+* framed through a POSIX shell (so `>>` redirection works), and `tail -c +N -f`
+* is available. Both are asserted here against a real sandbox rather than
+* assumed from the audit.
+*
+* A provider that cannot satisfy them MUST declare `unsupported.reason`. There
+* is deliberately no silent-skip path: a conformance case that quietly returns
+* prints as a pass, which is how an unimplemented capability ships green. The
+* three FOLLOW cases obey the same rule through a second declaration,
+* {@link JournalConformanceConfig.followUnsupported} — see {@link itFollows} for
+* why the strategy has to be declared rather than detected at registration time,
+* and {@link expectDeclaredStrategy} for what keeps the declaration honest.
+*
+* THE THIRD FOLLOW CASE TESTS THE OTHER SIDE OF THE BOUNDARY, and it is here
+* because the first two do not. `killableProcesses` is what selects `'follow'`
+* over `'poll'`, and a wrong `true` means `tail -f` is spawned on the assumption
+* it can be reclaimed — leaking one follower per run when it cannot. The two
+* follow cases only ever asserted that the READER stops, which
+* `journal-reader.ts`'s `untilAborted` guarantees on its own by abandoning the
+* pipe the moment the signal fires. So both of them pass a provider whose
+* `kill()` is `() => Promise.resolve()`, and three of the four `true`
+* declarations in this repo were in fact false: Docker's `stream.destroy()` only
+* detached the client, local-process's `sh -c` forks so signalling the shell left
+* the command alive, and Vercel's `kill()` never called the SDK's real
+* `Command.kill` at all. Every one of them shipped green through this suite.
+* "kills the sandbox-side process, not just the host's view of it" is the case
+* that fails them — see its own comment for how it probes.
+*
+* Vitest is an OPTIONAL peer dependency: this module is imported only from test
+* files, which already run under Vitest.
+*/
+/**
+* Per-case timeout. Every case here spawns a real sandbox and a real agent.
+*
+* 180s, not the 60s this used to be, and it matches the ceiling
+* `takeover-conformance.ts` already gives its heaviest cases. It is the one
+* wall-clock number left in the file and it is deliberately far outside the range
+* any healthy run needs: a case here makes half a dozen provider round-trips, and
+* ONE `docker exec` on a loaded daemon has been measured at 9.6s (see
+* `takeover-conformance.ts`'s `countingExec`) and at 20–45s on a saturated one, so
+* a 60s budget put the timeout itself in the same load-sensitive class as the
+* assertions that were removed from these cases — measured going red on cases that
+* pass in 7–13s each on a quiet machine.
+*
+* This bound exists only so a genuine hang FAILS instead of parking CI; it is not
+* an assertion about speed, and nothing here should be tuned to sit near it.
+*/
+var CASE_TIMEOUT_MS = 18e4;
+/**
+* Register a case that only means anything on a provider whose reads FOLLOW.
+*
+* `journalReadStrategy` needs a live handle and a live handle needs the async
+* `createHandle`, so the strategy is not knowable when the cases are registered.
+* It is therefore DECLARED, and the declaration selects `it` or `it.skip` here.
+*
+* This exists because the alternative — checking the strategy inside the case and
+* returning early — is the silent-skip the module doc forbids. Such a case prints
+* `✓` with a duration and a title claiming a property was verified while every
+* real assertion in it (including the incremental-delivery handshake, which is
+* the entire reason the follow path exists) was skipped. A named `it.skip` prints
+* `↓` with the reason instead.
+*/
+function itFollows(config, title, fn) {
+	const unsupported = config.followUnsupported;
+	if (unsupported === void 0) {
+		it(title, fn, CASE_TIMEOUT_MS);
+		return;
+	}
+	it.skip(`${title} — follow strategy unsupported: ${unsupported.reason}`, fn, CASE_TIMEOUT_MS);
+}
+/**
+* Assert the live handle's read strategy is the one the config DECLARED.
+*
+* BOTH directions are defects, and neither is a skip. A provider that declared
+* `followUnsupported` but whose handles do follow silently loses the two cases it
+* could pass. One that declared nothing but polls would reach the follow
+* assertions and fail them for a reason unrelated to journaling — which is what
+* the previous `expect(handle.capabilities.killableProcesses).toBe(false)` branch
+* did to a provider with `backgroundProcesses: false, killableProcesses: true`.
+* Either way the config does not describe the provider, and that is worth
+* failing.
+*/
+function expectDeclaredStrategy(handle, config) {
+	expect(journalReadStrategy(handle)).toBe(config.followUnsupported === void 0 ? "follow" : "poll");
+}
+/** Decode the base64 frame a journal read command produces into raw text. */
+function decodeJournalRead(stdout) {
+	return Buffer.from(stdout.replace(/\s+/g, ""), "base64").toString("utf8");
+}
+/**
+* Block until the run's journal file exists in the sandbox.
+*
+* Through the shell (`journalExistsCommand`), never `handle.fs.exists` — see
+* rule 3 in `../journal.ts`: on local-process the two resolve `/tmp`
+* differently, so an `fs` probe would report the wrong file.
+*
+* Exported for `./reaper-conformance.ts`, which needs the same bounded,
+* shell-only wait before probing a still-producing run. Internal to the testkit;
+* not part of the `./testkit` public surface.
+*/
+async function waitForJournal(handle, paths) {
+	const deadline = Date.now() + 15e3;
+	for (;;) {
+		if ((await handle.process.exec(journalExistsCommand(paths))).exitCode === 0) return;
+		if (Date.now() > deadline) throw new Error(`journal conformance: ${paths.journal} never appeared`);
+		await sleep(100);
+	}
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* An absolute path inside the sandbox that no other case, suite, or machine will
+* touch.
+*
+* Every character is in `[A-Za-z0-9./-]`, so these interpolate into the shell
+* commands below as a single word without quoting. `/tmp` and not the workspace:
+* on local-process a shell redirect reaches the host's real `/tmp` while
+* `handle.fs` resolves under the sandbox root (see rule 3 in `../journal.ts`),
+* and everything here is written AND read through the shell so the two never have
+* to agree.
+*/
+function noncePath(label) {
+	return `/tmp/tanstack-journal-conformance-${label}-${randomUUID()}`;
+}
+/** Iteration cap on the kill probe's loop, so nothing can outlive the suite. */
+var PROBE_MAX_TICKS = 600;
+/**
+* Bound on a journal read, so a reader that delivers nothing FAILS instead of
+* parking CI.
+*
+* Never an assertion, and deliberately far above anything a healthy read needs
+* (measured: 10–18s for the follow cases on both providers). Each case that uses
+* it proves its property some other way — a causal handshake, or
+* `backstop.aborted` — so this number can be raised freely and must never be the
+* thing a case is tuned against.
+*/
+var READ_BACKSTOP_MS = 9e4;
+/**
+* How long to let an asynchronous kill land before the quiet window opens.
+*
+* A kill is asynchronous on every provider here — Docker signals through a
+* second `exec`, local-process signals a process group and lets the OS reap — so
+* one more heartbeat tick immediately after `kill()` resolves is not a survivor.
+*/
+var KILL_SETTLE_MS = 5e3;
+/**
+* The quiet window: how long the heartbeat must stay frozen.
+*
+* This is NOT a load-sensitive bound, and the asymmetry is the point. A dead
+* process can never write again, so a slow or busy machine can only make this
+* window MORE reliable, never less — unlike a "must happen within Nms" ceiling,
+* which fails on load. Only a live survivor can end this window, and a live
+* survivor writes once a second.
+*/
+var HEARTBEAT_QUIET_MS = 6e3;
+/**
+* Byte count of `path`, according to the SANDBOX'S OWN shell, or `null` when it
+* cannot be read.
+*
+* `wc -c` through the shell, never `handle.fs`: on local-process the two resolve
+* `/tmp` differently (rule 3), so an `fs` probe would answer about a file the
+* sandbox never wrote and the growth below would look frozen from the first
+* sample — a vacuous pass. Parsed strictly rather than coerced, so a shell
+* diagnostic cannot become `NaN` and compare unequal to itself.
+*/
+async function fileSize(handle, path) {
+	const text = (await handle.process.exec(`wc -c < ${path} 2>/dev/null`)).stdout.trim();
+	return /^\d+$/.test(text) ? Number(text) : null;
+}
+/**
+* Wait until `path` has grown to at least `bytes`, i.e. the probe process is
+* provably DOING WORK inside the sandbox, and answer whether it got there.
+*
+* Returning the observation rather than throwing keeps the verdict inside the
+* case's own `expect`: this is the "before" half of the assertion, and it is what
+* makes the "after" half a live detector instead of a formality.
+*/
+async function waitForTicks(handle, path, bytes) {
+	const deadline = Date.now() + 3e4;
+	for (;;) {
+		const size = await fileSize(handle, path);
+		if (size !== null && size >= bytes) return true;
+		if (Date.now() > deadline) return false;
+		await sleep(1e3);
+	}
+}
+/**
+* Assert `createHandle` satisfies the journal conformance contract. Each `it`
+* gets a fresh sandbox via `createHandle`/`dispose`, so implementations may
+* share process state across calls without cross-test bleed only if
+* `createHandle` returns an isolated sandbox.
+*/
+function runJournalConformance(config) {
+	describe(`journal conformance — ${config.name}`, () => {
+		if (config.unsupported) {
+			it.skip(`unsupported: ${config.unsupported.reason}`, () => {
+				expect(true).toBe(true);
+			});
+			return;
+		}
+		it("redirects a command's stdout into the journal and appends the exit sentinel", async () => {
+			const { handle, dispose } = await config.createHandle();
+			try {
+				expectDeclaredStrategy(handle, config);
+				const paths = journalPaths(`conf-${Date.now()}`);
+				const command = journaledCommand(`printf '{"a":1}\\n{"b":2}\\n'`, paths);
+				expect(await (await handle.process.spawn(command)).wait()).toBe(0);
+				expect(decodeJournalRead((await handle.process.exec(journalReadCommand(paths, 0))).stdout)).toBe(`{"a":1}\n{"b":2}\n${exitSentinelLine(paths, 0)}\n`);
+			} finally {
+				await dispose();
+			}
+		}, CASE_TIMEOUT_MS);
+		it("records the agent's non-zero exit in the sentinel", async () => {
+			const { handle, dispose } = await config.createHandle();
+			try {
+				const paths = journalPaths(`conf-exit-${Date.now()}`);
+				await (await handle.process.spawn(journaledCommand("exit 7", paths))).wait();
+				expect(decodeJournalRead((await handle.process.exec(journalReadCommand(paths, 0))).stdout)).toBe(`${exitSentinelLine(paths, 7)}\n`);
+			} finally {
+				await dispose();
+			}
+		}, CASE_TIMEOUT_MS);
+		it("keeps the agent's stderr out of the journal", async () => {
+			const { handle, dispose } = await config.createHandle();
+			try {
+				const paths = journalPaths(`conf-err-${Date.now()}`);
+				await (await handle.process.spawn(journaledCommand(`printf '{"a":1}\\n'; printf 'a warning\\n' 1>&2`, paths))).wait();
+				const text = decodeJournalRead((await handle.process.exec(journalReadCommand(paths, 0))).stdout);
+				expect(text).toBe(`{"a":1}\n${exitSentinelLine(paths, 0)}\n`);
+				expect(text).not.toContain("a warning");
+			} finally {
+				await dispose();
+			}
+		}, CASE_TIMEOUT_MS);
+		it("reads incrementally from a byte offset with absolute positions", async () => {
+			const { handle, dispose } = await config.createHandle();
+			try {
+				const paths = journalPaths(`conf-seek-${Date.now()}`);
+				await (await handle.process.spawn(journaledCommand(`printf '{"a":1}\\n{"b":2}\\n'`, paths))).wait();
+				const all = [];
+				for await (const line of readJournal(handle, {
+					paths,
+					fromByte: 0,
+					strategy: "poll",
+					pollIntervalMs: 0,
+					signal: AbortSignal.timeout(READ_BACKSTOP_MS)
+				})) {
+					all.push(line);
+					if (all.length === 3) break;
+				}
+				expect(all.map((l) => l.line)).toEqual([
+					"{\"a\":1}",
+					"{\"b\":2}",
+					exitSentinelLine(paths, 0)
+				]);
+				const resumed = [];
+				for await (const line of readJournal(handle, {
+					paths,
+					fromByte: all[0]?.endPosition ?? 0,
+					strategy: "poll",
+					pollIntervalMs: 0,
+					signal: AbortSignal.timeout(READ_BACKSTOP_MS)
+				})) {
+					resumed.push(line);
+					if (resumed.length === 2) break;
+				}
+				expect(resumed.map((l) => l.line)).toEqual(["{\"b\":2}", exitSentinelLine(paths, 0)]);
+				expect(resumed[0]?.endPosition).toBe(all[1]?.endPosition);
+			} finally {
+				await dispose();
+			}
+		}, CASE_TIMEOUT_MS);
+		itFollows(config, "follows a journal that is still being written, delivering each line before the next is produced", async () => {
+			expect.hasAssertions();
+			const { handle, dispose } = await config.createHandle();
+			const gate = noncePath("follow-gate");
+			try {
+				expectDeclaredStrategy(handle, config);
+				const paths = journalPaths(`conf-follow-${Date.now()}`);
+				const agentCommand = `printf '{"a":1}\\n'; i=0; while [ ! -f ${gate} ]; do i=$((i+1)); if [ $i -gt 30 ]; then printf '{"gate":"never"}\\n'; break; fi; sleep 1; done; printf '{"b":2}\\n'`;
+				handle.process.spawn(journaledCommand(agentCommand, paths));
+				await waitForJournal(handle, paths);
+				expect((await handle.process.exec(`test -e ${gate}`)).exitCode).not.toBe(0);
+				const seen = [];
+				for await (const line of readJournal(handle, {
+					paths,
+					fromByte: 0,
+					signal: AbortSignal.timeout(READ_BACKSTOP_MS)
+				})) {
+					seen.push(line.line);
+					if (seen.length === 1) await handle.process.exec(`: >> ${gate}`);
+					if (seen.length === 3) break;
+				}
+				expect(seen).toEqual([
+					"{\"a\":1}",
+					"{\"b\":2}",
+					exitSentinelLine(paths, 0)
+				]);
+			} finally {
+				await handle.process.exec(`: >> ${gate}`).catch(() => void 0);
+				await dispose();
+			}
+		});
+		itFollows(config, "stops a follow read when its signal aborts, without a consumer break", async () => {
+			expect.hasAssertions();
+			const { handle, dispose } = await config.createHandle();
+			try {
+				expectDeclaredStrategy(handle, config);
+				const paths = journalPaths(`conf-abort-${Date.now()}`);
+				const agent = await handle.process.spawn(journaledCommand(`printf '{"a":1}\\n'; sleep 30`, paths));
+				try {
+					await waitForJournal(handle, paths);
+					const seen = [];
+					const stop = new AbortController();
+					const backstop = AbortSignal.timeout(READ_BACKSTOP_MS);
+					for await (const line of readJournal(handle, {
+						paths,
+						fromByte: 0,
+						signal: AbortSignal.any([stop.signal, backstop])
+					})) {
+						seen.push(line.line);
+						stop.abort();
+					}
+					expect({
+						seen,
+						backstopped: backstop.aborted
+					}).toEqual({
+						seen: ["{\"a\":1}"],
+						backstopped: false
+					});
+				} finally {
+					await agent.kill();
+				}
+			} finally {
+				await dispose();
+			}
+		});
+		itFollows(config, "kills the sandbox-side process, not just the host's view of it", async () => {
+			expect.hasAssertions();
+			const { handle, dispose } = await config.createHandle();
+			const heartbeat = noncePath("killprobe-hb");
+			const stop = noncePath("killprobe-stop");
+			try {
+				expectDeclaredStrategy(handle, config);
+				const probe = await handle.process.spawn(`( i=0; while [ ! -f ${stop} ] && [ $i -lt ${PROBE_MAX_TICKS} ]; do printf '.' >> ${heartbeat}; i=$((i+1)); sleep 1; done ) & wait`);
+				const tickedBeforeKill = await waitForTicks(handle, heartbeat, 2);
+				await probe.kill();
+				await sleep(KILL_SETTLE_MS);
+				const atSettle = await fileSize(handle, heartbeat);
+				await sleep(HEARTBEAT_QUIET_MS);
+				const afterQuietWindow = await fileSize(handle, heartbeat);
+				expect({
+					tickedBeforeKill,
+					tickedAfterKill: atSettle === null || afterQuietWindow === null || atSettle !== afterQuietWindow
+				}).toEqual({
+					tickedBeforeKill: true,
+					tickedAfterKill: false
+				});
+			} finally {
+				await handle.process.exec(`: >> ${stop}; rm -f ${heartbeat}`).catch(() => void 0);
+				await dispose();
+			}
+		});
+	});
+}
+//#endregion
+export { runJournalConformance, waitForJournal };
+
+//# sourceMappingURL=journal-conformance.js.map

package/dist/esm/testkit/journal-conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-conformance.js","names":[],"sources":["../../../src/testkit/journal-conformance.ts"],"sourcesContent":["/**\n * Provider conformance for the agent output journal.\n *\n * The journal design rests on two provider-level claims: a command string is\n * framed through a POSIX shell (so `>>` redirection works), and `tail -c +N -f`\n * is available. Both are asserted here against a real sandbox rather than\n * assumed from the audit.\n *\n * A provider that cannot satisfy them MUST declare `unsupported.reason`. There\n * is deliberately no silent-skip path: a conformance case that quietly returns\n * prints as a pass, which is how an unimplemented capability ships green. The\n * three FOLLOW cases obey the same rule through a second declaration,\n * {@link JournalConformanceConfig.followUnsupported} — see {@link itFollows} for\n * why the strategy has to be declared rather than detected at registration time,\n * and {@link expectDeclaredStrategy} for what keeps the declaration honest.\n *\n * THE THIRD FOLLOW CASE TESTS THE OTHER SIDE OF THE BOUNDARY, and it is here\n * because the first two do not. `killableProcesses` is what selects `'follow'`\n * over `'poll'`, and a wrong `true` means `tail -f` is spawned on the assumption\n * it can be reclaimed — leaking one follower per run when it cannot. The two\n * follow cases only ever asserted that the READER stops, which\n * `journal-reader.ts`'s `untilAborted` guarantees on its own by abandoning the\n * pipe the moment the signal fires. So both of them pass a provider whose\n * `kill()` is `() => Promise.resolve()`, and three of the four `true`\n * declarations in this repo were in fact false: Docker's `stream.destroy()` only\n * detached the client, local-process's `sh -c` forks so signalling the shell left\n * the command alive, and Vercel's `kill()` never called the SDK's real\n * `Command.kill` at all. Every one of them shipped green through this suite.\n * \"kills the sandbox-side process, not just the host's view of it\" is the case\n * that fails them — see its own comment for how it probes.\n *\n * Vitest is an OPTIONAL peer dependency: this module is imported only from test\n * files, which already run under Vitest.\n */\nimport { randomUUID } from 'node:crypto'\nimport { describe, expect, it } from 'vitest'\nimport {\n  exitSentinelLine,\n  journalExistsCommand,\n  journalPaths,\n  journalReadCommand,\n  journaledCommand,\n} from '../journal'\nimport { journalReadStrategy, readJournal } from '../journal-reader'\nimport type { JournalPaths } from '../journal'\nimport type { SandboxHandle } from '../contracts'\n\nexport interface JournalConformanceConfig {\n  /** Provider name, used in the describe title. */\n  name: string\n  /** Create a live sandbox plus its teardown. */\n  createHandle: () => Promise<{\n    handle: SandboxHandle\n    dispose: () => Promise<void>\n  }>\n  /**\n   * Declare that this provider cannot journal, with the reason. Registers a\n   * skipped case whose title carries the reason. Omit it and the suite runs.\n   */\n  unsupported?: { reason: string }\n  /**\n   * Declare that this provider's reads take the POLL strategy rather than the\n   * FOLLOW one — i.e. `journalReadStrategy` answers `'poll'` for its handles,\n   * because it lacks `backgroundProcesses` or `killableProcesses`. The two follow\n   * cases then register as NAMED skips carrying the reason.\n   *\n   * Declare this ONLY when the provider really cannot follow. It is checked\n   * against a live handle in a case that always runs\n   * ({@link expectDeclaredStrategy}), so a wrong declaration fails the suite in\n   * either direction rather than quietly removing coverage.\n   */\n  followUnsupported?: { reason: string }\n}\n\n/**\n * Per-case timeout. Every case here spawns a real sandbox and a real agent.\n *\n * 180s, not the 60s this used to be, and it matches the ceiling\n * `takeover-conformance.ts` already gives its heaviest cases. It is the one\n * wall-clock number left in the file and it is deliberately far outside the range\n * any healthy run needs: a case here makes half a dozen provider round-trips, and\n * ONE `docker exec` on a loaded daemon has been measured at 9.6s (see\n * `takeover-conformance.ts`'s `countingExec`) and at 20–45s on a saturated one, so\n * a 60s budget put the timeout itself in the same load-sensitive class as the\n * assertions that were removed from these cases — measured going red on cases that\n * pass in 7–13s each on a quiet machine.\n *\n * This bound exists only so a genuine hang FAILS instead of parking CI; it is not\n * an assertion about speed, and nothing here should be tuned to sit near it.\n */\nconst CASE_TIMEOUT_MS = 180_000\n\n/**\n * Register a case that only means anything on a provider whose reads FOLLOW.\n *\n * `journalReadStrategy` needs a live handle and a live handle needs the async\n * `createHandle`, so the strategy is not knowable when the cases are registered.\n * It is therefore DECLARED, and the declaration selects `it` or `it.skip` here.\n *\n * This exists because the alternative — checking the strategy inside the case and\n * returning early — is the silent-skip the module doc forbids. Such a case prints\n * `✓` with a duration and a title claiming a property was verified while every\n * real assertion in it (including the incremental-delivery handshake, which is\n * the entire reason the follow path exists) was skipped. A named `it.skip` prints\n * `↓` with the reason instead.\n */\nfunction itFollows(\n  config: JournalConformanceConfig,\n  title: string,\n  fn: () => Promise<void>,\n): void {\n  const unsupported = config.followUnsupported\n  if (unsupported === undefined) {\n    it(title, fn, CASE_TIMEOUT_MS)\n    return\n  }\n  it.skip(\n    `${title} — follow strategy unsupported: ${unsupported.reason}`,\n    fn,\n    CASE_TIMEOUT_MS,\n  )\n}\n\n/**\n * Assert the live handle's read strategy is the one the config DECLARED.\n *\n * BOTH directions are defects, and neither is a skip. A provider that declared\n * `followUnsupported` but whose handles do follow silently loses the two cases it\n * could pass. One that declared nothing but polls would reach the follow\n * assertions and fail them for a reason unrelated to journaling — which is what\n * the previous `expect(handle.capabilities.killableProcesses).toBe(false)` branch\n * did to a provider with `backgroundProcesses: false, killableProcesses: true`.\n * Either way the config does not describe the provider, and that is worth\n * failing.\n */\nfunction expectDeclaredStrategy(\n  handle: SandboxHandle,\n  config: JournalConformanceConfig,\n): void {\n  expect(journalReadStrategy(handle)).toBe(\n    config.followUnsupported === undefined ? 'follow' : 'poll',\n  )\n}\n\n/** Decode the base64 frame a journal read command produces into raw text. */\nfunction decodeJournalRead(stdout: string): string {\n  return Buffer.from(stdout.replace(/\\s+/g, ''), 'base64').toString('utf8')\n}\n\n/**\n * Block until the run's journal file exists in the sandbox.\n *\n * Through the shell (`journalExistsCommand`), never `handle.fs.exists` — see\n * rule 3 in `../journal.ts`: on local-process the two resolve `/tmp`\n * differently, so an `fs` probe would report the wrong file.\n *\n * Exported for `./reaper-conformance.ts`, which needs the same bounded,\n * shell-only wait before probing a still-producing run. Internal to the testkit;\n * not part of the `./testkit` public surface.\n */\nexport async function waitForJournal(\n  handle: SandboxHandle,\n  paths: JournalPaths,\n): Promise<void> {\n  const deadline = Date.now() + 15_000\n  for (;;) {\n    const probe = await handle.process.exec(journalExistsCommand(paths))\n    if (probe.exitCode === 0) return\n    if (Date.now() > deadline) {\n      throw new Error(`journal conformance: ${paths.journal} never appeared`)\n    }\n    await sleep(100)\n  }\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms))\n}\n\n/**\n * An absolute path inside the sandbox that no other case, suite, or machine will\n * touch.\n *\n * Every character is in `[A-Za-z0-9./-]`, so these interpolate into the shell\n * commands below as a single word without quoting. `/tmp` and not the workspace:\n * on local-process a shell redirect reaches the host's real `/tmp` while\n * `handle.fs` resolves under the sandbox root (see rule 3 in `../journal.ts`),\n * and everything here is written AND read through the shell so the two never have\n * to agree.\n */\nfunction noncePath(label: string): string {\n  return `/tmp/tanstack-journal-conformance-${label}-${randomUUID()}`\n}\n\n/** Iteration cap on the kill probe's loop, so nothing can outlive the suite. */\nconst PROBE_MAX_TICKS = 600\n\n/**\n * Bound on a journal read, so a reader that delivers nothing FAILS instead of\n * parking CI.\n *\n * Never an assertion, and deliberately far above anything a healthy read needs\n * (measured: 10–18s for the follow cases on both providers). Each case that uses\n * it proves its property some other way — a causal handshake, or\n * `backstop.aborted` — so this number can be raised freely and must never be the\n * thing a case is tuned against.\n */\nconst READ_BACKSTOP_MS = 90_000\n\n/**\n * How long to let an asynchronous kill land before the quiet window opens.\n *\n * A kill is asynchronous on every provider here — Docker signals through a\n * second `exec`, local-process signals a process group and lets the OS reap — so\n * one more heartbeat tick immediately after `kill()` resolves is not a survivor.\n */\nconst KILL_SETTLE_MS = 5_000\n\n/**\n * The quiet window: how long the heartbeat must stay frozen.\n *\n * This is NOT a load-sensitive bound, and the asymmetry is the point. A dead\n * process can never write again, so a slow or busy machine can only make this\n * window MORE reliable, never less — unlike a \"must happen within Nms\" ceiling,\n * which fails on load. Only a live survivor can end this window, and a live\n * survivor writes once a second.\n */\nconst HEARTBEAT_QUIET_MS = 6_000\n\n/**\n * Byte count of `path`, according to the SANDBOX'S OWN shell, or `null` when it\n * cannot be read.\n *\n * `wc -c` through the shell, never `handle.fs`: on local-process the two resolve\n * `/tmp` differently (rule 3), so an `fs` probe would answer about a file the\n * sandbox never wrote and the growth below would look frozen from the first\n * sample — a vacuous pass. Parsed strictly rather than coerced, so a shell\n * diagnostic cannot become `NaN` and compare unequal to itself.\n */\nasync function fileSize(\n  handle: SandboxHandle,\n  path: string,\n): Promise<number | null> {\n  const probe = await handle.process.exec(`wc -c < ${path} 2>/dev/null`)\n  const text = probe.stdout.trim()\n  return /^\\d+$/.test(text) ? Number(text) : null\n}\n\n/**\n * Wait until `path` has grown to at least `bytes`, i.e. the probe process is\n * provably DOING WORK inside the sandbox, and answer whether it got there.\n *\n * Returning the observation rather than throwing keeps the verdict inside the\n * case's own `expect`: this is the \"before\" half of the assertion, and it is what\n * makes the \"after\" half a live detector instead of a formality.\n */\nasync function waitForTicks(\n  handle: SandboxHandle,\n  path: string,\n  bytes: number,\n): Promise<boolean> {\n  const deadline = Date.now() + 30_000\n  for (;;) {\n    const size = await fileSize(handle, path)\n    if (size !== null && size >= bytes) return true\n    if (Date.now() > deadline) return false\n    // Matched to the heartbeat's own 1s period on purpose. Every poll is a\n    // provider round-trip, so a 250ms interval spent three of them per tick it\n    // could not possibly observe — pure pressure on the very `exec` path the rest\n    // of the case depends on.\n    await sleep(1_000)\n  }\n}\n\n/**\n * Assert `createHandle` satisfies the journal conformance contract. Each `it`\n * gets a fresh sandbox via `createHandle`/`dispose`, so implementations may\n * share process state across calls without cross-test bleed only if\n * `createHandle` returns an isolated sandbox.\n */\nexport function runJournalConformance(config: JournalConformanceConfig): void {\n  describe(`journal conformance — ${config.name}`, () => {\n    if (config.unsupported) {\n      it.skip(`unsupported: ${config.unsupported.reason}`, () => {\n        expect(true).toBe(true)\n      })\n      return\n    }\n\n    it(\n      \"redirects a command's stdout into the journal and appends the exit sentinel\",\n      async () => {\n        const { handle, dispose } = await config.createHandle()\n        try {\n          // Checked HERE, in a case that always runs, because\n          // `followUnsupported` gates the two follow cases below: a declaration\n          // that does not match the live handle must fail the suite rather than\n          // remove coverage from it. This is the only place a `poll` declaration\n          // can be caught, since the cases it skips never execute.\n          expectDeclaredStrategy(handle, config)\n          const paths = journalPaths(`conf-${Date.now()}`)\n          const command = journaledCommand(\n            `printf '{\"a\":1}\\\\n{\"b\":2}\\\\n'`,\n            paths,\n          )\n          const proc = await handle.process.spawn(command)\n          expect(await proc.wait()).toBe(0)\n\n          const read = await handle.process.exec(journalReadCommand(paths, 0))\n          const text = decodeJournalRead(read.stdout)\n          expect(text).toBe(`{\"a\":1}\\n{\"b\":2}\\n${exitSentinelLine(paths, 0)}\\n`)\n        } finally {\n          await dispose()\n        }\n      },\n      CASE_TIMEOUT_MS,\n    )\n\n    it(\n      \"records the agent's non-zero exit in the sentinel\",\n      async () => {\n        const { handle, dispose } = await config.createHandle()\n        try {\n          const paths = journalPaths(`conf-exit-${Date.now()}`)\n          const proc = await handle.process.spawn(\n            journaledCommand('exit 7', paths),\n          )\n          await proc.wait()\n          const read = await handle.process.exec(journalReadCommand(paths, 0))\n          const text = decodeJournalRead(read.stdout)\n          expect(text).toBe(`${exitSentinelLine(paths, 7)}\\n`)\n        } finally {\n          await dispose()\n        }\n      },\n      CASE_TIMEOUT_MS,\n    )\n\n    it(\n      \"keeps the agent's stderr out of the journal\",\n      async () => {\n        const { handle, dispose } = await config.createHandle()\n        try {\n          const paths = journalPaths(`conf-err-${Date.now()}`)\n          const proc = await handle.process.spawn(\n            journaledCommand(\n              `printf '{\"a\":1}\\\\n'; printf 'a warning\\\\n' 1>&2`,\n              paths,\n            ),\n          )\n          await proc.wait()\n          const read = await handle.process.exec(journalReadCommand(paths, 0))\n          const text = decodeJournalRead(read.stdout)\n          expect(text).toBe(`{\"a\":1}\\n${exitSentinelLine(paths, 0)}\\n`)\n          expect(text).not.toContain('a warning')\n        } finally {\n          await dispose()\n        }\n      },\n      CASE_TIMEOUT_MS,\n    )\n\n    it(\n      'reads incrementally from a byte offset with absolute positions',\n      async () => {\n        const { handle, dispose } = await config.createHandle()\n        try {\n          const paths = journalPaths(`conf-seek-${Date.now()}`)\n          const proc = await handle.process.spawn(\n            journaledCommand(`printf '{\"a\":1}\\\\n{\"b\":2}\\\\n'`, paths),\n          )\n          await proc.wait()\n\n          const all = []\n          for await (const line of readJournal(handle, {\n            paths,\n            fromByte: 0,\n            strategy: 'poll',\n            pollIntervalMs: 0,\n            // Not an assertion — see {@link READ_BACKSTOP_MS}. This was\n            // `AbortSignal.timeout(5_000)`, and it is a POLL read, so it costs one\n            // provider round-trip per line: measured going red on a saturated\n            // Docker daemon where a single `exec` took ~20s, while the lines it\n            // asserts were perfectly correct.\n            signal: AbortSignal.timeout(READ_BACKSTOP_MS),\n          })) {\n            all.push(line)\n            if (all.length === 3) break\n          }\n          expect(all.map((l) => l.line)).toEqual([\n            '{\"a\":1}',\n            '{\"b\":2}',\n            exitSentinelLine(paths, 0),\n          ])\n\n          const resumed = []\n          for await (const line of readJournal(handle, {\n            paths,\n            fromByte: all[0]?.endPosition ?? 0,\n            strategy: 'poll',\n            pollIntervalMs: 0,\n            signal: AbortSignal.timeout(READ_BACKSTOP_MS),\n          })) {\n            resumed.push(line)\n            if (resumed.length === 2) break\n          }\n          expect(resumed.map((l) => l.line)).toEqual([\n            '{\"b\":2}',\n            exitSentinelLine(paths, 0),\n          ])\n          expect(resumed[0]?.endPosition).toBe(all[1]?.endPosition)\n        } finally {\n          await dispose()\n        }\n      },\n      CASE_TIMEOUT_MS,\n    )\n\n    // This case is the reason `journalFollowCommand` pipes into nothing.\n    // `tail -f journal | base64` delivers ZERO bytes while the agent is still\n    // running — measured on GNU coreutils 8.32 `base64` and on busybox 1.36.1\n    // `base64` in Alpine — because the encoder buffers its stdout until its\n    // stdin closes, which only happens when the reader kills `tail`.\n    //\n    // INCREMENTAL, NOT MERELY EVENTUAL, AND PROVED CAUSALLY RATHER THAN BY A\n    // STOPWATCH. The agent writes its first line and then BLOCKS on a gate file\n    // that only this reader can create, and it creates it only on receiving that\n    // first line. So the agent cannot reach its second line until the first was\n    // delivered — receiving `{\"b\":2}` at all IS the proof of incremental\n    // delivery, and the `toEqual` below is the whole assertion. A buffering\n    // filter reintroduced onto the follow path deadlocks instead: nothing is\n    // delivered, the gate is never created, the agent never writes its second\n    // line, the read ends on its signal and `seen` is empty.\n    //\n    // This replaced `expect(firstLineMs).toBeLessThan(3_000)`, which measured\n    // MACHINE LOAD as much as behavior: it was observed failing in whole-suite\n    // fleet runs while passing 5/5 in isolation, because one `exec`/`spawn` is a\n    // provider round-trip whose latency this suite does not control (a\n    // `docker exec` on a loaded daemon has been measured at 9.6s). Same instinct\n    // as `takeover-conformance.ts`'s `countingExec`: anchor on the property, not\n    // on the clock. A bound that goes red on a busy machine teaches people to\n    // ignore the suite. Do NOT \"fix\" a failure here by widening a window —\n    // there is no window left to widen.\n    itFollows(\n      config,\n      'follows a journal that is still being written, delivering each line before the next is produced',\n      async () => {\n        // Every assertion below sits after an `await`, so a case that threw its way\n        // out of the loop early would report an unrelated failure; this one reports\n        // \"nothing was asserted\", which is the failure this case used to HIDE.\n        expect.hasAssertions()\n        const { handle, dispose } = await config.createHandle()\n        const gate = noncePath('follow-gate')\n        try {\n          expectDeclaredStrategy(handle, config)\n          const paths = journalPaths(`conf-follow-${Date.now()}`)\n          // The wait is bounded in the SANDBOX too, and on timeout it emits a\n          // line that names what went wrong instead of the expected one — so a\n          // gate that never arrives fails the `toEqual` with `{\"gate\":\"never\"}`\n          // rather than eventually satisfying it. 30 ticks so that diagnostic\n          // lands INSIDE `CASE_TIMEOUT_MS`; a longer cap would just time the case\n          // out and lose the message.\n          const agentCommand =\n            `printf '{\"a\":1}\\\\n'; ` +\n            `i=0; while [ ! -f ${gate} ]; do ` +\n            `i=$((i+1)); ` +\n            `if [ $i -gt 30 ]; then printf '{\"gate\":\"never\"}\\\\n'; break; fi; ` +\n            `sleep 1; done; ` +\n            `printf '{\"b\":2}\\\\n'`\n          // Not awaited anywhere: reading the `__exit` sentinel below IS the\n          // proof it finished. (`SpawnHandle.wait()` is not safe to call after the\n          // fact on every provider — local-process registers a `close` listener at\n          // call time, so a `wait()` issued after the process already exited never\n          // resolves.)\n          void handle.process.spawn(journaledCommand(agentCommand, paths))\n          // `tail` on a file that does not exist yet exits immediately, and the\n          // agent's spawn and the reader's spawn race. Waiting removes that race\n          // WITHOUT touching the property under test: with a buffering filter on\n          // the follow path the journal still exists, `tail` still runs, and the\n          // reader still receives nothing.\n          await waitForJournal(handle, paths)\n          // The premise, pinned: the gate is genuinely absent, so the agent\n          // really is blocked and its second line really is downstream of this\n          // reader. Without this a pre-existing gate path would make the case\n          // pass without following anything.\n          expect(\n            (await handle.process.exec(`test -e ${gate}`)).exitCode,\n          ).not.toBe(0)\n          const seen: Array<string> = []\n          for await (const line of readJournal(handle, {\n            paths,\n            fromByte: 0,\n            // Not the assertion — see {@link READ_BACKSTOP_MS}. The gate's own\n            // 30-tick cap fires well inside it, so the `{\"gate\":\"never\"}`\n            // diagnostic still reaches this reader.\n            signal: AbortSignal.timeout(READ_BACKSTOP_MS),\n          })) {\n            seen.push(line.line)\n            // Releases the agent, and only from inside the stream. `touch` is\n            // not portable to every BusyBox build with these flags, so this\n            // creates the file with a redirect, through the shell — `handle.fs`\n            // would write a path the agent's `test -f` cannot see on\n            // local-process (rule 3).\n            if (seen.length === 1) {\n              await handle.process.exec(`: >> ${gate}`)\n            }\n            if (seen.length === 3) break\n          }\n          expect(seen).toEqual([\n            '{\"a\":1}',\n            '{\"b\":2}',\n            exitSentinelLine(paths, 0),\n          ])\n        } finally {\n          // Unblocks the agent even when the case failed, so no `while` loop\n          // outlives it on a provider whose sandbox teardown does not reap.\n          await handle.process.exec(`: >> ${gate}`).catch(() => undefined)\n          await dispose()\n        }\n      },\n    )\n\n    // The follow read must obey its own AbortSignal rather than waiting for the\n    // provider's `kill` to close the stream — a provider whose kill misses a\n    // grandchild would otherwise hang the reader past its deadline.\n    itFollows(\n      config,\n      'stops a follow read when its signal aborts, without a consumer break',\n      async () => {\n        expect.hasAssertions()\n        const { handle, dispose } = await config.createHandle()\n        try {\n          expectDeclaredStrategy(handle, config)\n          const paths = journalPaths(`conf-abort-${Date.now()}`)\n          // Outlives the read on purpose: the journal must still be open, and the\n          // agent still running, when the signal fires.\n          const agent = await handle.process.spawn(\n            journaledCommand(`printf '{\"a\":1}\\\\n'; sleep 30`, paths),\n          )\n          try {\n            await waitForJournal(handle, paths)\n            const seen: Array<string> = []\n            // The signal fires ON the first line rather than on a stopwatch. The\n            // old form was `AbortSignal.timeout(3_000)`, which asked the provider\n            // to spawn a `tail` AND deliver a line inside 3s — measured failing on\n            // a loaded Windows machine (git-bash `sh` + `tail`, `seen` came back\n            // empty) while passing in isolation, the same load-sensitivity as the\n            // `firstLineMs` bound the case above replaced. Aborting from inside the\n            // stream keeps the property exactly: the agent is still running, the\n            // journal is still open, and the reader must stop because its SIGNAL\n            // said so.\n            const stop = new AbortController()\n            // A backstop, so a reader that delivers nothing fails instead of\n            // parking CI. It is not the assertion — `backstopped` below proves it\n            // was not what ended the loop.\n            const backstop = AbortSignal.timeout(READ_BACKSTOP_MS)\n            for await (const line of readJournal(handle, {\n              paths,\n              fromByte: 0,\n              signal: AbortSignal.any([stop.signal, backstop]),\n            })) {\n              seen.push(line.line)\n              // No `break`, ever: the pre-fix reader honored a consumer break but\n              // rode straight past its signal, so a `break` here would pass it.\n              stop.abort()\n            }\n            expect({ seen, backstopped: backstop.aborted }).toEqual({\n              seen: ['{\"a\":1}'],\n              // The loop ended, and NOT because the backstop timed out — which is\n              // the causal witness that \"the signal ends it at all\", with no clock\n              // in the assertion.\n              backstopped: false,\n            })\n          } finally {\n            await agent.kill()\n          }\n        } finally {\n          await dispose()\n        }\n      },\n    )\n\n    // THE CAPABILITY, not the reader's reaction to it.\n    //\n    // `killableProcesses` is the flag `journalReadStrategy` reads to choose\n    // `'follow'`, and the promise it makes is about the SANDBOX-SIDE process:\n    // `tail -f` may be spawned because the caller can reclaim it. Every other\n    // case in this file asserts only that the READER stopped, which\n    // `untilAborted` delivers unilaterally by abandoning the pipe — so all of\n    // them pass a provider whose `kill()` is `() => Promise.resolve()`. This one\n    // asks the sandbox itself.\n    //\n    // WHAT IT SPAWNS, AND WHY THAT SHAPE. The heartbeat loop is BACKGROUNDED\n    // (`( … ) & wait`), so the long-lived work is a grandchild of the wrapper\n    // shell rather than the wrapper itself. That is deliberate: it is the shape\n    // of the defects this bites on. `sh -c '<cmd>'` does not reliably exec its\n    // command, so a provider that signals only the wrapper leaves the real work\n    // running — measured on local-process POSIX, where `sh -c 'sleep 987654321'`\n    // survived `child.kill('SIGKILL')` — and Docker's `kill -SIG -\"$pid\"` group\n    // form exists precisely so a backgrounded grandchild is not orphaned. A probe\n    // that `exec`ed itself into the wrapper would be reclaimed by the correct and\n    // the broken implementation alike, and prove nothing.\n    //\n    // WHY IT MEASURES WORK AND NOT EXISTENCE. `kill -0 <pid>` was the obvious\n    // probe and it is WRONG here, measured: alpine's PID 1 under this provider is\n    // `tail -f /dev/null`, which never `wait()`s, so a correctly killed child\n    // lingers as an unreaped `[sleep]` forever and `kill -0` answers 0 for it.\n    // That fails a healthy provider. `ps` is no better and is why the identity\n    // here is a file rather than a nonce in the command line: on local-process\n    // under Windows the shell is git-bash, whose MSYS `ps` prints only the process\n    // IMAGE PATH (`/usr/bin/sleep`) and never argv — verified, `ps`, `ps -ef` and\n    // `ps -W` all omit it — so `ps | grep <nonce>` would match nothing there, and\n    // \"no match\" is indistinguishable from \"it is gone\": a vacuous pass on\n    // exactly the provider whose kill was broken. (`pgrep` is worse: BusyBox has\n    // it, git-bash does not.) A host-side census is not portable at all — Docker's\n    // container-side process has no host process, and a remote provider has none\n    // either.\n    //\n    // So the probe is a heartbeat: the process appends one byte per second to a\n    // nonce-named file, through the shell. Only a RUNNING process can do that. A\n    // zombie cannot, a killed process cannot, and no other test on the machine\n    // writes to that path.\n    //\n    // BOTH OBSERVATIONS ARE ASSERTED, in one object, and the \"before\" one is not\n    // decoration: a frozen-file check passes trivially against a file that never\n    // grew at all, which is the exact failure shape this whole review keeps\n    // turning up. `tickedBeforeKill` is what makes the detector live.\n    itFollows(\n      config,\n      \"kills the sandbox-side process, not just the host's view of it\",\n      async () => {\n        expect.hasAssertions()\n        const { handle, dispose } = await config.createHandle()\n        const heartbeat = noncePath('killprobe-hb')\n        const stop = noncePath('killprobe-stop')\n        try {\n          expectDeclaredStrategy(handle, config)\n          // The `stop` file is how a SURVIVOR is reclaimed in teardown, since a\n          // provider that fails this case cannot be trusted to kill it and the\n          // suite must not leak a spinner either way. The tick cap is the second\n          // net, for a teardown that never ran at all.\n          const probe = await handle.process.spawn(\n            `( i=0; while [ ! -f ${stop} ] && [ $i -lt ${PROBE_MAX_TICKS} ]; do ` +\n              `printf '.' >> ${heartbeat}; i=$((i+1)); sleep 1; ` +\n              `done ) & wait`,\n          )\n          // Two bytes, not one: one byte is \"it started\", two is \"it is looping\".\n          const tickedBeforeKill = await waitForTicks(handle, heartbeat, 2)\n\n          await probe.kill()\n          await sleep(KILL_SETTLE_MS)\n          const atSettle = await fileSize(handle, heartbeat)\n          await sleep(HEARTBEAT_QUIET_MS)\n          const afterQuietWindow = await fileSize(handle, heartbeat)\n\n          expect({\n            tickedBeforeKill,\n            // An UNREADABLE sample counts as a tick, i.e. fails: the file was\n            // provably readable a moment ago (`tickedBeforeKill`), so `null` here\n            // means the probe itself broke and the quiet window proves nothing.\n            // Two `null`s compare equal, which would otherwise read as \"frozen\".\n            tickedAfterKill:\n              atSettle === null ||\n              afterQuietWindow === null ||\n              atSettle !== afterQuietWindow,\n          }).toEqual({ tickedBeforeKill: true, tickedAfterKill: false })\n        } finally {\n          await handle.process\n            .exec(`: >> ${stop}; rm -f ${heartbeat}`)\n            .catch(() => undefined)\n          await dispose()\n        }\n      },\n    )\n  })\n}\n"],"mappings":"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"}