@sema-agent/core 5.24.0 → 5.25.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 5.25.0 — 2026-08-10
+
+No API-BREAKING changes (exports grow only; every new member is optional/additive). One
+behavior-surface narrowing, called out below.
+
+### Narrowed (behavior, ruled)
+
+- **The persisted-rule lane gains its mandate boundary (#144, dual-source measured).** *Allow rules
+  silence the classifier's questions, never a mandated one.* A persisted allow rule used to
+  short-circuit every surviving non-governance ask — including an operator's `shellGate:"always"`
+  (per-call confirmation mandated by deployment config) and a tool's own egress/irreversibility
+  marks (the non-budgetable family). The boundary is a single-source provenance predicate: the
+  classify-doctrine bash ask (coarse tier `"maybe"`) stays the rule lane's home turf (the
+  don't-ask-again main case is deliberately preserved); doctrine-installed `"always"` and
+  tool-declared marks are not clearable by rule. When a rule MATCHES but cannot clear, the surviving
+  ask discloses it on both channels: a message note naming the rule and the mandate, and the new
+  additive `PermissionResult.ask.persistedRuleShadowed` member (the matched rule text) — a consumer
+  renders "your rule is alive, just outranked". **Consumer note**: deployments under
+  `shellGate:"always"` or with marked tools will see asks their users' rules used to clear.
+
+### Added
+
+- **`CheckpointError.detail.reason`** (closed set, additive; downstream-requested): discriminates
+  the pre-CAS refusal arms one code used to cover — `version_newer` / `env_factory_missing` /
+  `governed_unwired` on `unsupported_version` (each retryable on a differently-capable worker), and
+  `real_approval_damaged` / `real_approval_forged` / `constraint_chain_missing` on the
+  `invalid_outcome` row-integrity arms (terminal for the row's bytes). A deployment retry policy can
+  now tell "a capable worker can redeem this" from "no worker ever will".
+- **`REAL_APPROVAL_CHECKPOINT_VERSION` exported** from the package root (joins the other five ladder
+  constants).
+- **The I6 adoption boot gate reaches two more store faces** via an optional `dataRoot` anchor on
+  `FilePermissionRuleStoreProvider` and `createFileTaskListStore` (additive; the adoption arc's own
+  nested rule leg keeps its exemption, pinned). The freeze header states its real coverage — two
+  doors and the seams between them — instead of over-claiming.
+
+### Fixed
+
+- **The disclosure channel is real end-to-end (pre-release rescan on this very batch).**
+  `persistedRuleShadowed` was write-only as first landed: `AskRequest` gains the member (all four
+  mint sites thread it), and the durable park mint carries it as `RiskDescriptor.shadowedRule`
+  (`inlineUntrusted`-capped) — the mandated population's normal route now discloses like the
+  synchronous one. The mandate predicate judges egress FIRST (the tool's own declaration is not
+  shadowed by the coarse doctrine sharing the seat). The secret-scrub quarantine capture stops
+  treating a name collision as a receipt (family suffix form; the polluted-index warning claims a
+  capture only when its write landed). The last silent timeout discard (a legal cap below the
+  resolved default) is announced; an empty env string is a written silence exception (the unset
+  idiom). The materialize-strategy announcements gain a per-value process ledger and a reset seam.
+- **The loud-bad-value law lands on its two founding cases (#123, ruled).** `BASH_*_TIMEOUT_MS`
+  discards stop exempting the garbage/0/negative classes (every discarded value names the knob, what
+  arrived — env legs show the original string — and the value in force);
+  `SEMA_TOOL_MATERIALIZE_STRATEGY`'s refusal now matches the seat the bad value occupies: shadowed
+  by an explicit legal spec ⇒ loud discard (the documented "spec wins" precedence finally holds),
+  would-be-in-force ⇒ the closed-set refusal stands, dormant (no deferred tools) ⇒ announced once
+  per process instead of lying in wait.
+- **A v7+ checkpoint declaring parent constraints must carry both the frozen chain and its digest**
+  (they are one write with the version stamp) — a row carrying neither is refused pre-CAS as damaged
+  instead of silently falling back to the count-only contract. Rows v6 and below keep the historic
+  contract.
+- **The org resume belt's refusal carries the overlay's disclosure lines** (the resume path has no
+  `onUnavailable` seat) and tells a cancelled wait apart from unreadable governance. The verdict is
+  unchanged; the account is not.
+- The sandbox-admission registry/decision domain split is documented and pinned (the two
+  un-instrumented fold families are safe for structural reasons — a family that gains an ask arm
+  reds instead of arriving unrecorded); frozen projections' fold position is disclosed; the adoption
+  report declares the memory-engine tree `action:"none"` explicitly; two engine quarantine captures
+  go `wx`-exclusive (no symlink at the final name, no overwrite of earlier evidence under a coarse
+  clock); the abort-races-timeout test pin gets real load headroom; the v8 stamp note carries its
+  erratum (v8 rows appear on ANY durable deployment via the always-mounted integrity policies — what
+  stays true: rows without the bit keep their historic stamps).
+
 ## 5.24.0 — 2026-08-10
 
 No API-BREAKING changes (exports grow only; `suspendAsk` gains an optional fifth parameter;

package/dist/core/checkpoint-store.d.ts

@@ -135,6 +135,11 @@ export interface RiskDescriptor {
      *  attempted — over-reaching a shell parse risks a wrong/forgeable path). Each path `inlineUntrusted`-capped.
      *  Omitted when none derivable. */
     touchedPaths?: string[];
+    /** #144 (additive): a persisted allow rule MATCHED this call but could not clear the mandated ask —
+     *  the matched rule text (`inlineUntrusted`-capped), threaded to the mint so the durable-park route
+     *  carries the same disclosure the synchronous ask does. The inbox renders "their rule is alive,
+     *  just outranked" instead of the person concluding their rule silently broke. */
+    shadowedRule?: string;
 }
 /**
  * design/80 §D-E: the DETERMINISTIC severity tier (1..5) for an escalation checkpoint, a PURE function of the
@@ -266,6 +271,8 @@ export declare function buildRiskDescriptor(input: {
     shellGated?: boolean;
     /** The resolved doctrine to persist when `shellGated` (see {@link RiskDescriptor.shellGateDoctrine}). */
     shellGateDoctrine?: "classify" | "always";
+    /** #144: the matched-but-outranked persisted rule to persist (see {@link RiskDescriptor.shadowedRule}). */
+    shadowedRule?: string;
 }): RiskDescriptor;
 /**
  * #130/#131/#120 (2026-08-10) — the durable record of an ask's `requiresRealApproval` bit, which used
@@ -805,8 +812,11 @@ export interface CheckpointState {
          * (extra deny-narrowing layers + the pre-CAS edit re-adjudication) rather than trusting a
          * re-supplied policy's execution half for the frozen deny data — a re-supplied closure that
          * matches the digest but behaves differently cannot un-deny what the suspend froze. Present iff
-         * `requiresParentConstraint` on new mints; absent on older checkpoints (⇒ no frozen deny data —
-         * the count-only contract governs, and an EDIT resume is refused for want of a validatable chain). */
+         * `requiresParentConstraint` on new mints; absent on PRE-F-012 checkpoints (⇒ no frozen deny data —
+         * the count-only contract governs, and an EDIT resume is refused for want of a validatable chain).
+         * "Older" is version-decidable, not guessed: chain, digest and the {@link F012_CHECKPOINT_VERSION}
+         * stamp are one write, so on a v7+ row the pair is REQUIRED — its absence there is a damaged row and
+         * the resume ladder refuses it pre-CAS rather than falling back to the count-only contract. */
         constraintChain?: ReadonlyArray<import("./tool-policy.js").ConstraintChainEntry>;
         /**
          * F-012 L1 — the content digest over `constraintChain` ({@link import("./tool-policy.js").constraintChainDigest}):
@@ -814,7 +824,8 @@ export interface CheckpointState {
          * content. The resume pre-CAS ladder recomputes the digest over the RE-SUPPLIED chain's
          * projections and rejects a mismatch (`resume.parent_constraint_mismatch`) — replacing the
          * count-only shape check with a content contract (a same-length chain of different frozen deny
-         * data no longer passes). Present iff `constraintChain` is. */
+         * data no longer passes). Present iff `constraintChain` is — and on a v7+ row both are required
+         * (see {@link constraintChain}: the pair and the version stamp are minted together). */
         constraintDigest?: string;
     };
     /**
@@ -940,7 +951,11 @@ export declare const F012_CHECKPOINT_VERSION = 7;
  * either redeem a governed row with no org wiring at all (#120's exact hole, replayed through version
  * skew) or burn the approval on the unavailable belt the bit exists to soften. Stamping v8 forces it
  * to reject PRE-CAS (`unsupported_version`, stays `pending`, retried on an enforcing worker). A gate
- * with NO `realApproval` keeps the historic stamps — ungoverned deployments see zero version movement.
+ * with NO `realApproval` keeps the historic stamps. NOTE (erratum 2026-08-10, downstream-measured):
+ * "zero version movement for ungoverned deployments" is TOO WIDE — the two always-mounted integrity
+ * policies (transcript-integrity, unverifiable-delete) mint `requiresRealApproval` asks, so a park on
+ * one of THOSE stamps v8 with `origin:"policy"` on ANY durable deployment, org-governed or not. What
+ * stays true: rows whose gate carries no realApproval bit keep their historic stamps everywhere.
  */
 export declare const REAL_APPROVAL_CHECKPOINT_VERSION = 8;
 /** The highest {@link Checkpoint.version} `runner.resume` will act on; a higher one is rejected pre-CAS with
@@ -1463,8 +1478,8 @@ export declare class CheckpointError extends Error {
      *  computable from a self-reported closure, so the edited resume is refused typed pre-CAS (the
      *  checkpoint stays `pending`, still decidable); an UNEDITED approval is untouched. */
      | "resume.constraint_unprojectable";
-    /** Structured discrimination a caller can branch on where the code alone is ambiguous. Today one
-     *  member: `field` names WHICH part of the decision payload was rejected on a
+    /** Structured discrimination a caller can branch on where the code alone is ambiguous. Two
+     *  members. `field` names WHICH part of the decision payload was rejected on a
      *  `checkpoint.invalid_outcome` — `"boundCallId"` (the action you decided on has been replaced:
      *  re-fetch the pending list), `"boundInputHash"` (the input you reviewed has changed under the same
      *  action: re-review), or `"answer"` (the content-ask answer is missing, or was attached to a
@@ -1476,6 +1491,18 @@ export declare class CheckpointError extends Error {
      *  discriminant. */
     readonly detail?: {
         field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy";
+        /** WHICH pre-CAS refusal arm fired, where one `code` covers several (requested 2026-08-10: a
+         *  deployment retry policy needs to tell "a newer worker can redeem this row" from "this row is
+         *  damaged/forged and no worker ever will" — blanket-retriable and gate-shape heuristics were
+         *  both refuted downstream, so the throw site carries the fact it always knew). Closed set;
+         *  additive and optional like `field` — `code` remains the only REQUIRED discriminant.
+         *   · `unsupported_version` arms: `"version_newer"` (retryable on a newer worker),
+         *     `"env_factory_missing"` (retryable on a factory-wired worker), `"governed_unwired"`
+         *     (retryable on an org-wired worker).
+         *   · `invalid_outcome` pre-CAS row-integrity arms: `"real_approval_damaged"`,
+         *     `"real_approval_forged"`, `"constraint_chain_missing"` (all terminal for the row's
+         *     current bytes — no worker version redeems a damaged row). */
+        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "real_approval_damaged" | "real_approval_forged" | "constraint_chain_missing";
     } | undefined;
     constructor(code: "checkpoint.already_exists" | "checkpoint.already_resolved" | "checkpoint.not_found"
     /** `runner.resume` was handed an {@link ResumeOutcome} whose `gate` arm does not match the
@@ -1572,8 +1599,8 @@ export declare class CheckpointError extends Error {
      *  computable from a self-reported closure, so the edited resume is refused typed pre-CAS (the
      *  checkpoint stays `pending`, still decidable); an UNEDITED approval is untouched. */
      | "resume.constraint_unprojectable", message: string, 
-    /** Structured discrimination a caller can branch on where the code alone is ambiguous. Today one
-     *  member: `field` names WHICH part of the decision payload was rejected on a
+    /** Structured discrimination a caller can branch on where the code alone is ambiguous. Two
+     *  members. `field` names WHICH part of the decision payload was rejected on a
      *  `checkpoint.invalid_outcome` — `"boundCallId"` (the action you decided on has been replaced:
      *  re-fetch the pending list), `"boundInputHash"` (the input you reviewed has changed under the same
      *  action: re-review), or `"answer"` (the content-ask answer is missing, or was attached to a
@@ -1585,6 +1612,18 @@ export declare class CheckpointError extends Error {
      *  discriminant. */
     detail?: {
         field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy";
+        /** WHICH pre-CAS refusal arm fired, where one `code` covers several (requested 2026-08-10: a
+         *  deployment retry policy needs to tell "a newer worker can redeem this row" from "this row is
+         *  damaged/forged and no worker ever will" — blanket-retriable and gate-shape heuristics were
+         *  both refuted downstream, so the throw site carries the fact it always knew). Closed set;
+         *  additive and optional like `field` — `code` remains the only REQUIRED discriminant.
+         *   · `unsupported_version` arms: `"version_newer"` (retryable on a newer worker),
+         *     `"env_factory_missing"` (retryable on a factory-wired worker), `"governed_unwired"`
+         *     (retryable on an org-wired worker).
+         *   · `invalid_outcome` pre-CAS row-integrity arms: `"real_approval_damaged"`,
+         *     `"real_approval_forged"`, `"constraint_chain_missing"` (all terminal for the row's
+         *     current bytes — no worker version redeems a damaged row). */
+        reason?: "version_newer" | "env_factory_missing" | "governed_unwired" | "real_approval_damaged" | "real_approval_forged" | "constraint_chain_missing";
     } | undefined);
 }
 /**

package/dist/core/checkpoint-store.js

@@ -120,6 +120,7 @@ export function buildRiskDescriptor(input) {
             axes,
             toolName,
             ...(input.shellGated && input.shellGateDoctrine !== undefined ? { shellGateDoctrine: input.shellGateDoctrine } : {}),
+            ...(input.shadowedRule !== undefined ? { shadowedRule: inlineUntrusted(input.shadowedRule, 200) } : {}),
             ...(summary !== undefined ? { summary } : {}),
             ...(touchedPaths !== undefined ? { touchedPaths } : {}),
         };

package/dist/core/hooks.d.ts

@@ -608,7 +608,10 @@ export interface ToolGateInput {
      *  auto-approve what only judgment may clear). `origin` records whether the bit came from an org
      *  ASK rule, from the org-unavailable tighten (whose resume semantics differ — see
      *  {@link import("./checkpoint-store.js").RealApprovalGateBit}), or from a policy/hook. */
-    realApproval?: import("./checkpoint-store.js").RealApprovalGateBit) => Promise<ToolGateResult["suspend"] | ParkAttemptFailed | undefined>;
+    realApproval?: import("./checkpoint-store.js").RealApprovalGateBit, 
+    /** #144: the matched-but-outranked persisted rule (the surviving ask's `persistedRuleShadowed`)
+     *  — threaded so the park mint's risk descriptor carries the disclosure on the durable route. */
+    shadowedRule?: string) => Promise<ToolGateResult["suspend"] | ParkAttemptFailed | undefined>;
     /**
      * design/174 — route a policy `ask` on the reserved question tool to this run's CONTENT-ask channel
      * before it can become a park or a refusal. Called in the `ask` branch with the FINAL post-hook,
@@ -728,10 +731,14 @@ export interface ToolGateInput {
      *  · the reserved question tool and a call MARKED unresolvable are excluded for the same reason the
      *    classifier excludes them: both contracts require that no synchronous decision-maker stands between
      *    the ask and the park / content route, and this lane is one.
-     * What it DOES consume is the egress and irreversibility/shellGate tightens and unmarked bare asks —
-     * deliberately, because a deployment forcing shell classification is exactly where the feature is for.
-     * Consuming such an ask also skips the park it would have minted; that IS what a standing approval
-     * means, and the first bullet is what keeps an integrity ask out of that set.
+     *  · #144 (ruled): a MANDATED ask is never consumed — an operator's shellGate:"always" tier and a
+     *    tool's own egress/irreversibility marks are structural requirements, not classifier hesitation
+     *    ("allow rules silence the classifier's questions, never a mandated one"). When a rule matches
+     *    but cannot clear, the surviving ask discloses it (message + `persistedRuleShadowed`).
+     * What it DOES consume is the classify-DOCTRINE shell ask (the coarse tier "maybe" — the
+     * don't-ask-again main case this feature exists for) and unmarked bare asks. Consuming such an ask
+     * also skips the park it would have minted; that IS what a standing approval means, and the
+     * bullets above are what keep integrity/hook/mandated asks out of that set.
      */
     persistedRules?: {
         /** The canonical text of the rule that admits this call, or `undefined`. Must not throw: a store that

package/dist/core/hooks.js

@@ -315,6 +315,15 @@ export async function runToolGate(input) {
             currentInput = policyRewrite;
             req.args = policyRewrite;
         }
+        const persistedRuleMandate = input.egress === true
+            ? "tool_marks"
+            : input.shellGated === true
+                ? input.irreversibility === "always"
+                    ? "operator_always"
+                    : undefined
+                : input.irreversibility === "always" || input.irreversibility === "maybe"
+                    ? "tool_marks"
+                    : undefined;
         if (input.persistedRules &&
             !orgRealApprovalRequired &&
             decision.action === "ask" &&
@@ -323,7 +332,7 @@ export async function runToolGate(input) {
             req.toolName !== ASK_USER_QUESTION_TOOL_NAME &&
             input.isMarkedUnresolvable?.(input.event.toolCallId) !== true) {
             const hit = await input.persistedRules.admits(req).catch(() => undefined);
-            if (hit !== undefined) {
+            if (hit !== undefined && persistedRuleMandate === undefined) {
                 decision = {
                     action: "allow",
                     message: `a persisted allow rule (${hit}) covers this call`,
@@ -332,6 +341,14 @@ export async function runToolGate(input) {
                 };
                 await notifier.notifyAsync(() => input.persistedRules?.onResolved?.({ toolName: req.toolName, toolCallId, rule: hit }), "toolGate.persistedRuleResolved");
             }
+            else if (hit !== undefined) {
+                const mandateNoun = persistedRuleMandate === "operator_always" ? "this deployment mandates per-call confirmation for shell commands (shellGate: always)" : "this tool carries egress/irreversibility marks (a mandated confirmation a rule cannot clear)";
+                decision = {
+                    ...decision,
+                    persistedRuleShadowed: hit,
+                    message: `${decision.message !== undefined ? `${decision.message} ` : ""}(a persisted allow rule (${hit}) matches this call but does not clear the ask — ${mandateNoun})`,
+                };
+            }
         }
         if (input.autoMode &&
             !orgRealApprovalRequired &&
@@ -390,7 +407,7 @@ export async function runToolGate(input) {
             ? { origin: orgAskOrigin !== undefined ? `org_${orgAskOrigin}` : "policy" }
             : undefined;
         if (suspendAsk && decision.action === "ask") {
-            const suspended = await suspendAsk(req, currentInput, safety, undefined, realApprovalOf(decision));
+            const suspended = await suspendAsk(req, currentInput, safety, undefined, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined);
             if (suspended) {
                 if ("parkFailed" in suspended)
                     parkFailed = suspended.parkFailed;
@@ -409,7 +426,7 @@ export async function runToolGate(input) {
                     req.args = outcome.presentedInput;
                 }
                 if (suspendAsk && outcome.parkDeclined && parkFailed === undefined) {
-                    const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(decision));
+                    const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined);
                     if (suspended) {
                         if ("parkFailed" in suspended)
                             parkFailed = suspended.parkFailed;
@@ -437,7 +454,7 @@ export async function runToolGate(input) {
             const resolved = await resolveAsk(decision, req);
             decision = resolved;
             if (resolved.action === "deny" && resolved.approverUnavailable === true && suspendAsk && parkFailed === undefined) {
-                const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(askBeforeResolve));
+                const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(askBeforeResolve), askBeforeResolve.action === "ask" ? askBeforeResolve.persistedRuleShadowed : undefined);
                 if (suspended) {
                     if ("parkFailed" in suspended)
                         parkFailed = suspended.parkFailed;

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

@@ -656,16 +656,18 @@ export class MemoryEngine {
             const indexNow = readSafe(pollutedIndexPath);
             if (indexNow === undefined || indexNow === handle.indexText)
                 return;
+            let indexCaptureLanded = false;
             try {
                 const dest = join(this.controlDir, QUARANTINE_DIR, `${this.now()}-polluted-${MEMORY_INDEX_FILENAME}`);
                 ensureDirExists(dirname(dest));
-                writeFileSync(dest, indexNow, "utf8");
+                writeFileSync(dest, indexNow, { encoding: "utf8", flag: "wx" });
+                indexCaptureLanded = true;
             }
             catch {
             }
             try {
                 writeFileNoFollow(pollutedIndexPath, handle.indexText);
-                report.warnings.push("memory index restored to its pre-session state — this session's index additions were not retained (session polluted; the removed text was captured to quarantine)");
+                report.warnings.push(`memory index restored to its pre-session state — this session's index additions were not retained (session polluted; ${indexCaptureLanded ? "the removed text was captured to quarantine" : "the quarantine capture did NOT land — the removed text is gone"})`);
             }
             catch (err) {
                 report.warnings.push(`memory index could NOT be restored to its pre-session state: ${err instanceof Error ? err.message : String(err)}`);
@@ -1225,7 +1227,20 @@ export class MemoryEngine {
         try {
             const dest = join(this.controlDir, QUARANTINE_DIR, `${this.now()}-${MEMORY_INDEX_FILENAME}`);
             ensureDirExists(dirname(dest));
-            writeFileSync(dest, text, "utf8");
+            let landed = false;
+            for (let attempt = 0; !landed && attempt < 10; attempt++) {
+                const candidate = attempt === 0 ? dest : `${dest}.${attempt}`;
+                try {
+                    writeFileSync(candidate, text, { encoding: "utf8", flag: "wx" });
+                    landed = true;
+                }
+                catch (err) {
+                    if (!(err instanceof Error && "code" in err && err.code === "EEXIST"))
+                        throw err;
+                }
+            }
+            if (!landed)
+                writeFileSync(`${dest}.${process.pid}`, text, { encoding: "utf8", flag: "wx" });
             captured = true;
         }
         catch (err) {

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

@@ -112,6 +112,15 @@ export declare const ORG_ADJUDICATION_TIMEOUT_MS = 15000;
 export declare function settleOrgVerdictWithin<T>(p: Promise<T>, fallback: T, opts: {
     signal?: AbortSignal;
     timeoutMs: number;
+    /**
+     * backlog #136④ — which arm WON, reported at the moment it won. A consumer that wants to tell a
+     * cancelled wait from an unreadable provider cannot get that by sampling `signal.aborted` after
+     * the await: a cancellation queued between the settlement and the continuation reads identically
+     * to one that actually ended the wait, and the operator-facing account would name the wrong
+     * cause. Called at most once, before `p` resolves, and only for the two non-provider arms —
+     * absent call ⇒ the awaited promise itself settled.
+     */
+    onFallback?: (cause: "aborted" | "timeout") => void;
 }): Promise<T>;
 /** The `decisionReason` of a decision an ORG RULE produced (a deny, or a non-dismissable ask). Same
  *  single-spelling contract as {@link ORG_UNAVAILABLE_DECISION_REASON}. */

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

@@ -11,22 +11,29 @@ export const ORG_ADJUDICATION_TIMEOUT_MS = 15_000;
 export function settleOrgVerdictWithin(p, fallback, opts) {
     return new Promise((resolve) => {
         let settled = false;
-        const finish = (v) => {
+        const finish = (v, cause) => {
             if (settled)
                 return;
             settled = true;
             clearTimeout(timer);
             opts.signal?.removeEventListener("abort", onAbort);
+            if (cause !== undefined) {
+                try {
+                    opts.onFallback?.(cause);
+                }
+                catch {
+                }
+            }
             resolve(v);
         };
-        const onAbort = () => finish(fallback);
-        const timer = setTimeout(() => finish(fallback), opts.timeoutMs);
+        const onAbort = () => finish(fallback, "aborted");
+        const timer = setTimeout(() => finish(fallback, "timeout"), opts.timeoutMs);
         if (opts.signal?.aborted === true) {
-            finish(fallback);
+            finish(fallback, "aborted");
             return;
         }
         opts.signal?.addEventListener("abort", onAbort);
-        p.then(finish, () => finish(fallback));
+        p.then((v) => finish(v), () => finish(fallback));
     });
 }
 export const ORG_RULE_DECISION_REASON = "org_rule";

package/dist/core/runner/prepare-task.d.ts

@@ -28,6 +28,8 @@ import { type WiringManifest } from "../wiring-manifest.js";
 import type { ActiveWorktreeSession, AgentMessage, AgentTool, ExecutionEnv } from "../../internal/harness.js";
 import type { NestedUsageAccum, RunnerDeps, TaskEvent, TaskLimits, TaskResult, TaskSpec, ToolActivity, ToolEffect } from "../types.js";
 import type { RepairBundle } from "../../agents/repair-loop.js";
+/** Test seam (mirrors `__resetBashTimeoutAnnouncements`): never called by production code. */
+export declare function __resetMaterializeEnvAnnouncements(): void;
 /**
  * design/164 — validate `TaskSpec.limits` at the door and return it unchanged.
  *

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

@@ -89,6 +89,10 @@ 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";
+const announcedMaterializeEnv = new Set();
+export function __resetMaterializeEnvAnnouncements() {
+    announcedMaterializeEnv.clear();
+}
 const RECONCILE_MAX_RETRIES = 3;
 const DEFAULT_MAX_SUSPENDS = 5;
 const TASK_LIMIT_KEY_DICT = {
@@ -2572,6 +2576,16 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             toolsDeltaRef = { pending: [], pendingRemoved: [], pendingReadded: [], pendingFailed: failedMcpServers };
         }
         const listingRideRef = {};
+        {
+            const raw = process.env.SEMA_TOOL_MATERIALIZE_STRATEGY;
+            if (raw !== undefined && raw !== "swap" && raw !== "static" && deferred.size === 0) {
+                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);
+                }
+            }
+        }
         if (deferred.size > 0) {
             if (deferred.has(TOOL_SEARCH_NAME) || tools.some((t) => t.name === TOOL_SEARCH_NAME)) {
                 const e = new Error(`Tool name "${TOOL_SEARCH_NAME}" is reserved when deferred tools are present.`);
@@ -2579,12 +2593,21 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 throw e;
             }
             const registry = buildDeferredRegistry(deferred, tools);
-            const envStrategy = process.env.SEMA_TOOL_MATERIALIZE_STRATEGY;
-            if (envStrategy !== undefined && envStrategy !== "swap" && envStrategy !== "static") {
-                const e = new Error(`SEMA_TOOL_MATERIALIZE_STRATEGY must be "swap" or "static" (got ${JSON.stringify(envStrategy)}).`);
+            const rawEnvStrategy = process.env.SEMA_TOOL_MATERIALIZE_STRATEGY;
+            const envStrategyInvalid = rawEnvStrategy !== undefined && rawEnvStrategy !== "swap" && rawEnvStrategy !== "static";
+            if (envStrategyInvalid && spec.toolMaterializeStrategy === undefined) {
+                const e = new Error(`SEMA_TOOL_MATERIALIZE_STRATEGY must be "swap" or "static" (got ${JSON.stringify(rawEnvStrategy)}).`);
                 e.code = "config.tool_materialize_invalid";
                 throw e;
             }
+            if (envStrategyInvalid) {
+                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);
+                }
+            }
+            const envStrategy = envStrategyInvalid ? undefined : rawEnvStrategy;
             const requestedStrategy = spec.toolMaterializeStrategy ?? envStrategy ?? "swap";
             const laneDegrade = requestedStrategy === "static" && spec.deferSelfResolve === false;
             const materializeStatic = requestedStrategy === "static" && !laneDegrade;
@@ -3273,6 +3296,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     ...askSourceIdentity(),
                     ...riskAxesOf(creq.toolName),
                     ...(re.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+                    ...(re.persistedRuleShadowed !== undefined ? { persistedRuleShadowed: re.persistedRuleShadowed } : {}),
                 }, onAskOf, csignal ?? abortController.signal);
                 if (rr.action !== "allow")
                     return rr;
@@ -3357,6 +3381,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             ...askSourceIdentity(),
                             ...riskAxesOf(creq.toolName),
                             ...(first.action === "ask" && first.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+                            ...(first.action === "ask" && first.persistedRuleShadowed !== undefined ? { persistedRuleShadowed: first.persistedRuleShadowed } : {}),
                         }, pc.onAsk, csignal ?? abortController.signal);
                         const askWaitMs = Math.max(0, now() - askT0);
                         if (resolved.action === "deny" && resolved.approverUnavailable === true) {
@@ -3443,6 +3468,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             ...askSourceIdentity(),
                             ...riskAxesOf(creq.toolName),
                             ...(decision.action === "ask" && decision.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+                            ...(decision.action === "ask" && decision.persistedRuleShadowed !== undefined ? { persistedRuleShadowed: decision.persistedRuleShadowed } : {}),
                         }, pc.onAsk, csignal ?? abortController.signal);
                         const askWaitMs = Math.max(0, now() - askT0);
                         if (resolved.action === "deny" && resolved.approverUnavailable === true) {
@@ -3755,6 +3781,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     ...askSourceIdentity(),
                     ...riskAxesOf(req.toolName),
                     ...(decision.action === "ask" && decision.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+                    ...(decision.action === "ask" && decision.persistedRuleShadowed !== undefined ? { persistedRuleShadowed: decision.persistedRuleShadowed } : {}),
                 }, onAsk, abortController.signal);
                 const waitMs = Math.max(0, now() - t0);
                 if (resolved.approverUnavailable !== true) {
@@ -4236,7 +4263,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 }
             };
             const suspendAsk = parkLaneArmed && checkpointStore !== undefined
-                ? async (req, postHookArgs, safety, liveFaceUnavailable, realApproval) => {
+                ? async (req, postHookArgs, safety, liveFaceUnavailable, realApproval, shadowedRule) => {
                     const syncFirstEligible = req.toolName === ASK_USER_QUESTION_TOOL_NAME ? contentAskRoutable(req.toolCallId) : isLiveApproverSeat(onAsk);
                     if (syncFirstEligible &&
                         runtimeCaps?.forceDurableGate !== true &&
@@ -4341,6 +4368,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             toolName: req.toolName,
                             args: parkedArgs,
                             safety,
+                            ...(shadowedRule !== undefined ? { shadowedRule } : {}),
                             shellGated: (req.toolName === "Bash" && shellGatedBash) || (req.toolName === "Monitor" && shellGatedMonitor),
                             ...(effectiveShellGate !== "off" ? { shellGateDoctrine: effectiveShellGate } : {}),
                         });

package/dist/core/runner/runtask.js

@@ -1,6 +1,6 @@
 import { AgentHarness, DEFAULT_COMPACTION_SETTINGS, uuidv7 } from "../../internal/harness.js";
 import { snapshotActorAssertion } from "../../internal/llm.js";
-import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, MAX_SUPPORTED_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, remainingBudgetMicroUsd, readPendingSteerQueue, remainingTokens, validatePendingSteer, winnerFromOutcome, } from "../checkpoint-store.js";
+import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, F012_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, remainingBudgetMicroUsd, readPendingSteerQueue, remainingTokens, validatePendingSteer, winnerFromOutcome, } from "../checkpoint-store.js";
 import { engineVersion } from "../version.js";
 import { CONFIG_CATALOG_VERSION, declarationReasons, resolveEffectiveConfig } from "../../config/catalog.js";
 import { eventDefaultOn } from "../../prompt-assembly/event-registry.js";
@@ -71,6 +71,7 @@ const STOP_HOOK_BLOCK_CAP = 8;
 const COMPACTION_REGROWTH_FACTOR = 1.5;
 const COMPACTION_FREED_EPSILON = 256;
 const BATCH_RESPONSE_MAX_CHARS = 500;
+const ORG_DISCLOSURE_MAX_CHARS = 600;
 function batchResponseDigest(result) {
     const content = result !== null && typeof result === "object" ? result.content : result;
     if (content === undefined || content === null)
@@ -3702,7 +3703,7 @@ export class Runner {
             }
         }
         if (checkpointVersionOf(cp) > MAX_SUPPORTED_CHECKPOINT_VERSION) {
-            throw new CheckpointError("checkpoint.unsupported_version", `checkpoint version ${checkpointVersionOf(cp)} is newer than this worker supports (max ${MAX_SUPPORTED_CHECKPOINT_VERSION})`);
+            throw new CheckpointError("checkpoint.unsupported_version", `checkpoint version ${checkpointVersionOf(cp)} is newer than this worker supports (max ${MAX_SUPPORTED_CHECKPOINT_VERSION})`, { reason: "version_newer" });
         }
         const preCasGateBit = cp.gate.kind === "irreversible_ask" ? cp.gate.realApproval : undefined;
         const preCasBitWellFormed = preCasGateBit !== undefined &&
@@ -3713,11 +3714,11 @@ export class Runner {
         if (checkpointVersionOf(cp) >= REAL_APPROVAL_CHECKPOINT_VERSION ? !preCasBitWellFormed : preCasGateBit !== undefined) {
             throw new CheckpointError("checkpoint.invalid_outcome", checkpointVersionOf(cp) >= REAL_APPROVAL_CHECKPOINT_VERSION
                 ? `a v${checkpointVersionOf(cp)} checkpoint must carry a well-formed non-budgetable realApproval gate bit (origin org_rule/org_unavailable/policy) on an irreversible_ask gate — this row does not; refusing to resume a damaged real-approval row (corruption / downgrade guard), the checkpoint stays pending`
-                : `a v${checkpointVersionOf(cp)} checkpoint carries a realApproval gate bit no release of that version ever minted — refusing to honor a fabricated origin (corruption / forgery guard), the checkpoint stays pending`);
+                : `a v${checkpointVersionOf(cp)} checkpoint carries a realApproval gate bit no release of that version ever minted — refusing to honor a fabricated origin (corruption / forgery guard), the checkpoint stays pending`, { reason: checkpointVersionOf(cp) >= REAL_APPROVAL_CHECKPOINT_VERSION ? "real_approval_damaged" : "real_approval_forged" });
         }
         if ((preCasGateBit?.origin === "org_rule" || preCasGateBit?.origin === "org_unavailable") &&
             this.deps.permissionRuleOrg === undefined) {
-            throw new CheckpointError("checkpoint.unsupported_version", `this checkpoint's approval was minted under organization governance (${preCasGateBit.origin}) and this worker has no org adjudication wiring (permissionRuleOrg) — a governed approval may only be redeemed where governance can be enforced; the checkpoint stays pending, resume it on an org-wired worker`);
+            throw new CheckpointError("checkpoint.unsupported_version", `this checkpoint's approval was minted under organization governance (${preCasGateBit.origin}) and this worker has no org adjudication wiring (permissionRuleOrg) — a governed approval may only be redeemed where governance can be enforced; the checkpoint stays pending, resume it on an org-wired worker`, { reason: "governed_unwired" });
         }
         const retiredWalltimeTotal = cp.resourceLedger?.totalWalltimeSec;
         if (retiredWalltimeTotal !== undefined) {
@@ -3729,7 +3730,7 @@ export class Runner {
             throw new CheckpointError("checkpoint.resume_aborted", "the resume was handed an ALREADY-ABORTED signal — refusing to consume the approval on a leg that cannot run it (the checkpoint stays pending and is resumable with a live signal)");
         }
         if (cp.state.workspaceHandle !== undefined && this.deps.executionEnvFactory === undefined) {
-            throw new CheckpointError("checkpoint.unsupported_version", "checkpoint has a remote workspaceHandle but no RunnerDeps.executionEnvFactory is wired to rebuild the env");
+            throw new CheckpointError("checkpoint.unsupported_version", "checkpoint has a remote workspaceHandle but no RunnerDeps.executionEnvFactory is wired to rebuild the env", { reason: "env_factory_missing" });
         }
         if (cp.state.inheritedGate?.requiresParentConstraint === true) {
             const supplied = internals?.inheritedGate?.parentConstraints?.length ?? 0;
@@ -3745,6 +3746,10 @@ export class Runner {
                     "re-supply would run the resumed leg under a different ancestor chain than it suspended with; " +
                     "rejected pre-CAS (the checkpoint stays pending) — re-resume with the full original chain");
             }
+            if (checkpointVersionOf(cp) >= F012_CHECKPOINT_VERSION &&
+                (cp.state.inheritedGate.constraintChain === undefined || cp.state.inheritedGate.constraintDigest === undefined)) {
+                throw new CheckpointError("checkpoint.invalid_outcome", `a v${checkpointVersionOf(cp)} checkpoint that requires parent constraints must carry BOTH the frozen constraintChain and its constraintDigest (they are minted in one write with the version stamp) — this row carries neither or only one; refusing to fall back to the count-only contract on a damaged row (corruption / downgrade guard), the checkpoint stays pending`, { reason: "constraint_chain_missing" });
+            }
             const expectedDigest = cp.state.inheritedGate.constraintDigest;
             if (expectedDigest !== undefined) {
                 const persistedChain = cp.state.inheritedGate.constraintChain;
@@ -4037,16 +4042,28 @@ export class Runner {
             const orgVerdict = prepared.permissionRuleOrg
                 .adjudicate({ toolName: pendingAction.toolName, args: resolvedArgs, toolCallId: pendingAction.toolCallId })
                 .catch(() => ({ status: "unavailable", disclosures: ["the org adjudication face threw on resume"] }));
-            const org = await settleOrgVerdictWithin(orgVerdict, { status: "unavailable", disclosures: [`the org adjudication face did not answer within ${ORG_ADJUDICATION_TIMEOUT_MS}ms (or the task ended first)`] }, { signal: prepared.abortController.signal, timeoutMs: ORG_ADJUDICATION_TIMEOUT_MS });
+            let orgWaitCancelled = false;
+            const org = await settleOrgVerdictWithin(orgVerdict, { status: "unavailable", disclosures: [`the org adjudication face did not answer within ${ORG_ADJUDICATION_TIMEOUT_MS}ms (or the task ended first)`] }, {
+                signal: prepared.abortController.signal,
+                timeoutMs: ORG_ADJUDICATION_TIMEOUT_MS,
+                onFallback: (cause) => {
+                    orgWaitCancelled = cause === "aborted";
+                },
+            });
             const blocked = org.status === "unavailable"
                 ? gateRealApproval?.origin === "org_unavailable"
                     ? undefined
-                    : "this deployment is org-governed and cannot currently adjudicate against an organization policy snapshot"
+                    : orgWaitCancelled
+                        ? "this deployment is org-governed and the task was cancelled before the organization policy snapshot could be adjudicated"
+                        : "this deployment is org-governed and cannot currently adjudicate against an organization policy snapshot"
                 : org.verdict?.behavior === "deny"
                     ? `an organization policy rule (${org.verdict.rule}) denies it`
                     : undefined;
             if (blocked !== undefined) {
-                const orgDenial = formatHookFeedback(`The approved tool call "${pendingAction.toolName}" was not executed: ${blocked}. This approval is spent — the call has to be re-issued and approved again once organization policy permits it.`);
+                const orgDisclosures = org.status === "unavailable" && org.disclosures.length > 0
+                    ? ` Governance disclosures: ${inlineUntrusted(org.disclosures.join("; "), ORG_DISCLOSURE_MAX_CHARS)}.`
+                    : "";
+                const orgDenial = formatHookFeedback(`The approved tool call "${pendingAction.toolName}" was not executed: ${blocked}.${orgDisclosures} This approval is spent — the call has to be re-issued and approved again once organization policy permits it.`);
                 emitEnd(true, { content: orgDenial });
                 const eid = await prepared.session.appendMessage(toolResultMsg(pendingAction.toolCallId, pendingAction.toolName, orgDenial, true));
                 emitCommitted(eid, "toolResult", pendingAction.toolCallId);

package/dist/core/tool-policy.d.ts

@@ -167,6 +167,13 @@ export type PermissionResult = {
     message?: string;
     decisionReason?: DecisionReason;
     requiresRealApproval?: boolean;
+    /** #144 disclosure (additive): a persisted allow rule MATCHED this call but could not clear the
+     *  ask, because the ask is MANDATED (operator shellGate:"always", or the tool's own
+     *  egress/irreversibility marks) rather than a classifier's hesitation — "allow rules silence
+     *  the classifier's questions, never a mandated one". Carries the matched rule text so a
+     *  consumer (approval card, wire frame) can tell the person their rule is alive, just outranked.
+     *  Absent ⇒ no rule matched, or the ask was cleared normally. */
+    persistedRuleShadowed?: string;
 } | {
     action: "deny";
     updatedInput?: unknown;
@@ -601,6 +608,10 @@ export interface AskDelegationProvenance {
 /** The structured context an `onAsk` approver receives for an `ask` decision (design/37). */
 export interface AskRequest {
     toolName: string;
+    /** #144: a persisted allow rule MATCHED this call but could not clear the ask (mandated — see
+     *  {@link PermissionResult}'s ask arm). The matched rule text, so the approval card renders "your
+     *  rule is alive, just outranked" instead of leaving the person to regex the message prose. */
+    persistedRuleShadowed?: string;
     toolCallId: string;
     /** The (post-rewrite) args the tool would run with. */
     args: unknown;

package/dist/index.d.ts

@@ -88,7 +88,7 @@ export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW,
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, type BashReadonlyRootBoundary, type CompoundReadonlyVerdict, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, type ToolResultStore, type ToolResultSlice, } from "./core/tool-result-store.js";
-export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, type ActorAssertion, type PendingSteerEntry, type PendingSteerInput, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type RealApprovalGateBit, type ResourceLedger, type ResourceLimitReason, type PlatformLimitReason, } from "./core/checkpoint-store.js";
+export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, type ActorAssertion, type PendingSteerEntry, type PendingSteerInput, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type RealApprovalGateBit, type ResourceLedger, type ResourceLimitReason, type PlatformLimitReason, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, type UsageWindow, type UsageWindowStore, type UsageWindowReading, type UsageWindowRecord, type UsageSlot, type UsageBucketRow, } from "./core/usage-window-store.js";
 export { FileUsageWindowStore } from "./stores/file/usage-window-store.js";
 export { ENV_LIFETIME_SUSPEND_MARGIN_MS, USAGE_WINDOW_REAP_MARGIN_MS } from "./core/runner/prepare-task.js";

package/dist/index.js

@@ -69,7 +69,7 @@ export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW,
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, } from "./core/tool-result-store.js";
-export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, } from "./core/checkpoint-store.js";
+export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, } from "./core/usage-window-store.js";
 export { FileUsageWindowStore } from "./stores/file/usage-window-store.js";
 export { ENV_LIFETIME_SUSPEND_MARGIN_MS, USAGE_WINDOW_REAP_MARGIN_MS } from "./core/runner/prepare-task.js";

package/dist/stores/file/adoption/adopt.d.ts

@@ -24,9 +24,29 @@
  *   ⑥ the marker is atomically rewritten into its PERMANENT terminal record carrying the immutable
  *     report. Never deleted; a re-run short-circuits to it.
  *
- * FREEZE (design/183 §8 load-bearing premise): from the moment ② lands, the whole root is read-only
- * for everyone but this machine — live writers are excluded by the locks, and across crashes every
- * file store constructor refuses the in-flight marker (invariant I6, `assertAdoptionBootGate`).
+ * FREEZE (design/183 §8 load-bearing premise): from the moment ② lands, the root is closed to new
+ * writers — and it is worth being exact about which mechanism covers what, because the two halves
+ * meet at a seam rather than overlapping (backlog #136⑧):
+ *   · the LOCKS cover the boot-locked shape: this machine holds `LOCK` (the engine's own boot lock,
+ *     taken by `FileStorageBackend`) and `ADOPTION-LOCK` for the whole arc, so a live backend refuses
+ *     the adoption instead of interleaving with it, and a second adoption refuses too;
+ *   · invariant I6 (`assertAdoptionBootGate`) covers CONSTRUCTION over a DATA-ROOT ANCHOR: while the
+ *     marker is in flight, a store constructor handed the data root refuses it — including across a
+ *     crash, when no lock survives.
+ * What NEITHER covers, enumerated rather than implied:
+ *   · an ALREADY-constructed instance over this root through a path that does not hold `LOCK` (the
+ *     independent store faces — `new FileMemoryStore(root)`, the mailbox family). It keeps its open
+ *     handles, and I6 is a construction-time gate, not a write-time one;
+ *   · a NEW construction whose anchor is not the data root. Two faces take a directory that need not
+ *     BE the data root — `FilePermissionRuleStoreProvider` (the rule bucket) and
+ *     `createFileTaskListStore` (the document's own directory) — so each takes its root anchor as an
+ *     explicit option, and a caller that omits it constructs unGATED during a freeze. That default is
+ *     what this arc's own nested rule leg rides (it must reach the bucket while the marker is in
+ *     flight); a deployment wanting the gate passes the anchor. Both arms are pinned.
+ * That is the same boundary the file family draws everywhere else (one live writer per data root is
+ * the deployment's contract, mechanically enforced only for the backend-factory shape), and it is why
+ * "stop the engine before adopting" remains an operational instruction and not merely a machine-
+ * checked one.
  * Idempotent resume ("re-run completes the unfinished legs") is only sound because no per-store row
  * moves underneath it; the freeze is the premise of idempotence, not an implementation detail.
  *

package/dist/stores/file/adoption/adopt.js

@@ -249,6 +249,7 @@ const ZERO_ACTION_STORES = [
     "tool-result",
     "file-snapshot",
     "memory",
+    "memory-engine",
     "task-list",
     "mailbox",
     "workflow-run",

package/dist/stores/file/adoption/marker.d.ts

@@ -5,8 +5,11 @@
  * Two shapes live in `<dataRoot>/adoption.json`:
  *  - the IN-FLIGHT marker (`marker`): a monotonically-advanced `phase` plus per-leg completion bits
  *    for the one leg class without a self-attesting completion predicate (row rewrites). While this
- *    shape is on disk the root is FROZEN: every file store constructor refuses to build over it
- *    ({@link assertAdoptionBootGate} — invariant I6), so no writer can serve a half-migrated root.
+ *    shape is on disk the root is FROZEN: every file store constructor ANCHORED TO THE DATA ROOT
+ *    refuses to build over it ({@link assertAdoptionBootGate} — invariant I6). Coverage is stated
+ *    precisely at the gate's own docstring: two faces whose constructor argument is not the root
+ *    take an optional `dataRoot` anchor, and a caller omitting it is outside the gate (the seam is
+ *    documented and pinned where those faces live).
  *  - the PERMANENT terminal record (`adopted`): never deleted. It is the idempotence anchor (a re-run
  *    with the same (from → toPrincipal) short-circuits to the recorded receipt) and it carries the
  *    IMMUTABLE report — the byte-stable half of every receipt.
@@ -186,17 +189,29 @@ export declare function readRootAdoptionFile(root: string): RootAdoptionFile | u
 /** Atomically publish the root marker (write-temp → fsync → rename, same discipline as every store). */
 export declare function writeRootAdoptionFile(root: string, content: RootAdoptionFile): void;
 /**
- * Invariant I6 (design/183 §3.1) — the adoption BOOT GATE, called by every file store constructor:
- * an in-flight root marker means the root is mid-adoption (possibly after a crash), and serving a
- * half-migrated root is refused LOUDLY. The refusal names the in-flight arc and the way forward
- * (resume `adoptLocalDataRoot` to completion). A terminal record passes: a completed adoption is a
- * normal, readable root. A corrupt marker throws (fail-closed, see {@link readRootAdoptionFile}).
+ * Invariant I6 (design/183 §3.1) — the adoption BOOT GATE: an in-flight root marker means the root is
+ * mid-adoption (possibly after a crash), and serving a half-migrated root is refused LOUDLY. The
+ * refusal names the in-flight arc and the way forward (resume `adoptLocalDataRoot` to completion). A
+ * terminal record passes: a completed adoption is a normal, readable root. A corrupt marker throws
+ * (fail-closed, see {@link readRootAdoptionFile}).
+ *
+ * WHO calls it, precisely: every store constructor whose argument IS the data root (that is most of
+ * the family — they derive their own subdirectory from it). The two faces whose argument is a
+ * caller-chosen directory instead — `FilePermissionRuleStoreProvider` (a rule bucket) and
+ * `createFileTaskListStore` (the document's directory) — cannot anchor on their argument, so each
+ * takes the data root as an explicit option and is gated only when given one. `root` here is always
+ * the ANCHOR, never "wherever this store keeps its bytes": passing a subdirectory reads a marker that
+ * is not there and passes unconditionally.
  *
  * This gate is what turns "the engine must be stopped during adoption" from an operational assumption
  * into a machine-checked invariant across crashes: the adoption's own locks die with its process, but
- * the marker (and this gate) survive. Boundary, stated honestly: the gate fires at CONSTRUCTION time.
- * A store instance constructed BEFORE the marker landed in another OS process is outside it — cross-
- * process sharing of one data dir is the file family's documented UNSUPPORTED shape (task-list F-14,
- * mailbox RB-249); adoption adds no new promise there.
+ * the marker (and this gate) survive. Boundary, stated honestly: the gate fires at CONSTRUCTION time,
+ * and it is the ONLY thing this function does — it never reaches an object that already exists. So a
+ * store instance constructed BEFORE the marker landed keeps writing for as long as it is held, in
+ * ANOTHER OS process (cross-process sharing of one data dir is the file family's documented
+ * UNSUPPORTED shape — task-list F-14, mailbox RB-249) and, symmetrically, in THIS one (an independent
+ * store face built before the adoption started; the arc's `LOCK` acquisition excludes a live
+ * `FileStorageBackend`, which is the only shape that takes that lock). Adoption adds no new promise on
+ * either side of that seam — see the freeze note on `adoptLocalDataRoot` for the full division.
  */
 export declare function assertAdoptionBootGate(root: string, storeName: string): void;

package/dist/stores/file/permission-rule-store.d.ts

@@ -157,12 +157,26 @@ declare class FilePermissionRuleStore implements WritablePermissionRuleStore {
  *
  * An absent principal resolves to a store that reads zero rules and refuses to write — an unauthenticated
  * task does not share anyone's bucket.
+ *
+ * ROOT FREEZE (design/183 invariant I6, backlog #136⑤): every sibling file store gates construction on
+ * the DATA ROOT's adoption marker, but this provider is built over the RULE BUCKET directory, which is
+ * a caller-chosen path that need not sit under (or equal) the data root — so `dir` is not a usable
+ * anchor for that gate and the bucket was writable straight through a root freeze. The anchor is
+ * therefore taken EXPLICITLY, via `opts.dataRoot`: supply it whenever the rule bucket belongs to a data
+ * root that `adoptLocalDataRoot` may adopt, and construction is refused while that root is mid-adoption
+ * exactly like `FileStorageBackend`'s. Omitting it keeps the previous behavior (no root gate) — which is
+ * also the EXEMPTION the adoption machine itself rides: its nested design/182 rule leg constructs this
+ * provider without a `dataRoot` precisely because it runs while the marker is in flight, and the
+ * bucket-level marker (read in `forPrincipal`/`forLocalOwner`) is what governs writes inside that arc.
  */
 export declare class FilePermissionRuleStoreProvider implements PermissionRuleStoreProvider {
     private readonly dir;
     private readonly onError?;
     private lock;
-    constructor(dir: string, onError?: ((message: string) => void) | undefined);
+    constructor(dir: string, onError?: ((message: string) => void) | undefined, opts?: {
+        /** The data root whose adoption marker gates construction (design/183 I6). Absent ⇒ no root gate. */
+        dataRoot?: string;
+    });
     /** Take the writer lock, once, on first use of a write face. Reading never calls this. */
     private acquireWriteLock;
     forPrincipal(principal: string | undefined): PermissionRuleStore;

package/dist/stores/file/permission-rule-store.js

@@ -4,6 +4,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { PERMISSION_RULE_WRITER, applySyncJoin, applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, foldDelta, } from "../../core/permission-rule-store.js";
 import { canonicalize } from "../../core/canonical-json.js";
 import { BootLock } from "./fs-atomic.js";
+import { assertAdoptionBootGate } from "./adoption/marker.js";
 const LOCAL_OWNER_FILE = "local-owner.json";
 const ADOPTION_FILE = "PERMISSION-RULES-ADOPTION.json";
 export function readRuleAdoptionFile(dir) {
@@ -298,9 +299,11 @@ export class FilePermissionRuleStoreProvider {
     dir;
     onError;
     lock;
-    constructor(dir, onError) {
+    constructor(dir, onError, opts) {
         this.dir = dir;
         this.onError = onError;
+        if (opts?.dataRoot !== undefined)
+            assertAdoptionBootGate(opts.dataRoot, "FilePermissionRuleStoreProvider");
     }
     acquireWriteLock = () => {
         if (this.lock !== undefined)

package/dist/stores/file/task-list-store.d.ts

@@ -1,2 +1,16 @@
 import type { TaskListStore } from "../../tools/task-list.js";
-export declare function createFileTaskListStore(root: string): TaskListStore;
+export declare function createFileTaskListStore(root: string, opts?: {
+    /**
+     * The DATA ROOT whose adoption marker gates construction (design/183 I6). Most of the file family
+     * takes the data root and derives `join(root, "<family>")` itself; this factory is one of the TWO
+     * faces that instead take a caller-chosen directory (the other being
+     * `FilePermissionRuleStoreProvider`, which takes a rule bucket) — here, the document's own
+     * directory. So when a deployment hands in a SUBDIRECTORY the I6 check would look for the marker
+     * inside that subdirectory, find nothing, and pass unconditionally: a gate that is always open
+     * (backlog #136⑦). Supply the data root here and the gate reads the anchor the root-taking faces
+     * read. Absent ⇒ the directory argument doubles as the anchor, which is exact when it IS the data
+     * root (the conventional wiring) and is the previous behavior otherwise; the adoption freeze note
+     * on `adoptLocalDataRoot` lists that default among the seams it does not cover.
+     */
+    dataRoot?: string;
+}): TaskListStore;

package/dist/stores/file/task-list-store.js

@@ -4,9 +4,9 @@ import { assertJsonMetadata, normalizeTaskShape } from "../../tools/task-list.js
 import { canonicalStoreKey, atomicWriteFile, ensureDir } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 const dirLocks = new Map();
-export function createFileTaskListStore(root) {
+export function createFileTaskListStore(root, opts) {
     const dir = resolve(root);
-    assertAdoptionBootGate(dir, "createFileTaskListStore");
+    assertAdoptionBootGate(opts?.dataRoot !== undefined ? resolve(opts.dataRoot) : dir, "createFileTaskListStore");
     const tmpDir = join(dir, "tmp");
     const path = join(dir, "task-list.json");
     ensureDir(dir);

package/dist/tools/fs/fs-shared.js

@@ -89,12 +89,19 @@ export function envErrorDetail(message) {
 }
 const announcedTimeoutConfig = new Set();
 function announceDiscardedTimeout(knob, raw, usedMs) {
-    if (!Number.isFinite(raw) || raw <= 0)
-        return;
-    const defect = bashTimeoutDefect(Math.floor(raw));
-    if (defect === undefined)
+    if (typeof raw === "string" && raw === "")
         return;
-    const line = `${knob}=${raw} was ignored — it ${defect}. Using ${usedMs}ms instead.`;
+    const n = typeof raw === "number" ? raw : Number(raw);
+    let line;
+    if (!Number.isFinite(n) || n <= 0) {
+        line = `${knob}=${String(raw)} was ignored — not a positive finite millisecond count. Using ${usedMs}ms instead.`;
+    }
+    else {
+        const defect = bashTimeoutDefect(Math.floor(n));
+        if (defect === undefined)
+            return;
+        line = `${knob}=${String(raw)} was ignored — it ${defect}. Using ${usedMs}ms instead.`;
+    }
     if (announcedTimeoutConfig.has(line))
         return;
     announcedTimeoutConfig.add(line);
@@ -126,11 +133,20 @@ export function resolveBashTimeoutCaps(opts) {
     if (opts?.bashDefaultTimeoutMs !== undefined)
         announceDiscardedTimeout("bashDefaultTimeoutMs", opts.bashDefaultTimeoutMs, defaultMs);
     else if (process.env.BASH_DEFAULT_TIMEOUT_MS !== undefined)
-        announceDiscardedTimeout("BASH_DEFAULT_TIMEOUT_MS", Number(process.env.BASH_DEFAULT_TIMEOUT_MS), defaultMs);
+        announceDiscardedTimeout("BASH_DEFAULT_TIMEOUT_MS", process.env.BASH_DEFAULT_TIMEOUT_MS, defaultMs);
     if (opts?.bashMaxTimeoutMs !== undefined)
         announceDiscardedTimeout("bashMaxTimeoutMs", opts.bashMaxTimeoutMs, maxMs);
     else if (process.env.BASH_MAX_TIMEOUT_MS !== undefined)
-        announceDiscardedTimeout("BASH_MAX_TIMEOUT_MS", Number(process.env.BASH_MAX_TIMEOUT_MS), maxMs);
+        announceDiscardedTimeout("BASH_MAX_TIMEOUT_MS", process.env.BASH_MAX_TIMEOUT_MS, maxMs);
+    const requestedCap = validTimeoutMs(opts?.bashMaxTimeoutMs) ?? validTimeoutMs(Number(process.env.BASH_MAX_TIMEOUT_MS));
+    if (requestedCap !== undefined && requestedCap < defaultMs) {
+        const knob = opts?.bashMaxTimeoutMs !== undefined ? "bashMaxTimeoutMs" : "BASH_MAX_TIMEOUT_MS";
+        const line = `${knob}=${requestedCap} is below the resolved default budget (${defaultMs}ms) — the ceiling was raised to ${maxMs}ms (the default always fits under the cap).`;
+        if (!announcedTimeoutConfig.has(line)) {
+            announcedTimeoutConfig.add(line);
+            console.warn(line);
+        }
+    }
     return { defaultMs, maxMs };
 }
 export function __resetBashTimeoutAnnouncements() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.24.0",
+  "version": "5.25.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",