@sema-agent/core 7.50.2 → 7.51.1

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,39 @@ 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.
+ */
+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 +91,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;
@@ -7,7 +8,7 @@ function isExemptEnvName(name) {
 }
 const ENV_NAMES = envNameView(CREDENTIAL_VOCABULARY);
 const OTEL_ENV_RE = /^(?:INPUT_)?OTEL_/i;
-const SEMA_NAMESPACE_SECRET_RE = new RegExp(`^SEMA_(?:.*_)?(?:KEY|KEYS|TOKEN|${ENV_NAMES.countedPlural}|SECRET|SECRETS|PASSWORD|PASSWORDS|PASSWD|CREDENTIAL|CREDENTIALS|PRIVATEKEY|APIKEY)(?:_|$)`, "is");
+const SEMA_NAMESPACE_SECRET_RE = new RegExp(`^SEMA_(?:.*_)?${ENV_NAMES.segmentWord}(?:_|$)`, "is");
 const BUNDLER_SETTINGS = ["BUILD", "LOCAL", "MIRROR", "PATH", "WITH", "WITHOUT", "CACHE", "DISABLE", "IGNORE", "ONLY"];
 const BUNDLER_HOST = "(?:[A-Za-z0-9]+(?:___[A-Za-z0-9]+)*__)+[A-Za-z]{2,}";
 const BUNDLER_CREDENTIAL_RE = new RegExp(`^(?:INPUT_)?BUNDLE_(?!(?:${BUNDLER_SETTINGS.join("|")})__(?!${BUNDLER_HOST}$))\\w*__`, "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

@@ -14,26 +14,37 @@
  *   (mirrors `steer.trusted`); core never adjudicates operator-ness, it only honors the flag.
  * - **CAS rev** (optimistic concurrency): a `putRules` with a stale `expectedRev` is rejected, so two replicas
  *   can't lose an update (mirrors the checkpoint store's `resolve` OCC).
- * - **structured fields only**: core interprets `toolAllow/Deny`, `allowDirs`, `commandAllow/Deny` (argv[0]
- *   names). A richer rule DSL is the service's/profile's job — core grows no rule interpreter.
- * - **NOT A SANDBOX**: command rules inherit the coarse argv[0] matching (wrappers like `sh -c`/`sudo` circumvention);
- *   the real isolation boundary is the executionEnv, never these rules.
+ * - **one grammar**: the two rule buckets hold rule ENTRIES — the grammar every entry list reads, through its one reader
+ *   (`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).
+ * - **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 RuleToolNameVerdict } from "./tool-name-aliases.js";
-/** The structured per-session rules. All optional; an absent field imposes no constraint of that kind. */
+import { 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 these tool names are allowed (others denied). A narrowing allowlist. */
+    /** If set, ONLY the calls these entries admit are allowed — a narrowing allowlist: a call no entry admits is refused.
+     *  Rule entries read in the allow direction (`Read`, `mcp__srv`, `Bash(git:*)`, `Edit(src/**)`). */
     toolAllow?: string[];
-    /** Tool names always denied (deny wins). */
+    /** Entries whose calls are always refused (deny wins) — rule entries read in the deny direction (`Bash`, `Bash(rm:*)`,
+     *  `mcp__srv__delete_*`, `Read(//etc/**)`). */
     toolDeny?: string[];
     /** If set, WRITE tools (`Write`/`Edit`) may only target paths within these dirs; a write-capable
      *  tool that can't be path-confined (e.g. `Bash`) is denied while this is set. Stored RAW; resolved at run time. */
     allowDirs?: string[];
-    /** If set, ONLY these `Bash` command names (argv[0]) are allowed. */
-    commandAllow?: string[];
-    /** `Bash` command names (argv[0]) always denied. */
-    commandDeny?: string[];
 }
+/** Every bucket a rules object holds, and how its entries are read: a rule-entry list in one direction, or the write
+ *  confinement's directories. A key outside this table is no bucket ({@link readSessionRulesShape} refuses it). */
+declare const SESSION_RULE_BUCKETS: {
+    readonly toolAllow: "allow";
+    readonly toolDeny: "deny";
+    readonly allowDirs: "dirs";
+};
+/** A bucket that holds rule entries. */
+export type SessionRuleEntryField = {
+    [K in keyof typeof SESSION_RULE_BUCKETS]: (typeof SESSION_RULE_BUCKETS)[K] extends "dirs" ? never : K;
+}[keyof typeof SESSION_RULE_BUCKETS];
 /** {@link SessionPermissionRules} plus the monotonic `rev` the store stamps (the OCC key). */
 export interface StoredSessionRules extends SessionPermissionRules {
     rev: number;
@@ -52,58 +63,42 @@ export interface PutRulesOptions {
      *  this from a verified, role-checked principal (mirrors `steer.trusted`). */
     operator?: boolean;
 }
-/** The {@link SessionPolicyError.detail} of a tool-name refusal: which bucket, which entry, the judgment's word, the judgment's
- *  one-line sentence when it has one, and the spelling to write instead when the judgment has one (a retired name's 1:1
- *  successor, an unmintable segment's minted name). */
-export interface SessionRuleNameRefusal {
-    field: SessionRuleToolNameField;
-    name: string;
-    verdict: Exclude<RuleToolNameVerdict["kind"], "current">;
-    /** The `guidance` of the judgment ({@link judgeRuleToolName}), byte for byte — the same string the refusal's sentence quotes. Present for
-     *  `retired` and `unmintable_segment`, the two verdicts that carry one; absent for `unprefixed_namespace`, whose judgment has no sentence of its own. */
-    guidance?: string;
-    currentName?: string;
+/** The {@link SessionPolicyError.detail} of an `invalid_shape` refusal: which key, and what it holds — its TYPE, never its
+ *  value (`a string`, `null`, `an array holding an entry that is not a string`), or `not a rule bucket` for a key outside
+ *  the buckets. `field` is empty when the rules value itself is not an object. */
+export interface SessionRuleShapeRefusal {
+    field: string;
+    got: string;
+}
+/** The {@link SessionPolicyError.detail} of an `inert_entry` refusal: which bucket, which entry, and why it reads as nothing —
+ *  the entry reader's own answer (`readRuleEntry`), reason and facts unchanged. */
+export interface SessionRuleEntryRefusal extends AllowEntryInertDetail {
+    field: SessionRuleEntryField;
+    entry: string;
+    reason: AllowEntryInertReason;
 }
 /** Typed error from {@link SessionPolicyStore.putRules}. `conflict` = stale `expectedRev`; `loosen_forbidden`
- *  = a non-operator write tried to relax the rules; `corrupt` = a backend could not read the erase-surviving
- *  rev mark ({@link SessionPolicyStore.deleteBySession}) and refuses rather than stamp an unproven rev; the fourth
- *  code = a tool-name bucket names a retired name, a prefix-less `__` name or a segment no mint spells (an empty one, or a peer spelled otherwise)
- *  ({@link assertSessionRuleNamesCurrent}) — `detail` is present on that code and only on it. */
+ *  = a non-operator write tried to relax the rules; `corrupt` = a backend could not read what it stored (a row, or the
+ *  erase-surviving rev mark of {@link SessionPolicyStore.deleteBySession}) and refuses rather than read it as fewer rules or
+ *  stamp an unproven rev; `invalid_shape` = the rules value is not an object of buckets, each a list of strings
+ *  ({@link readSessionRulesShape}); `inert_entry` = a bucket holds an entry the entry reader reads as nothing. `detail` is
+ *  present on the last two codes and only on them ({@link SessionRuleShapeRefusal}, {@link SessionRuleEntryRefusal}). */
 export declare class SessionPolicyError extends Error {
-    readonly code: "conflict" | "loosen_forbidden" | "corrupt" | "legacy_tool_name";
-    readonly detail?: SessionRuleNameRefusal | undefined;
-    constructor(code: "conflict" | "loosen_forbidden" | "corrupt" | "legacy_tool_name", message: string, detail?: SessionRuleNameRefusal | undefined);
+    readonly code: "conflict" | "loosen_forbidden" | "corrupt" | "invalid_shape" | "inert_entry";
+    readonly detail?: (SessionRuleShapeRefusal | SessionRuleEntryRefusal) | undefined;
+    constructor(code: "conflict" | "loosen_forbidden" | "corrupt" | "invalid_shape" | "inert_entry", message: string, detail?: (SessionRuleShapeRefusal | SessionRuleEntryRefusal) | undefined);
 }
-/** Which buckets hold TOOL names (the ones a run's policy audit reads as names); a new bucket is given a role here. */
-declare const HOLDS_TOOL_NAMES: {
-    readonly toolAllow: true;
-    readonly toolDeny: true;
-    readonly allowDirs: false;
-    readonly commandAllow: false;
-    readonly commandDeny: false;
-};
-type SessionRuleToolNameField = {
-    [K in keyof typeof HOLDS_TOOL_NAMES]: (typeof HOLDS_TOOL_NAMES)[K] extends true ? K : never;
-}[keyof typeof HOLDS_TOOL_NAMES];
 /** Construction options both bundled stores take. */
 export interface SessionPolicyStoreOptions {
-    /** The names this deployment mounts its OWN tools under — the roster the store judges a rule's tool names against
-     *  ({@link judgeRuleToolName}): a retired name declared here is an ordinary name to the write and to the loosening
-     *  check alike. Absent = none. A name carrying `__` is refused, as it is for a deployment tool. */
+    /** The names this deployment mounts its OWN tools under — the roster the store reads a rule entry's tool name against
+     *  (`readRuleEntry`): a retired name declared here is an ordinary name to the write and to the loosening check alike.
+     *  Absent = none. A name carrying `__` is refused, as it is for a deployment tool. */
     mountedToolNames?: Iterable<string>;
 }
 /** A store's declared roster from {@link SessionPolicyStoreOptions.mountedToolNames} — the one reader both bundled stores
  *  (and so `FileStorageBackendOptions.sessionPolicy`) construct through, refusing loudly when it is not a list of plain
  *  tool names (a bare string would iterate by character). */
 export declare function readMountedToolNames(value: unknown): ReadonlySet<string>;
-/**
- * The write judge for session rules, against `mountedToolNames` (the store's declaration; empty when it has none): every
- * entry of a tool-name bucket must be `current` ({@link judgeRuleToolName}), or the write is refused (the fourth
- * {@link SessionPolicyError} code) — such a name matches no tool, and a run's policy audit refuses to start with it.
- * Operator writes included. Both bundled stores call it after normalizing and before {@link loosenReasons}; a durable
- * backend calls it at the same point. The message names the entry and the way out, never a storage location.
- */
-export declare function assertSessionRuleNamesCurrent(rules: SessionPermissionRules, mountedToolNames?: ReadonlySet<string>): void;
 /**
  * The seam a deployment implements for DURABLE, cross-replica per-session rules. Unset on `RunnerDeps` ⇒ the
  * feature is OFF (no rules read, zero behavior change). Keyed on `(sessionId, principal-owner)`: core passes
@@ -118,11 +113,9 @@ export interface SessionRulesRecord {
 }
 export interface SessionPolicyStore {
     getRules(sessionId: string, principal?: string): Promise<StoredSessionRules | null>;
-    /** Write the rules for a key: CAS on `expectedRev`, then the name judge ({@link assertSessionRuleNamesCurrent} —
-     *  operator writes included), then, for a non-operator write over an existing row, the
-     *  tighten-only check ({@link loosenReasons}) — both against the names the deployment declares it mounts its own
-     *  tools under. A bucket that is not a list of strings (a bare `"rm"` for `commandDeny`) throws a `TypeError` from
-     *  {@link normalizeRules} before any of those is judged, and nothing is written. */
+    /** Write the rules for a key through the one write judge ({@link judgeSessionRulesWrite}): CAS on `expectedRev`, the
+     *  shape, every entry's reading (operator writes included), then, for a non-operator write over an existing row, the
+     *  tighten-only check — each refusal a {@link SessionPolicyError}, and nothing is written. */
     putRules(sessionId: string, principal: string | undefined, rules: SessionPermissionRules, opts?: PutRulesOptions): Promise<StoredSessionRules>;
     /**
      * 2c session-sync: every (principal, rules) record for `sessionId` across ALL principals — `getRules`
@@ -172,21 +165,47 @@ export interface SessionPolicyStore {
  * backend should keep `allowDirs` to real directories; a future symlink-aware write-time canonicalize closes it.
  */
 declare function lexWithin(root: string, p: string): boolean;
-/** Normalize a rules object's `allowDirs` (lexical `posix.normalize`) so stored rules are `..`-free and the
- *  tighten diff compares the same canonical-ish form the runtime resolves. Every bucket must be a list of strings
- *  ({@link ruleList}); a bucket that is not one throws `TypeError`, so neither bundled store (nor a durable twin that
- *  normalizes through this function) can store a rule list the matcher would read differently from the one written. */
-export declare function normalizeRules(rules: SessionPermissionRules): SessionPermissionRules;
 /**
- * Pure tighten-only diff: the reasons `next` LOOSENS `prior` (empty ⇒ `next` is a pure tightening or no-op).
- * Direction per field — deny-lists: removing an entry loosens, except a `toolDeny` entry that is not `current` against
- * `mountedToolNames` ({@link judgeRuleToolName}: it matches no tool, so removing it relaxes nothing — the way a session's owner
- * takes out a stale entry that stops every run). allowlists: removing the list (→ everything allowed) or adding an
- * 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). `mountedToolNames` = the
- * store's declaration ({@link SessionPolicyStoreOptions.mountedToolNames}; empty when it has none) — the write judge's too.
+ * 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).
+ */
+export declare function readSessionRulesShape(value: unknown): {
+    rules: SessionPermissionRules;
+} | {
+    fault: SessionRuleShapeRefusal;
+    sentence: string;
+};
+/** The CANONICAL stored form of a rules value: its shape read ({@link readSessionRulesShape} — a fault refuses with
+ *  `invalid_shape`), every list copied (detached from the caller's arrays), and `allowDirs` lexically `posix.normalize`d so the
+ *  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 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}).
+ */
+export declare function judgeSessionRulesWrite(prior: StoredSessionRules | null, rules: unknown, opts: PutRulesOptions | undefined, mountedToolNames?: ReadonlySet<string>): SessionPermissionRules;
+/**
+ * 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
+ * nothing is in neither side's effect, so removing one relaxes nothing and adding one widens nothing (the way a session's owner
+ * 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.
  */
-export declare function loosenReasons(prior: SessionPermissionRules, next: SessionPermissionRules, mountedToolNames?: ReadonlySet<string>): string[];
+export declare function loosenReasons(priorValue: SessionPermissionRules, nextValue: SessionPermissionRules, mountedToolNames?: ReadonlySet<string>): string[];
 /**
  * Does row `a` belong to the SAME lineage as row `b` — the one question every reader asks before it compares
  * two rows' `rev`, asked in ONE place so a `gen` that is ABSENT cannot mean three different things at three
@@ -205,8 +224,6 @@ export declare function continuesLineage(a: {
 }, b: {
     gen?: number;
 }): boolean;
-/** strip any caller-passed `rev` from a rules object so the store is the sole authority on it. */
-export declare function stripRev(rules: SessionPermissionRules): SessionPermissionRules;
 /**
  * In-process default {@link SessionPolicyStore} (single-replica). A deployment that needs cross-replica
  * durability supplies its own backend with the SAME CAS-rev + tighten-only semantics. Single-threaded JS makes