@sema-agent/core 7.9.2 → 7.11.0

package/dist/core/hooks.d.ts

@@ -5,7 +5,7 @@ import type { GateOutcome } from "./gate-outcome.js";
 export { normalizeOrgGateVerdict, normalizePersistedRuleHit, persistedRuleMandateOf } from "./gate-lanes.js";
 export { cloneObserverInput } from "./runner/gate-exit.js";
 import { type AskClass } from "./ask-class.js";
-import type { AutoModeDenialTracker } from "./auto-mode.js";
+import { type AutoModeDenialTracker } from "./auto-mode.js";
 export { formatHookFeedback } from "./reminder-mint.js";
 import type { WiringLegKind } from "./wiring-manifest.js";
 /**
@@ -1405,6 +1405,20 @@ export interface ToolGateInput {
         toolCallId: string;
         fallback: import("./auto-mode.js").DenialLimitFallback;
     }) => void;
+    /**
+     * #648 — the deny exit nobody judged: the ask's approver (the run's own, or an ancestor's frozen seat on
+     * a delegated child) answered `unavailable` and the durable park re-route did not take the call, so the
+     * fail-closed deny STANDS. Fired once per such call, after the park has had its one attempt, with the
+     * facts the `delegation.ask_unresolvable` notice is composed from (`ask-unresolvable-notice.ts`);
+     * `parkLaneExisted` = a park lane was armed for this run. Observe-only: a throwing seat never alters
+     * the deny. Absent ⇒ the deny stands silently (a host driving the gate directly, no notice sink).
+     */
+    onAskUnresolvable?: (info: {
+        toolName: string;
+        toolCallId: string;
+        settlementKind: "approver_unavailable";
+        parkLaneExisted: boolean;
+    }) => void;
     /**
      * design/153 §2/§7.4 (件4 复审, MED): true means this call's ask is MARKED — an inherited ancestor
      * constraint already determined "no synchronous layer may resolve this ask" (the ancestor's frozen
@@ -1497,6 +1511,19 @@ export interface ToolGateInput {
             rules: readonly string[];
         }) => void;
     };
+    /**
+     * #619 — observation sink for a shell call the READ-ONLY reader cleared (`readOnlyShellVerdict`, the
+     * allow layer's second member beside the persisted allow rule: consulted for the shell tool only, after
+     * the person's allow rules, under the SAME consumption predicate — never over a mandated ask, a hook's
+     * ask, an explicit ask rule, governance or a marked call). The allow-side disclosure of "why did this run
+     * without asking me?" for that arm; `command` is the FINAL command the gate judged (a policy rewrite
+     * included). Never affects the outcome. Absent ⇒ the arm still runs, silently.
+     */
+    onReadOnlyAllowed?: (info: {
+        toolName: string;
+        toolCallId: string;
+        command: string;
+    }) => void;
     /**
      * design/182 §7 — the ORG layer. Present ONLY when the deployment DECLARED org governance (the
      * overlay constructor is the boot gate: a governed declaration with no snapshot provider refuses to
@@ -1643,6 +1670,12 @@ export interface AskCarry {
     /** The surviving ask's engine-stamped origin word ({@link import("./ask-origin.js").AskOrigin}), persisted
      *  on the row so a durable card is rendered by the same word the synchronous card is. */
     readonly origin?: import("./ask-origin.js").AskOrigin;
+    /** #616: the surviving ask's classifier-unavailable fact (the classifier was consulted on this ask and could
+     *  not run — `cause` is the verdict's word), persisted on the row so a durable card says why it is asking
+     *  exactly as the synchronous card does. Absent ⇒ the classifier answered, was not eligible, or was not wired. */
+    readonly classifierUnavailable?: {
+        readonly cause: import("./auto-mode.js").AutoModeUnavailableCause;
+    };
 }
 /** What a durable row persists of an {@link AskCarry}: the fallback member COPIED (the row never aliases
  *  the gate's object; its window is already `0` — the gate's carry mint is the one writer of that
@@ -1651,6 +1684,9 @@ export interface AskCarry {
 export declare function askCarryRowMembers(carry: AskCarry | undefined): {
     denialLimitFallback?: import("./auto-mode.js").DenialLimitFallback;
     origin?: import("./ask-origin.js").AskOrigin;
+    classifierUnavailable?: {
+        readonly cause: import("./auto-mode.js").AutoModeUnavailableCause;
+    };
 };
 /**
  * The design/37 **two-phase tool gate** — the single chokepoint that makes the load-bearing invariant

package/dist/core/hooks.js

@@ -6,6 +6,7 @@ export { normalizeOrgGateVerdict, normalizePersistedRuleHit, persistedRuleMandat
 export { cloneObserverInput } from "./runner/gate-exit.js";
 import { brandPolicyAskClass } from "./ask-class.js";
 import { isAskOrigin } from "./ask-origin.js";
+import { isAutoModeUnavailableCause } from "./auto-mode.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 export { formatHookFeedback } from "./reminder-mint.js";
 import { createSafeNotifier } from "./safe-notify.js";
@@ -237,6 +238,7 @@ export function askCarryRowMembers(carry) {
     return {
         ...(carry.denialLimitFallback !== undefined ? { denialLimitFallback: { ...carry.denialLimitFallback } } : {}),
         ...(isAskOrigin(carry.origin) ? { origin: carry.origin } : {}),
+        ...(isAutoModeUnavailableCause(carry.classifierUnavailable?.cause) ? { classifierUnavailable: { cause: carry.classifierUnavailable.cause } } : {}),
     };
 }
 export async function runToolGate(input) {

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

@@ -497,28 +497,65 @@ export declare function parseRuleText(text: string, behavior: RuleBehavior): {
  *  double-slash directory form; for `path` it is the pattern as spelled. */
 export declare function formatRuleText(command: string, match: PersistedRuleMatch, tool: PersistedRuleTool): string;
 /**
- * The bases a path pattern resolves against at match time — facts of the CALL, never of the rule:
- * `home` for `~/…` (absent ⇒ `os.homedir()`), `root` for `/…` (the task's project root), `cwd` for a
- * relative pattern (the live working directory; absent ⇒ `root`). A pattern whose base is absent
- * resolves to nothing and reaches nothing.
+ * The closed set of BASES a path-form pattern resolves against — facts of the CALL (its execution
+ * environment and its task), never of the rule:
+ *  - `cwd`  — a relative pattern (`dist/**`, `./x`, a bare `x` read at any depth): the live tracked working directory; when no tracker
+ *             moved (or the caller keeps none) the task root stands in for it — that stand-in is the WORD's
+ *             own meaning (the same reading `TOOL_PATH_BASES.cwd` gives a tool's relative slot), not a
+ *             fallback to a different base;
+ *  - `root` — a root-relative pattern (`/dist/**`): the task's project root;
+ *  - `home` — a home-relative pattern (`~/.ssh/**`): the home directory OF THE EXECUTION ENVIRONMENT the
+ *             call runs in (`ExecutionEnv.homeDir`, declared by the adapter). NEVER the engine process's
+ *             own home: on a remote or sandboxed leg the two differ, and a `~/` deny resolved against the
+ *             engine host's home silently guarded the wrong directory (#644).
+ * A pattern whose base is ABSENT (or not an absolute path) cannot be judged: the reach is `unreadable`
+ * (fail-closed — a standing deny/ask the lane cannot read becomes an ask a person clears), never
+ * silence and never a guess. `//abs` patterns need no base. {@link ruleBasesNeeded} tells a host BEFORE
+ * prepare which base a rule will need, so it can declare it (or expect the ask).
  */
-export interface PathRuleBases {
-    readonly root?: string;
-    readonly cwd?: string;
-    readonly home?: string;
-}
+export declare const PATH_RULE_BASES: readonly ["cwd", "root", "home"];
+export type PathRuleBase = (typeof PATH_RULE_BASES)[number];
+/** The bases a call supplies, keyed by {@link PathRuleBase}; every member optional (absent = not supplied). */
+export type PathRuleBases = {
+    readonly [K in PathRuleBase]?: string;
+};
+/** The noun a refusal or an unreadable reason names each base by — the disposition table over the set
+ *  (a base without a row does not compile: {@link PathRuleBaseLabelCoversEveryBase}). */
+export declare const PATH_RULE_BASE_LABEL: {
+    readonly cwd: "the working directory";
+    readonly root: "the project root";
+    readonly home: "the home directory of the execution environment";
+};
+/** The fence over the label table: `never` while every base has a row. */
+export type PathRuleBaseLabelCoversEveryBase = AssertAllKeysHandled<Exclude<PathRuleBase, keyof typeof PATH_RULE_BASE_LABEL>>;
+/**
+ * WHICH base a rule's pattern resolves against — the one classification `resolvePathPattern`, the rule
+ * compiler's compile-time check and a host's pre-prepare "can this environment judge this rule?" all read.
+ * Empty for a rule that needs none: a `//abs` pattern, a `subpath` (directory) rule, a command rule. The
+ * relative form names `cwd`, whose own meaning includes "the root stands in when no tracker moved" — a
+ * host that supplies `root` has therefore supplied `cwd`'s stand-in too.
+ */
+export declare function ruleBasesNeeded(rule: Pick<PersistedRule, "match" | "command">): readonly PathRuleBase[];
 /** Is this base usable by {@link resolvePathPattern} — an absolute path with a lexical normal form? A rule
  *  compiler asks this at compile time so a pattern is refused rather than compiled inert. */
 export declare function isUsablePathBase(base: string | undefined): boolean;
 /**
- * The PATH family's tightening predicate: does this deny/ask rule reach the call's target path? The
- * target is the caller's ALREADY-RESOLVED lexical-normal absolute path (the same identity the read/write
- * fences judge with). A `subpath` rule reaches the directory and everything under it
- * ({@link directoryRuleAdmits}); a `path` rule resolves its spelling against the call's bases and
- * matches segment-wise (`*` within a segment, `**` across segments), reaching the path it names and
- * everything under a directory it names. A command-family rule reaches no path.
+ * The PATH family's tightening reach — three-valued like the command family's ({@link programRunReachOf}):
+ * does this deny/ask rule reach the call's target path? The target is the caller's ALREADY-RESOLVED
+ * lexical-normal absolute path (the same identity the read/write fences judge with). A `subpath` rule
+ * reaches the directory and everything under it ({@link directoryRuleAdmits}); a `path` rule resolves its
+ * spelling against the call's bases ({@link resolvePathPattern} — a cwd-relative bare name reads at any
+ * depth, a trailing `/**` peeled first and, for that peeled form alone, by the rule's BEHAVIOR:
+ * `path_rule.bare_name`) and matches segment-wise (`*` within a segment, `**` across
+ * segments), reaching the path it names and everything under a directory it names. A command-family rule
+ * reaches no path. `unreadable` (#644): the pattern needs a base the call did not supply (or supplied as
+ * a non-absolute spelling) — the rule CANNOT be judged, and the answer says which base; a lane that must
+ * fail closed on it turns it into the ask a person clears (the persisted lane's unreadable answer, the
+ * content lane's unreadable ask), exactly as an unreadable command is treated. Silence here was the #644
+ * defect (a `~/` deny falling back to the engine host's home guarded the wrong directory; a `/…` deny with
+ * no root reached nothing at all).
  */
-export declare function pathRuleReaches(rule: Pick<PersistedRule, "match" | "command">, target: string, bases: PathRuleBases): boolean;
+export declare function pathRuleReachOf(rule: Pick<PersistedRule, "match" | "command" | "behavior">, target: string, bases: PathRuleBases): ProgramRunReachOutcome;
 /**
  * Does this rule's command pattern admit `command`?
  *

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

@@ -331,20 +331,51 @@ function parsePathRuleContent(text, tool, content, behavior) {
     }
     return { rule: { behavior, rule: formatRuleText(content, "path", tool), tool, match: "path", command: content } };
 }
-function resolvePathPattern(pattern, bases) {
+export const PATH_RULE_BASES = ["cwd", "root", "home"];
+export const PATH_RULE_BASE_LABEL = {
+    cwd: "the working directory",
+    root: "the project root",
+    home: "the home directory of the execution environment",
+};
+export function ruleBasesNeeded(rule) {
+    if (rule.match !== "path")
+        return [];
+    const pattern = rule.command;
     if (pattern.startsWith("//"))
-        return "/" + pattern.slice(2);
-    const under = (base, rest) => {
-        const normal = base === undefined ? undefined : lexicalNormalAbsolutePathOf(base);
-        if (normal === undefined)
-            return undefined;
-        return (normal === "/" ? "" : normal) + "/" + rest;
-    };
+        return [];
     if (pattern.startsWith("~/"))
-        return under(bases.home ?? homedir(), pattern.slice(2));
+        return ["home"];
     if (pattern.startsWith("/"))
-        return under(bases.root, pattern.slice(1));
-    return under(bases.cwd ?? bases.root, pattern.startsWith("./") ? pattern.slice(2) : pattern);
+        return ["root"];
+    return ["cwd"];
+}
+function baseValueOf(base, bases) {
+    switch (base) {
+        case "home":
+            return bases.home;
+        case "root":
+            return bases.root;
+        case "cwd":
+            return bases.cwd ?? bases.root;
+        default: {
+            const _exhaustive = base;
+            return _exhaustive;
+        }
+    }
+}
+function resolvePathPattern(pattern, bases, behavior) {
+    if (pattern.startsWith("//"))
+        return { resolved: "/" + pattern.slice(2) };
+    const needed = ruleBasesNeeded({ match: "path", command: pattern })[0];
+    const normal = lexicalNormalAbsolutePathOf(baseValueOf(needed, bases) ?? "");
+    if (normal === undefined)
+        return { missingBase: needed };
+    const rest = pattern.startsWith("~/") ? pattern.slice(2) : pattern.startsWith("/") ? pattern.slice(1) : pattern.startsWith("./") ? pattern.slice(2) : pattern;
+    const peeled = rest.endsWith("/**") ? rest.slice(0, -3) : rest;
+    const bare = needed === "cwd" && peeled !== "" && !peeled.includes("/");
+    const anyDepth = bare && (peeled === rest || behavior !== "allow");
+    const body = anyDepth ? "**/" + peeled : rest;
+    return { resolved: (normal === "/" ? "" : normal) + "/" + body };
 }
 export function isUsablePathBase(base) {
     return base !== undefined && lexicalNormalAbsolutePathOf(base) !== undefined;
@@ -389,19 +420,20 @@ function globSegmentsReach(globs, target) {
     };
     return walk(0, 0);
 }
-export function pathRuleReaches(rule, target, bases) {
+export function pathRuleReachOf(rule, target, bases) {
     if (rule.match === "subpath")
-        return directoryRuleAdmits(rule, target);
+        return directoryRuleAdmits(rule, target) ? REACHED : NOT_REACHED;
     if (rule.match !== "path")
-        return false;
+        return NOT_REACHED;
     if (!isLexicalNormalAbsoluteDir(target) && target !== "/")
-        return false;
-    const resolved = resolvePathPattern(rule.command, bases);
-    if (resolved === undefined)
-        return false;
-    const globs = resolved.split("/").filter((sg) => sg !== "");
+        return NOT_REACHED;
+    const r = resolvePathPattern(rule.command, bases, rule.behavior);
+    if ("missingBase" in r) {
+        return { reach: "unreadable", reason: `the rule is relative to ${PATH_RULE_BASE_LABEL[r.missingBase]} and this call supplies no absolute \`${r.missingBase}\` base to resolve it against` };
+    }
+    const globs = r.resolved.split("/").filter((sg) => sg !== "");
     const segments = target.split("/").filter((sg) => sg !== "");
-    return globSegmentsReach(globs, segments);
+    return globSegmentsReach(globs, segments) ? REACHED : NOT_REACHED;
 }
 function hasUnescapedStar(s) {
     for (let i = 0; i < s.length; i++) {
@@ -778,12 +810,18 @@ export function adjudicatePersistedPathRules(rules, call, targets, bases) {
         }
         if (targets.tighten === undefined)
             continue;
+        let unreadable;
         for (const rule of rules) {
             if (!eligiblePersisted(rule, call, behavior))
                 continue;
-            if (pathRuleReaches(rule, targets.tighten, bases))
+            const outcome = pathRuleReachOf(rule, targets.tighten, bases);
+            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-rules.d.ts

@@ -132,10 +132,12 @@ export interface PermissionRulePolicyOptions {
      */
     ruleFaces?: (toolName: string) => RuleFaceView | undefined;
     /**
-     * The bases a path-form deny/ask pattern resolves against at match time: `root` for `/…` (the task's
-     * project root), `cwd` for a relative pattern (absent ⇒ `root`), `home` for `~/…` (absent ⇒ the process
-     * owner's home). Facts of the DEPLOYMENT and the task, never of the rule — a pattern is stored as
-     * spelled. A rule whose base is absent here is refused at compile time (`unsupported.path_base`).
+     * The bases a path-form deny/ask pattern resolves against at match time ({@link PathRuleBases}): `root`
+     * for `/…` (the task's project root), `cwd` for a relative pattern (the root stands in when absent — the
+     * word's own meaning), `home` for `~/…` (the EXECUTION ENVIRONMENT's home — never the engine process's
+     * own; #644). Facts of the DEPLOYMENT and the task, never of the rule — a pattern is stored as spelled.
+     * A rule whose base is absent (or not an absolute path) here is refused at compile time
+     * (`unsupported.path_base`, naming the base — {@link ruleBasesNeeded} is the same classification).
      */
     pathBases?: PathRuleBases;
 }

package/dist/core/permission-rules.js

@@ -1,7 +1,7 @@
 import { MCP_NAMESPACE, protocolOf } from "./protocol-table.js";
 import { catalogRuleFaceOf, pathTargetOf } from "./tool-registry.js";
 import { indexOfUnescaped, lastIndexOfUnescaped, parsePermissionRule } from "./permission-rule-syntax.js";
-import { isUsablePathBase, parseRuleText, pathRuleReaches, programRunReachOf } from "./permission-rule-model.js";
+import { PATH_RULE_BASE_LABEL, isUsablePathBase, parseRuleText, pathRuleReachOf, programRunReachOf, ruleBasesNeeded } from "./permission-rule-model.js";
 import { effectivePathTargetOf } from "./effective-path-target.js";
 import { protectivePathTargetOf } from "./tool-registry.js";
 export { parsePermissionRule };
@@ -186,19 +186,14 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
                     bad(text, "invalid.command_rule", `${parsedPath.reject.code}: ${parsedPath.reject.message}`);
                     continue;
                 }
-                const pattern = parsedPath.rule.command;
-                if (parsedPath.rule.match === "path" && !pattern.startsWith("//")) {
-                    const needsRoot = pattern.startsWith("/");
-                    const base = pattern.startsWith("~/") ? (pathBases.home ?? "/") : needsRoot ? pathBases.root : (pathBases.cwd ?? pathBases.root);
-                    if (!isUsablePathBase(base)) {
-                        bad(text, "unsupported.path_base", pattern.startsWith("~/")
-                            ? `"${text}" is relative to the home directory, and this policy's \`pathBases.home\` is not an absolute path — the rule would reach nothing`
-                            : needsRoot
-                                ? `"${text}" is relative to the project root, and this policy was given no absolute \`pathBases.root\` to resolve it against — the rule would reach nothing`
-                                : `"${text}" is relative to the working directory, and this policy was given no absolute \`pathBases.cwd\` (or \`root\`) to resolve it against — the rule would reach nothing`);
-                        continue;
+                for (const base of ruleBasesNeeded(parsedPath.rule)) {
+                    const value = base === "cwd" ? (pathBases.cwd ?? pathBases.root) : pathBases[base];
+                    if (!isUsablePathBase(value)) {
+                        bad(text, "unsupported.path_base", `"${text}" is relative to ${PATH_RULE_BASE_LABEL[base]}, and this policy was given no absolute \`pathBases.${base}\`${base === "cwd" ? " (or `root`)" : ""} to resolve it against — the rule could not be judged on any call`);
                     }
                 }
+                if (issues.length > 0 && issues[issues.length - 1].rule === text && issues[issues.length - 1].code === "unsupported.path_base")
+                    continue;
                 entry.content[r.behavior].push({ parsed: parsedPath.rule, ruleText: text, ...(r.source !== undefined ? { source: r.source } : {}) });
                 byTool.set(toolName, entry);
                 continue;
@@ -326,8 +321,13 @@ export function createPermissionRulePolicy(rules, opts) {
         let unreadable;
         for (const r of lane) {
             if (r.parsed.match === "subpath" || r.parsed.match === "path") {
-                if (target !== undefined && pathRuleReaches(r.parsed, target, pathBases))
+                if (target === undefined)
+                    continue;
+                const outcome = pathRuleReachOf(r.parsed, target, pathBases);
+                if (outcome.reach === "reached")
                     return { rule: r };
+                if (outcome.reach === "unreadable")
+                    unreadable ??= { rule: r, unreadable: outcome.reason };
                 continue;
             }
             if (typeof command !== "string")
@@ -342,7 +342,7 @@ export function createPermissionRulePolicy(rules, opts) {
     };
     const unreadableAsk = (hit, req) => ({
         action: "ask",
-        message: `tool "${req.toolName}" needs approval: the command could not be read against the permission rule ${hit.rule.ruleText} (${hit.unreadable}) — a person must decide`,
+        message: `tool "${req.toolName}" needs approval: the call could not be read against the permission rule ${hit.rule.ruleText} (${hit.unreadable}) — a person must decide`,
         matchedAskRule: hit.rule.ruleText,
         requiresRealApproval: true,
     });

package/dist/core/persisted-rule-arms.js

@@ -39,11 +39,12 @@ export function applyPersistedTightening(decision, read) {
             tightened: "ask",
         };
     }
+    const asked = { ...decision };
     return {
         decision: {
-            ...decision,
-            ...(decision.matchedAskRule === undefined ? { matchedAskRule: shown } : {}),
-            message: `${decision.message !== undefined ? `${decision.message} ` : ""}(a persisted ask rule (${shown}) also requires approval for this call)`,
+            ...asked,
+            ...(asked.matchedAskRule === undefined ? { matchedAskRule: shown } : {}),
+            message: `${asked.message !== undefined ? `${asked.message} ` : ""}(a persisted ask rule (${shown}) also requires approval for this call)`,
         },
         tightened: "ask",
     };

package/dist/core/read-only-shell-table.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The READ-ONLY shell tables — the closed data the read-only reader (`read-only-shell.ts`) judges a
+ * command against, transcribed from upstream's own tables (CC 2.1.250) and kept as DATA so the parity
+ * question is answered by diffing two tables, never by reading two programs:
+ *  - {@link READ_ONLY_COMMAND_TABLE} — the flag-vetted commands: a command (one or more leading words,
+ *    `git status`, `gh pr view`, `grep`) with the closed set of flags it may carry, each flag's value
+ *    ARITY, and where upstream carries one, its extra danger predicate over the remaining words
+ *    (upstream `w3t` + `tqe` + `nqe` + `XGn` + `JGn` + `dmt`);
+ *  - {@link READ_ONLY_BARE_PROGRAMS} — programs read-only under ANY literal arguments (upstream `jpe`);
+ *  - {@link READ_ONLY_GLOB_PROGRAMS} — the programs a segment carrying a GLOB may still be read-only
+ *    under (upstream `B3t`; a glob may expand to any name, so only a program that cannot write however
+ *    it is named is admitted);
+ *  - {@link READ_ONLY_EXACT_FORMS} / {@link READ_ONLY_BARE_ONLY} — whole-command forms (`node -v`) and
+ *    programs admitted only bare (`pwd`) (upstream `N3t` / `D3t`);
+ *  - {@link FIND_ACTION_PRIMARIES} / {@link FIND_VALUE_PRIMARIES} / {@link FIND_NEWER_PRIMARY} — the
+ *    `find` primaries that ACT (write, execute) and the ones that take a value (upstream `I3t`/`smt`/`amt`);
+ *  - {@link READ_ONLY_ENV_NAMES} — the environment variables a read-only command may be prefixed with
+ *    (upstream `nH`: a variable that cannot change what a program DOES);
+ *  - {@link XARGS_READ_ONLY_TARGETS} — the programs `xargs` may hand its input to (upstream `v3t`).
+ *
+ * NOT transcribed, each a stated gap rather than a silent one: `sed` (upstream vets the sed SCRIPT with a
+ * dedicated analyzer; without it a `sed` is not read-only here — fail-closed), the Windows PowerShell table
+ * and every Windows-only arm (UNC paths), and the two filesystem probes upstream runs beside the tables (a
+ * bare-repository indicator check and a `.git` redirection check — a shell tool here has no filesystem seat).
+ *
+ * Every predicate over the remaining words receives the words AFTER the command's own (upstream's `t`),
+ * dequoted. Upstream's substitution placeholders never appear here: a word carrying an expansion has
+ * already taken the whole command out of the read-only reading before a table is consulted.
+ */
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+/** How many words a flag's VALUE takes, and what the value must look like (upstream `ni`): `none` — the flag
+ *  takes no value (`--flag=x` is refused); `number` — one word of digits; `string` — one word, any text
+ *  (a value that starts with `-` is refused: it is another flag); `char` — one word of length 1; `{}` and
+ *  `EOF` — one word spelled exactly so (`xargs -I {}`, `xargs -E EOF`). Registered in docs/CLOSED-SETS.md. */
+export declare const READ_ONLY_FLAG_ARITIES: readonly ["none", "number", "string", "char", "{}", "EOF"];
+export type ReadOnlyFlagArity = (typeof READ_ONLY_FLAG_ARITIES)[number];
+/** The disposition table over the arity set: does `value` satisfy the arity? (`none` accepts NO value.) */
+export declare const FLAG_VALUE_ACCEPTS: {
+    readonly none: () => boolean;
+    readonly number: (value: string) => boolean;
+    readonly string: () => boolean;
+    readonly char: (value: string) => boolean;
+    readonly "{}": (value: string) => boolean;
+    readonly EOF: (value: string) => boolean;
+};
+/** Compile-time fence: `never` while every arity has a row. */
+export type FlagArityTableCoversEveryArity = AssertAllKeysHandled<Exclude<ReadOnlyFlagArity, keyof typeof FLAG_VALUE_ACCEPTS>>;
+/** One row of {@link READ_ONLY_COMMAND_TABLE}. */
+export interface ReadOnlyCommandRow {
+    /** Flag → the arity of its value. A flag not in the table refuses the command (a short cluster `-abc`
+     *  is admitted only when every letter is a `none` flag). */
+    readonly safeFlags: Readonly<Record<string, ReadOnlyFlagArity>>;
+    /** `false`: a `--` word is skipped like any other rather than ending the flag walk (the words after it
+     *  keep being vetted). Default: `--` ends the walk and the rest are operands. */
+    readonly respectsDoubleDash?: false;
+    /** Upstream carries a whole-text regex for this row; expressed here over the remaining words. */
+    readonly wordsShape?: (args: readonly string[]) => boolean;
+    /** Upstream's `additionalCommandIsDangerousCallback` over the remaining words: `true` refuses. */
+    readonly dangerous?: (args: readonly string[]) => boolean;
+}
+export declare const dockerRetargetDanger: (args: readonly string[]) => boolean;
+/**
+ * The flag-vetted command table (upstream `w3t` and everything it spreads; `sed` withheld — see the module
+ * note). Keys with a space are multi-word commands and are matched on the leading words.
+ */
+export declare const READ_ONLY_COMMAND_TABLE: Readonly<Record<string, ReadOnlyCommandRow>>;
+/** Programs read-only under any LITERAL arguments (upstream `jpe`): `cat x`, `wc -l x`, `diff a b`, `sleep 3`…
+ *  The two-word `docker ps` / `docker images` are matched on both words. */
+export declare const READ_ONLY_BARE_PROGRAMS: readonly ["docker ps", "docker images", "cal", "uptime", "cat", "head", "tail", "wc", "stat", "strings", "hexdump", "od", "nl", "id", "uname", "free", "df", "du", "locale", "groups", "nproc", "basename", "dirname", "realpath", "cut", "paste", "tr", "column", "tac", "rev", "fold", "expand", "unexpand", "fmt", "comm", "cmp", "numfmt", "readlink", "diff", "true", "false", "sleep", "which", "type", "expr", "seq", "tsort", "pr"];
+/** Programs a segment carrying a GLOB may still be read-only under (upstream `B3t`): the glob may name
+ *  anything, so only a program that writes nothing whatever it is handed. */
+export declare const READ_ONLY_GLOB_PROGRAMS: readonly ["ls", "cat", "head", "tail", "wc", "stat", "grep", "egrep", "fgrep", "diff", "du", "df", "echo", "strings", "hexdump", "od", "nl", "cut", "column", "tr", "tac", "rev", "cmp", "basename", "dirname", "realpath", "readlink", "sha256sum", "sha1sum", "md5sum", "cd"];
+/** Whole-command forms admitted exactly as spelled (upstream `N3t`). */
+export declare const READ_ONLY_EXACT_FORMS: readonly (readonly string[])[];
+/** Programs admitted only BARE (upstream `D3t`: `pwd`, `whoami`, `alias` — with an operand `alias` DEFINES one). */
+export declare const READ_ONLY_BARE_ONLY: readonly ["pwd", "whoami", "alias"];
+/** `find` primaries that ACT — delete, execute, write a file (upstream `I3t`). */
+export declare const FIND_ACTION_PRIMARIES: readonly ["-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprint0", "-fls", "-fprintf", "-files0-from"];
+/** `find` primaries that take ONE value word (the value is skipped, not vetted) (upstream `smt`). */
+export declare const FIND_VALUE_PRIMARIES: readonly ["-name", "-iname", "-path", "-ipath", "-lname", "-ilname", "-regex", "-iregex", "-wholename", "-iwholename", "-samefile", "-newer", "-anewer", "-cnewer", "-mnewer", "-perm", "-user", "-group", "-uid", "-gid", "-size", "-type", "-xtype", "-fstype", "-inum", "-links", "-used", "-context", "-amin", "-cmin", "-mmin", "-atime", "-ctime", "-mtime", "-mindepth", "-maxdepth", "-printf", "-regextype", "-D", "-f", "-flags", "-Bnewer", "-Btime", "-Bmin", "-files0-from", "-xattrname"];
+/** The `-newerXY` family, a value primary spelled by pattern (upstream `amt`). */
+export declare const FIND_NEWER_PRIMARY: RegExp;
+/** Environment variables a read-only command may be prefixed with (upstream `nH`): locale, colour, terminal
+ *  and toolchain switches that change how output LOOKS, never what a program does to the filesystem. */
+export declare const READ_ONLY_ENV_NAMES: readonly ["GOEXPERIMENT", "GOOS", "GOARCH", "CGO_ENABLED", "GO111MODULE", "RUST_BACKTRACE", "RUST_LOG", "NODE_ENV", "PYTHONUNBUFFERED", "PYTHONDONTWRITEBYTECODE", "PYTEST_DISABLE_PLUGIN_AUTOLOAD", "PYTEST_DEBUG", "ANTHROPIC_API_KEY", "LANG", "LANGUAGE", "LC_ALL", "LC_CTYPE", "LC_TIME", "CHARSET", "TERM", "COLORTERM", "NO_COLOR", "FORCE_COLOR", "TZ", "LS_COLORS", "LSCOLORS", "GREP_COLOR", "GREP_COLORS", "GCC_COLORS", "TIME_STYLE", "BLOCK_SIZE", "BLOCKSIZE", "COLUMNS", "LINES", "CLICOLOR", "CLICOLOR_FORCE", "CI", "DEBIAN_FRONTEND", "GIT_TERMINAL_PROMPT"];
+/** The programs `xargs` may hand its input to and stay read-only (upstream `v3t`). */
+export declare const XARGS_READ_ONLY_TARGETS: readonly ["echo", "printf", "wc", "grep", "egrep", "fgrep", "head", "tail"];