@sema-agent/core 5.27.0 → 5.28.0

package/dist/core/memory-engine/layout.js

@@ -1,5 +1,5 @@
-import { closeSync, constants as fsConstants, copyFileSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
-const { O_WRONLY, O_CREAT, O_TRUNC, O_NOFOLLOW } = fsConstants;
+import { closeSync, constants as fsConstants, copyFileSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+const { O_WRONLY, O_CREAT, O_TRUNC, O_NOFOLLOW, O_EXCL } = fsConstants;
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
@@ -184,6 +184,119 @@ export function scopeDirName(scope) {
     const hash = createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 6);
     return `${cleaned}-${hash}`;
 }
+const caseFoldByDirIdentity = new Map();
+let caseFoldProbeSeq = 0;
+function lstatOrAbsent(p) {
+    try {
+        return lstatSync(p);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+}
+function probeDirCaseFolds(dir) {
+    const name = `.casefold-probe-${process.pid}-${caseFoldProbeSeq++}`;
+    const writeLeg = (() => {
+        let fd;
+        try {
+            fd = openSync(join(dir, name), O_WRONLY | O_CREAT | O_EXCL, 0o600);
+        }
+        catch {
+            return undefined;
+        }
+        let identity;
+        try {
+            const st = fstatSync(fd);
+            identity = { dev: st.dev, ino: st.ino };
+        }
+        catch {
+        }
+        finally {
+            closeSync(fd);
+        }
+        try {
+            let swapped;
+            let orig;
+            try {
+                swapped = lstatOrAbsent(join(dir, name.toUpperCase()));
+                orig = swapped === undefined ? lstatOrAbsent(join(dir, name)) : undefined;
+            }
+            catch {
+                return undefined;
+            }
+            if (swapped !== undefined) {
+                return identity === undefined || (swapped.dev === identity.dev && swapped.ino === identity.ino) ? true : undefined;
+            }
+            if (orig === undefined || identity === undefined)
+                return undefined;
+            return orig.dev === identity.dev && orig.ino === identity.ino ? false : undefined;
+        }
+        finally {
+            try {
+                rmSync(join(dir, name), { force: true });
+            }
+            catch {
+            }
+        }
+    })();
+    if (writeLeg !== undefined)
+        return writeLeg;
+    try {
+        for (const entry of readdirSync(dir)) {
+            if (!/[A-Za-z]/.test(entry))
+                continue;
+            const swapped = entry.toLowerCase() !== entry ? entry.toLowerCase() : entry.toUpperCase();
+            try {
+                const orig = lstatOrAbsent(join(dir, entry));
+                if (orig === undefined)
+                    continue;
+                const other = lstatOrAbsent(join(dir, swapped));
+                const again = lstatOrAbsent(join(dir, entry));
+                if (again === undefined || again.dev !== orig.dev || again.ino !== orig.ino)
+                    continue;
+                if (other === undefined)
+                    return false;
+                return other.dev === orig.dev && other.ino === orig.ino;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    catch {
+    }
+    return undefined;
+}
+export function dirCaseFolds(dir) {
+    let key;
+    try {
+        ensureDirExists(dir);
+        const s = statSync(dir);
+        key = `${s.dev}:${s.ino}`;
+    }
+    catch {
+    }
+    if (key !== undefined) {
+        const cached = caseFoldByDirIdentity.get(key);
+        if (cached !== undefined)
+            return cached;
+    }
+    const folds = probeDirCaseFolds(dir);
+    if (folds === undefined)
+        return undefined;
+    try {
+        const after = statSync(dir);
+        if (key === undefined || key !== `${after.dev}:${after.ino}`)
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    caseFoldByDirIdentity.set(key, folds);
+    return folds;
+}
 function readScopesRecord(controlDir) {
     const path = join(controlDir, SCOPES_FILE);
     let raw;
@@ -217,6 +330,11 @@ function readScopesRecord(controlDir) {
         for (const [k, v] of Object.entries(rec.scopes)) {
             if (typeof v !== "string")
                 throw new ControlPlaneCorruptError(`scope registry entry ${JSON.stringify(k)} is not a string: ${path}`);
+            if ((v === "") !== (k === rec.rootScope)) {
+                throw new ControlPlaneCorruptError(v === ""
+                    ? `scope registry maps ${JSON.stringify(k)} to the root home but rootScope is ${rec.rootScope === undefined ? "unclaimed" : JSON.stringify(rec.rootScope)}: ${path}`
+                    : `scope registry maps the root scope ${JSON.stringify(k)} to subdir ${JSON.stringify(v)} instead of the root home: ${path}`);
+            }
         }
         scopes = rec.scopes;
     }
@@ -255,20 +373,26 @@ export function claimRootScope(controlDir, scope) {
         return { next: { rootScope: scope, scopes: { ...rec.scopes, [scope]: "" } }, result: scope };
     });
 }
-export function registerScope(memoryDir, controlDir, scope) {
+export function registerScope(memoryDir, controlDir, scope, opts) {
     return lockedScopesUpdate(controlDir, (rec) => {
-        const dirName = rec.rootScope === scope ? "" : scopeDirName(scope);
+        const dirName = rec.rootScope === scope ? "" : (rec.scopes?.[scope] ?? scopeDirName(scope));
         for (const [other, otherDir] of Object.entries(rec.scopes ?? {})) {
-            if (other !== scope && otherDir !== "" && otherDir === dirName) {
+            if (other === scope || otherDir === "")
+                continue;
+            if (otherDir === dirName) {
                 throw new ControlPlaneCorruptError(`scope directory collision: ${JSON.stringify(scope)} and ${JSON.stringify(other)} both map to ${JSON.stringify(dirName)} — refusing (fail-closed)`);
             }
+            if (dirName !== "" && otherDir.toLowerCase() === dirName.toLowerCase()) {
+                const folds = opts?.caseFoldingFs ?? dirCaseFolds(memoryDir);
+                if (folds !== false) {
+                    throw new ControlPlaneCorruptError(`scope directory collision on a case-folding filesystem: ${JSON.stringify(scope)} → ${JSON.stringify(dirName)} and ${JSON.stringify(other)} → ${JSON.stringify(otherDir)} are one physical directory under ${memoryDir}` +
+                        `${folds === undefined ? " (volume case semantics could not be probed — refusing the fold-equal pair rather than risking a silent cross-scope merge)" : ""} — refusing (fail-closed)`);
+                }
+            }
         }
         if (rec.scopes?.[scope] === undefined) {
             return { next: { ...rec, scopes: { ...rec.scopes, [scope]: dirName } }, result: dirName === "" ? memoryDir : join(memoryDir, dirName) };
         }
-        if (rec.scopes[scope] !== dirName) {
-            return { result: rec.scopes[scope] === "" ? memoryDir : join(memoryDir, rec.scopes[scope]) };
-        }
         return { result: dirName === "" ? memoryDir : join(memoryDir, dirName) };
     });
 }

package/dist/core/memory-engine/types.d.ts

@@ -224,11 +224,12 @@ export interface MemorySessionHandle {
      *  leave the injection path reading them anyway. Absent ⇒ the normal "live file wins" behavior. */
     indexOnDiskUntrusted?: boolean;
     /** True ⇔ this session materialized through the ADOPTION-RESTRICTED (committed-view) read face:
-     *  either the plane is a read-only layering (`writeScope === null`) or the caller declared the
-     *  session unable to persist (an explicit verdict — never inferred down here). Restricted sessions
-     *  read committed state only (ledger + control-plane shadow); disk divergence with no transaction
-     *  backing is neither adopted into the committed account nor served, and `inject` reads the
-     *  materialize-time index text instead of the live on-disk file. */
+     *  the caller declared the session unable to persist (an explicit session-level verdict — never
+     *  inferred down here, and never derived from the plane's shape: a read-only layering
+     *  (`writeScope === null`) keeps its ordinary adopt-on-read semantics and does NOT set this).
+     *  Restricted sessions read committed state only (ledger + control-plane shadow); disk divergence
+     *  with no transaction backing is neither adopted into the committed account nor served, and
+     *  `inject` reads the materialize-time index text instead of the live on-disk file. */
     adoptionRestricted?: boolean;
 }
 /** Stable rejection codes a harvest gate can produce (model-visible gate events — 镜头 I). */

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

@@ -27,7 +27,7 @@
  * this by editing a file backend's file. That is the settings-file trust model, stated rather than
  * defended against: for a file backend, host = user, no more and no less.
  */
-import { type RuleScope, type RuleDot } from "./permission-rule-model.js";
+import { type RuleRejectCode, type RuleScope, type RuleDot } from "./permission-rule-model.js";
 import type { PermissionRuleStoreProvider, RuleOwner } from "./permission-rule-store.js";
 /** One candidate rule inside an approval record: the exact text and where it would apply. */
 export interface RuleCandidate {
@@ -52,9 +52,19 @@ export interface RuleApprovalRecord {
     state: "pending" | "approved" | "redeemed";
     candidates: RuleCandidate[];
     createdAt: string;
-    /** The ask this record was drawn from, for reconciliation. Advisory metadata; never adjudication input. */
+    /** The ask this record was drawn from, for reconciliation. Advisory metadata; never adjudication input.
+     *  `boundInputHash` is ALSO the card-edit binding anchor: an edited-candidate confirmation must echo
+     *  it back, so a record minted without one refuses edits (there is nothing to bind the edit to). */
     toolCallId?: string;
     boundInputHash?: string;
+    /**
+     * The adjudicated command a CARD record was drawn for — the same post-rewrite bytes the ask carried
+     * (the form `boundInputHash` digests). Additive: absent on batch records and on every card a prior
+     * version minted. It is the edit gate's coverage input ("the edited rule must still admit THIS
+     * command"), so a record without one refuses edited candidates rather than guessing; the engine-
+     * candidate paths never read it.
+     */
+    command?: string;
     /** Monotonic revision of THIS record, bumped by every accepted transition. The compare-and-set key:
      *  comparing state alone cannot separate two different writes that both leave the state unchanged. */
     rev: number;
@@ -68,6 +78,20 @@ export interface RuleApprovalRecord {
      * previewed list by construction.
      */
     selectedCandidate?: number;
+    /**
+     * The person-EDITED candidate this record carries, if any — full provenance for the one candidate
+     * whose text was authored at the card rather than derived by the engine. `index` names the appended
+     * row in `candidates` (whose `rule` holds the CANONICAL spelling); `text` keeps the raw input bytes
+     * exactly as submitted (the idempotency primary key — a client retrying a lost response resends the
+     * same bytes); `at` is when the edit landed. Present ⇒ `selectedCandidate === index` (the edit and
+     * the choice are one CAS write). Absent on every record a prior version minted and on every card
+     * settled through an engine candidate.
+     */
+    edited?: {
+        index: number;
+        text: string;
+        at: string;
+    };
     /** Dots already minted for this record, keyed by candidate index — the replay anchor. */
     redeemedDots?: Record<number, RuleDot>;
 }
@@ -95,6 +119,16 @@ export interface RuleConsentDeps {
     /** Injectable clock/id for deterministic tests; defaults are the real ones. */
     now?: () => Date;
     newId?: () => string;
+    /**
+     * Deployment lever for the card-edit face: whether `confirmRuleApproval` accepts a FRESH
+     * `editedCandidate`. Absent or `false` = OFF (the default — the edit face widens what a fabricated
+     * confirmation could mint, from "one of the engine's bounded candidates" to "any same-head rule
+     * passing the coverage gate", so it is opt-in). Any other non-boolean value is a configuration
+     * mistake and refuses LOUDLY at the read — never silently mapped to a default. Replaying an edit a
+     * record already settled is a pure record read and does not consult this switch: the minting already
+     * happened, and withholding the receipt helps no one.
+     */
+    cardEdits?: boolean;
 }
 /** In-memory approval records — the test backend and the reference CAS semantics. */
 export declare class InMemoryRuleApprovalRecordStore implements RuleApprovalRecordStore {
@@ -157,21 +191,61 @@ export declare function confirmRuleApproval(opts: {
     /** design/182 §4.5 (additive): the structural owner — only the local-owner path needs it. */
     owner?: RuleOwner;
     /**
-     * REQUIRED for a card record: the index of the option the person chose. A card presents alternatives of
-     * different breadth, so "they said yes" is not an answer on its own — "they said yes to THIS one" is.
-     * Rejected on a batch record, whose confirmation covers the previewed list by construction.
+     * REQUIRED for a card record settled through an ENGINE candidate: the index of the option the person
+     * chose. A card presents alternatives of different breadth, so "they said yes" is not an answer on
+     * its own — "they said yes to THIS one" is. Rejected on a batch record, whose confirmation covers
+     * the previewed list by construction. Mutually exclusive with `editedCandidate`.
      */
     selectedCandidate?: number;
+    /**
+     * The person-EDITED rule text for this card, travelling on the SAME authenticated confirmation
+     * channel as a choice among the engine's candidates (never the un-authenticated prepare entry, which
+     * keeps refusing caller candidates). `text` is the rule as authored; `boundInputHash` must echo the
+     * record's own bound-input digest — the submitter's proof of "I am editing the card that showed THIS
+     * command", an in-process mis-binding fence (a caller holding only a leaked approvalId cannot spell
+     * it), not a cryptographic one. The engine validates the text through the one shared validator,
+     * requires it to still ADMIT the adjudicated command, appends it as a new candidate and binds the
+     * selection to it, returning the minted ticket. Mutually exclusive with `selectedCandidate`.
+     */
+    editedCandidate?: {
+        text: string;
+        boundInputHash: string;
+    };
     deps: RuleConsentDeps;
 }): Promise<ConfirmResult>;
-/** Why a confirmation did not land. A closed set so a host can branch (re-present, re-fetch, give up). */
-export type ConfirmRefusalReason = "record_not_found" | "selection_missing" | "selection_invalid" | "selection_mismatch" | "batch_takes_no_selection" | "not_pending" | "conflict";
-/** The confirmation outcome: landed, or refused with a named reason. */
+/** Why a confirmation did not land. A closed set so a host can branch (re-present, re-fetch, give up).
+ *  The three `edit_*` members are the card-edit face's own refusals:
+ *   - `"edit_disabled"` — the deployment has not opted into card edits (`RuleConsentDeps.cardEdits`);
+ *   - `"edit_binding_mismatch"` — the confirmation does not echo the record's bound-input digest
+ *     (missing echo, a record minted without one, or a different card). Refused BEFORE anything else,
+ *     settled replays included, and never returns a minted ticket;
+ *   - `"edit_rejected"` — the edited text failed a gate (validator refusal, coverage, record shape);
+ *     `detail` carries the specifics. */
+export type ConfirmRefusalReason = "record_not_found" | "selection_missing" | "selection_invalid" | "selection_mismatch" | "batch_takes_no_selection" | "not_pending" | "conflict" | "edit_disabled" | "edit_binding_mismatch" | "edit_rejected";
+/** The confirmation outcome: landed, or refused with a named reason.
+ *
+ *  `mintedCandidate` (additive) is present exactly when an EDITED candidate settled this confirmation —
+ *  fresh mint and idempotent replay alike (a client retrying a lost response gets the same index, the
+ *  same canonical rule text and the same deterministically re-minted ticket, never a push toward a
+ *  second card). `rule` is the CANONICAL spelling, which may differ from the submitted bytes (spelling
+ *  normalization); a surface echoes it back so the person sees the form that will actually persist.
+ *
+ *  `detail` (additive, refusal arm) rides `edit_rejected`: `code` is the shared validator's refusal
+ *  code when the validator is what refused, absent when another gate did; `message` always says why. */
 export type ConfirmResult = {
     ok: true;
+    mintedCandidate?: {
+        index: number;
+        rule: string;
+        ticket: RuleTicket;
+    };
 } | {
     ok: false;
     reason: ConfirmRefusalReason;
+    detail?: {
+        code?: RuleRejectCode;
+        message: string;
+    };
 };
 /** What a redemption produced. `alreadyRedeemed` marks the replay path — the same dot, no second rule. */
 export type RedeemResult = {

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

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { parseAllowRuleText, suggestRulesForCommand } from "./permission-rule-model.js";
+import { parseAllowRuleText, ruleAdmitsCommand, suggestRulesForCommand } from "./permission-rule-model.js";
 import { errText, sameRuleOwner, sameScope, writerOf } from "./permission-rule-store.js";
 export class InMemoryRuleApprovalRecordStore {
     rows = new Map();
@@ -109,6 +109,7 @@ export async function prepareCardApproval(opts) {
         state: "pending",
         rev: 0,
         candidates,
+        command: opts.command,
         createdAt: nowIso(opts.deps),
         ...(opts.toolCallId !== undefined ? { toolCallId: opts.toolCallId } : {}),
         ...(opts.boundInputHash !== undefined ? { boundInputHash: opts.boundInputHash } : {}),
@@ -120,10 +121,17 @@ const CARD_RULE_TOOL = "Bash";
 export async function confirmRuleApproval(opts) {
     const caller = resolveCallerOwner(opts.principal, opts.owner, "confirmRuleApproval");
     const no = (reason) => ({ ok: false, reason });
+    if (opts.editedCandidate !== undefined && opts.selectedCandidate !== undefined) {
+        const e = new Error("confirmRuleApproval takes selectedCandidate OR editedCandidate, never both — one confirmation carries one choice");
+        e.code = "config.invalid_argument";
+        throw e;
+    }
     const rec = await opts.deps.approvals.get(opts.approvalId);
     const recOwner = rec === undefined ? undefined : ownerOfRecord(rec);
     if (rec === undefined || recOwner === undefined || !sameRuleOwner(recOwner, caller))
         return no("record_not_found");
+    if (opts.editedCandidate !== undefined)
+        return await confirmEditedCandidate(rec, opts.editedCandidate, opts.deps);
     if (rec.kind === "card") {
         const chosen = opts.selectedCandidate;
         if (chosen === undefined)
@@ -145,6 +153,89 @@ export async function confirmRuleApproval(opts) {
     const won = await opts.deps.approvals.cas(rec.id, rec.rev, { ...rec, rev: rec.rev + 1, state: "approved" });
     return won ? { ok: true } : no("conflict");
 }
+function normalizeEditedSpelling(text) {
+    const m = /^([A-Za-z][A-Za-z0-9_]*)\((.+) \*\)$/.exec(text);
+    if (m === null)
+        return text;
+    const head = m[1];
+    const body = m[2];
+    if (head === undefined || body === undefined || body.includes("*"))
+        return text;
+    return `${head}(${body}:*)`;
+}
+async function confirmEditedCandidate(rec, edit, deps) {
+    const no = (reason, detail) => ({
+        ok: false,
+        reason,
+        ...(detail !== undefined ? { detail } : {}),
+    });
+    if (rec.kind !== "card") {
+        return no("edit_rejected", { message: "a batch record takes no edited candidate — its confirmation covers the previewed list whole" });
+    }
+    if (typeof edit.boundInputHash !== "string" || edit.boundInputHash === "")
+        return no("edit_binding_mismatch");
+    if (rec.boundInputHash === undefined) {
+        return no("edit_binding_mismatch");
+    }
+    if (edit.boundInputHash !== rec.boundInputHash)
+        return no("edit_binding_mismatch");
+    if (rec.state === "approved" || rec.state === "redeemed") {
+        if (rec.edited === undefined)
+            return no("selection_mismatch");
+        const canonical = rec.candidates[rec.edited.index]?.rule;
+        if (canonical === undefined)
+            return no("selection_mismatch");
+        let hit = edit.text === rec.edited.text;
+        if (!hit) {
+            const reparsed = parseAllowRuleText(normalizeEditedSpelling(edit.text));
+            hit = "rule" in reparsed && reparsed.rule.rule === canonical;
+        }
+        if (!hit)
+            return no("selection_mismatch");
+        return { ok: true, mintedCandidate: { index: rec.edited.index, rule: canonical, ticket: mintRuleTicket(rec.id, rec.edited.index) } };
+    }
+    if (rec.state !== "pending")
+        return no("not_pending");
+    if (deps.cardEdits !== undefined && typeof deps.cardEdits !== "boolean") {
+        throw new Error(`RuleConsentDeps.cardEdits must be a boolean when present (got ${typeof deps.cardEdits}) — refusing to guess whether the card-edit face is enabled`);
+    }
+    if (deps.cardEdits !== true)
+        return no("edit_disabled");
+    const scope = rec.candidates[0]?.scope;
+    if (scope === undefined || !rec.candidates.every((c) => sameScope(c.scope, scope))) {
+        return no("edit_rejected", { message: "the record's candidates carry no single common scope — an edited candidate inherits the card's scope, and a record without one is malformed" });
+    }
+    if (rec.command === undefined) {
+        return no("edit_rejected", { message: "the record does not carry the adjudicated command (minted before card edits existed) — coverage cannot be verified, so the edit is refused" });
+    }
+    const parsed = parseAllowRuleText(normalizeEditedSpelling(edit.text));
+    if ("reject" in parsed)
+        return no("edit_rejected", { code: parsed.reject.code, message: parsed.reject.message });
+    if (!ruleAdmitsCommand(parsed.rule, rec.command)) {
+        return no("edit_rejected", {
+            message: `the edited rule "${parsed.rule.rule}" does not admit the command that was decided ("${rec.command}") — a card's edit may widen how much the rule covers, never move it to a different grant`,
+        });
+    }
+    const index = rec.candidates.length;
+    const next = {
+        ...rec,
+        rev: rec.rev + 1,
+        state: "approved",
+        candidates: [...rec.candidates, { rule: parsed.rule.rule, scope }],
+        selectedCandidate: index,
+        edited: { index, text: edit.text, at: nowIso(deps) },
+    };
+    const won = await deps.approvals.cas(rec.id, rec.rev, next);
+    if (!won) {
+        const again = await deps.approvals.get(rec.id);
+        if (again === undefined)
+            return no("record_not_found");
+        if (again.state === "pending")
+            return no("conflict");
+        return await confirmEditedCandidate(again, edit, deps);
+    }
+    return { ok: true, mintedCandidate: { index, rule: parsed.rule.rule, ticket: mintRuleTicket(rec.id, index) } };
+}
 export async function redeemRuleTicket(opts) {
     const caller = resolveCallerOwner(opts.principal, opts.owner, "redeemRuleTicket");
     const parsed = parseRuleTicket(opts.ticket);

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

@@ -94,7 +94,7 @@ export interface RuleTombstone {
     deletedBy: RuleDot;
 }
 /** Why a rule text was refused. Codes are stable so an import report can group by them. */
-export type RuleRejectCode = "invalid.grammar" | "invalid.empty_command" | "invalid.not_simple_command" | "invalid.bare_interpreter_prefix" | "invalid.unbalanced_quotes" | "invalid.too_long" | "unsupported.tool" | "unsupported.wildcard";
+export type RuleRejectCode = "invalid.grammar" | "invalid.empty_command" | "invalid.not_simple_command" | "invalid.bare_interpreter_prefix" | "invalid.unbalanced_quotes" | "invalid.control_chars" | "invalid.too_long" | "unsupported.tool" | "unsupported.wildcard";
 export interface RuleReject {
     code: RuleRejectCode;
     message: string;
@@ -167,6 +167,22 @@ export declare const BARE_INTERPRETER_NAMES: ReadonlySet<string>;
  * loosening; the other against a person being misled.
  */
 export declare const SUGGESTION_LEXICON: readonly string[];
+/**
+ * Render a peer- or file-controlled value for a DISCLOSURE line (a warning, a refusal message, an
+ * operator log). Takes `unknown` on purpose: most of these values are typed but arrive off a wire or a
+ * file, so the runtime value can be anything, and a signature that demanded a string would push a bare
+ * `String(x)` to every call site — the exact step that gets forgotten. Rule texts are the motivating case; the same treatment is owed to every untrusted
+ * field a line interpolates (a wire `reason`, an actor id), since the hazard is the character class,
+ * not which field carries it.
+ *
+ * Quoting a refused text verbatim would carry the exact sequence the refusal exists to keep off a
+ * display surface, and would print the two texts a reader has to tell apart — `Bash(echo hi)` and
+ * `Bash(echo<ZWSP>hi)` — identically, so the report could not name WHICH rule it means. Every character
+ * {@link CONTROL_CHARS_RE} covers is therefore printed as its `\uXXXX` escape (`\u{XXXXX}` above the
+ * BMP — the TAG block U+E0020–U+E007F is a `\p{Cf}` family that lives there); everything else passes
+ * through, so an ordinary rule text reads normally. The result is length-bounded.
+ */
+export declare function escapeForDisclosure(value: unknown): string;
 /**
  * Parse one rule text into its canonical shape, or refuse it with a reason.
  *

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

@@ -91,10 +91,31 @@ function foldSpacing(s) {
 function reject(code, message) {
     return { reject: { code, message } };
 }
+const CONTROL_CHARS_RE = /[\u0000-\u0008\u000A-\u001F\u007F-\u009F\p{Cf}\u2028\u2029]/u;
+const CONTROL_CHARS_GLOBAL_RE = new RegExp(CONTROL_CHARS_RE.source, "gu");
+const DISCLOSED_RULE_TEXT_MAX_CHARS = 120;
+export function escapeForDisclosure(value) {
+    let text;
+    try {
+        text = typeof value === "string" ? value : String(value);
+    }
+    catch {
+        return "<unprintable>";
+    }
+    const escaped = text.replace(CONTROL_CHARS_GLOBAL_RE, (ch) => {
+        const cp = ch.codePointAt(0) ?? 0;
+        const hex = cp.toString(16).toUpperCase();
+        return cp > 0xffff ? `\\u{${hex}}` : `\\u${hex.padStart(4, "0")}`;
+    });
+    return escaped.length <= DISCLOSED_RULE_TEXT_MAX_CHARS ? escaped : `${escaped.slice(0, DISCLOSED_RULE_TEXT_MAX_CHARS)}…`;
+}
 export function parseAllowRuleText(text, opts) {
     if (text.length > MAX_RULE_TEXT_CHARS) {
         return reject("invalid.too_long", `rule text exceeds ${MAX_RULE_TEXT_CHARS} characters`);
     }
+    if (CONTROL_CHARS_RE.test(text)) {
+        return reject("invalid.control_chars", "rule text contains control characters (C0/C1, tab excepted), which cannot be part of a readable command");
+    }
     const parsed = parsePermissionRule(text);
     if (parsed.ruleContent === undefined) {
         return reject("invalid.grammar", `"${text}" is not a Tool(content) rule — a bare tool name claims the whole tool and is not a command rule`);

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

@@ -34,7 +34,7 @@
  * accept revision N−1 after a restart. Signature / predecessor chaining belongs to the privilege-
  * separation ticket; the high-water mark is the floor that needs no key distribution.
  */
-import { type RuleScope } from "./permission-rule-model.js";
+import { type RuleRejectCode, type RuleScope } from "./permission-rule-model.js";
 import { type PermissionRuleStore, type PermissionRuleStoreProvider, type RuleOwner } from "./permission-rule-store.js";
 /** One org rule. There is structurally no allow bucket (design/179 §9: the org layer only tightens). */
 export interface OrgPermissionRule {
@@ -160,13 +160,32 @@ export declare function createOrgRuleOverlay(cfg: {
     stalenessBoundMs: number;
     now?: () => number;
 }): OrgRuleOverlay;
+/**
+ * Which entries of an org snapshot the CURRENT rule validator refuses — the published deny/ask rules
+ * that can match nothing on this build. Empty ⟺ every rule is enforceable.
+ *
+ * Separate from {@link validateOrgSnapshot} because BOTH gates need it: the install gate (a fetched
+ * snapshot) and the serving gate (backlog #177 — a snapshot persisted by an earlier build is read back
+ * and served without ever having met this validator). It reports every offender rather than the first,
+ * since a refusal an administrator cannot act on names no line to fix.
+ */
+export declare function unenforceableOrgRules(rules: readonly OrgPermissionRule[]): Array<{
+    rule: string;
+    code: RuleRejectCode;
+}>;
 /**
  * design/182 §7.2 — which org rule speaks for this command, if any. Deny outranks ask; within a
  * behavior the first textual match wins (reporting order only — all denies are the same one answer).
  * Matching uses the SAME parser and matcher the personal lane uses (tighten direction: an
  * interpreter-headed prefix deny like `Bash(node:*)` is a legitimately wide tightening and matches).
- * A rule text the validator refuses never gets here — snapshot validation refuses the whole snapshot,
- * so an unenforceable deny cannot install as policy; the skip below is a defensive floor only.
+ *
+ * The skip below is a defensive floor, and what stands behind it is worth stating precisely: rules that
+ * arrive from {@link OrgRuleOverlay.resolve} have passed {@link validateOrgSnapshot} on BOTH the install
+ * and the serving path (backlog #177), so an unenforceable entry cannot reach here through the overlay
+ * — the whole snapshot is refused, or the resolution reports `unavailable`, and either way it is
+ * disclosed. A caller that hands this function a snapshot it obtained ELSEWHERE gets no such guarantee:
+ * the skip is silent, and naming the dead entries is that caller's job — {@link unenforceableOrgRules}
+ * is the shared way to do it.
  */
 export declare function orgRuleVerdictFor(rules: readonly OrgPermissionRule[], call: {
     tool: string;