@sema-agent/core 5.26.0 → 5.28.0

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

@@ -6,6 +6,54 @@ export const BARE_INTERPRETER_NAMES = new Set([
     "node", "deno", "bun", "python", "python2", "python3", "perl", "ruby", "php",
     "osascript", "env", "eval", "exec", "xargs", "nohup", "sudo", "doas", "su", "ssh",
 ]);
+export const SUGGESTION_LEXICON = [
+    "git status", "git log", "git diff", "git show", "git branch", "git checkout", "git switch",
+    "git add", "git commit", "git push", "git pull", "git fetch", "git merge", "git rebase",
+    "git tag", "git blame", "git describe", "git cherry-pick", "git restore", "git reset",
+    "git rev-parse", "git ls-files", "git grep",
+    "git stash list", "git stash show", "git stash push", "git stash pop", "git stash drop",
+    "git remote show", "git worktree list", "git submodule update", "git submodule status",
+    "npm run", "npm test", "npm ci", "npm ls", "npm view", "npm outdated", "npm audit",
+    "npm pack", "npm publish", "npm version", "npm why",
+    "pnpm run", "pnpm test", "pnpm ls", "pnpm outdated", "pnpm audit", "pnpm why",
+    "yarn run", "yarn test", "yarn workspaces list",
+    "cargo build", "cargo test", "cargo run", "cargo check", "cargo clippy", "cargo fmt",
+    "cargo doc", "cargo tree", "cargo bench", "cargo update", "cargo metadata",
+    "go build", "go test", "go vet", "go fmt", "go doc",
+    "go mod tidy", "go mod download", "go mod verify", "go mod graph",
+    "docker ps", "docker images", "docker logs", "docker inspect", "docker build", "docker pull",
+    "docker push", "docker stop", "docker start", "docker restart", "docker rm", "docker rmi",
+    "docker compose up", "docker compose down", "docker compose ps", "docker compose logs",
+    "docker compose build", "docker compose pull",
+    "kubectl get", "kubectl describe", "kubectl logs", "kubectl apply", "kubectl delete",
+    "kubectl diff", "kubectl explain", "kubectl top",
+    "kubectl rollout status", "kubectl rollout restart", "kubectl rollout history",
+    "gh pr view", "gh pr list", "gh pr diff", "gh pr checks", "gh pr status", "gh pr create",
+    "gh pr merge", "gh issue view", "gh issue list", "gh issue create", "gh repo view",
+    "gh repo clone", "gh release list", "gh release view", "gh run list", "gh run view",
+    "gh run watch", "gh workflow list", "gh workflow view", "gh auth status",
+    "gh search repos", "gh search issues", "gh search prs", "gh search code",
+];
+const LEXICON_BODIES = SUGGESTION_LEXICON.map((b) => b.split(" "));
+function longestReviewedBody(tokens) {
+    let best;
+    for (const words of LEXICON_BODIES) {
+        if (words.length > tokens.length)
+            continue;
+        if (best !== undefined && words.length <= best.length)
+            continue;
+        let hit = true;
+        for (let i = 0; i < words.length; i++) {
+            if (words[i] !== tokens[i]) {
+                hit = false;
+                break;
+            }
+        }
+        if (hit)
+            best = words;
+    }
+    return best?.join(" ");
+}
 function foldSpacing(s) {
     let out = "";
     let quote;
@@ -43,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`);
@@ -131,5 +200,15 @@ export function suggestRulesForCommand(command) {
     const exact = parseAllowRuleText(formatAllowRuleText(folded, "exact"));
     if ("rule" in exact)
         out.push({ rule: exact.rule.rule, match: "exact", command: exact.rule.command });
+    if (out.length === 1) {
+        const body = longestReviewedBody(folded.split(" "));
+        if (body !== undefined) {
+            const text = formatAllowRuleText(body, "prefix");
+            const parsed = parseAllowRuleText(text);
+            if ("rule" in parsed && parsed.rule.match === "prefix" && ruleAdmitsCommand(parsed.rule, command)) {
+                out.push({ rule: parsed.rule.rule, match: "prefix", command: parsed.rule.command });
+            }
+        }
+    }
     return out;
 }

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;

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

@@ -1,4 +1,4 @@
-import { parseAllowRuleText, ruleAdmitsCommand } from "./permission-rule-model.js";
+import { escapeForDisclosure, parseAllowRuleText, ruleAdmitsCommand } from "./permission-rule-model.js";
 import { sameScope, writerOf } from "./permission-rule-store.js";
 export function orgRuleStatePersistenceOf(store) {
     const s = store;
@@ -46,7 +46,7 @@ export function createOrgRuleOverlay(cfg) {
         throw new Error("org-governed is declared but no OrgRuleSnapshotProvider is wired — a governed deployment without an org source is a configuration contradiction; refusing to boot rather than running silently ungoverned");
     }
     if (typeof cfg.stalenessBoundMs !== "number" || !Number.isFinite(cfg.stalenessBoundMs) || cfg.stalenessBoundMs <= 0) {
-        throw new Error(`org stalenessBoundMs must be a finite positive number of milliseconds (got ${String(cfg.stalenessBoundMs)})`);
+        throw new Error(`org stalenessBoundMs must be a finite positive number of milliseconds (got ${escapeForDisclosure(cfg.stalenessBoundMs)})`);
     }
     const provider = cfg.provider;
     const now = cfg.now ?? Date.now;
@@ -75,11 +75,11 @@ export function createOrgRuleOverlay(cfg) {
         let fetched;
         let fetchFailed = false;
         try {
-            fetched = await provider.current();
+            fetched = structuredClone(await provider.current());
         }
         catch (err) {
             fetchFailed = true;
-            disclosures.push(`org snapshot provider failed: ${err instanceof Error ? err.message : String(err)}`);
+            disclosures.push(`org snapshot provider failed: ${escapeForDisclosure(err instanceof Error ? err.message : err)}`);
         }
         return await serialize(async () => {
             const nowMs = now();
@@ -88,7 +88,7 @@ export function createOrgRuleOverlay(cfg) {
                     return await readState();
                 }
                 catch (err) {
-                    disclosures.push(`org state ${context} read failed: ${err instanceof Error ? err.message : String(err)}`);
+                    disclosures.push(`org state ${context} read failed: ${escapeForDisclosure(err instanceof Error ? err.message : err)}`);
                     return undefined;
                 }
             };
@@ -101,8 +101,12 @@ export function createOrgRuleOverlay(cfg) {
                     disclosures.push(`org snapshot refused: ${invalid}; the previously installed snapshot (if any) remains in force`);
                     return persisted;
                 }
-                if (persisted !== undefined && fetched.revision < persisted.revisionHighWater) {
-                    disclosures.push(`org snapshot revision ${fetched.revision} is below the installed high-water mark ${persisted.revisionHighWater} — refusing the rollback; the current deny set is unchanged`);
+                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`);
                     return persisted;
                 }
                 if (persisted !== undefined && fetched.revision === persisted.snapshot.revision && !sameOrgPolicyContent(fetched, persisted.snapshot)) {
@@ -110,7 +114,7 @@ export function createOrgRuleOverlay(cfg) {
                     return persisted;
                 }
                 const state = {
-                    revisionHighWater: Math.max(persisted?.revisionHighWater ?? 0, fetched.revision),
+                    revisionHighWater: Math.max(persistedFloor !== undefined && Number.isFinite(persistedFloor) ? persistedFloor : 0, fetched.revision),
                     snapshot: fetched,
                     installedAtMs: nowMs,
                 };
@@ -119,11 +123,11 @@ export function createOrgRuleOverlay(cfg) {
                 }
                 catch (err) {
                     const reread = await guardedRead("reconciliation");
-                    if (reread !== undefined && reread.revisionHighWater >= state.revisionHighWater) {
-                        disclosures.push(`org snapshot install was superseded by a concurrent install at revision ${reread.snapshot.revision} — continuing on the newer installed state`);
+                    if (reread !== undefined && antiRollbackFloor(reread) >= state.revisionHighWater) {
+                        disclosures.push(`org snapshot install was superseded by a concurrent install at revision ${escapeForDisclosure(reread.snapshot.revision)} — continuing on the newer installed state`);
                         return reread;
                     }
-                    disclosures.push(`org snapshot install failed (${err instanceof Error ? err.message : String(err)}) and no superseding installed state exists — org adjudication is UNAVAILABLE`);
+                    disclosures.push(`org snapshot install failed (${escapeForDisclosure(err instanceof Error ? err.message : err)}) and no superseding installed state exists — org adjudication is UNAVAILABLE`);
                     return undefined;
                 }
                 return state;
@@ -132,7 +136,12 @@ export function createOrgRuleOverlay(cfg) {
             const withinBound = (snap) => decisionMs - snap.fetchedAtMs <= cfg.stalenessBoundMs && snap.fetchedAtMs <= decisionMs + ORG_FETCHED_AT_SKEW_ALLOWANCE_MS;
             if (installed !== undefined) {
                 if (installed.snapshot.fetchedAtMs > decisionMs + ORG_FETCHED_AT_SKEW_ALLOWANCE_MS) {
-                    disclosures.push(`the installed org snapshot claims a FUTURE observation time (${installed.snapshot.fetchedAtMs} vs now ${decisionMs}) — org adjudication is UNAVAILABLE; the consuming gate must tighten every terminal allow to a real-approval ask`);
+                    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 { 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`);
                     return { status: "unavailable", rules: [], disclosures };
                 }
                 if (withinBound(installed.snapshot)) {
@@ -156,16 +165,50 @@ export function createOrgRuleOverlay(cfg) {
     };
     return { resolve };
 }
+function antiRollbackFloor(state) {
+    const mark = typeof state.revisionHighWater === "number" && Number.isFinite(state.revisionHighWater) ? state.revisionHighWater : undefined;
+    const own = typeof state.snapshot?.revision === "number" && Number.isFinite(state.snapshot.revision) ? state.snapshot.revision : undefined;
+    if (mark === undefined)
+        return own ?? Number.NEGATIVE_INFINITY;
+    return own === undefined ? mark : Math.max(mark, own);
+}
+function persistedMarkIsCoherent(state) {
+    return (typeof state.revisionHighWater === "number" &&
+        Number.isFinite(state.revisionHighWater) &&
+        typeof state.snapshot?.revision === "number" &&
+        Number.isFinite(state.snapshot.revision) &&
+        state.revisionHighWater >= state.snapshot.revision);
+}
 function sameOrgPolicyContent(a, b) {
     if (a.rules.length !== b.rules.length)
         return false;
     return a.rules.every((r, i) => b.rules[i]?.rule === r.rule && b.rules[i]?.behavior === r.behavior);
 }
+const DISCLOSED_UNENFORCEABLE_RULES = 20;
+export function unenforceableOrgRules(rules) {
+    const out = [];
+    for (const r of rules) {
+        if (typeof r?.rule !== "string" || r.rule === "")
+            continue;
+        const parsed = parseAllowRuleText(r.rule, { direction: "tighten" });
+        if ("reject" in parsed)
+            out.push({ rule: r.rule, code: parsed.reject.code });
+    }
+    return out;
+}
+function describeUnenforceable(unenforceable) {
+    const named = unenforceable
+        .slice(0, DISCLOSED_UNENFORCEABLE_RULES)
+        .map((u) => `"${escapeForDisclosure(u.rule)}" (${u.code})`)
+        .join(", ");
+    const more = unenforceable.length - DISCLOSED_UNENFORCEABLE_RULES;
+    return more > 0 ? `${named} and ${more} more` : named;
+}
 function validateOrgSnapshot(s, nowMs) {
     if (typeof s.revision !== "number" || !Number.isFinite(s.revision))
-        return `revision is not a finite number (${String(s.revision)})`;
+        return `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 (${String(s.fetchedAtMs)})`;
+        return `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`;
     }
@@ -174,11 +217,15 @@ function validateOrgSnapshot(s, nowMs) {
     for (const r of s.rules) {
         if (typeof r?.rule !== "string" || r.rule === "")
             return "a rule entry carries no rule text";
-        if (r.behavior !== "deny" && r.behavior !== "ask")
-            return `rule "${r.rule}" carries behavior "${String(r.behavior)}" — the org layer has no allow bucket`;
-        const parsed = parseAllowRuleText(r.rule, { direction: "tighten" });
-        if ("reject" in parsed)
-            return `rule "${r.rule}" does not parse (${parsed.reject.code}) — an unenforceable ${r.behavior} must not install as policy`;
+        if (r.behavior !== "deny" && r.behavior !== "ask") {
+            return `rule "${escapeForDisclosure(r.rule)}" carries behavior "${escapeForDisclosure(r.behavior)}" — the org layer has no allow bucket`;
+        }
+    }
+    const unenforceable = unenforceableOrgRules(s.rules);
+    const first = unenforceable[0];
+    if (first !== undefined) {
+        const rest = unenforceable.length > 1 ? ` (${unenforceable.length} in all — ${describeUnenforceable(unenforceable)})` : "";
+        return `rule "${escapeForDisclosure(first.rule)}" does not parse (${first.code}) — an unenforceable deny/ask must not stand as policy${rest}`;
     }
     return undefined;
 }
@@ -231,7 +278,7 @@ function resolveIntrospectionStore(opts) {
         return store;
     }
     if (opts.owner !== undefined && opts.owner.kind === "principal" && opts.principal !== undefined && opts.owner.principal !== opts.principal) {
-        throw new Error(`contradictory identity: principal "${opts.principal}" and owner principal "${opts.owner.principal}" disagree`);
+        throw new Error(`contradictory identity: principal "${escapeForDisclosure(opts.principal)}" and owner principal "${escapeForDisclosure(opts.owner.principal)}" disagree`);
     }
     const principal = opts.owner?.kind === "principal" ? opts.owner.principal : opts.principal;
     return opts.provider.forPrincipal(principal);

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

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { canonicalize } from "./canonical-json.js";
-import { isRuleLive, parseAllowRuleText } from "./permission-rule-model.js";
+import { escapeForDisclosure, isRuleLive, parseAllowRuleText } from "./permission-rule-model.js";
 export function sameRuleOwner(a, b) {
     return a.kind === "principal" ? b.kind === "principal" && a.principal === b.principal : b.kind === "local-owner";
 }
@@ -191,7 +191,7 @@ export function applySyncJoin(cur, delta, nowMs) {
         }
         const canonicalTomb = parseAllowRuleText(t.rule);
         if ("reject" in canonicalTomb || canonicalTomb.rule.rule !== t.rule) {
-            throw new Error(`an inbound tombstone names a non-canonical or invalid rule text ("${t.rule}") — refusing the whole sync-join (the client's partitioning must withhold the round's adds alongside a malformed tombstone)`);
+            throw new Error(`an inbound tombstone names a non-canonical or invalid rule text ("${escapeForDisclosure(t.rule)}") — refusing the whole sync-join (the client's partitioning must withhold the round's adds alongside a malformed tombstone)`);
         }
     }
     const droppedInbound = [];

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

@@ -25,7 +25,7 @@
  * privilege-separation ticket adds device-bound signatures. Deployments should connect knowing which
  * level they are buying.
  */
-import type { PersistedAllowRule, RuleDot, RuleScope, RuleTombstone } from "./permission-rule-model.js";
+import type { PersistedAllowRule, RuleDot, RuleRejectCode, RuleScope, RuleTombstone } from "./permission-rule-model.js";
 import type { PermissionRuleStoreProvider, RuleOwner, RuleSyncDrop, RuleSyncFrontier, RuleSyncState } from "./permission-rule-store.js";
 import { type TracerHook } from "./trace.js";
 /** The injected HTTP seam — core never bundles a fetch. The deployment owns base URL, auth, TLS and
@@ -125,6 +125,15 @@ interface ParsedRuleSyncResponse {
         dot: RuleDot;
         reason: string;
     }>;
+    /** Tombstones whose SHAPE is whole but whose rule TEXT the current validator refuses — the third
+     *  outcome, kept OUT of `merged.tombstones` so it does not read as malformed. See {@link
+     *  parseRuleSyncResponse} for why this one does not withhold the round's adds (backlog #176). */
+    textRefusedTombstones: Array<{
+        rule: string;
+        scope: RuleScope;
+        dot: RuleDot;
+        code: RuleRejectCode;
+    }>;
     warnings: string[];
 }
 /**
@@ -134,6 +143,11 @@ interface ParsedRuleSyncResponse {
  * reaches the local disk); an unshapeable tombstone is surfaced as `undefined` so the caller's
  * tighten-only partitioning withholds the round's adds. Unknown keys never flow anywhere — every field
  * below is PICKED off the response, the object itself is discarded.
+ *
+ * A tombstone has THREE outcomes, not two (backlog #176): sound; malformed (bad shape, or a spelling
+ * that parses but is not canonical — the withholding arm); and shape-whole-but-TEXT-refused, reported
+ * on {@link ParsedRuleSyncResponse.textRefusedTombstones}. The third is a legacy row a tightened
+ * validator no longer admits — permanent, so treating it as the second would stall inbound adds forever.
  */
 export declare function parseRuleSyncResponse(raw: unknown, expectedPrincipal: string): ParsedRuleSyncResponse;
 export {};

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

@@ -1,4 +1,4 @@
-import { parseAllowRuleText } from "./permission-rule-model.js";
+import { escapeForDisclosure, parseAllowRuleText } from "./permission-rule-model.js";
 import { applyTombstones, errText, joinFrontiers, joinRuleStates, normalizePersistedRule, ruleSyncVector, sameScope, screenRuleSyncState, writerOf, } from "./permission-rule-store.js";
 import { emitTrace } from "./trace.js";
 export const PERMISSION_RULE_SYNC_PATH = "/v1/permission-rules/sync";
@@ -9,12 +9,13 @@ function refuseLocalOwnerSync() {
     throw e;
 }
 const SYNC_MAX_ATTEMPTS = 8;
+const DISCLOSED_REFUSED_TOMBSTONES = 5;
 export async function syncPermissionRules(opts) {
     if (opts.owner !== undefined) {
         if (opts.owner.kind === "local-owner")
             refuseLocalOwnerSync();
         if (opts.owner.principal !== opts.principal) {
-            throw new Error(`contradictory identity: principal "${opts.principal}" and owner principal "${opts.owner.principal}" disagree`);
+            throw new Error(`contradictory identity: principal "${escapeForDisclosure(opts.principal)}" and owner principal "${escapeForDisclosure(opts.owner.principal)}" disagree`);
         }
     }
     if (typeof opts.principal !== "string" || opts.principal === "") {
@@ -83,6 +84,18 @@ export async function syncPermissionRules(opts) {
     if (tombstoneWithholding) {
         warnings.push("the response carried at least one malformed tombstone — every inbound add is withheld this round (legal tombstones land; the adds re-arrive once the peer repairs the tombstone: full-state exchange has no missed-forever window)");
     }
+    for (const t of response.textRefusedTombstones) {
+        dropped.push({ rule: t.rule, scope: t.scope, dot: t.dot, reason: "invalid_rule_text" });
+    }
+    if (response.textRefusedTombstones.length > 0) {
+        const named = response.textRefusedTombstones
+            .slice(0, DISCLOSED_REFUSED_TOMBSTONES)
+            .map((t) => `"${escapeForDisclosure(t.rule)}" (${t.code})`)
+            .join(", ");
+        const more = response.textRefusedTombstones.length - DISCLOSED_REFUSED_TOMBSTONES;
+        warnings.push(`the response carried ${response.textRefusedTombstones.length} tombstone(s) whose rule text this version's validator refuses — ${named}${more > 0 ? ` and ${more} more` : ""}. ` +
+            "They are refused here and never land; this round's inbound adds are NOT withheld for them (an add under the same text is refused by the same validator, so such a tombstone covers nothing that could go live). The peer still holds them — removing them there is what ends this notice");
+    }
     const inboundRules = [];
     if (!tombstoneWithholding) {
         for (const r of response.merged.rules) {
@@ -120,7 +133,7 @@ export async function syncPermissionRules(opts) {
             dropped.push({ rule: d.rule, scope: d.scope, dot: d.dot, reason });
         }
         else {
-            warnings.push(`the server dropped an inbound-side record (${d.rule}, dot ${d.dot.actor}#${d.dot.counter}): ${d.reason}`);
+            warnings.push(`the server dropped an inbound-side record (${escapeForDisclosure(d.rule)}, dot ${escapeForDisclosure(d.dot.actor)}#${d.dot.counter}): ${escapeForDisclosure(d.reason)}`);
         }
     }
     const clean = !tombstoneWithholding;
@@ -147,7 +160,7 @@ export async function syncPermissionRules(opts) {
                 resurrected: [],
                 dropped,
                 rev: current.rev,
-                warnings: [...warnings, `the store refused the sync landing: ${errText(err)} — nothing landed, the local state is unchanged`],
+                warnings: [...warnings, `the store refused the sync landing: ${escapeForDisclosure(errText(err))} — nothing landed, the local state is unchanged`],
             });
         }
         if ("conflict" in res) {
@@ -205,9 +218,11 @@ export async function syncPermissionRules(opts) {
         warnings: [...warnings, `optimistic-concurrency retries exhausted after ${SYNC_MAX_ATTEMPTS} attempts — nothing landed, the local state is unchanged`],
     });
 }
-function isDot(v) {
+function pickDot(v) {
     const d = v;
-    return typeof d?.actor === "string" && d.actor !== "" && typeof d.counter === "number" && Number.isFinite(d.counter);
+    const actor = d?.actor;
+    const counter = d?.counter;
+    return typeof actor === "string" && actor !== "" && typeof counter === "number" && Number.isFinite(counter) ? { actor, counter } : undefined;
 }
 function pickScope(v) {
     const s = v;
@@ -219,13 +234,16 @@ function pickScope(v) {
 }
 function pickAdd(v) {
     const a = v;
-    if (!isDot(a?.dot))
+    const dot = pickDot(a?.dot);
+    const origin = a?.origin;
+    const createdAt = a?.createdAt;
+    if (dot === undefined)
         return undefined;
-    if (a.origin !== "user" && a.origin !== "imported-cc" && a.origin !== "starter")
+    if (origin !== "user" && origin !== "imported-cc" && origin !== "starter")
         return undefined;
-    if (typeof a.createdAt !== "string")
+    if (typeof createdAt !== "string")
         return undefined;
-    return { dot: { actor: a.dot.actor, counter: a.dot.counter }, origin: a.origin, createdAt: a.createdAt };
+    return { dot, origin, createdAt };
 }
 function pickFrontier(v) {
     if (v === null || typeof v !== "object" || Array.isArray(v))
@@ -243,35 +261,44 @@ export function parseRuleSyncResponse(raw, expectedPrincipal) {
         throw new Error("the sync response is not an object — protocol error, nothing landed");
     }
     const r = raw;
-    if (typeof r.principal !== "string") {
+    const echoedPrincipal = r.principal;
+    if (typeof echoedPrincipal !== "string") {
         throw new Error("the sync response carries no principal echo — protocol error, nothing landed");
     }
-    if (r.principal !== expectedPrincipal) {
-        throw new Error(`the sync response echoes principal "${r.principal}" but this round synced "${expectedPrincipal}" — the transport is wired to the wrong bucket; refusing the whole round`);
+    if (echoedPrincipal !== expectedPrincipal) {
+        throw new Error(`the sync response echoes principal "${escapeForDisclosure(echoedPrincipal)}" but this round synced "${escapeForDisclosure(expectedPrincipal)}" — the transport is wired to the wrong bucket; refusing the whole round`);
     }
     const merged = r.merged;
-    if (merged === null || typeof merged !== "object" || !Array.isArray(merged.rules) || !Array.isArray(merged.tombstones)) {
+    const mergedRules = merged?.rules;
+    const mergedTombstones = merged?.tombstones;
+    if (merged === null || typeof merged !== "object" || !Array.isArray(mergedRules) || !Array.isArray(mergedTombstones)) {
         throw new Error("the sync response carries no merged state — protocol error, nothing landed");
     }
+    const rawGcFrontier = r.gcFrontier;
     let gcFrontier;
-    if (r.gcFrontier !== undefined) {
-        gcFrontier = pickFrontier(r.gcFrontier);
+    if (rawGcFrontier !== undefined) {
+        gcFrontier = pickFrontier(rawGcFrontier);
         if (gcFrontier === undefined) {
             throw new Error("the sync response carries an unparseable gcFrontier — refusing the whole round (a garbled frontier must not drive the fence arm)");
         }
     }
     const warnings = [];
     const rules = [];
-    for (const entry of merged.rules) {
+    for (const entry of mergedRules) {
         const e = entry;
         const scope = pickScope(e?.scope);
-        if (typeof e?.rule !== "string" || scope === undefined || !Array.isArray(e.adds) || typeof e.command !== "string" || typeof e.tool !== "string" || typeof e.match !== "string") {
+        const eRule = e?.rule;
+        const eCommand = e?.command;
+        const eTool = e?.tool;
+        const eMatch = e?.match;
+        const eAdds = e?.adds;
+        if (typeof eRule !== "string" || scope === undefined || !Array.isArray(eAdds) || typeof eCommand !== "string" || typeof eTool !== "string" || typeof eMatch !== "string") {
             warnings.push("the response carried an unshapeable rule entry — skipped (it never reaches the local store)");
             continue;
         }
         const adds = [];
         let addDamaged = false;
-        for (const a of e.adds) {
+        for (const a of eAdds) {
             const picked = pickAdd(a);
             if (picked === undefined) {
                 addDamaged = true;
@@ -280,64 +307,79 @@ export function parseRuleSyncResponse(raw, expectedPrincipal) {
             adds.push(picked);
         }
         if (addDamaged)
-            warnings.push(`rule "${e.rule}" carried at least one unshapeable add — skipped those adds`);
+            warnings.push(`rule "${escapeForDisclosure(eRule)}" carried at least one unshapeable add — skipped those adds`);
         if (adds.length === 0)
             continue;
         rules.push({
-            rule: e.rule,
-            tool: e.tool,
-            match: e.match,
-            command: e.command,
+            rule: eRule,
+            tool: eTool,
+            match: eMatch,
+            command: eCommand,
             scope,
             adds,
         });
     }
     const tombstones = [];
-    for (const entry of merged.tombstones) {
+    const textRefusedTombstones = [];
+    for (const entry of mergedTombstones) {
         const t = entry;
         const scope = pickScope(t?.scope);
-        const canonicalTomb = typeof t?.rule === "string" ? parseAllowRuleText(t.rule) : undefined;
-        if (typeof t?.rule !== "string" ||
-            canonicalTomb === undefined ||
-            "reject" in canonicalTomb ||
-            canonicalTomb.rule.rule !== t.rule ||
-            scope === undefined ||
-            !isDot(t.deletedBy) ||
-            !Array.isArray(t.removedDots) ||
-            t.removedDots.length === 0 ||
-            !t.removedDots.every(isDot)) {
+        const ruleText = t?.rule;
+        const deletedBy = pickDot(t?.deletedBy);
+        const removedRaw = t?.removedDots;
+        const removedDots = [];
+        if (Array.isArray(removedRaw)) {
+            for (const d of removedRaw) {
+                const dot = pickDot(d);
+                if (dot === undefined) {
+                    removedDots.length = 0;
+                    break;
+                }
+                removedDots.push(dot);
+            }
+        }
+        if (typeof ruleText !== "string" || scope === undefined || deletedBy === undefined || removedDots.length === 0) {
             tombstones.push(undefined);
             continue;
         }
-        tombstones.push({
-            rule: t.rule,
-            scope,
-            removedDots: t.removedDots.map((d) => ({ actor: d.actor, counter: d.counter })),
-            deletedBy: { actor: t.deletedBy.actor, counter: t.deletedBy.counter },
-        });
+        const canonicalTomb = parseAllowRuleText(ruleText);
+        if ("reject" in canonicalTomb) {
+            textRefusedTombstones.push({ rule: ruleText, scope, dot: deletedBy, code: canonicalTomb.reject.code });
+            continue;
+        }
+        if (canonicalTomb.rule.rule !== ruleText) {
+            tombstones.push(undefined);
+            continue;
+        }
+        tombstones.push({ rule: ruleText, scope, removedDots, deletedBy });
     }
     const dropped = [];
-    if (r.dropped !== undefined) {
-        if (!Array.isArray(r.dropped)) {
+    const rawDropped = r.dropped;
+    if (rawDropped !== undefined) {
+        if (!Array.isArray(rawDropped)) {
             warnings.push("the response carried a non-array dropped field — ignored");
         }
         else {
-            for (const entry of r.dropped) {
+            for (const entry of rawDropped) {
                 const d = entry;
                 const scope = pickScope(d?.scope);
-                if (typeof d?.rule !== "string" || scope === undefined || !isDot(d.dot) || typeof d.reason !== "string") {
+                const dRule = d?.rule;
+                const dDot = pickDot(d?.dot);
+                const dReason = d?.reason;
+                if (typeof dRule !== "string" || scope === undefined || dDot === undefined || typeof dReason !== "string") {
                     warnings.push("the response carried an unshapeable dropped entry — ignored (the server's own drop discipline is its contract obligation)");
                     continue;
                 }
-                dropped.push({ rule: d.rule, scope, dot: { actor: d.dot.actor, counter: d.dot.counter }, reason: d.reason });
+                dropped.push({ rule: dRule, scope, dot: dDot, reason: dReason });
             }
         }
     }
     return {
-        principal: r.principal,
+        principal: echoedPrincipal,
         merged: { rules, tombstones },
         ...(gcFrontier !== undefined ? { gcFrontier } : {}),
         dropped,
+        textRefusedTombstones,
         warnings,
     };
 }