@sema-agent/core 7.20.0 → 7.21.0

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" },
@@ -156,6 +157,7 @@ function relativeUnderDataRoot(path, roots) {
     }
     return null;
 }
+export const WRITE_PROTECTION_TARGET_VIEWS = ["spelling-only", "target"];
 export function compileWriteProtection(entries, opts) {
     const rows = resolveWriteProtectedTable(entries);
     if (rows.length === 0)
@@ -206,16 +208,18 @@ 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;
     return {
         rows,
+        targetView: env === undefined ? "spelling-only" : "target",
         matchPath(path, cwd) {
             return judgeSpelling(path, cwd);
         },
@@ -225,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" };
         },
     };
 }
@@ -250,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",
         };
     }
@@ -265,11 +284,17 @@ 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)
         return undefined;
-    return (toolName, args, face, cwd, signal) => {
+    const check = (toolName, args, face, cwd, signal) => {
         const call = { toolName, args, ...(face !== undefined ? { face } : {}) };
         const protective = protectivePathTargetOf(call);
         if (protective === undefined || protective.access === "read")
@@ -279,4 +304,5 @@ export function createWriteProtectionCheck(entries, opts) {
             return null;
         return matcher.judge(path, { ...(cwd !== undefined ? { cwd } : {}), ...(signal !== undefined ? { signal } : {}), ...(() => { const b = pathTargetBaseOf(protective, { root: opts?.rootPath, cwd }); return b !== undefined ? { base: b } : {}; })() });
     };
+    return { check, targetView: matcher.targetView };
 }

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";
@@ -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, } 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 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/index.js

@@ -83,7 +83,7 @@ export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, }
 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, } from "./tools/fs/index.js";
 export { deploymentFaceClampNotice, resolveContainmentFace, } from "./tools/fs/index.js";
-export { WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, compileWriteProtection, } from "./core/write-protect.js";
+export { WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, compileWriteProtection, WRITE_PROTECTION_TARGET_VIEWS, } from "./core/write-protect.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, } 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, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, realApprovalOrgFact, resolveCheckpointStore, checkpointStoreExecutionUndeclared, } from "./core/checkpoint-store.js";
 export { EXECUTION_OUTCOME_RECORD_WORDS, EXECUTION_RECORD_LEAVES_ROW_UNRECORDED, ExecutionOutcomeConflictError, checkpointExecutionRecorded, executionRecordDisposition, sameExecutionRecord, executionVerdict, } from "./core/checkpoint-execution-record.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

@@ -307,11 +307,21 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
         const resolved = resolveOperandLexically(boundary.cwd ?? boundary.roots[0], word, boundary.homeDir);
         if (resolved === undefined || boundary.denyMatch?.(resolved) != null)
             return false;
-        return withinAnyRoot(boundary.roots, resolved);
+        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;

package/dist/tools/fs/safety.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { sliceHeadSafe } from "../../core/surrogate-safe-slice.js";
 import { pathTargetValue, protectivePathTargetOf } from "../../core/tool-registry.js";
+import { withGateTimeout, DEFAULT_GATE_AWAIT_TIMEOUT_MS } from "../../core/gate-bounded-await.js";
 export function fileArgPath(args) {
     const a = args;
     const fp = a?.file_path;
@@ -291,29 +292,6 @@ function stripWin32ExtendedPrefix(p) {
     }
     return unc ? "\\\\" + rest.slice(unc[0].length) : rest;
 }
-function foldUncLexically(p) {
-    const body = p.slice(2);
-    const segs = body.split(/[\\/]+/).filter((s) => s !== "");
-    const host = segs.shift() ?? "";
-    const share = segs.shift();
-    const out = [];
-    let climbed = false;
-    for (const seg of segs) {
-        if (seg === ".")
-            continue;
-        if (seg === "..") {
-            if (out.length === 0)
-                climbed = true;
-            else
-                out.pop();
-            continue;
-        }
-        const stripped = seg.replace(/[. ]+$/, "");
-        out.push(stripped.length > 0 ? stripped : seg);
-    }
-    const anchor = `\\\\${host}${share !== undefined ? `\\${share}` : ""}`;
-    return { key: out.length > 0 ? `${anchor}\\${out.join("\\")}` : anchor, climbedAboveShare: climbed };
-}
 export function hasWin32AliasedComponent(p) {
     if (!isWinFormPath(p))
         return false;
@@ -325,7 +303,7 @@ export function pathFamilyOf(bases) {
     const tree = bases.root ?? bases.cwd;
     return tree === undefined ? undefined : isWinFormPath(tree) ? "win" : "posix";
 }
-function isUncSpelling(p) {
+export function isUncSpelling(p) {
     return /^[\\/]{2}[^\\/]+[\\/]+[^\\/]/.test(p);
 }
 export function isAbsoluteForFamily(family, p) {
@@ -511,16 +489,26 @@ export async function canonicalizeTarget(env, path, signal, family, baseCwd) {
     if (!screened.ok) {
         return { ok: false, message: `path "${clipSpelling(path)}" ${WIN32_NAMESPACE_REFUSAL_TEXT[screened.refuse]}; refused (${screened.refuse}).`, refused: screened.refuse };
     }
-    const unprefixed = screened.spelled;
-    if (family === "win" && isUncSpelling(unprefixed)) {
-        const folded = foldUncLexically(unprefixed);
-        if (folded.climbedAboveShare) {
-            return { ok: false, message: `path "${path}" climbs above its UNC share root via ".." (\\\\host\\share is the root of a network path); refused.` };
-        }
-        return { ok: true, key: folded.key };
-    }
+    const unprefixed = nativeUncSpellingOf(family, screened.spelled);
     const spelled = family === "posix" && unprefixed.startsWith("//") ? unprefixed.replace(/^\/+/, "/") : unprefixed;
     const target = baseCwd && !isAbsoluteForFamily(family, spelled) ? joinForFamily(family, baseCwd, spelled) : spelled;
+    let thrownByProbe;
+    let seenThrow = false;
+    const probe = probeRealTarget(env, path, target, family, signal).catch((e) => {
+        thrownByProbe = e;
+        seenThrow = true;
+        throw e;
+    });
+    try {
+        return await withGateTimeout(probe, DEFAULT_GATE_AWAIT_TIMEOUT_MS, signal, "pathCanonicalization");
+    }
+    catch (err) {
+        if (seenThrow && err === thrownByProbe)
+            throw err;
+        return { ok: false, message: `cannot resolve path "${path}": ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+async function probeRealTarget(env, path, target, family, signal) {
     const absR = await env.absolutePath(target, signal);
     if (!absR.ok)
         return { ok: false, message: `cannot resolve path "${path}": ${absR.error.message}` };
@@ -531,7 +519,7 @@ export async function canonicalizeTarget(env, path, signal, family, baseCwd) {
             return { ok: false, message: `cannot determine whether "${path}" exists: ${exists.error.message}`, unresolvedSymlink: true };
         }
         if (!exists.value) {
-            const newPath = await canonicalizeNewPath(env, abs, signal);
+            const newPath = await canonicalizeNewPath(env, abs, family, signal);
             if (!newPath.ok) {
                 return { ok: false, message: newPath.message, unresolvedSymlink: true };
             }
@@ -545,7 +533,7 @@ export async function canonicalizeTarget(env, path, signal, family, baseCwd) {
             return { ok: false, message: `cannot determine whether "${path}" is a symlink: ${info.error.message}`, unresolvedSymlink: true };
         }
         if (info.value.kind !== "symlink") {
-            const viaAncestors = await canonicalizeNewPath(env, abs, signal, { skipLeaf: true });
+            const viaAncestors = await canonicalizeNewPath(env, abs, family, signal, { skipLeaf: true });
             if (!viaAncestors.ok) {
                 return { ok: false, message: viaAncestors.message, unresolvedSymlink: true };
             }
@@ -574,13 +562,26 @@ function parentDir(abs) {
     const head = abs.slice(0, i);
     return /^[A-Za-z]:$/.test(head) ? head + abs[i] : head;
 }
-async function canonicalizeNewPath(env, abs, signal, opts) {
+function uncAnchorIndex(parts) {
+    let seen = 0;
+    for (let i = 0; i < parts.length; i++) {
+        if (parts[i] === "")
+            continue;
+        seen++;
+        if (seen === 2)
+            return i;
+    }
+    return parts.length;
+}
+async function canonicalizeNewPath(env, abs, family, signal, opts) {
     const sep = nativeSepOf(abs);
-    const parts = isWinFormPath(abs) ? abs.split(/[\\/]/) : abs.split("/");
+    const winForm = family === "win" || isWinFormPath(abs);
+    const parts = winForm ? abs.split(/[\\/]/) : abs.split("/");
     const tail = [];
+    const floor = family === "win" && isUncSpelling(abs) ? uncAnchorIndex(parts) : 1;
     if (opts?.skipLeaf === true && parts.length > 1)
         tail.push(parts.pop());
-    while (parts.length > 1) {
+    while (parts.length > floor) {
         const candidate = parts.join(sep) || sep;
         const ex = await env.exists(candidate, signal);
         if (!ex.ok) {
@@ -591,7 +592,11 @@ async function canonicalizeNewPath(env, abs, signal, opts) {
             if (!canon.ok) {
                 return { ok: false, message: `cannot canonicalize existing ancestor "${candidate}": ${canon.error.message}` };
             }
-            return { ok: true, key: [canon.value, ...tail.reverse()].join(nativeSepOf(canon.value)) };
+            const tailSegments = tail.reverse();
+            const canonSep = nativeSepOf(canon.value);
+            if (tailSegments.length === 0)
+                return { ok: true, key: canon.value };
+            return { ok: true, key: [canon.value.replace(family === "win" ? /[\\/]+$/ : /\/+$/, ""), ...tailSegments].join(canonSep) };
         }
         tail.push(parts.pop());
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.20.0",
+  "version": "7.21.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -88,6 +88,7 @@
     "gate:docs-tool-names": "node scripts/verify-docs-tool-names.mjs",
     "gate:comment-ratio": "vitest run test/comment-ratio-ratchet.test.ts",
     "gate:negative-controls": "vitest run test/gate-negative-controls.test.ts",
+    "gate:memory-ga": "node scripts/gate-memory-distillation-ga.mjs",
     "gate:all": "node scripts/gate-all.mjs",
     "car:gate": "node scripts/car-gate.mjs"
   },