@sema-agent/core 7.1.0 → 7.2.0

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

@@ -765,7 +765,12 @@ export type PendingAction = {
      *  order (redemption TICKETS are keyed on the consent record's flat CANDIDATE list instead —
      *  a chosen offer is redeemed via `redeemRuleBatch`), per-element parse with single-row
      *  degrade on an unknown `kind` and
-     *  original-index preservation. The park→resume redemption chain walks the same consent
+     *  original-index preservation. design/382 B3: a batch offer's members are the
+     *  {@link import("./permission-rule-model.js").RuleOfferBatchMember} discriminated union
+     *  (`command` | `directoryRead`), and the member-level degrade is the union's own normative
+     *  arm — an unknown MEMBER kind drops the WHOLE batch offer (never one member: a conjunction
+     *  silently one member short renders "yes to N" as "yes to N−1"), while the sibling single
+     *  offers stay rendered. The park→resume redemption chain walks the same consent
      *  protocol as the synchronous card — there is no second form. */
     ruleOffers?: readonly import("./permission-rule-model.js").RuleOffer[];
     /** #490 修② (additive; no checkpoint-version bump — the `previewWithheld`/`hasBidiControls`
@@ -777,7 +782,11 @@ export type PendingAction = {
      *  the tool's own mandate marks, a hook-raised ask, an ancestor's authority, or — #502 — a
      *  demotion this CALL's reversibility probe declared structural, which for the built-in shell
      *  probe means a read outside the directories the session declared; an inbox must NOT point at
-     *  rule-writing on this arm, nor at a directory grant, which does not exist in this version),
+     *  rule-writing on this arm — "allow rules silence the classifier's questions, never a mandated
+     *  one" — nor at a directory grant: the subpath-rule family exists, but the out-of-root arm has
+     *  no clearing configuration in this version, so a grant minted in answer to this line would
+     *  never take effect where it was minted; confirming the call is the whole of what a person can
+     *  do about it),
      *  `"shadowed"` (a rule the person already wrote is
      *  speaking and does not clear it), `"lane_cannot_speak"` (this card has no rule to offer — the
      *  grammar has no text for the command, or the card's array-order contract declines to present
@@ -786,6 +795,14 @@ export type PendingAction = {
      *  "there are offers" and the structural doors (no lane wired, another tool, a task that cannot
      *  hold a rule) — so read presence. See the synchronous seat's doc for the full contract. */
     ruleOffersAbsence?: "mandated" | "lane_cannot_speak" | "shadowed";
+    /** design/382 §2.4 (adversarial-review r3; additive — no checkpoint-version bump, the
+     *  `previewWithheld` precedent: an optional field an older reader ignores and the resume
+     *  path never reads) — the PARK twin of `AskRequest.execCwd`, minted by the SAME factory as
+     *  {@link ruleOffers}: the relative-cd resolution base those offers were minted with (the
+     *  live tracked cwd at park time). An approval inbox reconstructing the authoritative
+     *  consent record threads it as `prepareCardApproval`'s `execCwd`. Present only beside
+     *  {@link ruleOffers} when the run had a tracked cwd; echo-only, never a control input. */
+    execCwd?: string;
     /**
      * design/80 D-1 §2 (slice 1a.2): the server-minted **opaque** boundInputHash of {@link args} — a
      * SHA-256 (hex) via {@link import("./canonical-json.js").boundInputHashOf}, computed ONCE here at
@@ -1483,6 +1500,49 @@ export interface ResolveExpectation {
     /** The monotonic {@link Checkpoint.rev} the caller observed at `get()` (absent rev ⇒ legacy `0`). */
     rev: number;
 }
+/** design/384 slice 2 / S-25-R1 — the terminal intents a claim can carry. Deliberately the
+ *  TERMINAL pair only: `resolve` and `expire` are the two verbs that race one pending row to
+ *  its end (the design/51 fence law). `reopen` (resolved→pending) is not terminal and `reap`
+ *  is a bulk sweep — both stay on their own verbs. */
+export type TerminalClaimIntent = {
+    kind: "resolve";
+    outcome: ResumeOutcome;
+    expect?: ResolveExpectation;
+} | {
+    kind: "expire";
+};
+/** design/384 slice 2 / S-25-R1 — the single-round-trip answer: EITHER the claim won, OR it lost and
+ *  the SAME atomic operation reports what the row is now. `current` reuses the row's own vocabulary
+ *  (status / rev / resolvedOutcome) — no new value domain. `status:"pending"` on a loss is the OCC
+ *  arm only (`expect.rev` mismatch): the row is still open — re-get + re-validate, zero backoff (a
+ *  cleanly KNOWN state is never "unknown"). */
+export type TerminalClaimOutcome = {
+    claimed: true;
+} | {
+    claimed: false;
+    current: {
+        status: "pending" | "resolved" | "expired";
+        /** `(cp.rev ?? 0)` — the absent-rev-reads-as-0 rule the OCC key already uses. */
+        rev: number;
+        /** Row-field PASSTHROUGH on every present status: the row PRESERVES it across `reopen`
+         *  (resolved→pending rows carry it), `expire` never clears it, and a winnerless resolve
+         *  (resource/wake/task_done) does not overwrite an older value — so even
+         *  `(status:"resolved", outcome present)` is only "the row is resolved AND this is its
+         *  LAST RECORDED decision winner", never a store-level guarantee that THIS resolve minted
+         *  it. Interpreting the pair as a current decision is the CALLER's discipline (the
+         *  runner's gate-kind matching; a single-decision row schema like a deployment's ask
+         *  rows). See {@link CheckpointStore.claimTerminal} law 6. */
+        resolvedOutcome?: ResolvedOutcome;
+    }
+    /** Row missing — OR wrong scope: the CAS predicate is the shared REF-A4 row match
+     *  ({@link checkpointRowMatches}), and a wrong-scope claim must lose WITHOUT reporting the
+     *  row's truth (multi-tenant isolation: cross-scope truth in a loss answer would be a read
+     *  bypass of the scope WHERE). Absent is a KNOWN state (zero backoff): expire intent ⇒ moot;
+     *  resolve intent ⇒ the caller's typed not-found path, no retry. */
+     | {
+        status: "absent";
+    };
+};
 /** A persisted suspension point: enough to resume a task on any replica. `status` drives the 3-state
  *  machine (pending → resolved | expired) that makes resume idempotent (§5). */
 export interface Checkpoint {
@@ -2447,6 +2507,78 @@ export interface CheckpointStore {
      * `resolve`/`reap`.
      */
     expire(token: CheckpointToken, scope: string): Promise<boolean>;
+    /**
+     * design/384 slice 2 / S-25-R1 — the ATOMIC terminal claim: "win the terminal race" and "read the
+     * truth on a loss" as ONE store operation. OPTIONAL, probed by presence (the `listByScope`
+     * precedent); the runner's resume chain adopts it when present (the loser triages off `current`
+     * with zero second read) and keeps the two-step resolve+get path otherwise. This JSDoc is the
+     * single normative statement of the claim law — `put`'s create-once/read-back three-state and the
+     * suspend saga's commit discipline are the same single-winner law's PUT variant and cross-reference
+     * here rather than restate.
+     *
+     * The laws:
+     *  1. **Atomicity** — the win/lose decision and the loser's `current` reading MUST come from the
+     *     same atomic unit (one `UPDATE … RETURNING` / one transaction / one single-threaded map
+     *     operation). A settle is self-sufficient: a caller holding `claimed:false` NEVER needs a
+     *     second read to act.
+     *  2. **CAS-predicate identity** — `kind:"resolve"`'s win IS {@link resolve}'s win (same WHERE:
+     *     token+scope+pending[+rev]; a win records the winner via {@link winnerFromOutcome} and bumps
+     *     `rev` identically); `kind:"expire"` IS {@link expire}. ONE-MACHINE OBLIGATION: a store that
+     *     provides `claimTerminal` must route all three verbs through one protected write path
+     *     (resolve/expire implemented over claimTerminal, or all three over one shared CAS kernel) —
+     *     two predicates would be a drift window, and this law forbids it.
+     *  3. **Timeout posture** — no timeout parameter here: transport deadlines belong to the backend,
+     *     wall-clock backstops to the caller. The contract states exactly two halves: a SETTLE carries
+     *     the truth; a REJECT proves NOTHING (the row may already be terminal — the caller must not
+     *     proclaim a terminal state from its own intent; fail-closed projection of "still pending"
+     *     stays legal). A LATE settle is as self-sufficient as a prompt one — an answer arriving after
+     *     the caller's own deadline still carries the true decision, so the caller settles on truth
+     *     with zero follow-up reads.
+     *  4. **Recovery discipline — truth is comparable, ownership is not.** A bounded retry after a
+     *     reject re-sends the SAME claim (the CAS is idempotent). When the retry answers
+     *     `claimed:false`, `current` tells the caller what the row IS — never WHOSE claim made it so:
+     *     two claimants writing byte-identical outcomes cannot be told apart by content, and
+     *     {@link ResolvedOutcome} carries no claimant identity. Two consumption classes follow:
+     *     IDEMPOTENT consumption (settle on the recorded truth — who wrote it is irrelevant) may use
+     *     `claimed:false` + the recorded decision directly; RESPONSIBILITY-bearing consumption (only
+     *     the winner may execute the pending action — the runner's resume) must NEVER self-attribute
+     *     after ambiguity: treat it as a loss (the `already_resolved` shape, nothing executed) — the
+     *     same law as the existing crash-after-CAS pin ("retry sees resolved and does NOT re-execute"),
+     *     which this claim does not weaken. There is NO replay arm: a burned approval takes the
+     *     existing reopen/re-ask compensation route, and this contract opens no "assume approved and
+     *     replay" door. (A claimant-identity field would be a schema change; not here.) Expire-class
+     *     claims are naturally idempotent (expire-by-me ≡ expire-by-reaper; no attribution needed).
+     *  5. **A loss reading is a consistent snapshot at the claim's linearization point, not an eternal
+     *     truth** — `resolved` can be reopened back to pending, so "settle is self-sufficient" scopes
+     *     to the disposition of THIS loss (settle on truth / re-validate on OCC / close on absent),
+     *     never to the row's future; a caller needing current state later still `get`s. `current` is a
+     *     projection, not the row (no state / pendingAction payloads).
+     *  6. **`resolvedOutcome` reads as the row field it is, passed through verbatim** — the persisted
+     *     winner record: written only by decision-bearing resolves ({@link winnerFromOutcome} answers
+     *     `undefined` for resource/wake/task_done), PRESERVED by `reopen`, not cleared by later
+     *     winnerless resolves. In a loss answer it means "the row's last recorded decision winner",
+     *     NOT "the payload of the claim that beat you"; absence means "no decision winner recorded",
+     *     not "the winner had no content". For has-a-human-decided consumption this is exactly the
+     *     needed semantics; "who beat me / with what" is claimant-identity territory this contract
+     *     does not mint.
+     *  7. **No declaration bit** — presence of the method IS the contract (an implementation
+     *     obligation at the same level as `resolve`'s CAS promise); no `redecision`-style declaration,
+     *     because that family guards against a stub satisfying a type, and a `claimTerminal` stub has
+     *     no such shape — the return form itself carries the obligation.
+     *
+     * Deployment correspondence (an ask-row store implementing the same law maps its own vocabulary):
+     * token+scope ↔ the ask id (+ its run binding); pending/resolved/expired ↔ the ask row's
+     * open/decided/terminal states; intent `resolve(outcome)` ↔ the human-decision verb; intent
+     * `expire` ↔ the expire/cancel verbs; the `claimed:false → (status, resolvedOutcome)` PAIRED read
+     * ↔ the decided row's recorded decision (reading the pair as the CURRENT decision is the CALLER's
+     * discipline here — gate-kind matching — while a single-decision row schema satisfies it
+     * structurally). Two shape notes carried from that correspondence: a store whose rows have NO
+     * OCC/rev axis simply never produces the `status:"pending"` loss arm (an honestly absent arm is
+     * correct — do not fabricate a rev); a store whose domain has NO reopen verb enjoys stronger
+     * monotonicity than law 5 assumes — consumption written against law 5's weaker snapshot reading
+     * stays correct there unchanged.
+     */
+    claimTerminal?(token: CheckpointToken, scope: string, intent: TerminalClaimIntent): Promise<TerminalClaimOutcome>;
     /**
      * CAS-expire `pending` checkpoints in `scope` whose `deadline` has passed (`deadline <= cutoff`):
      * `pending → expired`. Returns the count expired (for metrics). Idempotent across replicas (DB
@@ -2589,7 +2721,14 @@ export type CheckpointFaultMode =
 "resolve-after-commit"
 /** `resolve` throws *before* the CAS — simulates a crash before the commit; the row stays `pending`
  *  so a retry can still win it. */
- | "resolve-before-commit";
+ | "resolve-before-commit"
+/** design/384 slice 2 — `claimTerminal` wins its claim (the commit lands) then throws before the
+ *  caller is acked: the claim-law recovery scenario (law 3/4 — a reject proves nothing; the retry's
+ *  loss answer carries the truth and a responsibility-bearing consumer must NOT self-attribute). */
+ | "claim-after-commit"
+/** design/384 slice 2 — `claimTerminal` throws *before* its CAS: the row is untouched (still
+ *  pending), so a retry can still win the same claim. */
+ | "claim-before-commit";
 /**
  * Default in-process {@link CheckpointStore}. Single-instance / tests only — it does NOT survive a
  * restart or span replicas, so it cannot deliver the cross-process guarantee a durable backend does.
@@ -2613,7 +2752,54 @@ export declare class InMemoryCheckpointStore implements CheckpointStore {
     private fault;
     put(token: CheckpointToken, cp: Checkpoint): Promise<void>;
     get(token: CheckpointToken): Promise<Checkpoint | null>;
+    /** The loser's single-round-trip reading (claim law 1): what the row IS, in its own vocabulary —
+     *  or `absent` for a missing row AND a wrong-scope row alike (the isolation rule: cross-scope truth
+     *  in a loss answer would be a read bypass of the scope WHERE). Cloned projection, never a live ref. */
+    protected claimLossFrom(cp: Checkpoint | undefined, scope: string): TerminalClaimOutcome;
+    /**
+     * The ONE protected write core for the terminal-resolve claim — `resolve` and
+     * `claimTerminal({kind:"resolve"})` both run exactly this (claim law 2's one-machine obligation:
+     * one predicate, one commit, no drift window). Single-threaded JS makes the check + flip atomic; a
+     * durable backend folds the same predicate into its CAS WHERE clause.
+     *
+     * ORDER (design/384 slice 2, healing the pre-existing resolve shape): the winner is derived and
+     * CLONED — the point where an uncloneable `updatedInput` says so — BEFORE any field is written, and
+     * the commit is then one uninterrupted write group (status+rev+winner+reopenReason). The old order
+     * cloned AFTER the status/rev flip, so an uncloneable winner threw with the row already resolved
+     * and NO winner recorded; now the same throw leaves the row byte-identical (still pending) — the
+     * claim REJECTS (a reject proves nothing, law 3) instead of half-committing.
+     */
+    protected claimResolveCore(token: CheckpointToken, scope: string, outcome: ResumeOutcome, expect?: ResolveExpectation): TerminalClaimOutcome;
+    /** The one protected write core for the terminal-expire claim — `expire` and
+     *  `claimTerminal({kind:"expire"})` both run exactly this (claim law 2, same as the resolve core). */
+    protected claimExpireCore(token: CheckpointToken, scope: string): TerminalClaimOutcome;
     resolve(token: CheckpointToken, scope: string, outcome: ResumeOutcome, expect?: ResolveExpectation): Promise<boolean>;
+    /** design/384 slice 2 — the atomic terminal claim (the interface JSDoc is the law's single
+     *  normative statement). Implemented OVER the same protected cores `resolve`/`expire` run, which is
+     *  the one-machine obligation discharged rather than restated. ONE fault plane with the one
+     *  machine: a fault armed under the `resolve-*` names fires on the claim route of the SAME CAS too
+     *  (`kind:"resolve"` only — expire never consumed resolve faults), so a crash simulation pinned
+     *  against the two-step verb keeps firing byte-identically when the runner adopts the claim form.
+     *
+     *  INHERITANCE OBLIGATION (a subclass provides `claimTerminal` whether it means to or not): a
+     *  subclass that overrides `resolve`/`expire` to wrap the CAS (audit hooks, fault injection,
+     *  interleave fixtures) must override THIS method consistently. Overriding the `protected` cores
+     *  (`claimResolveCore`/`claimExpireCore`) instead covers every COMMIT on every route — the cores
+     *  are the one write core all three verbs share — but NOT every ATTEMPT: `resolve`/`expire`
+     *  evaluate the shared row predicate themselves and return `false` without entering a core when
+     *  the row is not pending (missing, another scope, already terminal), while this claim route
+     *  enters the core unconditionally and takes its loss reading from it. A core override therefore
+     *  sees every winning claim and every OCC loss, but a row-predicate loss only when it arrived via
+     *  the claim route; a hook that must record EVERY attempt, including those losses, on EVERY route
+     *  wraps the three public verbs consistently. The same applies to a DELEGATING WRAPPER (Proxy / hand-built object)
+     *  that forwards `claimTerminal` while hooking only `resolve`: forwarding IS providing, and the
+     *  claim route is then the one that actually runs. A resolve-only wrap goes dark the moment a
+     *  consumer prefers the claim route (the runner's resume does), which is a one-machine-law
+     *  violation the SUBCLASS created — the base class cannot route through the public verbs
+     *  instead, because an `await` between the CAS and the loss reading would break the law-1
+     *  atomic unit this method exists to provide. (A wrapper that OMITS the member opts out
+     *  cleanly: the consumer's presence probe then keeps the two-step path, hooks intact.) */
+    claimTerminal(token: CheckpointToken, scope: string, intent: TerminalClaimIntent): Promise<TerminalClaimOutcome>;
     reopen(token: CheckpointToken, scope: string, reason: ReopenReason): Promise<boolean>;
     setPendingSteer(token: CheckpointToken, scope: string, steer: PendingSteerInput): Promise<boolean>;
     expire(token: CheckpointToken, scope: string): Promise<boolean>;

package/dist/core/checkpoint-store.js

@@ -527,29 +527,71 @@ export class InMemoryCheckpointStore {
         const cp = this.cps.get(token);
         return cp ? structuredClone(cp) : null;
     }
-    async resolve(token, scope, outcome, expect) {
-        if (this.fault === "resolve-before-commit") {
-            this.fault = null;
-            throw new Error("injected fault: resolve before commit");
-        }
+    claimLossFrom(cp, scope) {
+        if (cp === undefined || cp.scope !== scope)
+            return { claimed: false, current: { status: "absent" } };
+        return {
+            claimed: false,
+            current: {
+                status: cp.status,
+                rev: cp.rev ?? 0,
+                ...(cp.resolvedOutcome !== undefined ? { resolvedOutcome: structuredClone(cp.resolvedOutcome) } : {}),
+            },
+        };
+    }
+    claimResolveCore(token, scope, outcome, expect) {
         const cp = this.cps.get(token);
         if (!checkpointRowMatches(cp, scope, "pending")) {
-            return false;
+            return this.claimLossFrom(cp, scope);
         }
         if (!checkpointOccMatches(cp, expect)) {
-            return false;
+            return this.claimLossFrom(cp, scope);
         }
+        const winner = winnerFromOutcome(outcome);
+        const winnerClone = winner ? structuredClone(winner) : undefined;
         cp.status = "resolved";
         cp.rev = (cp.rev ?? 0) + 1;
-        const winner = winnerFromOutcome(outcome);
-        if (winner)
-            cp.resolvedOutcome = structuredClone(winner);
+        if (winnerClone)
+            cp.resolvedOutcome = winnerClone;
         cp.reopenReason = undefined;
-        if (this.fault === "resolve-after-commit") {
+        return { claimed: true };
+    }
+    claimExpireCore(token, scope) {
+        const cp = this.cps.get(token);
+        if (!checkpointRowMatches(cp, scope, "pending")) {
+            return this.claimLossFrom(cp, scope);
+        }
+        cp.status = "expired";
+        return { claimed: true };
+    }
+    async resolve(token, scope, outcome, expect) {
+        if (this.fault === "resolve-before-commit") {
+            this.fault = null;
+            throw new Error("injected fault: resolve before commit");
+        }
+        if (!checkpointRowMatches(this.cps.get(token), scope, "pending")) {
+            return false;
+        }
+        const out = this.claimResolveCore(token, scope, outcome, expect);
+        if (out.claimed && this.fault === "resolve-after-commit") {
             this.fault = null;
             throw new Error("injected fault: resolve after commit");
         }
-        return true;
+        return out.claimed;
+    }
+    async claimTerminal(token, scope, intent) {
+        if (this.fault === "claim-before-commit" || (intent.kind === "resolve" && this.fault === "resolve-before-commit")) {
+            const name = this.fault === "claim-before-commit" ? "claim" : "resolve";
+            this.fault = null;
+            throw new Error(`injected fault: ${name} before commit`);
+        }
+        const out = intent.kind === "resolve" ? this.claimResolveCore(token, scope, intent.outcome, intent.expect) : this.claimExpireCore(token, scope);
+        if (out.claimed && (this.fault === "claim-after-commit" || (intent.kind === "resolve" && this.fault === "resolve-after-commit"))) {
+            const name = this.fault === "claim-after-commit" ? "claim" : "resolve";
+            this.fault = null;
+            throw new Error(`injected fault: ${name} after commit`);
+        }
+        return out;
     }
     async reopen(token, scope, reason) {
         const cp = this.cps.get(token);
@@ -571,12 +613,10 @@ export class InMemoryCheckpointStore {
         return true;
     }
     async expire(token, scope) {
-        const cp = this.cps.get(token);
-        if (!checkpointRowMatches(cp, scope, "pending")) {
+        if (!checkpointRowMatches(this.cps.get(token), scope, "pending")) {
             return false;
         }
-        cp.status = "expired";
-        return true;
+        return this.claimExpireCore(token, scope).claimed;
     }
     async reap(scope, cutoff) {
         let n = 0;

package/dist/core/hooks.d.ts

@@ -1220,13 +1220,14 @@ export interface ToolGateInput {
     /**
      * design/384 slice 1 — the PER-CALL abort signal, carried in from the `tool_call` hook event's
      * own `signal` seat (the loop's turn-scoped controller; the run abort is composed into it). The
-     * gate itself never awaits on it — it hands the signal verbatim to the three synchronous-wait
-     * seats below (`adjudicate`, `resolveAsk`, `resolveContentAsk`) as their optional trailing
-     * argument, and the Runner's closures compose it with the run signal so a turn interrupt (bare
-     * halt / steer-now) releases the wait. Absent (a host driving the gate directly, or an unthreaded
-     * emit) ⇒ every seat is invoked exactly as before — same arity, no trailing `undefined` (the
-     * threading is a conditional invocation) — and waits stay bound to the run signal alone: the
-     * historical shape, byte-identical.
+     * gate itself never awaits on it — it hands the signal verbatim to the four consuming seats
+     * below (`adjudicate`, `resolveAsk`, `resolveContentAsk`, and — slice 2 — `suspendAsk`, whose
+     * park closure composes it into the halt×park fence) as their optional trailing argument, and
+     * the Runner's closures compose it with the run signal so a turn interrupt (bare halt /
+     * steer-now) releases the wait — or, on the durable leg, makes the park concede. Absent (a host
+     * driving the gate directly, or an unthreaded emit) ⇒ every seat is invoked exactly as before —
+     * same arity, no trailing `undefined` (the threading is a conditional invocation) — and waits
+     * stay bound to the run signal alone: the historical shape, byte-identical.
      */
     callSignal?: AbortSignal;
     /** The combined tool-policy check (abort-bound), or undefined when no policy is wired (→ allow).
@@ -1314,7 +1315,13 @@ export interface ToolGateInput {
      *  rule the lane would then refuse to honor. APPENDED at the tail for the reason its neighbour
      *  states — every parameter here is positional — and typed `boolean` so a mis-bind against the two
      *  trailing `string` seats is a compile error rather than a silent re-binding. */
-    probeMandated?: boolean) => Promise<ToolGateResult["suspend"] | ParkAttemptFailed | undefined>;
+    probeMandated?: boolean, 
+    /** design/384 slice 2 — {@link ToolGateInput.callSignal}, threaded VERBATIM as a CONDITIONAL
+     *  trailing argument (the slice-1 arity discipline: absent means the historical arity, never a
+     *  trailing `undefined`). The park closure composes it with the run signal into the halt×park
+     *  fence's cut signal; an implementation that ignores it keeps the run-level binding. APPENDED at
+     *  the tail like its neighbours, and typed `AbortSignal` so a mis-bind is a compile error. */
+    callSignal?: AbortSignal) => 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,

package/dist/core/hooks.js

@@ -859,7 +859,8 @@ 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), decision.action === "ask" ? decision.persistedRuleShadowed : undefined, decision.action === "ask" ? decision.decisionReason : undefined, decision.action === "ask" ? decision.probeReason : undefined, decision.action === "ask" ? decision.probeCause : undefined, decision.action === "ask" ? decision.segmentCoverage : undefined, decision.action === "ask" ? decision.matchedAskRule : undefined, decision.action === "ask" ? decision.probeMandated : undefined);
+            const parkArgs = [req, currentInput, safety, undefined, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined, decision.action === "ask" ? decision.decisionReason : undefined, decision.action === "ask" ? decision.probeReason : undefined, decision.action === "ask" ? decision.probeCause : undefined, decision.action === "ask" ? decision.segmentCoverage : undefined, decision.action === "ask" ? decision.matchedAskRule : undefined, decision.action === "ask" ? decision.probeMandated : undefined];
+            const suspended = await (callSignal !== undefined ? suspendAsk(...parkArgs, callSignal) : suspendAsk(...parkArgs));
             if (suspended) {
                 if ("parkFailed" in suspended)
                     parkFailed = suspended.parkFailed;
@@ -878,7 +879,8 @@ 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), decision.action === "ask" ? decision.persistedRuleShadowed : undefined, decision.action === "ask" ? decision.decisionReason : undefined, decision.action === "ask" ? decision.probeReason : undefined, decision.action === "ask" ? decision.probeCause : undefined, decision.action === "ask" ? decision.segmentCoverage : undefined, decision.action === "ask" ? decision.matchedAskRule : undefined, decision.action === "ask" ? decision.probeMandated : undefined);
+                    const parkArgs = [req, currentInput, safety, true, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined, decision.action === "ask" ? decision.decisionReason : undefined, decision.action === "ask" ? decision.probeReason : undefined, decision.action === "ask" ? decision.probeCause : undefined, decision.action === "ask" ? decision.segmentCoverage : undefined, decision.action === "ask" ? decision.matchedAskRule : undefined, decision.action === "ask" ? decision.probeMandated : undefined];
+                    const suspended = await (callSignal !== undefined ? suspendAsk(...parkArgs, callSignal) : suspendAsk(...parkArgs));
                     if (suspended) {
                         if ("parkFailed" in suspended)
                             parkFailed = suspended.parkFailed;
@@ -910,7 +912,8 @@ export async function runToolGate(input) {
                 askDenyResolution = resolved.resolution;
             decision = resolved;
             if (resolved.action === "deny" && resolved.approverUnavailable === true && suspendAsk && parkFailed === undefined) {
-                const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(askBeforeResolve), askBeforeResolve.action === "ask" ? askBeforeResolve.persistedRuleShadowed : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.decisionReason : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.probeReason : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.probeCause : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.segmentCoverage : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.matchedAskRule : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.probeMandated : undefined);
+                const parkArgs = [req, currentInput, safety, true, realApprovalOf(askBeforeResolve), askBeforeResolve.action === "ask" ? askBeforeResolve.persistedRuleShadowed : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.decisionReason : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.probeReason : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.probeCause : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.segmentCoverage : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.matchedAskRule : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.probeMandated : undefined];
+                const suspended = await (callSignal !== undefined ? suspendAsk(...parkArgs, callSignal) : suspendAsk(...parkArgs));
                 if (suspended) {
                     if ("parkFailed" in suspended)
                         parkFailed = suspended.parkFailed;

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

@@ -27,7 +27,7 @@
  * this by editing a file backend's file. That is the settings-file trust model, stated rather than
  * defended against: for a file backend, host = user, no more and no less.
  */
-import { type RuleOffer, type RuleRejectCode, type RuleScope, type RuleDot } from "./permission-rule-model.js";
+import { type EditedRuleBreadthWarning, type UncoveredSegmentDetail, type RuleOffer, type RuleRejectCode, type RuleScope, type RuleDot } from "./permission-rule-model.js";
 import type { PermissionRuleStoreProvider, RuleOwner } from "./permission-rule-store.js";
 import type { SessionRuleOverlay } from "./permission-rule-session.js";
 /** One candidate rule inside an approval record: the exact text and where it would apply. */
@@ -48,10 +48,16 @@ export type RuleApprovalKind = "card" | "import" | "starter";
  *  · `kind: "batch"` — a CONJUNCTION batch: confirming it is one yes to ALL of `candidates` at
  *    once, with no per-member sub-selection. On a CARD record the batch carries two MINT-TIME
  *    facts that cannot be re-derived from candidate texts and therefore must be stored:
- *    `segments` (each member's source segment, index-aligned with `candidates`) and
+ *    `segments` (each member's source segment, index-aligned with `candidates`),
  *    `uncoveredSegments` (the honest surplus count the wire offer disclosed, judged on the
- *    prepare-time coverage snapshot). On an import/starter record there is no compound command
- *    and no coverage snapshot, so both fields must be ABSENT — honest absence, never an
+ *    prepare-time coverage snapshot) and — since `schema: 3` (design/382 §3.5) — `uncoveredDetail`,
+ *    one reason row per counted segment in segment order: WHY each stayed uncovered is a mint-time
+ *    fact that cannot be re-derived from candidate texts, so it must be stored or a crash/reload
+ *    rebuild would render a card that says less than the first render did (record-is-what-you-see).
+ *    REQUIRED on a card batch, all three: "optional, validated when present" is the
+ *    silent-absence-passes shape this record form already refused once, and it is not re-imported
+ *    for the new seat. On an import/starter record there is no compound command
+ *    and no coverage snapshot, so all three fields must be ABSENT — honest absence, never an
  *    empty-string stand-in. The read-side integrity checks refuse either direction's violation.
  *
  * Cardinality: a batch references 1..N candidates where N is the record's own candidate count.
@@ -67,6 +73,7 @@ export type RuleOffer2 = {
     readonly candidates: readonly number[];
     readonly segments?: readonly string[];
     readonly uncoveredSegments?: number;
+    readonly uncoveredDetail?: readonly UncoveredSegmentDetail[];
 };
 /** A durable record of one pending/settled human decision about minting rules.
  *
@@ -81,12 +88,16 @@ export interface RuleApprovalRecord {
     /** Structural owner (additive). Absent on every record a v1 tree minted. */
     owner?: RuleOwner;
     /**
-     * design/375 §4.5 — the record-form version stamp. A stored row WITHOUT it predates this form;
-     * such a row confirms and redeems nothing (refused loudly, `record_schema_stale`) and is never
-     * read through a compatibility shim: pending approvals are short-lived, and re-triggering the
-     * command draws a fresh card. Stores hand pre-form rows back as {@link StaleRuleApprovalRecord}.
+     * design/375 §4.5 — the record-form version stamp. A stored row WITHOUT it — or carrying an older
+     * number — predates this form; such a row confirms and redeems nothing (refused loudly,
+     * `record_schema_stale`) and is never read through a compatibility shim: pending approvals are
+     * short-lived, and re-triggering the command draws a fresh card. Stores hand pre-form rows back
+     * as {@link StaleRuleApprovalRecord}. `3` (design/382 §3.5, B8/B7): the card batch's
+     * `uncoveredDetail` seat became REQUIRED and `edited.warnings` became storable — a `schema: 2`
+     * row is read back stale exactly like the pre-stamp rows before it (the short-lived-pending
+     * bargain, unchanged).
      */
-    schema: 2;
+    schema: 3;
     kind: RuleApprovalKind;
     state: "pending" | "approved" | "redeemed";
     candidates: RuleCandidate[];
@@ -137,18 +148,26 @@ export interface RuleApprovalRecord {
      * same bytes); `at` is when the edit landed. Present ⇒ the record's chosen offer is the single
      * offer minted over this candidate (the append, the offer and the choice are one CAS write).
      * Absent on every card settled through an engine candidate.
+     *
+     * `warnings` (design/382 §3.3-5) — the BREADTH warning codes the text gates raised on this edit,
+     * written in the same CAS that settles it: "the width was named before the yes" becomes a fact the
+     * record itself carries, auditable after any crash or upgrade. Optional; present only when a
+     * warning was raised, and when present it is an array from the closed code set (the read-side
+     * integrity gate refuses anything else). Codes only — the sentences are derivable from the
+     * canonical rule text and are deliberately not stored (no second copy to drift).
      */
     edited?: {
         index: number;
         text: string;
         at: string;
+        warnings?: readonly EditedRuleBreadthWarning["code"][];
     };
     /** Dots already minted for this record, keyed by candidate index — the replay anchor. */
     redeemedDots?: Record<number, RuleDot>;
 }
 /**
  * design/375 §4.5 — the minimal ENVELOPE a store hands back for a durable row that predates the
- * `schema: 2` record form. A typed read cannot honestly return such a row as a
+ * CURRENT (`schema: 3`) record form. A typed read cannot honestly return such a row as a
  * {@link RuleApprovalRecord}, and dropping it at the store layer would misreport "stale" as
  * corruption — so the store contract is this variant instead: `staleSchema: true` plus the
  * IDENTITY fields, which are spelled the same way in every version and therefore safe to read.
@@ -209,6 +228,14 @@ export interface RuleConsentDeps {
      * coverage reads see no session rows — both fail toward asking.
      */
     sessionRules?: SessionRuleOverlay;
+    /**
+     * design/382 §2.4-6 — the deployment's sensitive-read negative control for the directoryRead MINT
+     * floor, same-source with its compiled read-deny judge (`(d) => readDeny.matchPath(d) !== null` is
+     * the canonical wiring). Consulted only when a card would PROPOSE a directory authorization from a
+     * cd segment — never by the explicit-consent doors (hand-written, import), which carry their own
+     * preview and validation. Absent ⇒ the engine's built-in default deny table stands in (refusal-only).
+     */
+    deniesDirectoryRead?: (directory: string) => boolean;
 }
 /** In-memory approval records — the test backend and the reference CAS semantics, the stale-row
  *  envelope read included. */
@@ -297,6 +324,17 @@ export declare function prepareCardApproval(opts: {
      * leans wide — the over-offer direction, which redemption's per-rule validation keeps safe.
      */
     cwd?: string;
+    /**
+     * design/382 §2.4 (adversarial-review r2) — the EXECUTION working directory of the adjudicated
+     * call: the live tracked cwd the shell will resolve a relative `cd ./x` against, threaded by the
+     * caller exactly like `cwd` (the runner's ask-projection seat threads its `handsCwdRef.current`;
+     * a host preparing cards for its own calls threads whatever base those calls execute under).
+     * ONLY the relative-cd resolution reads it; scope eligibility and the derived project scope stay
+     * on `cwd`. Absent ⇒ `cwd` is the base (the single-value deployment, where the two coincide).
+     * Present and DIFFERENT, it is what keeps this durable consent path and the advisory ask-time
+     * projection minting the SAME directory member — two faces reading one world.
+     */
+    execCwd?: string;
     deps: RuleConsentDeps;
 }): Promise<{
     approvalId: string;
@@ -346,7 +384,7 @@ export declare function confirmRuleApproval(opts: {
 /** Why a confirmation did not land. A closed set so a host can branch (re-present, re-fetch, give up).
  *  The two `record_*` members past `record_not_found` are the durable-row gates (design/375 §4.5/§4.7),
  *  disclosed to the record's own owner only — a non-owner gets `record_not_found` for every row:
- *   - `"record_schema_stale"` — the record predates the `schema: 2` form; the decision it carried
+ *   - `"record_schema_stale"` — the record predates the current (`schema: 3`) form; the decision it carried
  *     is void, and the recovery path is re-triggering the command for a fresh card (no
  *     compatibility read, no migration — `detail.message` says so);
  *   - `"record_malformed"` — the record's offer structure failed the read-side integrity checks
@@ -394,6 +432,16 @@ export type ConfirmResult = {
 export type EditedRuleTextPrecheck = {
     ok: true;
     canonicalRule: string;
+    /**
+     * design/382 §3.3-5 — BREADTH notes about the accepted rule (additive; absent = nothing to
+     * say). A warning is never a refusal: the muscle-memory wide forms are legal (§3.4), and this
+     * seat is what makes accepting one an informed act. Rendering them beside the input line is
+     * the surface's duty (the engine cannot force a display); what the ENGINE guarantees is the
+     * durable half — a confirmation through the edit arm writes the hit codes into the record
+     * (`edited.warnings`), so "the width was named before the yes" is an auditable fact. The
+     * confirmation result deliberately does NOT repeat them (one fact, one loud place).
+     */
+    warnings?: readonly EditedRuleBreadthWarning[];
 } | {
     ok: false;
     code?: RuleRejectCode;
@@ -483,19 +531,20 @@ export interface ImportPreview {
         reason: string;
     }>;
     /**
-     * #490 件4 — the entries whose SPELLING was rewritten on the way in, `from` as the settings file
-     * writes it and `to` as this lane will hold it (`Bash(npm run *)` → `Bash(npm run:*)`).
-     *
-     * Exactly ONE row per candidate the translation produced, in candidate order, carrying that
-     * candidate's `scope`. The scope is load-bearing rather than decoration: the same file line can
-     * appear in two layers and become two candidates in two scopes, and a report keyed on the text alone
-     * would show one row for two consents (independent-review finding — the row count and the candidate
-     * count must be readable against each other).
+     * ALWAYS EMPTY in this version — a compatibility seat, kept on the wire shape so an existing reader
+     * keeps finding the key (removing a wire field would break readers for no gain).
      *
-     * Always present, empty when nothing was translated: a person confirming this batch is being shown
-     * rule texts that are not the ones in their file, and a preview that let that pass silently would be
-     * asking for consent to something it had not shown them. Entries refused AFTER translation are not
-     * here — they are in `skipped`, named as the file writes them.
+     * The seat once carried the entries whose MATCH FORM was rewritten on the way in (the space-star
+     * suggestion form of the other product translated to this lane's colon-star form, one row per
+     * translated candidate with its `scope`). That translation is retired: the space-star wildcard is
+     * now a first-class match form of this lane's own grammar, so an entry's match form imports as the
+     * file states it — `Bash(npm run *)` lands as `Bash(npm run *)`, never as a colon-star — and nothing
+     * is ever pushed here. What `candidates` carries is the grammar's CANONICAL re-projection of each
+     * entry (the parser folds spacing: `Bash(npm<TAB>run *)` lands as `Bash(npm run *)`); that is the
+     * ordinary normalization every rule text in this lane undergoes, the same one the store applies,
+     * and not a translation this seat reports. An entry whose star placement has no rule form is
+     * refused into `skipped` under `unsupported.wildcard`, named as the file writes it. A reader
+     * rendering a "rewritten spellings" column from this seat renders an empty column, correctly.
      */
     translated: Array<{
         from: string;