@sema-agent/core 7.20.1 → 7.21.1

package/dist/core/runner-deps.d.ts

@@ -391,6 +391,27 @@ export interface RunnerDeps {
         maxCycles?: number;
         mintRepairBudget?: number;
     };
+    /**
+     * The advisory-to-execution BRIDGE: when `true`, a terminal harvest that crosses
+     * the consolidation threshold (the same edge that mints `memory.consolidation_recommended`) fires
+     * ONE host consolidation run for the recommended scope at the post-task tail — fire-and-forget,
+     * result-first, never on the harvest tail itself. Explicit `false` = OFF (the deployment's own off
+     * switch; it beats the default). ABSENT = the named default `AUTO_RUN_ON_RECOMMENDATION_DEFAULT` (ON)
+     * (`memory-consolidation-driver.ts`, read through `autoRunOnRecommendationEffective` — the ONE
+     * resolver), applied ONLY where a run could actually happen (the protocol switch wired AND a model
+     * seat resolvable): a default-on value never arms a deployment that wired no consolidation.
+     *
+     * DEPLOYMENT seat ONLY (no TaskSpec twin), the same law as {@link RunnerDeps.memoryConsolidation} /
+     * {@link RunnerDeps.memoryConsolidationDriver}: arming this is an EGRESS decision — memory content crosses
+     * to the consolidation model automatically after every recommending task, never a task author's call.
+     *
+     * `true` with nothing to run (no {@link RunnerDeps.memoryConsolidation}, or no resolvable driver model
+     * seat), or a non-boolean, is refused at prepare (`config.auto_consolidation`) — never folded to off.
+     *
+     * Reported on the effective wiring manifest as `WiringManifest.autoConsolidation`, PRESENT IFF armed
+     * (absent and fingerprint-identical when off).
+     */
+    autoRunOnRecommendation?: boolean;
     /**
      * design/199 件A — the DEPLOYMENT's read-face declaration
      * ({@link import("../tools/fs/containment-face.js").ContainmentFace}; see {@link TaskSpec.readFace} for the

package/dist/core/sensitive-path-policy.js

@@ -4,6 +4,7 @@ import { canonicalizeTarget, expandHomeTilde, isAbsoluteForFamily, isWinFormPath
 import { compileSegmentPattern, matchSegmentPatterns, READ_FACE_BUILTIN_DENY_TABLE } from "../tools/fs/read-deny.js";
 import { isProtectedWrite, protectivePathTargetOf } from "./tool-registry.js";
 import { pathTargetBaseOf } from "./effective-path-target.js";
+import { symlinkChainHops } from "./path-identity.js";
 export function agentConfigDenyPatterns() {
     return READ_FACE_BUILTIN_DENY_TABLE.filter((row) => row.tier === "agent-config").map((row) => row.pattern);
 }
@@ -147,6 +148,18 @@ export function createSensitivePathPolicy(opts) {
                     decisionReason: "safety",
                 };
             }
+            if (relative === null) {
+                for (const hop of await symlinkChainHops(opts.env, path, signal, pathFamilyOf({ root: opts.rootPath, cwd: req.cwd ?? opts.env.cwd }), pathTargetBaseOf(protective, { root: opts.rootPath, cwd: req.cwd }))) {
+                    const viaHop = matchSensitive(hop, compiled, false);
+                    if (viaHop) {
+                        return {
+                            action: "deny",
+                            message: `write to "${path}" is blocked: its symlink chain passes through the guarded sensitive path "${viaHop}"`,
+                            decisionReason: "safety",
+                        };
+                    }
+                }
+            }
             return { action: "allow" };
         },
     };

package/dist/core/wiring-manifest.d.ts

@@ -347,6 +347,19 @@ export interface WiringManifest {
     writeProtection?: {
         targetView: WriteProtectionTargetView;
     };
+    /**
+     * EFFECTIVE half only. PRESENT IFF auto-consolidation is EFFECTIVELY armed on this
+     * deployment (`autoRunOnRecommendationEffective`: an explicit `true`, or an absent seat under the
+     * named default `AUTO_RUN_ON_RECOMMENDATION_DEFAULT` where both consolidation seats are wired): a
+     * terminal harvest that crosses the threshold auto-runs one host consolidation — memory content
+     * auto-egresses to the configured model. ABSENT (and the manifest, including `configFingerprint`,
+     * byte-identical) when not armed — an explicit `false`, or a default that does not arm it.
+     * IN the fingerprint (an assembly fact, the same class as {@link WiringManifest.writeProtection}); always
+     * `{ onRecommendation: true }` when present — the prepare door refuses an armed-but-unrunnable state.
+     */
+    autoConsolidation?: {
+        onRecommendation: true;
+    };
     /** EFFECTIVE half only — a short, non-sensitive fingerprint (sha256 prefix over the canonical
      *  JSON of this manifest's own resolved facts; every field here is an enum/boolean/count, no
      *  secrets) so an operator can correlate legs that ran under the same resolved assembly. */
@@ -428,6 +441,9 @@ export interface WiringFacts {
     /** Effective half only — the compiled write-protection judge's OWN target-view word
      *  ({@link WiringManifest.writeProtection}); absent ⇒ this leg compiled no judge (an emptied table). */
     writeProtectionTargetView?: WriteProtectionTargetView;
+    /** Effective half only — `RunnerDeps.autoRunOnRecommendation === true`
+     *  ({@link WiringManifest.autoConsolidation}); false ⇒ no section (byte-identical manifest). */
+    autoConsolidationOnRecommendation?: boolean;
 }
 /** Named view of the deps seats the static half reads (a `Pick` of the real {@link RunnerDeps} —
  *  single-source shapes, no parallel hand-copied interface). */

package/dist/core/wiring-manifest.js

@@ -142,6 +142,7 @@ export function deriveWiringManifest(facts) {
         ...(facts.half === "effective" && facts.hooks !== undefined && facts.hooks.length > 0 ? { hooks: facts.hooks.map((h) => ({ ...h })) } : {}),
         ...(facts.half === "effective" && facts.lsp !== undefined ? { lsp: { ...facts.lsp } } : {}),
         ...(facts.half === "effective" && facts.writeProtectionTargetView !== undefined ? { writeProtection: { targetView: facts.writeProtectionTargetView } } : {}),
+        ...(facts.half === "effective" && facts.autoConsolidationOnRecommendation === true ? { autoConsolidation: { onRecommendation: true } } : {}),
     };
     if (facts.half === "effective") {
         const { leg: _leg, mcp: _mcp, tools: _tools, lsp: _lsp, hooks: _hooks, ...assembly } = manifest;

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

@@ -51,7 +51,8 @@ export declare function resolveWriteProtectedTable(entries?: readonly WriteProte
  * 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;
  *  · `hit` — a row matched; `via` says which view named it: `"spelling"` (the anchored spelling, no
- *    filesystem consulted) or `"target"` (the resolved real target, the spelling being innocent);
+ *    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.
@@ -61,7 +62,7 @@ export type WriteProtectionVerdict = {
 } | {
     readonly kind: "hit";
     readonly hit: WriteProtectedHit;
-    readonly via: "spelling" | "target";
+    readonly via: "spelling" | "chain" | "target";
 } | {
     readonly kind: "unresolvable";
     readonly cause: string;
@@ -161,6 +162,17 @@ export declare function compileWriteProtection(entries?: readonly WriteProtected
  *  · `clear` ⇒ `undefined`: the surviving decision stands.
  */
 export declare function writeProtectionTightenDecision(toolName: string, verdict: WriteProtectionVerdict): PermissionResult | undefined;
+/**
+ * @contract write_protection.verdict_is_the_mandate — the judge's two non-clear verdicts are the two facts
+ * a standing allow rule may not retire, and `clear` is neither: a MATCHED row is the mandate a live decider
+ * may still clear, a target it could not RESOLVE is the mandate no automatic lane may. These two predicates
+ * are the ONE reading of a verdict as either fact, beside the decision mint, so the fold records what the
+ * judge said and never re-derives "was this write protection?" from the decision it got back.
+ */
+export declare function writeProtectionMandated(verdict: WriteProtectionVerdict): boolean;
+/** The second half of {@link writeProtectionMandated}'s contract: the judge could not name this target
+ *  (the arm that owns the ACTION denies on the same verdict). */
+export declare function writeProtectionUnresolved(verdict: WriteProtectionVerdict): boolean;
 /**
  * The ENGINE-FILLED gate input (`ToolGateInput.writeProtectionCheck`). Returns `null` SYNCHRONOUSLY when the
  * call is not this layer's business — not a covered write, or no resolvable target string — and otherwise

package/dist/core/write-protect.js

@@ -2,6 +2,7 @@ import { canonicalizeTarget, isWinFormPath, writeTargetPath, isUncPath, isAbsolu
 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";
 const freezeTable = (rows) => Object.freeze(rows.map((r) => Object.freeze(r)));
 export const WRITE_PROTECTED_DEFAULT_TABLE = freezeTable([
     { name: ".gitconfig", kind: "basename" },
@@ -207,11 +208,12 @@ export function compileWriteProtection(entries, opts) {
     const judgeViews = (spelling) => judgeSegments(pathViewSegments(spelling, false, POSIX_SEPARATOR_FAMILY, uncAnchorSegments(spelling))) ??
         judgeSegments(pathViewSegments(spelling, false)) ??
         judgeSegments(pathViewSegments(spelling, true));
+    const judgeSpelled = (spelled) => judgeViews(relativeUnderDataRoot(spelled, rootViews) ?? spelled);
     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 judgeViews(relativeUnderDataRoot(spelled, rootViews) ?? spelled);
+        return judgeSpelled(spelled);
     };
     const env = opts?.env;
     const rootPath = opts?.rootPath;
@@ -227,22 +229,35 @@ export function compileWriteProtection(entries, opts) {
                 return { kind: "hit", hit: bySpelling, via: "spelling" };
             if (env === undefined)
                 return { kind: "clear" };
-            const canon = await canonicalizeTarget(env, path, ctx.signal, pathFamilyOf({ root: rootPath, cwd: ctx.cwd ?? env.cwd }), ctx.base ?? ctx.cwd ?? rootPath);
+            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)
-                return { kind: "clear" };
-            for (const rootKey of await canonicalDataRootKeys(env, dataRootPaths, ctx.signal)) {
-                const relative = relativeUnderRoot(canon.key, rootKey);
-                if (relative === null)
+            if (byTarget !== null) {
+                for (const rootKey of await canonicalDataRootKeys(env, dataRootPaths, ctx.signal)) {
+                    const relative = relativeUnderRoot(canon.key, 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)) {
+                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" };
+                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" };
             }
-            return { kind: "hit", hit: byTarget, via: "target" };
+            return { kind: "clear" };
         },
     };
 }
@@ -252,7 +267,9 @@ export function writeProtectionTightenDecision(toolName, verdict) {
             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`
-                : `tool "${toolName}" writes to a write-protected path (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",
         };
     }
@@ -267,6 +284,12 @@ export function writeProtectionTightenDecision(toolName, verdict) {
     }
     return undefined;
 }
+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);
     if (matcher === undefined)

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

@@ -1,5 +1,6 @@
 import { type ExecResult, type ExecutionEnv, ExecutionError, type ExecutionEnvExecOptions, FileError, type FileInfo, type Result } from "../harness/types.js";
 import { type SecretEnvFinding } from "../../core/secret-env.js";
+import type { SymlinkChain } from "../harness/types.js";
 import type { BackgroundShellCapability, BackgroundShellId, BackgroundPoll, BackgroundSpawnOptions } from "../../core/background-shell.js";
 import { BackgroundShellError } from "../../core/background-shell.js";
 import type { SchedulerCapability, ScheduledIntent, SchedulerContext, ScheduledTaskId, ScheduledTaskSummary } from "../../core/scheduler.js";
@@ -165,6 +166,15 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
     listDir(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     canonicalPath(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`). 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>>;
     createDir(path: string, options?: {
         recursive?: boolean;

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

@@ -3,12 +3,13 @@ import { randomUUID } from "node:crypto";
 import { closeSync, constants, createReadStream, mkdtempSync, openSync, readSync, statSync, truncateSync, unlinkSync } from "node:fs";
 import { access, appendFile, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, rename, rm, unlink, writeFile, } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { createInterface } from "node:readline";
 import { ExecutionError, err, FileError, ok, toError, } from "../harness/types.js";
 import { killProcessTree, shutdownDebug } from "./kill-tree.js";
 import { scrubSecretEnv } from "../../core/secret-env.js";
 import { physicalPathOfAsync } from "../../core/physical-path.js";
+import { isUncSpelling } from "../../tools/fs/safety.js";
 import { RollingTailBuffer, markTruncated, newStreamCursorState, sliceStreamIncrement, } from "../../core/exec-output-tail.js";
 import { BackgroundShellError } from "../../core/background-shell.js";
 import { SchedulerError } from "../../core/scheduler.js";
@@ -41,6 +42,7 @@ function fileKindFromStats(stats) {
     return undefined;
 }
 const HAS_POSIX_MODE_FACE = process.platform !== "win32";
+const SYMLINK_CHAIN_HOP_BOUND = 64;
 function fileInfoFromStats(path, stats) {
     const kind = fileKindFromStats(stats);
     if (!kind) {
@@ -1026,6 +1028,32 @@ export class NodeExecutionEnv {
             return err(toFileError(error, resolved));
         }
     }
+    async canonicalChain(path) {
+        const resolved = resolvePath(this.cwd, path);
+        const hops = [];
+        const seen = new Set([resolved]);
+        let cur = resolved;
+        for (let hop = 0; hop < SYMLINK_CHAIN_HOP_BOUND; hop++) {
+            let target;
+            try {
+                target = await readlink(cur);
+            }
+            catch (error) {
+                if (isNodeError(error) && (error.code === "EINVAL" || error.code === "ENOENT" || error.code === "ENOTDIR"))
+                    return ok({ hops });
+                return err(toFileError(error, cur));
+            }
+            const next = isAbsolute(target) ? target : `${dirname(cur)}${sep}${target}`;
+            if (seen.has(next))
+                break;
+            hops.push(next);
+            if (process.platform === "win32" && isUncSpelling(next))
+                break;
+            seen.add(next);
+            cur = next;
+        }
+        return ok({ hops });
+    }
     async exists(path) {
         const result = await this.fileInfo(path);
         if (result.ok) {

package/dist/engine/harness/types.d.ts

@@ -271,6 +271,14 @@ export interface FileInfo {
      */
     mode?: number;
 }
+/**
+ * @contract fs.canonical_chain.leaf_hops_only — `hops` lists, in order, the target each link on the LEAF chain writes
+ * ({@link FileSystem.canonicalChain}): a relative target anchored, unfolded, at its own link's directory (`..` is the
+ * filesystem's to resolve on the next lookup, never the walk's); the addressed spelling and the canonical terminal ({@link FileSystem.canonicalPath}'s one answer) are not repeated; a directory-component symlink is not expanded; a non-link leaf answers `[]`.
+ */
+export interface SymlinkChain {
+    readonly hops: readonly string[];
+}
 /** Options for {@link Shell.exec}. */
 export interface ExecutionEnvExecOptions {
     /** Working directory for the command. Relative paths are resolved against {@link ExecutionEnv.cwd}. Defaults to {@link ExecutionEnv.cwd}. */
@@ -397,6 +405,8 @@ export interface FileSystem {
      * target of `write_file innocent.txt` where `innocent.txt -> .git/hooks/payload`.
      */
     readLink?(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** OPTIONAL: the LEAF symlink chain of `path` ({@link SymlinkChain}). Omitted, or `ok: false` ⇒ the path judges read the spelling and the canonical terminal only (the reach they had before this seat); a remote adapter answers in one `readlink` round trip and a caller never emulates it through {@link readLink}; bounded (64 hops, a cycle ends it), a network hop kept unprobed. */
+    canonicalChain?(path: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     /** Return false for missing paths. Other errors, such as permission failures, return a {@link FileError}. */
     exists(path: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     /** Create a directory. Defaults: `recursive: true`, no abort signal. */

package/dist/index.d.ts

@@ -87,7 +87,7 @@ export { isSecretEnvKey, scrubSecretEnv } from "./core/secret-env.js";
 export type { SecretEnvFinding, SecretEnvFindingKind } from "./core/secret-env.js";
 export { MAX_EXEC_OUTPUT_BYTES, RollingTailBuffer, markTruncated } from "./core/exec-output-tail.js";
 export { physicalPathOf, physicalPathOfExisting } from "./core/physical-path.js";
-export type { ExecutionEnv, FileInfo, Result, FileErrorCode, ExecutionErrorCode, WriteExpectation, WriteReceipt } from "./internal/harness.js";
+export type { ExecutionEnv, FileInfo, Result, FileErrorCode, ExecutionErrorCode, WriteExpectation, WriteReceipt, SymlinkChain } from "./internal/harness.js";
 export type { ExecResult } from "./internal/harness.js";
 export { RemoteExecutionError, hasDestroy, isRemoteExecutionEnv, isSuspendable, isIsolated, canonicalPathIsAuthoritative, missingRestoreSurface, isRetryableRemoteErrorCode, RETRYABLE_REMOTE_ERROR_CODES, } from "./core/remote-env.js";
 export { withRetry } from "./core/with-retry.js";

package/dist/internal/harness-types.d.ts

@@ -8,7 +8,7 @@ export type { CompactionPreparation, SummarizationClampDryRun } from "../engine/
 export type { InvokedSkillRetention } from "../engine/compaction/utils.js";
 export type { AgentCoreRuntimeDeps } from "../engine/loop/runtime-deps.js";
 export type { AgentMessage, AgentTool, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode, ToolInputValidationContext, ToolInputVerdict, } from "../engine/loop/types.js";
-export type { AgentHarnessEvent, CompactionSettings, ExecutionEnv, ExecutionErrorCode, FileError, FileErrorCode, FileInfo, Result, WriteExpectation, WriteReceipt, Session, SessionMetadata, SessionRepo, SessionStorage, SessionTreeEntry, Skill, } from "../engine/harness/types.js";
+export type { AgentHarnessEvent, CompactionSettings, ExecutionEnv, ExecutionErrorCode, FileError, FileErrorCode, FileInfo, Result, WriteExpectation, WriteReceipt, SymlinkChain, Session, SessionMetadata, SessionRepo, SessionStorage, SessionTreeEntry, Skill, } from "../engine/harness/types.js";
 export type { ExecutionEnvExecOptions, ExecResult } from "../engine/harness/types.js";
 export type { SessionWriteOptions, CompactionEntry } from "../engine/harness/types.js";
 export type { ActiveWorktreeSession, WorkspaceState } from "../engine/harness/types.js";

package/dist/tools/fs/bash-readonly-classifier.js

@@ -309,9 +309,19 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
             return false;
         return boundary.face === "open" || withinAnyRoot(boundary.roots, resolved);
     };
-    const unlistedSegmentJudgedInside = (words, from) => {
+    const unlistedSegmentJudgedInside = (words, from, leadingAssignments = []) => {
         if (boundary === undefined)
             return true;
+        const assignmentJudgedInside = (word) => {
+            const payload = assignmentWordPayload(word);
+            return payload === undefined || (payload.kind === "value" && stdinFileJudgedInside(payload.value));
+        };
+        for (const k of leadingAssignments) {
+            if (k >= from)
+                continue;
+            if (!assignmentJudgedInside(words.folded[k]))
+                return false;
+        }
         let endOfOptions = false;
         for (let j = from; j < words.folded.length; j++) {
             const word = words.folded[j];
@@ -330,6 +340,8 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
                 if (!stdinFileJudgedInside(candidate))
                     return false;
             }
+            if (!optionShaped && !assignmentJudgedInside(word))
+                return false;
         }
         return true;
     };
@@ -352,7 +364,7 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
                 continue;
             if (argvReentryUnjudged(pos, NO_PATH_OPERAND_COMMANDS))
                 return false;
-            if (!unlistedSegmentJudgedInside(words, pos.launchers[0].index))
+            if (!unlistedSegmentJudgedInside(words, pos.launchers[0].index, pos.assignments))
                 return false;
             continue;
         }
@@ -366,7 +378,7 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
             if (argvReentryUnjudged(pos, NO_PATH_OPERAND_COMMANDS))
                 return false;
             if (!listed(program.basename)) {
-                if (!unlistedSegmentJudgedInside(words, pos.launchers[0].index))
+                if (!unlistedSegmentJudgedInside(words, pos.launchers[0].index, pos.assignments))
                     return false;
                 continue;
             }
@@ -375,7 +387,7 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
         if (head === "cd" || UNMODELLED_BASE_MOVERS.has(head))
             continue;
         if (!allow.has(head)) {
-            if (!unlistedSegmentJudgedInside(words, program.index))
+            if (!unlistedSegmentJudgedInside(words, program.index, pos.assignments))
                 return false;
             continue;
         }
@@ -1516,6 +1528,18 @@ function isGrepFileStdinLongOption(tok) {
     return name !== undefined && isLongOptionAbbrevOf(name, "file");
 }
 const CLUSTER_OPTION_CHAR = /[A-Za-z0-9]/;
+const ASSIGNMENT_OR_APPEND_WORD = /^[A-Za-z_][A-Za-z0-9_]*\+?=/;
+function assignmentWordPayload(word) {
+    if (!ASSIGNMENT_OR_APPEND_WORD.test(word))
+        return undefined;
+    const eq = word.indexOf("=");
+    const value = word.slice(eq + 1);
+    if (word[eq - 1] === "+")
+        return { kind: "unresolved", reason: `"${word}" appends to a value the text does not contain` };
+    if (value.includes("~"))
+        return { kind: "unresolved", reason: `"${word}" carries a tilde whose expansion the text does not settle` };
+    return value === "" ? undefined : { kind: "value", value };
+}
 function attachedOptionPayloads(tok) {
     const literal = literalTildeSpelling;
     const out = [];
@@ -1651,6 +1675,11 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
                 continue;
             positionalOperands.push(t);
             judgeOperand(t, argGlobs(k));
+            const payload = assignmentWordPayload(t);
+            if (payload?.kind === "value")
+                judgeOperand(payload.value, argGlobs(k));
+            else if (payload?.kind === "unresolved")
+                findings.push({ kind: "unresolvable", operand: t, reason: `"${name}": ${payload.reason} ${NOT_AUTO_ALLOWED}` });
         }
     }
     for (let k = 0; k < args.length; k++) {
@@ -2163,7 +2192,7 @@ export function classifySimpleCommandReadBoundary(command, boundary) {
     return evaluateReadBoundary([toks], boundary, true);
 }
 const NOT_GATED = { gated: false, paths: [] };
-const UNREADABLE_WHITELIST_WORD = /[$`()*?[\]{}~]/;
+const UNREADABLE_WHITELIST_WORD = /[$`()*?[\]{}]/;
 const UNMODELLED_BASE_MOVERS = new Set(["pushd", "popd"]);
 export const COMMAND_LAUNCHERS_FOR_TEST = COMMAND_LAUNCHERS;
 const LAUNCHER_SCAN_HEAD = "cat";
@@ -2211,7 +2240,7 @@ export function classifyOutOfRootReadGate(command, allow, boundary) {
             if (UNMODELLED_BASE_MOVERS.has(name))
                 baseMoved = true;
             if (!allow.has(name) && name !== "cd") {
-                pushReader({ folded: [LAUNCHER_SCAN_HEAD, ...toks.folded.slice(i)], raw: [LAUNCHER_SCAN_HEAD, ...toks.raw.slice(i)], slotVerb: name });
+                pushReader({ folded: [LAUNCHER_SCAN_HEAD, ...toks.folded], raw: [LAUNCHER_SCAN_HEAD, ...toks.raw], slotVerb: name });
                 continue;
             }
             pushReader(i === 0 && name === written ? toks : { folded: [name, ...toks.folded.slice(i + 1)], raw: [toks.raw[i] ?? name, ...toks.raw.slice(i + 1)] });

package/dist/tools/fs/read-deny.d.ts

@@ -47,10 +47,12 @@ export interface ReadDenyMatcher {
     matchPath(path: string, opts?: {
         readonly aliasResolved?: boolean;
     }): ReadDenyHit | null;
-    /** §3.3 target judgment: canonical view + lexical view; EITHER hit decides. `aliasResolved`
-     *  applies to the CANONICAL arm only — the lexical view is an unresolved spelling. */
+    /** §3.3 target judgment: canonical view + lexical view + every hop of the leaf symlink chain (`hops`,
+     *  each an unresolved spelling some link wrote); ANY hit decides. `aliasResolved` applies to the
+     *  CANONICAL arm only — the lexical view and the hops are unresolved spellings. */
     matchTarget(canonicalKey: string, lexicalView?: string, opts?: {
         readonly aliasResolved?: boolean;
+        readonly hops?: readonly string[];
     }): ReadDenyHit | null;
     /** Traversal exclusions for the rg legs: `!`-polarity glob pairs — `!**\/<p>` plus `!**\/<p>/…`
      *  (the entry itself and its descendants). */

package/dist/tools/fs/read-deny.js

@@ -227,6 +227,11 @@ export function compileReadDeny(additions = [], layer = "additions", builtin) {
                 if (lexical !== null)
                     return { ...lexical, matchedView: lexicalView };
             }
+            for (const hop of opts?.hops ?? []) {
+                const viaHop = matchPath(hop);
+                if (viaHop !== null)
+                    return { ...viaHop, matchedView: hop };
+            }
             return null;
         },
         rgExclusionGlobs,

package/dist/tools/fs/safety.d.ts

@@ -290,6 +290,10 @@ export declare function pathFamilyOf(bases: {
     readonly root?: string | undefined;
     readonly cwd?: string | undefined;
 }): PathFamily | undefined;
+/** UNC under the win family: two leading separators, a host, a share — either separator, as `path.win32`
+ *  reads it. The ONE UNC recognizer behind {@link isAbsoluteForFamily}, {@link pathIdentityOf} and
+ *  {@link joinForFamily}. */
+export declare function isUncSpelling(p: string): boolean;
 /**
  * FULLY QUALIFIED under the family. win: drive-rooted (`C:\`/`C:/`) or UNC — a `/x` / `\x` is rooted-not-
  * qualified and joins the base's drive or share root ({@link joinForFamily}), a `C:rel` is drive-relative.
@@ -422,6 +426,14 @@ export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, pat
  * `createSensitivePathPolicy` (which matches the real target against a guarded list).
  * A single source of truth for symlink resolution: a sensitive-path policy that matched the raw path
  * instead of the real target would compare against the spelling, not the destination.
+ *
+ * @contract fs.canonical_target.probed_and_bounded — every model-spelled path is resolved by asking the
+ * execution environment where it really lands; no spelling shape is exempt from that, and the win-form
+ * UNC spelling stopped being the one that was. The ask is bounded by the tree's shared bounded-await
+ * deadline rather than by a timer of this module's own, and a wait that elapses or a probe that fails
+ * comes back as a refusal carrying no key — the spelling is never handed back as a substitute for the
+ * answer. What the deadline bounds is the CALLER'S wait: the underlying filesystem call is not
+ * cancellable and may go on occupying the runtime's I/O capacity until the kernel gives up.
  */
 export declare function canonicalizeTarget(env: ExecutionEnv, path: string, signal: AbortSignal | undefined, family: PathFamily, baseCwd?: string): Promise<{
     ok: true;