@sema-agent/core 7.9.0 → 7.9.2

package/dist/core/mcp-injection-drop.d.ts

@@ -0,0 +1,74 @@
+/**
+ * `mcp.injection_dropped` — the one mint of the notice a host raises when an entry of the user's own
+ * MCP injection (a `.mcp.json` row handed to the engine through the host's request lane) was NOT
+ * mounted for the leg. L-167: three drop sites in the host's intake and one cap site each produced
+ * their own wording and none reached the user; the engine did not see the entry at all (it never
+ * reached `prepareTask`), so no core-side notice could stand for it.
+ *
+ * Division of labour, the settlement pattern (`settlement.single_mint`): the HOST supplies FACTS
+ * (which session, which server name, which of four reasons, optionally which field was bad) and
+ * CORE composes the notice — the code word, the audience row, the message text per reason. A host
+ * never spells the code or the text itself: a second wording is a second source that drifts, and a
+ * host-spelled code is not in {@link import("./governance-codes.js").ENGINE_NOTICE_CODES}'s
+ * mint scan, so its audience row could silently rot.
+ *
+ * Audience `"user"`: the dropped entry is the user's own configuration and the recovery (rename the
+ * server, fix the field, trim the list) is in their hands — an operator channel does not reach them.
+ * `sessionId` is therefore REQUIRED at the mint (the routing half of a user row: a user disclosure
+ * that cannot name its session has nowhere to be delivered) — a host with no session has no user to
+ * tell and must not mint. Dedup unit: per leg per server name — the HOST's obligation (it owns the
+ * leg's intake loop); this module is pure.
+ */
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+import type { EngineNotice } from "./engine-notice.js";
+/**
+ * The closed set of drop reasons ({@link McpInjectionDropFacts.reason}) — the host's intake
+ * enumerates exactly these, and a consumer rendering the notice keys on the word:
+ *  · `malformed_entry`              — the entry did not parse as a server declaration (a missing
+ *                                     `command`/`url`, a `toolFaces` value of the wrong shape, …);
+ *                                     `field` names the offending key when the host knows it;
+ *  · `name_reserved_by_deployment`  — the entry's server name collides with one the deployment
+ *                                     itself mounts, and the deployment's wins;
+ *  · `gate_closed`                  — the deployment does not accept request-lane MCP injection on
+ *                                     this leg at all (a multi-tenant posture): the whole list is
+ *                                     ignored, one notice per entry;
+ *  · `over_cap`                     — the entry sits beyond the deployment's injection cap.
+ */
+export declare const MCP_INJECTION_DROP_REASONS: readonly ["malformed_entry", "name_reserved_by_deployment", "gate_closed", "over_cap"];
+export type McpInjectionDropReason = (typeof MCP_INJECTION_DROP_REASONS)[number];
+/**
+ * The user-facing sentence per reason — the disposition table over {@link MCP_INJECTION_DROP_REASONS}
+ * (one reason, one wording; a consumer that wants its own phrasing keys on `detail.reason`, never on
+ * this text). Each names the recovery, because the reader is the person who can perform it.
+ */
+export declare const MCP_INJECTION_DROP_TEXT: {
+    readonly malformed_entry: "its declaration could not be read — fix the entry and start a new session";
+    readonly name_reserved_by_deployment: "the deployment mounts a server of that name and its own wins — rename the entry";
+    readonly gate_closed: "this deployment does not accept MCP servers from the request on this leg — ask the operator, or use the deployment's servers";
+    readonly over_cap: "the request named more MCP servers than this deployment mounts per leg — trim the list";
+};
+export type DropTextCoversEveryReason = AssertAllKeysHandled<Exclude<McpInjectionDropReason, keyof typeof MCP_INJECTION_DROP_TEXT>>;
+/** What a host knows at the drop site — facts only, no words of the engine's vocabulary composed. */
+export interface McpInjectionDropFacts {
+    /** The session whose injection carried the entry — the notice's routing key, required (see module note). */
+    readonly sessionId: string;
+    /** The entry's server name as the user spelled it (the message quotes it verbatim). */
+    readonly server: string;
+    readonly reason: McpInjectionDropReason;
+    /** `malformed_entry` only, optional: the key the host found bad, so the user knows what to edit. */
+    readonly field?: string;
+}
+/**
+ * Compose the `mcp.injection_dropped` notice from a host's facts.
+ *
+ * @contract mcp.injection_dropped.single_mint — the `mcp.injection_dropped` notice is composed by CORE
+ * from a host's drop FACTS (session, server name, one of four reasons, optionally the bad field); a
+ * host never spells the code, the audience or the sentence, and a fact outside the vocabulary (an
+ * unlisted reason word, an empty session or server name) is refused at the mint with a `TypeError`
+ * rather than shaped into a notice that would route nowhere or read as an unknown word downstream.
+ *
+ * `detail: { sessionId, server, reason, field? }` — `sessionId` is lifted onto the typed key by
+ * {@link import("./engine-notice.js").deliverEngineNotice}, the one throat, so the two spellings
+ * cannot disagree; `field` is present only when the host supplied a non-empty one.
+ */
+export declare function mcpInjectionDroppedNotice(facts: McpInjectionDropFacts): EngineNotice;

package/dist/core/mcp-injection-drop.js

@@ -0,0 +1,27 @@
+export const MCP_INJECTION_DROP_REASONS = ["malformed_entry", "name_reserved_by_deployment", "gate_closed", "over_cap"];
+export const MCP_INJECTION_DROP_TEXT = {
+    malformed_entry: "its declaration could not be read — fix the entry and start a new session",
+    name_reserved_by_deployment: "the deployment mounts a server of that name and its own wins — rename the entry",
+    gate_closed: "this deployment does not accept MCP servers from the request on this leg — ask the operator, or use the deployment's servers",
+    over_cap: "the request named more MCP servers than this deployment mounts per leg — trim the list",
+};
+const isReason = (x) => typeof x === "string" && MCP_INJECTION_DROP_REASONS.includes(x);
+export function mcpInjectionDroppedNotice(facts) {
+    const { sessionId, server, reason, field } = facts;
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+        throw new TypeError("mcp.injection_dropped: sessionId is required — a user-audience notice with no session routes nowhere");
+    }
+    if (typeof server !== "string" || server.length === 0) {
+        throw new TypeError("mcp.injection_dropped: server name is required");
+    }
+    if (!isReason(reason)) {
+        throw new TypeError(`mcp.injection_dropped: reason ${JSON.stringify(reason)} is not one of ${MCP_INJECTION_DROP_REASONS.join("/")}`);
+    }
+    const fieldSeat = typeof field === "string" && field.length > 0 ? { field } : {};
+    const where = reason === "malformed_entry" && typeof field === "string" && field.length > 0 ? ` (field \`${field}\`)` : "";
+    return {
+        code: "mcp.injection_dropped",
+        message: `MCP server "${server}" from this request was not mounted: ${MCP_INJECTION_DROP_TEXT[reason]}${where}.`,
+        detail: { sessionId, server, reason, ...fieldSeat },
+    };
+}

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

@@ -14,11 +14,12 @@
  *
  * The two DIRECTIONS read a command differently, on purpose: an allow must cover the WHOLE call
  * ({@link ruleAdmitsCommand} — one recorded yes clears exactly what it spells), while a deny/ask
- * speaks about any PROGRAM RUN the call may perform ({@link ruleReachesProgramRun} — whole command or
- * any segment of a chain, the wider tightening reading). Precedence across behaviors is the upstream
- * one, deny > ask > allow ({@link RULE_BEHAVIOR_PRECEDENCE}, the one table every adjudication reads).
+ * speaks about any PROGRAM RUN the call may perform ({@link programRunReachOf} — whole command or
+ * any segment of a chain, read with a real shell lexer, `shell-lexer.ts`, and answering `unreadable`
+ * for what it cannot read rather than silence). Precedence across behaviors is the upstream one,
+ * deny > ask > allow ({@link RULE_BEHAVIOR_PRECEDENCE}, the one table every adjudication reads).
  *
- * ## The floor: what a rule may name, and what a rule may match
+ * ## The floor: what a rule may name, and what a rule may match (the ALLOW direction)
  *
  * Everything a shell can use to run a program the text does not NAME — substitution, subshells,
  * backgrounding, escapes, line breaks, and **redirection** — puts the command outside this lane
@@ -52,7 +53,9 @@
  * The floor is `parseLeadingCommandName` + `splitShellCompoundSegments` — the one simple-command parser
  * and the one segmentation, both already shared with the read-only classifier, the reversibility probe,
  * the coarse command-name policy and the skill tool specifier. A second tokenizer would drift, and drift
- * on a loosening face shows up as a circumvention rather than as a test failure.
+ * on a LOOSENING face shows up as a circumvention rather than as a test failure. The tightening
+ * direction's lexer is not that second tokenizer: it reads MORE than the floor (never less), and a
+ * drift there costs an approval prompt, never a standing approval.
  *
  * argv[0] may carry a PATH prefix here (`./gradlew`, `/usr/bin/git`) — opt-in at the shared parser and
  * used by this lane alone. The bare-name requirement belongs to the argv[0]-NAME filters, which compare
@@ -337,18 +340,16 @@ export declare const BARE_INTERPRETER_NAMES: ReadonlySet<string>;
  * Shell KEYWORDS, refused as a segment's `argv[0]` everywhere this lane reads a command.
  *
  * The floor this lane stands on extracts the first TOKEN of a segment and calls it the command name.
- * That identification is what every comparison here rests on — the interpreter refusal, the deny/ask
- * layer's per-segment judgement, and a person's reading of the rule text. For a control structure it is
- * simply false. `for x in once; do curl evil.example; done` splits into three segments whose first
- * tokens are `for`, `do` and `done`; all three are ordinary bare words, so the floor accepts each,
- * `curl` is named by nothing, and a published `deny Bash(curl:*)` matches none of them while bash runs
- * curl. A whole loop body — any number of programs — hides behind three tokens that name no program.
- *
- * Refusing the keyword puts the whole command outside the lane, which is the honest answer: no rule can
- * be minted for it and no rule matches it, so it asks. Recovering these shapes properly needs a real
- * shell grammar (upstream has one — it parses to a syntax tree and reads the commands out of the
- * structure, so a keyword is never mistaken for a program); a token-level lane cannot, and pretending
- * otherwise is the loosening direction.
+ * That identification is what every comparison here rests on — the interpreter refusal and a person's
+ * reading of the rule text. For a control structure it is simply false: `for x in once; do curl
+ * evil.example; done` splits into three segments whose first tokens are `for`, `do` and `done`; all
+ * three are ordinary bare words, so the floor accepts each, and a rule text could name a keyword as
+ * though it were a program.
+ *
+ * Refusing the keyword puts the whole command outside the ALLOW lane, which is the honest answer: no rule
+ * can be minted for it and no allow matches it, so it asks. The DENY/ASK direction reads these shapes
+ * with its own lexer (`shell-lexer.ts`: a prefixing keyword is stripped so `do curl evil.example` runs
+ * `curl`; a `for`/`case` header, whose commands need a syntax tree, is `unreadable` and asks).
  *
  * `!` is here for the same reason with a sharper edge: it is a keyword that PREFIXES a real command, so
  * `! node -e …` is the `node` licence the interpreter table exists to refuse, wearing one extra token.
@@ -537,50 +538,71 @@ export declare function pathRuleReaches(rule: Pick<PersistedRule, "match" | "com
  */
 export declare function ruleAdmitsCommand(rule: Pick<PersistedRule, "match" | "command">, command: string): boolean;
 /**
- * The same match, asked the DENY/ASK layer's question — "does this rule speak about this program run?".
- *
- * Split from {@link ruleAdmitsCommand} because the two differ on one axis that decides real cases: a
- * quoted operator. `curl "https://x/?a=1&b=2"` is ONE command bash runs, and the `&` in a query string
- * is not a connector; the matching side refuses it anyway (a rule text is a spelling with no operator
- * characters in it at all — the historical rule-face contract), and the deny side inheriting that
- * refusal made `deny Bash(curl:*)` silent on the commonest spelling of the very program it names
- * (adversarial round 3).
- *
- * The asymmetry only ever runs one way: this predicate reads MORE commands than the matching one, never
- * fewer. A shape only the ALLOW side could read would be a standing approval no published policy could
- * see — the inversion this whole ticket exists to prevent.
+ * What one TIGHTENING (deny/ask) rule can say about a call — the closed three-word answer of
+ * {@link programRunReachOf}:
+ *  - `reached` — the text PROVABLY performs a run the rule names (the whole chain, or any one segment);
+ *  - `not_reached` — the text provably does not (every compared word is literal and differs, or the
+ *    command is shorter than the rule's body);
+ *  - `unreadable` — the text MAY perform it but cannot be read: an expansion sits where the rule reads a
+ *    word, a quote or substitution never closes, a syntax error, a control structure whose commands need
+ *    a syntax tree, a wrapper handed its command as one string.
+ * The three lanes that consume it (the org partition, the personal deny/ask rows, the rule DSL's
+ * content-form rules) dispose of the words identically: `reached` speaks with the rule's behavior,
+ * `not_reached` is silence, and `unreadable` is a FAIL-CLOSED ask — never silence, which is what once let
+ * `rm -r x; echo "$HOME"` walk past a deny on `rm -r` because one expansion took the whole line out of
+ * the reader. Registered in docs/CLOSED-SETS.md.
  */
-export declare function ruleAdmitsProgramRun(rule: Pick<PersistedRule, "match" | "command">, command: string): boolean;
+export declare const PROGRAM_RUN_REACHES: readonly ["reached", "not_reached", "unreadable"];
+export type ProgramRunReach = (typeof PROGRAM_RUN_REACHES)[number];
+/** The answer of {@link programRunReachOf}: the word, and for `unreadable` the reason a surface can show. */
+export type ProgramRunReachOutcome = {
+    readonly reach: "reached" | "not_reached";
+} | {
+    readonly reach: "unreadable";
+    readonly reason: string;
+};
 /**
  * Does one TIGHTENING (deny/ask) rule speak about this call — as a whole, or about any single program
- * run in it? The ONE reach predicate of the tightening direction, shared by the org partition, the
- * personal deny/ask rows and the rule DSL's content-form deny/ask rules, so no two of them can disagree
- * about what a deny reaches.
+ * run in it — or can the call not be read against it at all? The ONE reach predicate of the tightening
+ * direction, shared by the org partition, the personal deny/ask rows and the rule DSL's content-form
+ * deny/ask rules, so no two of them can disagree about what a deny reaches.
  *
  * The allow lane asks a different question and gets a different answer, deliberately. An allow rule is
- * one recorded human yes and must cover the WHOLE call to clear it: `Bash(npm test)` does not clear
- * `npm test && curl evil.example`, because nobody said yes to the second half. A deny/ask rule is a
- * standing statement about a program run, and a call that MAY perform that run is a call the rule
- * speaks about — so a segment hit is a hit. Deliberately an OVER-approximation, in the tightening
- * direction: the segments are the runs the text can reach, not the runs that will happen, so a
- * short-circuited branch (`true || curl evil.example`) and a commented-out tail
- * (`echo ok # ; curl evil.example`) are judged as though they ran. Answering "does this definitely
- * execute" needs evaluation, not parsing; over-firing costs an approval prompt, and the opposite error
- * costs the rule. Reading the compound as one unmatched blob is what once made `deny Bash(curl:*)`
- * silent on `npm test && curl evil.example`: a rule standing on paper and matching nothing in fact.
- *
- * `ruleAdmitsProgramRun`, not `ruleAdmitsCommand`, on BOTH arms — this direction asks which programs
- * the call runs, and the matching predicate refuses a quoted operator that is ordinary argument text
- * (a `&` inside a URL); inheriting that refusal here silenced a deny on the commonest curl spelling.
- * EVERY segment is judged, including the sole segment of a one-element list: the two readings differ
- * on terminator handling, so `curl evil.example;` has a single segment `curl evil.example` that the
- * whole-command arm refuses and this arm must still see (a trailing `;` once carried a chain past the
- * fence). A command the lane cannot read at all (a redirection, a substitution) has no segments; the
- * whole-command arm still runs and answers false, as it always did — those shapes are refused upstream.
- *
- * A path-family rule (`subpath` / `path`) reaches no command: its predicates are {@link directoryRuleAdmits}
- * and {@link pathRuleReaches}.
+ * one recorded human yes and must cover the WHOLE call to clear it ({@link ruleAdmitsCommand}:
+ * `Bash(npm test)` does not clear `npm test && curl evil.example`, because nobody said yes to the second
+ * half), and it refuses every shell construct outright. A deny/ask rule is a standing statement about a
+ * program run, and a call that MAY perform that run is a call the rule speaks about — so this direction
+ * reads the command with a real lexer ({@link readShellCommand}): redirections are stripped at the
+ * token level, quotes are removed on BOTH sides before words are compared (`rm "-r" x` runs `rm -r x`),
+ * wrappers are peeled (`sudo env X=1 nohup rm -r x` runs `rm -r x`), every connector — `&` and a newline
+ * included — bounds a segment, and a comment is not a run. Deliberately an OVER-approximation, in the
+ * tightening direction: the segments are the runs the text can reach, not the runs that will happen, so
+ * a short-circuited branch (`true || curl evil.example`) is judged as though it ran. Answering "does this
+ * definitely execute" needs evaluation, not parsing; over-firing costs an approval prompt, and the
+ * opposite error costs the rule.
+ *
+ * Words are compared ARGV-wise, position by position, against the rule body read by the same lexer —
+ * over every run CANDIDATE a segment carries: as spelled, then each peeled layer (`sudo rm -r x` is a run
+ * of `sudo …` AND of `rm -r x`; a deny on either reaches; a rule body is never peeled, so
+ * `Bash(sudo rm -r x)` denies exactly that). A literal word that differs settles `not_reached`; a word
+ * carrying an expansion at a position the rule reads settles `unreadable` (the text could spell the
+ * rule's word there — unless it is the SAME glob/brace spelling the body wrote); a prefix body whose
+ * every word is matched is `reached` whatever follows; an exact body needs equal length — a longer
+ * command is `not_reached` unless an extra word is an UNQUOTED expansion (or `"$@"` / an array
+ * expansion), which may expand to nothing. The commands inside a substitution and an unquoted heredoc
+ * body are segments of their own (`echo "$(rm -r x)"` runs `rm`). A compound
+ * body (`Bash(echo ok && rm -r:*)`) reaches only a chain of the same shape — same segment count, same
+ * connectors, every leading segment equal, the final one by the body's match kind; a single-segment
+ * body reaches any segment. A segment the lexer could not read makes the answer `unreadable` when no
+ * other segment already reached.
+ *
+ * A rule body the lexer cannot read (foreign store bytes; every entrance validates against exactly
+ * this) reaches nothing. A path-family rule (`subpath` / `path`) reaches no command: its predicates are
+ * {@link directoryRuleAdmits} and {@link pathRuleReaches}.
  */
+export declare function programRunReachOf(rule: Pick<PersistedRule, "match" | "command">, command: string): ProgramRunReachOutcome;
+/** The boolean face of {@link programRunReachOf}: `reached` only. The shadow view and the pins that
+ *  assert a reach read this; a lane that must fail closed on `unreadable` reads the outcome. */
 export declare function ruleReachesProgramRun(rule: Pick<PersistedRule, "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 —
@@ -620,20 +642,6 @@ export interface EditedRuleBreadthWarning {
  * superset disclosure (registered divergence, design/382 §6-4).
  */
 export declare function ruleBreadthWarningsOf(rule: Pick<PersistedRule, "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.
- *
- * A tightening rule speaks about a PROGRAM RUN, and a compound runs several. `Bash(curl:*)` published
- * as a deny means "this machine does not make that call", and reading `npm test && curl evil.example`
- * as one unmatched blob answered that with silence — the shape the widening above would otherwise make
- * permanently approvable. Exported (rather than folded into a matcher here) because the layer that
- * needs it holds the rules: this module owns what a command IS, `permission-rule-org.ts` owns what the
- * organization says about each part of it.
- *
- * A single simple command yields a one-element list, so a deny that matched before matches identically.
- */
-export declare function ruleLaneSegmentsOf(command: string): readonly string[] | undefined;
 /**
  * Is `path` inside (or equal to) `root`? Word-boundary containment on the path separator, so `/a` does
  * not contain `/ab`. Both sides are expected to be canonical already.
@@ -780,6 +788,11 @@ export declare function findAdmittingRule(rules: readonly PersistedRule[], call:
 export interface PersistedRuleVerdict {
     readonly behavior: RuleBehavior;
     readonly rules: readonly PersistedRule[];
+    /** The call could not be READ against the person's deny/ask rows (see {@link programRunReachOf}):
+     *  `behavior` is `ask`, `rules` names the first tightening row that could not be judged, and this is
+     *  the lexer's reason. The lane projects it as an UNREADABLE answer — the same fail-closed shape an
+     *  unreadable store takes — never as a matched ask rule. */
+    readonly unreadable?: string;
 }
 /**
  * The ONE adjudication over a MIXED persisted-rule table for a shell call: walk the behaviors in
@@ -787,12 +800,15 @@ export interface PersistedRuleVerdict {
  * for the call — deny before ask before allow, the upstream arbiter's order across its three lists.
  *
  * Each behavior is judged with ITS direction's instrument: a deny/ask row through
- * {@link ruleReachesProgramRun} (the wide tightening reading: whole command or any program run in
- * it), an allow through {@link findAdmittingRule} (the narrow reading: the whole call, or every segment
- * of it, covered by recorded yeses). The asymmetry is the point and runs one way only: a deny reads
- * MORE of a command than an allow does, so an exact allow naming a whole chain can never outrun a deny
- * on one of its parts. Eligibility (live, this tool, scope covers the call, THIS behavior) is the one
- * predicate every consumer shares. `undefined` ⇒ no rule of any behavior speaks.
+ * {@link programRunReachOf} (the wide tightening reading: whole command or any program run in it,
+ * three-valued), an allow through {@link findAdmittingRule} (the narrow reading: the whole call, or
+ * every segment of it, covered by recorded yeses). The asymmetry is the point and runs one way only: a
+ * deny reads MORE of a command than an allow does, so an exact allow naming a whole chain can never
+ * outrun a deny on one of its parts. A call the lexer cannot read against a standing deny/ask row is an
+ * UNREADABLE verdict (`behavior: "ask"` + `unreadable`), returned before any allow is consulted: the
+ * question "does one of my rules forbid this?" is unanswered, and a recorded yes must not answer it.
+ * Eligibility (live, this tool, scope covers the call, THIS behavior) is the one predicate every
+ * consumer shares. `undefined` ⇒ no rule of any behavior speaks.
  */
 export declare function adjudicatePersistedRules(rules: readonly PersistedRule[], call: {
     tool: string;

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

@@ -4,6 +4,7 @@ import { compileReadDeny } from "../tools/fs/read-deny.js";
 import { carriesShellRedirection, parseLeadingCommandName, splitShellCompoundSegments } from "../tools/fs/bash-readonly-classifier.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { pathTargetOf } from "./tool-registry.js";
+import { readShellCommand } from "./shell-lexer.js";
 export const RULE_BEHAVIORS = ["deny", "ask", "allow"];
 const RULE_BEHAVIOR_SET = new Set(RULE_BEHAVIORS);
 export function isRuleBehavior(v) {
@@ -144,7 +145,6 @@ function reject(code, message) {
 }
 const RULE_LANE_FLOOR = { pathPrefixedNameIsText: true };
 const MATCH_READING = { terminator: "keep", quotedOperatorsAreText: false, redirection: "reject" };
-const PROGRAM_RUNS_READING = { terminator: "strip", quotedOperatorsAreText: true, redirection: "reject" };
 const OFFER_READING = { terminator: "keep", quotedOperatorsAreText: false, redirection: "tolerate" };
 function commandBasename(name) {
     return name.slice(name.lastIndexOf("/") + 1);
@@ -418,117 +418,94 @@ function hasUnescapedStar(s) {
 export function ruleAdmitsCommand(rule, command) {
     return admitsUnder(rule, command, MATCH_READING);
 }
-export function ruleAdmitsProgramRun(rule, command) {
-    return admitsUnder(rule, command, PROGRAM_RUNS_READING);
-}
-export function ruleReachesProgramRun(rule, command) {
+export const PROGRAM_RUN_REACHES = ["reached", "not_reached", "unreadable"];
+const REACHED = { reach: "reached" };
+const NOT_REACHED = { reach: "not_reached" };
+export function programRunReachOf(rule, command) {
     if (rule.match === "subpath" || rule.match === "path")
-        return false;
-    if (ruleAdmitsProgramRun(rule, command))
-        return true;
-    const spelled = stripRedirections(stripFdDuplications(command) ?? command) ?? command;
-    if (spelled !== command && ruleAdmitsProgramRun(rule, spelled))
-        return true;
-    const segments = ruleLaneSegmentsOf(spelled);
-    if (segments === undefined)
-        return false;
-    return segments.some((segment) => ruleAdmitsProgramRun(rule, segment));
+        return NOT_REACHED;
+    const body = readRuleBody(rule.command);
+    if (body === undefined)
+        return NOT_REACHED;
+    const shape = readCommandMemo(command);
+    const exact = rule.match === "exact";
+    if (body.segments.length > 1) {
+        const broken = shape.segments.find((s) => s.unreadable !== undefined);
+        if (broken !== undefined)
+            return { reach: "unreadable", reason: broken.unreadable };
+        const hidden = shape.segments.find((s) => s.peelUnreadable !== undefined);
+        const shaped = !shape.grouped && shape.segments.length === body.segments.length && shape.connectors.every((c, i) => c === body.connectors[i]);
+        if (!shaped)
+            return hidden === undefined ? NOT_REACHED : { reach: "unreadable", reason: hidden.peelUnreadable };
+        let outcome = REACHED;
+        for (let i = 0; i < body.segments.length; i++) {
+            const r = segmentReachOf(body.segments[i].argv, shape.segments[i], exact || i < body.segments.length - 1);
+            if (r.reach === "not_reached")
+                return hidden === undefined ? NOT_REACHED : { reach: "unreadable", reason: hidden.peelUnreadable };
+            if (r.reach === "unreadable")
+                outcome = r;
+        }
+        return outcome;
+    }
+    const bodyArgv = body.segments[0].argv;
+    let unreadable;
+    for (const segment of shape.segments) {
+        const r = segmentReachOf(bodyArgv, segment, exact);
+        if (r.reach === "reached")
+            return REACHED;
+        if (r.reach === "unreadable")
+            unreadable ??= r;
+    }
+    return unreadable ?? NOT_REACHED;
 }
-function stripRedirections(command) {
-    const isSpace = (c) => c === " " || c === "\t";
-    const isRedirect = (c) => c === "<" || c === ">";
-    const isConnector = (c) => c === "|" || c === "&" || c === ";";
-    let out = "";
-    let quote;
-    let i = 0;
-    while (i < command.length) {
-        const ch = command[i];
-        if (quote !== undefined) {
-            out += ch;
-            if (ch === quote)
-                quote = undefined;
-            i++;
-            continue;
-        }
-        if (ch === "'" || ch === '"') {
-            quote = ch;
-            out += ch;
-            i++;
-            continue;
-        }
-        if (isRedirect(ch)) {
-            let k = out.length;
-            while (k > 0 && /\d/.test(out[k - 1]))
-                k--;
-            if (k < out.length && (k === 0 || isSpace(out[k - 1]) || isConnector(out[k - 1])))
-                out = out.slice(0, k);
-            let j = i;
-            while (j < command.length && isRedirect(command[j]))
-                j++;
-            if (j < command.length && command[j] === "|" && command[i] === ">" && j === i + 1)
-                j++;
-            while (j < command.length && isSpace(command[j]))
-                j++;
-            if (j < command.length && isConnector(command[j]))
-                return undefined;
-            let q2;
-            while (j < command.length) {
-                const c = command[j];
-                if (q2 !== undefined) {
-                    if (c === q2)
-                        q2 = undefined;
-                    j++;
-                    continue;
-                }
-                if (c === "'" || c === '"') {
-                    q2 = c;
-                    j++;
-                    continue;
-                }
-                if (isSpace(c) || isRedirect(c) || isConnector(c))
-                    break;
-                j++;
-            }
-            if (q2 !== undefined)
-                return undefined;
-            if (out !== "" && !isSpace(out[out.length - 1]))
-                out += " ";
-            i = j;
-            continue;
+export function ruleReachesProgramRun(rule, command) {
+    return programRunReachOf(rule, command).reach === "reached";
+}
+function segmentReachOf(bodyArgv, segment, exact) {
+    if (segment.unreadable !== undefined)
+        return { reach: "unreadable", reason: segment.unreadable };
+    let unreadable;
+    for (const argv of [segment.argv, ...segment.peeled]) {
+        const r = argvReachOf(bodyArgv, argv, exact);
+        if (r.reach === "reached")
+            return REACHED;
+        if (r.reach === "unreadable")
+            unreadable ??= r;
+    }
+    if (segment.peelUnreadable !== undefined)
+        unreadable ??= { reach: "unreadable", reason: segment.peelUnreadable };
+    return unreadable ?? NOT_REACHED;
+}
+function argvReachOf(bodyArgv, argv, exact) {
+    for (let i = 0; i < bodyArgv.length; i++) {
+        const word = argv[i];
+        const wanted = bodyArgv[i];
+        if (word === undefined)
+            return NOT_REACHED;
+        if (word.expands !== false) {
+            if (word.raw === wanted.raw)
+                continue;
+            return { reach: "unreadable", reason: i === 0 ? "the program name is an expansion" : `an expansion (${word.raw}) stands where the rule reads a word` };
         }
-        out += ch;
-        i++;
+        if (word.text !== wanted.text)
+            return NOT_REACHED;
     }
-    if (quote !== undefined)
+    if (!exact || argv.length === bodyArgv.length)
+        return REACHED;
+    const loose = argv.slice(bodyArgv.length).find((w) => w.expands === "many");
+    return loose === undefined ? NOT_REACHED : { reach: "unreadable", reason: `an unquoted expansion (${loose.raw}) may expand to nothing` };
+}
+function readRuleBody(body) {
+    const shape = readShellCommand(body);
+    if (shape.grouped || shape.segments.length === 0)
         return undefined;
-    return out.trim();
+    return shape.segments.every((s) => s.unreadable === undefined && s.argv.length > 0) ? shape : undefined;
 }
-function stripFdDuplications(command) {
-    let out = "";
-    let quote;
-    for (let i = 0; i < command.length; i++) {
-        const ch = command[i];
-        if (quote !== undefined) {
-            out += ch;
-            if (ch === quote)
-                quote = undefined;
-            continue;
-        }
-        if (ch === "'" || ch === '"') {
-            quote = ch;
-            out += ch;
-            continue;
-        }
-        const atWordStart = i === 0 || command[i - 1] === " " || command[i - 1] === "\t" || command[i - 1] === ";" || command[i - 1] === "|" || command[i - 1] === "&";
-        const m = (atWordStart ? /^\d*[<>]&\d+/ : /^[<>]&\d+/).exec(command.slice(i));
-        if (m !== null) {
-            i += m[0].length - 1;
-            out += " ";
-            continue;
-        }
-        out += ch;
-    }
-    return quote === undefined ? out : undefined;
+let lastRead;
+function readCommandMemo(command) {
+    if (lastRead?.command !== command)
+        lastRead = { command, shape: readShellCommand(command) };
+    return lastRead.shape;
 }
 function admitsUnder(rule, command, reading) {
     if (rule.match === "subpath" || rule.match === "path")
@@ -572,10 +549,6 @@ export function ruleBreadthWarningsOf(rule) {
     }
     return [];
 }
-export function ruleLaneSegmentsOf(command) {
-    const shape = ruleLaneShapeOf(command, PROGRAM_RUNS_READING);
-    return "reject" in shape ? undefined : shape.segments;
-}
 export function pathWithinRoot(path, root) {
     if (path === root)
         return true;
@@ -775,12 +748,18 @@ export function adjudicatePersistedRules(rules, call) {
                 return { behavior, rules: covering };
             continue;
         }
+        let unreadable;
         for (const rule of rules) {
             if (!eligiblePersisted(rule, call, behavior))
                 continue;
-            if (ruleReachesProgramRun(rule, call.command))
+            const outcome = programRunReachOf(rule, call.command);
+            if (outcome.reach === "reached")
                 return { behavior, rules: [rule] };
+            if (outcome.reach === "unreadable")
+                unreadable ??= { behavior: "ask", rules: [rule], unreadable: outcome.reason };
         }
+        if (unreadable !== undefined)
+            return unreadable;
     }
     return undefined;
 }

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

@@ -188,8 +188,9 @@ export declare function unenforceableOrgRules(rules: readonly OrgPermissionRule[
  * design/182 §7.2 — which org rule speaks for this command, if any. Deny outranks ask; within a
  * behavior the first textual match wins (reporting order only — all denies are the same one answer).
  * Matching uses the SAME parser and the SAME tightening reach the personal deny/ask rows use
- * ({@link ruleReachesProgramRun}: an interpreter-headed prefix deny like `Bash(node:*)` is a
- * legitimately wide tightening and matches; a segment hit is a hit).
+ * ({@link programRunReachOf}: an interpreter-headed prefix deny like `Bash(node:*)` is a
+ * legitimately wide tightening and matches; a segment hit is a hit; a call the lexer cannot read
+ * against a rule is an ASK with the reason — fail closed, never silence).
  *
  * The skip below is a defensive floor, and what stands behind it is worth stating precisely: rules that
  * arrive from the org partition's `resolve` ({@link createOrgRulePartition}) have passed {@link validateOrgSnapshot} on BOTH the install
@@ -202,10 +203,15 @@ export declare function unenforceableOrgRules(rules: readonly OrgPermissionRule[
 export declare function orgRuleVerdictFor(rules: readonly OrgPermissionRule[], call: {
     tool: string;
     command: string;
-}): {
-    behavior: "deny" | "ask";
-    rule: string;
-} | undefined;
+}): OrgRuleVerdict | undefined;
+/** The org layer's answer for one call: which rule spoke, with what behavior — and, when the call could
+ *  not be READ against the org's rules, the lexer's reason beside the first rule it could not judge
+ *  (`behavior` is then `ask`: the org published a rule that may reach this call, and nobody can say). */
+export interface OrgRuleVerdict {
+    readonly behavior: "deny" | "ask";
+    readonly rule: string;
+    readonly unreadable?: string;
+}
 /**
  * design/182 §7.3 / design/389 — the SHADOW predicate the unified store's read face applies to every
  * personal allow row: does an org DENY reach this rule's own command pattern? An org deny does not