@namzu/sandbox 14.0.0 → 16.0.0

package/src/backends/kubernetes/rbac.ts

@@ -0,0 +1,192 @@
+/**
+ * The verbs a CLAIM-ONLY host issues — the pool-only path, written down once
+ * so `k8s/manifests/rbac-claimant.yaml`, and the test that compares it to both
+ * this list and the call sites behind it, cannot drift from the code they
+ * describe.
+ *
+ * A host that sets `warmPoolName` and never creates a `Sandbox` itself needs
+ * a strictly smaller grant than `k8s/manifests/rbac.yaml`'s, and the smaller
+ * it is the more it matters that it is EXACT. Two failure directions, and
+ * this constant is the one place both are decided:
+ *
+ *  - **Too few verbs** is a `403` on a flow nobody ran in review. The four
+ *    `list` verbs are the load-bearing ones, and the two a host can go a long
+ *    time without noticing are the sharp ones: `sandboxclaims: list` is the
+ *    crash-recovery read (`releaseKubernetesTaskSandboxes`) and the
+ *    pool-membership read (`readKubernetesTaskCapacity`), and `pods: list` is
+ *    `readBoundPod`'s fallback read by the bound Sandbox's own selector and
+ *    `readKubernetesTaskCapacity`'s count of Pending pods. The ACQUIRE path
+ *    never notices either is missing — `create()` never lists either
+ *    collection, so a claim is still created, bound, renewed and released
+ *    exactly as before — which makes the failure DEFERRED rather than quiet:
+ *    the `await client.request` inside each of those two functions rejects
+ *    with a `KubernetesCredentialError` (`403`), and neither call catches one,
+ *    so the first release or capacity read a host makes fails loudly, with the
+ *    refused verb and the collection's path in the error. The other two are
+ *    load-bearing SOONER: `list` is what both policy checks need, and the
+ *    ingress one runs by default before every create.
+ *  - **One verb too many** is the vulnerability class issue #500 is about: a
+ *    `sandboxes: create` grant against a namespace running a privileged
+ *    workspace template is an arbitrary privileged pod for anyone holding
+ *    it. Every verb below has a call site named against it in the list.
+ *
+ * The path this describes is the CLAIM path, not the task tier as a whole:
+ * with `warmPoolName` unset the same backend POSTs a `Sandbox` instead of a
+ * claim, reads its `SandboxTemplate` first, and patches and deletes that
+ * object — none of which is granted here, deliberately. See the manifest's
+ * own header for what it declines to grant and why.
+ *
+ * Kept honest by a test rather than by review, and the test reaches the CODE
+ * rather than only this list: `k8s/__tests__/manifests.test.ts` reads the
+ * pool-only path's own files — `index.ts`, `objects.ts`, `ingress-policy.ts`,
+ * `egress-policy.ts` — as text, resolves every literal `client.request(
+ * '<METHOD>', <path>, …)` in them to the `(apiGroup, resource, verb)` triple
+ * the builder that path goes through addresses, and FAILS on anything it
+ * cannot resolve — an unknown builder, a path it cannot follow, a builder
+ * call with anything appended to it (`podPath(ns, name) + '/log'` is the
+ * `pods/log` subresource, which RBAC authorizes separately), a name the source
+ * writes a second path to — the guard reads four spellings, wherever each is
+ * written rather than only where it opens a statement: a plain assignment
+ * (`path = …`, the one-line branch included), a compound one (`path += …`), a
+ * `for (path of …)` binding, and a destructuring target (`({ path } = …)`) — as
+ * a `const`/`let`/`var`-declared name, whose initializer is then not what a
+ * request through it sends, or as a wrapper's own path parameter, whose call
+ * sites then do not say what it sends — a path
+ * that is a parameter of a body whose call sites the scan has not been told
+ * about, a wrapper declared as such in a file the scan does not read — so a new
+ * request has to declare itself instead of escaping. WHICH files those are
+ * is not a list that can quietly stop covering the path: every `.ts` under
+ * `src/backends/kubernetes/` that reaches the client — calling
+ * `client.request(…)` itself in either spelling the scan reads, the literal
+ * one or a computed `client['request']`, or naming `listPolicies`, the one
+ * wrapper the scan knows, which takes its path as an argument; every half read
+ * on text with its comments blanked — is either scanned or declared off the
+ * path with its reason, so a file that reaches the client fails that test
+ * until someone decides which of the two it is. The triples it
+ * observes must be exactly this list, plus the four the pool-LESS branch
+ * issues and this grant declines by design. A request added to the pool-only
+ * path therefore fails that test naming the resource, the file and the line,
+ * instead of surfacing as a `403` in a host's log — and so does a rule here
+ * with no call site, which is a grant wider than the code needs.
+ *
+ * What that test still cannot see, so none of the above reads stronger than
+ * it is: the files it declares off the path — `workspace.ts`, `k8s-client.ts`,
+ * `transport.ts` — are never resolved to triples, a wrapper call site in one
+ * of them included, since call sites are read from the scanned files only; and
+ * that a claimant host never reaches `workspace.ts` is a claim about the
+ * DEPLOYMENT (`warmPoolName` set, no `Sandbox` created by that host), which
+ * nothing in this repository measures. A wrapper reached by ANOTHER name is outside that file predicate,
+ * which matches the wrapper's name and not its identity: a file importing a
+ * re-export of it, or calling a helper one level further out that calls it, is
+ * neither scanned nor required to be declared. A request whose path is a
+ * parameter of an expression-bodied arrow is likewise outside what the scan
+ * matches, and a body the scan could not register — a class method, or an
+ * object literal's shorthand method, declared INSIDE one of the bodies it
+ * reads — is attributed to the body that encloses it, so its own parameters
+ * are invisible. The assignment guard is by name in the file it resolves in,
+ * not by scope, so a BINDING it registers nowhere shadows nothing there: a
+ * destructuring parameter (`function f({ path })`) keeps its positional slot
+ * without a name this scan can match, a `catch (path)` is not read at all, and
+ * a write made to an exported binding from ANOTHER module is not in that file's
+ * text — which is also to say that an assignment to a same-named local in an
+ * unrelated function of the same file refuses the request too, a false refusal
+ * rather than an escape. A parameter carrying a DEFAULT is written with an `=`
+ * (`function f(path = …)`, `function f({ path } = {})`), so the guard reads it
+ * and refuses the request rather than resolving it — a refusal, where the bare
+ * pattern would have resolved or failed; and a destructuring pattern nested
+ * inside another (`({ a: { path } } = …)`) is read by neither spelling, which
+ * is measured green.
+ *
+ * **That list is the SHORT form, not the list.** It is carried in full in the
+ * header of `k8s/__tests__/manifests.test.ts`, which also holds two bullets
+ * this paragraph does not: `a path assembled by an operation the scan does not
+ * model`, and `the cluster` (nothing there contacts an API server, so no live
+ * `Role` is measured).
+ *
+ * Exported from the package root because the grant is a property of the
+ * backend, not of a file this package does not publish: `k8s/` is outside
+ * the `files` array, so a consumer cannot read the YAML out of `node_modules`
+ * — it can, however, compare its own applied `Role` against this.
+ */
+
+/** An RBAC verb this backend issues. No wildcard, and none is ever added. */
+export type KubernetesRbacVerb = 'create' | 'get' | 'list' | 'patch' | 'delete'
+
+/**
+ * One `rules[]` entry, in the shape RBAC itself uses — one resource per
+ * entry, which is also how the shipped manifests are written, so a rule here
+ * and a rule there compare field for field.
+ */
+export interface KubernetesRbacRule {
+	/** The `apiGroups` entry, verbatim: `''` for the core group. */
+	readonly apiGroup: string
+	readonly resource: string
+	readonly verbs: readonly KubernetesRbacVerb[]
+}
+
+/**
+ * Every verb the pool-only path issues, each pinned to its call site in
+ * `./index.ts` (and, for the policy checks, `./ingress-policy.ts` /
+ * `./egress-policy.ts`):
+ *
+ *  - `sandboxclaims` — `create` is the acquire's POST (`createPath`), `get`
+ *    the readiness poll that waits for the controller to bind one, `patch`
+ *    the lease renewal that keeps a long run's claim alive, `delete` the
+ *    release `destroy()` and a failed acquire's cleanup both send, and
+ *    `list` the two host-invoked reads named above.
+ *  - `sandboxes: get` — read for `status.selector` when the pod-by-name GET
+ *    comes back gone, which on the claim path is the ONLY way to find the
+ *    bound pod: a claim has no `podSelector` of its own to fall back on.
+ *  - `sandboxwarmpools: get` — `readKubernetesTaskCapacity` reads the
+ *    configured pool's own `status.readyReplicas`/`spec.replicas` before a
+ *    host admits more work.
+ *  - `pods` — `get` by name for the agent's bind token and, under
+ *    `agentAddress: 'pod-ip'`, its address, plus the whole-namespace `list`
+ *    that counts in-flight scale-up. The two policy checks use NO pod
+ *    subresource; the agent's protocol is a socket the guest serves, not
+ *    `pods/exec`.
+ *  - `networkpolicies` / `ciliumnetworkpolicies` — `list` is the ingress
+ *    coverage check (on by default before every create) and the egress UNION
+ *    check (on by default whenever `config.egress` is set); `get` is the
+ *    egress named-object check, also only under `config.egress`. Under
+ *    `engine: 'core'` the Cilium rule simply never matches, and a cluster
+ *    with no Cilium CRDs installed never has an object to match it.
+ */
+export const KUBERNETES_CLAIMANT_RBAC_RULES: readonly KubernetesRbacRule[] = Object.freeze([
+	// Every RULE is frozen too, not just the array and the verb lists: a
+	// frozen array still hands out mutable elements, so a plain-JS consumer
+	// could rewrite `rule.resource` and compare its live `Role` against a
+	// grant this module never declared. The test pins that (see
+	// `k8s/__tests__/manifests.test.ts`), because a `readonly` modifier is
+	// TypeScript's promise and not the runtime's.
+	Object.freeze({
+		apiGroup: 'extensions.agents.x-k8s.io',
+		resource: 'sandboxclaims',
+		verbs: Object.freeze(['create', 'get', 'list', 'patch', 'delete'] as const),
+	}),
+	Object.freeze({
+		apiGroup: 'agents.x-k8s.io',
+		resource: 'sandboxes',
+		verbs: Object.freeze(['get'] as const),
+	}),
+	Object.freeze({
+		apiGroup: 'extensions.agents.x-k8s.io',
+		resource: 'sandboxwarmpools',
+		verbs: Object.freeze(['get'] as const),
+	}),
+	Object.freeze({
+		apiGroup: '',
+		resource: 'pods',
+		verbs: Object.freeze(['get', 'list'] as const),
+	}),
+	Object.freeze({
+		apiGroup: 'networking.k8s.io',
+		resource: 'networkpolicies',
+		verbs: Object.freeze(['get', 'list'] as const),
+	}),
+	Object.freeze({
+		apiGroup: 'cilium.io',
+		resource: 'ciliumnetworkpolicies',
+		verbs: Object.freeze(['get', 'list'] as const),
+	}),
+])

package/src/backends/kubernetes/sandbox.ts

@@ -11,20 +11,36 @@
  *
  * Implemented: `exec` (through the shared {@link RemoteExecutionController},
  * so an `AbortSignal` terminates the guest process rather than abandoning
- * the wait), `writeFile`, `readFile`, `listFiles`, `openTerminal`,
- * `openTcpConnection`, `destroy`.
+ * the wait), `writeFile`, `readFile`, `listFiles`, `walkFiles`,
+ * `openTerminal`, `openTcpConnection`, `destroy`.
+ *
+ * Conditionally present, on the same contract read the other way:
+ *
+ *  - `setNetworkPolicy` — present on a TASK handle exactly when the backend
+ *    was configured with `egress.perSandbox`, which is what gives this host
+ *    an object to write (one `CiliumNetworkPolicy` per sandbox, owned by the
+ *    claim), an admission fence bounding what it may write, and the RBAC to
+ *    write it. Without that configuration there is still no per-running-pod
+ *    knob to turn, so the method is ABSENT rather than present and throwing —
+ *    the same rule, applied to a capability that now sometimes exists.
+ *    Presence follows configuration alone, never a probe of the cluster. See
+ *    `per-sandbox-policy.ts`.
+ *
+ *    A WORKSPACE handle never carries it: `KubernetesWorkspace`'s create path
+ *    builds its handle through `buildKubernetesSandbox` without this option,
+ *    because it composes no per-sandbox pod label and tracks no owner uid for
+ *    one. That is a property of the PATH and not of the configuration, so it
+ *    is not answered by omission: `createKubernetesWorkspace` refuses a
+ *    config carrying `egress.perSandbox` outright
+ *    (`KubernetesWorkspacePerSandboxEgressConfigError`, before any request)
+ *    rather than letting the option declare a capability the path never
+ *    serves — see `workspace.ts`.
  *
  * Absent on purpose, because the SDK's contract says a backend that cannot
  * honour an optional method must omit it rather than accept and ignore:
  *
- *  - `setNetworkPolicy` — egress here is a `NetworkPolicy` attached to the
- *    pool's `SandboxTemplate`. There is no per-running-pod knob to turn, and
- *    a policy accepted and not applied is worse than one never offered: the
- *    caller stops looking.
  *  - `spawnDetached` — the guest agent has no op that starts a process and
  *    returns it running. A host asking for background jobs must be told no.
- *  - `walkFiles` — not in this batch. A host that requires bounded search
- *    refuses an absent method, which is the honest answer today.
  *
  * ## Terminals are owned
  *
@@ -52,11 +68,15 @@ import type {
 	SandboxExecResult,
 	SandboxFileEntry,
 	SandboxId,
+	SandboxNetworkPolicy,
+	SandboxReadFileOptions,
 	SandboxStatus,
 	SandboxTcpConnectOptions,
 	SandboxTcpConnection,
+	SandboxWalkFilesOptions,
 	TerminalSession,
 } from '@namzu/sdk'
+import { walkFilesViaExec } from '@namzu/sdk'
 
 import { OperationDeadline } from '../readiness.js'
 import {
@@ -116,6 +136,58 @@ interface KubernetesSandboxBaseOptions {
 	readonly transport: KubernetesAgentTransport
 	/** DELETE the object this backend created. Already-gone counts as done. */
 	readonly release: (signal?: AbortSignal) => Promise<void>
+	/**
+	 * Decide what an execution whose cancellation could not be CONFIRMED
+	 * does to this sandbox — called instead of retiring it, and answering
+	 * the {@link SandboxRetirementObservation} that goes onto the error the
+	 * caller is about to receive.
+	 *
+	 * Unset (the task path, and the Firecracker tier through its own
+	 * transport) keeps the shared controller's rule verbatim: a command of
+	 * unknown state is still in that pod, the pod stops being reusable, and
+	 * the handle retires it through {@link release}. That is right for a
+	 * disposable object whose disk is scratch.
+	 *
+	 * It is wrong for an object that is not disposable. On a workspace
+	 * `release` is an `operatingMode: Suspended` patch, which makes the
+	 * controller delete the pod — so eight seconds of network loss under one
+	 * `exec()` would take every other holder's terminals, dev servers and
+	 * running commands with it, and no host-side lock can prevent it because
+	 * no caller issued it. The workspace passes a hook that keeps the pod,
+	 * diagnoses the agent and says `accepted: false` with a `reason` rather
+	 * than letting a decision that large be made from inside a failing call.
+	 *
+	 * It must not reject; one that does is reported as an unaccepted
+	 * retirement carrying its own error, so a broken hook cannot replace the
+	 * error the caller asked about.
+	 */
+	readonly onUnconfirmedCancellation?: (
+		error: RemoteCancellationUnknownError,
+	) => Promise<SandboxRetirementObservation>
+	/**
+	 * Narrow this sandbox's egress while it runs — present on the handle
+	 * EXACTLY when this is passed, and passed by the TASK acquire exactly when
+	 * `config.egress.perSandbox` is configured.
+	 *
+	 * That conditional presence is what the SDK's omit-or-throw contract
+	 * licenses and what makes it honest here: without the configuration there
+	 * is no policy object to write, no admission fence bounding what this
+	 * host may write, and no RBAC grant to write it with, so the method is
+	 * ABSENT rather than present and throwing. With it, `per-sandbox-policy.ts`
+	 * writes one `CiliumNetworkPolicy` per sandbox, owned by the object the
+	 * acquire created.
+	 *
+	 * The workspace passes NO such option whatever the config says — its
+	 * create path composes no per-sandbox pod label and tracks no owner uid
+	 * for one — and `createKubernetesWorkspace` refuses
+	 * `config.egress.perSandbox` rather than silently omitting the method the
+	 * option asks for.
+	 *
+	 * Presence depends only on configuration — never on a runtime probe of
+	 * the cluster — so a caller's capability detection cannot come out
+	 * differently depending on when it asked.
+	 */
+	readonly setNetworkPolicy?: (policy: SandboxNetworkPolicy) => Promise<void>
 }
 
 /**
@@ -163,13 +235,13 @@ function detectEnvironment(): SandboxEnvironment {
 }
 
 /**
- * What this backend hands back: the SDK contract, with the two optional
- * members it DOES implement narrowed to present, so a caller that composes
- * one — `workspace.ts` wraps this handle — does not have to re-check for a
- * method this file always defines.
+ * What this backend hands back: the SDK contract, with the optional members
+ * it DOES implement narrowed to present, so a caller that composes one —
+ * `workspace.ts` wraps this handle — does not have to re-check for a method
+ * this file always defines.
  */
 export type KubernetesSandboxHandle = Sandbox &
-	Required<Pick<Sandbox, 'openTerminal' | 'openTcpConnection'>>
+	Required<Pick<Sandbox, 'openTerminal' | 'openTcpConnection' | 'walkFiles' | 'readFileStream'>>
 
 /**
  * Build the handle. It does NOT run the acquire-time privilege probe — that
@@ -183,6 +255,9 @@ export function buildKubernetesSandbox(options: KubernetesSandboxOptions): Kuber
 	// line carrying an id is also a `kubectl get sandbox` argument.
 	const id = options.name as SandboxId
 	const transport = options.transport
+	// Captured as a const so the conditional member below narrows: the method
+	// is on the handle if and only if this is defined, decided once, here.
+	const setNetworkPolicy = options.setNetworkPolicy
 
 	type Lifecycle = 'active' | 'retiring' | 'destroyed' | 'gone'
 	let lifecycle: Lifecycle = 'active'
@@ -278,6 +353,29 @@ export function buildKubernetesSandbox(options: KubernetesSandboxOptions): Kuber
 		return retirementPromise
 	}
 
+	/**
+	 * What an unconfirmed cancellation does to THIS sandbox: retire it, or
+	 * whatever the owner's hook decided instead — see
+	 * {@link KubernetesSandboxBaseOptions.onUnconfirmedCancellation}.
+	 */
+	const observeUnconfirmedCancellation = async (
+		error: RemoteCancellationUnknownError,
+	): Promise<SandboxRetirementObservation> => {
+		const decide = options.onUnconfirmedCancellation
+		if (decide === undefined) return await retire()
+		try {
+			return await decide(error)
+		} catch (hookError: unknown) {
+			// The caller is already receiving `error`; a hook that threw must
+			// not replace it, and must not be reported as a teardown that was
+			// attempted either.
+			return {
+				accepted: false,
+				error: hookError instanceof Error ? hookError : new Error(String(hookError)),
+			}
+		}
+	}
+
 	const runExecution = async <T>(operation: string, run: () => Promise<T>): Promise<T> => {
 		assertAdmissible(operation)
 		activeExecutions += 1
@@ -285,7 +383,7 @@ export function buildKubernetesSandbox(options: KubernetesSandboxOptions): Kuber
 			return await run()
 		} catch (error) {
 			if (error instanceof RemoteCancellationUnknownError) {
-				error.retirement = await retire()
+				error.retirement = await observeUnconfirmedCancellation(error)
 			}
 			throw error
 		} finally {
@@ -317,10 +415,15 @@ export function buildKubernetesSandbox(options: KubernetesSandboxOptions): Kuber
 		 * Every `tcp` request dials a fresh connection, so its envelope is
 		 * also that connection's first, not-yet-authenticated frame and is
 		 * bounded by the guest's pre-auth frame ceiling (8 MiB by default).
-		 * The transport checks that BEFORE dialing and throws
-		 * `AgentPreauthFrameTooLargeError` naming the limit; it is passed
-		 * through unwrapped so a caller can catch that class and chunk,
-		 * rather than having to pattern-match a message.
+		 * A body above it is no longer a refusal: the transport splits it
+		 * into parts that each fit, writes them to a temporary sibling of
+		 * the target and finishes with an atomic rename, so this method
+		 * takes a body of any size the transport's `maxWriteFileBytes`
+		 * admits (1 GiB by default). The named refusals that remain are
+		 * passed through unwrapped so a caller can catch them BY CLASS:
+		 * `AgentWriteFileTooLargeError` for a body above that bound, and
+		 * `AgentPreauthFrameTooLargeError` for an oversized body against a
+		 * guest too old to advertise the part protocol.
 		 */
 		async writeFile(path: string, content: string | Buffer): Promise<void> {
 			assertAdmissible('writeFile')
@@ -328,11 +431,47 @@ export function buildKubernetesSandbox(options: KubernetesSandboxOptions): Kuber
 			await transport.writeFile(path, buf)
 		},
 
-		async readFile(path: string): Promise<Buffer> {
+		/**
+		 * A whole-file read is served by the guest's streamed op when the
+		 * guest advertises it, so neither side holds the file's base64 form
+		 * or its JSON envelope in one piece and a file of any size this
+		 * workspace's disk holds can be read. `offset`/`length` ask for one
+		 * slice instead; a guest too old to honour them is refused with
+		 * `AgentReadFileStreamUnsupportedError` rather than answering with
+		 * the whole file.
+		 */
+		async readFile(path: string, readOptions?: SandboxReadFileOptions): Promise<Buffer> {
 			assertAdmissible('readFile')
-			return await transport.readFile(path)
+			return await transport.readFile(path, readOptions)
+		},
+
+		/**
+		 * Chunks, in order, with nothing whole at either end — what a host
+		 * draining a large output file before `destroy()` needs. The
+		 * admissibility check runs at the call, not per chunk: a workspace
+		 * suspended mid-stream takes its pod's connection with it, which is
+		 * what ends the iteration.
+		 */
+		readFileStream(path: string, readOptions?: SandboxReadFileOptions): AsyncIterable<Buffer> {
+			assertAdmissible('readFileStream')
+			return transport.readFileStream(path, readOptions)
 		},
 
+		// Present only when the backend was configured for per-sandbox egress
+		// — see {@link KubernetesSandboxBaseOptions.setNetworkPolicy}. The
+		// admissibility gate is this file's, not the writer's, so a destroyed
+		// or cluster-removed sandbox refuses BY NAME here, exactly as every
+		// other method does, rather than failing at the API server one round
+		// trip later.
+		...(setNetworkPolicy !== undefined
+			? {
+					setNetworkPolicy: async (policy: SandboxNetworkPolicy): Promise<void> => {
+						assertAdmissible('setNetworkPolicy')
+						await setNetworkPolicy(policy)
+					},
+				}
+			: {}),
+
 		async openTerminal(terminalOptions: OpenTerminalOptions): Promise<TerminalSession> {
 			assertAdmissible('openTerminal')
 			const terminal = await transport.openTerminal(terminalOptions)
@@ -369,6 +508,65 @@ export function buildKubernetesSandbox(options: KubernetesSandboxOptions): Kuber
 			})
 		},
 
+		/**
+		 * Bounded, lazy file discovery — the method the SDK's `glob` and
+		 * `grep` builtins refuse a sandbox for not having.
+		 *
+		 * Built on {@link walkFilesViaExec}, the same host-side enumerator the
+		 * Firecracker and docker backends use, over this transport's `exec`:
+		 * the guest needs no new agent op, because the walk IS an execution —
+		 * `node -e` running the SDK's own walk program and streaming one JSONL
+		 * record per match. The guest image is `node:22-bookworm-slim` (see
+		 * `k8s/Dockerfile`) and the agent is itself node, so node on the
+		 * guest's PATH is a precondition of the agent existing rather than a
+		 * new requirement this method introduces.
+		 *
+		 * Ownership is the same as `exec`'s, and deliberately NOT
+		 * `runExecution`'s: that helper wraps one awaited call, and a walk is a
+		 * sequence of them. `activeExecutions` is therefore held for the whole
+		 * walk rather than per entry — `status` reads `busy` from the first
+		 * `next()` to the last, never flapping between yields — and an
+		 * unconfirmed cancellation retires this handle exactly as a failed
+		 * `exec` cancel does, on the same error class and through the same
+		 * `retire()`.
+		 *
+		 * Cancellation: `options.signal` and the consumer's own
+		 * `iterator.return()` both abort the underlying `exec`, which sends
+		 * the guest a `cancel-execution` and kills the walk's process group —
+		 * so breaking out of the loop after five entries leaves nothing
+		 * running in the pod.
+		 */
+		async *walkFiles(
+			rootPath: string,
+			walkOptions: SandboxWalkFilesOptions,
+		): AsyncIterable<SandboxFileEntry> {
+			assertAdmissible('walkFiles')
+			activeExecutions += 1
+			try {
+				yield* walkFilesViaExec(
+					async (command, argv, execOpts) => await transport.exec(command, argv, execOpts),
+					rootPath,
+					walkOptions,
+				)
+			} catch (error) {
+				// The same rule `runExecution` applies, inlined because a
+				// generator cannot be wrapped by it: a command whose
+				// cancellation the guest could not confirm may still be running
+				// in that pod, so the pod stops being reusable.
+				//
+				// TWO SITES, ONE RULE. This block and `runExecution`'s must
+				// change together — #480, which owns the unconfirmed-cancel
+				// rule for this backend, is the next change to both, and a
+				// change that lands in one of them is a bug in the other.
+				if (error instanceof RemoteCancellationUnknownError) {
+					error.retirement = await retire()
+				}
+				throw error
+			} finally {
+				activeExecutions = Math.max(0, activeExecutions - 1)
+			}
+		},
+
 		async destroy(destroyOptions?: SandboxDestroyOptions): Promise<void> {
 			if (retirementPromise) {
 				const observation = await retirementPromise