@sema-agent/core 7.22.0 → 7.23.1

package/dist/core/types.d.ts

@@ -18,7 +18,7 @@ export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditR
 export type { AgentDefinition, SkillManifest, SkillSpec } from "./agent-definition.js";
 export type { McpServerSpec, A2aServerSpec, McpElicitRequest, McpElicitResponse, OnElicit } from "./mcp-server-spec.js";
 export type { TaskLimits } from "./task-limits.js";
-export type { TaskStatus, RemoteEnvFailureNote, EffectiveMemoryScopes, TaskResult } from "./task-result.js";
+export type { TaskStatus, RemoteEnvFailureNote, EffectiveMemoryScopes, TaskResult, HumanReviewGateRow } from "./task-result.js";
 export type { TerminalCause, PausedCause } from "./terminal-cause.js";
 export type { TaskEventIdentity, BrainStatusPhase, BrainRetryErrClass, BrainStatus, ToolActivity, HumanInputSource, HumanInputDelivery, DelegationTaskType, TaskEvent, HumanInputEvent, CompactOutcome } from "./task-event.js";
 export type { TaskStream } from "./task-stream.js";

package/dist/core/write-protect.d.ts

@@ -30,13 +30,26 @@ export interface WriteProtectedHit {
 }
 export declare const WRITE_PROTECTED_DEFAULT_TABLE: readonly WriteProtectedRow[];
 /**
- * The ONE case fold of this module, applied to BOTH sides of every comparison (table names at
- * compile, path segments at match) — `toLowerCase` plus the two confusable letters CC's fold maps
- * (U+0131 dotless ı → i, U+017F long ſ → s). Deliberately NOT full Unicode confusable folding:
- * that would be a different, wider claim than the one made (the read deny set's ASCII-contract doc
- * states the same boundary for its own fold).
+ * The ONE SEGMENT fold of this module, applied to BOTH sides of every comparison (table names at
+ * compile, path segments at match), in the reference implementation's own order:
+ *  · `toLowerCase` plus the two confusable letters its fold maps (U+0131 dotless ı → i, U+017F long ſ → s);
+ *  · the INVISIBLE FORMAT characters it strips — the zero-width joiners/non-joiners, the bidirectional
+ *    overrides and the byte-order mark (U+200C–U+200F, U+202A–U+202E, U+206A–U+206F, U+FEFF), verbatim.
+ *    A segment carrying one of these LOOKS like the row it is not, on both sides of every comparison, so
+ *    the strip is a deception axis rather than a platform one: it applies to every reading below, not to
+ *    the win32 one alone. It can only ADD matches, which on a TIGHTEN costs one extra question — and the
+ *    data-root passthrough, where an added match would be a guard BYPASSED, deliberately does not use this
+ *    fold at all (its comparison is byte-exact; see {@link relativeUnderDataRoot}).
+ *  · …and a strip that would EMPTY the segment keeps the segment instead (the reference fold's own `|| n`):
+ *    an all-invisible component names a real file, and folding it to "" would make it collide with nothing
+ *    or with everything depending on the caller.
+ * Deliberately NOT full Unicode confusable folding: that would be a different, wider claim than the one made
+ * (the read deny set's ASCII-contract doc states the same boundary for its own fold). The NTFS data-stream
+ * suffix the reference fold also strips is a win32 NAMESPACE fact, not a comparison one, and lives with the
+ * other component normalization of those views ({@link ComponentNormalization}) so a POSIX file legally
+ * named `a:b` keeps its own identity on the POSIX reading.
  */
-export declare function foldWriteProtectCase(s: string): string;
+export declare function foldWriteProtectSegment(s: string): string;
 /**
  * Resolve the ACTIVE table under the deployment seat (validated, loud — #123's bad-value states all
  * throw and name the knob). `undefined` = the default table; `[]` = NO table (an explicit, legal
@@ -47,15 +60,32 @@ export declare function foldWriteProtectCase(s: string): string;
  * candidate configuration with the engine's own rules.
  */
 export declare function resolveWriteProtectedTable(entries?: readonly WriteProtectedEntry[]): readonly WriteProtectedRow[];
+/**
+ * WHY the ENVIRONMENT half of one judgment could not contribute — the canonicalizer refused the spelling,
+ * a link the tree could not follow, a namespace spelling it declines, an environment call that threw.
+ * Reported through {@link WriteProtectionCompileOptions.onViewAbsent}; it is a DISCLOSURE, never a verdict
+ * (see the absence law on {@link WriteProtectionMatcher.judge}).
+ */
+export interface WriteProtectionViewAbsence {
+    /** The environment's own sentence, verbatim — what it said when asked to resolve this target. */
+    readonly cause: string;
+    /** The failure was specifically a symlink whose real target is unknowable, as opposed to a spelling the
+     *  tree refuses or a probe that errored. */
+    readonly unresolvedSymlink: boolean;
+}
 /**
  * The judge's answer for ONE covered write ({@link WriteProtectionMatcher.judge}):
- *  · `clear` — no row on either view: the write is not this layer's business;
+ *  · `clear` — no row on any view that could answer: the write is not this layer's business;
  *  · `hit` — a row matched; `via` says which view named it: `"spelling"` (the anchored spelling, no
  *    filesystem consulted), `"chain"` (a spelling the leaf symlink chain passes through, judged as a
  *    spelling) or `"target"` (the resolved real target, the spelling being innocent);
- *  · `unresolvable` — the real target could not be resolved (an unfollowable symlink, an errored probe, a
- *    namespace spelling the tree refuses); `cause` is the canonicalizer's own sentence and the consumer
- *    REFUSES, an unjudged target never being vouched.
+ *  · `unresolvable` — NO half of the judgment answered at all. The judge itself no longer mints this: an
+ *    environment that cannot resolve the target has ANSWERED, and an answer of "I cannot resolve this"
+ *    leaves the lexical half's judgment standing (the absence law below). What is left for this verdict is
+ *    the judgment that never happened — the gate's bounded wait elapsing or the task ending before
+ *    anything came back (`awaitWriteProtectionJudgment`, gate-bounded-await.ts) — where there is no
+ *    lexical answer to stand on either, and the consumer REFUSES. `unresolvedSymlink` is that minter's
+ *    `false`: a wait that produced nothing knows nothing about what it was waiting for.
  */
 export type WriteProtectionVerdict = {
     readonly kind: "clear";
@@ -115,8 +145,8 @@ export interface WriteProtectionMatcher {
      * @contract write_protection.judges_the_real_target — the always-on write-protection table and the
      * opt-in sensitive-path deny set differ in VOCABULARY (literal rows / segment globs) and SEVERITY
      * (ask / deny), never in REACH: both judge the file the tool will write — the spelling anchored at the
-     * live cwd AND its resolved real target, through one canonicalizer — and a target neither can resolve is
-     * refused, never vouched. An environment-less judge has no target view and answers by the spelling alone —
+     * live cwd AND its resolved real target, through one canonicalizer. Where they DO part: a target the write-protection
+     * judge cannot resolve leaves its resolved view ABSENT (the spelling still judges); the deny set still REFUSES whole. An environment-less judge has no target view and answers by the spelling alone —
      * the same absence law the cwd follows (absent ⇒ the spelling is judged exactly as given). REACH is what
      * this sentence promises, not a LOCK: the identity is resolved at judgment time and re-resolved by the
      * tool at execute time (the module header states that window and the seat that would close it).
@@ -136,6 +166,17 @@ export interface WriteProtectionCompileOptions {
      *  path-family source when the call carries no cwd. Omitted ⇒ relative spellings resolve against the
      *  cwd, then the environment's own working directory. */
     readonly rootPath?: string;
+    /**
+     * Called at most ONCE per judgment, at the moment the ENVIRONMENT half is found unable to contribute
+     * ({@link WriteProtectionViewAbsence}) — before the judgment returns, and on the hit arm as well as the
+     * clear one, because the fact is about the ENVIRONMENT rather than about the answer it did not change.
+     * Omitted ⇒ the absence is silent, which is the honest default for a judge compiled outside a leg.
+     * A throwing sink is the caller's bug and is not caught here; the leg that wires one wraps it.
+     *
+     * Deliberately carries no call identity: what it reports is a deployment-level fact (this environment
+     * cannot answer path questions), and its consumer announces once per leg rather than once per write.
+     */
+    readonly onViewAbsent?: (absence: WriteProtectionViewAbsence) => void;
 }
 /**
  * Compile the write-protection judge for a deployment configuration. Returns `undefined` when the
@@ -204,5 +245,16 @@ export interface WriteProtectionMount {
  * environment cannot RESOLVE is the judge's own `unresolvable` verdict, not this null.
  * Returns `undefined` when the resolved table is empty — nothing to judge, mount nothing.
  * `opts` are the judge's own seats, passed straight through ({@link compileWriteProtection}).
+ *
+ * @contract write_protection.membership_is_the_call — WHICH calls the always-on table judges is a
+ * PREDICATE OVER THE CALL and nothing else: the call's own face declares a path target whose access is not
+ * a read, so a custom writer joins this judge by DECLARING what it writes and a tool that declares nothing
+ * is not this layer's business under any name. There is deliberately NO name-list seat beside it, and the
+ * asymmetry with the opt-in deny policy — which does take one (`createSensitivePathPolicy({ tools })`, its
+ * own pre-declaration hatch) — is the intended shape rather than a gap: a name list on a default-ON floor
+ * is a way to narrow that floor silently, one tool name at a time, while the seat this layer gives a
+ * deployment for narrowing is the whole-table replacement, which says what it removes. A deployment that
+ * wants name-list membership composes the deny policy alongside; the two then answer under the shared
+ * `deny > ask > allow` fold, which is what makes the missing seat cost nothing.
  */
 export declare function createWriteProtectionCheck(entries?: readonly WriteProtectedEntry[], opts?: WriteProtectionCompileOptions): WriteProtectionMount | undefined;

package/dist/core/write-protect.js

@@ -57,8 +57,19 @@ export const WRITE_PROTECTED_DEFAULT_TABLE = freezeTable([
     { name: ".sema.json", kind: "basename" },
     { name: ".sema", kind: "segment" },
 ]);
-export function foldWriteProtectCase(s) {
-    return s.toLowerCase().replace(/ı/g, "i").replace(/ſ/g, "s");
+export function foldWriteProtectSegment(s) {
+    const cased = s.toLowerCase().replace(/ı/g, "i").replace(/ſ/g, "s");
+    return stripInvisibleFormat(cased) || cased;
+}
+function stripInvisibleFormat(s) {
+    return s.replace(/[\u200c-\u200f\u202a-\u202e\u206a-\u206f\ufeff]/g, "");
+}
+function stripWin32Component(raw, normalization) {
+    const base = normalization.invisibleFirst ? stripInvisibleFormat(raw) : raw;
+    return (normalization.stream ? base.replace(/:.*$/, "") : base).replace(/[. ]+$/, "");
+}
+function foldWriteProtectName(name) {
+    return name.split("/").map(foldWriteProtectSegment).join("/");
 }
 const KINDS = ["basename", "segment", "segment-run"];
 function describeEntryValue(v) {
@@ -107,7 +118,7 @@ export function resolveWriteProtectedTable(entries) {
     const seen = new Set();
     for (const entry of entries) {
         const row = normalizeWriteProtectedEntry(entry);
-        const key = `${row.kind}:${foldWriteProtectCase(row.name)}`;
+        const key = `${row.kind}:${foldWriteProtectName(row.name)}`;
         if (seen.has(key))
             continue;
         seen.add(key);
@@ -115,8 +126,9 @@ export function resolveWriteProtectedTable(entries) {
     }
     return freezeTable(out);
 }
-function pathViewSegments(path, win32, seps = BOTH_SEPARATOR_FAMILIES, anchorFloor = 0) {
+function pathViewSegments(path, normalization, seps = BOTH_SEPARATOR_FAMILIES, anchorFloor = 0) {
     const segs = [];
+    const win32 = normalization !== "literal";
     for (const raw of path.split(seps)) {
         if (raw.length === 0)
             continue;
@@ -131,11 +143,17 @@ function pathViewSegments(path, win32, seps = BOTH_SEPARATOR_FAMILIES, anchorFlo
                 segs.push("..");
             continue;
         }
-        const stripped = win32 ? raw.replace(/[. ]+$/, "") : raw;
+        const stripped = normalization === "literal" ? raw : stripWin32Component(raw, normalization);
         segs.push(stripped.length > 0 ? stripped : raw);
     }
     return segs;
 }
+const WIN32_NORMALIZATIONS = [
+    { invisibleFirst: false, stream: false },
+    { invisibleFirst: false, stream: true },
+    { invisibleFirst: true, stream: false },
+    { invisibleFirst: true, stream: true },
+];
 const BOTH_SEPARATOR_FAMILIES = /[\\/]/;
 const POSIX_SEPARATOR_FAMILY = /\//;
 function uncAnchorSegments(path) {
@@ -149,7 +167,7 @@ function relativeUnderDataRoot(path, roots) {
         if (root.win ? !isWinFormPath(path) : isWinFormPath(path) || !path.startsWith("/"))
             continue;
         const seps = root.win ? BOTH_SEPARATOR_FAMILIES : POSIX_SEPARATOR_FAMILY;
-        const segs = pathViewSegments(path, false, seps, uncAnchorSegments(path));
+        const segs = pathViewSegments(path, "literal", seps, uncAnchorSegments(path));
         if (segs.length < root.segments.length)
             continue;
         if (root.segments.every((s, i) => segs[i] === s))
@@ -165,13 +183,13 @@ export function compileWriteProtection(entries, opts) {
     const dataRootPaths = dataRootSpellings(opts?.dataRoot);
     const rootViews = dataRootPaths.map((r) => {
         const win = isWinFormPath(r);
-        return { win, segments: pathViewSegments(r, false, win ? BOTH_SEPARATOR_FAMILIES : POSIX_SEPARATOR_FAMILY, uncAnchorSegments(r)) };
+        return { win, segments: pathViewSegments(r, "literal", win ? BOTH_SEPARATOR_FAMILIES : POSIX_SEPARATOR_FAMILY, uncAnchorSegments(r)) };
     });
     const basenames = new Map();
     const segments = new Map();
     const runs = [];
     for (const row of rows) {
-        const folded = foldWriteProtectCase(row.name);
+        const folded = foldWriteProtectName(row.name);
         if (row.kind === "basename") {
             if (!basenames.has(folded))
                 basenames.set(folded, row.name);
@@ -187,7 +205,7 @@ export function compileWriteProtection(entries, opts) {
     const judgeSegments = (raw) => {
         if (raw.length === 0)
             return null;
-        const segs = raw.map(foldWriteProtectCase);
+        const segs = raw.map(foldWriteProtectSegment);
         const base = basenames.get(segs[segs.length - 1] ?? "");
         if (base !== undefined)
             return { name: base, kind: "basename" };
@@ -205,9 +223,20 @@ export function compileWriteProtection(entries, opts) {
         }
         return null;
     };
-    const judgeViews = (spelling) => judgeSegments(pathViewSegments(spelling, false, POSIX_SEPARATOR_FAMILY, uncAnchorSegments(spelling))) ??
-        judgeSegments(pathViewSegments(spelling, false)) ??
-        judgeSegments(pathViewSegments(spelling, true));
+    const judgeViews = (spelling) => {
+        const posix = judgeSegments(pathViewSegments(spelling, "literal", POSIX_SEPARATOR_FAMILY, uncAnchorSegments(spelling)));
+        if (posix !== null)
+            return posix;
+        const bothSeparators = judgeSegments(pathViewSegments(spelling, "literal"));
+        if (bothSeparators !== null)
+            return bothSeparators;
+        for (const normalization of WIN32_NORMALIZATIONS) {
+            const hit = judgeSegments(pathViewSegments(spelling, normalization));
+            if (hit !== null)
+                return hit;
+        }
+        return null;
+    };
     const judgeSpelled = (spelled) => judgeViews(relativeUnderDataRoot(spelled, rootViews) ?? spelled);
     const judgeSpelling = (path, cwd) => {
         const base = typeof cwd === "string" && cwd.length > 0 ? cwd : undefined;
@@ -231,31 +260,55 @@ export function compileWriteProtection(entries, opts) {
                 return { kind: "clear" };
             const family = pathFamilyOf({ root: rootPath, cwd: ctx.cwd ?? env.cwd });
             const base = ctx.base ?? ctx.cwd ?? rootPath;
-            const canon = await canonicalizeTarget(env, path, ctx.signal, family, base);
-            if (!canon.ok)
-                return { kind: "unresolvable", cause: canon.message, unresolvedSymlink: canon.unresolvedSymlink === true };
-            const byTarget = judgeViews(canon.key);
-            if (byTarget !== null) {
-                for (const rootKey of await canonicalDataRootKeys(env, dataRootPaths, ctx.signal)) {
-                    const relative = relativeUnderRoot(canon.key, rootKey);
-                    if (relative === null)
+            let noted = false;
+            const noteAbsence = (cause, unresolvedSymlink) => {
+                if (noted)
+                    return;
+                noted = true;
+                opts?.onViewAbsent?.({ cause, unresolvedSymlink });
+            };
+            let canonKey;
+            try {
+                const canon = await canonicalizeTarget(env, path, ctx.signal, family, base);
+                if (canon.ok)
+                    canonKey = canon.key;
+                else
+                    noteAbsence(canon.message, canon.unresolvedSymlink === true);
+            }
+            catch (err) {
+                noteAbsence(err instanceof Error ? err.message : String(err), false);
+            }
+            try {
+                if (canonKey !== undefined) {
+                    const byTarget = judgeViews(canonKey);
+                    if (byTarget !== null) {
+                        for (const rootKey of await canonicalDataRootKeys(env, dataRootPaths, ctx.signal)) {
+                            const relative = relativeUnderRoot(canonKey, rootKey);
+                            if (relative === null)
+                                continue;
+                            if (relative === "")
+                                return { kind: "clear" };
+                            const remainder = judgeViews(relative);
+                            return remainder === null ? { kind: "clear" } : { kind: "hit", hit: remainder, via: "target" };
+                        }
+                        return { kind: "hit", hit: byTarget, via: "target" };
+                    }
+                }
+                for (const hop of await symlinkChainHops(env, path, ctx.signal, family, base, (cause) => noteAbsence(cause, false))) {
+                    const byHop = judgeSpelled(hop);
+                    if (byHop === null)
                         continue;
-                    if (relative === "")
-                        return { kind: "clear" };
-                    const remainder = judgeViews(relative);
-                    return remainder === null ? { kind: "clear" } : { kind: "hit", hit: remainder, via: "target" };
+                    if (canonKey !== undefined) {
+                        for (const rootKey of await canonicalDataRootKeys(env, dataRootPaths, ctx.signal)) {
+                            if (relativeUnderRoot(canonKey, rootKey) !== null)
+                                return { kind: "clear" };
+                        }
+                    }
+                    return { kind: "hit", hit: byHop, via: "chain" };
                 }
-                return { kind: "hit", hit: byTarget, via: "target" };
             }
-            for (const hop of await symlinkChainHops(env, path, ctx.signal, family, base)) {
-                const byHop = judgeSpelled(hop);
-                if (byHop === null)
-                    continue;
-                for (const rootKey of await canonicalDataRootKeys(env, dataRootPaths, ctx.signal)) {
-                    if (relativeUnderRoot(canon.key, rootKey) !== null)
-                        return { kind: "clear" };
-                }
-                return { kind: "hit", hit: byHop, via: "chain" };
+            catch (err) {
+                noteAbsence(err instanceof Error ? err.message : String(err), false);
             }
             return { kind: "clear" };
         },

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -7,6 +7,21 @@ import type { SchedulerCapability, ScheduledIntent, SchedulerContext, ScheduledT
 import { SchedulerError } from "../../core/scheduler.js";
 /** Convert user-facing timeout seconds into a positive, timer-safe millisecond delay. */
 export declare function resolveExecTimeoutMs(timeoutSeconds: unknown): number | undefined;
+/**
+ * Anchor a RELATIVE symlink target at its link's own directory, UNFOLDED and with exactly one separator
+ * between the two. A directory that IS a root already ends in its own separator (`/`, `C:\`, `C:/`,
+ * `\\host\share\`, all of which `dirname` answers that way), and concatenating a second one mints a
+ * DOUBLE-separator spelling for a path that has one spelling — `/tmp -> private/tmp` came back as
+ * `//private/tmp`, which the judges that walk this chain then match against nothing, because a guarded row
+ * and a containment root are both written with single separators. Joining through `path.resolve`/`path.join`
+ * would fix the separator and fold `..` with it, which is the one thing this walk may not do.
+ *
+ * `separator` is the one the caller's `dirname` writes, passed rather than read from the module so the rule
+ * is a pure function of its inputs. A backslash counts as a terminator only where it IS a separator: on a
+ * POSIX tree a directory whose name ends in one (`/a/b\`) is an ordinary name, and reading it as terminated
+ * would rename `/a/b\/t` to `/a/b\t` — the same class of rewrite as folding `..` lexically.
+ */
+export declare function anchorAtLinkDir(linkDir: string, target: string, separator: string): string;
 /** review finding (win32): `where bash.exe` can resolve to `System32\bash.exe` — the
  *  WSL LAUNCHER, not a native shell. Running it drops into a Linux subsystem where Windows cwd/paths
  *  do not exist; silently adopting it is exactly the "wrong shell, false green" failure D1 forbids.
@@ -171,8 +186,10 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
      * target, until a hop is not a link (`EINVAL`), is absent (`ENOENT` / `ENOTDIR`), repeats, or the bound is
      * reached. A relative target is ANCHORED at its link's directory and never folded — `..` is the filesystem's
      * to resolve during the next `readlink`'s own lookup (a lexical fold reads `bridge/../next` as `next` and misses
-     * every link behind `bridge`). One syscall per hop, no `lstat`. On a win32 host a share-shaped hop is kept and
-     * ends the walk unprobed. Any other errno is an answer nobody can use (`err`), never a shortened chain.
+     * every link behind `bridge`). Anchoring puts EXACTLY ONE separator between the directory and the target
+     * ({@link anchorAtLinkDir}); a root directory already ends in its own. One syscall per hop, no `lstat`. On a
+     * win32 host a share-shaped hop is kept and ends the walk unprobed. Any other errno is an answer nobody can
+     * use (`err`), never a shortened chain.
      */
     canonicalChain(path: string): Promise<Result<SymlinkChain, FileError>>;
     exists(path: string): Promise<Result<boolean, FileError>>;

package/dist/engine/execution-env/node-execution-env.js

@@ -42,6 +42,10 @@ function fileKindFromStats(stats) {
     return undefined;
 }
 const HAS_POSIX_MODE_FACE = process.platform !== "win32";
+export function anchorAtLinkDir(linkDir, target, separator) {
+    const endsInSeparator = linkDir.endsWith(separator) || (separator === "\\" && linkDir.endsWith("/"));
+    return endsInSeparator ? `${linkDir}${target}` : `${linkDir}${separator}${target}`;
+}
 const SYMLINK_CHAIN_HOP_BOUND = 64;
 function fileInfoFromStats(path, stats) {
     const kind = fileKindFromStats(stats);
@@ -1043,7 +1047,7 @@ export class NodeExecutionEnv {
                     return ok({ hops });
                 return err(toFileError(error, cur));
             }
-            const next = isAbsolute(target) ? target : `${dirname(cur)}${sep}${target}`;
+            const next = isAbsolute(target) ? target : anchorAtLinkDir(dirname(cur), target, sep);
             if (seen.has(next))
                 break;
             hops.push(next);

package/dist/index.d.ts

@@ -105,7 +105,7 @@ export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, ty
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, type ReadDenyEntry, type ReadDenyMatcher, type NormalizedReadDenyEntry, type ReadDenyBuiltinTier, type ReadDenyBuiltinRow, type ReadDenyBuiltinConfig, } from "./tools/fs/index.js";
 export { deploymentFaceClampNotice, resolveContainmentFace, type ContainmentFace, type ContainmentFaceInputs, type ContainmentFaceKind, type ContainmentFaceLayer, } from "./tools/fs/index.js";
-export { WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, compileWriteProtection, type WriteProtectedEntry, type WriteProtectedRow, type WriteProtectedKind, type WriteProtectedHit, type WriteProtectionMatcher, type WriteProtectionVerdict, type WriteProtectionJudgeContext, type WriteProtectionCompileOptions, type WriteProtectionCheck, WRITE_PROTECTION_TARGET_VIEWS, type WriteProtectionTargetView, type WriteProtectionMount, } from "./core/write-protect.js";
+export { WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, compileWriteProtection, type WriteProtectedEntry, type WriteProtectedRow, type WriteProtectedKind, type WriteProtectedHit, type WriteProtectionMatcher, type WriteProtectionVerdict, type WriteProtectionViewAbsence, type WriteProtectionJudgeContext, type WriteProtectionCompileOptions, type WriteProtectionCheck, WRITE_PROTECTION_TARGET_VIEWS, type WriteProtectionTargetView, type WriteProtectionMount, } from "./core/write-protect.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, type ToolResultProvenance, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, type ToolResultStore, type ToolResultSlice, type ToolResultDeletionReport, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointId, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, type ActorAssertion, type PendingSteerEntry, type PendingSteerInput, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type ProbeCause, type ProbeCauseOperands, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type TerminalClaimIntent, type TerminalClaimOutcome, type SafetyAxis, type RealApprovalGateBit, type ResourceLedger, type ResourceLimitReason, type PlatformLimitReason, type CheckpointRow, realApprovalOrgFact, resolveCheckpointStore, checkpointStoreExecutionUndeclared, } from "./core/checkpoint-store.js";
 export { EXECUTION_OUTCOME_RECORD_WORDS, EXECUTION_RECORD_LEAVES_ROW_UNRECORDED, type ExecutionOutcomeRecordWord, type ExecutionRecordRowFacts, type ExecutionVerdict, ExecutionOutcomeConflictError, checkpointExecutionRecorded, executionRecordDisposition, sameExecutionRecord, executionVerdict, } from "./core/checkpoint-execution-record.js";

package/dist/tools/fs/bash-lexer.d.ts

@@ -92,20 +92,27 @@ export interface SegmentTokens {
 /** What a substitution leaves in a word's FOLDED spelling: a marker no argv word can spell, so a consumer that
  *  judges words sees "this word carries text the shell computes" rather than the computing text itself. */
 export declare const SUBSTITUTION_PLACEHOLDER = " subst";
+export type QuoteOpen = '"' | "'" | undefined;
 /**
- * Which characters of `s` sit inside a QUOTED region, by the same pairing rule the lexer walks with. The pairing
- * quote characters themselves are reported as quoted — they are not operators either way.
+ * Which QUOTE holds each character of `s`, by the same pairing rule the lexer walks with, and the boolean view
+ * of it. The pairing quote characters themselves belong to the region they bound — they are not operators
+ * either way — so `openedBy` names that region's quote character at their own index too.
+ *
+ * `quoted` is a VIEW of `openedBy`, minted in the same step: a consumer asking only "is this inside quotes"
+ * reads it, one asking WHICH quote (single quotes suppress every expansion, double quotes suppress neither `$`
+ * nor the backtick) reads `openedBy`, and the two cannot drift.
  *
  * `balanced` is false when a region is still open at the end of the string. Callers must then NOT use the mask:
  * an unterminated quote is a string bash itself cannot parse, and every consumer falls back to the quote-BLIND
  * reading, which is the stricter one.
  *
  * EXACTNESS. This models bash only for the residual character space the strict faces operate in, where backslash
- * escapes, `$`, backticks, and subshells are rejected outright — there `'` and `"` pairing is the whole of
- * quoting, so a region computed here is exactly a region bash quotes. It is NOT a general shell quoting parser
- * and must not be used before those characters are excluded.
+ * escapes and subshells are rejected outright — there `'` and `"` pairing is the whole of quoting, so a region
+ * computed here is exactly a region bash quotes. A caller deciding about `$` or a backtick on this mask owes
+ * the argument in `bash-readonly-classifier.ts`. It is NOT a general shell quoting parser.
  */
 export declare function quoteMask(s: string): {
+    openedBy: readonly QuoteOpen[];
     quoted: readonly boolean[];
     balanced: boolean;
 };

package/dist/tools/fs/bash-lexer.js

@@ -5,14 +5,17 @@ function quoteStep(open, ch) {
     return open === ch ? undefined : open;
 }
 export function quoteMask(s) {
+    const openedBy = new Array(s.length).fill(undefined);
     const quoted = new Array(s.length).fill(false);
     let open;
     for (let i = 0; i < s.length; i++) {
         const before = open;
         open = quoteStep(open, s[i]);
-        quoted[i] = before !== undefined || open !== undefined;
+        const holds = before ?? open;
+        openedBy[i] = holds;
+        quoted[i] = holds !== undefined;
     }
-    return { quoted, balanced: open === undefined };
+    return { openedBy, quoted, balanced: open === undefined };
 }
 export function literalTildeSpelling(word) {
     return word.startsWith("~") ? `./${word}` : word;

package/dist/tools/fs/bash-program-position.d.ts

@@ -114,6 +114,9 @@ export type ProgramPositionRefusal = {
     readonly kind: "control_syntax_at_program_position";
     readonly owner: string;
     readonly word: string;
+    /** Not a DECLINE ({@link programPositionRunsShell}): the row WAS read and a SHELL stands at the program
+     *  position. Absent ⇒ genuine control syntax, which IS one. */
+    readonly runsShell?: true;
 };
 export interface ProgramPosition {
     /** Indices of the bare control words stripped in front (`!`, `if`, `time`, …), in order; their declared options
@@ -159,5 +162,20 @@ export declare function readProgramPosition(toks: SegmentTokens): ProgramPositio
  *  stdin AND the program it runs is not one the caller accepts as a stream target. ONE reading, shared by every
  *  consumer; WHICH targets are accepted is the caller's declaration, not this reader's. */
 export declare function argvReentryUnjudged(pos: ProgramPosition, acceptedTargets: ReadonlySet<string>): boolean;
+/**
+ * The two ways this reader DECLINES rather than judges — a CLOSED set, because which of them a seat reads as
+ * evidence is a table each seat declares against (`fs-bash.ts`, where the argument is), not a boolean buried
+ * in a caller. `unreadable_program_position`: the walk cannot name the program bash will run (`env -- ls`).
+ * `stream_fed_operands`: the operands arrive on a STREAM it never saw (`… | xargs cat`). Neither names a WORD.
+ */
+export declare const SHELL_SCAN_DECLINES: readonly ["unreadable_program_position", "stream_fed_operands"];
+export type ShellScanDecline = (typeof SHELL_SCAN_DECLINES)[number];
+/** Does a SHELL stand where this segment's program would be — as the program itself (`sh -c`), or as a launcher
+ *  ROW handing its operands to one (`watch "…"`)? ONE predicate for the re-entry class, so the two spellings
+ *  cannot be answered differently; which names are shells is the caller's declaration. Not a decline. */
+export declare function programPositionRunsShell(pos: ProgramPosition, shellProgram: RegExp): boolean;
+/** Which decline, if any, this program position raises — ONE reading of the two facts above, so no consumer
+ *  re-derives either. A refusal that says a SHELL runs is NOT one: it names what runs. */
+export declare function shellScanDeclineOf(pos: ProgramPosition, acceptedStreamTargets: ReadonlySet<string>): ShellScanDecline | undefined;
 /** ONE sentence per refusal kind, minted here and nowhere else. */
 export declare function programPositionRefusalSentence(refusal: ProgramPositionRefusal): string;

package/dist/tools/fs/bash-program-position.js

@@ -107,7 +107,7 @@ export function readProgramPosition(toks) {
     }
     const launchers = [{ index: i, name: basename }];
     const owner = head;
-    const shellRefusal = () => ({ kind: "control_syntax_at_program_position", owner, word: "sh" });
+    const shellRefusal = () => ({ kind: "control_syntax_at_program_position", owner, word: "sh", runsShell: true });
     let owedOperands = LAUNCHER_TABLE.get(basename)?.requiredOperands ?? 0;
     let lastRow = LAUNCHER_TABLE.get(basename);
     const chain0 = (program, refusal) => ({ controlWords, written, assignments, launchers, argvFromStdin: false, runsDefaultProgram: false, program, refusal });
@@ -158,6 +158,18 @@ export function argvReentryUnjudged(pos, acceptedTargets) {
     const runs = pos.program?.basename ?? (pos.runsDefaultProgram ? ARGV_REENTRY_DEFAULT_PROGRAM : undefined);
     return runs === undefined || !acceptedTargets.has(runs);
 }
+export const SHELL_SCAN_DECLINES = ["unreadable_program_position", "stream_fed_operands"];
+export function programPositionRunsShell(pos, shellProgram) {
+    if (pos.refusal !== undefined)
+        return pos.refusal.kind === "control_syntax_at_program_position" && pos.refusal.runsShell === true;
+    return pos.program !== undefined && shellProgram.test(pos.program.basename);
+}
+export function shellScanDeclineOf(pos, acceptedStreamTargets) {
+    if (pos.refusal !== undefined) {
+        return pos.refusal.kind === "control_syntax_at_program_position" && pos.refusal.runsShell === true ? undefined : "unreadable_program_position";
+    }
+    return argvReentryUnjudged(pos, acceptedStreamTargets) ? "stream_fed_operands" : undefined;
+}
 export function programPositionRefusalSentence(refusal) {
     switch (refusal.kind) {
         case "option_at_program_position":

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -1,4 +1,5 @@
 import { type ShellSegmentConnector } from "./bash-lexer.js";
+import { type ShellScanDecline } from "./bash-program-position.js";
 /**
  * Bare command names `bash_readonly` permits out of the box, ALSO the default reversible set for the
  * The {@link import("./fs-bash.js").bashReversibilityProbe} classifier. **Coarse first filter, NOT a security
@@ -31,7 +32,6 @@ import { type ShellSegmentConnector } from "./bash-lexer.js";
  * value-taking options defeat the stdin-floor operand count without a per-verb option-value model
  * — those are a follow-on slice, not a silent drop.
  */
-export { NOT_AUTO_ALLOWED } from "./bash-program-position.js";
 export type { ShellSegmentConnector } from "./bash-lexer.js";
 export declare const BASH_READONLY_DEFAULT_ALLOW: readonly string[];
 /**
@@ -174,7 +174,7 @@ export interface ShellCompoundSegments {
  * drift in a segmentation is drift in what a deny rule is even looking at.
  *
  * Three steps, in this order and load-bearing:
- *  1. WHOLE-STRING hard reject of {@link SHELL_SEGMENT_HARD_REJECT} — redirection, substitution,
+ *  1. WHOLE-STRING hard reject ({@link hardRejectReason}) — redirection, substitution,
  *     subshells, escapes, line breaks. This is what makes step 3's quote mask EXACT: with those
  *     characters gone, `'`/`"` pairing is the entirety of quoting, so the mask's regions are exactly
  *     bash's quoted regions and the unquoted connectors are exactly bash's command boundaries. Callers
@@ -524,7 +524,10 @@ export declare function resolveOperandSpellings(base: string | undefined, operan
  *  here-document, a here-string or a literal in-root stdin file; a directory change (which then makes every relative
  *  stdin literal in the command unjudged). A substitution body (`$(…)`, backticks, `<(…)`) is judged on its own: green
  *  under the compound walk, or exempt under this whitelist; a here-document body is text, not commands. */
-export declare function refusedCommandMayRead(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): boolean;
+export declare function refusedCommandMayRead(command: string, allow: ReadonlySet<string>, boundary: BashReadonlyRootBoundary | undefined, 
+/** The {@link ShellScanDecline} members THIS SEAT reads as evidence (tables and argument: `fs-bash.ts`); one
+ *  the table omits ends the scan with "exempt". */
+declinesAreEvidence: ReadonlySet<ShellScanDecline>): boolean;
 /**
  * The home directory's VARIABLE spellings, SUBSTITUTED with the declared value before a read face segments the
  * command: `$HOME` / `${HOME}` at the START of a word (an empty quote pair before it included), unquoted or
@@ -602,6 +605,10 @@ export interface OutOfRootReadGateVerdict {
      *  operand is placed against a base bash has already left, so no path can be named honestly. Read it
      *  as display/triage evidence; emptiness is not "not gated". */
     readonly paths: readonly string[];
+    /** Did the deployment's DENY judge speak about an operand this command names? The other half of the same
+     *  question, over the very same readers, in a second pass WITH the deny judge — which is what lets the
+     *  containment answer above stay deny-free and keep its `paths` contract. Absent ⇔ it said nothing. */
+    readonly denied?: true;
 }
 /** Test seam for the lockstep pin that the launcher table (the ONE launcher truth, in the program-position
  *  reader's module) stays a SUBSET of the rule lane's curated `BARE_INTERPRETER_NAMES`. Exported for that one