@namzu/sandbox 26.0.0 → 27.0.0

package/src/backends/kubernetes/per-sandbox-policy.ts

@@ -46,7 +46,11 @@
  * operator's own baseline policy. So before the FIRST write, this module
  * proves an operator applied a `ValidatingAdmissionPolicy` and its binding,
  * and refuses with {@link KubernetesAdmissionFenceMissingError}, having
- * written nothing, if either is absent. The shipped example
+ * written nothing, if either is absent — and with
+ * {@link KubernetesAdmissionFenceInertError}, naming the field, if either
+ * exists and would not enforce (see `per-sandbox-fence.ts`: the same
+ * standard the `no-network` baseline's named-object check holds its own
+ * object to). The shipped example
  * (`k8s/manifests/validatingadmissionpolicy-cilium.yaml`) bounds the host
  * identity to this name prefix, an owner reference whose uid the name has to
  * match, ONE selector label whose VALUE is that owner's own name (the shape
@@ -56,6 +60,18 @@
  * kube-dns rule on port 53, no address-based or entity-based peers and no
  * ingress.
  *
+ * ## Verified after every write
+ *
+ * Reading the object back proves the object is the one that was sent. It says
+ * nothing about the BOUNDARY, which is the union of every policy selecting the
+ * pod: a policy applied between this sandbox's create and its grant that
+ * allows more is invisible to a read-back of this one. So after the read-back
+ * the union is enumerated again, against the baseline translation plus the
+ * policy just written (`unionEgressAllowance`), and if anything allows more
+ * the object is deleted before the error is thrown — the per-sandbox
+ * analogue of the baseline's "no sandbox is handed back". An empty list is not
+ * re-checked: a deletion only narrows.
+ *
  * ## Union, not replacement
  *
  * The cluster unions every policy selecting a pod, so what this writes ADDS
@@ -89,6 +105,7 @@ import {
 	assertHostsFitNarrowing,
 	assertUsableHost,
 	buildCiliumEgressManifest,
+	narrowedHostPorts,
 	perSandboxEgressLabelKey,
 	verifyEgressPolicyApplied,
 } from './egress-policy.js'
@@ -108,6 +125,17 @@ import {
 	validatingAdmissionPolicyBindingPath,
 	validatingAdmissionPolicyPath,
 } from './objects.js'
+import {
+	KubernetesAdmissionFenceInertError,
+	KubernetesPermittedHostsError,
+	KubernetesPermittedHostsParamError,
+	type PermittedHosts,
+	assertFenceEnforces,
+	assertPermittedHostsFenceEnforces,
+	assertWithinPermittedHosts,
+	permittedHostsFenceNames,
+	readPermittedHosts,
+} from './per-sandbox-fence.js'
 
 /**
  * Every per-sandbox policy's name starts with this, and the shipped admission
@@ -224,6 +252,15 @@ export class KubernetesAdmissionFenceMissingError extends Error {
  */
 export { KubernetesNetworkPolicyHostError }
 
+// The fence's content checks and the operator-pinned host set live in
+// `per-sandbox-fence.ts`; their errors are re-exported here so every import
+// path a per-sandbox refusal is caught by keeps resolving from one module.
+export {
+	KubernetesAdmissionFenceInertError,
+	KubernetesPermittedHostsError,
+	KubernetesPermittedHostsParamError,
+}
+
 /**
  * One `allowedHosts` entry, validated and canonicalised to the bytes a
  * `CiliumNetworkPolicy` should carry.
@@ -286,18 +323,21 @@ export interface PerSandboxPolicyFence {
 export function buildAdmissionFence(
 	client: KubernetesClient,
 	perSandbox: KubernetesPerSandboxEgressConfig,
+	namespace: string,
 ): PerSandboxPolicyFence {
 	const policyName = perSandbox.admissionPolicyName
 	const bindingName = perSandbox.admissionPolicyBindingName ?? `${policyName}-binding`
+	const param = perSandbox.permittedHostsParam
+	const companion = param === undefined ? undefined : permittedHostsFenceNames(perSandbox)
 	let applied: Promise<void> | undefined
 	const read = async (
 		kind: 'ValidatingAdmissionPolicy' | 'ValidatingAdmissionPolicyBinding',
 		name: string,
 		path: string,
 		signal?: AbortSignal,
-	): Promise<void> => {
+	): Promise<unknown> => {
 		try {
-			await client.request('GET', path, undefined, signal)
+			return await client.request('GET', path, undefined, signal)
 		} catch (err) {
 			if (err instanceof KubernetesAlreadyGoneError) {
 				throw new KubernetesAdmissionFenceMissingError(kind, name, path)
@@ -311,21 +351,47 @@ export function buildAdmissionFence(
 			throw err
 		}
 	}
+	const readPair = async (
+		policy: string,
+		binding: string,
+		signal?: AbortSignal,
+	): Promise<{
+		policyName: string
+		policy: unknown
+		bindingName: string
+		binding: unknown
+	}> => ({
+		policyName: policy,
+		policy: await read(
+			'ValidatingAdmissionPolicy',
+			policy,
+			validatingAdmissionPolicyPath(policy),
+			signal,
+		),
+		bindingName: binding,
+		binding: await read(
+			'ValidatingAdmissionPolicyBinding',
+			binding,
+			validatingAdmissionPolicyBindingPath(binding),
+			signal,
+		),
+	})
 	return {
 		async assertApplied(signal) {
+			// Existence first, then CONTENT, and both memoized together on
+			// success: the baseline's named-object check does the same, and a
+			// fence that existed but would not enforce is refused here, with
+			// the field that failed, before anything is written.
 			applied ??= (async () => {
-				await read(
-					'ValidatingAdmissionPolicy',
-					policyName,
-					validatingAdmissionPolicyPath(policyName),
-					signal,
-				)
-				await read(
-					'ValidatingAdmissionPolicyBinding',
-					bindingName,
-					validatingAdmissionPolicyBindingPath(bindingName),
-					signal,
-				)
+				assertFenceEnforces(await readPair(policyName, bindingName, signal), namespace, perSandbox)
+				if (param !== undefined && companion !== undefined) {
+					assertPermittedHostsFenceEnforces(
+						await readPair(companion.policyName, companion.bindingName, signal),
+						namespace,
+						perSandbox,
+						param,
+					)
+				}
 			})().catch((err: unknown) => {
 				applied = undefined
 				throw err
@@ -352,6 +418,41 @@ export interface PerSandboxPolicySetterOptions {
 	 * config, through the one resolver.
 	 */
 	readonly selectorValue: string
+	/**
+	 * The post-write union check: given the policy just written and read back,
+	 * prove that the union of every policy selecting the pod is still the
+	 * baseline plus that policy, and throw if any other one allows more.
+	 * Absent when the deployment opted out of union verification
+	 * (`egress.verify: 'named-object-only'`), exactly as the create path's
+	 * union check is.
+	 */
+	readonly verifyUnion?: (
+		written: KubernetesTranslatedEgressPolicy,
+		signal?: AbortSignal,
+	) => Promise<void>
+}
+
+/**
+ * Raised when a per-sandbox policy was written, FAILED a post-write check, and
+ * the attempt to remove it failed too. The refusal that triggered the removal
+ * is `cause`; the policy may still be in force, and the message says so,
+ * because the one thing a caller must not conclude is that the refusal left the
+ * cluster as it found it.
+ */
+export class KubernetesPerSandboxPolicyNotRemovedError extends Error {
+	override readonly name = 'KubernetesPerSandboxPolicyNotRemovedError'
+
+	constructor(
+		readonly policyName: string,
+		readonly path: string,
+		readonly refusal: unknown,
+		readonly removal: unknown,
+	) {
+		super(
+			`kubernetes: the per-sandbox policy ${policyName} (${path}) failed verification after it was written (${refusal instanceof Error ? refusal.message : String(refusal)}) and removing it failed too (${removal instanceof Error ? removal.message : String(removal)}). It may still be in force: delete it by hand. The sandbox's own destruction also removes it, because the policy is owned by the sandbox's claim.`,
+			{ cause: refusal },
+		)
+	}
 }
 
 /**
@@ -366,7 +467,7 @@ export interface PerSandboxPolicySetterOptions {
 export function buildPerSandboxPolicySetter(
 	options: PerSandboxPolicySetterOptions,
 ): (policy: SandboxNetworkPolicy) => Promise<void> {
-	const { client, fence, namespace, egress, owner, selectorValue } = options
+	const { client, fence, namespace, egress, owner, selectorValue, verifyUnion } = options
 	const perSandbox = egress.perSandbox
 	const labelKey = perSandboxEgressLabelKey(egress)
 	if (labelKey === undefined) {
@@ -419,7 +520,27 @@ export function buildPerSandboxPolicySetter(
 		// gone means its owner was deleted underneath the call and this
 		// sandbox is already being destroyed. The refusal is still right; only
 		// its advice belongs to the other caller.
-		await verifyEgressPolicyApplied(client, translated)
+		//
+		// Then the boundary, not only the object: what the pod can now reach is
+		// the union of every policy selecting it, and the read-back above says
+		// nothing about a policy applied between this sandbox's create and this
+		// grant. A failure of EITHER check removes what was just written, the
+		// way the baseline's create-path checks release the claim they were
+		// about to hand back: an unverified grant left in force is the state
+		// both checks exist to prevent. A policy that held an earlier,
+		// verified list is removed too — falling back to the baseline is the
+		// narrower of the two wrong answers.
+		try {
+			await verifyEgressPolicyApplied(client, translated)
+			await verifyUnion?.(translated)
+		} catch (refusal) {
+			try {
+				await remove()
+			} catch (removal) {
+				throw new KubernetesPerSandboxPolicyNotRemovedError(name, path, refusal, removal)
+			}
+			throw refusal
+		}
 	}
 
 	const remove = async (): Promise<void> => {
@@ -486,6 +607,20 @@ export function buildPerSandboxPolicySetter(
 				await remove()
 				return
 			}
+			// The operator-pinned set, read per call: it is the operator's to
+			// edit, and a stale copy would refuse (or grant) against a list that
+			// is no longer the reviewed one. Only a grant is checked — a removal
+			// can only narrow, and the companion policy does not cover DELETE
+			// for the same reason, so a missing parameter never blocks a revoke.
+			if (perSandbox.permittedHostsParam !== undefined) {
+				const param = perSandbox.permittedHostsParam
+				const permitted: PermittedHosts = await readPermittedHosts(client, param)
+				assertWithinPermittedHosts(param, permitted, hosts, (host) =>
+					perSandbox.narrowing === undefined
+						? undefined
+						: narrowedHostPorts(host, perSandbox.narrowing),
+				)
+			}
 			await write(translate(hosts))
 		})
 		queue = run.then(

package/src/backends/kubernetes/sandbox.ts

@@ -26,15 +26,10 @@
  *    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`.
+ *    A WORKSPACE handle carries it on the same condition, built in
+ *    `workspace.ts` rather than here: the `Sandbox` is the owner, the pod
+ *    template carries the selector label, and a resume re-proves the fence —
+ *    see `workspace-per-sandbox.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:

package/src/backends/kubernetes/transport.ts

@@ -43,8 +43,11 @@ import {
 	type ExecRequest,
 	ExecResultAccumulator,
 	FLUSH_FEATURE,
+	GUEST_MISMATCH_REFUSAL,
 	type GuestReplyIdentity,
+	PINNED_GUEST_FEATURE,
 	QUIESCE_FEATURE,
+	QUIESCE_IDLE_FEATURE,
 	type QuiesceScope,
 	type QuiescedProcess,
 	SESSIONS_FEATURE,
@@ -124,11 +127,63 @@ export class KubernetesAgentRetiringError extends Error {
 
 	constructor(
 		message = 'kubernetes tcp transport: the guest agent has fenced itself (agent_retiring) because an earlier process group’s shutdown could not be confirmed. A command of unknown state may still be running in that pod and nothing on this side can end it: only a new pod clears the fence, and until the pod is replaced every call except healthz and cancel-execution meets this same refusal — reads, writes, terminals and tcp connections included. Nothing was changed on the cluster by this refusal and this handle was not retired. On a persistent workspace, call suspend() and then resume() when you are ready for the live terminals and background processes in that pod to go down; on a task sandbox, destroy() it and take another.',
+		/**
+		 * The agent process that is fenced, when the refusal named it. Only a
+		 * request sent through a pinned view carries one: it is how a caller
+		 * tells "the guest I pinned is the one that is fenced" (the same id)
+		 * from "a different guest stands there" (a `guest_mismatch`).
+		 */
+		readonly guestBootId?: string,
 	) {
 		super(message)
 	}
 }
 
+/**
+ * The guest agent refused a pinned request before dispatching it because its
+ * own boot id is not the one the request was pinned to. Nothing ran.
+ *
+ * `guestBootId` is the id of the agent that answered, so a caller can tell a
+ * replacement (a new id) from a refusal that has nothing to do with identity.
+ * `retiring` is true when that agent is also fenced.
+ */
+export class KubernetesAgentGuestMismatchError extends Error {
+	override readonly name = 'KubernetesAgentGuestMismatchError'
+
+	constructor(
+		readonly guestBootId: string | undefined,
+		readonly retiring = false,
+	) {
+		super(
+			`kubernetes tcp transport: the guest agent refused a pinned request before dispatching it (${GUEST_MISMATCH_REFUSAL}): its boot id is ${guestBootId ?? 'unreported'}, not the one the request was pinned to. Nothing ran.`,
+		)
+	}
+}
+
+/**
+ * The fresh guest boot id carried by a pinned refusal, wherever in an error's
+ * cause chain it sits — the control-plane path throws the class above, and
+ * every other path throws a plain `Error` whose message is the guest's error
+ * text, `guest_mismatch:<id>`.
+ */
+export function guestMismatchOf(
+	error: unknown,
+): { readonly guestBootId: string | undefined; readonly retiring: boolean } | undefined {
+	let current: unknown = error
+	for (let depth = 0; depth < 8 && current instanceof Error; depth += 1) {
+		if (current instanceof KubernetesAgentGuestMismatchError) {
+			return { guestBootId: current.guestBootId, retiring: current.retiring }
+		}
+		const prefix = `${GUEST_MISMATCH_REFUSAL}:`
+		if (current.message.startsWith(prefix)) {
+			const id = current.message.slice(prefix.length).trim()
+			return { guestBootId: id === '' ? undefined : id, retiring: false }
+		}
+		current = current.cause
+	}
+	return undefined
+}
+
 /**
  * Thrown when the agent's address could not be RESOLVED — the dial never
  * reached a socket because the name has no answer here.
@@ -350,7 +405,7 @@ function refusedWith(response: unknown, error: string): boolean {
  * output is quoted into a message, does not equal it. The chain is walked
  * because the retry wrapper and the stream paths wrap rather than replace.
  */
-function isUnauthorizedRefusal(error: unknown): boolean {
+export function isUnauthorizedRefusal(error: unknown): boolean {
 	let current: unknown = error
 	for (let depth = 0; depth < 8 && current instanceof Error; depth += 1) {
 		if (current instanceof KubernetesAgentUnauthorizedError) return true
@@ -461,7 +516,19 @@ async function requestChecked(
 ): Promise<unknown> {
 	const response = await wire.request(request, signal)
 	if (isUnauthorized(response)) throw new KubernetesAgentUnauthorizedError()
-	if (isAgentRetiring(response)) throw new KubernetesAgentRetiringError()
+	if (isAgentRetiring(response)) {
+		throw new KubernetesAgentRetiringError(undefined, guestBootIdOf(response))
+	}
+	if (response && typeof response === 'object') {
+		const value = response as { ok?: unknown; error?: unknown; retiring?: unknown }
+		if (
+			value.ok === false &&
+			typeof value.error === 'string' &&
+			value.error.startsWith(`${GUEST_MISMATCH_REFUSAL}:`)
+		) {
+			throw new KubernetesAgentGuestMismatchError(guestBootIdOf(response), value.retiring === true)
+		}
+	}
 	return response
 }
 
@@ -1314,6 +1381,76 @@ export class KubernetesQuiesceUnconfirmedError extends Error {
 	}
 }
 
+/** One thing the guest found running when an idle-only quiesce looked. */
+export interface KubernetesQuiesceBusyProcess {
+	readonly pid: number
+	/** The kernel's short name for the executable, never its command line. */
+	readonly command: string
+	/** The `/proc` state letter (`R`, `S`, `D`, `Z`...). `Z` here is a zombie leader with a live thread. */
+	readonly state: string
+}
+
+/** A start the agent's registries hold that `/proc` may not show yet. */
+export interface KubernetesQuiesceBusyRegistryEntry {
+	readonly source: 'execution' | 'session'
+	readonly state: string
+}
+
+/**
+ * Thrown by `quiesce({ onlyIfIdle: true })` when the guest is not idle.
+ *
+ * An answer, not a failure: nothing was signalled, marked or stopped, the
+ * guest is exactly as it was, and `busy` says what was seen so the caller can
+ * decide to retry later. `busy` is capped (the guest names at most 32
+ * processes); `busyTotal` counts them all.
+ */
+export class KubernetesQuiesceBusyError extends Error {
+	override readonly name = 'KubernetesQuiesceBusyError'
+
+	constructor(
+		readonly busy: readonly KubernetesQuiesceBusyProcess[],
+		readonly busyTotal: number,
+		readonly registries: readonly KubernetesQuiesceBusyRegistryEntry[],
+		message: string,
+	) {
+		super(message)
+	}
+}
+
+function busyDetail(reply: Record<string, unknown>): {
+	busy: KubernetesQuiesceBusyProcess[]
+	busyTotal: number
+	registries: KubernetesQuiesceBusyRegistryEntry[]
+} {
+	const rows = (value: unknown): Record<string, unknown>[] =>
+		Array.isArray(value)
+			? value.filter(
+					(entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === 'object',
+				)
+			: []
+	const busy = rows(reply.busy).flatMap((row): KubernetesQuiesceBusyProcess[] =>
+		typeof row.pid === 'number'
+			? [
+					{
+						pid: row.pid,
+						command: typeof row.command === 'string' ? row.command : '',
+						state: typeof row.state === 'string' ? row.state : '',
+					},
+				]
+			: [],
+	)
+	const registries = rows(reply.registries).flatMap((row): KubernetesQuiesceBusyRegistryEntry[] =>
+		row.source === 'execution' || row.source === 'session'
+			? [{ source: row.source, state: typeof row.state === 'string' ? row.state : '' }]
+			: [],
+	)
+	return {
+		busy,
+		busyTotal: typeof reply.busyTotal === 'number' ? reply.busyTotal : busy.length,
+		registries,
+	}
+}
+
 /** What the guest stopped, and how widely it was allowed to look. */
 export interface KubernetesQuiesceReport {
 	/** Every process signalled, with the last signal it was actually sent. */
@@ -1479,6 +1616,8 @@ export class KubernetesAgentTransport {
 	private readonly refreshHandle?: (signal?: AbortSignal) => Promise<KubernetesAgentHandle>
 	/** Simple pass-through operations share one transport instance. */
 	private wire: VsockAgentTransport
+	/** What {@link pinnedTo} builds a sibling from: everything but the hooks that follow or report a pod. */
+	private readonly siblingOptions: KubernetesTransportOptions
 
 	constructor(handle: KubernetesAgentHandle, options: KubernetesTransportOptions = {}) {
 		const { onTiming, refreshHandle, onGuestReply, ...transportOptions } = options
@@ -1508,9 +1647,34 @@ export class KubernetesAgentTransport {
 		}
 		this.onTiming = onTiming
 		this.refreshHandle = refreshHandle
+		this.siblingOptions = { ...transportOptions, ...(onTiming !== undefined ? { onTiming } : {}) }
 		this.wire = new VsockAgentTransport(handle, this.wireOptions(handle))
 	}
 
+	/**
+	 * A separate transport for the guest this one is bound to RIGHT NOW,
+	 * whose every request is pinned to the agent process `guestBootId`.
+	 *
+	 * Never rebinds: it has no `refreshHandle`, so a refused token or a dead
+	 * address ends the call where it stands, and it holds its own copy of the
+	 * handle, so a rebind of THIS transport later cannot move it onto another
+	 * pod. It reports no guest identity back either, so a pinned call cannot
+	 * move the observer a workspace uses to detect restarts. Pair it with
+	 * {@link supportsPinnedGuest}: against an agent without the feature the
+	 * `pinned` op is refused as unknown, and nothing is dispatched.
+	 */
+	pinnedTo(guestBootId: string): KubernetesAgentTransport {
+		return new KubernetesAgentTransport(
+			{ ...this.handle },
+			{ ...this.siblingOptions, pinnedGuestBootId: guestBootId },
+		)
+	}
+
+	/** Whether the guest serves the `pinned` op; see {@link PINNED_GUEST_FEATURE}. */
+	async supportsPinnedGuest(signal?: AbortSignal): Promise<boolean> {
+		return (await this.wire.guestFeatures(signal)).includes(PINNED_GUEST_FEATURE)
+	}
+
 	/**
 	 * The shared transport's options for ONE wire, with the reply observer
 	 * bound to the pod that wire is talking to.
@@ -2164,17 +2328,31 @@ export class KubernetesAgentTransport {
 	 * process would not stop, and the reply names its pid.
 	 */
 	async quiesce(
-		options: { readonly graceMs?: number } = {},
+		options: { readonly graceMs?: number; readonly idleOnly?: boolean } = {},
 		signal?: AbortSignal,
 	): Promise<KubernetesQuiesceReport> {
+		const idleOnly = options.idleOnly === true
+		if (idleOnly && options.graceMs !== undefined) {
+			throw new TypeError(
+				'kubernetes: quiesce({ onlyIfIdle: true }) signals nothing, so graceMs has no meaning with it',
+			)
+		}
 		await this.assertQuiesceSupported(signal)
+		// Checked BEFORE anything is sent: an agent without the feature
+		// ignores `idleOnly` and would run the stopping quiesce.
+		if (idleOnly && !(await this.supportsQuiesceIdle(signal))) {
+			throw this.quiesceIdleUnsupported()
+		}
 		const reply = (await this.withRebind(
 			async () =>
 				await requestChecked(
 					this.wire,
 					{
 						op: 'quiesce',
-						body: { ...(options.graceMs !== undefined ? { graceMs: options.graceMs } : {}) },
+						body: {
+							...(idleOnly ? { idleOnly: true } : {}),
+							...(options.graceMs !== undefined ? { graceMs: options.graceMs } : {}),
+						},
 					},
 					signal,
 				),
@@ -2186,6 +2364,15 @@ export class KubernetesAgentTransport {
 		// is one image, not two, so it is the unsupported error rather than a
 		// second name for the same fact — see {@link assertQuiesceSupported}.
 		if (refusal.startsWith('unknown_op')) throw this.quiesceUnsupported()
+		if (idleOnly && refusal === 'quiesce_busy') {
+			const seen = busyDetail(reply)
+			throw new KubernetesQuiesceBusyError(
+				seen.busy,
+				seen.busyTotal,
+				seen.registries,
+				`kubernetes: the guest is not idle (${seen.busyTotal} process(es), ${seen.registries.length} registry entr${seen.registries.length === 1 ? 'y' : 'ies'}). Nothing was signalled, marked or stopped; retry later.`,
+			)
+		}
 		const detail = typeof reply.message === 'string' ? `: ${reply.message}` : ''
 		throw new KubernetesQuiesceUnconfirmedError(
 			refusal,
@@ -2274,6 +2461,18 @@ export class KubernetesAgentTransport {
 		return (await this.wire.guestFeatures(signal)).includes(QUIESCE_FEATURE)
 	}
 
+	/** Whether the guest's `quiesce` accepts `idleOnly`; see {@link QUIESCE_IDLE_FEATURE}. */
+	async supportsQuiesceIdle(signal?: AbortSignal): Promise<boolean> {
+		return (await this.wire.guestFeatures(signal)).includes(QUIESCE_IDLE_FEATURE)
+	}
+
+	private quiesceIdleUnsupported(): KubernetesQuiesceUnsupportedError {
+		return new KubernetesQuiesceUnsupportedError(
+			QUIESCE_IDLE_FEATURE,
+			`kubernetes: this workspace's guest agent does not advertise the '${QUIESCE_IDLE_FEATURE}' healthz feature, so it would ignore the idle-only request and run the ordinary quiesce, which signals and kills what is running. Nothing was sent. Rebuild the workspace image from this Namzu release, or call quiesce() without onlyIfIdle if stopping the work is acceptable.`,
+		)
+	}
+
 	private async assertQuiesceSupported(signal?: AbortSignal): Promise<void> {
 		if (await this.supportsQuiesce(signal)) return
 		throw this.quiesceUnsupported()