@sema-agent/core 5.27.0 → 5.28.0

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,
     };
 }

package/dist/core/runner/prepare-task.js

@@ -89,10 +89,14 @@ import { BINDING_CHECKPOINT_VERSION, mintCheckpointToken, ORG_ADMISSION_CHECKPOI
 import { boundInputHashOf } from "../canonical-json.js";
 import { countElicitOptIns, deriveAskEffective, deriveWiringManifest, resolveAskSeamForm, resolveDeclaredDurability, resolveElicitSeam, resolveQuestionSeam } from "../wiring-manifest.js";
 import { GLOBAL_USAGE_KEY, resolveUsageWindows, usageRetryAfterMs } from "../usage-window-store.js";
+import { deliverEngineNotice } from "../types.js";
 const announcedMaterializeEnv = new Set();
 export function __resetMaterializeEnvAnnouncements() {
     announcedMaterializeEnv.clear();
 }
+function emitMaterializeEnvNotice(onNotice, message, detail) {
+    deliverEngineNotice(onNotice, { code: "config.materialize_env_discarded", message, detail });
+}
 const RECONCILE_MAX_RETRIES = 3;
 const DEFAULT_MAX_SUSPENDS = 5;
 const TASK_LIMIT_KEY_DICT = {
@@ -1659,6 +1663,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 ...(sessionId !== undefined ? { sessionId } : {}),
                 ...(internals?.onTaskNotification !== undefined ? { taskNotification: internals.onTaskNotification } : {}),
                 ...(internals?.detachHub !== undefined ? { detachHub: internals.detachHub } : {}),
+                ...(deps.onNotice !== undefined ? { onNotice: deps.onNotice } : {}),
                 pdfModelCapabilities: pdfModelCapabilitiesOf(model),
                 ...(deps.hands?.bashReadonlyAllow !== undefined ? { bashReadonlyAllow: deps.hands.bashReadonlyAllow } : {}),
                 ...(deps.hands?.commitCoAuthor !== undefined ? { commitCoAuthor: deps.hands.commitCoAuthor } : {}),
@@ -2606,7 +2611,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 const line = `SEMA_TOOL_MATERIALIZE_STRATEGY=${JSON.stringify(raw)} is not "swap" or "static" — inert on this task (no deferred tools), but a deferring task WITHOUT an explicit spec strategy will refuse to prepare under it (an explicit legal spec outranks and discards it, loudly). Fix or unset the flag.`;
                 if (!announcedMaterializeEnv.has(line)) {
                     announcedMaterializeEnv.add(line);
-                    console.warn(line);
+                    emitMaterializeEnvNotice(deps.onNotice, line, { raw });
                 }
             }
         }
@@ -2628,7 +2633,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 const line = `SEMA_TOOL_MATERIALIZE_STRATEGY=${JSON.stringify(rawEnvStrategy)} was ignored — not "swap" or "static", and the task spec pins toolMaterializeStrategy=${JSON.stringify(spec.toolMaterializeStrategy)} which outranks it. Fix or unset the env flag.`;
                 if (!announcedMaterializeEnv.has(line)) {
                     announcedMaterializeEnv.add(line);
-                    console.warn(line);
+                    emitMaterializeEnvNotice(deps.onNotice, line, { raw: rawEnvStrategy, specStrategy: spec.toolMaterializeStrategy });
                 }
             }
             const envStrategy = envStrategyInvalid ? undefined : rawEnvStrategy;
@@ -4731,7 +4736,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 ...(offloadStore
                     ? {
                         offload: {
-                            persist: createOffloadPersist(offloadStore, sessionId),
+                            persist: createOffloadPersist(offloadStore, sessionId, deps.onNotice),
                         },
                     }
                     : {}),

package/dist/core/runner/runtask.js

@@ -131,7 +131,10 @@ const DEFERRED_REISSUE = "[DEFERRED] This tool call shared a batch with a call t
 function toolEndBodyFrom(result, isError, settledBy) {
     const o = toolOutputFrom(result);
     const st = structuredFrom(result);
-    const code = isError ? result?.details?.code : undefined;
+    const det = isError ? result?.details : undefined;
+    const codeRaw = det?.code;
+    const kindRaw = det?.errorKind;
+    const code = typeof codeRaw === "string" ? codeRaw : typeof kindRaw === "string" ? kindRaw : undefined;
     return {
         ...(o !== undefined ? { output: o.output, ...(o.truncated ? { truncated: true } : {}), ...(o.totalChars !== undefined ? { totalChars: o.totalChars } : {}) } : {}),
         ...(st !== undefined ? { structured: st } : {}),
@@ -1412,6 +1415,10 @@ export class Runner {
         return runSideQuery(spec, { brain: this.deps.brain, models: this.deps.models, roles: this.deps.roles });
     }
     runTaskStream(spec, resume, internals) {
+        if (resume !== undefined && (typeof resume !== "object" || resume.outcome === undefined)) {
+            throw new TypeError("runTaskStream: `resume` must be a ResumeRun carrying `outcome` — got a value without one. " +
+                "(Note the parameter order: runTaskStream(spec, resume?, internals?) — internals is the THIRD parameter.)");
+        }
         const entryActor = spec.actor === undefined ? undefined : snapshotActorAssertion(spec.actor);
         const queue = new PushQueue();
         const detachHub = new ToolDetachHub();

package/dist/core/task-registry-agent.d.ts

@@ -471,6 +471,15 @@ export declare function serveDurableAgentRowLane(row: BackgroundAgentRecord): Un
  *
  * No store configured (a deployment that never wired a `toolResultStore`) ⇒ returns `clipped` UNCHANGED
  * — the legal degrade design/158 §2.2 calls for, byte-identical to pre-S1 behavior.
+ *
+ * Backlog #169 — a FAILING `put` (throwing or rejecting; the store contract admits both dialects) is
+ * NOT fatal to the poll: the clipped text is still served, with {@link AGENT_SPILL_FAILED_NOTE} in
+ * place of the ref disclosure (advertising a ref nobody can read back would be a false promise), and
+ * `handle.spillFailed` latches so later polls of the same cycle repeat the honest note instead of
+ * retrying the write — see the catch below for why latch-not-retry. Same "store failure is never
+ * fatal" posture as the monitor/offload/budget/compaction write sites. A put that settles AFTER a
+ * revive (stale cycle) is generation-guarded: it answers its own caller honestly but never writes
+ * spill state onto the new cycle (see `mintCycle` below).
  */
 export declare function spillClippedAgentResult(handle: BackgroundAgentTaskHandle, full: string, clipped: string, store: ToolResultStore | undefined, sessionId: string | undefined): Promise<string>;
 export declare function pollBackgroundAgentLane(handle: BackgroundAgentTaskHandle, deadline?: number, signal?: AbortSignal,