@sema-agent/core 5.11.0 → 5.13.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # 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
+
+- **The compaction summary request FORKS the main conversation (CC form).** When the summary model IS the main model (no `compactionModel`/`summarize` role) and the run's latest main request is a faithful (untrimmed) projection, the summary request is now that request byte-for-byte — same system prompt, same message prefix, same tools — plus ONE appended user-role instruction message, so the provider's prompt cache re-serves the already-paid prefix instead of re-prefilling an independent serialized-conversation request at full price every boundary. Degradations keep the independent form byte-identical: a direct `maybeCompact` caller without `forkContext`; an explicit `compactionModel`; the PTL-recovery lane; a lossy request projection (guard-trim drop, clearStale content blanking, aggregate tool-result/media caps, orphan sweep) clears the fork seam for that boundary; and a fork attempt that fails as prompt-too-long, the empty-summary class (e.g. the model answered the fork with a tool call), OR a non-conforming response (the fork instruction demands the summary inside a closed `<summary>` envelope; a response without one — e.g. an obedient refusal under a BYOM system prompt that forbids summaries — is discarded, never persisted as history) falls back ONCE inside `compact()` to the independent (clamp-capable) form — a generic summarizer failure stays terminal (one call per pass). The fork is also refused when the snapshot's served model differs from the summary model (mid-run budget degradation): the model is part of the provider cache key, so that fork would pay a full prefill for nothing. **Consumer flips**: probes pinning the OLD summary-request shape (independent `SUMMARIZATION_SYSTEM_PROMPT` + single serialized user message) red — detect a summary request as EITHER form (independent system prompt, OR main prefix + trailing user instruction mentioning the structured summary). `MaybeCompactOptions.forkContext` (accessor) and a trailing optional `compact(..., forkContext)` parameter are the additive seams.
+
+- **Default `keepRecentTokens` drops 20000 → 0 (full compaction, CC form).** With the knob unset, a landed compaction now keeps NO verbatim token budget — the summary replaces the compacted region entirely (the cut still lands on the nearest valid floor, so tool pairs and an in-progress turn's suffix stay intact; the turn-prefix leg summarizes the rest). Explicit `keepRecentTokens` values keep their exact meaning and are the opt-back. **Consumer flips**: probes pinning "pre-compaction verbatim text survives after a default-settings compaction" red.
+
+- **The post-compact background-task restatement is DEFAULT ON** (`attachments.backgroundTasks` becomes `boolean`; explicit `false` is the opt-out — same contract as the listing family). CC hard-codes this behavior; the opt-in default left every non-shell host with a window after a compaction where the model had no context evidence of an in-flight task — duplicate spawns and premature turn ends. Explicit `true`/`false` keep their exact meaning; only the absent case flips. The zero-config fast path (no attachment state at all) now applies only to runs that explicitly opt out — the residual cost on default runs is one cadence-clock pass per message (reducers stay type-gated no-ops). **Consumer flips**: a probe pinning "no `background_tasks` frame without opt-in" reds; the frame itself is byte-unchanged.
+
+### Added
+
+- **`compaction cannot help` — honest disclosure for an oversized fixed prefix.** When the fixed per-request prefix (system prompt + tool schemas) alone meets/exceeds the compaction trigger threshold, the run emits one `onError` frame (`phase:"config"`) naming the numbers, at trigger-geometry derivation time — compaction only shrinks conversation history, so such a run re-triggers or overflows no matter how well summaries land. One frame per run; geometry itself unchanged.
+
+- **`compaction.staleToolResultOffload` — opt-in stale tool-result offload (request-projection clear).** In the outgoing request, same-tool results older than the most recent `keepRecentPerTool` (default 3) are replaced by a short pointer (persisted under the design/30 tool-result store, readable back via `read_tool_result`) once the swap saves ≥ `minSavingsChars` (default 2000). Refs are content-digested (`<toolCallId>_s<sha256-128bit>`), so recurring tool-call ids — which carry no cross-turn uniqueness contract under BYOM — cannot make one pointer resolve to another result's content (collision-resistant at 128 bits; tool results are untrusted text, so the digest width is chosen adversarially, not for accidental collisions). Replacement decisions are deterministic and one-way (an already-replaced result renders the same pointer bytes on every later request — no flip-flop churn); the verbatim→pointer transition itself is a bounded once-per-result cache break, amortized by the `minSavingsChars` floor. The session transcript is never rewritten. Absent (default) = requests byte-identical to before; knob set while the offload store is disabled = one `config` onError and the knob stays inert.
+
+- **A PARKED child joins the post-compact restatement.** The snapshot filter (pending/running) gains `parked`, rendered as `parked awaiting an out-of-band approval — do NOT re-issue the gated call` — a child waiting at an approval gate is exactly the task a post-compact model must not re-issue.
+
+- **The walltime axis feeds the limit-approach frames.** A caller-armed hard deadline (`limits.maxWalltimeMs`) now contributes its fill ratio to the design/164 converge/deliver advisories alongside tokens/cost/turns — previously the deadline was the only armed ceiling that never warned, so the model learned it was out of time by being cut. Same thresholds (default 80%/95%), same caller-armed rule, same per-slice clock the enforcement reads; frames name the axis (`walltime budget`). Consumer note: a probe pinning "no `limit_approach` steering on a walltime-only run" reds.
+
+### Fixed
+
+- **The summarization instruction carries a fabricated-user-turn guard** (both prompt variants and the fork-form instruction): only real user-role messages count as user messages — a `"user: ..."`/`"Human: ..."` line quoted inside assistant output is the assistant's own text, never attribute it to the user.
+
+- **`summarize` role doc corrected**: the main model is the correct default baseline (fork form amortizes the prefix via prompt cache); a separate cheap model is an explicit quality-for-price tradeoff, not the recommended posture.
+
+- **The exec-gate's buffered leg keeps ran-then-cut partial output.** A timed-out/aborted setup step on a non-streaming env reported empty stdout/stderr even though the `ExecutionError` carried the captured partials — the streaming leg already kept its chunks. Partials now ride the step result, clamped at `maxOutputBytes`.
+
 ## 5.11.0 — 2026-08-04
 
 ### 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/auto-compaction.d.ts

@@ -1,5 +1,5 @@
 import { type AgentMessage, type CompactionSettings, type Session, type ThinkingLevel } from "../internal/harness.js";
-import type { Model } from "../internal/llm.js";
+import type { Message, Model, Tool } from "../internal/llm.js";
 import type { Hooks } from "./hooks.js";
 import type { TraceEvent } from "./trace.js";
 import type { Brain } from "./types.js";
@@ -20,6 +20,16 @@ export interface CompactionWindowSafetyInfo {
 }
 export declare const STALE_ANCHOR_STRUCTURAL_MARGIN = 2;
 export declare function sanitizeCompactionSettings(settings: CompactionSettings, contextWindow: number | undefined): CompactionSettings;
+export interface CompactionForkContext {
+    systemPrompt?: string;
+    systemBlocks?: Array<{
+        text: string;
+        cacheControlBoundary: boolean;
+    }>;
+    messages: Message[];
+    tools?: Tool[];
+    modelId?: string;
+}
 export interface MaybeCompactOptions {
     onNotifyError?: (failure: import("./safe-notify.js").SafeNotifyFailure) => void;
     session: Session;
@@ -34,6 +44,7 @@ export interface MaybeCompactOptions {
     };
     model: Model;
     compactionModel?: Model;
+    forkContext?: () => CompactionForkContext | undefined;
     brain: Brain;
     getApiKeyAndHeaders?: (model: Model) => Promise<{
         apiKey: string;

package/dist/core/auto-compaction.js

@@ -234,12 +234,14 @@ export async function maybeCompact(opts) {
         const auth = await opts.getApiKeyAndHeaders?.(summaryModel);
         const summarySignal = opts.signal;
         const runtime = brainToRuntime(opts.brain);
+        const forkCandidate = opts.compactionModel === undefined ? opts.forkContext?.() : undefined;
+        const forkContext = forkCandidate !== undefined && (forkCandidate.modelId === undefined || forkCandidate.modelId === summaryModel.id) ? forkCandidate : undefined;
         let res;
         summaryStartAt = Date.now();
         try {
             res = await compact(prep.value, summaryModel, auth?.apiKey, auth?.headers, effectiveInstructions, summarySignal, opts.thinking, undefined, runtime, undefined, opts.onInputTruncated, () => {
                 ptlRetries += 1;
-            });
+            }, forkContext);
         }
         finally {
             summaryEndAt = Date.now();

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/exec-gate.js

@@ -65,7 +65,18 @@ async function runBufferedStep(env, step, options, maxOutputBytes) {
         abortSignal: options.signal,
     });
     if (!res.ok) {
-        return { label, command: step.command, exitCode: null, stdout: "", stderr: "", ok: false, errorCode: res.error.code };
+        const po = clampBytes(res.error.partialStdout ?? "", maxOutputBytes);
+        const pe = clampBytes(res.error.partialStderr ?? "", maxOutputBytes);
+        return {
+            label,
+            command: step.command,
+            exitCode: null,
+            stdout: po.text,
+            stderr: pe.text,
+            ok: false,
+            errorCode: res.error.code,
+            truncated: po.truncated || pe.truncated,
+        };
     }
     const so = clampBytes(res.value.stdout, maxOutputBytes);
     const se = clampBytes(res.value.stderr, maxOutputBytes);

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"];