@namzu/sandbox 14.0.0 → 16.0.0

package/dist/backends/kubernetes/rbac.d.ts

@@ -0,0 +1,153 @@
+/**
+ * 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 declare const KUBERNETES_CLAIMANT_RBAC_RULES: readonly KubernetesRbacRule[];
+//# sourceMappingURL=rbac.d.ts.map

package/dist/backends/kubernetes/rbac.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rbac.d.ts","sourceRoot":"","sources":["../../../src/backends/kubernetes/rbac.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAEH,6EAA6E;AAC7E,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE/E;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAA;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,kBAAkB,EAqCtE,CAAA"}

package/dist/backends/kubernetes/rbac.js

@@ -0,0 +1,177 @@
+/**
+ * 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.
+ */
+/**
+ * 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 = 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']),
+    }),
+    Object.freeze({
+        apiGroup: 'agents.x-k8s.io',
+        resource: 'sandboxes',
+        verbs: Object.freeze(['get']),
+    }),
+    Object.freeze({
+        apiGroup: 'extensions.agents.x-k8s.io',
+        resource: 'sandboxwarmpools',
+        verbs: Object.freeze(['get']),
+    }),
+    Object.freeze({
+        apiGroup: '',
+        resource: 'pods',
+        verbs: Object.freeze(['get', 'list']),
+    }),
+    Object.freeze({
+        apiGroup: 'networking.k8s.io',
+        resource: 'networkpolicies',
+        verbs: Object.freeze(['get', 'list']),
+    }),
+    Object.freeze({
+        apiGroup: 'cilium.io',
+        resource: 'ciliumnetworkpolicies',
+        verbs: Object.freeze(['get', 'list']),
+    }),
+]);
+//# sourceMappingURL=rbac.js.map

package/dist/backends/kubernetes/rbac.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rbac.js","sourceRoot":"","sources":["../../../src/backends/kubernetes/rbac.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAiBH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAkC,MAAM,CAAC,MAAM,CAAC;IAC1F,qEAAqE;IACrE,wEAAwE;IACxE,sEAAsE;IACtE,4DAA4D;IAC5D,uEAAuE;IACvE,8CAA8C;IAC9C,MAAM,CAAC,MAAM,CAAC;QACb,QAAQ,EAAE,4BAA4B;QACtC,QAAQ,EAAE,eAAe;QACzB,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC;KAC3E,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACb,QAAQ,EAAE,iBAAiB;QAC3B,QAAQ,EAAE,WAAW;QACrB,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAU,CAAC;KACtC,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACb,QAAQ,EAAE,4BAA4B;QACtC,QAAQ,EAAE,kBAAkB;QAC5B,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAU,CAAC;KACtC,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACb,QAAQ,EAAE,EAAE;QACZ,QAAQ,EAAE,MAAM;QAChB,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,CAAU,CAAC;KAC9C,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACb,QAAQ,EAAE,mBAAmB;QAC7B,QAAQ,EAAE,iBAAiB;QAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,CAAU,CAAC;KAC9C,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACb,QAAQ,EAAE,WAAW;QACrB,QAAQ,EAAE,uBAAuB;QACjC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,CAAU,CAAC;KAC9C,CAAC;CACF,CAAC,CAAA"}

package/dist/backends/kubernetes/sandbox.d.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
  *
@@ -42,7 +58,8 @@
  * {@link KubernetesSandboxGoneError} (the cluster deleted it — the lease
  * renewal found the object already gone).
  */
-import type { Sandbox } from '@namzu/sdk';
+import type { Sandbox, SandboxNetworkPolicy } from '@namzu/sdk';
+import { RemoteCancellationUnknownError, type SandboxRetirementObservation } from '../remote-execution-controller.js';
 import type { KubernetesAgentTransport } from './transport.js';
 /** Thrown by any operation on a sandbox this host already destroyed. */
 export declare class KubernetesSandboxDestroyedError extends Error {
@@ -71,6 +88,56 @@ 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>;
 }
 /**
  * The lease half of the options: a way to move the expiry, and the expiry it
@@ -106,12 +173,12 @@ interface KubernetesSandboxUnleasedOptions {
 }
 export type KubernetesSandboxOptions = KubernetesSandboxBaseOptions & (KubernetesSandboxLeaseOptions | KubernetesSandboxUnleasedOptions);
 /**
- * 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'>>;
+export type KubernetesSandboxHandle = Sandbox & Required<Pick<Sandbox, 'openTerminal' | 'openTcpConnection' | 'walkFiles' | 'readFileStream'>>;
 /**
  * Build the handle. It does NOT run the acquire-time privilege probe — that
  * is `create()`'s job in `index.ts`, so that a refusal can destroy this

package/dist/backends/kubernetes/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/backends/kubernetes/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAEX,OAAO,EAWP,MAAM,YAAY,CAAA;AAQnB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AAW9D,wEAAwE;AACxE,qBAAa,+BAAgC,SAAQ,KAAK;IAIxD,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM;IAJ7B,SAAkB,IAAI,qCAAoC;gBAGhD,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM;CAM7B;AAED;;;;;;GAMG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IAInD,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM;IAJ7B,SAAkB,IAAI,gCAA+B;gBAG3C,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM;CAM7B;AAED,UAAU,4BAA4B;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,wBAAwB,CAAA;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACzD;AAED;;;;;;;GAOG;AACH,UAAU,6BAA6B;IACtC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7E,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAClD,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CACjC;AAED;;;;;;;;GAQG;AACH,UAAU,gCAAgC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAA;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAA;IAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,CAAA;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,CAAA;CACpC;AAED,MAAM,MAAM,wBAAwB,GAAG,4BAA4B,GAClE,CAAC,6BAA6B,GAAG,gCAAgC,CAAC,CAAA;AASnE;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAC5C,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,mBAAmB,CAAC,CAAC,CAAA;AAE9D;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,wBAAwB,GAAG,uBAAuB,CAuNjG"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/backends/kubernetes/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,OAAO,KAAK,EAEX,OAAO,EAOP,oBAAoB,EAOpB,MAAM,YAAY,CAAA;AAInB,OAAO,EACN,8BAA8B,EAC9B,KAAK,4BAA4B,EACjC,MAAM,mCAAmC,CAAA;AAE1C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AAW9D,wEAAwE;AACxE,qBAAa,+BAAgC,SAAQ,KAAK;IAIxD,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM;IAJ7B,SAAkB,IAAI,qCAAoC;gBAGhD,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM;CAM7B;AAED;;;;;;GAMG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IAInD,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM;IAJ7B,SAAkB,IAAI,gCAA+B;gBAG3C,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM;CAM7B;AAED,UAAU,4BAA4B;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,wBAAwB,CAAA;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACzD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,CACpC,KAAK,EAAE,8BAA8B,KACjC,OAAO,CAAC,4BAA4B,CAAC,CAAA;IAC1C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3E;AAED;;;;;;;GAOG;AACH,UAAU,6BAA6B;IACtC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7E,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAClD,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CACjC;AAED;;;;;;;;GAQG;AACH,UAAU,gCAAgC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAA;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAA;IAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,CAAA;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,CAAA;CACpC;AAED,MAAM,MAAM,wBAAwB,GAAG,4BAA4B,GAClE,CAAC,6BAA6B,GAAG,gCAAgC,CAAC,CAAA;AASnE;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAC5C,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,mBAAmB,GAAG,WAAW,GAAG,gBAAgB,CAAC,CAAC,CAAA;AAE/F;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,wBAAwB,GAAG,uBAAuB,CAqVjG"}