@namzu/sandbox 14.0.0 → 16.0.0

package/src/testing/sandbox-conformance.ts

@@ -28,10 +28,10 @@
  * Contract behaviour only — never a backend-specific object, field or
  * error string. A case never inspects `sandbox.constructor.name`, never
  * matches an error message, and never assumes a particular
- * {@link SandboxEnvironment}. `openTerminal` and `openTcpConnection` are
- * OPTIONAL on {@link Sandbox} by the SDK's own contract — a backend that
- * cannot honour one must omit it rather than accept and ignore it — so a
- * factory whose sandbox omits either capability skips that section rather
+ * {@link SandboxEnvironment}. `openTerminal`, `openTcpConnection` and
+ * `walkFiles` are OPTIONAL on {@link Sandbox} by the SDK's own contract — a
+ * backend that cannot honour one must omit it rather than accept and ignore
+ * it — so a factory whose sandbox omits any of them skips that section rather
  * than failing it. Every other section runs against every sandbox.
  *
  * ## Where it runs today
@@ -61,12 +61,16 @@
  * ```
  */
 
+import { createHash } from 'node:crypto'
 import type {
 	OpenTerminalOptions,
 	Sandbox,
+	SandboxExecResult,
 	SandboxTcpConnectOptions,
+	SandboxWalkFilesOptions,
 	TerminalSession,
 } from '@namzu/sdk'
+
 import type {
 	ConformanceAssertion,
 	ConformanceDescribe,
@@ -79,8 +83,24 @@ import type {
  * label so a failure is legible on sight as "the sandbox contract", the
  * same convention `PROVIDER_DRIVER_CONTRACT_VERSION` uses — raised only
  * when a case is ADDED or TIGHTENED, never on a rewording.
+ *
+ * 3 is the `walkFiles`, concurrent-`exec` and `exec`-timeout sections, none
+ * of which needs a guest feature that did not already exist.
+ *
+ * **The ranged and streamed read cases deliberately did NOT raise it
+ * further.** Raising it for them would assert that every backend this suite
+ * runs against implements them, and one does not: the Firecracker tier's
+ * guest lives in a golden rootfs image that is NOT built from this
+ * repository — nothing here builds one, `packages/sandbox/package.json#files`
+ * does not even ship `agent/`, and `README.md` documents the image as
+ * something the operator builds and canaries on their own schedule. A
+ * deployment therefore runs whatever agent its last image build baked in,
+ * and a contract version that claimed otherwise would be a claim about
+ * images this repository cannot see. Those two cases are gated on
+ * {@link SandboxConformanceOptions.supportsRangedAndStreamedReads}
+ * instead, and skip by name when a backend does not declare them.
  */
-export const SANDBOX_CONTRACT_VERSION = 1
+export const SANDBOX_CONTRACT_VERSION = 3
 
 /** A sandbox to test, plus whatever teardown building it required. */
 export interface SandboxConformanceHandle {
@@ -134,6 +154,24 @@ export interface SandboxConformanceOptions {
 	 * {@link GuestListenerCommand.parsePort} expects.
 	 */
 	readonly guestListenerCommand?: () => GuestListenerCommand
+	/**
+	 * Whether this backend's guest honours `readFile`'s `offset`/`length`
+	 * and implements {@link Sandbox.readFileStream}.
+	 *
+	 * **Defaults to `false`, and the default is the honest one.** These
+	 * cases are not in {@link SANDBOX_CONTRACT_VERSION} — see the comment
+	 * on that constant for why — so the suite cannot assume a backend has
+	 * them. A backend whose guest is built from this repository sets it
+	 * `true`; every other backend gets the cases as named skips, counted in
+	 * the runner's own totals and titled with the reason, rather than as
+	 * failures for a contract it never agreed to.
+	 *
+	 * A backend that sets this `true` while its guest ignores
+	 * `offset`/`length` FAILS, and that is the point: returning the whole
+	 * file where a slice was asked for is a wrong answer, not a missing
+	 * capability.
+	 */
+	readonly supportsRangedAndStreamedReads?: boolean
 }
 
 /** Assert `call()` rejects. The contract cares that admission was refused, never the message. */
@@ -168,6 +206,36 @@ function sleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms))
 }
 
+/**
+ * `size` bytes of deterministic pseudo-random content (xorshift32 from a
+ * fixed seed).
+ *
+ * Pseudo-random rather than a repeated byte because the large-body case
+ * below is about whether every byte survived in the right ORDER: a body of
+ * one repeated value passes a length check and a content check even if the
+ * transport shipped its pieces out of order, duplicated one, or dropped
+ * one and padded. Deterministic rather than `randomBytes` so a failure is
+ * reproducible from the size alone.
+ */
+function deterministicBytes(size: number): Buffer {
+	const out = Buffer.allocUnsafe(size)
+	let x = 0x9e3779b9
+	for (let i = 0; i < size; i += 1) {
+		x ^= x << 13
+		x >>>= 0
+		x ^= x >> 17
+		x ^= x << 5
+		x >>>= 0
+		out[i] = x & 0xff
+	}
+	return out
+}
+
+/** `sha256` of a buffer, hex — a byte-exact comparison that prints short. */
+function digest(buffer: Buffer): string {
+	return createHash('sha256').update(buffer).digest('hex')
+}
+
 /**
  * A program the `openTcpConnection` positive case can start INSIDE a guest
  * through {@link Sandbox.openTerminal}, and dial back into over
@@ -311,6 +379,7 @@ export function defineSandboxConformance(options: SandboxConformanceOptions): vo
 	const label = options.label ?? 'sandbox'
 	const guestCanRunNode = options.guestCanRunNode ?? true
 	const guestListenerCommand = options.guestListenerCommand ?? nodeGuestListener
+	const supportsRangedAndStreamedReads = options.supportsRangedAndStreamedReads ?? false
 
 	/**
 	 * Run `body` against a sandbox built for this case alone.
@@ -332,6 +401,24 @@ export function defineSandboxConformance(options: SandboxConformanceOptions): vo
 		}
 	}
 
+	/**
+	 * A case that needs {@link SandboxConformanceOptions.supportsRangedAndStreamedReads}.
+	 *
+	 * The skip is deliberately visible: the reason is in the case's TITLE and
+	 * the case still runs and is counted in the runner's totals, which is what
+	 * {@link SANDBOX_CONTRACT_VERSION}'s note asks for. What it does not do is
+	 * build a sandbox to skip inside — `withSandbox` is applied only on the
+	 * branch that uses one, so a backend without the capability pays nothing
+	 * per skipped case.
+	 */
+	const rangedReadCase = (
+		title: string,
+		body: (sandbox: Sandbox) => Promise<void>,
+	): [string, () => Promise<void>] =>
+		supportsRangedAndStreamedReads
+			? [title, withSandbox(body)]
+			: [`${title} (skipped: supportsRangedAndStreamedReads is false)`, async () => {}]
+
 	describe(`${label} — sandbox contract v${SANDBOX_CONTRACT_VERSION}`, () => {
 		describe('exec', () => {
 			it(
@@ -458,6 +545,123 @@ export function defineSandboxConformance(options: SandboxConformanceOptions): vo
 					expect(read.toString('base64')).toBe(payload.toString('base64'))
 				}),
 			)
+
+			/**
+			 * A body too large to cross the wire in ONE message.
+			 *
+			 * 7 MiB is chosen against a real number rather than a round one:
+			 * a `write-file` body travels base64-encoded inside the request
+			 * envelope, so 7 MiB of content is ~9.3 MiB of frame — past the
+			 * 8 MiB ceiling the guest agent enforces on an unauthenticated
+			 * connection's first frame, which on a transport that dials
+			 * fresh per call is EVERY frame. That ceiling used to make this
+			 * case a documented refusal on the kubernetes backend while the
+			 * host-local backends served it without noticing, which is
+			 * exactly the shape of divergence a contract suite exists to
+			 * catch: `Sandbox.writeFile` promises to write a file, and a
+			 * caller seeding a repository archive into a workspace cannot
+			 * be told that the promise holds below a number nothing in the
+			 * interface names.
+			 *
+			 * Compared by digest, not by content: a mismatch here belongs in
+			 * the failure message as a short string, and 7 MiB of base64
+			 * does not.
+			 */
+			it(
+				'round-trips a body larger than one wire frame',
+				withSandbox(async (sandbox) => {
+					const payload = deterministicBytes(7 * 1024 * 1024)
+					await sandbox.writeFile('conformance-large/archive.bin', payload)
+					const read = await sandbox.readFile('conformance-large/archive.bin')
+					expect(read.length).toBe(payload.length)
+					expect(digest(read)).toBe(digest(payload))
+				}),
+			)
+
+			/**
+			 * A read ABOVE the ceiling the case above sits below.
+			 *
+			 * 7 MiB is chosen for what the WRITE costs — 9.3 MiB of base64
+			 * envelope, past the guest's 8 MiB pre-auth frame limit — and a
+			 * reply frame is not measured against that limit at all, so that
+			 * case proves nothing about the read side. 9 MiB is above the
+			 * number on both sides of the wire, which is the only way to tell
+			 * a backend that reads a file in bounded pieces from one that
+			 * hands back a single reply and hopes.
+			 *
+			 * Skipped by NAME, and counted in the runner's totals as a case,
+			 * for a backend that has not declared the capability — see
+			 * {@link SandboxConformanceOptions.supportsRangedAndStreamedReads}
+			 * and the note on {@link SANDBOX_CONTRACT_VERSION}.
+			 */
+			it(
+				...rangedReadCase(
+					'reads a file larger than one wire frame back in bounded pieces',
+					async (sandbox) => {
+						const payload = deterministicBytes(9 * 1024 * 1024)
+						await sandbox.writeFile('conformance-large/wide.bin', payload)
+
+						const whole = await sandbox.readFile('conformance-large/wide.bin')
+						expect(whole.length).toBe(payload.length)
+						expect(digest(whole)).toBe(digest(payload))
+
+						// A backend declaring the capability must expose the stream
+						// too: the whole point is that a caller can read a file it
+						// could not hold, and `readFile` hands back one buffer.
+						const readFileStream = sandbox.readFileStream
+						if (!readFileStream) {
+							throw new Error(
+								'supportsRangedAndStreamedReads is true but this sandbox has no readFileStream. ' +
+									'A backend that honours offset/length but cannot stream must pass ' +
+									'supportsRangedAndStreamedReads: false and state why.',
+							)
+						}
+						const chunks: Buffer[] = []
+						for await (const chunk of readFileStream.call(sandbox, 'conformance-large/wide.bin')) {
+							chunks.push(Buffer.from(chunk))
+						}
+						// More than one chunk is what "bounded pieces" means; a
+						// backend yielding the whole file once satisfies the
+						// signature and none of the promise.
+						expect(chunks.length > 1).toBe(true)
+						expect(digest(Buffer.concat(chunks))).toBe(digest(payload))
+					},
+				),
+			)
+
+			/**
+			 * A slice, and the three things a slice has to get right: the
+			 * bytes, a range that runs off the end, and the fact that asking
+			 * for one must not hand back the whole file.
+			 */
+			it(
+				...rangedReadCase(
+					'reads an explicit byte range, and clips it to the end of the file',
+					async (sandbox) => {
+						const payload = deterministicBytes(64 * 1024)
+						await sandbox.writeFile('conformance-range/slice.bin', payload)
+
+						const middle = await sandbox.readFile('conformance-range/slice.bin', {
+							offset: 1_000,
+							length: 256,
+						})
+						expect(middle.length).toBe(256)
+						expect(middle.toString('base64')).toBe(
+							payload.subarray(1_000, 1_256).toString('base64'),
+						)
+
+						// Past the end returns what exists rather than failing: a
+						// caller resuming from a remembered offset cannot be made to
+						// know the answer before it asks.
+						const straddling = await sandbox.readFile('conformance-range/slice.bin', {
+							offset: payload.length - 10,
+							length: 500,
+						})
+						expect(straddling.length).toBe(10)
+						expect(straddling.toString('base64')).toBe(payload.subarray(-10).toString('base64'))
+					},
+				),
+			)
 		})
 
 		describe('listFiles', () => {
@@ -658,6 +862,337 @@ export function defineSandboxConformance(options: SandboxConformanceOptions): vo
 				}),
 			)
 		})
+
+		/**
+		 * Optional on {@link Sandbox} by the SDK's own contract, and the same
+		 * documented skip as `openTerminal`: a factory whose sandbox omits
+		 * `walkFiles` passes every case below vacuously. It is not a small
+		 * omission to make, though — the SDK's `glob` and `grep` builtins
+		 * REFUSE a sandbox that has no `walkFiles`, so a host that registers
+		 * the default builtin set and moves to such a backend loses both
+		 * tools with no change on its own side.
+		 *
+		 * What is asserted here is the contract's own wording: absolute paths,
+		 * regular files only, symlinks not followed, the bounds honoured by
+		 * whoever does the walking, and — the one that is easy to get wrong —
+		 * an exhausted examined-entry budget raising an error carrying
+		 * `ERR_FILE_WALK_LIMIT` rather than handing back a short list a caller
+		 * would read as complete.
+		 */
+		describe('walkFiles', () => {
+			/**
+			 * Every path this walk yielded, sorted.
+			 *
+			 * `walkFiles` is called through `.call(sandbox, …)` for the same
+			 * reason `openTerminal` is above: it may be an ordinary method
+			 * relying on `this`, and detaching it would drop that binding.
+			 */
+			const walkPaths = async (
+				sandbox: Sandbox,
+				root: string,
+				options: SandboxWalkFilesOptions,
+			): Promise<string[]> => {
+				const walk = sandbox.walkFiles
+				if (!walk) throw new Error('unreachable: every case guards on walkFiles first')
+				const paths: string[] = []
+				for await (const entry of walk.call(sandbox, root, options)) paths.push(entry.path)
+				return paths.sort()
+			}
+
+			it(
+				'yields written files as absolute paths with their sizes, bounded by maxEntries',
+				withSandbox(async (sandbox) => {
+					if (!sandbox.walkFiles) return
+					await sandbox.writeFile('conformance-walk/a.txt', '1')
+					await sandbox.writeFile('conformance-walk/b.txt', '22')
+					await sandbox.writeFile('conformance-walk/c.txt', '333')
+					const dir = `${sandbox.rootDir}/conformance-walk`
+
+					const sizes = new Map<string, number>()
+					const walk = sandbox.walkFiles
+					for await (const entry of walk.call(sandbox, dir, { maxEntries: 10 })) {
+						sizes.set(entry.path, entry.size)
+					}
+					expect([...sizes.keys()].sort()).toEqual([`${dir}/a.txt`, `${dir}/b.txt`, `${dir}/c.txt`])
+					expect(sizes.get(`${dir}/c.txt`)).toBe(3)
+
+					// The bound is on what is EMITTED, so a walk asked for two
+					// entries yields two and stops — it does not yield three and
+					// leave the caller to discard one.
+					expect((await walkPaths(sandbox, dir, { maxEntries: 2 })).length).toBe(2)
+				}),
+			)
+
+			it(
+				'bounds the descent with maxDepth, counting direct children as depth 1',
+				withSandbox(async (sandbox) => {
+					if (!sandbox.walkFiles) return
+					await sandbox.writeFile('conformance-depth/top.txt', 'top')
+					await sandbox.writeFile('conformance-depth/one/mid.txt', 'mid')
+					await sandbox.writeFile('conformance-depth/one/two/deep.txt', 'deep')
+					const dir = `${sandbox.rootDir}/conformance-depth`
+
+					expect(await walkPaths(sandbox, dir, { maxEntries: 50, maxDepth: 1 })).toEqual([
+						`${dir}/top.txt`,
+					])
+					expect(await walkPaths(sandbox, dir, { maxEntries: 50, maxDepth: 2 })).toEqual([
+						`${dir}/one/mid.txt`,
+						`${dir}/top.txt`,
+					])
+				}),
+			)
+
+			it(
+				'keeps hidden names out of a wildcard unless includeHidden is set',
+				withSandbox(async (sandbox) => {
+					if (!sandbox.walkFiles) return
+					await sandbox.writeFile('conformance-hidden/visible.txt', 'v')
+					await sandbox.writeFile('conformance-hidden/.secret.txt', 'h')
+					const dir = `${sandbox.rootDir}/conformance-hidden`
+
+					expect(await walkPaths(sandbox, dir, { maxEntries: 50 })).toEqual([`${dir}/visible.txt`])
+					expect(await walkPaths(sandbox, dir, { maxEntries: 50, includeHidden: true })).toEqual([
+						`${dir}/.secret.txt`,
+						`${dir}/visible.txt`,
+					])
+				}),
+			)
+
+			it(
+				'reports a root that does not exist as an empty walk rather than failing',
+				withSandbox(async (sandbox) => {
+					if (!sandbox.walkFiles) return
+					const paths = await walkPaths(sandbox, `${sandbox.rootDir}/conformance-never-walked`, {
+						maxEntries: 10,
+					})
+					expect(paths.length).toBe(0)
+				}),
+			)
+
+			it(
+				'does not follow symbolic links, to a file or to a directory',
+				withSandbox(async (sandbox) => {
+					if (!sandbox.walkFiles) return
+					await sandbox.writeFile('conformance-links/real/target.txt', 'target')
+					const dir = `${sandbox.rootDir}/conformance-links`
+					const linked = await sandbox.exec('/bin/sh', [
+						'-c',
+						`cd ${dir} && ln -s real/target.txt link-to-file.txt && ln -s real link-to-dir`,
+					])
+					// Never a silent skip. A runtime discovery cannot travel
+					// through this suite's one skip channel — the case's own
+					// title, decided synchronously from the options — so a guest
+					// that cannot build the fixture says so out loud instead of
+					// passing a case that asserted nothing.
+					if (linked.exitCode !== 0) {
+						throw new Error(
+							`walkFiles conformance: this case builds its fixture with POSIX \`ln -s\`, and the guest's shell answered ${linked.exitCode}: ${linked.stderr.trim()}. A guest image that cannot make a symbolic link is not held to "symlinks are not followed" by asserting nothing — ship \`ln\`, or raise the gap so the suite grows a declared skip rather than a quiet one.`,
+						)
+					}
+
+					// The real file, once, under its real path. Following the
+					// directory link would have reported it again through
+					// `link-to-dir/target.txt`, and the file link again as itself.
+					expect(await walkPaths(sandbox, dir, { maxEntries: 50 })).toEqual([
+						`${dir}/real/target.txt`,
+					])
+				}),
+			)
+
+			it(
+				'raises ERR_FILE_WALK_LIMIT when the examined-entry budget runs out',
+				withSandbox(async (sandbox) => {
+					if (!sandbox.walkFiles) return
+					for (let index = 0; index < 12; index += 1) {
+						await sandbox.writeFile(`conformance-budget/f${index}.txt`, 'x')
+					}
+					// An incomplete search is an ERROR carrying a code, never a
+					// short list: a caller handed six of twelve files with no
+					// signal reads it as "that is all there is".
+					let code: unknown
+					try {
+						await walkPaths(sandbox, `${sandbox.rootDir}/conformance-budget`, {
+							maxEntries: 50,
+							maxVisitedEntries: 4,
+						})
+					} catch (error) {
+						code = (error as { code?: unknown }).code
+					}
+					expect(code).toBe('ERR_FILE_WALK_LIMIT')
+				}),
+			)
+
+			it(
+				'refuses a walk once the sandbox has been destroyed',
+				withSandbox(async (sandbox) => {
+					if (!sandbox.walkFiles) return
+					const root = sandbox.rootDir
+					await sandbox.destroy()
+					// Consumed, not merely constructed: an async generator runs
+					// nothing until its first `next()`, so a case that built the
+					// iterator and stopped would pass against a sandbox that
+					// admits the walk happily.
+					await expectRejects(expect, () => walkPaths(sandbox, root, { maxEntries: 10 }))
+				}),
+			)
+		})
+
+		/**
+		 * One sandbox, several commands at once.
+		 *
+		 * A supervisor and its sub-agents share a sandbox, so this is the
+		 * ordinary case rather than an exotic one — and nothing in this suite
+		 * used to exercise it. A backend that serialises executions behind one
+		 * connection, or that lets two commands' output frames land in each
+		 * other's result, passes every other case here.
+		 *
+		 * Overlap is proved by the commands themselves rather than by a clock:
+		 * each appends its own mark to a shared file, waits for every other
+		 * mark to appear, and then prints the whole file back. If the backend
+		 * really ran them together every command sees every mark; if it ran
+		 * them one at a time the first one waits out its ceiling and can only
+		 * ever see its own.
+		 */
+		describe('concurrent exec', () => {
+			it(
+				'runs several commands at once on one sandbox, with no cross-talk between their results',
+				withSandbox(async (sandbox) => {
+					const count = 4
+					await sandbox.writeFile('conformance-concurrent/marks', '')
+					const marks = `${sandbox.rootDir}/conformance-concurrent/marks`
+
+					// A rendezvous rather than a sleep: each command appends its
+					// own mark and then WAITS for every other mark to appear
+					// before it prints. A backend that really runs them together
+					// settles as soon as the slowest one has started — no clock
+					// to tune, and nothing that gets tighter on a machine or a
+					// cluster where four dials cost more than a fixed pause. A
+					// backend that serialises them has the first command wait
+					// out the ceiling below and still print only its own mark,
+					// which is what the assertions catch.
+					const everyMark = Array.from({ length: count }, (_unused, index) => index).join(' ')
+					const rendezvous = (index: number): string =>
+						[
+							`printf '[%s]' '${index}' >> "${marks}"`,
+							'waited=0',
+							// 60 × 0.1 s. Only a backend that has already failed
+							// the case ever reaches it.
+							'while [ "$waited" -lt 60 ]; do',
+							`  all=$(cat "${marks}")`,
+							'  seen=1',
+							`  for mark in ${everyMark}; do`,
+							'    case "$all" in *"[$mark]"*) ;; *) seen=0 ;; esac',
+							'  done',
+							'  [ "$seen" -eq 1 ] && break',
+							'  waited=$((waited + 1))',
+							'  sleep 0.1',
+							'done',
+							`printf 'own:%s ' '${index}'`,
+							`cat "${marks}"`,
+						].join('\n')
+
+					const running = Array.from({ length: count }, (_unused, index) =>
+						sandbox.exec('/bin/sh', ['-c', rendezvous(index)]),
+					)
+					// Attached BEFORE the first assertion, and that ordering is
+					// load-bearing: an assertion that threw with four commands
+					// still in flight would leave four promises nobody is
+					// handling, and a backend that then rejects one of them
+					// takes the runner down with an unhandled rejection instead
+					// of failing this case.
+					const settled = Promise.allSettled(running)
+					// Every one of them is in flight right now.
+					expect(sandbox.status).toBe('busy')
+					const results: SandboxExecResult[] = []
+					for (const outcome of await settled) {
+						if (outcome.status === 'rejected') {
+							throw outcome.reason instanceof Error
+								? outcome.reason
+								: new Error(String(outcome.reason))
+						}
+						results.push(outcome.value)
+					}
+
+					for (let index = 0; index < count; index += 1) {
+						const result = results[index]
+						if (!result) throw new Error('unreachable: one result per started command')
+						expect(result.exitCode).toBe(0)
+						// Its OWN identity, on its own result: a backend that
+						// mixed two commands' output frames fails here.
+						expect(result.stdout).toMatch(new RegExp(`own:${index} `))
+						// And every other command's mark, which only holds if
+						// they were all admitted before any of them finished.
+						for (let other = 0; other < count; other += 1) {
+							expect(result.stdout).toMatch(new RegExp(`\\[${other}\\]`))
+						}
+					}
+					expect(sandbox.status).toBe('ready')
+				}),
+			)
+		})
+
+		/**
+		 * `SandboxExecOptions.timeout` and the `timedOut` flag it sets.
+		 *
+		 * `SandboxExecResult.timedOut` is REQUIRED on the contract, so every
+		 * backend answers it on every result — and until now nothing checked
+		 * that a backend ever sets it to `true`. A backend that accepts
+		 * `timeout` and ignores it reports a clean, unaborted-looking success
+		 * after however long the command felt like taking, which is the same
+		 * defect class the `AbortSignal` case above exists for and reads the
+		 * same way to a caller: a result that says the work is done.
+		 */
+		describe('exec timeout', () => {
+			it(
+				'reports a command that outran its timeout as timedOut, and really terminates it',
+				withSandbox(async (sandbox) => {
+					// The same shape as the abort case: the marker file is
+					// written a moment after "ready", so it only ever exists if
+					// the command was left running past its timeout. `trap ''
+					// TERM` on both the shell and the background job makes a
+					// polite TERM insufficient, exactly as a real runaway
+					// command would.
+					const marker = 'conformance-timeout-marker.txt'
+					const started = Date.now()
+					const result = await sandbox.exec(
+						'/bin/sh',
+						[
+							'-c',
+							`trap '' TERM; (trap '' TERM; sleep 1.5; printf late > ${marker}) & echo ready; wait`,
+						],
+						{ timeout: 400 },
+					)
+					const elapsed = Date.now() - started
+
+					expect(result.timedOut).toBe(true)
+					// Settled on the timeout rather than on the command
+					// finishing: the script itself waits 1.5 s, and a generous
+					// ceiling still separates the two outcomes.
+					expect(elapsed < 10_000).toBe(true)
+					// Long enough that a command left running would have written.
+					await sleep(1_800)
+					await expectRejects(expect, () => sandbox.readFile(marker))
+					// And the sandbox is still usable: a timeout is one
+					// command's outcome, not the handle's.
+					expect(sandbox.status).toBe('ready')
+					const after = await sandbox.exec('/bin/sh', ['-c', 'echo conformance-after-timeout'])
+					expect(after.exitCode).toBe(0)
+					expect(after.stdout).toMatch(/conformance-after-timeout/)
+				}),
+			)
+
+			it(
+				'leaves timedOut false for a command that finishes inside its timeout',
+				withSandbox(async (sandbox) => {
+					const result = await sandbox.exec('/bin/sh', ['-c', 'echo conformance-quick'], {
+						timeout: 30_000,
+					})
+					expect(result.timedOut).toBe(false)
+					expect(result.exitCode).toBe(0)
+					expect(result.stdout).toMatch(/conformance-quick/)
+				}),
+			)
+		})
 	})
 }