@sema-agent/core 7.51.0 → 7.51.2

package/dist/core/runner/prepare-policy-chain.js

@@ -7,6 +7,7 @@ import { cloneObserverInput, resolveHookTimeoutMs } from "../hooks.js";
 import { assertHookSeatsCallable } from "../hook-seats.js";
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers } from "../permission-rules.js";
 import { isIsolated } from "../remote-env.js";
+import { earlierGrammarAdvisory } from "../session-policy-store.js";
 import { askApproverIdentity, attest, attestationOf, checkToolPolicyProjection, combinePolicies, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, durableParkOptInDeclared, isLiveApproverSeat, mergeAttestation, refuseOutOfContractDecision, resolveAsk, toolPolicyNameSets, withAttestation, wrapToolPolicy } from "../tool-policy.js";
 import { judgeRuleToolName, mountedToolNames } from "../tool-name-aliases.js";
 import { approvalCardMemberOf } from "../tool-roster.js";
@@ -110,6 +111,7 @@ export async function preparePolicyChain(input) {
         catch {
         }
     };
+    const announceEarlierGrammar = (rulesSessionId) => (entries) => deps.onError?.(Object.assign(new Error(earlierGrammarAdvisory(rulesSessionId, entries)), { code: "config.session_rules_earlier_grammar" }), { phase: "config", sessionId });
     let sessionRulePolicy;
     if (deps.sessionPolicyStore && spec.sessionId) {
         const store = deps.sessionPolicyStore;
@@ -125,7 +127,7 @@ export async function preparePolicyChain(input) {
                 rules: row,
             };
         };
-        sessionRulePolicy = createSessionRulePolicy({ seed, read: createLiveSessionRules(store, { ...sessionRuleKey, seed }, { onUnreadable: announceSessionRulesUnreadable, onEnforced: publishOwnRules }) }, { env: executionEnv, rootPath: taskRootFinal, toolEffects, anchors: pathRuleAnchors.leg });
+        sessionRulePolicy = createSessionRulePolicy({ seed, read: createLiveSessionRules(store, { ...sessionRuleKey, seed }, { onUnreadable: announceSessionRulesUnreadable, onEnforced: publishOwnRules }) }, { env: executionEnv, rootPath: taskRootFinal, toolEffects, anchors: pathRuleAnchors.leg, onEarlierGrammar: announceEarlierGrammar(sessionRuleKey.sessionId) });
         if (rules)
             publishOwnRules(rules);
     }
@@ -146,7 +148,7 @@ export async function preparePolicyChain(input) {
             ...(deps.sessionPolicyStore
                 ? { read: createLiveSessionRules(deps.sessionPolicyStore, { sessionId: snap.sessionId, ...(snap.principal !== undefined ? { principal: snap.principal } : {}), seed }, { onUnreadable: announceSessionRulesUnreadable, onEnforced: publishAncestorRules }) }
                 : {}),
-        }, { env: executionEnv, rootPath: taskRootFinal, toolEffects, anchors: pathRuleAnchors.leg }));
+        }, { env: executionEnv, rootPath: taskRootFinal, toolEffects, anchors: pathRuleAnchors.leg, onEarlierGrammar: announceEarlierGrammar(snap.sessionId) }));
     }
     const frozenConstraintLayers = (seedInheritedGate?.constraintChain ?? [])
         .filter((e) => !("opaque" in e))

package/dist/core/runner/session-rule-policy.d.ts

@@ -111,7 +111,8 @@ export declare function createLiveSessionRules(store: SessionPolicyStore, floor:
  *    (a line it cannot read against the rule is refused too), a path rule over every view of the call's target.
  *  - `toolAllow` (if set) → deny any call no entry admits (the matcher's allow reading in the `narrowing` posture: every
  *    segment of a command line named by an entry; never the allow layer's auto-mode strip), naming the uncovered segment.
- *  - an entry that reads as nothing → in no row (it guards and grants nothing; the prepare-time audit names it).
+ *  - an entry that reads as nothing → in no row (it guards and grants nothing; the prepare-time audit names it, or
+ *    `onEarlierGrammar`, once per distinct set, when its snapshot's own earlier grammar reads it so).
  *  - a snapshot the shape reading refuses → deny every call, saying what it holds (never its text).
  *  - `allowDirs` (if set) → a WRITE tool must land inside one of the dirs (resolved via `canonicalizeTarget`,
  *    so a symlink can't carry across a write out); a write-capable tool that cannot be path-confined (e.g. `bash`)
@@ -131,4 +132,5 @@ export declare function createSessionRulePolicy(rules: SessionPermissionRules |
     rootPath?: string;
     toolEffects?: ReadonlyMap<string, ToolEffect>;
     anchors?: PathRuleBases;
+    onEarlierGrammar?: (entries: readonly string[]) => void;
 }): NamedToolPolicy;

package/dist/core/runner/session-rule-policy.js

@@ -1,6 +1,6 @@
 import { canonicalizeTarget, isWinFormPath, pathFamilyOf, writeTargetPath } from "../../tools/fs/safety.js";
-import { continuesLineage, readSessionRulesShape } from "../session-policy-store.js";
-import { compileAllowList, compiledEntryName, judgeAllowEntries, uncoveredCommandSegment } from "../allow-entry.js";
+import { compileSessionRuleBucket, continuesLineage, earlierGrammarAnnouncer, readSessionRulesShape } from "../session-policy-store.js";
+import { compiledEntryName, judgeAllowEntries, uncoveredCommandSegment } from "../allow-entry.js";
 import { inlineUntrusted } from "../untrusted-text.js";
 import { callTargetReadingOf, pathTargetBaseOf, readCallTarget } from "../effective-path-target.js";
 import { egressThrownText } from "../untrusted-egress.js";
@@ -104,26 +104,27 @@ export function createLiveSessionRules(store, floor, hooks) {
         return p;
     };
 }
-function compileSessionRules(rules) {
+function compileSessionRules(rules, announceEarlier) {
     const shaped = readSessionRulesShape(rules);
     if ("fault" in shaped) {
         const { field, got } = shaped.fault;
         const what = got === "not a rule bucket" ? "a key that is no rule bucket" : field === "" ? `a value that is ${got}, not an object of rule buckets` : `${field} holding ${got}`;
         return { deny: [], allow: undefined, allowDirs: undefined, pathRows: false, names: { deny: [], allow: [] }, unreadable: `the session rules cannot be read as rules (they hold ${what}) — every call is refused until they are rewritten` };
     }
-    const { toolDeny, toolAllow, allowDirs } = shaped.rules;
-    const denyList = compileAllowList(toolDeny ?? [], "deny");
-    const allowList = toolAllow === undefined ? undefined : compileAllowList(toolAllow, "allow");
+    const { toolAllow, allowDirs } = shaped.rules;
+    const denyList = compileSessionRuleBucket(shaped.rules, "toolDeny");
+    const allowList = toolAllow === undefined ? undefined : compileSessionRuleBucket(shaped.rules, "toolAllow");
     const rowsOf = (behavior, list) => list.rows.map((r) => ({ behavior, entry: r.entry, compiled: r.compiled }));
     const deny = rowsOf("deny", denyList);
     const allow = allowList === undefined ? undefined : rowsOf("allow", allowList);
-    const namesOf = (rows, list) => [...rows.map((r) => compiledEntryName(r.compiled)), ...(list?.inert ?? []).map((i) => i.entry)];
+    const named = (list, earlier) => (list?.inert ?? []).filter((i) => (i.reason === "earlier_grammar") === earlier).map((i) => i.entry);
+    announceEarlier(named(allowList, true));
     return {
         deny,
         allow,
         allowDirs: allowDirs !== undefined && allowDirs.length > 0 ? allowDirs : undefined,
         pathRows: [...deny, ...(allow ?? [])].some((r) => r.compiled.kind === "path"),
-        names: { deny: namesOf(deny, denyList), allow: namesOf(allow ?? [], allowList) },
+        names: { deny: [...deny.map((r) => compiledEntryName(r.compiled)), ...named(denyList, false)], allow: [...(allow ?? []).map((r) => compiledEntryName(r.compiled)), ...named(allowList, false)] },
     };
 }
 export function createSessionRulePolicy(rules, opts) {
@@ -132,11 +133,12 @@ export function createSessionRulePolicy(rules, opts) {
     const source = "seed" in rules ? rules : { seed: rules };
     const seed = source.seed;
     const readRules = source.read ?? (() => Promise.resolve(seed));
+    const announceEarlier = earlierGrammarAnnouncer(opts.onEarlierGrammar);
     let compiledFor;
     let compiled;
     const compile = (r) => {
         if (compiled === undefined || compiledFor !== r) {
-            compiled = compileSessionRules(r);
+            compiled = compileSessionRules(r, announceEarlier);
             compiledFor = r;
         }
         return compiled;

package/dist/core/runner/tool-output-projection.d.ts

@@ -4,6 +4,11 @@
  * state, zero runtask coupling — the module-level inputs are the text cap below and the shared media budget default
  * (`mediaBudgetBytes`); the leg hands in its own `mediaByteCapBytes`.
  */
+/** A block's own size in characters — the ONE counter `tool_end.totalChars` adds up over a tool result's blocks (a
+ *  consumer that re-renders a result sums the same function): a text block its text plus whatever else it carries at
+ *  its serialized length (the contract's text block carries nothing else), a media block its payload, any other block
+ *  its serialization. */
+export declare const toolOutputBlockChars: (b: unknown) => number;
 type ToolOutput = {
     output: unknown;
     truncated: boolean;

package/dist/core/runner/tool-output-projection.js

@@ -4,9 +4,9 @@ import { engineCardTypes } from "../tool-registry.js";
 import { readMember } from "../thrown-value.js";
 const MAX_TOOL_END_OUTPUT_CHARS = 16384;
 const marker = (n) => `…[+${n} chars truncated]`;
-const ownChars = (b) => isTextBlock(b) ? b.text.length + (JSON.stringify({ ...b, type: undefined, text: undefined })?.length ?? 2) - 2 : isMediaBlock(b) ? b.data.length : (JSON.stringify(b)?.length ?? 0);
+export const toolOutputBlockChars = (b) => isTextBlock(b) ? b.text.length + (JSON.stringify({ ...b, type: undefined, text: undefined })?.length ?? 2) - 2 : isMediaBlock(b) ? b.data.length : (JSON.stringify(b)?.length ?? 0);
 const boundTextLane = (blocks, lane) => {
-    const sized = lane.map((i) => ({ i, size: ownChars(blocks[i]) }));
+    const sized = lane.map((i) => ({ i, size: toolOutputBlockChars(blocks[i]) }));
     const stream = sized.reduce((n, { size }, k) => n + size + (k > 0 ? 1 : 0), 0);
     const forms = new Map();
     let used = 0;
@@ -61,7 +61,7 @@ const project = (content, mediaByteCapBytes) => {
         return { output: content, truncated: false };
     let next = 0;
     const output = content.flatMap((_, i) => (media[i] ? (fit.blocks[next++] ?? []) : text.forms.has(i) ? [text.forms.get(i)] : []));
-    return { output, truncated: true, totalChars: content.reduce((n, b) => n + ownChars(b), 0) };
+    return { output, truncated: true, totalChars: content.reduce((n, b) => n + toolOutputBlockChars(b), 0) };
 };
 export const toolOutputFrom = (result, mediaByteCapBytes) => {
     try {

package/dist/core/secret-env.d.ts

@@ -4,7 +4,8 @@
  * A child the engine spawns may run what the MODEL chose (a tool shell, a gate over model-written code, a language
  * server). Under the `"scrub"` policy (the default) it inherits every variable but those the judgment below names —
  * deleted whole, never rewritten; `"all"` and a `string[]` allow list are the caller's explicit alternatives
- * ({@link inheritedHostEnv}). One judgment per variable ({@link classifySecretEnvEntry}), the first rule that answers:
+ * ({@link inheritedHostEnv}). Whatever the policy, a name the deployment declares as its own credential
+ * ({@link declareWithheldEnv}) is never inherited. One judgment per variable ({@link classifySecretEnvEntry}), the first rule that answers:
  *   1. exempt — git's environment config and the proxy variables, handed on as written ({@link isExemptEnvName});
  *   2. `exact-name` — a known credential name (the vocabulary's exact env names);
  *   3. `prefix-rule` — the OpenTelemetry settings ({@link OTEL_ENV_RE});
@@ -25,10 +26,11 @@ import { type EngineNotice } from "./engine-notice.js";
  *  Reads the first {@link VALUE_SCAN_LIMIT} code units. The value half of the judgment, exported apart from the env
  *  entry's exemptions ({@link isExemptEnvName}): a caller holding a value that is no environment variable asks this. */
 export declare function looksLikeCredentialValue(value: string): boolean;
-/** Which rule withheld an entry. */
-export type SecretEnvFindingKind = "exact-name" | "name-rule" | "namespace-rule" | "prefix-rule" | "value-rule";
-/** One env entry the `"scrub"` policy withheld (deleted): its name — never its value, so the record is loggable —, the
- *  rule that withheld it, how strong that claim is, and the minting module. */
+/** Which rule withheld an entry: one of the scrub's rules, or `own-credential` — the deployment declared the name as its
+ *  own credential ({@link declareWithheldEnv}), which every policy withholds. */
+export type SecretEnvFindingKind = "exact-name" | "name-rule" | "namespace-rule" | "prefix-rule" | "value-rule" | "own-credential";
+/** One env entry withheld (deleted) from a child's environment: its name — never its value, so the record is
+ *  loggable —, the rule that withheld it, how strong that claim is, and the minting module. */
 export interface SecretEnvFinding {
     key: string;
     kind: SecretEnvFindingKind;
@@ -49,16 +51,44 @@ export declare function scrubSecretEnv(env: NodeJS.ProcessEnv, findings?: Secret
 /** How much of this process's environment a child spawned on this host inherits — the `inheritEnv` value. */
 export type InheritEnvPolicy = "all" | "scrub" | string[];
 /**
- * The environment a child spawned ON THIS HOST inherits, by an {@link InheritEnvPolicy}: `"scrub"` (and absent) is
- * this process's environment through {@link scrubSecretEnv}; `"all"` is this process's environment
- * verbatim (the explicit opt-out); a `string[]` is exactly the named variables that are set, verbatim — a strict allow
- * list, so a name it leaves out (`PATH` included) is not inherited. `findings` collects what the scrub withheld, and
- * only the `"scrub"` arm adds to it. Any other value reads as `"scrub"`; both spawn sites that take a policy — the
- * tool shell's `NodeExecutionEnv` (at construction) and the oracle gate (per gate) — refuse a malformed one through
- * {@link inheritEnvPolicyProblem} before it gets here.
+ * Declare the names of this deployment's OWN credentials in this process's environment — the engine's or its host's:
+ * an approval bearer, a service token. From then on no child spawned on this host inherits one, whatever the policy:
+ * every spawn site reads its environment through {@link inheritedHostEnv}, which subtracts them from `"all"` and from
+ * the scrub's result (each one present is a finding of kind `own-credential`), and {@link inheritEnvPolicyProblem}
+ * refuses an allow list naming one. Compared as the platform compares variable names: exactly, but case-blind on
+ * Windows. A variable a host hands a child itself (a shell's `shellEnv`, a per-exec `env`, a language server's `env`, an MCP server entry's `env`)
+ * is its explicit grant and is not read against the list.
+ *
+ * Declared once, at start-up, before anything spawns; a later call REPLACES the list (a configuration reload), read
+ * from the next spawn on — a spawn whose environment is already read (one announcing its findings) keeps it. The
+ * list is copied. A malformed list — not an array, an entry that is no variable name, or a name the host hands every
+ * child anyway ({@link runtimeSuppliedEnv}) — throws and leaves the declaration as it was.
+ *
+ * Two Windows readings, measured on a real machine: a withheld name that the child's own shell or runtime re-creates
+ * with a DEFAULT of its own (`ComSpec`, `PATHEXT`, `HOME`, `CommonProgramFiles`, …) shows up in the child's table with
+ * that default, never with this process's value — withheld, not leaked; and the disclosure (`detail.ownCredentials`)
+ * spells each withheld name as this process's environment spells it, not as the declaration spelled it.
+ */
+export declare function declareWithheldEnv(names: readonly string[]): void;
+/** Test seam: never called by production code (a host re-declares `[]`). */
+export declare function __resetWithheldEnv(): void;
+/**
+ * THE environment a child spawned ON THIS HOST inherits: the policy's arm, less the declared own credentials
+ * ({@link declareWithheldEnv}). The arms: `"scrub"` (and absent) is this process's environment through
+ * {@link scrubSecretEnv}; `"all"` is this process's environment as written; a `string[]` is exactly the named
+ * variables that are set, as written — a strict allow list, so a name it leaves out (`PATH` included) is not
+ * inherited. `findings` collects every entry withheld: the scrub's, and each declared own credential the arm held.
+ *
+ * A policy {@link inheritEnvPolicyProblem} refuses throws that reason HERE, at every spawn, read against the
+ * declaration as it stands: a value that is no policy at all (never read as the scrub), and an allow list naming a
+ * declared own credential — whenever the declaration was made, so the refusal at spawn time is the invariant. The
+ * spawn sites that take a policy (the tool shell's `NodeExecutionEnv` at construction, the oracle gate per gate) also
+ * ask first, so a host that declared before building them hears it at start-up.
  */
 export declare function inheritedHostEnv(policy: InheritEnvPolicy | undefined, findings?: SecretEnvFinding[]): NodeJS.ProcessEnv;
-/** Why `value` is not an {@link InheritEnvPolicy} (absent counts as one — the scrub), or `undefined` when it is. */
+/** Why `value` is not an {@link InheritEnvPolicy} this deployment can read (absent counts as one — the scrub), or
+ *  `undefined` when it is: a malformed policy, or an allow list naming one of the declared own credentials
+ *  ({@link declareWithheldEnv}, compared as it says). */
 export declare function inheritEnvPolicyProblem(value: unknown): string | undefined;
 /** Test seam: never called by production code. */
 export declare function __resetSecretEnvScrubNoticeAnnouncement(): void;
@@ -66,7 +96,8 @@ export declare function __resetSecretEnvScrubNoticeAnnouncement(): void;
  * The ONE disclosure point for a scrub's withheld keys. Routed through {@link deliverEngineNotice} — the
  * engine's one notice throat — so a wired `onNotice` seat REPLACES the console line exactly as every
  * other `EngineNotice` does, and an absent seat prints the same words `console.warn` always printed here.
- * `detail.names` carries every withheld key. Once per PROCESS, never per call or per site; an EMPTY
- * findings array is a no-op.
+ * `detail.names` carries every withheld key; `detail.ownCredentials`, present only when one was withheld, the
+ * subset withheld as the deployment's declared own credentials (kind `own-credential`) rather than by the scrub.
+ * Once per PROCESS, never per call or per site; an EMPTY findings array is a no-op.
  */
 export declare function announceSecretEnvScrub(onNotice: ((notice: EngineNotice) => void) | undefined, findings: readonly SecretEnvFinding[]): void;

package/dist/core/secret-env.js

@@ -1,4 +1,5 @@
 import { CREDENTIAL_VOCABULARY, envNameView, splitCamelCase } from "./credential-vocabulary.js";
+import { DEFAULT_INHERITED_ENV_VARS } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { deliverEngineNotice } from "./engine-notice.js";
 const GIT_CONFIG_ENV_RE = /^GIT_CONFIG_(?:COUNT|PARAMETERS|(?:KEY|VALUE)_[0-9]+)$/;
 const PROXY_ENV_RE = /^(?:(?:https?|ftp|all|no)_proxy|npm_config_(?:https?_)?proxy|npm_config_noproxy|yarn_proxy|(?:yarn|global_agent|docker|claude_code)_(?:https?|no)_proxy|cloudsdk_proxy_[a-z]+|electron_get_use_proxy)$/i;
@@ -93,6 +94,7 @@ const SECRET_ENV_KIND_CONFIDENCE = {
     "exact-name": "high",
     "prefix-rule": "high",
     "value-rule": "high",
+    "own-credential": "high",
     "name-rule": "medium",
     "namespace-rule": "medium",
 };
@@ -131,29 +133,91 @@ export function scrubSecretEnv(env, findings) {
     }
     return Object.fromEntries(kept);
 }
+function envNameKey(name) {
+    return process.platform === "win32" ? name.toUpperCase() : name;
+}
+const UNPAIRED_SURROGATE_RE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+function variableNameListProblem(label, value) {
+    const bad = value.findIndex((k) => typeof k !== "string" || k.length === 0 || /[=\0\s]/.test(k) || UNPAIRED_SURROGATE_RE.test(k));
+    if (bad === -1)
+        return undefined;
+    const k = value[bad];
+    const why = typeof k !== "string" ? typeof k : k === "" ? "an empty string" : `a name holding ${k.includes("=") ? "\"=\"" : k.includes("\0") ? "a NUL" : /\s/.test(k) ? "whitespace" : "an unpaired surrogate"}`;
+    return `${label}[${bad}] is not a variable name (got ${why})`;
+}
+const WINDOWS_REQUIRED_ENV = Object.freeze(["HOMEDRIVE", "HOMEPATH", "LOGONSERVER", "PATH", "SYSTEMDRIVE", "SYSTEMROOT", "TEMP", "USERDOMAIN", "USERNAME", "USERPROFILE", "WINDIR"]);
+function runtimeSuppliedEnv() {
+    return ["NODE_V8_COVERAGE", ...DEFAULT_INHERITED_ENV_VARS, ...(process.platform === "win32" ? WINDOWS_REQUIRED_ENV : [])];
+}
+const WITHHELD_ENV = Symbol.for("sema.core.withheldEnv");
+const NOTHING_WITHHELD = Object.freeze([]);
+const withheldEnvOf = () => {
+    const held = Reflect.get(globalThis, WITHHELD_ENV);
+    return Array.isArray(held) ? held : NOTHING_WITHHELD;
+};
+const setWithheldEnv = (names) => {
+    Reflect.set(globalThis, WITHHELD_ENV, Object.freeze([...names]));
+};
+export function declareWithheldEnv(names) {
+    const value = names;
+    if (!Array.isArray(value))
+        throw new Error(`declareWithheldEnv: the list must be an array of variable names (got ${typeof value === "string" ? JSON.stringify(value) : value === null ? "null" : typeof value})`);
+    const problem = variableNameListProblem("names", value);
+    if (problem !== undefined)
+        throw new Error(`declareWithheldEnv: ${problem}`);
+    const supplied = new Set(runtimeSuppliedEnv().map(envNameKey));
+    const unwithholdable = value.findIndex((k) => supplied.has(envNameKey(k)));
+    if (unwithholdable !== -1)
+        throw new Error(`declareWithheldEnv: names[${unwithholdable}] is ${value[unwithholdable]}, which a child is handed from this process's environment whatever the spawn passes (by Node, the MCP stdio transport or Windows) — it cannot be withheld`);
+    setWithheldEnv(value);
+}
+export function __resetWithheldEnv() {
+    setWithheldEnv([]);
+}
+function withholdOwnCredentials(inherited, findings) {
+    if (withheldEnvOf().length === 0)
+        return inherited;
+    const own = new Set(withheldEnvOf().map(envNameKey));
+    const kept = [];
+    for (const key of Object.keys(inherited)) {
+        if (!own.has(envNameKey(key)))
+            kept.push([key, inherited[key]]);
+        else
+            findings?.push({ key, kind: "own-credential", confidence: SECRET_ENV_KIND_CONFIDENCE["own-credential"], source: "secret-env" });
+    }
+    return Object.fromEntries(kept);
+}
+function policyShapeProblem(value) {
+    if (value === undefined || value === "all" || value === "scrub")
+        return undefined;
+    if (Array.isArray(value))
+        return variableNameListProblem("inheritEnv", value);
+    return `inheritEnv must be "scrub", "all" or a list of variable names (got ${typeof value === "string" ? JSON.stringify(value) : value === null ? "null" : typeof value})`;
+}
 export function inheritedHostEnv(policy, findings) {
+    const problem = inheritEnvPolicyProblem(policy);
+    if (problem !== undefined)
+        throw new Error(problem);
+    let arm;
     if (policy === "all")
-        return { ...process.env };
-    if (Array.isArray(policy)) {
-        const picked = {};
+        arm = { ...process.env };
+    else if (Array.isArray(policy)) {
+        arm = {};
         for (const k of policy)
             if (process.env[k] !== undefined)
-                picked[k] = process.env[k];
-        return picked;
+                arm[k] = process.env[k];
     }
-    return scrubSecretEnv(process.env, findings);
+    else
+        arm = scrubSecretEnv(process.env, findings);
+    return withholdOwnCredentials(arm, findings);
 }
 export function inheritEnvPolicyProblem(value) {
-    if (value === undefined || value === "all" || value === "scrub")
-        return undefined;
-    if (Array.isArray(value)) {
-        const bad = value.findIndex((k) => typeof k !== "string" || k.length === 0 || /[=\0]/.test(k));
-        if (bad === -1)
-            return undefined;
-        const k = value[bad];
-        return `inheritEnv[${bad}] is not a variable name (got ${typeof k !== "string" ? typeof k : k === "" ? "an empty string" : `a name holding ${k.includes("=") ? "\"=\"" : "a NUL"}`})`;
-    }
-    return `inheritEnv must be "scrub", "all" or a list of variable names (got ${typeof value === "string" ? JSON.stringify(value) : value === null ? "null" : typeof value})`;
+    const shape = policyShapeProblem(value);
+    if (shape !== undefined || !Array.isArray(value) || withheldEnvOf().length === 0)
+        return shape;
+    const own = new Set(withheldEnvOf().map(envNameKey));
+    const named = value.findIndex((k) => own.has(envNameKey(k)));
+    return named === -1 ? undefined : `inheritEnv[${named}] names ${value[named]}, which is this deployment's own credential and cannot be inherited by a child (a configuration error: no retry succeeds until the policy or the declaration changes)`;
 }
 let secretEnvScrubNoticeAnnounced = false;
 export function __resetSecretEnvScrubNoticeAnnouncement() {
@@ -164,9 +228,11 @@ export function announceSecretEnvScrub(onNotice, findings) {
         return;
     secretEnvScrubNoticeAnnounced = true;
     const names = findings.map((f) => f.key);
+    const ownCredentials = findings.filter((f) => f.kind === "own-credential").map((f) => f.key);
+    const own = ownCredentials.length > 0 ? `; ${ownCredentials.length} of them this deployment's own credential(s) (${ownCredentials.join(", ")})` : "";
     deliverEngineNotice(onNotice, {
         code: "config.secret_env_scrubbed",
-        message: `secret_env_scrubbed: ${findings.length} env key(s) withheld from a spawned child's environment (${names.join(", ")}) — once per process; wire onNotice for the structured form`,
-        detail: { names },
+        message: `secret_env_scrubbed: ${findings.length} env key(s) withheld from a spawned child's environment (${names.join(", ")})${own} — once per process; wire onNotice for the structured form`,
+        detail: { names, ...(ownCredentials.length > 0 ? { ownCredentials } : {}) },
     });
 }

package/dist/core/session-policy-store.d.ts

@@ -18,10 +18,13 @@
  *   (`readRuleEntry`, allow-entry.ts): a tool name, a protocol namespace, a shell command rule (`Bash(git push:*)`), a
  *   path rule, a name or host rule. Entries are stored as written; every station that validates, compares, matches or
  *   names one reads that reader's answer ({@link judgeSessionRulesWrite}, {@link loosenReasons}, the run-time layer).
+ * - **a row keeps its grammar**: the write judge stamps the grammar it read the entries in ({@link SESSION_RULES_GRAMMAR}), and
+ *   every station reads a row's entries in the grammar the row carries ({@link readSessionRulesShape}) — a row stored before
+ *   the stamp keeps the reading it was written under, so an upgrade never turns a stored entry into a grant.
  * - **NOT A SANDBOX**: a shell command rule reads the command line the call carries (every program run in its connector
  *   chain); the real isolation boundary is the executionEnv, never these rules.
  */
-import { type AllowEntryInertDetail, type AllowEntryInertReason } from "./allow-entry.js";
+import { compileAllowList, type AllowEntryInertDetail, type AllowEntryInertReason } from "./allow-entry.js";
 /** The per-session rules. All optional; an absent bucket imposes no constraint of that kind. */
 export interface SessionPermissionRules {
     /** If set, ONLY the calls these entries admit are allowed — a narrowing allowlist: a call no entry admits is refused.
@@ -45,6 +48,14 @@ declare const SESSION_RULE_BUCKETS: {
 export type SessionRuleEntryField = {
     [K in keyof typeof SESSION_RULE_BUCKETS]: (typeof SESSION_RULE_BUCKETS)[K] extends "dirs" ? never : K;
 }[keyof typeof SESSION_RULE_BUCKETS];
+/**
+ * The rule grammar this engine reads a session's rule entries in: the `grammar` the write judge stamps on every rules value it
+ * judges ({@link judgeSessionRulesWrite}), so every store that writes through it keeps the stamp on the row. It counts
+ * revisions of what an entry MEANS and moves only when that changes. Grammar 0 is the reading before the one entry reader:
+ * a bucket's entries were tool names compared as written, so an allow entry the reader now reads as speaking for another name
+ * (`Bash(rm:*)`, `Bash(*)`) named no tool and admitted nothing.
+ */
+export declare const SESSION_RULES_GRAMMAR = 1;
 /** {@link SessionPermissionRules} plus the monotonic `rev` the store stamps (the OCC key). */
 export interface StoredSessionRules extends SessionPermissionRules {
     rev: number;
@@ -53,7 +64,15 @@ export interface StoredSessionRules extends SessionPermissionRules {
      *  can tell a recreated row from a continuation of the one it enforces whatever `rev` the new row wears.
      *  Absent = generation 0 (a backend that predates the mark, or a row written before it). */
     gen?: number;
+    /** The rule grammar the row's entries are read in ({@link SESSION_RULES_GRAMMAR}), stamped by the write judge. Absent =
+     *  a row stored before the stamp: grammar 0. */
+    grammar?: number;
 }
+/** A rules value as the shape reading hands it on ({@link readSessionRulesShape}): its buckets, and the grammar its entries
+ *  are read in — resolved, so a store that serves it on beside its own counters serves the row's grammar with it. */
+export type SessionRulesInGrammar = SessionPermissionRules & {
+    grammar: number;
+};
 /** Options for {@link SessionPolicyStore.putRules}. */
 export interface PutRulesOptions {
     /** CAS: reject the write if the stored `rev` is not this (optimistic concurrency). Omit to skip the check. */
@@ -169,13 +188,14 @@ declare function lexWithin(root: string, p: string): boolean;
  * THE ONE SHAPE READING of a rules value — what every station that takes one reads it through: the write (incoming rules),
  * a store's read-back of its own rows, the tighten comparison's prior, the run-time layer's served row. A rules value is an
  * object whose keys are buckets ({@link SessionPermissionRules}); each bucket present is a list of strings (`allowDirs`: of
- * non-blank strings — a directory is no blank). A bucket's TYPE is all this reads: what an entry means is the entry reader's.
- * The store's own stamps (`rev`, `gen`) are passed over, and a key holding `undefined` holds nothing. Anything else is a fault,
- * named by key and by TYPE, never by value — a bare string is never one rule and never its characters (`"rm"` spread into
- * `["r","m"]`), and a key outside the buckets is never dropped (a dropped deny is a deny nobody enforces).
+ * non-blank strings — a directory is no blank). A bucket's TYPE is all this reads: what an entry means is the entry reader's,
+ * in the grammar the value is written in ({@link grammarOf}), handed on as `grammar`. The store's counters (`rev`, `gen`) are
+ * passed over, and a key holding `undefined` holds nothing. Anything else is a fault, named by key and by TYPE, never by value —
+ * a bare string is never one rule and never its characters (`"rm"` spread into `["r","m"]`), and a key outside the buckets is
+ * never dropped (a dropped deny is a deny nobody enforces).
  */
 export declare function readSessionRulesShape(value: unknown): {
-    rules: SessionPermissionRules;
+    rules: SessionRulesInGrammar;
 } | {
     fault: SessionRuleShapeRefusal;
     sentence: string;
@@ -185,15 +205,33 @@ export declare function readSessionRulesShape(value: unknown): {
  *  stored form is `..`-free and the tighten diff compares the form the runtime resolves. Both bundled stores and a durable twin
  *  stamp exactly this, so a structuredClone and a JSON round-trip of it are byte-identical. */
 export declare function normalizeRules(rules: unknown): SessionPermissionRules;
+/**
+ * THE LIST READING of one rule bucket of a rules value the shape reading read — what the run-time layer enforces, the tighten
+ * comparison compares and the write judge refuses on: `compileAllowList` over the one entry reader, in the bucket's direction,
+ * against `roster` when given, in the grammar the value is written in. An entry its grammar reads as nothing that the reader
+ * reads as a row ({@link readsAsNothingIn}) is moved to the entries that read as nothing, reason `earlier_grammar`.
+ */
+export declare function compileSessionRuleBucket(rules: SessionRulesInGrammar, field: SessionRuleEntryField, roster?: ReadonlySet<string>): ReturnType<typeof compileAllowList>;
+/** The advisory for allow entries a stored row's earlier grammar reads as nothing ({@link compileSessionRuleBucket}): the session,
+ *  the entries as written, what they do and the way to make them the rules they now spell. */
+export declare function earlierGrammarAdvisory(sessionId: string, entries: readonly string[]): string;
+/** A layer's delivery of the entries its snapshots' earlier grammar reads as nothing ({@link compileSessionRuleBucket},
+ *  `earlier_grammar`) to `sink`: once per distinct set per layer (the ledger is this closure's), an empty set is no news, and a
+ *  throwing sink never changes what the snapshot enforces. */
+export declare function earlierGrammarAnnouncer(sink: ((entries: readonly string[]) => void) | undefined): (entries: readonly string[]) => void;
 /**
  * THE ONE WRITE JUDGE every store applies before it stamps a row (both bundled stores, and a durable backend at the same point):
  * the rules to stamp, or a {@link SessionPolicyError}, in this order — `conflict` (a stale `expectedRev` against `prior`'s rev),
- * `invalid_shape` ({@link normalizeRules}), `inert_entry` (an entry the reader reads as nothing; operator writes included — a
- * rule that names nothing guards nothing whoever writes it), then, for a non-operator write over an existing row,
- * `loosen_forbidden` ({@link loosenReasons}) — or `corrupt` when that prior cannot be read as rules, which the comparison never
- * reads as fewer. `mountedToolNames` = the store's declaration ({@link SessionPolicyStoreOptions.mountedToolNames}).
+ * `invalid_shape` ({@link normalizeRules}), `inert_entry` (an entry that reads as nothing in the grammar the rules are written
+ * in; operator writes included — a rule that names nothing guards nothing whoever writes it), then, for a non-operator write
+ * over an existing row, `loosen_forbidden` ({@link loosenReasons}) — or `corrupt` when that prior cannot be read as rules,
+ * which the comparison never reads as fewer. The rules to stamp carry `grammar` = {@link SESSION_RULES_GRAMMAR}: what passed
+ * the judge means the same in this engine's grammar, and THIS is the one place the stamp is minted, so every store that
+ * stores what the judge returns keeps it. `mountedToolNames` = the store's declaration ({@link SessionPolicyStoreOptions.mountedToolNames}).
  */
-export declare function judgeSessionRulesWrite(prior: StoredSessionRules | null, rules: unknown, opts: PutRulesOptions | undefined, mountedToolNames?: ReadonlySet<string>): SessionPermissionRules;
+export declare function judgeSessionRulesWrite(prior: StoredSessionRules | null, rules: unknown, opts: PutRulesOptions | undefined, mountedToolNames?: ReadonlySet<string>): SessionPermissionRules & {
+    grammar: number;
+};
 /**
  * Pure tighten-only diff: the reasons `next` LOOSENS `prior` (empty ⇒ `next` is a pure tightening or no-op), over the EFFECTIVE
  * entries of each rule bucket — the list as the run-time layer enforces it ({@link effectiveEntries}). An entry that reads as
@@ -201,9 +239,11 @@ export declare function judgeSessionRulesWrite(prior: StoredSessionRules | null,
  * takes out an entry that names nothing); an allowlist a `*` voids admits nothing, so dropping the `*` widens. toolDeny: removing an effective entry loosens. toolAllow: removing the list
  * (→ everything allowed) or adding an effective entry outside the prior set loosens; prior-undefined → any defined next only
  * narrows. allowDirs: removing confinement, or adding a dir not within some prior dir, loosens (coarse raw containment).
- * Entries compare as written. Both sides are read through {@link readSessionRulesShape} first: a side it cannot read (a key that
- * is no bucket — a retired one included) throws `invalid_shape` rather than compare without it. `mountedToolNames` = the store's
- * declaration ({@link SessionPolicyStoreOptions.mountedToolNames}; empty when it has none) — the write judge's too.
+ * Entries compare as written, each side's in the grammar that side is written in (a stored row's entry that its grammar reads as
+ * nothing is in no effect, so writing it in this engine's grammar widens). Both sides are read through
+ * {@link readSessionRulesShape} first: a side it cannot read (a key that is no bucket — a retired one included) throws
+ * `invalid_shape` rather than compare without it. `mountedToolNames` = the store's declaration
+ * ({@link SessionPolicyStoreOptions.mountedToolNames}; empty when it has none) — the write judge's too.
  */
 export declare function loosenReasons(priorValue: SessionPermissionRules, nextValue: SessionPermissionRules, mountedToolNames?: ReadonlySet<string>): string[];
 /**