@sema-agent/core 7.1.0 → 7.2.0

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

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { escapeForDisclosure, hasUnrenderableCharacters, parseAllowRuleText, ruleAdmitsCommand, segmentCoverageOf, suggestRulesForCommand, translateImportedWildcardRule, } from "./permission-rule-model.js";
+import { escapeForDisclosure, hasUnrenderableCharacters, parseAllowRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf, segmentCoverageOf, suggestRulesForCommand, } from "./permission-rule-model.js";
 import { errText, isValidConsentScope, normalizePersistedRule, sameRuleOwner, sameScope, writerOf } from "./permission-rule-store.js";
 export class InMemoryRuleApprovalRecordStore {
     rows = new Map();
@@ -7,7 +7,7 @@ export class InMemoryRuleApprovalRecordStore {
         const r = this.rows.get(id);
         if (r === undefined)
             return undefined;
-        if (r.schema !== 2) {
+        if (r.schema !== 3) {
             return {
                 staleSchema: true,
                 id: r.id,
@@ -139,8 +139,42 @@ function approvalRecordDamageOf(rec) {
                 if (!Number.isInteger(offer.uncoveredSegments) || offer.uncoveredSegments < 0) {
                     return `card batch offer ${at} must carry a non-negative uncovered-segment count`;
                 }
+                const detail = offer.uncoveredDetail;
+                if (!Array.isArray(detail))
+                    return `card batch offer ${at} must carry its uncovered-segment reason rows`;
+                if (detail.length !== offer.uncoveredSegments) {
+                    return `card batch offer ${at} carries ${detail.length} reason rows for an uncovered-segment count of ${offer.uncoveredSegments} — one fact, two seats, and they must agree`;
+                }
+                for (const [ri, row] of detail.entries()) {
+                    if (typeof row !== "object" ||
+                        row === null ||
+                        typeof row.segment !== "string" ||
+                        (row.reason !== "redirection" && row.reason !== "no_rule_form" && row.reason !== "cap_overflow")) {
+                        return `card batch offer ${at} reason row ${ri} is not a segment/reason row from the closed reason set`;
+                    }
+                }
+                if (detail.length > 0) {
+                    const rows = detail;
+                    const table = typeof rec.command === "string" ? segmentCoverageOf(rec.command, { persisted: [] }, { tool: CARD_RULE_TOOL, cwd: undefined }) : undefined;
+                    if (table === undefined) {
+                        return `card batch offer ${at} carries reason rows but the record's command cannot back them — a row without a readable source command is a row nobody can audit`;
+                    }
+                    let cursor = 0;
+                    for (const [ri, row] of rows.entries()) {
+                        let found = -1;
+                        for (let j = cursor; j < table.length; j++) {
+                            if (table[j]?.segment === row.segment) {
+                                found = j;
+                                break;
+                            }
+                        }
+                        if (found === -1)
+                            return `card batch offer ${at} reason row ${ri} names a segment the record's command does not carry at or after that position`;
+                        cursor = found + 1;
+                    }
+                }
             }
-            else if (offer.segments !== undefined || offer.uncoveredSegments !== undefined) {
+            else if (offer.segments !== undefined || offer.uncoveredSegments !== undefined || offer.uncoveredDetail !== undefined) {
                 return `${escapeForDisclosure(rec.kind)} batch offer ${at} must not carry segment metadata — there is no compound command behind it`;
             }
         }
@@ -149,6 +183,16 @@ function approvalRecordDamageOf(rec) {
         if (!claimed.has(at))
             return `candidate ${at} belongs to no offer — every candidate row is claimed by exactly one offer`;
     }
+    if (rec.edited !== undefined) {
+        if (typeof rec.edited !== "object" || rec.edited === null)
+            return "the edited seat is not an object";
+        const w = rec.edited.warnings;
+        if (w !== undefined) {
+            if (!Array.isArray(w) || w.length !== 1 || (w[0] !== "broad_prefix" && w[0] !== "compound_prefix")) {
+                return "the edited seat's warnings are not a single-code array from the closed breadth-code set";
+            }
+        }
+    }
     return undefined;
 }
 export function ruleOffersOfRecord(rec) {
@@ -163,21 +207,51 @@ export function ruleOffersOfRecord(rec) {
         return { rule: parsed.rule.rule, match: parsed.rule.match, command: parsed.rule.command };
     };
     return rec.offers.map((offer) => {
-        if (offer.kind === "single")
-            return { kind: "single", ...tripleOf(offer.candidate) };
+        if (offer.kind === "single") {
+            const t = tripleOf(offer.candidate);
+            if (t.match === "subpath") {
+                throw new Error("approval-record single offer references a directory rule — a shape this engine does not mint; refusing to render it");
+            }
+            return { kind: "single", ...t };
+        }
         const segments = offer.segments;
-        if (segments === undefined || offer.uncoveredSegments === undefined) {
+        if (segments === undefined || offer.uncoveredSegments === undefined || offer.uncoveredDetail === undefined) {
             throw new Error("a batch offer without mint-time segment metadata has no card face to project — import/starter batches render as previews, not offer cards");
         }
+        const rawDetail = offer.uncoveredDetail;
+        const count = offer.uncoveredSegments;
+        const detail = [];
+        const detailDamaged = (() => {
+            if (!Array.isArray(rawDetail) || !Number.isInteger(count) || count < 0 || rawDetail.length !== count)
+                return true;
+            for (let i = 0; i < rawDetail.length; i++) {
+                const row = rawDetail[i];
+                if (typeof row !== "object" || row === null)
+                    return true;
+                const segment = row.segment;
+                const reason = row.reason;
+                if (typeof segment !== "string" || (reason !== "redirection" && reason !== "no_rule_form" && reason !== "cap_overflow"))
+                    return true;
+                detail.push({ segment, reason });
+            }
+            return false;
+        })();
+        if (detailDamaged) {
+            throw new Error("a batch offer's uncovered-segment reason rows do not match their count or the closed reason set — refusing to render damaged mint-time facts as a card face");
+        }
         return {
             kind: "batch",
             rules: offer.candidates.map((candidate, i) => {
                 const segment = segments[i];
                 if (segment === undefined)
                     throw new Error(`batch offer member ${i} has no source segment recorded`);
-                return { ...tripleOf(candidate), segment };
+                const t = tripleOf(candidate);
+                return t.match === "subpath"
+                    ? { kind: "directoryRead", rule: t.rule, directory: t.command, segment }
+                    : { kind: "command", rule: t.rule, match: t.match, command: t.command, segment };
             }),
-            uncoveredSegments: offer.uncoveredSegments,
+            uncoveredSegments: count,
+            uncoveredDetail: detail,
         };
     });
 }
@@ -234,12 +308,19 @@ export async function prepareCardApproval(opts) {
             if (sessionRows.length > 0)
                 table = [...sessionRows, ...listed.rules];
         }
-        coverage = segmentCoverageOf(opts.command, { persisted: table }, { tool: CARD_RULE_TOOL, cwd: opts.cwd, sessionId: opts.sessionId });
+        coverage = segmentCoverageOf(opts.command, { persisted: table }, { tool: CARD_RULE_TOOL, cwd: opts.cwd, sessionId: opts.sessionId, ...(opts.execCwd !== undefined ? { execCwd: opts.execCwd } : {}) });
     }
     catch {
         coverage = undefined;
     }
-    const suggested = suggestRulesForCommand(opts.command, coverage !== undefined ? { coverage } : undefined);
+    const suggested = suggestRulesForCommand(opts.command, {
+        ...(coverage !== undefined ? { coverage } : {}),
+        scope,
+        ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+        ...(opts.execCwd !== undefined ? { execCwd: opts.execCwd } : {}),
+        ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+        ...(opts.deps.deniesDirectoryRead !== undefined ? { deniesDirectoryRead: opts.deps.deniesDirectoryRead } : {}),
+    });
     const candidates = [];
     const claimedBy = new Map();
     const claim = (text) => {
@@ -257,13 +338,14 @@ export async function prepareCardApproval(opts) {
             candidates: offer.rules.map((r) => claim(r.rule)),
             segments: offer.rules.map((r) => r.segment),
             uncoveredSegments: offer.uncoveredSegments,
+            uncoveredDetail: offer.uncoveredDetail ?? [],
         });
     if (candidates.length === 0)
         return undefined;
     const record = {
         id: mintId(opts.deps, "rar"),
         ...recordIdentityOf(owner),
-        schema: 2,
+        schema: 3,
         kind: "card",
         state: "pending",
         rev: 0,
@@ -366,7 +448,8 @@ function checkEditedRuleText(text, command) {
             message: `the edited rule "${parsed.rule.rule}" does not admit the command that was decided ("${escapeForDisclosure(command)}") — a card's edit may widen how much the rule covers, never move it to a different grant`,
         };
     }
-    return { ok: true, canonicalRule: parsed.rule.rule };
+    const warnings = ruleBreadthWarningsOf(parsed.rule);
+    return { ok: true, canonicalRule: parsed.rule.rule, ...(warnings.length > 0 ? { warnings } : {}) };
 }
 export function precheckEditedRuleText(text, command) {
     if (typeof text !== "string") {
@@ -443,7 +526,7 @@ async function confirmEditedCandidate(rec, edit, deps) {
         candidates: [...rec.candidates, { rule: checked.canonicalRule, scope }],
         offers: [...rec.offers, { kind: "single", candidate: index }],
         selectedOffer: rec.offers.length,
-        edited: { index, text: edit.text, at: nowIso(deps) },
+        edited: { index, text: edit.text, at: nowIso(deps), ...(checked.warnings !== undefined ? { warnings: checked.warnings.map((w) => w.code) } : {}) },
     };
     const won = await deps.approvals.cas(rec.id, rec.rev, next);
     if (!won) {
@@ -675,30 +758,36 @@ export async function prepareCcImport(opts) {
                 skipped.push({ rule: String(entry), reason: "settings entry is not a string" });
                 continue;
             }
+            if (entry.startsWith("Read(")) {
+                const parsed = parseAllowRuleText(entry);
+                if ("reject" in parsed) {
+                    skipped.push({
+                        rule: entry,
+                        reason: "unsupported.form: only the Read(//abs-dir/**) directory form imports in v1 — this entry stays in the settings file, unimported",
+                    });
+                    continue;
+                }
+                if (!candidates.some((c) => c.rule === parsed.rule.rule && sameScope(c.scope, scope))) {
+                    candidates.push({ rule: parsed.rule.rule, scope });
+                }
+                continue;
+            }
             if (!entry.startsWith("Bash(")) {
                 const reason = /^[A-Za-z][A-Za-z0-9_]*\(.*\)$/.test(entry)
-                    ? "unsupported.tool: only Bash(...) command rules import in v1 — this entry stays in the settings file, unimported"
+                    ? "unsupported.tool: only Bash(...) command rules and Read(//abs-dir/**) directory rules import in v1 — this entry stays in the settings file, unimported"
                     : /^[A-Za-z][A-Za-z0-9_-]*$/.test(entry)
                         ? "unsupported.form: a bare tool-name entry is a name-set item, not a command rule — it stays in the settings file, unimported"
-                        : "unsupported.form: not a Bash(...) command rule — it stays in the settings file, unimported";
+                        : "unsupported.form: not a command rule spelling this version imports — it stays in the settings file, unimported";
                 skipped.push({ rule: entry, reason });
                 continue;
             }
-            const wildcard = translateImportedWildcardRule(entry);
-            if (wildcard !== undefined && "skip" in wildcard) {
-                skipped.push({ rule: entry, reason: wildcard.skip });
-                continue;
-            }
-            const text = wildcard?.rule ?? entry;
-            const parsed = parseAllowRuleText(text);
+            const parsed = parseAllowRuleText(entry);
             if ("reject" in parsed) {
                 skipped.push({ rule: entry, reason: `${parsed.reject.code}: ${parsed.reject.message}` });
                 continue;
             }
             if (candidates.some((c) => c.rule === parsed.rule.rule && sameScope(c.scope, scope)))
                 continue;
-            if (wildcard !== undefined)
-                translated.push({ from: entry, to: parsed.rule.rule, scope });
             candidates.push({ rule: parsed.rule.rule, scope });
         }
     }
@@ -708,7 +797,7 @@ export async function prepareCcImport(opts) {
     const record = {
         id: mintId(opts.deps, "rar"),
         ...recordIdentityOf(owner),
-        schema: 2,
+        schema: 3,
         kind: "import",
         state: "pending",
         rev: 0,
@@ -742,7 +831,7 @@ export async function prepareStarterBatch(opts) {
     const record = {
         id: mintId(opts.deps, "rar"),
         ...recordIdentityOf(owner),
-        schema: 2,
+        schema: 3,
         kind: "starter",
         state: "pending",
         rev: 0,

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

@@ -58,16 +58,37 @@
  * here) and no leading-env-assignment stripping (`FOO=1 git status` simply does not match
  * `Bash(git status:*)`) — the last two are strict-side divergences from upstream, registered as such.
  */
-/** The one tool the v1 rule lane speaks for. The field exists on the rule so v2 can widen without a shape change.
+/** The tools the rule lane speaks for. `"Bash"` is the historical member; `"Read"` (design/382 §2.2)
+ *  speaks EXACTLY ONE grammar — the double-slash directory form `Read(//abs/**)`, the directory
+ *  read-authorization a compound card's cd segment mints — and its admission is the CLOSED two-point
+ *  one on {@link directoryRuleAdmits}: a Read tool call under the directory, and a compound's cd
+ *  segment resolving into it. Nothing else — never a write, never a whole Bash command, never a
+ *  non-cd segment.
  *
  *  design/276 §3.3 (doctrine, for whoever widens this set): a future `SendMessage(…)`-form rule MAY
  *  clear the peer-referral ask — that ask is classifier hesitation by construction (#144: allow rules
  *  silence the classifier's questions, never a mandated one), so a recorded human yes is exactly what
  *  clears it. The org/hook/matchedAskRule immunities stay: those conjuncts live in the gate's
  *  persisted-rule lane and do not loosen with this set. */
-export type PersistedRuleTool = "Bash";
-/** v1 match forms. `"wildcard"` is reserved for v2 and is not a value this version ever produces. */
-export type PersistedRuleMatch = "exact" | "prefix";
+export type PersistedRuleTool = "Bash" | "Read";
+/**
+ * Match forms. Four members, two of them one predicate:
+ *  · `exact` — admits the one string the rule spells.
+ *  · `wildcard` — the TRAILING SPACE-STAR spelling (`Bash(npm run *)`): the body, or the body followed
+ *    by a space and more, inside the body's own segment count. This is the spelling upstream itself
+ *    mints for its prefix suggestions (its classifier compiles one trailing ` *` into an optional
+ *    suffix `^body( .*)?$`), so it is the form this lane's SUGGESTION face mints too (#510).
+ *  · `prefix` — the historical COLON-STAR spelling (`Bash(npm run:*)`), match-equivalent to `wildcard`
+ *    on the single-command body. Kept as a fully supported COMPATIBILITY READ — stored rules are never
+ *    migrated or rewritten — and it remains the ONLY spelling of the compound-prefix form
+ *    (`Bash(cd /tmp && adb pull:*)`): the trailing-star form deliberately has no compound reading
+ *    (see {@link parseAllowRuleText}), because upstream's own trailing-star pattern is inert on a
+ *    compound and importing/minting one as a chain licence would grant what nobody approved.
+ *  · `subpath` — the Read directory form (design/382 §2.2): `Read(//abs/**)`, admitting reads under
+ *    one absolute directory. Never admits any command; its one predicate is
+ *    {@link directoryRuleAdmits}.
+ */
+export type PersistedRuleMatch = "exact" | "prefix" | "wildcard" | "subpath";
 /**
  * Where a rule applies — design/382 §4.1, the THREE consent dimensions.
  *
@@ -155,8 +176,11 @@ export interface RuleTombstone {
     /** The delete operation's own dot — the operation's persistent identity. */
     deletedBy: RuleDot;
 }
-/** Why a rule text was refused. Codes are stable so an import report can group by them. */
-export type RuleRejectCode = "invalid.grammar" | "invalid.empty_command" | "invalid.not_simple_command" | "invalid.bare_interpreter_prefix" | "invalid.unbalanced_quotes" | "invalid.control_chars" | "invalid.too_long" | "unsupported.tool" | "unsupported.wildcard";
+/** Why a rule text was refused. Codes are stable so an import report can group by them.
+ *  `invalid.path_traversal` (design/382 §2.2, B5): a Read directory body carrying a `.` or `..`
+ *  segment — the lexical-normal spelling is the ONLY spelling, so a traversal segment is not
+ *  normalized away but refused. */
+export type RuleRejectCode = "invalid.grammar" | "invalid.empty_command" | "invalid.not_simple_command" | "invalid.bare_interpreter_prefix" | "invalid.unbalanced_quotes" | "invalid.control_chars" | "invalid.too_long" | "invalid.path_traversal" | "unsupported.tool" | "unsupported.wildcard";
 export interface RuleReject {
     code: RuleRejectCode;
     message: string;
@@ -371,49 +395,10 @@ export declare function parseAllowRuleText(text: string, opts?: {
 } | {
     reject: RuleReject;
 };
-/** The canonical spelling of a rule for a (already folded) command and match form. */
+/** The canonical spelling of a rule for a (already folded) command and match form. For `subpath` the
+ *  command is the lexical-normal absolute directory (one leading slash), re-spelled in the
+ *  double-slash directory form. */
 export declare function formatAllowRuleText(command: string, match: PersistedRuleMatch): string;
-/**
- * #490 件4 — read ANOTHER product's `Bash(<body> *)` SPACE-STAR spelling as this lane's colon-star
- * prefix rule, for the IMPORT door only.
- *
- * Why a translation is owed at all: the other product mints its prefix suggestions in that spelling
- * (its own classifier reads `X:*` as its earlier prefix form and anything else containing an unescaped star as
- * a wildcard), so a person migrating settings had EVERY prefix rule they had ever approved refused as
- * `unsupported.wildcard` — the import silently emptied out exactly the rules that were the point of it.
- *
- * Translated ONLY for the ONE spelling whose semantics this lane can state exactly: content ending in
- * ` *` with that star the only unescaped one. Upstream compiles a single trailing ` *` into an
- * OPTIONAL suffix (`^body( .*)?$`), which is precisely "the body, or the body followed by a space and
- * more" — this lane's prefix predicate. Any other star placement compiles to a real glob with no rule
- * form here, and a bare `*` is a whole-tool grant that must never become a command rule; both are
- * refused with a reason of their own so the import can DISCLOSE them rather than drop them.
- *
- * WHAT THE TRANSLATED RULE GRANTS, against the source spelling, axis by axis (the direction matters,
- * and it is one-way with one named exception): identical on the bare body, on body-plus-arguments, on
- * the word boundary (`npm run` never reaches `npm run-x`) and on compounds (both sides refuse a chain
- * against a single-command body). NARROWER here on four axes, because upstream normalizes the
- * CANDIDATE before matching and this lane never does: a candidate carrying a redirection, wrapped in
- * `timeout`/`nice`/`nohup`-style words, fed through `xargs`, or prefixed with a `VAR=value` assignment
- * matches there and matches nothing here. WIDER on exactly one: this lane folds runs of whitespace on
- * both sides, so `npm  run  build` matches the imported rule where upstream's wildcard arm (which does
- * not fold) would refuse it. That axis is NOT introduced by this translation — whitespace folding is
- * this lane's universal reading and already applies to every imported EXACT rule, against an upstream
- * exact arm that is byte-strict — so it is disclosed as a lane property rather than treated as a
- * translation defect. Every other difference runs toward granting less.
- *
- * Returns `undefined` when the text is not a Bash wildcard spelling at all (nothing to translate; the
- * caller proceeds with the text as written), `{ rule }` with the spelling to parse INSTEAD, or
- * `{ skip }` with the reason a star spelling has no form here. Never bypasses the validator: the
- * returned text goes through {@link parseAllowRuleText} exactly like a hand-written one, so the
- * interpreter-head refusal, the control-character screen and the length bound all still apply — a
- * translated `Bash(node *)` is refused `invalid.bare_interpreter_prefix` just as a typed one is.
- */
-export declare function translateImportedWildcardRule(text: string): {
-    rule: string;
-} | {
-    skip: string;
-} | undefined;
 /**
  * Does this rule's command pattern admit `command`?
  *
@@ -447,6 +432,44 @@ export declare function ruleAdmitsCommand(rule: Pick<PersistedAllowRule, "match"
  * see — the inversion this whole ticket exists to prevent.
  */
 export declare function ruleAdmitsProgramRun(rule: Pick<PersistedAllowRule, "match" | "command">, command: string): boolean;
+/** design/382 §3.3-5 — one BREADTH note about a rule a person is about to persist: which wide shape
+ *  it has, said in words a surface can show beside the input line. A warning is never a refusal —
+ *  the closed refusal set is untouched — and never adjudication input. */
+export interface EditedRuleBreadthWarning {
+    readonly code: "broad_prefix" | "compound_prefix";
+    /** The baseline sentence (a surface may reword it, never invert it — the same contract as the
+     *  §3.5 reason baselines). */
+    readonly message: string;
+}
+/**
+ * design/382 §3.3-5 — the breadth classifier behind the card-edit face's warning seat: does this
+ * (accepted) rule carry a width worth saying out loud before a person persists it?
+ *
+ *  · `broad_prefix` — a prefix rule whose body is a SINGLE token (a bare verb, `Bash(mkdir:*)`):
+ *    it admits every argument form of that command, not just the one on the card. This is the
+ *    legal wide grant of §3.4 — the offer face deliberately never proposes it, the edit /
+ *    hand-written channels legally accept it, and this sentence is what makes that acceptance an
+ *    INFORMED one.
+ *  · `compound_prefix` — a prefix rule whose body is a connector CHAIN (`Bash(cd /tmp && npm:*)`):
+ *    one rule admitting several program runs, with anything extending its final segment.
+ *
+ * Judged on the CANONICAL rule (post-normalization, the spelling that would persist), with the
+ * lane's own instruments — the same shape reader the matcher uses, never a second grammar. A body
+ * this lane cannot read yields no warning: every such spelling is already the validator's refusal,
+ * and a warning beside a refusal would be noise about a rule that is not going to exist.
+ *
+ * An EXACT rule never warns (it admits one string, the one it spells — there is no width to name),
+ * and a SUBPATH rule is not this classifier's subject (no command reach at all). The two
+ * reach-bearing forms take the same two questions: `prefix` (colon-star) and `wildcard`
+ * (trailing space-star, #510 — match-equivalent reach on a single-command body; its grammar has no
+ * chain reading, so only the single-token question can fire for it).
+ * MAINTENANCE DUTY, stated where it binds: every match form with PREFIX REACH belongs here — a
+ * new reach-bearing member added to {@link PersistedRuleMatch} owes this classifier its arm, judged
+ * by the same "single token / chain body" questions (an exact-only form never warns).
+ * The upstream editor validates edited text but shows no breadth evidence at all; this seat is a
+ * superset disclosure (registered divergence, design/382 §6-4).
+ */
+export declare function ruleBreadthWarningsOf(rule: Pick<PersistedAllowRule, "match" | "command">): readonly EditedRuleBreadthWarning[];
 /**
  * The segments of `command` as the deny/ask layer must judge them, or `undefined` for a command this
  * lane cannot read.
@@ -466,6 +489,35 @@ export declare function ruleLaneSegmentsOf(command: string): readonly string[] |
  * not contain `/ab`. Both sides are expected to be canonical already.
  */
 export declare function pathWithinRoot(path: string, root: string): boolean;
+/**
+ * The LEXICAL NORMALIZER for a CALL's target path (design/382 §2.2 — the rule family's one path
+ * identity is the lexical normal form, zero IO): collapse slash runs and `.` segments, resolve `..`
+ * segments textually, and answer the one-leading-slash absolute spelling — or `undefined` when no
+ * such spelling exists (a relative path, a `..` climbing past the root, an empty result). RULE
+ * bodies never come through here (their canonical spelling is unique and non-normal spellings are
+ * refused at the validator); this is for the comparison INPUT a caller derives from a live call.
+ */
+export declare function lexicalNormalAbsolutePathOf(path: string): string | undefined;
+/**
+ * design/382 §2.5 — the ONE admission predicate of the Read directory rule family, beside
+ * {@link ruleAdmitsCommand} as its path-lane sibling. Four consumers share it (the minting round
+ * trip, the coverage table, the gate conjunction arm, and the gate's Read lane) so there is no
+ * second fact source anywhere.
+ *
+ * `path` is the caller's ALREADY-RESOLVED lexical-normal absolute path — the same path identity the
+ * deployment's read adjudication judged the call with (for the Read tool face), or the cd resolver's
+ * output (for the Bash cd-segment face). This predicate NORMALIZES NOTHING: a non-normal spelling
+ * (a `.`/`..` segment, a doubled slash, a relative path) is refused outright, fail-closed, so a
+ * caller cannot smuggle a second path identity through the comparison. Containment is the
+ * word-boundary one ({@link pathWithinRoot}: `/a` never reaches `/ab`).
+ *
+ * What it never does, stated as loudly as what it does (§2.5): admits READS ONLY — a rule of this
+ * family never admits a write, never a whole Bash command, never a non-cd segment — and it clears
+ * ASKS only, never a filesystem fence: workspace containment, the sensitive-read deny face and every
+ * violation refusal judge exactly as they would without the rule (a fence refusal is structural, not
+ * an ask, so there is nothing here for it to clear).
+ */
+export declare function directoryRuleAdmits(rule: Pick<PersistedAllowRule, "tool" | "match" | "command">, path: string): boolean;
 /** Does a rule's scope cover a task running in `cwd` (and, for the session dimension, in the session
  *  named by `sessionId`)? A project rule needs a cwd to compare against; without one it covers nothing
  *  (fail-closed). A session rule (design/382 §4.3) covers a call iff the call's `sessionId` equals the
@@ -556,6 +608,11 @@ export declare function findAdmittingRule(rules: readonly PersistedAllowRule[],
     command: string;
     cwd: string | undefined;
     sessionId?: string;
+    /** The directory RELATIVE cd targets resolve against — the live TRACKED working directory of the
+     *  execution seat (adversarial-review P1: after an earlier observable `cd`, the shell resolves
+     *  `./x` against the moved cursor, not the task root). Defaults to `cwd`; the scope/eligibility
+     *  axis stays `cwd` either way. */
+    execCwd?: string;
 }): readonly PersistedAllowRule[] | undefined;
 /**
  * design/375 §5.2 — the per-segment coverage table for `command`: which segments an eligible rule
@@ -597,6 +654,9 @@ export declare function segmentCoverageOf(command: string, rules: {
     tool: string;
     cwd: string | undefined;
     sessionId?: string;
+    /** The relative-cd resolution base (see {@link findAdmittingRule}'s member of the same name) —
+     *  defaults to `cwd`; scope/eligibility stays `cwd`. */
+    execCwd?: string;
 }): readonly SegmentCoverage[] | undefined;
 /** One row of a per-segment coverage table (see {@link segmentCoverageOf}): the FOLDED, trimmed
  *  segment text (a display/correlation seat, never adjudication input) and whether an eligible rule
@@ -626,6 +686,34 @@ export interface SegmentRuleSuggestion {
      *  show a reader something other than what they authorize. */
     readonly segment: string;
 }
+/**
+ * design/382 §2.3 (B3, BREAKING) — one member of a batch offer, a DISCRIMINATED union keyed by
+ * `kind`:
+ *
+ *  · `kind: "command"` — the historical shape: a per-segment Bash rule
+ *    ({@link SegmentRuleSuggestion}'s four seats, plus the discriminant).
+ *  · `kind: "directoryRead"` — a DIRECTORY READ AUTHORIZATION minted from a cd segment (the §2.4
+ *    floor): `rule` is the canonical `Read(//dir/**)` text, `directory` the lexical-normal absolute
+ *    directory (a render seat, spared a re-parse), `segment` the folded cd segment it came from (a
+ *    rendering-context seat like its command sibling's — never adjudication input).
+ *
+ * CONSUMER DEGRADE ARM (normative, design/382 §2.3): a batch member whose `kind` is outside this set
+ * drops the WHOLE batch offer — never the single member (a conjunction batch silently one member
+ * short renders "yes to N" as "yes to N−1", worse than not rendering), and never the whole card (the
+ * exact single beside it is intact and honest). Selection indices stay keyed on the ORIGINAL wire
+ * offer order.
+ */
+export type RuleOfferBatchMember = (SegmentRuleSuggestion & {
+    readonly kind: "command";
+}) | {
+    readonly kind: "directoryRead";
+    /** The canonical rule text the host would redeem — `Read(//a/b/**)`. */
+    readonly rule: string;
+    /** The lexical-normal absolute directory the rule names — a render seat, no re-parse needed. */
+    readonly directory: string;
+    /** The (folded) cd segment this authorization came from — rendering context, never adjudication input. */
+    readonly segment: string;
+};
 /**
  * design/375 §3.1 — ONE "don't ask again" option on an approval card. A CLOSED discriminated union
  * (`kind`); consumers parse it per element, and an element whose `kind` they do not know is dropped
@@ -639,7 +727,10 @@ export interface SegmentRuleSuggestion {
  *    is one yes to ALL of `rules` at once — there is no per-member selection inside a batch; a
  *    consumer that wants a narrower answer picks the single offer or approves once without a rule.
  *    `rules` has 1..5 members (the card-lane minting cap), in segment order, deduplicated by rule
- *    text. `uncoveredSegments` is the honest surplus disclosure of the cap: judged at MINT time
+ *    text, each a {@link RuleOfferBatchMember} (design/382 B3: the member form is a discriminated
+ *    union — a cd segment of a project-scope card mints a `directoryRead` member, one accept lands
+ *    commands and directory authorization together, the upstream single-line merged-consent form).
+ *    `uncoveredSegments` is the honest surplus disclosure of the cap: judged at MINT time
  *    against the coverage snapshot the card was drawn from ∪ this batch's FINAL (deduplicated,
  *    capped) rules, it counts the violating segments still admitted by neither — 0 means "once this
  *    batch is redeemed, this compound is fully covered by that snapshot's lights". It is a statement
@@ -666,12 +757,72 @@ export type RuleOffer = {
     readonly command: string;
 } | {
     readonly kind: "batch";
-    /** 1..5 per-segment rules, segment order, deduplicated by rule text. */
-    readonly rules: readonly SegmentRuleSuggestion[];
+    /** 1..5 per-segment members, segment order, deduplicated by rule text (design/382 B3: the
+     *  member form is the {@link RuleOfferBatchMember} discriminated union). */
+    readonly rules: readonly RuleOfferBatchMember[];
     /** Mint-time honest surplus: violating segments admitted by neither the coverage snapshot nor
      *  this batch's final rules (see the union doc above for the exact arithmetic). */
     readonly uncoveredSegments: number;
+    /**
+     * design/382 §3.5 — WHY each of those segments stays uncovered, one row per counted segment,
+     * segment order (same text repeated = two rows; the correspondence is positional, never a raw
+     * text dedup). Minted in the SAME pass as `uncoveredSegments` off the same snapshot, so
+     * `uncoveredDetail.length === uncoveredSegments` whenever the seat is present; the count seat
+     * stays the truth source, and ABSENCE (an older minter, a degraded consumer's re-emit) is not
+     * a claim. `segment` is the folded, trimmed segment text — a display/correlation seat carrying
+     * raw command bytes (render like its siblings, {@link renderUntrustedCommandText}); `reason`
+     * is the closed set {@link UncoveredSegmentDetail} documents. Additive on the wire (an unknown
+     * key inside a known kind — old consumers read the batch exactly as before); on the CONSENT
+     * RECORD's card batch the seat is REQUIRED (schema: 3) — see the record's own contract.
+     */
+    readonly uncoveredDetail?: readonly UncoveredSegmentDetail[];
 };
+/** design/382 §3.5 — the closed reason set for one uncovered segment of a batch offer.
+ *
+ *  · `"redirection"` — the segment carries a shell redirection: refused by discipline (#490 修①,
+ *    §3.2), PERMANENTLY per-ask — no rule text can cover this spelling; the honest outlet is a rule
+ *    for its redirection-free form, if the person trusts that form.
+ *  · `"no_rule_form"` — neither the segment's prefix nor its exact form survives the mint round
+ *    trip (a glob argument, an over-length line): nothing coverable exists for these bytes, and
+ *    guidance deliberately does NOT point at hand-writing a rule — the same grammar refuses the
+ *    same text on every door.
+ *  · `"cap_overflow"` — the segment minted a rule, but the batch's dedup+cap left it out and no
+ *    surviving member admits it: covered next time it comes up, asked about until then.
+ *
+ * These are WIRE-STRUCTURED facts, and that is the whole §3.6 point (recorded here so the design's
+ * half-radius is visible in the code): the reader is not only a person. A model or harness that
+ * keeps meeting `redirection` on a spelling it retries can re-run the redirection-free form —
+ * which HAS a coverable rule — with zero new mechanism on this side; a structured honest refusal
+ * is programmable, exactly like a loud bad-value error. The baseline person-facing sentences are
+ * {@link UNCOVERED_SEGMENT_REASON_BASELINE}. */
+export interface UncoveredSegmentDetail {
+    /** The folded, trimmed segment text — raw post-rewrite command bytes, same contract as
+     *  {@link SegmentRuleSuggestion.segment}. */
+    readonly segment: string;
+    readonly reason: "redirection" | "no_rule_form" | "cap_overflow";
+}
+/**
+ * design/382 §3.5-2 — the BASELINE "why + outlet" sentence per uncovered-segment reason: the
+ * one-source copy a surface renders beside the §3.5 detail rows. A surface may reword these, never
+ * invert them (the same contract as {@link renderUntrustedCommandText}: adopt the baseline, or own
+ * an equivalent-strength rewrite). Load-bearing asymmetries, deliberate:
+ *  · `redirection` points at the redirection-FREE form's outlets (that form is coverable);
+ *  · `no_rule_form` points at NOTHING but per-use approval — hand-writing is not suggested,
+ *    because the same grammar refuses the same text on every door, and pointing a person at a rule
+ *    that can never take effect is the exact defect this surface exists to remove;
+ *  · `cap_overflow` promises only honesty: not covered by this batch, asked again when met.
+ */
+export declare const UNCOVERED_SEGMENT_REASON_BASELINE: Readonly<Record<UncoveredSegmentDetail["reason"], string>>;
+/**
+ * design/382 §3.5-2 — the BASELINE sentence per card-level offer-ABSENCE reason (#490 修②'s typed
+ * seat: `ruleOffersAbsence` on the ask and its durable park twin; the closed vocabulary is declared
+ * literally at those two faces, and this table spells the same literals — the copy row is data, not
+ * the type's home). Same reword-never-invert contract as the table above. The load-bearing
+ * asymmetry: `mandated` must NOT point at writing rules — on a mandated ask no rule is consulted,
+ * and directing a person to mint one that can never take effect is the #457④ anti-shape; the other
+ * two reasons name their real outlets.
+ */
+export declare const RULE_OFFERS_ABSENCE_BASELINE: Readonly<Record<"mandated" | "lane_cannot_speak" | "shadowed", string>>;
 /**
  * The offers presented on an approval card for `command` (design/375 §5.2).
  *
@@ -740,4 +891,47 @@ export type RuleOffer = {
  */
 export declare function suggestRulesForCommand(command: string, ctx?: {
     readonly coverage?: readonly SegmentCoverage[];
+    /**
+     * design/382 §2.4-7 — the SCOPE the card's candidates would land in, the directoryRead mint
+     * gate's first input: a cd segment mints a directory member ONLY when this scope is a PROJECT
+     * or SESSION scope that also COVERS the adjudicated call (the second conjunct, through the one
+     * scope predicate — a scope that does not cover the deciding call would mint a member that is
+     * never eligible where it was minted, the offer-that-never-works shape). The SESSION arm is the
+     * §8-Q3 re-ruling (opened at final sign-off: the upstream session destination is exactly this
+     * grant's home, and a session-scope member is a pure narrowing of the project one). GLOBAL
+     * stays closed — a directory grant is place-and-time consent, and the everywhere spelling is
+     * the explicit channels' business. Absent ⇒ the gate is closed and a cd segment falls back to
+     * its command member (the pre-382 behaviour, byte-for-byte).
+     */
+    readonly scope?: RuleScope;
+    /**
+     * The adjudicated call's working directory (threaded from the original call context, never the
+     * process — the same value the coverage read and the gate judged with). Two consumers: the
+     * `./`-relative cd resolution, and the scope gate's coverage conjunct. Absent ⇒ no relative cd
+     * resolves and a project-scope gate is closed.
+     */
+    readonly cwd?: string;
+    /**
+     * The relative-cd RESOLUTION base — the live tracked working directory of the execution seat
+     * (adversarial-review P1: after an earlier observable `cd`, the shell resolves `./x` against the
+     * moved cursor, not the task root — a member minted off the wrong base names a directory the cd
+     * never enters). Defaults to `cwd`; the scope gate's coverage conjunct stays on `cwd`.
+     */
+    readonly execCwd?: string;
+    /**
+     * The adjudicated call's SESSION identity (threaded like `cwd`, never inferred) — the session
+     * arm's coverage conjunct: a session-scope card mints a directory member only when its scope
+     * names THIS session. Absent ⇒ no session scope covers anything (fail-closed, the shared
+     * predicate's own arm).
+     */
+    readonly sessionId?: string;
+    /**
+     * design/382 §2.4-6 — the deployment's sensitive-read negative control, SAME-SOURCE with its
+     * compiled read-deny judge (`ReadDenyMatcher.matchPath !== null` is the canonical wiring): the
+     * engine never PROPOSES a directory authorization for a directory this judge names. Absent ⇒
+     * the built-in default deny table stands in (refusal-only; a deployment with a wired judge
+     * passes its own so the two faces cannot disagree). Explicit-consent doors (hand-written,
+     * import) are deliberately NOT behind this — they have their own preview and validation.
+     */
+    readonly deniesDirectoryRead?: (directory: string) => boolean;
 }): RuleOffer[];