@stigmer/server 3.16.1-dev.20260917224426 → 3.18.0-dev.20260918103812

package/src/extensions/registry.ts

@@ -53,6 +53,7 @@ import type { SecretCodec } from "../encryption/codec.js";
 import { V1_VERSION } from "../encryption/v1-codec.js";
 import type { AuthorizationQueryEngine } from "./authorization-queries.js";
 import type { IdentityFederation } from "./identity-federation.js";
+import type { LicenseStatusProvider } from "./license-status.js";
 import type { ListReadScope } from "./list-read-scope.js";
 import type { PolicyGrantScope } from "./policy-grant-scope.js";
 import type { ModelCatalogProvider } from "../domain/workflow/registry/model-catalog-provider.js";
@@ -272,6 +273,11 @@ export interface ResolvedExtensionDrivers {
    * tuple-half RPC arms refuse UNIMPLEMENTED with the edition reason.
    */
   readonly authorizationQueries: AuthorizationQueryEngine | undefined;
+  /**
+   * The license-status provider — undefined = compose.ts installs the
+   * built-in `absent` answer, so every edition serves getLicenseStatus.
+   */
+  readonly licenseStatus: LicenseStatusProvider | undefined;
 }
 
 /**
@@ -325,6 +331,8 @@ export function resolveExtensions(
   let policyGrantScopeDeclaredBy: string | undefined;
   let authorizationQueries: AuthorizationQueryEngine | undefined;
   let authorizationQueriesDeclaredBy: string | undefined;
+  let licenseStatus: LicenseStatusProvider | undefined;
+  let licenseStatusDeclaredBy: string | undefined;
   const artifactStorageDrivers = new Map<
     string,
     ArtifactStorageDriverFactory
@@ -516,6 +524,16 @@ export function resolveExtensions(
       authorizationQueriesDeclaredBy = unit.name;
     }
 
+    if (unit.drivers?.licenseStatus !== undefined) {
+      if (licenseStatusDeclaredBy !== undefined) {
+        throw new Error(
+          `extension '${unit.name}' registers a LicenseStatusProvider, but '${licenseStatusDeclaredBy}' already did — exactly one may be composed`,
+        );
+      }
+      licenseStatus = unit.drivers.licenseStatus;
+      licenseStatusDeclaredBy = unit.name;
+    }
+
     if (unit.drivers?.artifactStorageDrivers !== undefined) {
       for (const [name, factory] of unit.drivers.artifactStorageDrivers) {
         if ((BUILT_IN_STORAGE_TYPES as ReadonlyArray<string>).includes(name)) {
@@ -641,6 +659,7 @@ export function resolveExtensions(
       iamPolicyStore,
       policyGrantScope,
       authorizationQueries,
+      licenseStatus,
     },
     services,
     workers,

package/src/index.ts

@@ -111,6 +111,14 @@ export type {
 } from "./extensions/resource-authorization.js";
 export type { OrganizationDirectory } from "./extensions/organization-directory.js";
 export { ALL_ORGANIZATIONS } from "./extensions/organization-directory.js";
+// The license-status seam (drivers.licenseStatus): the provider an
+// Enterprise composition registers so getLicenseStatus answers from its
+// configured ticket. The built-in `absent` default is the composition
+// root's and is not exported.
+export type {
+  LicenseStatusProvider,
+  LicenseStatusReport,
+} from "./extensions/license-status.js";
 // The 20260911.11 identity-account seams (Q-IA-9): the store PORT a
 // composition drives the domain through (drivers.identityAccountStore;
 // a driver throws DuplicateAccountError for a held id), the federation

package/src/pipeline/__tests__/billing-contract-rules.test.ts

@@ -0,0 +1,260 @@
+/**
+ * Pins the message-level rules of the plan, subscription and license
+ * contract through the shared validator every edition runs
+ * (steps/validation.ts, the same instance the transport interceptor uses).
+ *
+ * Why here and not in a conformance suite: every billing kind is cloud_only,
+ * so the open-source server never serves a Plan or a License and the
+ * cross-edition suites, where field rules are normally proven against a
+ * running server, cannot reach them. The vocabulary those kinds share with
+ * the Enterprise edition (Entitlements, LicenseClaims) is verified offline
+ * by a server that holds no store for it at all. The one place in this
+ * repository where a rule on these messages can be proven red-then-green is
+ * the validator itself, so this file drives it directly, one row per rule,
+ * a passing shape beside every refused one.
+ *
+ * What the rows pin: the instrument decides which PlanTerms a plan may carry;
+ * a license's timestamps are ordered (issue, expiry, grace); a limit is
+ * present or absent, never zero; a feature is named once. A row that
+ * stops matching means the contract moved, and the proto is where it moved.
+ */
+import { create } from "@bufbuild/protobuf";
+import type { DescMessage, MessageInitShape } from "@bufbuild/protobuf";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+import {
+  PlanInstrument,
+  PlanSpecSchema,
+} from "@stigmer/protos/ai/stigmer/billing/plan/v1/spec_pb";
+import { LicenseSpecSchema } from "@stigmer/protos/ai/stigmer/billing/license/v1/spec_pb";
+import {
+  EntitlementLimitsSchema,
+  EntitlementsSchema,
+  Feature,
+} from "@stigmer/protos/ai/stigmer/platform/v1/entitlement_pb";
+import {
+  LicenseClaimsSchema,
+  LicenseTerm,
+} from "@stigmer/protos/ai/stigmer/platform/v1/license_pb";
+import { describe, expect, it } from "vitest";
+
+import { validator } from "../steps/validation.js";
+
+const t = (iso: string) => timestampFromDate(new Date(iso));
+
+const customer = {
+  id: "cus_acme",
+  displayName: "Acme Corp",
+  contactEmail: "billing@acme.example",
+};
+const entitlements = { features: [Feature.channels] };
+const orderedTerm = {
+  issuedAt: t("2026-09-01T00:00:00Z"),
+  expiresAt: t("2027-09-01T00:00:00Z"),
+  graceUntil: t("2027-10-01T00:00:00Z"),
+};
+
+/** One row: a message, its init, and the rule id it must trip, or none. */
+interface Row<Desc extends DescMessage> {
+  readonly name: string;
+  readonly schema: Desc;
+  readonly init: MessageInitShape<Desc>;
+  readonly refusedBy?: string;
+}
+
+function row<Desc extends DescMessage>(r: Row<Desc>): Row<Desc> {
+  return r;
+}
+
+const rows: ReadonlyArray<Row<DescMessage>> = [
+  row({
+    name: "a subscription plan with monthly terms",
+    schema: PlanSpecSchema,
+    init: {
+      instrument: PlanInstrument.subscription,
+      entitlements,
+      terms: { monthlyMinimumMicros: 1n, usageShareBasisPoints: 100 },
+    },
+  }),
+  row({
+    name: "a license plan with an annual price",
+    schema: PlanSpecSchema,
+    init: {
+      instrument: PlanInstrument.license,
+      entitlements,
+      terms: { annualPriceMicros: 1n },
+    },
+  }),
+  row({
+    name: "a plan with no terms at all",
+    schema: PlanSpecSchema,
+    init: { instrument: PlanInstrument.subscription, entitlements },
+  }),
+  row({
+    name: "a license plan carrying a monthly minimum",
+    schema: PlanSpecSchema,
+    init: {
+      instrument: PlanInstrument.license,
+      entitlements,
+      terms: { monthlyMinimumMicros: 1n },
+    },
+    refusedBy: "plan_spec.license_has_no_monthly_terms",
+  }),
+  row({
+    name: "a license plan carrying a usage share",
+    schema: PlanSpecSchema,
+    init: {
+      instrument: PlanInstrument.license,
+      entitlements,
+      terms: { usageShareBasisPoints: 100 },
+    },
+    refusedBy: "plan_spec.license_has_no_monthly_terms",
+  }),
+  row({
+    name: "a subscription plan carrying an annual price",
+    schema: PlanSpecSchema,
+    init: {
+      instrument: PlanInstrument.subscription,
+      entitlements,
+      terms: { annualPriceMicros: 1n },
+    },
+    refusedBy: "plan_spec.subscription_has_no_annual_price",
+  }),
+  row({
+    name: "a usage share above one hundred percent",
+    schema: PlanSpecSchema,
+    init: {
+      instrument: PlanInstrument.subscription,
+      entitlements,
+      terms: { usageShareBasisPoints: 10001 },
+    },
+    refusedBy: "int32.gte_lte",
+  }),
+  row({
+    name: "ordered license claims",
+    schema: LicenseClaimsSchema,
+    init: {
+      licenseId: "lic_1",
+      customer,
+      term: LicenseTerm.paid,
+      entitlements,
+      ...orderedTerm,
+    },
+  }),
+  row({
+    name: "claims expiring before they were issued",
+    schema: LicenseClaimsSchema,
+    init: {
+      licenseId: "lic_1",
+      customer,
+      term: LicenseTerm.paid,
+      entitlements,
+      ...orderedTerm,
+      expiresAt: t("2026-08-01T00:00:00Z"),
+      graceUntil: t("2026-08-02T00:00:00Z"),
+    },
+    refusedBy: "license_claims.expires_after_issue",
+  }),
+  row({
+    name: "claims whose grace ends before expiry",
+    schema: LicenseClaimsSchema,
+    init: {
+      licenseId: "lic_1",
+      customer,
+      term: LicenseTerm.paid,
+      entitlements,
+      ...orderedTerm,
+      graceUntil: t("2027-08-01T00:00:00Z"),
+    },
+    refusedBy: "license_claims.grace_not_before_expiry",
+  }),
+  row({
+    name: "a customer with no contact address",
+    schema: LicenseClaimsSchema,
+    init: {
+      licenseId: "lic_1",
+      customer: { id: "cus_acme", displayName: "Acme Corp" },
+      term: LicenseTerm.paid,
+      entitlements,
+      ...orderedTerm,
+    },
+    refusedBy: "required",
+  }),
+  row({
+    name: "a customer whose contact address is not an email",
+    schema: LicenseClaimsSchema,
+    init: {
+      licenseId: "lic_1",
+      customer: { ...customer, contactEmail: "acme" },
+      term: LicenseTerm.paid,
+      entitlements,
+      ...orderedTerm,
+    },
+    refusedBy: "string.email",
+  }),
+  row({
+    name: "a license spec whose grace ends before expiry",
+    schema: LicenseSpecSchema,
+    init: {
+      customer,
+      entitlements,
+      term: LicenseTerm.trial,
+      expiresAt: orderedTerm.expiresAt,
+      graceUntil: t("2027-08-01T00:00:00Z"),
+    },
+    refusedBy: "license_spec.grace_not_before_expiry",
+  }),
+  row({
+    name: "a license spec with grace on the expiry instant",
+    schema: LicenseSpecSchema,
+    init: {
+      customer,
+      entitlements,
+      term: LicenseTerm.trial,
+      expiresAt: orderedTerm.expiresAt,
+      graceUntil: orderedTerm.expiresAt,
+    },
+  }),
+  row({
+    name: "a limit of zero, which is never what an operator meant",
+    schema: EntitlementLimitsSchema,
+    init: { maxOrganizations: 0 },
+    refusedBy: "int32.gt",
+  }),
+  row({
+    name: "an absent limit, which is no limit",
+    schema: EntitlementLimitsSchema,
+    init: {},
+  }),
+  row({
+    name: "a feature named twice",
+    schema: EntitlementsSchema,
+    init: { features: [Feature.channels, Feature.channels] },
+    refusedBy: "repeated.unique",
+  }),
+  row({
+    name: "the unspecified feature",
+    schema: EntitlementsSchema,
+    init: { features: [Feature.feature_unspecified] },
+    refusedBy: "enum.not_in",
+  }),
+];
+
+describe("the billing contract's rules, through the shared validator", () => {
+  for (const r of rows) {
+    const verdict =
+      r.refusedBy === undefined ? "passes" : `is refused by ${r.refusedBy}`;
+    it(`${r.name} ${verdict}`, () => {
+      const result = validator().validate(r.schema, create(r.schema, r.init));
+      if (r.refusedBy === undefined) {
+        expect(result.kind).toBe("valid");
+        return;
+      }
+      if (result.kind !== "invalid") {
+        throw new Error(`expected a refusal, got ${result.kind}`);
+      }
+      expect(result.error.violations.map((v) => v.ruleId)).toContain(
+        r.refusedBy,
+      );
+    });
+  }
+});

package/src/sandbox/__tests__/docker.integration.test.ts

@@ -68,6 +68,7 @@ describe.skipIf(!optedIn || !dockerAnswers())(
       await driver.ensureSessionSandbox(sessionId, {
         taskQueue: `session:${sessionId}`,
         stigmerToken: "tok-docker-smoke",
+        callerClass: "user",
       });
       expect(await driver.probe("session", sessionId)).toBe("running");
 
@@ -91,6 +92,7 @@ describe.skipIf(!optedIn || !dockerAnswers())(
       await driver.ensureSessionSandbox(sessionId, {
         taskQueue: `session:${sessionId}`,
         stigmerToken: "tok-docker-smoke",
+        callerClass: "user",
       });
       expect(await driver.probe("session", sessionId)).toBe("running");
 

package/src/sandbox/__tests__/kubernetes.test.ts

@@ -89,7 +89,11 @@ function fakeGateway(
   };
 }
 
-const env = { taskQueue: "session:ses_1", stigmerToken: "tok-1" };
+const env = {
+  taskQueue: "session:ses_1",
+  stigmerToken: "tok-1",
+  callerClass: "user",
+};
 
 describe("the ensure state machine", () => {
   it("absent → Secret, PVC, Deployment — in that order, no readiness wait", async () => {
@@ -211,7 +215,11 @@ describe("the manifest shapes (the Java SandboxManifestFactory pins)", () => {
   });
 
   it("a token-less sandbox omits the token env but keeps the (empty) Secret", () => {
-    const tokenless = { taskQueue: "session:ses_1", stigmerToken: "" };
+    const tokenless = {
+      taskQueue: "session:ses_1",
+      stigmerToken: "",
+      callerClass: "user",
+    };
     const deployment = buildSandboxDeployment(
       "session",
       "ses_1",

package/src/sandbox/__tests__/local-process.integration.test.ts

@@ -6,7 +6,11 @@
  * can read it, so no real runner install is needed.
  *
  * Unix-only like the runner itself; deterministic (poll with timeout,
- * never sleep).
+ * never sleep). Every poll gets an explicit budget: vitest's default
+ * second is enough on an idle laptop and not under the full suite's
+ * load, where a /bin/sh child can take longer than that to start and
+ * write its first line. Polling returns the moment the condition holds,
+ * so the larger budget costs nothing on a quiet host.
  */
 import {
   chmodSync,
@@ -25,6 +29,9 @@ import { createLogger } from "../../boot/logger.js";
 import { newLocalProcessSandboxProvisioner } from "../local-process.js";
 import type { SandboxDriverConfig } from "../provisioner.js";
 
+/** How long a spawned child is given to start, write, or die under load. */
+const CHILD_SETTLE_TIMEOUT_MS = 10_000;
+
 const silentLogger = createLogger({
   level: "error",
   pretty: false,
@@ -74,14 +81,18 @@ describe.skipIf(process.platform === "win32")(
       await driver.ensureSessionSandbox("ses_smoke", {
         taskQueue: "session:ses_smoke",
         stigmerToken: "tok-smoke",
+        callerClass: "user",
+      });
+      await vi.waitFor(() => expect(spawnCount()).toBe(1), {
+        timeout: CHILD_SETTLE_TIMEOUT_MS,
       });
-      await vi.waitFor(() => expect(spawnCount()).toBe(1));
       expect(await driver.probe("session", "ses_smoke")).toBe("running");
 
       // Fast path: a second ensure must not spawn a second process.
       await driver.ensureSessionSandbox("ses_smoke", {
         taskQueue: "session:ses_smoke",
         stigmerToken: "tok-smoke",
+        callerClass: "user",
       });
       expect(spawnCount()).toBe(1);
 
@@ -104,16 +115,22 @@ describe.skipIf(process.platform === "win32")(
 
     it("deprovision kills the child; probe reports absent; re-ensure respawns", async () => {
       await driver.deprovisionSessionSandbox("ses_smoke");
-      await vi.waitFor(async () => {
-        expect(await driver.probe("session", "ses_smoke")).toBe("absent");
-      });
+      await vi.waitFor(
+        async () => {
+          expect(await driver.probe("session", "ses_smoke")).toBe("absent");
+        },
+        { timeout: CHILD_SETTLE_TIMEOUT_MS },
+      );
 
       // The repair arm without stored state: a fresh ensure respawns.
       await driver.ensureSessionSandbox("ses_smoke", {
         taskQueue: "session:ses_smoke",
         stigmerToken: "",
+        callerClass: "user",
+      });
+      await vi.waitFor(() => expect(spawnCount()).toBe(2), {
+        timeout: CHILD_SETTLE_TIMEOUT_MS,
       });
-      await vi.waitFor(() => expect(spawnCount()).toBe(2));
       expect(await driver.probe("session", "ses_smoke")).toBe("running");
     });
 

package/src/sandbox/__tests__/steps.test.ts

@@ -11,7 +11,10 @@
  *   - the terminal observer deprovisions exactly on transitions INTO a
  *     terminal phase, fire-and-forget, and swallows (logs) teardown
  *     failures;
- *   - a disabled mint lane launches token-less rather than failing.
+ *   - a disabled mint lane launches token-less rather than failing;
+ *   - the caller splits two ways on both lanes: the identity id reaches
+ *     the credential mint, the caller class reaches the driver's
+ *     environment unchanged (a composed lane such as `guest` included).
  */
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -53,14 +56,25 @@ import {
   ensureWorkflowSandboxForExecution,
   newWorkflowSandboxTerminalObserver,
   SANDBOX_PROVISIONING_FAILED_PREFIX,
+  type SandboxCaller,
 } from "../steps.js";
 
 /**
- * The caller identity the ensure bodies thread into the credential mint
- * (C4): the OSS execution-scoped mint ignores it, so these tests pass a
- * fixed value and the token assertions stay binding-shaped.
+ * The caller the ensure bodies split two ways: the identity id into the
+ * credential mint (C4 — the OSS execution-scoped mint ignores it, so the
+ * token assertions stay binding-shaped) and the class onto the driver's
+ * environment. `user` is the plain lane; the class-propagation cases hand
+ * in a composed lane's word to prove the body copies, never normalises.
  */
 const TEST_CALLER_IDENTITY_ID = "ida_test_caller";
+const TEST_CALLER: SandboxCaller = {
+  identityId: TEST_CALLER_IDENTITY_ID,
+  callerClass: "user",
+};
+const GUEST_CALLER: SandboxCaller = {
+  identityId: "ida_guest_caller",
+  callerClass: "guest",
+};
 
 const silentLogger = createLogger({
   level: "error",
@@ -235,7 +249,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(provisioner.ensured).toEqual([
       {
@@ -244,11 +258,32 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         env: {
           taskQueue: `session:${sessionId}`,
           stigmerToken: `tok-${execution.metadata?.id ?? ""}`,
+          callerClass: "user",
         },
       },
     ]);
   });
 
+  it("hands the caller's class to the driver unchanged and the caller's id to the mint", async () => {
+    const provisioner = fakeProvisioner();
+    const credentials = capabilityCredentials();
+    const { execution } = await seed(ExecutionTarget.CLOUD);
+    await ensureSessionSandboxForExecution(
+      {
+        store,
+        logger: silentLogger,
+        lane: lane(provisioner, credentials),
+        temporalConfig: sessionRoutingCloudDefault,
+      },
+      execution,
+      GUEST_CALLER,
+    );
+    expect(provisioner.ensured[0]?.env.callerClass).toBe("guest");
+    expect(credentials.minted[0]?.callerIdentityId).toBe(
+      GUEST_CALLER.identityId,
+    );
+  });
+
   it("delegates the mint to the capability provider with the full provisioning context (C4)", async () => {
     const provisioner = fakeProvisioner();
     const credentials = capabilityCredentials();
@@ -277,7 +312,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
 
     expect(credentials.minted).toEqual([
@@ -303,7 +338,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(provisioner.ensured).toEqual([]);
   });
@@ -327,7 +362,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
   });
 
@@ -345,7 +380,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(provisioner.ensured).toEqual([]);
   });
@@ -366,7 +401,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         ),
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(provisioner.ensured).toEqual([]);
   });
@@ -382,7 +417,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(provisioner.ensured[0]?.env.stigmerToken).toBe("");
   });
@@ -401,7 +436,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     const stamped = await store.getResource(
       ApiResourceKind.agent_execution,
@@ -439,7 +474,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     const after = await store.getResource(
       ApiResourceKind.agent_execution,
@@ -467,17 +502,35 @@ describe("the workflow lane (ensureWorkflowSandboxForExecution)", () => {
         temporalConfig: executionRoutingConfig,
       },
       workflowExecution(ExecutionTarget.CLOUD),
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(provisioner.ensured).toEqual([
       {
         scope: "workflow",
         id: "wfx_sbx_1",
-        env: { taskQueue: "wfexec:wfx_sbx_1", stigmerToken: "tok-wfx_sbx_1" },
+        env: {
+          taskQueue: "wfexec:wfx_sbx_1",
+          stigmerToken: "tok-wfx_sbx_1",
+          callerClass: "user",
+        },
       },
     ]);
   });
 
+  it("hands the caller's class to the driver unchanged on the workflow lane", async () => {
+    const provisioner = fakeProvisioner();
+    await ensureWorkflowSandboxForExecution(
+      {
+        logger: silentLogger,
+        lane: lane(provisioner),
+        temporalConfig: executionRoutingConfig,
+      },
+      workflowExecution(ExecutionTarget.CLOUD),
+      GUEST_CALLER,
+    );
+    expect(provisioner.ensured[0]?.env.callerClass).toBe("guest");
+  });
+
   it("delegates the mint to the capability provider on the workflow scope (C4)", async () => {
     const provisioner = fakeProvisioner();
     const credentials = capabilityCredentials();
@@ -491,7 +544,7 @@ describe("the workflow lane (ensureWorkflowSandboxForExecution)", () => {
         metadata: { id: "wfx_sbx_cap", name: "wfx_sbx_cap", org: "org-test" },
         spec: { executionTarget: ExecutionTarget.CLOUD },
       }),
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(credentials.minted).toEqual([
       {
@@ -514,7 +567,7 @@ describe("the workflow lane (ensureWorkflowSandboxForExecution)", () => {
         temporalConfig: executionRoutingConfig,
       },
       workflowExecution(ExecutionTarget.LOCAL),
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     await ensureWorkflowSandboxForExecution(
       {
@@ -528,7 +581,7 @@ describe("the workflow lane (ensureWorkflowSandboxForExecution)", () => {
         ),
       },
       workflowExecution(ExecutionTarget.CLOUD),
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(provisioner.ensured).toEqual([]);
   });
@@ -545,7 +598,7 @@ describe("the workflow lane (ensureWorkflowSandboxForExecution)", () => {
           temporalConfig: executionRoutingConfig,
         },
         workflowExecution(ExecutionTarget.CLOUD),
-        TEST_CALLER_IDENTITY_ID,
+        TEST_CALLER,
       );
       expect.unreachable("the workflow lane must throw on failure");
     } catch (error) {

package/src/sandbox/kubernetes.ts

@@ -85,7 +85,14 @@ const RUNNER_RESOURCES = {
   limits: { cpu: "2", memory: "2Gi" },
 } as const;
 
-/** The persistent-workspace scopes (SandboxScope.persistentWorkspace). */
+/**
+ * The persistent-workspace scopes (SandboxScope.persistentWorkspace).
+ * Durability here is decided by SCOPE alone: this driver reads neither the
+ * environment's caller class nor any per-session policy, so every session
+ * keeps its PVC whoever asked. A driver that gives some caller classes a
+ * workspace that dies with the conversation is a composition's choice
+ * built on SandboxEnvironment.callerClass, not a built-in behaviour.
+ */
 const PERSISTENT_SCOPES: ReadonlySet<SandboxScope> = new Set([
   "session",
   "workflow",