@sema-agent/core 7.48.0 → 7.49.1

package/dist/core/write-protect.js

@@ -1,12 +1,13 @@
-import { releasableAskClassesFor } from "./ask-origin.js";
-import { canonicalizeTarget, isWinFormPath, writeTargetPath, isUncPath, isAbsoluteForFamily, joinForFamily, pathFamilyOf } from "../tools/fs/safety.js";
+import { anchorSpelling, canonicalizeTarget, isAbsoluteForFamily, isWinFormPath, writeTargetPath, isUncPath, pathFamilyOf } from "../tools/fs/safety.js";
+import { judgePathRows } from "./path-guard-rows.js";
 import { protectivePathTargetOf } from "./tool-registry.js";
 import { pathTargetBaseOf } from "./effective-path-target.js";
 import { canonicalDataRootKeys, dataRootSpellings, relativeUnderRoot } from "./sensitive-path-policy.js";
-import { symlinkChainHops } from "./path-identity.js";
+import { chainHopsOrNone, symlinkChainHops } from "./path-identity.js";
 import { readDenyPatternRun } from "../tools/fs/read-deny.js";
 import { agentConfigDirSegments, agentConfigDirTail } from "./agent-config-dir.js";
 import { thrownText } from "./thrown-value.js";
+import { fromSource, gateWaitFailureOf } from "./gate-bounded-await.js";
 const freezeTable = (rows) => Object.freeze(rows.map((r) => Object.freeze(r)));
 export const WRITE_PROTECTED_DEFAULT_TABLE = freezeTable([
     { name: ".gitconfig", kind: "basename" },
@@ -85,39 +86,52 @@ function describeEntryValue(v) {
         return String(v);
     }
 }
-function normalizeWriteProtectedEntry(entry) {
+function normalizeWriteProtectedEntry(entry, owner = "writeProtectedPaths") {
     const shape = typeof entry === "string" ? { name: entry, kind: entry.includes("/") ? "segment-run" : "segment" } : entry;
     if (typeof shape !== "object" || shape === null || typeof shape.name !== "string") {
-        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(entry)} is not a name string or { name, kind } row.`);
+        throw new Error(`${owner}: entry ${describeEntryValue(entry)} is not a name string or { name, kind } row.`);
     }
     const name = shape.name;
     if (!KINDS.includes(shape.kind)) {
-        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(entry)} has kind ${describeEntryValue(shape.kind)} — known kinds: ${KINDS.join(", ")}.`);
+        throw new Error(`${owner}: entry ${describeEntryValue(entry)} has kind ${describeEntryValue(shape.kind)} — known kinds: ${KINDS.join(", ")}.`);
     }
     const kind = shape.kind;
     const { homeAnchored, run } = readDenyPatternRun(name);
     if (homeAnchored) {
-        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(name)} opens with the home word "~", which this table does not place — its names are matched wherever their segments appear. ` +
+        throw new Error(`${owner}: entry ${describeEntryValue(name)} opens with the home word "~", which this table does not place — its names are matched wherever their segments appear. ` +
             (run.length > 0 ? `Spell the name without it (${describeEntryValue(run)}), which covers the home's file and every same-named one.` : "The home directory itself is not a row; spell the name of what it holds."));
     }
     if (name.includes("*") || name.includes("?")) {
-        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(name)} contains a wildcard metacharacter — this table speaks LITERAL names only (a silently-literal "*" would guard less than it reads); pattern semantics live in createSensitivePathPolicy.`);
+        throw new Error(`${owner}: entry ${describeEntryValue(name)} contains a wildcard metacharacter — this table speaks LITERAL names only (a silently-literal "*" would guard less than it reads); pattern semantics live in createSensitivePathPolicy.`);
     }
     if (name.includes("\\")) {
-        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(name)} contains a backslash — names are "/"-separated (both path families are matched); spell the segments with "/".`);
+        throw new Error(`${owner}: entry ${describeEntryValue(name)} contains a backslash — names are "/"-separated (both path families are matched); spell the segments with "/".`);
     }
     const segments = name.split("/").filter((s) => s.length > 0);
     if (segments.length === 0) {
-        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(name)} contains no path segments and would protect nothing — remove the entry or spell the name.`);
+        throw new Error(`${owner}: entry ${describeEntryValue(name)} contains no path segments and would protect nothing — remove the entry or spell the name.`);
     }
     if (segments.some((s) => s === "." || s === "..")) {
-        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(name)} contains a "." or ".." segment — the judge folds dot segments lexically before matching, so such a row could never match anything; spell the real name.`);
+        throw new Error(`${owner}: entry ${describeEntryValue(name)} contains a "." or ".." segment — the judge folds dot segments lexically before matching, so such a row could never match anything; spell the real name.`);
     }
     if (segments.length > 1 && kind !== "segment-run") {
-        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(name)} spans ${segments.length} segments but declares kind "${kind}" — multi-segment names match as kind "segment-run".`);
+        throw new Error(`${owner}: entry ${describeEntryValue(name)} spans ${segments.length} segments but declares kind "${kind}" — multi-segment names match as kind "segment-run".`);
     }
     return { name: segments.join("/"), kind };
 }
+export function writeProtectedEntryProblem(entry, owner) {
+    try {
+        normalizeWriteProtectedEntry(entry, owner);
+        return undefined;
+    }
+    catch (e) {
+        return e.message;
+    }
+}
+export function writeProtectedEntryIdentity(entry) {
+    const row = normalizeWriteProtectedEntry(entry);
+    return `${row.kind}:${foldWriteProtectName(row.name)}`;
+}
 export function resolveWriteProtectedTable(entries) {
     if (entries === undefined)
         return WRITE_PROTECTED_DEFAULT_TABLE;
@@ -128,7 +142,7 @@ export function resolveWriteProtectedTable(entries) {
     const seen = new Set();
     for (const entry of entries) {
         const row = normalizeWriteProtectedEntry(entry);
-        const key = `${row.kind}:${foldWriteProtectName(row.name)}`;
+        const key = writeProtectedEntryIdentity(row);
         if (seen.has(key))
             continue;
         seen.add(key);
@@ -185,206 +199,250 @@ function relativeUnderDataRoot(path, roots) {
     }
     return null;
 }
+export function spelledExemptionOf(dataRootPaths) {
+    const roots = dataRootPaths.map((r) => {
+        const win = isWinFormPath(r);
+        return { win, segments: pathViewSegments(r, "literal", win ? BOTH_SEPARATOR_FAMILIES : POSIX_SEPARATOR_FAMILY, uncAnchorSegments(r)) };
+    });
+    return (spelling) => relativeUnderDataRoot(spelling, roots);
+}
 export const WRITE_PROTECTION_TARGET_VIEWS = Object.freeze(["spelling-only", "target"]);
 export function compileWriteProtection(entries, opts) {
     const rows = resolveWriteProtectedTable(entries);
     if (rows.length === 0)
         return undefined;
-    const dataRootPaths = dataRootSpellings(opts?.dataRoot);
-    const rootViews = dataRootPaths.map((r) => {
-        const win = isWinFormPath(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 = [];
+    const { dataRoot, ...seats } = opts ?? {};
+    return compileWriteJudgment(rows, entries === undefined ? "builtin" : "replacement", { ...seats, exemptRoots: dataRootSpellings(dataRoot) }).matcher;
+}
+export function compileLegWriteJudgment(entries, opts) {
+    const rows = resolveWriteProtectedTable(entries);
+    const compiled = compileWriteJudgment(rows, "replacement", opts);
+    const guardRows = opts.guardRows;
+    return {
+        matcher: rows.length === 0 ? undefined : compiled.matcher,
+        judgeWriteTarget: rows.length === 0 && guardRows === undefined
+            ? undefined
+            : async (target, judgeOpts) => {
+                const hit = await compiled.judgment(target, { ...(judgeOpts?.signal !== undefined ? { signal: judgeOpts.signal } : {}), ...(judgeOpts?.canonical === true ? { canonical: true } : {}) }, guardRows);
+                return hit === undefined ? undefined : hit.unreadable === undefined && TABLE_ROWS.has(hit.row) ? "protected" : "guarded";
+            },
+    };
+}
+const TABLE_ROWS = new WeakSet();
+function heldRows(cause) {
+    return { name: "the deployment's guarded write rows", grammar: { kind: "segment-glob", run: "" }, polarity: "deny", faces: ["write"], placement: "anywhere", fold: "exact", exemptible: false, origin: "replacement", reach: () => ({ reach: "unreadable", reason: `the rows did not come back: ${cause}` }) };
+}
+function compileWriteJudgment(rows, origin, opts) {
+    const dataRootPaths = opts.exemptRoots;
+    const spelledRemainder = spelledExemptionOf(dataRootPaths);
+    const readingMemo = new Map();
+    const readingsOf = (spelling) => {
+        const known = readingMemo.get(spelling);
+        if (known !== undefined)
+            return known;
+        const raw = [pathViewSegments(spelling, "literal", POSIX_SEPARATOR_FAMILY, uncAnchorSegments(spelling)), pathViewSegments(spelling, "literal"), ...WIN32_NORMALIZATIONS.map((n) => pathViewSegments(spelling, n))];
+        const folded = raw.map((segs) => segs.map(foldWriteProtectSegment));
+        if (readingMemo.size >= 64)
+            readingMemo.clear();
+        readingMemo.set(spelling, folded);
+        return folded;
+    };
+    const literalRow = (row, reach, placement) => {
+        const minted = { name: row.name, kind: row.kind, grammar: { kind: "literal-name", match: row.kind, name: row.name }, polarity: "ask", faces: ["write"], placement, fold: "protective", exemptible: true, origin, reach };
+        TABLE_ROWS.add(minted);
+        return minted;
+    };
+    const tableRows = [];
+    for (const kind of KINDS) {
+        for (const row of rows) {
+            if (row.kind !== kind)
+                continue;
+            const parts = foldWriteProtectName(row.name).split("/").filter((s) => s.length > 0);
+            tableRows.push(literalRow(row, (view) => (readingsOf(view.path).some((segs) => literalNameMeets(kind, parts, segs)) ? REACHED : NOT_REACHED), "anywhere"));
+        }
+    }
     const configTails = [];
     for (const row of rows) {
-        const folded = foldWriteProtectName(row.name);
-        if (row.kind === "basename") {
-            if (!basenames.has(folded))
-                basenames.set(folded, row.name);
-        }
-        else if (row.kind === "segment") {
-            if (!segments.has(folded))
-                segments.set(folded, row.name);
-        }
-        else {
-            runs.push({ name: row.name, parts: folded.split("/").filter((s) => s.length > 0) });
-        }
         const tail = row.kind === "basename" ? undefined : agentConfigDirTail(row.name);
         if (tail !== undefined && opts?.agentConfigDir !== undefined)
-            configTails.push({ hit: { name: row.name, kind: row.kind }, tail: foldWriteProtectName(tail).split("/").filter((s) => s.length > 0) });
+            configTails.push({ row, tail: foldWriteProtectName(tail).split("/").filter((s) => s.length > 0) });
     }
     const configRootSpelled = opts?.agentConfigDir === undefined ? [] : [agentConfigDirSegments(opts.agentConfigDir)];
-    const judgeAtConfigRoots = (segs, roots) => {
-        for (const root of roots) {
-            const at = root.map(foldWriteProtectSegment);
-            if (segs.length < at.length || !at.every((a, i) => segs[i] === a))
-                continue;
-            for (const { hit, tail } of configTails)
-                if (segs.length >= at.length + tail.length && tail.every((t, i) => segs[at.length + i] === t))
-                    return hit;
-        }
-        return null;
+    const configRowsAt = (canonicalRoots) => configTails.map(({ row, tail }) => literalRow(row, (view) => {
+        if (!isAbsoluteForFamily("own", view.path))
+            return NOT_REACHED;
+        const roots = view.kind === "canonical" ? [...configRootSpelled, ...canonicalRoots] : configRootSpelled;
+        return readingsOf(view.path).some((segs) => roots.some((root) => atConfigRoot(segs, root.map(foldWriteProtectSegment), tail))) ? REACHED : NOT_REACHED;
+    }, { below: opts?.agentConfigDir ?? "" }));
+    const tableAt = (canonicalRoots) => (configTails.length === 0 ? tableRows : [...tableRows, ...configRowsAt(canonicalRoots)]);
+    const spelledView = (spelled, kind) => {
+        const remainder = spelledRemainder(spelled);
+        return { path: spelled, kind, ...(remainder !== null ? { exemptRemainder: remainder } : {}) };
     };
-    const judgeSegments = (raw, configRoots) => {
-        if (raw.length === 0)
-            return null;
-        const segs = raw.map(foldWriteProtectSegment);
-        const base = basenames.get(segs[segs.length - 1] ?? "");
-        if (base !== undefined)
-            return { name: base, kind: "basename" };
-        for (const s of segs) {
-            const hit = segments.get(s);
-            if (hit !== undefined)
-                return { name: hit, kind: "segment" };
+    const anchoredSpelling = (path, cwd) => {
+        const base = typeof cwd === "string" && cwd.length > 0 ? cwd : undefined;
+        return base !== undefined ? anchorSpelling(pathFamilyOf({ cwd: base }), base, path) : path;
+    };
+    const env = opts?.env;
+    const rootPath = opts?.rootPath;
+    const judgment = async (path, ctx, extraSource) => {
+        let noted = false;
+        const noteAbsence = (cause, unresolvedSymlink) => {
+            if (noted)
+                return;
+            noted = true;
+            opts?.onViewAbsent?.({ cause, unresolvedSymlink });
+        };
+        const sourceFailed = (err, what) => {
+            if (gateWaitFailureOf(err) !== "aborted")
+                noteAbsence(what === undefined ? thrownText(err) : `${what}: ${thrownText(err)}`, false);
+        };
+        const extra = await (async () => {
+            if (extraSource === undefined)
+                return [];
+            const answer = await fromSource(() => extraSource({ ...(env !== undefined ? { env } : {}), ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}) }), ctx.signal, "deploymentRows");
+            if (answer.ok)
+                return answer.value;
+            sourceFailed(answer.cause, "the deployment's guarded write rows did not come back, so the writes they could guard are not placed");
+            return [heldRows(thrownText(answer.cause))];
+        })();
+        const givenKey = ctx.canonical === true && env !== undefined;
+        const base = ctx.base ?? ctx.cwd ?? rootPath;
+        const lexical = givenKey ? undefined : spelledView(anchoredSpelling(path, ctx.base ?? ctx.cwd), "lexical");
+        const bySpelling = lexical === undefined ? undefined : judgePathRows([...tableAt([]), ...extra], { views: [lexical] }, "tighten");
+        if (bySpelling !== undefined && bySpelling.unreadable === undefined && TABLE_ROWS.has(bySpelling.row))
+            return bySpelling;
+        if (env === undefined)
+            return bySpelling;
+        const family = pathFamilyOf({ root: rootPath, cwd: ctx.cwd ?? env.cwd });
+        const rootLookupFailed = (err) => sourceFailed(err, "a root's key did not come back, so that root takes no part");
+        let canonKey = givenKey ? path : undefined;
+        let canonAliased = false;
+        let targetUnread;
+        let targetUnreadSymlink = false;
+        if (!givenKey) {
+            const answer = await fromSource(() => canonicalizeTarget(env, path, ctx.signal, family, base), ctx.signal, "canonicalTarget");
+            if (!answer.ok) {
+                sourceFailed(answer.cause);
+                targetUnread = thrownText(answer.cause);
+            }
+            else if (answer.value.ok) {
+                canonKey = answer.value.key;
+                canonAliased = answer.value.aliasResolved === true;
+            }
+            else {
+                noteAbsence(answer.value.message, answer.value.unresolvedSymlink === true);
+                targetUnread = answer.value.message;
+                targetUnreadSymlink = answer.value.unresolvedSymlink === true;
+            }
         }
-        for (const run of runs) {
-            const n = run.parts.length;
-            for (let i = 0; i + n <= segs.length; i++) {
-                if (run.parts.every((p, j) => segs[i + j] === p))
-                    return { name: run.name, kind: "segment-run" };
+        const canonicalRoots = canonKey === undefined || configTails.length === 0 || opts?.agentConfigDir === undefined ? [] : (await canonicalDataRootKeys(env, [opts.agentConfigDir], ctx.signal, rootLookupFailed)).map(agentConfigDirSegments);
+        const table = [...tableAt(canonicalRoots), ...extra];
+        const aliased = canonAliased ? { aliasResolved: true } : {};
+        const views = [...(lexical !== undefined ? [{ ...lexical, ...aliased }] : []), ...(canonKey !== undefined ? [{ path: canonKey, kind: "canonical", ...aliased }] : [])];
+        const identity = {};
+        const identityRemainder = () => (identity.asked ??= (async () => {
+            if (canonKey === undefined)
+                return undefined;
+            for (const rootKey of await canonicalDataRootKeys(env, dataRootPaths, ctx.signal, rootLookupFailed)) {
+                const relative = relativeUnderRoot(canonKey, rootKey);
+                if (relative !== null)
+                    return relative;
             }
+            return undefined;
+        })());
+        const judged = async () => {
+            const unread = targetUnread !== undefined ? { unreadable: targetUnread } : {};
+            const hit = judgePathRows(table, { views, ...unread }, "tighten");
+            if (hit === undefined)
+                return undefined;
+            const relative = await identityRemainder();
+            const final = relative === undefined ? hit : judgePathRows(table, { views: views.map((v) => (v.kind === "canonical" ? { ...v, exemptRemainder: relative } : v)), identityExempt: true, ...unread }, "tighten");
+            return final !== undefined && final.unreadable !== undefined && targetUnread !== undefined && targetUnreadSymlink ? { ...final, unresolvedSymlink: true } : final;
+        };
+        const byTarget = canonKey === undefined ? undefined : await judged();
+        if (byTarget !== undefined && byTarget.unreadable === undefined && TABLE_ROWS.has(byTarget.row))
+            return byTarget;
+        if (givenKey)
+            return byTarget;
+        if (identity.asked !== undefined && (await identity.asked) !== undefined && table.every((row) => row.exemptible))
+            return byTarget;
+        const chain = await fromSource(() => symlinkChainHops(env, path, ctx.signal, family, base), ctx.signal, "canonicalChain");
+        if (!chain.ok) {
+            sourceFailed(chain.cause);
+            targetUnread ??= thrownText(chain.cause);
         }
-        return configTails.length === 0 ? null : judgeAtConfigRoots(segs, configRoots);
-    };
-    const judgeViews = (spelling, configRoots = configRootSpelled) => {
-        const posix = judgeSegments(pathViewSegments(spelling, "literal", POSIX_SEPARATOR_FAMILY, uncAnchorSegments(spelling)), configRoots);
-        if (posix !== null)
-            return posix;
-        const bothSeparators = judgeSegments(pathViewSegments(spelling, "literal"), configRoots);
-        if (bothSeparators !== null)
-            return bothSeparators;
-        for (const normalization of WIN32_NORMALIZATIONS) {
-            const hit = judgeSegments(pathViewSegments(spelling, normalization), configRoots);
-            if (hit !== null)
-                return hit;
+        else {
+            if (!chain.value.ok && chain.value.asked) {
+                noteAbsence(chain.value.cause, false);
+                targetUnread ??= chain.value.cause;
+            }
+            for (const hop of chainHopsOrNone(chain.value))
+                views.push(spelledView(hop, "hop"));
         }
-        return null;
-    };
-    const judgeSpelled = (spelled) => {
-        const remainder = relativeUnderDataRoot(spelled, rootViews);
-        return remainder === null ? judgeViews(spelled) : judgeViews(remainder, []);
+        return judged();
     };
-    const judgeSpelling = (path, cwd) => {
-        const base = typeof cwd === "string" && cwd.length > 0 ? cwd : undefined;
-        const family = pathFamilyOf({ cwd: base });
-        const spelled = base !== undefined && family !== undefined && !isAbsoluteForFamily(family, path) ? joinForFamily(family, base, path) : path;
-        return judgeSpelled(spelled);
-    };
-    const env = opts?.env;
-    const rootPath = opts?.rootPath;
-    return {
+    const matcher = {
         rows,
         targetView: env === undefined ? "spelling-only" : "target",
         matchPath(path, cwd) {
-            return judgeSpelling(path, cwd);
+            const hit = judgePathRows(tableAt([]), { views: [spelledView(anchoredSpelling(path, cwd), "lexical")] }, "tighten");
+            return hit === undefined ? null : { name: hit.row.name, kind: hit.row.kind };
         },
         async judge(path, ctx = {}) {
-            const givenKey = ctx.canonical === true && env !== undefined;
-            const bySpelling = givenKey ? null : judgeSpelling(path, ctx.cwd);
-            if (bySpelling !== null)
-                return { kind: "hit", hit: bySpelling, via: "spelling" };
-            if (env === undefined)
+            const hit = await judgment(path, ctx);
+            if (hit === undefined)
                 return { kind: "clear" };
-            const family = pathFamilyOf({ root: rootPath, cwd: ctx.cwd ?? env.cwd });
-            const base = ctx.base ?? ctx.cwd ?? rootPath;
-            let noted = false;
-            const noteAbsence = (cause, unresolvedSymlink) => {
-                if (noted)
-                    return;
-                noted = true;
-                opts?.onViewAbsent?.({ cause, unresolvedSymlink });
-            };
-            let canonKey = givenKey ? path : undefined;
-            if (!givenKey) {
-                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(thrownText(err), false);
-                }
-            }
-            try {
-                if (canonKey !== undefined) {
-                    const canonicalRoots = configTails.length === 0 || opts?.agentConfigDir === undefined ? [] : (await canonicalDataRootKeys(env, [opts.agentConfigDir], ctx.signal)).map(agentConfigDirSegments);
-                    const byTarget = judgeViews(canonKey, [...configRootSpelled, ...canonicalRoots]);
-                    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 givenKey ? [] : await symlinkChainHops(env, path, ctx.signal, family, base, (cause) => noteAbsence(cause, false))) {
-                    const byHop = judgeSpelled(hop);
-                    if (byHop === null)
-                        continue;
-                    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" };
-                }
-            }
-            catch (err) {
-                noteAbsence(thrownText(err), false);
-            }
-            return { kind: "clear" };
+            if (hit.unreadable !== undefined)
+                return { kind: "unresolvable", cause: hit.unreadable, unresolvedSymlink: hit.unresolvedSymlink === true };
+            return verdictOf(hit);
         },
     };
+    return { matcher, judgment };
 }
-export function writeProtectionTightenDecision(toolName, verdict, face) {
-    if (verdict.kind === "hit") {
-        return {
-            action: "ask",
-            message: verdict.via === "target"
-                ? `tool "${toolName}" writes to a write-protected path — its real target resolves onto table entry "${verdict.hit.name}" — explicit approval required`
-                : verdict.via === "chain"
-                    ? `tool "${toolName}" writes to a write-protected path — its symlink chain passes through table entry "${verdict.hit.name}" — explicit approval required`
-                    : `tool "${toolName}" writes to a write-protected path (table entry "${verdict.hit.name}") — explicit approval required`,
-            decisionReason: "safety",
-        };
-    }
+const REACHED = { reach: "reached" };
+const NOT_REACHED = { reach: "not_reached" };
+function literalNameMeets(kind, parts, segs) {
+    if (segs.length === 0)
+        return false;
+    if (kind === "basename")
+        return segs[segs.length - 1] === parts[0];
+    if (kind === "segment")
+        return segs.includes(parts[0]);
+    for (let i = 0; i + parts.length <= segs.length; i++)
+        if (parts.every((p, j) => segs[i + j] === p))
+            return true;
+    return false;
+}
+function atConfigRoot(segs, root, tail) {
+    return segs.length >= root.length + tail.length && root.every((a, i) => segs[i] === a) && tail.every((t, i) => segs[root.length + i] === t);
+}
+function verdictOf(hit) {
+    return { kind: "hit", hit: { name: hit.row.name, kind: hit.row.kind }, via: hit.viewKind === "canonical" ? "target" : hit.viewKind === "hop" ? "chain" : "spelling" };
+}
+export function writeProtectionTightenDecision(toolName, verdict) {
+    if (verdict.kind === "clear")
+        return undefined;
     if (verdict.kind === "unresolvable") {
-        if (releasableAskClassesFor(face).includes("write_protection_unresolved")) {
-            return {
-                action: "ask",
-                message: verdict.unresolvedSymlink
-                    ? `tool "${toolName}" writes to a symlink whose real target could not be resolved, so the write-protection judge cannot tell whether it lands on a protected path (${verdict.cause}) — explicit approval required`
-                    : `tool "${toolName}" writes to a target that could not be resolved on this tree, so the write-protection judge cannot tell whether it lands on a protected path (${verdict.cause}) — explicit approval required`,
-                decisionReason: "safety",
-            };
-        }
         return {
             action: "deny",
-            message: verdict.unresolvedSymlink
-                ? `tool "${toolName}" is blocked: its target is a symlink whose real target could not be resolved, so the write-protection judge cannot tell whether it lands on a protected path (${verdict.cause})`
-                : `tool "${toolName}" is blocked: its target could not be resolved on this tree, so the write-protection judge cannot tell whether it lands on a protected path (${verdict.cause})`,
+            message: `tool "${toolName}" is refused (target_unresolved): where its write target leads on disk could not be determined${verdict.unresolvedSymlink ? " (a link on the way could not be followed)" : ""}, so the write-protected table cannot tell whether it lands on a protected path — ${verdict.cause}`,
             decisionReason: "safety",
         };
     }
-    return undefined;
+    return {
+        action: "ask",
+        message: verdict.via === "target"
+            ? `tool "${toolName}" writes to a write-protected path — its real target resolves onto table entry "${verdict.hit.name}" — explicit approval required`
+            : verdict.via === "chain"
+                ? `tool "${toolName}" writes to a write-protected path — its symlink chain passes through table entry "${verdict.hit.name}" — explicit approval required`
+                : `tool "${toolName}" writes to a write-protected path (table entry "${verdict.hit.name}") — explicit approval required`,
+        decisionReason: "safety",
+    };
 }
 export function writeProtectionMandated(verdict) {
     return verdict.kind === "hit";
 }
-export function writeProtectionUnresolved(verdict) {
-    return verdict.kind === "unresolvable";
-}
 export function createWriteProtectionCheck(entries, opts) {
     const matcher = compileWriteProtection(entries, opts);
     return matcher === undefined ? undefined : writeProtectionMountOver(matcher, opts?.rootPath);

package/dist/engine/compaction/compaction.d.ts

@@ -450,8 +450,8 @@ export interface CompactionPreparation {
      *  (raised in review as a contradiction; it is not one, but it was unstated). Byte-identity is
      *  over the SUMMARIZATION REQUEST ASSEMBLY, and there it is exact. Registering
      *  `<instruction-files>` in the authority census additionally puts it in the derived
-     *  fenced/shelled-lane sets, so external bytes that literally spell the tag are now defused with a
-     *  ZWSP on those lanes — for every deployment, seat or no seat. That is not a compatibility break
+     *  fenced/shelled-lane sets, so external bytes that literally spell the tag are now defused (an
+     *  entity in the bracket's place) on those lanes — for every deployment, seat or no seat. That is not a compatibility break
      *  smuggled in: those lanes rewrite bytes BY CONTRACT (that is what makes them fences), it is what
      *  registering any new authority envelope means in this tree, and the alternative — a
      *  model-facing authority tag that the fences built to defuse forgeries do not defuse — is

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

@@ -8,21 +8,6 @@ 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.
@@ -99,6 +84,9 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
     /** `ExecutionEnv.homeDir` = the `HOME` the shell child receives (its `~`/`$HOME`/`${HOME}` all expand to it), read LIVE off the same `shellEnv`-over-`inheritEnv` merge each exec gets; ABSENT when the
      *  child gets none (an allowlist that withholds it: `~` then falls back to passwd while `$HOME` is empty — two values, no single home, home-relative operands stay fail-closed). Residual: a per-exec `env.HOME` override. */
     get homeDir(): string | undefined;
+    /** `ExecutionEnv.cdPath` = the `CDPATH` the shell child receives, read LIVE off the same merge each exec gets (never the
+     *  engine process's own environment): its entries, `[]` when the child gets none. Residual: a per-exec `env.CDPATH`. */
+    get cdPath(): readonly string[];
     private shellPath?;
     private shellEnv?;
     private inheritEnv;
@@ -194,14 +182,8 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
     fileIdentity(path: string): Promise<Result<string, FileError>>;
     readLink(path: string): Promise<Result<string, FileError>>;
     /**
-     * The LEAF symlink chain ({@link FileSystem.canonicalChain}): `readlink` on the whole spelling, then on each
-     * 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`). 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.
+     * The LEAF symlink chain ({@link FileSystem.canonicalChain}): {@link walkSymlinkChain} over {@link readLinkTarget}
+     * (not the `readLink` method: a wrapper counting or overriding it sees only a caller's own calls).
      */
     canonicalChain(path: string): Promise<Result<SymlinkChain, FileError>>;
     exists(path: string): Promise<Result<boolean, FileError>>;