@sema-agent/core 7.51.1 → 7.52.0

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

@@ -18,10 +18,15 @@
  *   (`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.
+ * - **rules are read as rules or not at all**: rules whose shape cannot be read, or whose toolDeny holds an entry no grammar
+ *   reads ({@link unreadableDenyEntries}), refuse every call until an operator writes them afresh — never read as fewer.
  * - **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 AllowEntryInert, 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 +50,19 @@ 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:
+ *  - 0, 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 — and so did
+ *    `*`, one more name no tool carried, which voided nothing beside it;
+ *  - 1, the one entry reader taking its tool name from the lenient rule parser (trimmed before a `(`, any character but a
+ *    blank, a parenthesis or a control / format character);
+ *  - 2, the rule syntax's tool-name head (`ruleSpellingOf`): a name is read as written, in the characters names are minted in.
+ * An entry this grammar reads as no rule in a row an earlier grammar wrote reads as `earlier_grammar` ({@link compileSessionRuleBucket}).
+ */
+export declare const SESSION_RULES_GRAMMAR = 2;
 /** {@link SessionPermissionRules} plus the monotonic `rev` the store stamps (the OCC key). */
 export interface StoredSessionRules extends SessionPermissionRules {
     rev: number;
@@ -53,7 +71,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. */
@@ -92,7 +118,8 @@ export declare class SessionPolicyError extends Error {
 export interface SessionPolicyStoreOptions {
     /** 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. */
+     *  Absent = none. Each name keeps the caller tool name contract a deployment tool's name keeps at the mount
+     *  (`callerToolNameProblem`: a name a rule can name, no `__`); one that does not is refused at construction. */
     mountedToolNames?: Iterable<string>;
 }
 /** A store's declared roster from {@link SessionPolicyStoreOptions.mountedToolNames} — the one reader both bundled stores
@@ -169,13 +196,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,25 +213,73 @@ 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 ONE ANSWER to "can these rules' denies be read?": the `toolDeny` entries the list reading ({@link compileSessionRuleBucket},
+ * in the rules' own grammar) reads as no rule at all. Rules whose deny bucket holds one cannot be read, and rules that cannot be
+ * read are never read as fewer: they refuse every call (the run-time layer) and a non-operator write over them is a loosening
+ * ({@link loosenReasons}) — until an operator writes them afresh, and the write judge refuses such an entry. Unlike a definition
+ * file a plugin ships, which its user cannot edit, a session's rules are written by the session's own operator and can be
+ * rewritten, so a deny nobody can read costs one write instead of quietly guarding nothing. An entry the grammar reads that names
+ * no mounted tool (or `*`) is not here: it names nothing and refuses nothing, the rest of the bucket refusing as written.
+ * `roster` as in {@link compileSessionRuleBucket}; it never changes this answer (a spelling is read before a name is judged).
+ */
+export declare function unreadableDenyEntries(rules: SessionRulesInGrammar, roster?: ReadonlySet<string>): AllowEntryInert[];
+/**
+ * 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
+ * ({@link earlierGrammarReads}) is moved to the entries that read as nothing, reason `earlier_grammar`, before the list is
+ * compiled: it is one entry that reads as nothing, and the list beside it is read as written. The move is an ENTRY's reading and
+ * never the list's: an allow list a `*` voids (in any spelling the voiding test reads as `*`, `* (*)` included) is voided in
+ * every grammar from 1 on, so in such a row the list is read whole, as written — only grammar 0, where `*` was one more name, takes
+ * it out alone.
+ */
+export declare function compileSessionRuleBucket(rules: SessionRulesInGrammar, field: SessionRuleEntryField, roster?: ReadonlySet<string>): ReturnType<typeof compileAllowList>;
+/**
+ * The advisory for the entries of one bucket a stored row's earlier grammar reads as nothing ({@link compileSessionRuleBucket},
+ * `earlier_grammar`; `grammar` = the row's): the session, the bucket, the entries as written, what they do and the way out. An
+ * entry this engine's grammar reads as no rule is named with the reader's word — in `toolAllow` it admits nothing, in `toolDeny`
+ * the rules cannot be read and every call is refused ({@link unreadableDenyEntries}); the way out is a rewrite leaving it out
+ * (the write judge refuses an entry it cannot read). A grammar-0 allow entry that named no tool there is told as it always was:
+ * to make a parenthesized one the rule it now spells, or (`*`, which is no allow rule in any grammar) to leave it out.
+ */
+export declare function earlierGrammarAdvisory(sessionId: string, entries: readonly string[], field: SessionRuleEntryField, grammar: number): string;
+/** The clause a run-time refusal carries when the allowlist it judged by holds entries its earlier grammar reads as nothing
+ *  ({@link compileSessionRuleBucket}; `grammar` = the row's): the grammar the rules are stored in, then which entries name no tool
+ *  there (grammar 0: `*` by its spelling, the parenthesized ones counted) and how many this engine's grammar reads as no rule —
+ *  counted, since a stored entry's own text is data and never reaches a sentence the model reads. Empty when none. */
+export declare function earlierGrammarRefusalClause(entries: readonly string[], grammar: number): string;
+/** A layer's delivery of the entries its snapshots' earlier grammar reads as nothing ({@link compileSessionRuleBucket},
+ *  `earlier_grammar`), one bucket at a time with the grammar its row is written in, 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[], field: SessionRuleEntryField, grammar: number) => void) | undefined): (entries: readonly string[], field: SessionRuleEntryField, grammar: number) => 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
+ * entries of each rule bucket — the list as the run-time layer enforces it ({@link effectiveEntries}). Rules whose toolDeny holds
+ * an entry no grammar reads ({@link unreadableDenyEntries}) refuse every call: as `next` they loosen nothing, and as `prior`
+ * every readable `next` loosens them (one reason, naming the entries). Any other 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
+ * takes out an entry that names nothing); an allowlist a `*` voids (in this engine's grammar; in grammar 0 a `*` is one such entry beside the rest) 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[];
 /**

package/dist/core/session-policy-store.js

@@ -1,12 +1,14 @@
 import { posix } from "node:path";
 import { isWinFormPath } from "../tools/fs/safety.js";
-import { NAMESPACED_NAME_SHAPES, carriesNamespaceSeparator } from "./protocol-table.js";
-import { compileAllowList, inertEntryPhrase, readRuleEntry, renderListEntry } from "./allow-entry.js";
+import { NAMESPACED_NAME_SHAPES } from "./protocol-table.js";
+import { callerToolNameProblem } from "./caller-tool-name.js";
+import { compileAllowList, compiledEntryName, inertEntryPhrase, readRuleEntry, renderListEntry, rootFacingToolNames } from "./allow-entry.js";
 import { valueTypeLabel } from "./tool-name-list.js";
 const SESSION_RULE_BUCKETS = { toolAllow: "allow", toolDeny: "deny", allowDirs: "dirs" };
 const BUCKETS = Object.keys(SESSION_RULE_BUCKETS);
 const ENTRY_FIELDS = BUCKETS.filter((f) => SESSION_RULE_BUCKETS[f] !== "dirs");
-const STORE_STAMPS = new Set(["rev", "gen"]);
+const STORE_STAMPS = new Set(["rev", "gen", "grammar"]);
+export const SESSION_RULES_GRAMMAR = 2;
 export class SessionPolicyError extends Error {
     code;
     detail;
@@ -28,10 +30,11 @@ export function readMountedToolNames(value) {
         refuse("must be an iterable of tool names (an array or a Set), not a single value");
     const names = new Set();
     for (const n of value) {
-        if (typeof n !== "string" || n.length === 0)
-            refuse(`holds ${JSON.stringify(n) ?? String(n)}, which is not a non-empty tool name`);
-        if (carriesNamespaceSeparator(n))
-            refuse(`holds ${JSON.stringify(n)}: "__" is reserved for protocol tool names and no deployment tool may carry it`);
+        if (typeof n !== "string")
+            refuse(`holds ${JSON.stringify(n) ?? String(n)}, which is not a tool name`);
+        const problem = callerToolNameProblem(n);
+        if (problem !== undefined)
+            refuse(`holds ${JSON.stringify(n)}: ${problem}`);
         names.add(n);
     }
     return names;
@@ -49,13 +52,32 @@ function lexWithin(root, p) {
         return true;
     return np === nr || np.startsWith(nr + "/");
 }
+function grammarOf(value) {
+    const stamp = value.grammar;
+    if (stamp === undefined)
+        return { grammar: value.rev !== undefined ? 0 : SESSION_RULES_GRAMMAR };
+    if (typeof stamp !== "number" || !Number.isInteger(stamp) || stamp < 0) {
+        const got = typeof stamp === "number" ? "a number that is not a whole number of 0 or more" : valueTypeLabel(stamp);
+        return { got, sentence: `session rules carry a grammar stamp that is ${got} — the stamp is the whole number of the rule grammar the rules were written in (this engine reads grammar ${SESSION_RULES_GRAMMAR})` };
+    }
+    if (stamp > SESSION_RULES_GRAMMAR) {
+        return {
+            got: `${stamp}, a grammar newer than this engine's (${SESSION_RULES_GRAMMAR})`,
+            sentence: `session rules were written in rule grammar ${stamp}, newer than this engine reads (grammar ${SESSION_RULES_GRAMMAR}) — refusing rather than read their entries in an older grammar; an engine that reads grammar ${stamp} reads them`,
+        };
+    }
+    return { grammar: stamp };
+}
 export function readSessionRulesShape(value) {
     const fault = (field, got, sentence) => ({ fault: { field, got }, sentence });
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         const got = Array.isArray(value) ? "an array" : valueTypeLabel(value);
         return fault("", got, `session rules must be an object of rule buckets (${BUCKETS.join(", ")}), got ${got}`);
     }
-    const rules = {};
+    const read = grammarOf(value);
+    if ("got" in read)
+        return fault("grammar", read.got, read.sentence);
+    const rules = { grammar: read.grammar };
     for (const [key, v] of Object.entries(value)) {
         if (STORE_STAMPS.has(key) || v === undefined)
             continue;
@@ -78,36 +100,160 @@ export function readSessionRulesShape(value) {
     return { rules };
 }
 export function normalizeRules(rules) {
+    return canonicalRules(shapeOrRefuse(rules));
+}
+function shapeOrRefuse(rules) {
     const read = readSessionRulesShape(rules);
     if ("fault" in read)
         throw new SessionPolicyError("invalid_shape", read.sentence, read.fault);
+    return read.rules;
+}
+function canonicalRules(read) {
     const out = {};
     for (const field of BUCKETS) {
-        const list = read.rules[field];
+        const list = read[field];
         if (list === undefined)
             continue;
         out[field] = SESSION_RULE_BUCKETS[field] === "dirs" ? list.map((d) => posix.normalize(d).replace(/\/+$/, "") || "/") : [...list];
     }
     return out;
 }
-function effectiveEntries(field, list, mountedToolNames) {
-    return compileAllowList(list ?? [], SESSION_RULE_BUCKETS[field], mountedToolNames).rows.map((r) => r.entry);
+function earlierGrammarReads(grammar, field, entry, reading) {
+    if (grammar >= SESSION_RULES_GRAMMAR)
+        return false;
+    if (reading.kind === "inert" && reading.reason === "grammar")
+        return true;
+    if (grammar !== 0 || SESSION_RULE_BUCKETS[field] !== "allow")
+        return false;
+    return reading.kind === "row" ? compiledEntryName(reading.compiled) !== entry : reading.reason === "wildcard_all";
+}
+function readsAsNoRule(entry, field) {
+    const reading = readRuleEntry(entry, SESSION_RULE_BUCKETS[field]);
+    return reading.kind === "inert" && reading.reason === "grammar";
+}
+const NO_RULE_REASONS = new Set(["grammar", "earlier_grammar"]);
+export function unreadableDenyEntries(rules, roster) {
+    return compileSessionRuleBucket(rules, "toolDeny", roster).inert.filter((i) => NO_RULE_REASONS.has(i.reason));
+}
+function readsAsWildcard(entry) {
+    return compileAllowList([entry], "allow").inert.some((i) => i.reason === "wildcard_all");
+}
+const STAR_IS_NO_ALLOW_RULE = "it is no allow rule in any grammar and a write holding it is refused";
+function starWayOut(onlyStars, others, left) {
+    return onlyStars
+        ? `"*" is no allow rule in any grammar (a write holding it is refused); to drop it, write the session's rules afresh without it ${REWRITE_THROUGH}; ${left}`
+        : `${others}, leaving "*" out — ${STAR_IS_NO_ALLOW_RULE}; ${left}`;
+}
+export function compileSessionRuleBucket(rules, field, roster) {
+    const direction = SESSION_RULE_BUCKETS[field];
+    const entries = rules[field] ?? [];
+    const earlier = new Set(entries.filter((e) => earlierGrammarReads(rules.grammar, field, e, readRuleEntry(e, direction, roster))));
+    const whole = compileAllowList(entries, direction, roster);
+    const voided = direction === "allow" && whole.inert.some((i) => i.reason === "wildcard_all");
+    if (earlier.size === 0 || (voided && rules.grammar > 0))
+        return whole;
+    const list = compileAllowList(entries.filter((e) => !earlier.has(e)), direction, roster);
+    return { rows: list.rows, inert: [...list.inert, ...entries.filter((e) => earlier.has(e)).map((entry) => ({ entry, reason: "earlier_grammar" }))] };
+}
+const ADVISORY_ENTRIES_SHOWN = 5;
+function shownEntries(entries, render) {
+    const rest = entries.length > ADVISORY_ENTRIES_SHOWN ? ` and ${entries.length - ADVISORY_ENTRIES_SHOWN} more` : "";
+    return `${entries.slice(0, ADVISORY_ENTRIES_SHOWN).map(render).join(", ")}${rest}`;
+}
+const REWRITE_THROUGH = `through this engine (an operator write of a new value without the stored row's rev; the write stamps grammar ${SESSION_RULES_GRAMMAR})`;
+export function earlierGrammarAdvisory(sessionId, entries, field, grammar) {
+    const noRule = entries.filter((e) => readsAsNoRule(e, field));
+    const namedNoTool = entries.filter((e) => !readsAsNoRule(e, field));
+    const sentences = [...(namedNoTool.length > 0 ? [namedNoToolInGrammar0(namedNoTool)] : []), ...(noRule.length > 0 ? [noRuleInThisGrammar(noRule, field, grammar)] : [])];
+    return `session permission rules of session ${JSON.stringify(sessionId)}: ${sentences.join(" ")}`;
+}
+function namedNoToolInGrammar0(entries) {
+    const one = entries.length === 1;
+    const wildcard = entries.some(readsAsWildcard);
+    const rules = entries.some((e) => !readsAsWildcard(e));
+    const left = `left as stored, ${one ? "it keeps" : "they keep"} admitting nothing.`;
+    const way = !wildcard
+        ? `To make ${one ? "it an allow rule" : "them allow rules"}, write the session's rules afresh ${REWRITE_THROUGH}; ${left}`
+        : starWayOut(!rules, `To make the parenthesized ones allow rules, write the session's rules afresh ${REWRITE_THROUGH}`, left);
+    return (`toolAllow ${shownEntries(entries, renderListEntry)} ${one ? "was" : "were"} stored before the rule grammar stamp, when session rules compared an entry as a tool name as written, so ${wildcard ? 'an entry that is no bare tool name (a parenthesized rule, or "*")' : "a parenthesized entry"} named no tool — ` +
+        `${one ? "it admits" : "they admit"} nothing, as when written${wildcard ? "; the rest of the list is read as written, not voided" : ""}. ${way}`);
+}
+function noRuleInThisGrammar(entries, field, grammar) {
+    const one = entries.length === 1;
+    const stored = `${field} ${shownEntries(entries, (entry) => inertEntryPhrase({ entry, reason: "grammar" }))} ${one ? "was" : "were"} stored in rule grammar ${grammar}${grammar === 0 ? ", before the rule grammar stamp" : ""}, and this engine's rule grammar (${SESSION_RULES_GRAMMAR}) reads ${one ? "it" : "them"} as no rule`;
+    const way = `write the session's rules afresh ${REWRITE_THROUGH}, leaving ${one ? "it" : "them"} out or spelling the tool's name as a rule spells one — the write judge refuses an entry it cannot read`;
+    if (SESSION_RULE_BUCKETS[field] === "deny") {
+        return `${stored}: rules whose toolDeny holds an entry no grammar reads cannot be read, so every call is refused until they are rewritten. To lift that, ${way}, and a non-operator write cannot loosen rules that refuse every call.`;
+    }
+    const stars = entries.filter(readsAsWildcard).length;
+    const left = `left as stored, ${one ? "it keeps" : "they keep"} admitting nothing.`;
+    const wayOut = stars === 0
+        ? `To allow what ${one ? "it" : "they"} meant, ${way}; ${left}`
+        : starWayOut(stars === entries.length, `To allow what the others meant, write the session's rules afresh ${REWRITE_THROUGH}, spelling each tool's name as a rule spells one`, left);
+    return `${stored} — ${one ? "it admits" : "they admit"} nothing, and the rest of the list is read as written. ${wayOut}`;
+}
+export function earlierGrammarRefusalClause(entries, grammar) {
+    if (entries.length === 0)
+        return "";
+    const noRule = entries.filter((e) => readsAsNoRule(e, "toolAllow")).length;
+    const namedNoTool = entries.filter((e) => !readsAsNoRule(e, "toolAllow"));
+    const stars = namedNoTool.filter(readsAsWildcard).length;
+    const others = namedNoTool.length - stars;
+    const named = [...(stars > 0 ? ['"*"'] : []), ...(others > 0 ? [`${others} parenthesized ${others === 1 ? "entry" : "entries"}`] : [])];
+    const clauses = [
+        ...(namedNoTool.length > 0 ? [`where ${named.join(" and ")} ${namedNoTool.length === 1 ? "names no tool and admits" : "name no tool and admit"} nothing`] : []),
+        ...(noRule > 0 ? [`${namedNoTool.length > 0 ? "and " : "where "}${noRule} ${noRule === 1 ? "entry is" : "entries are"} no rule in this engine's rule grammar (${SESSION_RULES_GRAMMAR}) and ${noRule === 1 ? "admits" : "admit"} nothing`] : []),
+    ];
+    return `; the session's rules are stored in rule grammar ${grammar}, ${clauses.join(" ")}`;
+}
+export function earlierGrammarAnnouncer(sink) {
+    const announced = new Set();
+    return (entries, field, grammar) => {
+        const key = JSON.stringify([field, grammar, entries]);
+        if (sink === undefined || entries.length === 0 || announced.has(key))
+            return;
+        announced.add(key);
+        try {
+            sink(entries, field, grammar);
+        }
+        catch {
+        }
+    };
+}
+function effectiveEntries(rules, field, mountedToolNames) {
+    return compileSessionRuleBucket(rules, field, mountedToolNames).rows.map((r) => r.entry);
 }
 function assertEntriesRead(rules, mountedToolNames) {
+    const known = rootFacingToolNames(mountedToolNames);
     for (const field of ENTRY_FIELDS) {
         for (const entry of rules[field] ?? []) {
-            const read = readRuleEntry(entry, SESSION_RULE_BUCKETS[field], mountedToolNames);
+            const reading = readRuleEntry(entry, SESSION_RULE_BUCKETS[field], known);
+            const read = earlierGrammarReads(rules.grammar, field, entry, reading) ? { kind: "inert", reason: "earlier_grammar" } : reading;
             if (read.kind === "row")
                 continue;
             const { kind: _kind, ...why } = read;
             void _kind;
-            const way = why.verdict === "retired"
-                ? ` If this deployment mounts its own tool under ${renderListEntry(entry)}, declare it in the store's mountedToolNames.`
-                : why.currentName === undefined
-                    ? ` An entry is a tool name (Read; a protocol tool is named ${NAMESPACED_NAME_SHAPES}), a protocol namespace (mcp__<server>), or a rule in its tool's own grammar (Bash(<command>), Edit(<path>), Skill(<name>), WebFetch(domain:<host>)).`
-                    : "";
+            const way = why.reason === "earlier_grammar"
+                ? readsAsNoRule(entry, field)
+                    ? ` These rules are written in grammar ${rules.grammar} (a stored row), and this engine's grammar (${SESSION_RULES_GRAMMAR}) reads this entry as no rule (grammar) — ` +
+                        (field === "toolAllow" && readsAsWildcard(entry) ? `leave the entry out: it spells "*", and ${STAR_IS_NO_ALLOW_RULE}.` : "leave the entry out, or spell the tool's name as a rule spells one.")
+                    : ` These rules are written in grammar ${rules.grammar} (a stored row from before the grammar stamp), in which this entry names no tool.` +
+                        (readsAsWildcard(entry)
+                            ? ` It is no allow rule in grammar ${SESSION_RULES_GRAMMAR} either (a write holding it is refused) — leave the entry out.`
+                            : ` To make it an allow rule, write the rules afresh — a value without the stored row's rev; the write stamps grammar ${SESSION_RULES_GRAMMAR} — or leave the entry out.`)
+                : why.verdict === "retired" || why.reason === "near_miss"
+                    ? ` If this deployment mounts its own tool under ${renderListEntry(entry)}, declare it in the store's mountedToolNames.`
+                    : why.currentName === undefined
+                        ? ` An entry is a tool name (Read; a protocol tool is named ${NAMESPACED_NAME_SHAPES}), a protocol namespace (mcp__<server>), or a rule in its tool's own grammar (Bash(<command>), Edit(<path>), Skill(<name>), WebFetch(domain:<host>)).`
+                        : "";
             const sentence = why.guidance !== undefined ? ` — ${why.guidance}` : "";
-            throw new SessionPolicyError("inert_entry", `session rules ${field} holds ${inertEntryPhrase({ entry, ...why })}, which ${SESSION_RULE_BUCKETS[field] === "deny" ? "refuses" : "admits"} nothing as written${sentence}; nothing was written.${way}`, { field, entry, ...why });
+            const does = SESSION_RULE_BUCKETS[field] === "allow"
+                ? "admits nothing as written"
+                : NO_RULE_REASONS.has(why.reason)
+                    ? "refuses every call as stored (rules whose toolDeny holds an entry no grammar reads cannot be read) — a write holding it is refused"
+                    : "refuses nothing as written";
+            const carriedBy = why.reason === "near_miss" && why.currentName !== undefined && !mountedToolNames.has(why.currentName) ? { carriedBy: "catalog" } : {};
+            throw new SessionPolicyError("inert_entry", `session rules ${field} holds ${inertEntryPhrase({ entry, ...why, ...carriedBy })}, which ${does}${sentence}; nothing was written.${way}`, { field, entry, ...why });
         }
     }
 }
@@ -115,8 +261,9 @@ export function judgeSessionRulesWrite(prior, rules, opts, mountedToolNames = NO
     if (opts?.expectedRev !== undefined && (prior?.rev ?? 0) !== opts.expectedRev) {
         throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts.expectedRev}, have ${prior?.rev ?? 0})`);
     }
-    const clean = normalizeRules(rules);
-    assertEntriesRead(clean, mountedToolNames);
+    const read = shapeOrRefuse(rules);
+    const clean = canonicalRules(read);
+    assertEntriesRead(read, mountedToolNames);
     if (prior !== null && opts?.operator !== true) {
         const stored = readSessionRulesShape(prior);
         if ("fault" in stored) {
@@ -127,7 +274,7 @@ export function judgeSessionRulesWrite(prior, rules, opts, mountedToolNames = NO
             throw new SessionPolicyError("loosen_forbidden", `a non-operator session-rule write may only tighten; refused: ${loosens.join("; ")}`);
         }
     }
-    return clean;
+    return { ...clean, grammar: SESSION_RULES_GRAMMAR };
 }
 export function loosenReasons(priorValue, nextValue, mountedToolNames = NO_DECLARED_TOOLS) {
     const shapeOf = (side, value) => {
@@ -138,17 +285,23 @@ export function loosenReasons(priorValue, nextValue, mountedToolNames = NO_DECLA
     };
     const prior = shapeOf("prior", priorValue);
     const next = shapeOf("next", nextValue);
+    if (unreadableDenyEntries(next, mountedToolNames).length > 0)
+        return [];
+    const unreadPrior = unreadableDenyEntries(prior, mountedToolNames);
+    if (unreadPrior.length > 0) {
+        return [`the prior rules refuse every call — their toolDeny holds ${shownEntries(unreadPrior.map((i) => i.entry), (entry) => inertEntryPhrase({ entry, reason: "grammar" }))}, which no grammar reads`];
+    }
     const reasons = [];
-    const keptDeny = new Set(effectiveEntries("toolDeny", next.toolDeny, mountedToolNames));
-    for (const x of effectiveEntries("toolDeny", prior.toolDeny, mountedToolNames))
+    const keptDeny = new Set(effectiveEntries(next, "toolDeny", mountedToolNames));
+    for (const x of effectiveEntries(prior, "toolDeny", mountedToolNames))
         if (!keptDeny.has(x))
             reasons.push(`removed toolDeny ${renderListEntry(x)}`);
     if (prior.toolAllow !== undefined) {
         if (next.toolAllow === undefined)
             reasons.push("removed toolAllow allowlist (all allowed)");
         else {
-            const had = new Set(effectiveEntries("toolAllow", prior.toolAllow, mountedToolNames));
-            for (const x of effectiveEntries("toolAllow", next.toolAllow, mountedToolNames))
+            const had = new Set(effectiveEntries(prior, "toolAllow", mountedToolNames));
+            for (const x of effectiveEntries(next, "toolAllow", mountedToolNames))
                 if (!had.has(x))
                     reasons.push(`widened toolAllow with ${renderListEntry(x)}`);
         }

package/dist/core/session-reconcile.d.ts

@@ -51,6 +51,9 @@ export interface OrphanToolCall {
  *  message and `errorCode` on the synthetic `tool_end` frame, so a consumer never parses the text. Two-valued
  *  (a third value needs a cross-repo slip, see {@link reconcileInterruptedSession}). */
 export type ReconciledErrorKind = "interrupted_never_started" | "interrupted_outcome_unknown";
+/** The class that is positive evidence the call never ran: closed with no start observed. The synthetic `tool_end` frame's
+ *  `notExecuted` (`reconciledEnd`) and the persisted close's `details.notExecuted` both read it — one table, two faces. */
+export declare const closeNeverExecuted: (errorKind: ReconciledErrorKind) => boolean;
 /** One orphan closed by {@link reconcileInterruptedSession}, with everything the caller needs to mint the
  *  matching stream frame WITHOUT re-reading the session. */
 export type RecoveredOrphan = OrphanToolCall & {
@@ -153,6 +156,7 @@ export declare function isInterruptedClose(message: {
 /** The `toolResult` message for one {@link InterruptedResult} — the persisted and the request-view closes are this one shape. */
 export declare function interruptedResultMessage(result: InterruptedResult, timestamp: number): ToolResultMessage<{
     errorKind: ReconciledErrorKind;
+    notExecuted?: true;
 }>;
 /**
  * Reconcile a resumed session's active branch: close any orphan tool calls with a synthetic

package/dist/core/session-reconcile.js

@@ -1,4 +1,5 @@
 import { readMember } from "./thrown-value.js";
+export const closeNeverExecuted = (errorKind) => errorKind === "interrupted_never_started";
 const INTERRUPTED_UNKNOWN = "[INTERRUPTED] The previous run ended before this tool call's result was recorded. Its outcome " +
     "is UNKNOWN — the action may have completed, partially completed, or never run. Do not assume " +
     "success or failure. Before relying on it: if it is safe to read, query the current state to " +
@@ -119,7 +120,7 @@ export function interruptedResultMessage(result, timestamp) {
         toolCallId: result.toolCallId,
         toolName: result.toolName,
         content: [{ type: "text", text: result.text }],
-        details: { errorKind: result.errorKind },
+        details: { errorKind: result.errorKind, ...(closeNeverExecuted(result.errorKind) ? { notExecuted: true } : {}) },
         isError: true,
         timestamp,
     };

package/dist/core/shell-read-silence.js

@@ -2,6 +2,7 @@ import { types } from "node:util";
 import { dispositionsOfRow, SHELL_READ_FINDINGS } from "../tools/fs/shell-read-judge.js";
 import { receiveContract } from "./decision-receipt.js";
 import { egressThrownText } from "./untrusted-egress.js";
+import { receive } from "./mods/kernel/receive.js";
 const DISPOSITIONS = ["refuse", "mandated", "ordinary", "vouch"];
 const MEMBER_KINDS = {
     disposition: "word",
@@ -20,37 +21,7 @@ const MEMBER_KINDS = {
     admit: "admission",
 };
 const VERDICT_MEMBERS = Object.keys(MEMBER_KINDS);
-const DATA_DEPTH = 8;
-function ownedData(value, depth, path) {
-    if (value === null || value === undefined || typeof value === "string" || typeof value === "number" || typeof value === "boolean")
-        return { ok: true, value };
-    if (typeof value !== "object" || depth >= DATA_DEPTH || types.isProxy(value) || path.has(value))
-        return { ok: false };
-    const list = Array.isArray(value);
-    const proto = Object.getPrototypeOf(value);
-    if (list ? proto !== Array.prototype : proto !== Object.prototype && proto !== null)
-        return { ok: false };
-    const own = Object.getOwnPropertyDescriptors(value);
-    path.add(value);
-    try {
-        const out = list ? [] : {};
-        for (const key of Object.keys(own)) {
-            if (list && key === "length")
-                continue;
-            const d = own[key];
-            if (!Object.hasOwn(d, "value") || d.enumerable !== true)
-                return { ok: false };
-            const inner = ownedData(d.value, depth + 1, path);
-            if (!inner.ok)
-                return { ok: false };
-            Object.defineProperty(out, key, { value: inner.value, enumerable: true, writable: true, configurable: true });
-        }
-        return { ok: true, value: out };
-    }
-    finally {
-        path.delete(value);
-    }
-}
+const OWNED_DATA_MODE = Object.freeze({ accessors: "refuse", depth: 8, others: "refuse", isProxy: (v) => types.isProxy(v) });
 function receivedAnswer(answer, call) {
     if (typeof answer !== "object" || answer === null)
         return undefined;
@@ -65,7 +36,7 @@ function receivedAnswer(answer, call) {
         if (kind === "word" ? typeof v !== "string" : kind === "mark" ? v !== true : kind === "face" ? v !== "write" : kind === "admission" ? typeof v !== "function" || types.isProxy(v) : false)
             return undefined;
         if (kind === "record") {
-            const data = ownedData(v, 0, new Set());
+            const data = receive(v, OWNED_DATA_MODE);
             if (!data.ok || typeof data.value !== "object" || data.value === null || Array.isArray(data.value))
                 return undefined;
             v = data.value;

package/dist/core/side-query.d.ts

@@ -63,9 +63,11 @@ export interface SideQuerySpec {
      * Per-model auth — MIRRORS {@link TaskSpec.getApiKeyAndHeaders} (same signature, resolved per
      * call against the RESOLVED model, exactly like the task path's per-call hook). The brain
      * contract is the route pairing law (route-adjudicator.ts): a per-model credential (this hook,
-     * or an auth header on `Model.headers`) always rides; the deployment credential rides only to the
-     * deployment's own root — a model carrying a root of its own is refused
-     * (`route.credential_mismatch` / `route.credential_missing`), never silently followed.
+     * or a credential header on `Model.headers`) rides to the origin it first went out to and is
+     * refused anywhere else (`route.credential_origin_mismatch`); an answer handing the key beside
+     * the lane's own key header is refused as one verdict (`route.credential_answer_conflict`); the
+     * deployment credential rides only to the deployment's own root — a model carrying a root of its
+     * own is refused (`route.credential_mismatch` / `route.credential_missing`), never silently followed.
      * Historically the fallback was unconditional (`options.apiKey ?? config.apiKey`, with a model's
      * own `baseUrl` outranking the brain's), so a side query routed to a model carrying its own
      * `baseUrl` + per-model key sent the GATEWAY key to the per-model (possibly external) URL — the

package/dist/core/skill-grant.d.ts

@@ -69,8 +69,9 @@ export declare function skillGrantBindingMembers(call: {
  * bytes — the row stays pending: deny it, then activate again) and the resumed execution boundary (`site: "execution"`, the
  * bytes that will run, after every station that can rewrite them — the approval is spent: the call does not run). The
  * sentence says which side of the digest differs, read off the row's own arguments: the arguments name another skill than
- * the card's (`row.args`), or the card's skill no longer declares the lists the card showed (or is not served). Names the
- * skills, never a path; says the way out.
+ * the card's (`row.args`), or the card's skill's lists no longer bind to the card's digest (or it is not served) — its
+ * definition changed, or this engine reads an entry of it differently than the engine that parked the row (an entry that
+ * reads as nothing: the digest is the list reader's reading, not the text). Names the skills, never a path; says the way out.
  */
 export declare function parkedSkillApprovalRefusal(row: {
     readonly toolName: string;