@sema-agent/core 7.1.0 → 7.3.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/mailbox-store.d.ts

@@ -12,7 +12,54 @@ export interface MailboxMessage {
      *  has other writers): such records deliver with an empty chain and are never retro-admitted —
      *  cross-engine records sit outside the guard's promise domain by ruling. */
     hopChain?: string[];
+    /** design/385 — typed peer metadata the drain point's authoritative judgments read (from-mode parity,
+     *  reply routing, admission sender key, record kind, the cross-principal trust anchors). Typed side
+     *  channel, never model-facing text — encoding it into `content` would let text reach authority.
+     *  ABSENT = a pre-385 or foreign record (same semantics as an absent `hopChain`): the drain treats it
+     *  as foreign, never retro-admits it. Validated at `append` ({@link readMailboxPeerMeta}). */
+    peerMeta?: MailboxPeerMeta;
 }
+/** design/385 — the typed peer-metadata record on a parked message. ONE optional object, one-time
+ *  contract extension; every field optional. Bundled backends persist it verbatim and hand back a
+ *  detached copy. */
+export interface MailboxPeerMeta {
+    /** The sending session's id (reply routing). */
+    fromSession?: string;
+    /** The sender's permission-mode class at send time — the drain judges parity against the RECEIVER. */
+    fromMode?: MailboxPeerFromMode;
+    /** The admission gate's sender key (rate/dedup axis). */
+    senderKey?: string;
+    /** Record kind: a peer message runs the parity judgment; notices bypass it and land on the notice face. */
+    kind?: MailboxPeerRecordKind;
+    /** Cross-principal delivery only — the SENDER's scope, the typed trust anchor for attribution. */
+    fromScope?: string;
+    /** Cross-principal delivery only — the delivery gate's receipt id (audit back-reference). */
+    gateReceiptId?: string;
+}
+export declare const MAILBOX_PEER_FROM_MODES: readonly ["bypass", "prompting"];
+export type MailboxPeerFromMode = (typeof MAILBOX_PEER_FROM_MODES)[number];
+export declare const MAILBOX_PEER_RECORD_KINDS: readonly ["peer_message", "idle_notice", "delivery_notice"];
+export type MailboxPeerRecordKind = (typeof MAILBOX_PEER_RECORD_KINDS)[number];
+/** The `append` refusal code for a malformed `peerMeta` (design/385): a garbage record is refused up
+ *  front with this code, never silently stripped or stored — a drain that reads a half-typed record
+ *  would judge on fabricated inputs. */
+export declare const MAILBOX_INVALID_PEER_META_CODE = "mailbox.invalid_peer_meta";
+/** The lane-mount refusal code: the cross-session lane asked for a backend that does not declare
+ *  cross-process safety ({@link mailboxCrossProcessMountVerdict}). */
+export declare const MAILBOX_CROSS_PROCESS_UNSAFE_CODE = "mailbox.cross_process_unsafe";
+/**
+ * Validate + detach an appended `peerMeta`. `undefined` ⇒ `undefined` (absent record). Anything else
+ * must be a plain object whose keys are all known, whose present values are non-empty strings, with
+ * `fromMode`/`kind` drawn from their closed sets; an `undefined`-valued key counts as absent. Any other
+ * shape throws {@link MailboxStoreError} with {@link MAILBOX_INVALID_PEER_META_CODE} — every bundled
+ * backend calls this BEFORE touching storage, so a refused append has zero side effects. Unknown keys
+ * are refused on purpose: the object is the contract's one typed slot, and a key nobody declared is
+ * either a typo or a newer schema this engine cannot judge on — both are loud, not silent.
+ */
+export declare function readMailboxPeerMeta(raw: unknown): MailboxPeerMeta | undefined;
+/** A detached copy of a persisted record's `peerMeta` (absent stays absent) — the read-side twin of
+ *  {@link readMailboxPeerMeta}, so a lease consumer's mutation never reaches the stored record. */
+export declare function cloneMailboxPeerMeta(meta: MailboxPeerMeta | undefined): MailboxPeerMeta | undefined;
 /** The enqueue refusal code of the pre-delete clause (see {@link MailboxStore} and
  *  {@link MailboxStoreError}) — the ONE place it is spelled, so an out-of-repo store twin imports it
  *  instead of value-copying the string (same posture as `STALE_RUNNING_REAP_ATTRIBUTION`: a shared
@@ -31,9 +78,10 @@ export declare const MAILBOX_TOMBSTONED_RECIPIENT_CODE = "mailbox.recipient_tomb
  * A backend may raise the same code with a plain `Error` carrying `.code`; consumers branch on the
  * string, not on this class (a cross-process/out-of-repo store cannot hand back an instance).
  */
+export type MailboxStoreErrorCode = typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE | typeof MAILBOX_INVALID_PEER_META_CODE | typeof MAILBOX_CROSS_PROCESS_UNSAFE_CODE;
 export declare class MailboxStoreError extends Error {
-    readonly code: typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE;
-    constructor(code: typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE, message: string);
+    readonly code: MailboxStoreErrorCode;
+    constructor(code: MailboxStoreErrorCode, message: string);
 }
 /** A leased batch: the messages a claim winner owns for delivery, plus the ack cursor. */
 export interface MailboxLease {
@@ -49,6 +97,8 @@ export interface MailboxAppendMessage {
     sentAt: number;
     /** design/176 — see {@link MailboxMessage.hopChain}. */
     hopChain?: string[];
+    /** design/385 — see {@link MailboxMessage.peerMeta}; validated by {@link readMailboxPeerMeta}. */
+    peerMeta?: MailboxPeerMeta;
 }
 /**
  * The pluggable mailbox seam (design/151 §7.1). Contract notes for implementations (file/pg):
@@ -92,8 +142,25 @@ export interface MailboxAppendMessage {
  *   lifecycle (the two bundled ones, the CC inbox adapter) has nothing to refuse and keeps accepting
  *   — the clause fixes the SPELLING of the refusal, so a deployment reads one code instead of a
  *   per-backend dialect. Acceptance kit: `mailboxTombstonedRecipientContract`.
+ * - PEER METADATA (design/385, additive): `append` takes an optional typed `peerMeta`; a backend
+ *   persists it and hands it back on `claimLease` byte-for-byte (a detached copy), absent stays absent,
+ *   and a malformed value is REFUSED with `"mailbox.invalid_peer_meta"` before any side effect
+ *   (`readMailboxPeerMeta` is the one validator; bundled backends call it first). T1 cases in
+ *   `mailboxStoreContract` cover the round trip, the refusal and the aliasing.
+ * - CROSS-PROCESS SAFETY (design/385, optional capability declared on the store): the session-box
+ *   drain shares ONE box between several OS processes. A backend that is correct under that sharing —
+ *   seq minted once across processes, lease/ack never crossing, one process's housekeeping never
+ *   discarding another's durable append — declares `crossProcessSafe: true` AFTER passing
+ *   `mailboxCrossProcessContract` (the T2 kit that pins the whole set, not "has a lock"). A backend
+ *   that does not declare it is refused by the lane at mount time with a named reason
+ *   ({@link mailboxCrossProcessMountVerdict}) — never silently mounted on luck.
  */
 export interface MailboxStore {
+    /** design/385 — cross-process safety declaration (see the interface notes). `true` = this backend
+     *  passed `mailboxCrossProcessContract` over real OS processes; `false` = deliberately process-local
+     *  (the in-memory reference); absent = undeclared (the CC inbox adapter). Read by
+     *  {@link mailboxCrossProcessMountVerdict}; any other value is a malformed declaration and refuses. */
+    readonly crossProcessSafe?: boolean;
     /** Durably park one message. Refuses `"mailbox.recipient_tombstoned"` when the backend can see
      *  that its recipient is in the deployment's pre-delete state (see the interface notes above). */
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
@@ -110,6 +177,21 @@ export interface MailboxStore {
         maxAgeMs?: number;
     }): Promise<number>;
 }
+/** The lane-mount verdict on a backend's cross-process declaration. */
+export type MailboxCrossProcessVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    code: typeof MAILBOX_CROSS_PROCESS_UNSAFE_CODE;
+    reason: string;
+};
+/**
+ * design/385 — may the cross-session lane (several OS processes draining one session box) mount over
+ * this backend? `ok` only for an explicit `crossProcessSafe: true`. Every other shape refuses with a
+ * named reason so the host can print it: absent (undeclared), `false` (process-local by design), or a
+ * value of the wrong type (a malformed declaration is refused, not read as "probably fine").
+ */
+export declare function mailboxCrossProcessMountVerdict(store: MailboxStore): MailboxCrossProcessVerdict;
 /** RB-250② (2026-07-28) class fix — the box age for `reap` is the MAX `sentAt`, not the
  *  last array element: `sentAt` is caller-supplied, so append order need not be time order, and taking
  *  the tail let a box whose freshest message was mid-array be swept — both bundled backends discarded
@@ -118,12 +200,17 @@ export interface MailboxStore {
  *  adapter's documented posture — treating it as very old would let a malformed row delete a live
  *  box). Module-level export only; NOT re-exported from src/index.ts. */
 export declare function newestSentAt(messages: readonly MailboxMessage[]): number | undefined;
+/** A lease-facing copy of a stored record: every mutable member (hopChain, peerMeta) detached, so a
+ *  consumer's mutation can never reach the record a redelivery serves. Shared by the bundled backends. */
+export declare function detachMailboxMessage(m: MailboxMessage): MailboxMessage;
 /**
  * In-process reference implementation (single-instance / tests). Same posture as
  * {@link import("./background-agent-store.js").InMemoryBackgroundAgentStore}: not default-mounted,
  * detached copies at both boundaries, single-event-loop atomicity.
  */
 export declare class InMemoryMailboxStore implements MailboxStore {
+    /** Process-local by construction (a Map): never a cross-process box, said so explicitly. */
+    readonly crossProcessSafe = false;
     private boxes;
     private key;
     private box;

package/dist/core/mailbox-store.js

@@ -1,4 +1,52 @@
 import { assertRetentionPolicy } from "./retention-policy.js";
+export const MAILBOX_PEER_FROM_MODES = ["bypass", "prompting"];
+export const MAILBOX_PEER_RECORD_KINDS = ["peer_message", "idle_notice", "delivery_notice"];
+export const MAILBOX_INVALID_PEER_META_CODE = "mailbox.invalid_peer_meta";
+export const MAILBOX_CROSS_PROCESS_UNSAFE_CODE = "mailbox.cross_process_unsafe";
+const PEER_META_STRING_KEYS = ["fromSession", "senderKey", "fromScope", "gateReceiptId"];
+export function readMailboxPeerMeta(raw) {
+    if (raw === undefined)
+        return undefined;
+    const refuse = (why) => {
+        throw new MailboxStoreError(MAILBOX_INVALID_PEER_META_CODE, `MailboxStore.append: peerMeta ${why}`);
+    };
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return refuse("must be a plain object");
+    const proto = Object.getPrototypeOf(raw);
+    if (proto !== Object.prototype && proto !== null)
+        return refuse("must be a plain object (a class instance, Date, Map or similar is not)");
+    const out = {};
+    for (const key of Reflect.ownKeys(raw)) {
+        if (typeof key !== "string")
+            return refuse("carries a symbol-keyed member");
+        const k = key;
+        const v = raw[k];
+        if (v === undefined)
+            continue;
+        if (k === "fromMode") {
+            if (!MAILBOX_PEER_FROM_MODES.includes(v))
+                return refuse(`fromMode must be one of ${MAILBOX_PEER_FROM_MODES.join("|")}`);
+            out.fromMode = v;
+        }
+        else if (k === "kind") {
+            if (!MAILBOX_PEER_RECORD_KINDS.includes(v))
+                return refuse(`kind must be one of ${MAILBOX_PEER_RECORD_KINDS.join("|")}`);
+            out.kind = v;
+        }
+        else if (PEER_META_STRING_KEYS.includes(k)) {
+            if (typeof v !== "string" || v === "")
+                return refuse(`${k} must be a non-empty string`);
+            out[k] = v;
+        }
+        else {
+            return refuse(`carries an unknown key ${JSON.stringify(k)}`);
+        }
+    }
+    return out;
+}
+export function cloneMailboxPeerMeta(meta) {
+    return meta === undefined ? undefined : { ...meta };
+}
 export const MAILBOX_TOMBSTONED_RECIPIENT_CODE = "mailbox.recipient_tombstoned";
 export class MailboxStoreError extends Error {
     code;
@@ -8,6 +56,17 @@ export class MailboxStoreError extends Error {
         this.name = "MailboxStoreError";
     }
 }
+export function mailboxCrossProcessMountVerdict(store) {
+    const declared = store.crossProcessSafe;
+    if (declared === true)
+        return { ok: true };
+    const reason = declared === undefined
+        ? "the mailbox backend does not declare cross-process safety (crossProcessSafe is absent): several terminal sessions would share one session box on luck"
+        : declared === false
+            ? "the mailbox backend declares crossProcessSafe: false (process-local by design): it cannot serve a session box shared across OS processes"
+            : `the mailbox backend's crossProcessSafe declaration is malformed (${typeof declared}, expected a boolean)`;
+    return { ok: false, code: MAILBOX_CROSS_PROCESS_UNSAFE_CODE, reason };
+}
 export function newestSentAt(messages) {
     let newest;
     for (const m of messages) {
@@ -18,7 +77,15 @@ export function newestSentAt(messages) {
     }
     return newest;
 }
+export function detachMailboxMessage(m) {
+    return {
+        ...m,
+        ...(m.hopChain !== undefined ? { hopChain: [...m.hopChain] } : {}),
+        ...(m.peerMeta !== undefined ? { peerMeta: cloneMailboxPeerMeta(m.peerMeta) } : {}),
+    };
+}
 export class InMemoryMailboxStore {
+    crossProcessSafe = false;
     boxes = new Map();
     key(scope, handle) {
         if (handle.includes("\u0000")) {
@@ -38,9 +105,17 @@ export class InMemoryMailboxStore {
     async append(scope, handle, msg) {
         if (scope === undefined || scope === "")
             throw new Error("MailboxStore.append: refusing a message without a scope");
+        const peerMeta = readMailboxPeerMeta(msg.peerMeta);
         const b = this.box(scope, handle);
         const seq = b.nextSeq++;
-        b.messages.push({ seq, ...(msg.from !== undefined ? { from: msg.from } : {}), content: msg.content, sentAt: msg.sentAt, ...(msg.hopChain !== undefined ? { hopChain: [...msg.hopChain] } : {}) });
+        b.messages.push({
+            seq,
+            ...(msg.from !== undefined ? { from: msg.from } : {}),
+            content: msg.content,
+            sentAt: msg.sentAt,
+            ...(msg.hopChain !== undefined ? { hopChain: [...msg.hopChain] } : {}),
+            ...(peerMeta !== undefined ? { peerMeta } : {}),
+        });
         return seq;
     }
     async claimLease(scope, handle, owner, ttlMs, now = Date.now()) {
@@ -51,7 +126,7 @@ export class InMemoryMailboxStore {
             return null;
         const maxSeq = b.messages[b.messages.length - 1].seq;
         b.lease = { owner, expiresAt: now + ttlMs, maxSeq };
-        return { messages: b.messages.map((m) => ({ ...m, ...(m.hopChain !== undefined ? { hopChain: [...m.hopChain] } : {}) })), maxSeq };
+        return { messages: b.messages.map((m) => detachMailboxMessage(m)), maxSeq };
     }
     async ack(scope, handle, owner, upToSeq) {
         const b = this.boxes.get(this.key(scope, handle));

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;