@namzu/sandbox 26.0.0 → 27.0.0

package/dist/backends/kubernetes/workspace.js

@@ -159,13 +159,15 @@
  */
 import { OperationDeadline, OperationDeadlineExpired, runFailureCleanup } from '../readiness.js';
 import { RemoteCancellationUnknownError } from '../remote-execution-controller.js';
-import { assertEgressPolicyIsEnforceable, assertEgressProfileIsUsable, assertWorkspaceCarriesNoPerSandboxEgress, composeAdditionalPodLabels, egressProfileLabel, } from './egress-policy.js';
-import { KubernetesWorkspaceGuestGoneError, KubernetesWorkspaceReplacedError, } from './identity.js';
+import { assertEgressPolicyIsEnforceable, assertEgressProfileIsUsable, assertPerSandboxEgressIsUsable, composeAdditionalPodLabels, egressProfileLabel, } from './egress-policy.js';
+import { KubernetesGuestPinRefusedError, KubernetesWorkspaceGuestGoneError, KubernetesWorkspaceReplacedError, freezePinnedIdentity, } from './identity.js';
 import { DEFAULT_AGENT_PORT, ReadinessPollTimeout, bindingFromSandbox, buildEgressBoundary, buildIngressVerifier, buildSandboxBody, clientAccess, clientOptions, pollForBinding, probeSandboxPrivileges, readBoundPod, readSandboxTemplate, resolveAgentAddress, resolveKubernetesReadiness, resolveProbeTimeoutMs, resolveStreamHeartbeatMs, sandboxPodLabels, sandboxPodTemplate, } from './index.js';
 import { KubernetesAlreadyGoneError, KubernetesConflictError, KubernetesPatchNotAppliedError, createKubernetesClient, } from './k8s-client.js';
 import { HOLDER_EPOCH_ANNOTATION_KEY, OPERATING_MODE_CHANGED_AT_ANNOTATION_KEY, POD_TEMPLATE_HASH_ANNOTATION_KEY, SANDBOX_TEMPLATE_LABEL_KEY, buildHolderEpochPatch, holderEpochAllows, isPodStopped, persistentVolumeClaimPath, podPath, podTemplateHash, readHolderEpoch, readPodTemplateHash, sandboxCollectionPath, sandboxPath, } from './objects.js';
+import { KubernetesOwnerUidMissingError, buildAdmissionFence, buildPerSandboxPolicySetter, } from './per-sandbox-policy.js';
 import { KubernetesSandboxDestroyedError, buildKubernetesSandbox, } from './sandbox.js';
-import { KubernetesAgentTransport, KubernetesFlushUnconfirmedError, KubernetesFlushUnreachableError, KubernetesFlushUnsupportedError, KubernetesQuiesceUnconfirmedError, KubernetesQuiesceUnsupportedError, flushUnsupportedError, guestWhenReserved, } from './transport.js';
+import { KubernetesAgentTransport, KubernetesFlushUnconfirmedError, KubernetesFlushUnreachableError, KubernetesFlushUnsupportedError, KubernetesQuiesceUnconfirmedError, KubernetesQuiesceUnsupportedError, flushUnsupportedError, guestMismatchOf, guestWhenReserved, isUnauthorizedRefusal, } from './transport.js';
+import { perSandboxWorkspaceLabels, reverifyPerSandboxEgress, withoutPerSandboxLabel, } from './workspace-per-sandbox.js';
 /**
  * Thrown when a workspace's `SandboxTemplate` does not describe a block disk
  * this backend is willing to build a workspace on.
@@ -368,7 +370,7 @@ export class KubernetesWorkspacePreconditionError extends Error {
  * as a decimal string, and an integer because a fractional epoch would
  * round-trip through the annotation as something other than what was passed.
  */
-function assertHolderEpoch(epoch, where) {
+export function assertHolderEpoch(epoch, where) {
     if (epoch === undefined)
         return undefined;
     if (!Number.isSafeInteger(epoch) || epoch < 0) {
@@ -611,6 +613,13 @@ export function assertAdoptedWorkspaceMatchesConfig(sandboxName, namespace, podT
             throw new KubernetesWorkspaceMismatchError(sandboxName, 'egressProfile', `${profile.key}=${profile.value}`, carried === undefined ? undefined : `${profile.key}=${carried}`, `kubernetes: Sandbox ${sandboxName} in namespace ${namespace} already exists, and its spec.podTemplate carries ${profile.key}: ${carried === undefined ? '(absent)' : JSON.stringify(carried)} rather than the configured egress profile ${JSON.stringify(profile.value)}. The translated policy's podSelector matches that label as well as the template one, so this object's pod is not selected by the policy this call just verified — and since each profile needs its own policy object, a pod carrying no profile label at all is selected by none of them, while create() would have reported the boundary verified. A standing workspace's pod labels are not rewritten underneath it by an ordinary adopt, so the mismatch is named instead. Three ways out, and only the last one costs the disk: reopen it with refreshPodTemplate: true, which rewrites spec.podTemplate — profile label and all — on the one Suspended → Running transition and is the supported way to move a workspace between profiles; or point config.egress.profile at ${carried === undefined ? 'the profile this object was built under (none was)' : JSON.stringify(carried)}; or delete the Sandbox — which takes its disk with it — and create it again under ${JSON.stringify(profile.value)}.`);
         }
     }
+    const perSandboxLabel = expected.perSandboxLabel;
+    if (perSandboxLabel !== undefined) {
+        const carried = podTemplate?.metadata?.labels?.[perSandboxLabel.key];
+        if (carried !== perSandboxLabel.value) {
+            throw new KubernetesWorkspaceMismatchError(sandboxName, 'perSandboxLabel', `${perSandboxLabel.key}=${perSandboxLabel.value}`, carried === undefined ? undefined : `${perSandboxLabel.key}=${carried}`, `kubernetes: Sandbox ${sandboxName} in namespace ${namespace} already exists, and its spec.podTemplate carries ${perSandboxLabel.key}: ${carried === undefined ? '(absent)' : JSON.stringify(carried)} rather than ${JSON.stringify(perSandboxLabel.value)}. config.egress.perSandbox is configured, and every per-sandbox policy selects a pod by exactly that label — a workspace created before the option was set carries none, so a policy written for it would select nothing while setNetworkPolicy reported the grant applied. A standing workspace's pod labels are not rewritten underneath it by an ordinary adopt, so the mismatch is named instead. Reopen it with refreshPodTemplate: true, which rewrites spec.podTemplate — the label included — on the one Suspended → Running transition, or unset config.egress.perSandbox, or delete the Sandbox — which takes its disk with it — and create it again.`);
+        }
+    }
     if (expected.runtimeClassName === undefined)
         return;
     const declared = podTemplate?.spec?.runtimeClassName;
@@ -644,17 +653,15 @@ export function assertAdoptedWorkspaceMatchesConfig(sandboxName, namespace, podT
  */
 export async function createKubernetesWorkspace(config, options) {
     options.signal?.throwIfAborted();
-    // `config.egress.perSandbox` is the one part of `config.egress` this path
-    // cannot honour at all, and it is refused FIRST — before readiness, before
-    // the client, before any request. It configures `setNetworkPolicy`, which
-    // a workspace handle never carries: nothing in the create path below
-    // composes a per-sandbox pod label or tracks an owner uid for one, and
-    // the option exists to make the method present on a TASK handle. Accepting
-    // it here and omitting the method is the silent downgrade every other
-    // refusal in `egress-policy.ts` exists to prevent, so it is refused by
-    // name rather than validated: `assertPerSandboxEgressIsUsable` would
-    // check a config this path serves no purpose for and report it as usable.
-    assertWorkspaceCarriesNoPerSandboxEgress(config.egress);
+    // `config.egress.perSandbox` is honoured here exactly as on a task handle:
+    // the workspace's pod template carries the per-sandbox selector label, the
+    // Sandbox owns every policy written for it, and the handle serves
+    // `setNetworkPolicy`. A value the backend can never honour — an engine
+    // with no hostname concept, an unnamed fence, a selector key the API
+    // server would refuse — is decidable from config alone and is refused
+    // first, before readiness, before the client, before any request. With
+    // `perSandbox` unset this is a no-op and nothing below changes.
+    assertPerSandboxEgressIsUsable(config.egress);
     const readiness = resolveKubernetesReadiness(config);
     const namespace = config.namespace;
     const name = workspaceSandboxName(options.workspaceId);
@@ -704,6 +711,17 @@ export async function createKubernetesWorkspace(config, options) {
         assertEgressPolicyIsEnforceable(config.egress.policy, config.egress.engine ?? 'core', config.egress.ciliumNarrowing);
         await egressBoundary?.verifyNamedObject(options.signal);
     }
+    // Per-sandbox egress: the fence that bounds what this host may write is
+    // proved BEFORE the POST and before any adopt patch, so a workspace is
+    // never opened, woken or created under a configuration whose fence does
+    // not enforce. `undefined` — and not one extra request — without it.
+    const perSandboxEgress = config.egress?.perSandbox !== undefined
+        ? { ...config.egress, perSandbox: config.egress.perSandbox }
+        : undefined;
+    const openFence = perSandboxEgress !== undefined
+        ? buildAdmissionFence(client, perSandboxEgress.perSandbox, namespace)
+        : undefined;
+    await openFence?.assertApplied(options.signal);
     // Read and validate BEFORE anything is created, so a template that cannot
     // carry a workspace fails with nothing to clean up.
     const template = await readSandboxTemplate(client, namespace, templateName, options.signal);
@@ -730,7 +748,8 @@ export async function createKubernetesWorkspace(config, options) {
     // workspace onto a new profile is `refreshPodTemplate: true`, which
     // rewrites `/spec/podTemplate` with exactly these labels.
     const profile = egressProfileLabel(config.egress);
-    const profilePodLabels = composeAdditionalPodLabels(config.egress);
+    const perSandboxLabels = perSandboxWorkspaceLabels(config.egress, name);
+    const profilePodLabels = composeAdditionalPodLabels(config.egress, perSandboxLabels);
     const workspacePodLabels = sandboxPodLabels(template, templateName, profilePodLabels);
     const workspaceSubject = `to open workspace ${options.workspaceId} as Sandbox ${name} in namespace ${namespace}`;
     const verifyIngress = buildIngressVerifier(client, config);
@@ -744,7 +763,14 @@ export async function createKubernetesWorkspace(config, options) {
     // reason the ingress check is, and on the adopt path before any resume
     // patch — a workspace whose egress stopped being bounded is refused asleep
     // rather than woken up to be refused.
-    await egressBoundary?.verifyUnion(workspacePodLabels, workspaceSubject, options.signal);
+    // Without the per-sandbox label when one is configured: the only policy
+    // that selects a pod BY that key and value is this workspace's own, which
+    // a standing workspace already has and which the post-write union check
+    // (against the full labels) judged when it was written. Judged here
+    // against the BASELINE it would read as a widening and refuse to reopen
+    // every workspace that holds a grant.
+    const unionLabels = withoutPerSandboxLabel(workspacePodLabels, perSandboxLabels);
+    await egressBoundary?.verifyUnion(unionLabels, workspaceSubject, options.signal);
     // The pod template this call would write, and its revision — built once,
     // from the same overlays `buildSandboxBody` applies below, because the
     // hash has to be taken over exactly the object that lands on the cluster.
@@ -754,8 +780,9 @@ export async function createKubernetesWorkspace(config, options) {
     // by the POST would be taken over a template the POST never wrote.
     const refresh = buildPodTemplateRefresh(template, templateName, config.runtimeClassName, profilePodLabels);
     let adopted;
+    let createdUid;
     try {
-        await client.request('POST', sandboxCollectionPath(namespace), 
+        const created = await client.request('POST', sandboxCollectionPath(namespace), 
         // No shutdownTime: a workspace carries no expiry — see the module
         // comment.
         buildSandboxBody({
@@ -779,6 +806,7 @@ export async function createKubernetesWorkspace(config, options) {
                 ? { runtimeClassName: config.runtimeClassName }
                 : {}),
         }), options.signal);
+        createdUid = created?.metadata?.uid;
     }
     catch (err) {
         if (!(err instanceof KubernetesConflictError))
@@ -789,10 +817,50 @@ export async function createKubernetesWorkspace(config, options) {
             // were built from, so the object is checked against exactly
             // the label this call would have stamped.
             ...(profile !== undefined ? { profile } : {}),
+            ...(perSandboxLabels !== undefined
+                ? {
+                    perSandboxLabel: {
+                        key: Object.keys(perSandboxLabels)[0],
+                        value: name,
+                    },
+                }
+                : {}),
             ...(config.runtimeClassName !== undefined
                 ? { runtimeClassName: config.runtimeClassName }
                 : {}),
-        }, epoch, options.refreshPodTemplate === true ? refresh : undefined, options.signal);
+        }, epoch, options.refreshPodTemplate === true ? refresh : undefined, options.signal, perSandboxEgress !== undefined && openFence !== undefined
+            ? async (uid) => {
+                await reverifyPerSandboxEgress({
+                    client,
+                    namespace,
+                    sandboxName: name,
+                    ownerUid: uid,
+                    egress: perSandboxEgress,
+                    fence: openFence,
+                    ...(options.signal !== undefined ? { signal: options.signal } : {}),
+                });
+            }
+            : undefined);
+    }
+    // A workspace this call just created has no policy of its own yet, but a
+    // same-named one deleted a moment ago may have left one the garbage
+    // collector has not reached: it selects this label value, so it is
+    // dropped now that the new uid is known. A reply with no uid skips it, and
+    // the handle refuses `setNetworkPolicy` for the same reason.
+    if (adopted === undefined &&
+        perSandboxEgress !== undefined &&
+        openFence !== undefined &&
+        typeof createdUid === 'string' &&
+        createdUid !== '') {
+        await reverifyPerSandboxEgress({
+            client,
+            namespace,
+            sandboxName: name,
+            ownerUid: createdUid,
+            egress: perSandboxEgress,
+            fence: openFence,
+            ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        });
     }
     return await openWorkspaceHandle({
         client,
@@ -813,6 +881,15 @@ export async function createKubernetesWorkspace(config, options) {
         // would patch the egress profile off the very pod the configured
         // policy selects.
         ...(Object.keys(profilePodLabels).length > 0 ? { podLabels: profilePodLabels } : {}),
+        ...(perSandboxEgress !== undefined
+            ? {
+                perSandboxEgress: {
+                    egress: perSandboxEgress,
+                    boundary: egressBoundary,
+                    podLabels: workspacePodLabels,
+                },
+            }
+            : {}),
         // A create wrote the revision it just computed; an adopt reports
         // whatever the standing object carries, which is `undefined` for one
         // created before the annotation existed.
@@ -867,7 +944,7 @@ export async function createKubernetesWorkspace(config, options) {
  * been created yet, and the first bind attempt has to WAIT for it rather than
  * fail on the read that finds no live pod — see {@link PodBindPolicy}.
  */
-async function adoptExistingWorkspace(client, namespace, name, workspaceId, expected, epoch, refresh, signal) {
+async function adoptExistingWorkspace(client, namespace, name, workspaceId, expected, epoch, refresh, signal, reverifyPerSandbox) {
     const target = { client, namespace, name, workspaceId };
     const existing = await readSandboxObject(target, signal);
     assertBlockModeWorkspaceDisk(`Sandbox ${name} in namespace ${namespace}`, existing?.spec?.podTemplate, existing?.spec?.volumeClaimTemplates);
@@ -892,6 +969,9 @@ async function adoptExistingWorkspace(client, namespace, name, workspaceId, expe
             ? {}
             : {
                 ...(expected.profile !== undefined ? { profile: expected.profile } : {}),
+                ...(expected.perSandboxLabel !== undefined
+                    ? { perSandboxLabel: expected.perSandboxLabel }
+                    : {}),
                 ...(expected.runtimeClassName !== undefined
                     ? { runtimeClassName: expected.runtimeClassName }
                     : {}),
@@ -903,6 +983,17 @@ async function adoptExistingWorkspace(client, namespace, name, workspaceId, expe
     // superseded opener patches nothing and starts no pod.
     if (epoch !== undefined)
         assertHolderEpochAllows(target, 'createKubernetesWorkspace', epoch, reading);
+    // Per-sandbox egress, before any patch for the reason the refusals above
+    // are: the fence is proved again and every policy this Sandbox does not
+    // own is dropped, so a workspace is never woken under a grant it did not
+    // consent to. See `workspace-per-sandbox.ts` for the rule.
+    if (reverifyPerSandbox !== undefined) {
+        const uid = existing?.metadata?.uid;
+        if (typeof uid !== 'string' || uid === '') {
+            throw new KubernetesOwnerUidMissingError(name, namespace);
+        }
+        await reverifyPerSandbox(uid);
+    }
     if (refreshing && refresh !== undefined) {
         // Both BEFORE the patch, and both against the SANDBOX's
         // volumeClaimTemplates rather than the template's: those are
@@ -1041,6 +1132,36 @@ function operatingModePatch(mode) {
  * re-read and then succeeds.
  */
 const HOLDER_EPOCH_WRITE_ATTEMPTS = 3;
+/** The `expectedSandboxUid` a standalone verb's options carry, validated. */
+function expectedUidOf(options) {
+    const identity = options?.expectedIdentity;
+    if (identity === undefined)
+        return {};
+    if (typeof identity.sandboxUid !== 'string' || identity.sandboxUid === '') {
+        throw new TypeError('kubernetes: expectedIdentity.sandboxUid must be a non-empty string — an empty uid would be a fence that fences nothing.');
+    }
+    return { expectedSandboxUid: identity.sandboxUid };
+}
+/**
+ * Refuse a write whose target is not the Sandbox the caller meant.
+ *
+ * Decided off the read the write is conditioned on, so the refusal is raised
+ * BEFORE any request that could mutate. The same uid then rides in the write
+ * itself, which is what makes the check hold against a replacement landing
+ * between this read and that write.
+ */
+function assertSandboxUidStands(target, standing, options) {
+    const expected = target.expectedSandboxUid;
+    if (expected === undefined || standing === expected)
+        return;
+    throw new KubernetesWorkspaceReplacedError(target.workspaceId, target.name, expected, standing, options);
+}
+/** The `test` clause that pins a JSON patch to the Sandbox the caller meant. */
+function sandboxUidTests(target) {
+    return target.expectedSandboxUid === undefined
+        ? []
+        : [{ op: 'test', path: '/metadata/uid', value: target.expectedSandboxUid }];
+}
 /** One GET of the Sandbox, which is where every condition is read from. */
 async function readSandboxObject(target, signal) {
     return await target.client.request('GET', sandboxPath(target.namespace, target.name), undefined, signal);
@@ -1104,7 +1225,11 @@ async function readHolderEpochGate(target, operation, epoch, signal) {
  */
 async function writeOperatingMode(target, operation, mode, epoch, signal, gate) {
     const path = sandboxPath(target.namespace, target.name);
-    if (epoch === undefined) {
+    // Nothing to write is nothing to condition: the stamp-only write exists to
+    // move the epoch, and without one it has no mutation in it at all.
+    if (epoch === undefined && mode === undefined)
+        return;
+    if (epoch === undefined && target.expectedSandboxUid === undefined) {
         if (mode === undefined)
             return;
         await target.client.request('PATCH', path, operatingModePatch(mode), signal);
@@ -1112,10 +1237,15 @@ async function writeOperatingMode(target, operation, mode, epoch, signal, gate)
     }
     let reading = gate ?? readHolderEpoch((await readSandboxObject(target, signal))?.metadata);
     for (let attempt = 1;; attempt += 1) {
-        assertHolderEpochAllows(target, operation, epoch, reading);
+        // Identity before epoch: a stranger under this name is not this
+        // caller's workspace, whatever epoch it happens to carry.
+        assertSandboxUidStands(target, reading.sandboxUid);
+        if (epoch !== undefined)
+            assertHolderEpochAllows(target, operation, epoch, reading);
         const patch = buildHolderEpochPatch({
             reading,
-            epoch,
+            ...(epoch !== undefined ? { epoch } : {}),
+            tests: sandboxUidTests(target),
             ...(mode !== undefined
                 ? { operatingMode: mode, operatingModeChangedAt: new Date().toISOString() }
                 : {}),
@@ -1130,6 +1260,10 @@ async function writeOperatingMode(target, operation, mode, epoch, signal, gate)
             if (attempt >= HOLDER_EPOCH_WRITE_ATTEMPTS)
                 throw err;
             const next = readHolderEpoch((await readSandboxObject(target, signal))?.metadata);
+            // A replacement that landed between the read and the write is what
+            // the uid `test` refused. It is never retried against the new
+            // owner: this is the refusal, not a race to win.
+            assertSandboxUidStands(target, next.sandboxUid);
             const unmoved = next.annotation === reading.annotation &&
                 next.resourceVersion === reading.resourceVersion &&
                 next.hasAnnotations === reading.hasAnnotations;
@@ -1151,7 +1285,7 @@ async function writeOperatingMode(target, operation, mode, epoch, signal, gate)
  * every create POSTs, so `templateCurrent` would report drift that no refresh
  * could clear.
  */
-function buildPodTemplateRefresh(template, sandboxTemplateName, runtimeClassName, podLabels) {
+export function buildPodTemplateRefresh(template, sandboxTemplateName, runtimeClassName, podLabels) {
     const podTemplate = sandboxPodTemplate(template, sandboxTemplateName, runtimeClassName, podLabels);
     return {
         podTemplate,
@@ -1196,12 +1330,16 @@ async function writeRefreshedPodTemplate(target, operation, refresh, epoch, gate
     const path = sandboxPath(target.namespace, target.name);
     let reading = gate;
     for (let attempt = 1;; attempt += 1) {
+        assertSandboxUidStands(target, reading.sandboxUid);
         if (epoch !== undefined)
             assertHolderEpochAllows(target, operation, epoch, reading);
         const patch = buildHolderEpochPatch({
             reading,
             ...(epoch !== undefined ? { epoch } : {}),
-            tests: [{ op: 'test', path: '/spec/operatingMode', value: 'Suspended' }],
+            tests: [
+                ...sandboxUidTests(target),
+                { op: 'test', path: '/spec/operatingMode', value: 'Suspended' },
+            ],
             annotations: { [POD_TEMPLATE_HASH_ANNOTATION_KEY]: refresh.hash },
             podTemplate: refresh.podTemplate,
             operatingMode: 'Running',
@@ -1229,6 +1367,7 @@ async function writeRefreshedPodTemplate(target, operation, refresh, epoch, gate
             if (sandbox === undefined)
                 throw err;
             const next = readHolderEpoch(sandbox.metadata);
+            assertSandboxUidStands(target, next.sandboxUid);
             if (operatingModeOf(sandbox) !== 'Suspended') {
                 // Somebody resumed it first. If they also took the workspace
                 // over, this caller hears THAT rather than being handed a pod
@@ -1266,7 +1405,8 @@ async function writeRefreshedPodTemplate(target, operation, refresh, epoch, gate
  */
 async function deleteSandboxObject(target, operation, epoch, signal, gate) {
     const path = sandboxPath(target.namespace, target.name);
-    if (epoch === undefined) {
+    const expectedUid = target.expectedSandboxUid;
+    if (epoch === undefined && expectedUid === undefined) {
         try {
             await target.client.request('DELETE', path, undefined, signal);
         }
@@ -1278,7 +1418,9 @@ async function deleteSandboxObject(target, operation, epoch, signal, gate) {
     }
     let reading = gate;
     for (let attempt = 1;; attempt += 1) {
-        if (reading === undefined) {
+        // The epoch needs the object's current version for its precondition;
+        // the uid alone does not, because it is the precondition.
+        if (reading === undefined && epoch !== undefined) {
             let sandbox;
             try {
                 sandbox = await readSandboxObject(target, signal);
@@ -1290,8 +1432,12 @@ async function deleteSandboxObject(target, operation, epoch, signal, gate) {
             }
             reading = readHolderEpoch(sandbox?.metadata);
         }
-        assertHolderEpochAllows(target, operation, epoch, reading);
-        if (reading.resourceVersion === undefined) {
+        if (reading !== undefined) {
+            assertSandboxUidStands(target, reading.sandboxUid);
+            if (epoch !== undefined)
+                assertHolderEpochAllows(target, operation, epoch, reading);
+        }
+        if (epoch !== undefined && reading?.resourceVersion === undefined) {
             // Unreachable against a real API server, which sets it on every
             // object it serves — and a bodyless DELETE here would be an
             // UNFENCED delete of somebody's disk, which is the one thing this
@@ -1302,7 +1448,12 @@ async function deleteSandboxObject(target, operation, epoch, signal, gate) {
             await target.client.request('DELETE', path, {
                 apiVersion: 'v1',
                 kind: 'DeleteOptions',
-                preconditions: { resourceVersion: reading.resourceVersion },
+                preconditions: {
+                    ...(reading?.resourceVersion !== undefined
+                        ? { resourceVersion: reading.resourceVersion }
+                        : {}),
+                    ...(expectedUid !== undefined ? { uid: expectedUid } : {}),
+                },
             }, signal);
             return;
         }
@@ -1311,9 +1462,25 @@ async function deleteSandboxObject(target, operation, epoch, signal, gate) {
                 return;
             if (!(err instanceof KubernetesConflictError))
                 throw err;
+            // A 409 is either the version moving (epoch path: re-read and try
+            // again) or the uid precondition refusing a stranger. Look, and
+            // let the uid decide: a different owner is the refusal and is
+            // never retried against.
+            let standing;
+            try {
+                standing = await readSandboxObject(target, signal);
+            }
+            catch (readErr) {
+                if (readErr instanceof KubernetesAlreadyGoneError)
+                    return;
+                throw readErr;
+            }
+            assertSandboxUidStands(target, standing?.metadata?.uid, { cause: err });
+            if (epoch === undefined)
+                throw err;
             if (attempt >= HOLDER_EPOCH_WRITE_ATTEMPTS)
                 throw err;
-            reading = undefined;
+            reading = readHolderEpoch(standing?.metadata);
         }
     }
 }
@@ -1489,7 +1656,7 @@ export async function deleteKubernetesWorkspace(config, workspaceId, options) {
     // matters most on: a retention job superseded between deciding to delete a
     // workspace and calling this would otherwise take the new holder's disk,
     // and nothing brings a disk back.
-    await deleteSandboxObject({ client, namespace, name, workspaceId }, 'deleteKubernetesWorkspace', epoch, options?.signal);
+    await deleteSandboxObject({ client, namespace, name, workspaceId, ...expectedUidOf(options) }, 'deleteKubernetesWorkspace', epoch, options?.signal);
 }
 /**
  * Suspend a workspace by id, without ever adopting it: send the patch, then
@@ -1527,7 +1694,7 @@ export async function suspendKubernetesWorkspace(config, workspaceId, options) {
     assertNoFlushHere(options?.flush, 'suspendKubernetesWorkspace');
     const readiness = resolveKubernetesReadiness(config);
     const client = createKubernetesClient(clientAccess(config), clientOptions(config));
-    await writeOperatingMode({ client, namespace, name, workspaceId }, 'suspendKubernetesWorkspace', 'Suspended', epoch, options?.signal);
+    await writeOperatingMode({ client, namespace, name, workspaceId, ...expectedUidOf(options) }, 'suspendKubernetesWorkspace', 'Suspended', epoch, options?.signal);
     await awaitPodRetired(client, namespace, name, workspaceId, readiness, options?.signal);
 }
 /**
@@ -1568,7 +1735,18 @@ async function openWorkspaceHandle(options) {
     const { client, namespace, name, workspaceId, readiness } = options;
     const id = name;
     /** What every fenced write addresses, and what a refusal names. */
-    const target = { client, namespace, name, workspaceId };
+    const target = {
+        client,
+        namespace,
+        name,
+        workspaceId,
+        // A getter, because the uid is learned at the first bind and every
+        // write after it must carry it. Before that the handle has no uid to
+        // pin, which is the only window it writes unpinned.
+        get expectedSandboxUid() {
+            return sandboxUid;
+        },
+    };
     /**
      * The epoch this handle writes under when a call passes none.
      *
@@ -2744,6 +2922,79 @@ async function openWorkspaceHandle(options) {
         await awaitPodRetired(client, namespace, name, workspaceId, readiness, signal);
         state = 'suspended';
     };
+    /**
+     * Per-sandbox egress on this handle — present exactly when
+     * `config.egress.perSandbox` is configured, which is what makes
+     * `setNetworkPolicy` PRESENT here and absent otherwise (presence follows
+     * configuration, never a probe).
+     *
+     * The fence is replaced, not reused, on every resume: its memo is "proved
+     * once", and a resume is precisely the moment that is no longer enough.
+     * The setter delegates to whichever one is current. Setters are cached per
+     * Sandbox uid, because a policy is NAMED after the uid and its write queue
+     * has to outlive one call.
+     */
+    const perSandboxEgress = options.perSandboxEgress;
+    let currentFence = perSandboxEgress !== undefined
+        ? buildAdmissionFence(client, perSandboxEgress.egress.perSandbox, namespace)
+        : undefined;
+    const delegatingFence = {
+        assertApplied: async (signal) => {
+            await currentFence?.assertApplied(signal);
+        },
+    };
+    const policySetters = new Map();
+    /**
+     * The Sandbox that owns every policy this handle writes, as the cluster
+     * reports it NOW. A different uid than the one this handle bound is a
+     * workspace deleted and created again under the same name: refused, the
+     * way every other call on such a handle is, rather than writing a grant
+     * the new disk's owner never consented to.
+     */
+    const resolvePolicyOwner = async (signal) => {
+        const standing = await readSandboxObject(target, signal);
+        const uid = standing?.metadata?.uid;
+        if (standing === undefined) {
+            throw new KubernetesWorkspaceReplacedError(workspaceId, name, sandboxUid, undefined);
+        }
+        if (typeof uid !== 'string' || uid === '') {
+            throw new KubernetesOwnerUidMissingError(name, namespace);
+        }
+        if (sandboxUid !== undefined && uid !== sandboxUid) {
+            throw new KubernetesWorkspaceReplacedError(workspaceId, name, sandboxUid, uid);
+        }
+        return uid;
+    };
+    const setNetworkPolicy = perSandboxEgress === undefined
+        ? undefined
+        : async (policy) => {
+            // Serialised with the transitions: a write racing a resume would
+            // run under the fence the resume is about to replace, and one
+            // racing a destroy would name an owner that is going away.
+            await serialise(async () => {
+                if (state === 'deleted')
+                    throw new KubernetesSandboxDestroyedError('setNetworkPolicy', name);
+                const uid = await resolvePolicyOwner();
+                let setter = policySetters.get(uid);
+                if (setter === undefined) {
+                    setter = buildPerSandboxPolicySetter({
+                        client,
+                        fence: delegatingFence,
+                        namespace,
+                        egress: perSandboxEgress.egress,
+                        owner: { kind: 'Sandbox', name, uid },
+                        selectorValue: name,
+                        ...(perSandboxEgress.boundary !== undefined
+                            ? {
+                                verifyUnion: (written, signal) => perSandboxEgress.boundary?.verifyUnionWith(perSandboxEgress.podLabels, `the per-sandbox policy ${written.name} written for Sandbox ${name} in namespace ${namespace}`, written, signal) ?? Promise.resolve(),
+                            }
+                            : {}),
+                    });
+                    policySetters.set(uid, setter);
+                }
+                await setter(policy);
+            });
+        };
     /**
      * Wake the workspace if it is asleep, then bring a session up on it.
      *
@@ -2794,6 +3045,31 @@ async function openWorkspaceHandle(options) {
         // the object says it was built from, including a refresh another
         // process applied while this handle slept.
         templateRevision = readPodTemplateHash(current?.metadata);
+        // Per-sandbox egress, before ANY patch: a fresh fence, then every
+        // policy this Sandbox does not own dropped — see
+        // `workspace-per-sandbox.ts` for the rule. A fence that does not
+        // verify refuses the resume with the workspace still suspended, and
+        // nothing written; a policy this Sandbox owns is kept.
+        if (perSandboxEgress !== undefined && current !== undefined) {
+            const uid = current.metadata?.uid;
+            if (typeof uid !== 'string' || uid === '') {
+                throw new KubernetesOwnerUidMissingError(name, namespace);
+            }
+            if (sandboxUid !== undefined && uid !== sandboxUid) {
+                throw new KubernetesWorkspaceReplacedError(workspaceId, name, sandboxUid, uid);
+            }
+            const fence = buildAdmissionFence(client, perSandboxEgress.egress.perSandbox, namespace);
+            await reverifyPerSandboxEgress({
+                client,
+                namespace,
+                sandboxName: name,
+                ownerUid: uid,
+                egress: perSandboxEgress.egress,
+                fence,
+                ...(signal !== undefined ? { signal } : {}),
+            });
+            currentFence = fence;
+        }
         if (woke && refreshPodTemplate) {
             // The template is re-read HERE rather than remembered from the
             // open: the whole point of the option is to pick up an edit made
@@ -3265,7 +3541,109 @@ async function openWorkspaceHandle(options) {
      * the transition queue — the public verb takes it, and `suspendNow` runs
      * inside it.
      */
-    const quiesceNow = async (quiesceOptions) => await admitted('quiesce', async (handle) => await admittedTransport('quiesce', handle).quiesce(quiesceOptions?.graceMs !== undefined ? { graceMs: quiesceOptions.graceMs } : {}, quiesceOptions?.signal));
+    const quiesceNow = async (quiesceOptions) => await admitted('quiesce', async (handle) => await admittedTransport('quiesce', handle).quiesce({
+        ...(quiesceOptions?.graceMs !== undefined ? { graceMs: quiesceOptions.graceMs } : {}),
+        ...(quiesceOptions?.onlyIfIdle === true ? { idleOnly: true } : {}),
+    }, quiesceOptions?.signal));
+    /**
+     * The pinned view over this handle — see {@link KubernetesWorkspace.pinGuest}.
+     *
+     * It owns a sibling transport (built by `pinnedTo`) for the live session's
+     * pod and a Sandbox around it, made on first use and reused while the live
+     * session's transport is the one it was built from. The sibling has no
+     * `refreshHandle`, so nothing it does can follow a replaced pod, and the
+     * Sandbox's `release` does nothing and its unconfirmed-cancellation hook
+     * keeps the pod: a view is not allowed to retire what it does not own.
+     */
+    const buildPinnedGuest = (expected) => {
+        let built;
+        const refuse = (reason, actual, field, fresh, cause) => new KubernetesGuestPinRefusedError(reason, workspaceId, expected, actual, field, fresh, cause !== undefined ? { cause } : undefined);
+        /** Compared before anything is dialed. The guest's own check is the authority; this one is free. */
+        const resolve = (operation) => {
+            const actual = identityNow();
+            if (state !== 'running' || session === undefined || actual.podUid === undefined) {
+                throw refuse('identity-changed', actual, 'podUid');
+            }
+            if (actual.sandboxUid !== expected.sandboxUid) {
+                throw refuse('identity-changed', actual, 'sandboxUid');
+            }
+            if (actual.podUid !== expected.podUid)
+                throw refuse('identity-changed', actual, 'podUid');
+            // Not yet heard from is not "changed": the guest compares it itself.
+            if (actual.guestBootId !== undefined && actual.guestBootId !== expected.guestBootId) {
+                throw refuse('identity-changed', actual, 'guestBootId');
+            }
+            for (const [claim, uid] of Object.entries(expected.volumeClaimUids ?? {})) {
+                if (actual.volumeClaimUids[claim] !== uid) {
+                    throw refuse('identity-changed', actual, 'volumeClaimUids');
+                }
+            }
+            const parent = admittedTransport(operation, session);
+            if (built === undefined || built.parent !== parent) {
+                const transport = parent.pinnedTo(expected.guestBootId);
+                built = {
+                    parent,
+                    transport,
+                    sandbox: buildKubernetesSandbox({
+                        name,
+                        rootDir: options.rootDir,
+                        transport,
+                        release: async () => { },
+                        onUnconfirmedCancellation: async () => ({
+                            accepted: false,
+                            reason: 'pinned-view-keeps-the-pod',
+                        }),
+                    }),
+                };
+            }
+            return built;
+        };
+        const translate = (err) => {
+            if (err instanceof KubernetesGuestPinRefusedError)
+                return err;
+            const replaced = guestMismatchOf(err);
+            if (replaced !== undefined) {
+                return refuse('guest-replaced', undefined, undefined, replaced.guestBootId, err);
+            }
+            if (isUnauthorizedRefusal(err))
+                return refuse('pod-replaced', undefined, undefined, undefined, err);
+            return err;
+        };
+        const pinned = async (operation, run, signal) => {
+            const view = resolve(operation);
+            try {
+                if (!(await view.transport.supportsPinnedGuest(signal))) {
+                    throw refuse('guest-unsupported', undefined, undefined);
+                }
+                return await run(view);
+            }
+            catch (err) {
+                throw translate(err);
+            }
+        };
+        return Object.freeze({
+            expected,
+            exec: async (command, argv, execOptions) => await pinned('exec', async (view) => await view.sandbox.exec(command, argv, execOptions)),
+            readFile: async (path, readOptions) => await pinned('readFile', async (view) => await view.sandbox.readFile(path, readOptions)),
+            writeFile: async (path, content) => await pinned('writeFile', async (view) => await view.sandbox.writeFile(path, content)),
+            listFiles: async (rootPath) => await pinned('listFiles', async (view) => await view.sandbox.listFiles(rootPath)),
+            openTerminal: async (terminalOptions) => await pinned('openTerminal', async (view) => await view.sandbox.openTerminal(terminalOptions)),
+            openTcpConnection: async (connectOptions) => await pinned('openTcpConnection', async (view) => await view.sandbox.openTcpConnection(connectOptions)),
+            quiesce: async (quiesceOptions) => {
+                // Copied before any await, like the workspace's own.
+                if (quiesceOptions?.onlyIfIdle !== undefined &&
+                    typeof quiesceOptions.onlyIfIdle !== 'boolean') {
+                    throw new TypeError('kubernetes: quiesce({ onlyIfIdle }) must be a boolean');
+                }
+                const request = {
+                    ...(quiesceOptions?.graceMs !== undefined ? { graceMs: quiesceOptions.graceMs } : {}),
+                    ...(quiesceOptions?.onlyIfIdle === true ? { idleOnly: true } : {}),
+                };
+                const signal = quiesceOptions?.signal;
+                return await pinned('quiesce', async (view) => await view.transport.quiesce(request, signal), signal);
+            },
+        });
+    };
     /**
      * Tell the host about a gap a suspend went ahead over.
      *
@@ -3489,6 +3867,9 @@ async function openWorkspaceHandle(options) {
         get identity() {
             return identityNow();
         },
+        pinGuest(input) {
+            return buildPinnedGuest(freezePinnedIdentity(input));
+        },
         onGuestRestart(listener) {
             restartListeners.add(listener);
             return () => {
@@ -3512,6 +3893,7 @@ async function openWorkspaceHandle(options) {
         },
         rootDir: options.rootDir,
         environment,
+        ...(setNetworkPolicy !== undefined ? { setNetworkPolicy } : {}),
         async exec(command, argv, execOptions) {
             // The default path, untouched: the SDK's exec through the inner
             // handle, the shared execution controller, and the retirement
@@ -3652,7 +4034,23 @@ async function openWorkspaceHandle(options) {
             // racing the suspend that follows it would be a quiesce of a pod the
             // patch has already taken away, and one racing a resume would ask
             // the old pod to stop the new one's processes.
-            return await serialise(async () => await quiesceNow(quiesceOptions));
+            //
+            // The options are copied HERE, synchronously, before the queue is
+            // awaited: a caller that mutates its object after calling cannot
+            // change what is sent, in particular cannot turn an idle-only
+            // request into a stopping one.
+            if (quiesceOptions?.onlyIfIdle !== undefined &&
+                typeof quiesceOptions.onlyIfIdle !== 'boolean') {
+                throw new TypeError('kubernetes: quiesce({ onlyIfIdle }) must be a boolean');
+            }
+            const request = Object.freeze({
+                ...(quiesceOptions?.graceMs !== undefined ? { graceMs: quiesceOptions.graceMs } : {}),
+                ...(quiesceOptions?.onlyIfIdle !== undefined
+                    ? { onlyIfIdle: quiesceOptions.onlyIfIdle }
+                    : {}),
+                ...(quiesceOptions?.signal !== undefined ? { signal: quiesceOptions.signal } : {}),
+            });
+            return await serialise(async () => await quiesceNow(request));
         },
         async flush(flushOptions) {
             // Serialised for the reason `quiesce()` is: a flush racing the