@sema-agent/core 5.12.0 → 5.13.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 5.13.0 — 2026-08-05
+
+### BREAKING
+
+- **Request-origin `org:` memory scopes now require fail-closed admission** (`RunnerDeps.memoryScopeAdmission`, new module `memory-admission.ts`). Under the v2 scope contract, an org scope in `TaskSpec.memory` (or a subagent's `AgentDefinition.memory`) that is not deployment-declared refuses the WHOLE prepare: resolver absent ⇒ `memory.admission_required` (transient); resolver throw ⇒ same; principal absent / explicit refusal / partial admit / unrequested grant ⇒ `memory.admission_denied` (terminal). Verdicts are two-state — no silent narrowing of the request side (mount visibility must not become an org-membership probe); the one silent-but-disclosed narrowing is the org WRITE face, which collapses to read-only (`null`) unless the verdict grants it explicitly. **Zero migration for operator-pinned deployments**: scopes listed in the new `RunnerDeps.deploymentMemoryScopes` are deployment-origin (self-certified — no principal, no resolver needed); a present resolver may narrow them (disclosed via `onError`, phase `"memory"`). Delegation freeze: the admitted org set rides `InheritedGate.admittedOrgScopes` (always emitted; absent = older chain, read fail-closed as empty) and persists on the checkpoint data half (seed ∩ live fold — a resume can never widen it); a child's request-origin org scopes must sit inside the parent verdict. On admission-governed deployments, org-SHAPED scopes outside the v2 contract are refused outright; without a governance surface, opaque behavior is byte-identical. **Consumer flips**: probes pinning "request-side org scope mounts with no resolver" red.
+
+- **`classifySubagentError` governance retryability is table-driven** (new module `governance-codes.ts`, closed `GOVERNANCE_CODES` registry — the machine reads the table, never the `_required`/`_denied` name suffix). `errorKind`'s closed domain is unchanged (no new members), but governance is no longer uniformly non-retryable: TRANSIENT codes (`memory.admission_required`, `config.compliance_required` — control-plane absence/outage) now classify `retryable: true`; TERMINAL codes (`*_denied`, `config.locked_key`, the whole legacy `usage.*` family — whose deferred retryability stays on the paired `retryAfterMs` field) stay `retryable: false`. **Consumer flips**: probes pinning "governance ⇒ retryable:false unconditionally" red.
+
+- **Org-admission state is version-fenced on checkpoints** (`ORG_ADMISSION_CHECKPOINT_VERSION = 6`; `MAX_SUPPORTED_CHECKPOINT_VERSION` raised to 6). A suspend whose state carries org-admission freeze fields — the delegation-chain verdict, the session's OWN verdict (`ownAdmittedOrgScopes`, persisted even when adjudicated-EMPTY), and the frozen org WRITE grant (`ownAdmittedOrgWriteScope`; `null` = read-only, a resume can never gain write authority the suspend leg did not hold) — stamps v6, so a pre-admission worker rejects it pre-CAS (`unsupported_version`, stays pending) instead of resuming raw org scopes with no admission door. The session freeze applies to the FINAL admitted projection regardless of origin: a deployment-declared tenant layer the session already lost is dropped-and-disclosed on resume, never silently remounted. Checkpoints without org-admission state keep their historic stamps (zero version movement for deployments not using org memory).
+
+### Added
+
+- **Administrator lock layer** (`locked-config.ts`): `RunnerDeps.lockedConfig` declares locked keys from the closed registry (`mcp` / `toolPolicy` / `compliancePosture` / `retentionPolicy`). A task spec occupying a locked slot refuses the whole prepare (`config.locked_key`, two-state); an unknown key in the declaration refuses too (`config.locked_registry` — a security control that doesn't parse must not half-arm). One preflight resolver runs at the prepare door before any side effect and mints the snapshot all downstream assembly reads (fresh/resume/child legs covered structurally). Locks are config-time only — no request-time unlock; "who can unlock" ≡ "who can change the deployment config". Unlocked deployments byte-identical.
+
+- **Compliance capability veto** (`compliance.ts`): `RunnerDeps.compliancePostureResolver` resolves a per-principal posture (closed profiles `hipaa`/`zdr` × closed capabilities `mcp_servers`/`workflows`/`web_fetch`/`org_memory_mount`; effective denies = builtin floor ∪ `additionalDenies`, supply can only tighten; unknown values refuse loudly). Fail-closed: resolver fault denies every managed capability + `onError`. A denied capability the spec explicitly requests refuses the prepare (`config.compliance_denied`; `config.compliance_required` when the denial came from the resolver fault). `web_fetch` is enforced in CC double-point form (roster refusal at prepare + a call-time lock in the tool gate). No resolver ⇒ byte-identical.
+
+- **Managed retention declaration + contract** (`retention.ts`): stores declare `retention: "managed" | "none"` (declaration, never duck-typing; absence reads fail-closed as `"none"`; an unparseable declaration is a loud refusal). All bundled stores honestly declare `"none"`. `RunnerDeps.retentionPolicy` + a LOCKED `retentionPolicy` key over any `"none"` store refuses the deployment (`config.retention_capability` — via the exported `assertRetentionCapability` at startup, re-run every prepare as backstop). `ManagedRetentionCapability` is the contract TYPE a deployment scheduler implements (tenant-domain enumeration, CAS-fenced checkpoint expiry that releases pins, lineage-aware session deletion, orphan tool-result cleanup; idempotent, tombstoned, audited) — core ships no scheduler and does no cleanup on the task path.
+
+### Fixed
+
+- **Every task notification now delivers at the NEXT turn boundary (mid-work included).** `later`-priority frames (background agent/workflow completions, Monitor watch events) rode `harness.followUp()`, whose queue drains only when the agent would otherwise stop — a model busy-polling a background task (the exact model the receipt told "you will be notified, do not poll") never received the completion, and the end-of-run drain then extended finished runs with stale frames. Re-anchored against CC 2.1.221: queued task-notification inputs are unconditionally deliverable at the boundary. Delivery order is ARRIVAL order; consecutive buffered notifications drain as ONE boundary batch (the retired `followUpMode:"all"` batching, now on the steer lane), and an engine-note backlog past 50 frames parks per session instead of crowding out user steering. `priority` keeps its park/uplink semantics; the harness followUp/stop-gate seam is untouched. Consumer note: a probe pinning "a busy run never sees a `later` completion frame" reds.
+
+- **`finalVerification` mechanism hardening (four of the seven field failure modes).** ① The injection headroom guard read only the turn axis — it now also reads the tightest caller-armed budget axis (tokens/cost/walltime, same axes as the limit-approach frames); ≥90% full skips the injection, so the gate can no longer convert an externally-passing run into `limits.*_exceeded`. ② Both injections emit the standard `steering_injected` echo (**new closed-set member: `source: "final_verification"`** — switches over the source union add an arm), closing the stats-vs-stream observability gap. ③ The nudge licenses cleaning up residue the model's own testing created (the state-harmless clause no longer reads as "leave your test residue in place"). ④ The nudge forbids laundering pre-existing uncertainty into "confirmed". The remaining modes are design-bounded: the engine never judges check semantics, and self-grading is the deployment's verifier-role wiring.
+
 ## 5.12.0 — 2026-08-05
 
 ### BREAKING

package/dist/agents/subagent.js

@@ -18,6 +18,7 @@ import { addWorktree } from "../core/git-worktree-env.js";
 import { shellQuote } from "../tools/fs/search.js";
 import { BG_AGENT_REAP_STOP_ERROR } from "../core/task-registry.js";
 import { extractErrorCode } from "../brain/errors.js";
+import { governanceRetryClass } from "../core/governance-codes.js";
 import { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX, RUNNING_AGENT_OBSERVE_EVERY_BEATS } from "../config/defaults.js";
 function rollupDelegatedCost(stats, nested) {
     if (stats.costMicroUsd === undefined)
@@ -221,6 +222,7 @@ export function classifySubagentError(child) {
         return undefined;
     const code = child.errorCode ?? extractErrorCode(child.errorMessage);
     const msg = (child.errorMessage ?? "").toLowerCase();
+    const governanceClass = code !== undefined ? governanceRetryClass(code) : undefined;
     const errorKind = code === "rate_limit"
         ? "rate_limit"
         : code === "server" && (msg.includes("overloaded") || msg.includes("529"))
@@ -229,10 +231,10 @@ export function classifySubagentError(child) {
                 ? "timeout"
                 : code === "network" || code === "server"
                     ? "network"
-                    : code !== undefined && code.startsWith("usage.")
+                    : governanceClass !== undefined
                         ? "governance"
                         : "logic";
-    return { errorKind, retryable: errorKind !== "logic" && errorKind !== "governance" };
+    return { errorKind, retryable: errorKind === "governance" ? governanceClass === "transient" : errorKind !== "logic" };
 }
 export function completedAgentCard(child, extras) {
     return {

package/dist/core/checkpoint-store.d.ts

@@ -142,6 +142,10 @@ export interface CheckpointState {
             rules: SessionPermissionRules;
         }>;
         shellGate?: "off" | "always" | "classify";
+        admittedOrgScopes?: readonly string[];
+        ownAdmittedOrgScopes?: readonly string[];
+        ownAdmittedOrgWriteScope?: string | null;
+        orgAdmissionGoverned?: true;
         requiresParentConstraint: boolean;
         parentConstraintCount?: number;
     };
@@ -158,7 +162,8 @@ export declare const CURRENT_CHECKPOINT_VERSION = 1;
 export declare const RESOURCE_CHECKPOINT_VERSION = 2;
 export declare const BINDING_CHECKPOINT_VERSION = 3;
 export declare const TOKEN_CHECKPOINT_VERSION = 5;
-export declare const MAX_SUPPORTED_CHECKPOINT_VERSION = 5;
+export declare const ORG_ADMISSION_CHECKPOINT_VERSION = 6;
+export declare const MAX_SUPPORTED_CHECKPOINT_VERSION = 6;
 export declare function checkpointVersionOf(cp: Pick<Checkpoint, "version">): number;
 export interface ResourceLedger {
     totalBudgetMicroUsd?: number;
@@ -255,6 +260,7 @@ export declare class CheckpointError extends Error {
     } | undefined);
 }
 export interface CheckpointStore {
+    readonly retention?: import("./retention.js").RetentionDeclaration;
     put(token: CheckpointToken, cp: Checkpoint): Promise<void>;
     get(token: CheckpointToken): Promise<Checkpoint | null>;
     resolve(token: CheckpointToken, scope: string, outcome: ResumeOutcome, expect?: ResolveExpectation): Promise<boolean>;
@@ -280,6 +286,7 @@ export declare function checkpointRowMatches(cp: Checkpoint | undefined, scope:
 export declare function checkpointOccMatches(cp: Checkpoint, expect?: ResolveExpectation): boolean;
 export type CheckpointFaultMode = "resolve-after-commit" | "resolve-before-commit";
 export declare class InMemoryCheckpointStore implements CheckpointStore {
+    readonly retention: "none";
     private cps;
     private fault;
     put(token: CheckpointToken, cp: Checkpoint): Promise<void>;

package/dist/core/checkpoint-store.js

@@ -128,7 +128,8 @@ export const CURRENT_CHECKPOINT_VERSION = 1;
 export const RESOURCE_CHECKPOINT_VERSION = 2;
 export const BINDING_CHECKPOINT_VERSION = 3;
 export const TOKEN_CHECKPOINT_VERSION = 5;
-export const MAX_SUPPORTED_CHECKPOINT_VERSION = 5;
+export const ORG_ADMISSION_CHECKPOINT_VERSION = 6;
+export const MAX_SUPPORTED_CHECKPOINT_VERSION = 6;
 export function checkpointVersionOf(cp) {
     return cp.version ?? 0;
 }
@@ -250,6 +251,7 @@ export function checkpointOccMatches(cp, expect) {
     return expect === undefined || (cp.rev ?? 0) === expect.rev;
 }
 export class InMemoryCheckpointStore {
+    retention = "none";
     cps = new Map();
     fault = null;
     async put(token, cp) {

package/dist/core/compliance.d.ts

@@ -0,0 +1,11 @@
+export type ComplianceProfile = "hipaa" | "zdr";
+export type ComplianceCapability = "mcp_servers" | "workflows" | "web_fetch" | "org_memory_mount";
+export declare const COMPLIANCE_CAPABILITIES: readonly ["mcp_servers", "workflows", "web_fetch", "org_memory_mount"];
+export interface CompliancePosture {
+    profile: ComplianceProfile;
+    additionalDenies?: readonly ComplianceCapability[];
+}
+export declare const BUILTIN_COMPLIANCE_DENIES: Record<ComplianceProfile, readonly ComplianceCapability[]>;
+export declare function resolveComplianceDenies(posture: CompliancePosture): ReadonlySet<ComplianceCapability>;
+export declare const WEB_FETCH_TOOL_NAME = "WebFetch";
+export declare function complianceCallDenial(denies: ReadonlySet<ComplianceCapability>, toolName: string): string | undefined;

package/dist/core/compliance.js

@@ -0,0 +1,34 @@
+export const COMPLIANCE_CAPABILITIES = ["mcp_servers", "workflows", "web_fetch", "org_memory_mount"];
+export const BUILTIN_COMPLIANCE_DENIES = {
+    hipaa: ["web_fetch", "org_memory_mount"],
+    zdr: ["org_memory_mount"],
+};
+const PROFILES = ["hipaa", "zdr"];
+function codedError(code, message) {
+    const e = new Error(message);
+    e.code = code;
+    return e;
+}
+export function resolveComplianceDenies(posture) {
+    if (!PROFILES.includes(posture.profile)) {
+        throw codedError("config.compliance_posture", `compliance posture profile "${String(posture.profile)}" is not a member of the closed profile set ` +
+            `(${PROFILES.join(", ")}) — refusing to half-apply an unparseable posture.`);
+    }
+    const denies = new Set(BUILTIN_COMPLIANCE_DENIES[posture.profile]);
+    for (const cap of posture.additionalDenies ?? []) {
+        if (!COMPLIANCE_CAPABILITIES.includes(cap)) {
+            throw codedError("config.compliance_posture", `compliance posture additionalDenies contains "${String(cap)}", not a member of the closed capability set ` +
+                `(${COMPLIANCE_CAPABILITIES.join(", ")}) — a misspelled deny must never silently not-enforce.`);
+        }
+        denies.add(cap);
+    }
+    return denies;
+}
+export const WEB_FETCH_TOOL_NAME = "WebFetch";
+export function complianceCallDenial(denies, toolName) {
+    if (denies.has("web_fetch") && toolName === WEB_FETCH_TOOL_NAME) {
+        return (`"${toolName}" is denied by this principal's compliance posture (capability "web_fetch") — ` +
+            `the call is refused by policy; do not retry it.`);
+    }
+    return undefined;
+}

package/dist/core/governance-codes.d.ts

@@ -0,0 +1,12 @@
+export type GovernanceRetryClass = "transient" | "terminal";
+export declare const GOVERNANCE_CODES: {
+    readonly "usage.window_exhausted": "terminal";
+    readonly "memory.admission_required": "transient";
+    readonly "memory.admission_denied": "terminal";
+    readonly "config.compliance_required": "transient";
+    readonly "config.compliance_denied": "terminal";
+    readonly "config.locked_key": "terminal";
+};
+export type GovernanceCode = keyof typeof GOVERNANCE_CODES;
+export declare const NON_GOVERNANCE_MEMORY_CODES: ReadonlySet<string>;
+export declare function governanceRetryClass(code: string): GovernanceRetryClass | undefined;

package/dist/core/governance-codes.js

@@ -0,0 +1,24 @@
+export const GOVERNANCE_CODES = {
+    "usage.window_exhausted": "terminal",
+    "memory.admission_required": "transient",
+    "memory.admission_denied": "terminal",
+    "config.compliance_required": "transient",
+    "config.compliance_denied": "terminal",
+    "config.locked_key": "terminal",
+};
+export const NON_GOVERNANCE_MEMORY_CODES = new Set([
+    "memory.secret_detected",
+    "memory.promotable_ungated",
+    "memory.announce_failed",
+    "memory.partition_adopt_failed",
+    "memory.partition_split",
+    "memory.tail",
+]);
+export function governanceRetryClass(code) {
+    if (Object.prototype.hasOwnProperty.call(GOVERNANCE_CODES, code)) {
+        return GOVERNANCE_CODES[code];
+    }
+    if (code.startsWith("usage."))
+        return "terminal";
+    return undefined;
+}

package/dist/core/locked-config.d.ts

@@ -0,0 +1,27 @@
+import type { RunnerDeps, TaskSpec } from "./types.js";
+import type { ToolPolicy } from "./tool-policy.js";
+export type LockedKey = "mcp" | "toolPolicy" | "compliancePosture" | "retentionPolicy";
+export declare const LOCKED_KEY_REGISTRY: {
+    readonly mcp: {
+        readonly specFields: readonly ["mcp"];
+    };
+    readonly toolPolicy: {
+        readonly specFields: readonly ["toolPolicy"];
+    };
+    readonly compliancePosture: {
+        readonly specFields: readonly [];
+    };
+    readonly retentionPolicy: {
+        readonly specFields: readonly [];
+    };
+};
+export interface LockedConfig {
+    keys: readonly LockedKey[];
+}
+export interface LockedPreflight {
+    lockedKeys: ReadonlySet<LockedKey>;
+    mcp: TaskSpec["mcp"];
+    toolPolicy: ToolPolicy | undefined;
+}
+export declare function resolveLockedKeys(config: LockedConfig | undefined): ReadonlySet<LockedKey>;
+export declare function preflightLockedConfig(spec: TaskSpec, deps: RunnerDeps): LockedPreflight;

package/dist/core/locked-config.js

@@ -0,0 +1,42 @@
+export const LOCKED_KEY_REGISTRY = {
+    mcp: { specFields: ["mcp"] },
+    toolPolicy: { specFields: ["toolPolicy"] },
+    compliancePosture: { specFields: [] },
+    retentionPolicy: { specFields: [] },
+};
+function codedError(code, message) {
+    const e = new Error(message);
+    e.code = code;
+    return e;
+}
+export function resolveLockedKeys(config) {
+    if (config === undefined)
+        return new Set();
+    const keys = new Set();
+    for (const key of config.keys) {
+        if (!Object.prototype.hasOwnProperty.call(LOCKED_KEY_REGISTRY, key)) {
+            throw codedError("config.locked_registry", `lockedConfig.keys contains "${String(key)}", which is not a member of the locked-key registry ` +
+                `(${Object.keys(LOCKED_KEY_REGISTRY).join(", ")}). A lock that does not parse must not half-arm — ` +
+                `fix the deployment's lock declaration.`);
+        }
+        keys.add(key);
+    }
+    return keys;
+}
+export function preflightLockedConfig(spec, deps) {
+    const lockedKeys = resolveLockedKeys(deps.lockedConfig);
+    for (const key of lockedKeys) {
+        for (const field of LOCKED_KEY_REGISTRY[key].specFields) {
+            if (spec[field] !== undefined) {
+                throw codedError("config.locked_key", `TaskSpec.${field} is administratively locked by this deployment (locked key "${key}") — ` +
+                    `the task-supplied value is refused wholesale (locks are config-time; there is no request-time ` +
+                    `unlock). Remove the field from the task, or change the deployment's lock configuration.`);
+            }
+        }
+    }
+    return {
+        lockedKeys,
+        mcp: lockedKeys.has("mcp") ? undefined : spec.mcp,
+        toolPolicy: lockedKeys.has("toolPolicy") ? deps.toolPolicy : (spec.toolPolicy ?? deps.toolPolicy),
+    };
+}

package/dist/core/memory-admission.d.ts

@@ -0,0 +1,47 @@
+import type { NormalizedMemorySpec } from "./memory.js";
+export type MemoryScopeOrigin = "deployment" | "request";
+export interface MemoryScopeRequest {
+    scope: string;
+    origin: MemoryScopeOrigin;
+}
+export type MemoryAdmissionVerdict = {
+    ok: true;
+    scopes: readonly string[];
+    writeScope: string | null;
+} | {
+    ok: false;
+    reason: string;
+};
+export type MemoryScopeAdmission = (input: {
+    principal: string | undefined;
+    requested: ReadonlyArray<MemoryScopeRequest>;
+    requestedWriteScope: MemoryScopeRequest | null;
+}) => MemoryAdmissionVerdict | Promise<MemoryAdmissionVerdict>;
+export interface MemoryAdmissionInput {
+    memorySpec: NormalizedMemorySpec;
+    principal: string | undefined;
+    admission: MemoryScopeAdmission | undefined;
+    deploymentScopes: ReadonlySet<string>;
+    orgMemoryDenied: boolean;
+    complianceDegraded: boolean;
+    parentAdmittedOrgScopes: readonly string[] | undefined;
+    priorOwnVerdict: OwnOrgAdmissionVerdict | undefined;
+    governedProvenance: boolean;
+}
+export interface MemoryAdmissionOutcome {
+    scopes: string[];
+    writeScope: string | null;
+    admittedOrgScopes: string[];
+    droppedDeploymentScopes: string[];
+    writeScopeNarrowed: boolean;
+    ownVerdict: OwnOrgAdmissionVerdict | undefined;
+}
+export declare function foldAdmissionFreeze(input: {
+    delegated: boolean;
+    inherited: readonly string[] | undefined;
+}): readonly string[] | undefined;
+export interface OwnOrgAdmissionVerdict {
+    scopes: readonly string[];
+    writeScope: string | null;
+}
+export declare function admitMemoryScopes(input: MemoryAdmissionInput): Promise<MemoryAdmissionOutcome>;

package/dist/core/memory-admission.js

@@ -0,0 +1,156 @@
+import { parseScopeKey } from "./memory-engine/scope-contract.js";
+function codedError(code, message) {
+    const e = new Error(message);
+    e.code = code;
+    return e;
+}
+export function foldAdmissionFreeze(input) {
+    return input.delegated ? (input.inherited ?? []) : input.inherited;
+}
+const ORG_SHAPE = /^org:/;
+function orgScopesOf(spec) {
+    if (spec.scopeContract !== "v2")
+        return { readOrg: [], writeOrg: null };
+    const readOrg = spec.scopes.filter((s) => parseScopeKey(s).kind === "org");
+    const writeOrg = spec.writeScope !== null && parseScopeKey(spec.writeScope).kind === "org" ? spec.writeScope : null;
+    return { readOrg, writeOrg };
+}
+export async function admitMemoryScopes(input) {
+    const { memorySpec, principal, admission, deploymentScopes, parentAdmittedOrgScopes } = input;
+    const governed = admission !== undefined ||
+        deploymentScopes.size > 0 ||
+        input.priorOwnVerdict !== undefined ||
+        input.governedProvenance ||
+        input.orgMemoryDenied ||
+        (parentAdmittedOrgScopes !== undefined && parentAdmittedOrgScopes.length > 0);
+    if (governed && memorySpec.scopeContract !== "v2") {
+        const shaped = [...memorySpec.scopes, ...(memorySpec.writeScope !== null ? [memorySpec.writeScope] : [])].find((s) => ORG_SHAPE.test(s));
+        if (shaped !== undefined) {
+            throw codedError("memory.admission_denied", `memory scope "${shaped}" is org-shaped but the task did not opt into the v2 scope contract ` +
+                `(memory.scopeContract: "v2") — on a deployment with org-memory admission configured, org scopes ` +
+                `outside the contract are refused (fail-closed), not mounted as opaque keys.`);
+        }
+    }
+    const { readOrg, writeOrg } = orgScopesOf(memorySpec);
+    const allOrg = [...readOrg, ...(writeOrg !== null && !readOrg.includes(writeOrg) ? [writeOrg] : [])];
+    if (allOrg.length === 0) {
+        return {
+            scopes: [...memorySpec.scopes],
+            writeScope: memorySpec.writeScope,
+            admittedOrgScopes: [],
+            droppedDeploymentScopes: [],
+            writeScopeNarrowed: false,
+            ownVerdict: undefined,
+        };
+    }
+    const priorOwn = input.priorOwnVerdict;
+    const applySessionFreeze = (proj) => {
+        let { admitted, scopes, writeScope, dropped, writeScopeNarrowed } = proj;
+        if (priorOwn !== undefined) {
+            const outsideRequest = admitted.filter((s) => !deploymentScopes.has(s) && !priorOwn.scopes.includes(s));
+            if (outsideRequest.length > 0) {
+                throw codedError("memory.admission_denied", `org memory scope(s) ${outsideRequest.map((s) => `"${s}"`).join(", ")} are outside this session's frozen ` +
+                    `admission verdict (recorded at suspend) — a session's org grant can only narrow across suspend/resume.`);
+            }
+            const frozenOut = admitted.filter((s) => !priorOwn.scopes.includes(s));
+            if (frozenOut.length > 0) {
+                dropped = [...dropped, ...frozenOut];
+                admitted = admitted.filter((s) => priorOwn.scopes.includes(s));
+                scopes = scopes.filter((s) => !frozenOut.includes(s));
+            }
+            if (writeScope !== null && writeOrg !== null && writeScope === writeOrg && priorOwn.writeScope !== writeScope) {
+                writeScope = null;
+                writeScopeNarrowed = true;
+            }
+        }
+        return {
+            scopes,
+            writeScope,
+            admittedOrgScopes: admitted,
+            droppedDeploymentScopes: dropped,
+            writeScopeNarrowed,
+            ownVerdict: { scopes: admitted, writeScope: writeScope !== null && writeOrg !== null && writeScope === writeOrg ? writeScope : null },
+        };
+    };
+    const stampedOrigins = memorySpec.scopeOrigins;
+    const originOf = (scope) => stampedOrigins !== undefined
+        ? (stampedOrigins[scope] === "deployment" ? "deployment" : "request")
+        : deploymentScopes.has(scope)
+            ? "deployment"
+            : "request";
+    const requests = allOrg.map((scope) => ({ scope, origin: originOf(scope) }));
+    const requestOrigin = requests.filter((r) => r.origin === "request");
+    if (input.orgMemoryDenied && requestOrigin.length > 0) {
+        throw codedError(input.complianceDegraded ? "config.compliance_required" : "config.compliance_denied", `org memory scope(s) ${requestOrigin.map((r) => `"${r.scope}"`).join(", ")} are denied for this principal by the ` +
+            `compliance posture (capability "org_memory_mount"${input.complianceDegraded ? "; posture resolver failing, fail-closed" : ""}).`);
+    }
+    if (parentAdmittedOrgScopes !== undefined) {
+        const exceeding = requestOrigin.filter((r) => !parentAdmittedOrgScopes.includes(r.scope));
+        if (exceeding.length > 0) {
+            throw codedError("memory.admission_denied", `delegated child requests org memory scope(s) ${exceeding.map((r) => `"${r.scope}"`).join(", ")} outside the ` +
+                `parent's frozen admission verdict — a child plane can only narrow the parent's org grant, never exceed it.`);
+        }
+    }
+    if (admission === undefined) {
+        if (requestOrigin.length > 0) {
+            throw codedError("memory.admission_required", `org memory scope(s) ${requestOrigin.map((r) => `"${r.scope}"`).join(", ")} come from the request side but this ` +
+                `deployment has no memory-scope admission resolver (RunnerDeps.memoryScopeAdmission) — refused fail-closed. ` +
+                `Deployment-pinned org scopes belong in RunnerDeps.deploymentMemoryScopes.`);
+        }
+        return applySessionFreeze({
+            admitted: allOrg,
+            scopes: [...memorySpec.scopes],
+            writeScope: memorySpec.writeScope,
+            dropped: [],
+            writeScopeNarrowed: false,
+        });
+    }
+    if (requestOrigin.length > 0 && principal === undefined) {
+        throw codedError("memory.admission_denied", `org memory scope(s) ${requestOrigin.map((r) => `"${r.scope}"`).join(", ")} require an authenticated ` +
+            `TaskSpec.principal for admission — a principal-less request cannot be admitted to a tenant plane.`);
+    }
+    let verdict;
+    try {
+        verdict = await admission({
+            principal,
+            requested: requests,
+            requestedWriteScope: writeOrg !== null ? { scope: writeOrg, origin: originOf(writeOrg) } : null,
+        });
+    }
+    catch (err) {
+        const hinted = err.retryAfterMs;
+        const e = codedError("memory.admission_required", `memory-scope admission resolver failed (${err instanceof Error ? err.message : String(err)}) — refused fail-closed.`);
+        if (typeof hinted === "number" && Number.isFinite(hinted) && hinted > 0)
+            e.retryAfterMs = hinted;
+        throw e;
+    }
+    if (!verdict.ok) {
+        throw codedError("memory.admission_denied", `org memory admission denied: ${verdict.reason}`);
+    }
+    const unrequested = verdict.scopes.filter((s) => !allOrg.includes(s));
+    if (unrequested.length > 0 || (verdict.writeScope !== null && verdict.writeScope !== writeOrg)) {
+        throw codedError("memory.admission_denied", `memory-scope admission verdict granted unrequested scope(s) ` +
+            `${[...unrequested, ...(verdict.writeScope !== null && verdict.writeScope !== writeOrg ? [String(verdict.writeScope)] : [])].map((s) => `"${s}"`).join(", ")} — ` +
+            `admission can only narrow a request, never extend it; treating the verdict as a resolver fault.`);
+    }
+    const refusedRequest = requestOrigin.filter((r) => !verdict.scopes.includes(r.scope));
+    if (refusedRequest.length > 0) {
+        throw codedError("memory.admission_denied", `org memory scope(s) ${refusedRequest.map((r) => `"${r.scope}"`).join(", ")} were not admitted — the whole ` +
+            `prepare is refused (two-state verdict; partial admission is never applied silently).`);
+    }
+    const dropped = requests.filter((r) => r.origin === "deployment" && !verdict.scopes.includes(r.scope)).map((r) => r.scope);
+    const admitted = allOrg.filter((s) => !dropped.includes(s));
+    const scopes = memorySpec.scopes.filter((s) => !dropped.includes(s));
+    let writeScope = memorySpec.writeScope;
+    let writeScopeNarrowed = false;
+    if (writeOrg !== null) {
+        if (verdict.writeScope === writeOrg && !dropped.includes(writeOrg)) {
+            writeScope = writeOrg;
+        }
+        else {
+            writeScope = null;
+            writeScopeNarrowed = true;
+        }
+    }
+    return applySessionFreeze({ admitted, scopes, writeScope, dropped, writeScopeNarrowed });
+}

package/dist/core/memory.d.ts

@@ -94,12 +94,14 @@ export interface NormalizedMemorySpec {
     writeScope: string | null;
     enabled: boolean;
     scopeContract?: "v2";
+    scopeOrigins?: Readonly<Record<string, "deployment" | "request">>;
 }
 export type MemorySpecInput = {
     scopes?: ReadonlyArray<string>;
     writeScope?: string | null;
     enabled?: boolean;
     scopeContract?: "v2";
+    scopeOrigins?: Readonly<Record<string, "deployment" | "request">>;
 };
 export declare function normalizeMemorySpec(input: MemorySpecInput | undefined): NormalizedMemorySpec | undefined;
 export declare const MAX_MEMORY_BYTES: number;

package/dist/core/memory.js

@@ -384,12 +384,13 @@ export function normalizeMemorySpec(input) {
     else {
         writeScope = scopes[scopes.length - 1];
     }
+    const origins = input.scopeOrigins !== undefined ? { scopeOrigins: input.scopeOrigins } : {};
     if (input.scopeContract === "v2") {
         for (const key of writeScope !== null ? [...scopes, writeScope] : scopes)
             parseScopeKey(key);
-        return { scopes, writeScope, enabled: input.enabled !== false, scopeContract: "v2" };
+        return { scopes, writeScope, enabled: input.enabled !== false, scopeContract: "v2", ...origins };
     }
-    return { scopes, writeScope, enabled: input.enabled !== false };
+    return { scopes, writeScope, enabled: input.enabled !== false, ...origins };
 }
 export const MAX_MEMORY_BYTES = 100 * 1024;
 export const MEMORY_WRAPPER_TAGS = ["user_memory"];

package/dist/core/retention.d.ts

@@ -0,0 +1,36 @@
+export type RetentionDeclaration = "managed" | "none";
+export interface RetentionDeclaring {
+    readonly retention?: RetentionDeclaration;
+}
+export interface RetentionPolicy {
+    maxAgeDays: number;
+}
+export interface ManagedRetentionCapability {
+    listRetentionDomains(): Promise<readonly string[]>;
+    expireCheckpoints(input: {
+        domain: string;
+        cutoffMs: number;
+    }): Promise<RetentionReceipt>;
+    deleteExpiredSessions(input: {
+        domain: string;
+        cutoffMs: number;
+    }): Promise<RetentionReceipt>;
+    deleteOrphanToolResults(input: {
+        domain: string;
+        cutoffMs: number;
+    }): Promise<RetentionReceipt>;
+}
+export interface RetentionReceipt {
+    domain: string;
+    deleted: number;
+    skipped: number;
+    tombstones: number;
+}
+export declare function assertRetentionCapability(input: {
+    policy: RetentionPolicy | undefined;
+    locked: boolean;
+    stores: ReadonlyArray<{
+        name: string;
+        store: object | undefined;
+    }>;
+}): void;

package/dist/core/retention.js

@@ -0,0 +1,31 @@
+function codedError(code, message) {
+    const e = new Error(message);
+    e.code = code;
+    return e;
+}
+export function assertRetentionCapability(input) {
+    const { policy, locked, stores } = input;
+    if (policy !== undefined && (!Number.isFinite(policy.maxAgeDays) || policy.maxAgeDays < 0)) {
+        throw codedError("config.retention_policy", `retentionPolicy.maxAgeDays must be a finite non-negative number of days (got ${String(policy.maxAgeDays)}).`);
+    }
+    const declaredRetention = (name, store) => {
+        const r = store.retention;
+        if (r === undefined || r === "none")
+            return "none";
+        if (r === "managed")
+            return "managed";
+        throw codedError("config.retention_capability", `store "${name}" declares an unparseable retention value ${JSON.stringify(r)} — expected "managed" or "none".`);
+    };
+    const declarations = stores
+        .filter((s) => s.store !== undefined)
+        .map(({ name, store }) => ({ name, retention: declaredRetention(name, store) }));
+    if (!locked || policy === undefined)
+        return;
+    const incapable = declarations.filter(({ retention }) => retention !== "managed");
+    if (incapable.length > 0) {
+        throw codedError("config.retention_capability", `retention policy is LOCKED but ${incapable.map((s) => s.name).join(", ")} ` +
+            `declare${incapable.length === 1 ? "s" : ""} retention "none" (or no declaration — read fail-closed as "none"): ` +
+            `a locked retention policy over stores that cannot delete would be "policy locked, data immortal". ` +
+            `Wire managed-retention stores, or unlock/remove the retention policy.`);
+    }
+}

package/dist/core/runner/assemble-result.js

@@ -154,7 +154,7 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     if (errorCode !== undefined && SALVAGE_ELIGIBLE_TERMINALS.has(errorCode)) {
         salvagedOutput = text.trim() || undefined;
     }
-    const retryAfterMs = errorCode === "usage.window_exhausted" ? flags.retryAfterMs : undefined;
+    const retryAfterMs = errorCode === "usage.window_exhausted" || errorCode === "memory.admission_required" ? flags.retryAfterMs : undefined;
     const { compactionMicroUsd: _internalCompaction, ...publicStats } = stats;
     void _internalCompaction;
     if (flags.unpricedSpend)

package/dist/core/runner/prepare-memory.d.ts

@@ -8,6 +8,13 @@ export interface PrepareMemoryInput {
     memoryWriteGateRef: {
         current?: BeforeWriteHook;
     };
+    admissionCtx: {
+        orgMemoryDenied: boolean;
+        complianceDegraded: boolean;
+        parentAdmittedOrgScopes: readonly string[] | undefined;
+        priorOwnVerdict: import("../memory-admission.js").OwnOrgAdmissionVerdict | undefined;
+        governedProvenance: boolean;
+    };
 }
 export interface PrepareMemoryResult {
     memoryEngineSession: Prepared["memoryEngineSession"];
@@ -16,5 +23,7 @@ export interface PrepareMemoryResult {
         path: string;
         content: string;
     }>;
+    admittedOrgScopes: readonly string[];
+    ownOrgVerdict: import("../memory-admission.js").OwnOrgAdmissionVerdict | undefined;
 }
 export declare function prepareMemory(input: PrepareMemoryInput): Promise<PrepareMemoryResult>;