@sema-agent/core 7.53.0 → 7.54.0

package/dist/core/parent-spec-seat.js

@@ -1,3 +1,12 @@
+import { applyClampSeats, clampFieldSeatsOf } from "./child-clamp-seats.js";
+import { assertNoRetiredKeys } from "./retired-keys.js";
+const RETIRED_PARENT_SPEC_SEAT_KEYS = Object.freeze({
+    memoryOff: "the request-level memory-off fact is the clamp table's `memory` row now — carry `memory: { enabled: false }`",
+});
+export function assertParentSpecSeatCurrent(seat) {
+    if (seat !== undefined)
+        assertNoRetiredKeys(seat, RETIRED_PARENT_SPEC_SEAT_KEYS, "ParentSpecSeat");
+}
 export function parentSpecSeatOf(spec, frozenOnQuestion) {
     return Object.freeze({
         ...(spec.principal !== undefined ? { principal: spec.principal } : {}),
@@ -15,14 +24,15 @@ export function parentSpecSeatOf(spec, frozenOnQuestion) {
         ...(spec.fileHistory !== undefined ? { fileHistory: spec.fileHistory } : {}),
         ...(spec.promptForm !== undefined ? { promptForm: spec.promptForm } : {}),
         ...(spec.promptBinding !== undefined ? { promptBinding: spec.promptBinding } : {}),
-        ...(spec.memory?.enabled === false ? { memoryOff: true } : {}),
+        ...clampFieldSeatsOf(spec),
     });
 }
 export function applyParentSpecSeat(child, seat) {
     if (seat === undefined)
         return child;
+    assertParentSpecSeatCurrent(seat);
     const fill = (key, value) => child[key] === undefined && value !== undefined ? { [key]: value } : {};
-    return {
+    const landed = {
         ...child,
         ...fill("principal", seat.principal),
         ...fill("clientContext", seat.clientContext),
@@ -39,15 +49,13 @@ export function applyParentSpecSeat(child, seat) {
         ...fill("promptBinding", seat.promptBinding),
         ...(seat.oneShot === true ? { oneShot: true } : {}),
         ...(seat.memoryPersistenceCapable === false ? { memoryPersistenceCapable: false } : fill("memoryPersistenceCapable", seat.memoryPersistenceCapable)),
-        ...(seat.memoryOff === true ? { memory: memoryTurnedOff(child.memory) } : {}),
     };
-}
-export function memoryTurnedOff(memory) {
-    return { ...(memory ?? {}), enabled: false };
+    return applyClampSeats(landed, clampFieldSeatsOf(seat));
 }
 const SEAT_FACTS_ON_CTX = ["principal", "oneShot", "onQuestion", "memoryPersistenceCapable"];
 export function parentSpecSeatOfCtx(ctx) {
     const seat = ctx.parentSpecSeat;
+    assertParentSpecSeatCurrent(seat);
     const facts = SEAT_FACTS_ON_CTX.filter((k) => ctx[k] !== undefined);
     if (seat === undefined) {
         if (facts.length === 0)

package/dist/core/pause-registry.d.ts

@@ -3,10 +3,12 @@
  * hanging / what brings it back), the three word types and the resume match DERIVED from it, and the
  * registry-bound `gate` × `pendingAction` pair with its checked constructor. A vocabulary module on the
  * floor: it types against `checkpoint-store.ts` (type-only, no runtime edge) and `checkpoint-store.ts`
- * reaches down for the pair type.
+ * reaches down for the pair type and the card reading; its one runtime edge is the card vocabulary
+ * (`tool-face.ts`, itself a leaf).
  */
 import type { AssertAllKeysHandled } from "./ask-origin.js";
 import type { Checkpoint, CheckpointGate, CheckpointRow, PendingAction, ResumeOutcome } from "./checkpoint-store.js";
+import { type ToolApprovalCard } from "./tool-face.js";
 /**
  * THE registry of pauses — one row per way a run can stop and wait, and the ONE place the three faces
  * of that pause are declared together: WHY it stopped (`CheckpointGate.kind`, the row key), WHAT it left
@@ -93,6 +95,38 @@ export declare function isQuestionGate(gate: {
     readonly kind: GateKind;
     readonly approvalCard?: unknown;
 }): boolean;
+/** What a parked row's gate says about its approval card — the four answers {@link parkedApprovalCardOf} gives. */
+export type ParkedApprovalCardReading = 
+/** An approval gate carrying a word of the closed card set (`TOOL_APPROVAL_CARDS`). */
+{
+    readonly kind: "card";
+    readonly card: ToolApprovalCard;
+}
+/** An approval gate carrying no card. */
+ | {
+    readonly kind: "no_card";
+}
+/** An approval gate carrying a value outside the closed set (a word a later engine minted, a hand-edited row,
+ *  a non-string). `word` is the value as read, unscreened: a caller that renders it bounds and redacts it. */
+ | {
+    readonly kind: "unknown_word";
+    readonly word: unknown;
+}
+/** Not an approval gate: a registered gate whose `pending` column is not `tool_approval`, or a gate kind the
+ *  registry does not hold. No card is read on it. */
+ | {
+    readonly kind: "not_approval";
+};
+/**
+ * The one reading of a parked row's approval card. A gate is an approval gate when its kind is a registry row whose
+ * `pending` column is `tool_approval`; only there is the card read, and only a member of the closed set is a card.
+ * Each member of `gate` is read once (the value screened is the value answered). Pure: the answer says nothing about
+ * how loud an `unknown_word` should be — that is the caller's to decide.
+ */
+export declare function parkedApprovalCardOf(gate: {
+    readonly kind: unknown;
+    readonly approvalCard?: unknown;
+}): ParkedApprovalCardReading;
 /** The one resume-match predicate: does this outcome gate word answer a checkpoint of this kind? `wake`
  *  answers any (it passed its own, stricter, non-gate validation upstream); every other word must be the
  *  row's `resume` column. Replaces a six-arm hand-written disjunction. */

package/dist/core/pause-registry.js

@@ -1,3 +1,4 @@
+import { isToolApprovalCard } from "./tool-face.js";
 export const PAUSE_REGISTRY = {
     human: { pending: "tool_approval", resume: "policy_ask", facet: "A", taskStatus: "suspended", terminal: false },
     irreversible_ask: { pending: "tool_approval", resume: "policy_ask", facet: "A", taskStatus: "suspended", terminal: false },
@@ -15,6 +16,15 @@ export function facetOf(gate) {
 export function isQuestionGate(gate) {
     return PAUSE_REGISTRY[gate.kind].pending === "tool_approval" && gate.approvalCard === "question";
 }
+export function parkedApprovalCardOf(gate) {
+    const kind = gate.kind;
+    if (!isGateKind(kind) || PAUSE_REGISTRY[kind].pending !== "tool_approval")
+        return { kind: "not_approval" };
+    const word = gate.approvalCard;
+    if (word === undefined)
+        return { kind: "no_card" };
+    return isToolApprovalCard(word) ? { kind: "card", card: word } : { kind: "unknown_word", word };
+}
 export function resumeGateMatches(gateKind, outcomeGate) {
     return outcomeGate === "wake" || PAUSE_REGISTRY[gateKind].resume === outcomeGate;
 }

package/dist/core/permission-rule-consent.d.ts

@@ -38,8 +38,15 @@ export interface RuleCandidate {
     rule: string;
     scope: RuleScope;
 }
+/** The approval-record kinds, spelled once: {@link RuleApprovalKind} is derived from this tuple. */
+export declare const RULE_APPROVAL_KINDS: readonly ["card", "import", "starter"];
 /** What the approval record is for — it decides the provenance the minted adds carry. */
-export type RuleApprovalKind = "card" | "import" | "starter";
+export type RuleApprovalKind = (typeof RULE_APPROVAL_KINDS)[number];
+/** The approval-record states, spelled once: {@link RuleApprovalState} is derived from this tuple. */
+export declare const RULE_APPROVAL_STATES: readonly ["pending", "approved", "redeemed"];
+/** Where one approval record stands: `pending` as minted, `approved` once a person confirms, `redeemed` once a
+ *  redemption has recorded its dot (recorded before the rule is written, so a crash leaves a replayable intent). */
+export type RuleApprovalState = (typeof RULE_APPROVAL_STATES)[number];
 /**
  * design/375 §4.1 — one "don't ask again" OPTION as the record stores it: references into the
  * record's `candidates` by index, never rule text of its own. The display triple (rule, match,
@@ -78,6 +85,10 @@ export type RuleOffer2 = {
     readonly uncoveredSegments?: number;
     readonly uncoveredDetail?: readonly UncoveredSegmentDetail[];
 };
+/** The CURRENT record-form version stamp ({@link RuleApprovalRecord.schema}), spelled once: every mint writes it and
+ *  every readback compares against it by equality (an older or absent stamp is a stale row, never a floor). A
+ *  durable backend's stale gate reads this value rather than its own number. */
+export declare const RULE_APPROVAL_RECORD_SCHEMA = 4;
 /** A durable record of one pending/settled human decision about minting rules.
  *
  * Identity (design/182 §4.5, additive): a v1 record carries `principal` and nothing else — it stays
@@ -101,9 +112,9 @@ export interface RuleApprovalRecord {
      * bargain, unchanged). `4`: every candidate carries its `behavior` (the settings import now carries
      * the deny/ask lists too) — a `schema: 3` row is stale by the same equality gate.
      */
-    schema: 4;
+    schema: typeof RULE_APPROVAL_RECORD_SCHEMA;
     kind: RuleApprovalKind;
-    state: "pending" | "approved" | "redeemed";
+    state: RuleApprovalState;
     candidates: RuleCandidate[];
     /**
      * The card's OPTION structure over `candidates` (design/375 §4.1). The flat candidate list stays
@@ -504,8 +515,10 @@ export declare function redeemRuleTicket(opts: {
     owner?: RuleOwner;
     deps: RuleConsentDeps;
 }): Promise<RedeemResult>;
+/** The settings layer names, spelled once: {@link ImportedSettingsLayer} is derived from this tuple. */
+export declare const IMPORTED_SETTINGS_LAYERS: readonly ["userSettings", "projectSettings", "localSettings"];
 /** The three user-editable settings layers this version reads. */
-export type ImportedSettingsLayer = "userSettings" | "projectSettings" | "localSettings";
+export type ImportedSettingsLayer = (typeof IMPORTED_SETTINGS_LAYERS)[number];
 /** One layer to read. `root` is the canonical directory a project-layer rule is scoped to — taken from
  *  where the FILE actually lives, since the local layer is not always at a repository root. */
 export interface CcImportLayer {
@@ -528,7 +541,7 @@ export interface ImportPreview {
         reason: string;
     }>;
     /**
-     * ALWAYS EMPTY in this version — a compatibility seat, kept on the wire shape so an existing reader
+     * ALWAYS EMPTY in this version — a compatibility seat (RL-1336-import-translated), kept on the wire shape so an existing reader
      * keeps finding the key (removing a wire field would break readers for no gain).
      *
      * The seat once carried the entries whose MATCH FORM was rewritten on the way in (the space-star

package/dist/core/permission-rule-consent.js

@@ -1,14 +1,18 @@
 import { randomBytes } from "node:crypto";
-import { escapeForDisclosure, hasUnrenderableCharacters, parseRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf, ruleToolGrammarOf, segmentCoverageOf, suggestRuleForName, suggestRulesForCommand, RULE_BEHAVIORS, RULE_BEHAVIOR_PRECEDENCE, isRuleBehavior, } from "./permission-rule-model.js";
+import { escapeForDisclosure, hasUnrenderableCharacters, parseRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf, ruleToolGrammarOf, segmentCoverageOf, suggestRuleForName, suggestRulesForCommand, EDITED_RULE_BREADTH_WARNING_CODES, UNCOVERED_SEGMENT_REASONS, RULE_BEHAVIORS, RULE_BEHAVIOR_PRECEDENCE, isRuleBehavior, } from "./permission-rule-model.js";
 import { effectiveOrThrow } from "./permission-rule-provider.js";
 import { errText, isValidConsentScope, landRuleAdd, sameRuleOwner, sameScope, writerOf } from "./permission-rule-store.js";
+const isUncoveredSegmentReason = (v) => UNCOVERED_SEGMENT_REASONS.some((word) => v === word);
+export const RULE_APPROVAL_KINDS = Object.freeze(["card", "import", "starter"]);
+export const RULE_APPROVAL_STATES = Object.freeze(["pending", "approved", "redeemed"]);
+export const RULE_APPROVAL_RECORD_SCHEMA = 4;
 export class InMemoryRuleApprovalRecordStore {
     rows = new Map();
     async get(id) {
         const r = this.rows.get(id);
         if (r === undefined)
             return undefined;
-        if (r.schema !== 4) {
+        if (r.schema !== RULE_APPROVAL_RECORD_SCHEMA) {
             return {
                 staleSchema: true,
                 id: r.id,
@@ -156,7 +160,7 @@ function approvalRecordDamageOf(rec) {
                     if (typeof row !== "object" ||
                         row === null ||
                         typeof row.segment !== "string" ||
-                        (row.reason !== "redirection" && row.reason !== "no_rule_form" && row.reason !== "cap_overflow")) {
+                        !UNCOVERED_SEGMENT_REASONS.some((word) => row.reason === word)) {
                         return `card batch offer ${at} reason row ${ri} is not a segment/reason row from the closed reason set`;
                     }
                 }
@@ -195,7 +199,7 @@ function approvalRecordDamageOf(rec) {
             return "the edited seat is not an object";
         const w = rec.edited.warnings;
         if (w !== undefined) {
-            if (!Array.isArray(w) || w.length !== 1 || (w[0] !== "broad_prefix" && w[0] !== "compound_prefix")) {
+            if (!Array.isArray(w) || w.length !== 1 || !EDITED_RULE_BREADTH_WARNING_CODES.some((code) => w[0] === code)) {
                 return "the edited seat's warnings are not a single-code array from the closed breadth-code set";
             }
         }
@@ -238,7 +242,7 @@ export function ruleOffersOfRecord(rec) {
                     return true;
                 const segment = row.segment;
                 const reason = row.reason;
-                if (typeof segment !== "string" || (reason !== "redirection" && reason !== "no_rule_form" && reason !== "cap_overflow"))
+                if (typeof segment !== "string" || !isUncoveredSegmentReason(reason))
                     return true;
                 detail.push({ segment, reason });
             }
@@ -348,7 +352,7 @@ export async function prepareCardApproval(opts) {
     const record = {
         id: mintId(opts.deps, "rar"),
         ...recordIdentityOf(owner),
-        schema: 4,
+        schema: RULE_APPROVAL_RECORD_SCHEMA,
         kind: "card",
         state: "pending",
         rev: 0,
@@ -667,6 +671,7 @@ async function applyRedemption(args) {
 function originOfRecordKind(kind) {
     return kind === "import" ? "imported-cc" : kind === "starter" ? "starter" : "user";
 }
+export const IMPORTED_SETTINGS_LAYERS = Object.freeze(["userSettings", "projectSettings", "localSettings"]);
 const IMPORT_UNCOVERED_LAYERS = { flagSettings: "not-imported-v1", policySettings: "not-imported-v1" };
 export async function prepareCcImport(opts) {
     const owner = resolveCallerOwner(opts.principal, opts.owner, "prepareCcImport");
@@ -760,7 +765,7 @@ export async function prepareCcImport(opts) {
     const record = {
         id: mintId(opts.deps, "rar"),
         ...recordIdentityOf(owner),
-        schema: 4,
+        schema: RULE_APPROVAL_RECORD_SCHEMA,
         kind: "import",
         state: "pending",
         rev: 0,
@@ -794,7 +799,7 @@ export async function prepareStarterBatch(opts) {
     const record = {
         id: mintId(opts.deps, "rar"),
         ...recordIdentityOf(owner),
-        schema: 4,
+        schema: RULE_APPROVAL_RECORD_SCHEMA,
         kind: "starter",
         state: "pending",
         rev: 0,

package/dist/core/permission-rule-model.d.ts

@@ -15,7 +15,7 @@
  * The two DIRECTIONS read a command differently, on purpose: an allow must cover the WHOLE call
  * ({@link ruleAdmitsCommand} — one recorded yes clears exactly what it spells), while a deny/ask
  * speaks about any PROGRAM RUN the call may perform ({@link programRunReachOf} — whole command or
- * any segment of a chain, read with a real shell lexer, `shell-lexer.ts`, and answering `unreadable`
+ * any segment of a chain, read off the one shell lexer by `shell-run-candidates.ts`, and answering `unreadable`
  * for what it cannot read rather than silence). Precedence across behaviors is the upstream one,
  * deny > ask > allow ({@link RULE_BEHAVIOR_PRECEDENCE}, the one table every adjudication reads).
  *
@@ -235,6 +235,10 @@ export declare function nameRuleSubjectOf(toolName: string, args: unknown): stri
  *  name, as a policy's rule does. Every lane that judges a call by a rule's word reads it here: the policy compiler, the
  *  person's stored rows, the org partition, the allow lists. Empty ⇒ no grammar speaks for the call. */
 export declare function laneToolNamesOf(req: Pick<import("./tool-policy.js").ToolCallRequest, "toolName" | "face">): readonly string[];
+/** The match words a persisted rule is stored with, spelled once: {@link PersistedRuleMatch} is derived from this
+ *  tuple (each form is documented there). A store backend that checks a stored row's `match` reads this value
+ *  rather than keeping its own list. */
+export declare const PERSISTED_RULE_MATCHES: readonly ["exact", "prefix", "wildcard", "subpath", "path", "name", "name_prefix", "host", "subdomain"];
 /**
  * Match forms, one family per grammar (`prefix` and `wildcard` are one predicate):
  *  · `exact` — admits the one string the rule spells.
@@ -261,7 +265,7 @@ export declare function laneToolNamesOf(req: Pick<import("./tool-policy.js").Too
  *  · `host` / `subdomain` — the DOMAIN grammar ({@link parseDomainRuleContent}): one exact host, or every
  *    host below one domain.
  */
-export type PersistedRuleMatch = "exact" | "prefix" | "wildcard" | "subpath" | "path" | "name" | "name_prefix" | "host" | "subdomain";
+export type PersistedRuleMatch = (typeof PERSISTED_RULE_MATCHES)[number];
 /**
  * Where a rule applies — design/382 §4.1, the THREE consent dimensions.
  *
@@ -306,9 +310,12 @@ export interface RuleDot {
     actor: string;
     counter: number;
 }
+/** The add provenance words, spelled once: {@link RuleAddOrigin} is derived from this tuple, and the sync wire's and
+ *  the session overlay's add checks read it. */
+export declare const RULE_ADD_ORIGINS: readonly ["user", "imported-cc", "starter"];
 /** Where one add came from. Stored PER ADD — never folded across dots (a folded provenance cannot
  *  follow a dot that is later deleted on its own). */
-export type RuleAddOrigin = "user" | "imported-cc" | "starter";
+export type RuleAddOrigin = (typeof RULE_ADD_ORIGINS)[number];
 /** One add of one logical rule, carrying its own dot and its own provenance. */
 export interface RuleAdd {
     dot: RuleDot;
@@ -462,7 +469,7 @@ export declare const BARE_INTERPRETER_NAMES: ReadonlySet<string>;
  *
  * Refusing the keyword puts the whole command outside the ALLOW lane, which is the honest answer: no rule
  * can be minted for it and no allow matches it, so it asks. The DENY/ASK direction reads these shapes
- * with its own lexer (`shell-lexer.ts`: a prefixing keyword is stripped so `do curl evil.example` runs
+ * with its run-candidate view (`shell-run-candidates.ts`: a prefixing keyword is stripped so `do curl evil.example` runs
  * `curl`; a `for`/`case` header, whose commands need a syntax tree, is `unreadable` and asks).
  *
  * `!` is here for the same reason with a sharper edge: it is a keyword that PREFIXES a real command, so
@@ -780,11 +787,14 @@ export declare function programRunReachOf(rule: Pick<PersistedRule, "match" | "c
 /** The boolean face of {@link programRunReachOf}: `reached` only. The shadow view and the pins that
  *  assert a reach read this; a lane that must fail closed on `unreadable` reads the outcome. */
 export declare function ruleReachesProgramRun(rule: Pick<PersistedRule, "match" | "command">, command: string): boolean;
+/** The breadth-warning codes, spelled once: {@link EditedRuleBreadthWarning}'s `code` is derived from this tuple,
+ *  and a consent record's `edited.warnings` stores exactly these words (its readback refuses any other). */
+export declare const EDITED_RULE_BREADTH_WARNING_CODES: readonly ["broad_prefix", "compound_prefix"];
 /** design/382 §3.3-5 — one BREADTH note about a rule a person is about to persist: which wide shape
  *  it has, said in words a surface can show beside the input line. A warning is never a refusal —
  *  the closed refusal set is untouched — and never adjudication input. */
 export interface EditedRuleBreadthWarning {
-    readonly code: "broad_prefix" | "compound_prefix";
+    readonly code: (typeof EDITED_RULE_BREADTH_WARNING_CODES)[number];
     /** The baseline sentence (a surface may reword it, never invert it — the same contract as the
      *  §3.5 reason baselines). */
     readonly message: string;
@@ -1187,6 +1197,11 @@ export interface SegmentRuleSuggestion {
      *  show a reader something other than what they authorize. */
     readonly segment: string;
 }
+/** The batch member discriminants as a value: the `kind` words of {@link RuleOfferBatchMember}, both directions
+ *  fenced at compile time ({@link RuleOfferBatchMemberKindsCoverEveryArm} / {@link RuleOfferBatchMemberArmsCoverEveryKind}).
+ *  A consumer applying the degrade arm below (a member whose `kind` is outside this set drops the whole batch offer)
+ *  reads this value rather than keeping its own list. */
+export declare const RULE_OFFER_BATCH_MEMBER_KINDS: readonly ["command", "directoryRead"];
 /**
  * design/382 §2.3 (B3, BREAKING) — one member of a batch offer, a DISCRIMINATED union keyed by
  * `kind`:
@@ -1215,6 +1230,10 @@ export type RuleOfferBatchMember = (SegmentRuleSuggestion & {
     /** The (folded) cd segment this authorization came from — rendering context, never adjudication input. */
     readonly segment: string;
 };
+/** Compile fence: an arm whose `kind` is not in {@link RULE_OFFER_BATCH_MEMBER_KINDS} turns the argument into that word. */
+export type RuleOfferBatchMemberKindsCoverEveryArm = AssertAllKeysHandled<Exclude<RuleOfferBatchMember["kind"], (typeof RULE_OFFER_BATCH_MEMBER_KINDS)[number]>>;
+/** Compile fence, the other direction: a word in {@link RULE_OFFER_BATCH_MEMBER_KINDS} that no arm carries. */
+export type RuleOfferBatchMemberArmsCoverEveryKind = AssertAllKeysHandled<Exclude<(typeof RULE_OFFER_BATCH_MEMBER_KINDS)[number], RuleOfferBatchMember["kind"]>>;
 /**
  * design/375 §3.1 — ONE "don't ask again" option on an approval card. A CLOSED discriminated union
  * (`kind`); consumers parse it per element, and an element whose `kind` they do not know is dropped
@@ -1278,6 +1297,10 @@ export type RuleOffer = {
      */
     readonly uncoveredDetail?: readonly UncoveredSegmentDetail[];
 };
+/** The uncovered-segment reason words, spelled once: {@link UncoveredSegmentDetail}'s `reason` is derived from this
+ *  tuple, {@link UNCOVERED_SEGMENT_REASON_BASELINE} is keyed by it, and a consent record's reason rows are read
+ *  against it. */
+export declare const UNCOVERED_SEGMENT_REASONS: readonly ["redirection", "no_rule_form", "cap_overflow"];
 /** design/382 §3.5 — the closed reason set for one uncovered segment of a batch offer.
  *
  *  · `"redirection"` — the segment carries a shell redirection: refused by discipline (#490 修①,
@@ -1300,7 +1323,7 @@ export interface UncoveredSegmentDetail {
     /** The folded, trimmed segment text — raw post-rewrite command bytes, same contract as
      *  {@link SegmentRuleSuggestion.segment}. */
     readonly segment: string;
-    readonly reason: "redirection" | "no_rule_form" | "cap_overflow";
+    readonly reason: (typeof UNCOVERED_SEGMENT_REASONS)[number];
 }
 /**
  * design/382 §3.5-2 — the BASELINE "why + outlet" sentence per uncovered-segment reason: the

package/dist/core/permission-rule-model.js

@@ -8,7 +8,7 @@ import { isShellFaceToolName, pathTargetOf, protectivePathTargetOf } from "./too
 import { heldValues } from "./tool-name-readings.js";
 import { carriesDotSegment, isAbsoluteForFamily, isIdentityDir, isPathIdentity, isShellRootedSpellingUnmapped, isUncIdentity, pathFamilyOf, pathIdentityOf } from "../tools/fs/safety.js";
 import { bindPathRules, judgeRuleRows, rowsWhereTheyLead } from "./path-rule-binding.js";
-import { readShellCommand } from "./shell-lexer.js";
+import { readShellCommand } from "./shell-run-candidates.js";
 import { lineDescriptorsOfText, readOnlyLineObjection, readOnlyShellVerdict } from "./read-only-shell.js";
 import { ARTIFACT_ACTIONS } from "./artifact-host.js";
 import { ARTIFACT_TOOL_NAME } from "./tool-catalog-entries.js";
@@ -111,9 +111,11 @@ function ruleWordOf(name) {
         return COMMAND_RULE_TOOL;
     return ruleToolGrammarOf(name) !== undefined ? name : undefined;
 }
+export const PERSISTED_RULE_MATCHES = Object.freeze(["exact", "prefix", "wildcard", "subpath", "path", "name", "name_prefix", "host", "subdomain"]);
 function isCommandMatch(match) {
     return match === "exact" || match === "prefix" || match === "wildcard";
 }
+export const RULE_ADD_ORIGINS = Object.freeze(["user", "imported-cc", "starter"]);
 export const MAX_RULE_TEXT_CHARS = 512;
 export const NOTICE_RULE_TEXT_MAX = 2 * MAX_RULE_TEXT_CHARS;
 export function noticeRuleText(text) {
@@ -811,6 +813,7 @@ function admitsUnder(rule, command, reading) {
         return false;
     return folded === rule.command || folded.startsWith(rule.command + " ");
 }
+export const EDITED_RULE_BREADTH_WARNING_CODES = Object.freeze(["broad_prefix", "compound_prefix"]);
 export function ruleBreadthWarningsOf(rule) {
     if (rule.match !== "prefix" && rule.match !== "wildcard")
         return [];
@@ -1159,6 +1162,8 @@ export function segmentCoverageOf(command, rules, call) {
         };
     });
 }
+export const RULE_OFFER_BATCH_MEMBER_KINDS = Object.freeze(["command", "directoryRead"]);
+export const UNCOVERED_SEGMENT_REASONS = Object.freeze(["redirection", "no_rule_form", "cap_overflow"]);
 export const UNCOVERED_SEGMENT_REASON_BASELINE = {
     redirection: "This part carries a redirection, so it is approved per use — no rule can cover this spelling. If you trust its redirection-free form, a rule can be written for that form (the card's edit row, or settings).",
     no_rule_form: "No rule form exists for this part; it can be approved per use.",

package/dist/core/permission-rule-org.d.ts

@@ -276,6 +276,27 @@ export declare function orgRuleListOf(rules: unknown): {
 } | {
     readonly refused: string;
 };
+/** A snapshot the partition holds whose rules the list judgment refused: the envelope it carried and the words it was refused in,
+ *  judged ONCE, on the list as it stood at the receipt. It has no `rules` at all (so no reading can take it for a table of zero
+ *  rows) and keeps none of the caller's value (a list past the cap is a live array, and the partition awaits its persistence
+ *  between the receipt and the validator, so a source that shrank the list it handed over in between would otherwise be admitted,
+ *  uncopied and mutable, on a judgment it no longer meets). It is never installed or served. */
+export interface RefusedOrgSnapshot extends Omit<OrgRuleSnapshot, "rules"> {
+    readonly refused: string;
+}
+/** What the partition holds of one snapshot, fetched or read back: one that can be installed, or the refusal of one that cannot.
+ *  Read it by its shape — `rules` is on the first arm only, and {@link validateOrgSnapshot} is the one way from a held snapshot to an
+ *  installable one. */
+export type HeldOrgSnapshot = OrgRuleSnapshot | RefusedOrgSnapshot;
+/** A snapshot as the partition holds it — fetched from the source or read back from its persistence alike: its envelope's members
+ *  ({@link ORG_SNAPSHOT_ENVELOPE_MEMBERS} through {@link scalarMembersOf}; anything else it carries is never read or kept), its
+ *  rows as the one list reader reads them (each row its policy) — so a snapshot read back reads, and compares, exactly as the one
+ *  fetched, and what is persisted is never larger than these. Rules the list judgment refuses (not a list, a Proxy, past the cap)
+ *  are held as that refusal alone ({@link RefusedOrgSnapshot}; the list judgment runs no code of the value's); such a snapshot — and
+ *  one that is not an object, whose envelope has no members — is never installed or served. A list that cannot be received, and a
+ *  Proxy snapshot (its traps would answer for the envelope), throw: an envelope that cannot be copied. Exported for the pins; the
+ *  package root does not carry it. */
+export declare function orgSnapshotCopyOf(v: unknown): HeldOrgSnapshot;
 /**
  * The ONE reading of an org snapshot's rows: each row read once ({@link readOrgRow}), and the one judgment of a call
  * against them. Every reader of org rows goes through it — the partition's degraded line, the lane's adjudication,
@@ -319,6 +340,22 @@ export declare function orgUnreadableClause(reason: string): string;
  * exactly the ones that do not render.
  */
 export declare function describeUnreadableOrgRows(unreadable: readonly UnreadableOrgRow[], revision?: unknown): string | undefined;
+/**
+ * Envelope validation of one held snapshot — what the staleness bound and the anti-rollback fence need to judge it. Answers
+ * the snapshot as an installable one, or the words it is refused in: a finite revision, a finite observation time not in the
+ * future beyond the skew allowance, and rules that are a LIST ({@link listRefusalOf}, judged at the receipt — a held snapshot
+ * whose list was refused there is answered in those words). The rows inside are not judged here: a row this layer cannot
+ * read is read as such by {@link readOrgRules}, and never takes the rest of the snapshot down with it.
+ *
+ * Run on BOTH the fetch path (before install) and the serving path (before a persisted snapshot adjudicates), so the
+ * two cannot diverge on what an installable snapshot is — see backlog #177. The only way from a {@link HeldOrgSnapshot} to an
+ * installable {@link OrgRuleSnapshot}: install and serve read the `admitted` arm.
+ */
+export declare function validateOrgSnapshot(s: HeldOrgSnapshot, nowMs: number): {
+    readonly admitted: OrgRuleSnapshot;
+} | {
+    readonly refused: string;
+};
 /**
  * design/182 §7.2 — which org rule speaks for this call, if any: {@link readOrgRules}'s judgment, over a snapshot read for
  * this call alone. Matching uses the SAME parser and the SAME tightening reach the personal deny/ask rows use

package/dist/core/permission-rule-org.js

@@ -81,7 +81,7 @@ export function createOrgRulePartition(cfg) {
                 throw new Error(`the org snapshot source did not answer within ${ORG_ADJUDICATION_TIMEOUT_MS}ms`);
             if ("e" in settled)
                 throw settled.e;
-            fetched = orgSnapshotCopyOf(settled.v);
+            fetched = settled.v === undefined ? undefined : orgSnapshotCopyOf(settled.v);
         }
         catch (err) {
             fetchFailed = true;
@@ -102,29 +102,30 @@ export function createOrgRulePartition(cfg) {
                 const persisted = await guardedRead("persistence");
                 if (fetched === undefined)
                     return persisted;
-                const invalid = validateOrgSnapshot(fetched, nowMs);
-                if (invalid !== undefined) {
-                    disclosures.push(`org snapshot refused: ${invalid}; the previously installed snapshot (if any) remains in force`);
+                const judged = validateOrgSnapshot(fetched, nowMs);
+                if ("refused" in judged) {
+                    disclosures.push(`org snapshot refused: ${judged.refused}; the previously installed snapshot (if any) remains in force`);
                     return persisted;
                 }
+                const incoming = judged.admitted;
                 const persistedFloor = persisted === undefined ? undefined : antiRollbackFloor(persisted);
                 if (persisted !== undefined && !persistedMarkIsCoherent(persisted)) {
                     disclosures.push(`the durable org state carries a high-water mark (${escapeForDisclosure(persisted.revisionHighWater)}) that is not a finite number at or above its own snapshot revision (${escapeForDisclosure(persisted.snapshot?.revision)}) — the anti-rollback fence is being held at ${escapeForDisclosure(persistedFloor)} instead, and the durable state should be repaired`);
                 }
-                if (persistedFloor !== undefined && fetched.revision < persistedFloor) {
-                    disclosures.push(`org snapshot revision ${fetched.revision} is below the installed high-water mark ${escapeForDisclosure(persistedFloor)} — refusing the rollback; the current deny set is unchanged`);
+                if (persistedFloor !== undefined && incoming.revision < persistedFloor) {
+                    disclosures.push(`org snapshot revision ${incoming.revision} is below the installed high-water mark ${escapeForDisclosure(persistedFloor)} — refusing the rollback; the current deny set is unchanged`);
                     return persisted;
                 }
-                if (persisted !== undefined && fetched.revision === persisted.snapshot.revision && sameOrgPolicyContent(fetched, persisted.snapshot) && fetched.fetchedAtMs <= persisted.snapshot.fetchedAtMs) {
+                if (persisted !== undefined && incoming.revision === persisted.snapshot.revision && sameOrgPolicyAsHeld(incoming, persisted.snapshot) && incoming.fetchedAtMs <= persisted.snapshot.fetchedAtMs) {
                     return persisted;
                 }
-                if (persisted !== undefined && fetched.revision === persisted.snapshot.revision && !sameOrgPolicyContent(fetched, persisted.snapshot)) {
-                    disclosures.push(`org snapshot revision ${fetched.revision} equals the installed revision but carries DIFFERENT policy content — refusing the swap; the current deny set is unchanged`);
+                if (persisted !== undefined && incoming.revision === persisted.snapshot.revision && !sameOrgPolicyAsHeld(incoming, persisted.snapshot)) {
+                    disclosures.push(`org snapshot revision ${incoming.revision} equals the installed revision but carries DIFFERENT policy content — refusing the swap; the current deny set is unchanged`);
                     return persisted;
                 }
                 const state = {
-                    revisionHighWater: Math.max(persistedFloor !== undefined && Number.isFinite(persistedFloor) ? persistedFloor : 0, fetched.revision),
-                    snapshot: fetched,
+                    revisionHighWater: Math.max(persistedFloor !== undefined && Number.isFinite(persistedFloor) ? persistedFloor : 0, incoming.revision),
+                    snapshot: incoming,
                     installedAtMs: nowMs,
                 };
                 try {
@@ -148,24 +149,25 @@ export function createOrgRulePartition(cfg) {
                     disclosures.push(`the installed org snapshot claims a FUTURE observation time (${escapeForDisclosure(installed.snapshot.fetchedAtMs)} vs now ${decisionMs}) — org adjudication is UNAVAILABLE; the consuming gate must tighten every terminal allow to a real-approval ask`);
                     return { source: "org", status: "unavailable", rules: [], disclosures };
                 }
-                const servingRefusal = validateOrgSnapshot(installed.snapshot, decisionMs);
-                if (servingRefusal !== undefined) {
-                    disclosures.push(`the installed org snapshot (revision ${escapeForDisclosure(installed.snapshot.revision)}) does not meet this version's validator: ${servingRefusal} — org adjudication is UNAVAILABLE; the consuming gate must tighten every terminal allow to a real-approval ask`);
+                const serving = validateOrgSnapshot(installed.snapshot, decisionMs);
+                if ("refused" in serving) {
+                    disclosures.push(`the installed org snapshot (revision ${escapeForDisclosure(installed.snapshot.revision)}) does not meet this version's validator: ${serving.refused} — org adjudication is UNAVAILABLE; the consuming gate must tighten every terminal allow to a real-approval ask`);
                     return { source: "org", status: "unavailable", rules: [], disclosures };
                 }
-                if (withinBound(installed.snapshot)) {
+                const served = serving.admitted;
+                if (withinBound(served)) {
                     const freshlyInstalled = fetched !== undefined && installed.snapshot === fetched;
                     if (!freshlyInstalled && !fetchFailed && fetched === undefined) {
                         disclosures.push("org snapshot source returned no snapshot — continuing on the last-known-good");
                     }
-                    const degraded = describeUnreadableOrgRows(readListedOrgRules(installed.snapshot.rules).unreadable, installed.snapshot.revision);
+                    const degraded = describeUnreadableOrgRows(readListedOrgRules(served.rules).unreadable, served.revision);
                     if (degraded !== undefined)
                         disclosures.push(degraded);
                     return {
                         source: "org",
                         status: freshlyInstalled ? "fresh" : "last-known-good",
-                        rules: structuredClone(installed.snapshot.rules),
-                        revision: installed.snapshot.revision,
+                        rules: structuredClone(served.rules),
+                        revision: served.revision,
                         disclosures,
                     };
                 }
@@ -203,6 +205,9 @@ export function sameOrgPolicyContent(a, b) {
     const policy = (r) => canonicalize(orgRowPolicyOf(r));
     return a.rules.every((r, i) => policy(b.rules[i]) === policy(r));
 }
+function sameOrgPolicyAsHeld(a, b) {
+    return !("refused" in b) && sameOrgPolicyContent(a, b);
+}
 const DISCLOSED_UNREADABLE_ROWS = 20;
 function reachOfRowHead(text, behavior) {
     const head = typeof text === "string" ? ruleSpellingOf(text)?.toolName : undefined;
@@ -221,13 +226,8 @@ function rowReaches(reach, words, face) {
     return reach.words.some((w) => words.includes(w)) || (face !== undefined && reach.faces.includes(face));
 }
 function listRefusalOf(rules) {
-    if (typeof rules === "object" && rules !== null) {
-        if (types.isProxy(rules))
-            return "rules is a Proxy, not an array";
-        const held = HELD_LIST_REFUSALS.get(rules);
-        if (held !== undefined)
-            return held;
-    }
+    if (typeof rules === "object" && rules !== null && types.isProxy(rules))
+        return "rules is a Proxy, not an array";
     if (!Array.isArray(rules))
         return "rules is not an array";
     const cap = DEFAULT_CAPS.maxRules;
@@ -262,22 +262,14 @@ export function orgRuleListOf(rules) {
     const copy = received.value;
     return { rows: Array.from({ length: copy.length }, (_, i) => orgRowPolicyOf(Object.hasOwn(copy, i) ? copy[i] : undefined)) };
 }
-const HELD_LIST_REFUSALS = new WeakMap();
-function heldRefusalOf(words) {
-    const held = Object.freeze({});
-    HELD_LIST_REFUSALS.set(held, words);
-    return held;
-}
-function orgSnapshotCopyOf(v) {
-    if (v === undefined)
-        return undefined;
+export function orgSnapshotCopyOf(v) {
     if (typeof v === "object" && v !== null && types.isProxy(v))
         throw new Error("the snapshot is a Proxy, not data");
     const envelope = scalarMembersOf(v, ORG_SNAPSHOT_ENVELOPE_MEMBERS);
     const rules = typeof v === "object" && v !== null ? v.rules : undefined;
-    const refusal = listRefusalOf(rules);
-    if (refusal !== undefined)
-        return { ...envelope, rules: heldRefusalOf(refusal) };
+    const refused = listRefusalOf(rules);
+    if (refused !== undefined)
+        return { ...envelope, refused };
     const list = orgRuleListOf(rules);
     if ("refused" in list)
         throw new Error(`the snapshot's ${list.refused}`);
@@ -379,15 +371,15 @@ export function describeUnreadableOrgRows(unreadable, revision) {
     return (`the org snapshot${revision !== undefined ? ` (revision ${escapeForDisclosure(revision)})` : ""} is served DEGRADED: ${unreadable.length} row(s) this layer cannot read — ${named}${more > 0 ? ` and ${more} more` : ""}; ` +
         `each stands at its strictest reading over the calls it may reach (a deny row, or one whose behavior cannot be read, refuses them; an ask row asks a person), and every readable row stands as published — republish the named rows in the shell tool's command grammar`);
 }
-function validateOrgSnapshot(s, nowMs) {
+export function validateOrgSnapshot(s, nowMs) {
     if (typeof s.revision !== "number" || !Number.isFinite(s.revision))
-        return `revision is not a finite number (${escapeForDisclosure(s.revision)})`;
+        return { refused: `revision is not a finite number (${escapeForDisclosure(s.revision)})` };
     if (typeof s.fetchedAtMs !== "number" || !Number.isFinite(s.fetchedAtMs))
-        return `fetchedAtMs is not a finite number (${escapeForDisclosure(s.fetchedAtMs)})`;
+        return { refused: `fetchedAtMs is not a finite number (${escapeForDisclosure(s.fetchedAtMs)})` };
     if (s.fetchedAtMs > nowMs + ORG_FETCHED_AT_SKEW_ALLOWANCE_MS) {
-        return `fetchedAtMs is ${s.fetchedAtMs - nowMs}ms in the future (allowance ${ORG_FETCHED_AT_SKEW_ALLOWANCE_MS}ms) — a future-dated observation would satisfy the staleness bound indefinitely`;
+        return { refused: `fetchedAtMs is ${s.fetchedAtMs - nowMs}ms in the future (allowance ${ORG_FETCHED_AT_SKEW_ALLOWANCE_MS}ms) — a future-dated observation would satisfy the staleness bound indefinitely` };
     }
-    return listRefusalOf(s.rules);
+    return "refused" in s ? { refused: s.refused } : { admitted: s };
 }
 export function orgRuleVerdictFor(rules, call) {
     return readListedOrgRules(rules).verdictFor(call);