@sema-agent/core 5.63.0 → 5.64.0

package/dist/orchestration/run-workflow-tool.js

@@ -492,6 +492,7 @@ export async function createRunWorkflowTool(d) {
                     ...(sourceTaskId !== undefined ? { sourceTaskId } : {}),
                     ...(d.originatingSessionId !== undefined ? { originatingSessionId: d.originatingSessionId } : {}),
                     ...((ctx.rootSessionId ?? d.rootSessionId ?? d.originatingSessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? d.rootSessionId ?? d.originatingSessionId } : {}),
+                    ...((ctx.placementRoot ?? d.placementRoot) !== undefined ? { placementRoot: ctx.placementRoot ?? d.placementRoot } : {}),
                     ...(workflowTaskId !== undefined ? { runId: workflowTaskId } : {}),
                     journalStore: d.journalStore,
                     ...(resumeFromRunId !== undefined ? { resumeFromRunId } : {}),

package/dist/orchestration/workflow.d.ts

@@ -297,6 +297,12 @@ export interface RunWorkflowOptions {
      *  `ctx.rootSessionId ?? originatingSessionId`); rides the wa* observer frames so a recovery face
      *  groups workflow-agent rows under the root host session too. */
     rootSessionId?: string;
+    /** design/380 O1② (C12) — the host run's EXPLICIT placement fixed point
+     *  (`RunInternals.placementRoot`, threaded by the run-workflow tool when the host carried one):
+     *  every workflow-spawned agent inherits it verbatim so descendants of a cascade/verify leg stay
+     *  placed at the ladder/gate root. Absent ⇒ nothing extra travels (the rootSessionId chain is the
+     *  placement root through prepare's mint middle segment). */
+    placementRoot?: string;
     /** design/149 — the PROCESS-level child observer (same seam as
      *  {@link import("../core/types.js").RunnerDeps.onBackgroundChildEvent}). When set, every workflow
      *  agent emits spawn/tick/terminal {@link import("../core/types.js").BackgroundChildEvent} frames with a

package/dist/orchestration/workflow.js

@@ -526,6 +526,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         ...(opts.onForwardEvent ? { onForwardEvent: opts.onForwardEvent } : {}),
         ...(opts.inheritedGate !== undefined ? { inheritedGate: opts.inheritedGate } : {}),
         ...((opts.rootSessionId ?? opts.originatingSessionId) !== undefined ? { rootSessionId: opts.rootSessionId ?? opts.originatingSessionId } : {}),
+        ...(opts.placementRoot !== undefined ? { placementRoot: opts.placementRoot } : {}),
     };
     const bceSink = opts.onBackgroundChildEvent;
     const bceEmit = (e) => {

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

@@ -15,11 +15,46 @@
  * but state-MUTATING with args, which an argv[0]-only filter cannot tell apart. Leaving them in defeated
  * both the `effect:read` truthfulness here and the classifier's irreversibility promise (a `date -s` would
  * auto-allow an irreversible clock jump under `shellGate:"classify"`).
+ *
+ * backlog #482 (CC parity): rows 3-4 are the CC-anchored expansion — the members of CC's safe-command
+ * set (pretty223.js:420513-420565 `e6s`; identical in the 220 corpus; the 220→245 campaign diff records
+ * no change on this face) that satisfy THIS list's curation bar (no write/mutation mode under any args)
+ * without new stdin-floor/option-value modeling: pure status/computation printers (`cal`…`sleep` — none
+ * reads stdin when bare, none takes a path it READS except realpath/readlink, which stay boundary-judged)
+ * plus the floor-2 content comparers `diff`/`cmp`/`comm` (STDIN_FILE_FLOOR rows added alongside; diff's
+ * recursive form was already modeled in RECURSIVE_READ_FORMS). Still deliberately excluded, each for a
+ * stated reason: `env` (an executor: `env FOO=1 cmd` runs cmd — CC excludes it too), `sort` (`-o` writes),
+ * `uniq` (second positional is an OUTPUT file; CC allows a flags-only regex form this filter cannot
+ * express), `printf` (builtin `-v var` assigns), `find` (CC allows only a regex excluding
+ * `-delete`/`-exec`/…), and the bare-stdin text filters (`od`/`strings`/`nl`/`tsort`/`pr`/…) whose
+ * value-taking options defeat the stdin-floor operand count without a per-verb option-value model (#109)
+ * — those are a follow-on slice, not a silent drop.
  */
 /** The verdict every unresolvable / out-of-root / unbounded finding ends on. The findings differ in what
  *  they found; the consequence is one consequence, and a copy that drifts reads as a second rule. */
 export declare const NOT_AUTO_ALLOWED = "\u2014 not auto-allowed";
 export declare const BASH_READONLY_DEFAULT_ALLOW: readonly string[];
+/**
+ * backlog #482 slice 2 — the CLASSIFY face's default allow set: the shared list PLUS the verbs that are
+ * admissible only where the compound classifier's per-verb judgment runs, and NOT on the shared list's
+ * other consumer faces:
+ *  · `find` — read-only only when no CC `aCy` dangerous predicate token is present (guard arm);
+ *  · `sed`  — read-only only in CC's `_Ld` grammar (guard arm);
+ *  · `cd`   — never touches the filesystem, but it MUTATES the persistent shell's committed cwd, so it
+ *    must not reach the shared list's `isConcurrencySafe` consumer (a parallel-batch `cd` reorders
+ *    every sibling's working directory) or the `effect:"read"` declaration face; the classify face's
+ *    EXISTING cd boundary arm (glob/no-arg/`-` conservative, target judged against the roots) is what
+ *    makes it admissible here.
+ * The bash_readonly DECLARATION face checks names without argument vetting (its own header says so), so
+ * none of the three may join {@link BASH_READONLY_DEFAULT_ALLOW}: `find . -delete` / `sed -i` under an
+ * `effect:"read"` declaration would falsify it. Consumed as
+ * {@link import("./fs-bash.js").bashReversibilityProbe}'s default when the caller passes NO allow list —
+ * a caller-narrowed list is honored verbatim (naming these verbs there opts into the same guard/boundary
+ * arms; omitting them keeps them refused), so the superset can never widen a narrowed deployment. The
+ * poll-loop face inherits the guard arms for free: its body vetting delegates to the same compound
+ * classifier.
+ */
+export declare const BASH_CLASSIFY_DEFAULT_ALLOW: readonly string[];
 /**
  * G2 — options for {@link parseLeadingCommandName}. Omitting them keeps the parser byte-identical to
  * what every existing caller (the `bash_readonly` declaration face, the coarse command-name policy, the
@@ -293,7 +328,15 @@ export declare function formatOutOfRootReadApprovalOption(directory: string): st
  * out-of-root signal; the boundary scan below only ever converts a would-be READ-ONLY verdict into a
  * demotion, which is why omitting `boundary` reproduces the pre-RB-412 behaviour exactly.
  */
-export declare function classifyCompoundReadonlyDetailed(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
+export declare function classifyCompoundReadonlyDetailed(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary, 
+/** backlog #482 slice 3 (C4): the poll-loop face passes `iterated:true` over a body REPLICATED
+ *  `beats` times — a single cd repeated per iteration is a legitimate accumulating shift, not the
+ *  ">1 cd = ask for clarity" compound CC refuses (a `for` loop is a sema-only face; CC asks for any
+ *  loop). It suppresses ONLY that multi-cd refuse; every read is still threaded + boundary-judged
+ *  against its real per-iteration base, so the escape a climbing loop opens is still caught. */
+opts?: {
+    readonly iterated?: boolean;
+}): CompoundReadonlyVerdict;
 /**
  * RB-413 — the read boundary ALONE, for the `bash_readonly` face.
  *

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

@@ -3,7 +3,10 @@ export const NOT_AUTO_ALLOWED = "— not auto-allowed";
 export const BASH_READONLY_DEFAULT_ALLOW = [
     "ls", "cat", "head", "tail", "wc", "pwd", "echo", "whoami", "uname",
     "grep", "cut", "tr", "basename", "dirname", "stat", "du", "df", "which",
+    "cal", "uptime", "id", "groups", "nproc", "locale", "free", "realpath", "readlink",
+    "true", "false", "seq", "expr", "type", "sleep", "diff", "cmp", "comm",
 ];
+export const BASH_CLASSIFY_DEFAULT_ALLOW = [...BASH_READONLY_DEFAULT_ALLOW, "find", "sed", "cd"];
 const SHELL_OPERATORS = /[;&|<>$()`\n\r\\]/;
 function quoteMask(s) {
     const quoted = new Array(s.length).fill(false);
@@ -166,7 +169,10 @@ export function formatOutOfRootReadApprovalOption(directory) {
     const leaf = cut >= 0 ? trimmed.slice(cut + 1) : trimmed;
     return `Yes, allow reading from ${leaf || directory}/ from this project`;
 }
-const NO_PATH_OPERAND_COMMANDS = new Set(["pwd", "echo", "whoami", "uname", "which", "tr", "basename", "dirname"]);
+const NO_PATH_OPERAND_COMMANDS = new Set([
+    "pwd", "echo", "whoami", "uname", "which", "tr", "basename", "dirname",
+    "cal", "uptime", "id", "groups", "nproc", "locale", "free", "true", "false", "seq", "expr", "type", "sleep",
+]);
 function isPathShapedToken(tok) {
     return tok.includes("/") || tok.startsWith("~") || tok === "." || tok === "..";
 }
@@ -311,6 +317,8 @@ const SEPARATED_VALUE_OPTIONS = {
             "exclude-dir",
         ],
     },
+    cmp: { short: "ni", long: ["bytes", "ignore-initial"] },
+    diff: { short: "UCWIFxL", ownsValueButNotSkippable: "SX", long: ["unified", "context", "width", "ignore-matching-lines", "show-function-line", "exclude", "label", "horizon-lines", "tabsize"] },
 };
 function takesSeparatedValue(name, tok) {
     const model = SEPARATED_VALUE_OPTIONS[name];
@@ -353,6 +361,98 @@ const RECURSIVE_READ_FORMS = {
     tar: { shortLetters: "cru", valueOwners: "fCTXbg", longNames: ["create", "append", "update"], bundledModeLetters: "cru", dashIsStdin: true },
     diff: { shortLetters: "r", valueOwners: "UCWISFXx", longNames: ["recursive"], dashIsStdin: true },
 };
+const FIND_DANGEROUS_PREDICATES = new Set([
+    "-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprint0", "-fls", "-fprintf", "-files0-from",
+]);
+const SED_READONLY_FLAGS = new Set([
+    "-n", "--quiet", "--silent", "-E", "--regexp-extended", "-r", "-z", "--zero-terminated", "--posix",
+]);
+const SED_READONLY_CLUSTER_LETTERS = new Set(["n", "E", "r", "z"]);
+const SED_READONLY_SCRIPT_PIECE = /^(?:\d+|\d+,\d+)?p$/;
+function guardedVerbFormReason(name, toks, raw) {
+    if (name === "find") {
+        for (const t of toks) {
+            if (FIND_DANGEROUS_PREDICATES.has(t)) {
+                return `\`find ${t}\` executes a command or writes a file — not a read ${NOT_AUTO_ALLOWED}`;
+            }
+        }
+        for (const rt of raw.slice(1)) {
+            if (hasUnquotedGlobMetachar(rt) || hasUnquotedExpansionMetachar(rt)) {
+                return `\`find\` is given the unquoted pattern "${rt}", which the shell may expand into other arguments before find runs ${NOT_AUTO_ALLOWED}`;
+            }
+        }
+        return undefined;
+    }
+    if (name === "sed") {
+        for (const rt of raw.slice(1)) {
+            if (hasUnquotedGlobMetachar(rt) || hasUnquotedExpansionMetachar(rt)) {
+                return `\`sed\` is given the unquoted pattern "${rt}", which the shell may expand into other arguments (a file named like a flag becomes a live option) before sed runs ${NOT_AUTO_ALLOWED}`;
+            }
+        }
+        const flags = [];
+        const operands = [];
+        let endOfOptions = false;
+        for (const t of toks.slice(1)) {
+            if (!endOfOptions && t === "--") {
+                endOfOptions = true;
+                continue;
+            }
+            if (!endOfOptions && t.startsWith("-")) {
+                flags.push(t);
+                continue;
+            }
+            operands.push(t);
+        }
+        for (const f of flags) {
+            if (SED_READONLY_FLAGS.has(f))
+                continue;
+            if (/^-[A-Za-z]+$/.test(f) && f.length > 2 && [...f.slice(1)].every((ch) => SED_READONLY_CLUSTER_LETTERS.has(ch)))
+                continue;
+            return `\`sed ${f}\` is outside the read-only sed form (-n plus print-only script) ${NOT_AUTO_ALLOWED}`;
+        }
+        const quiet = flags.some((f) => f === "-n" || f === "--quiet" || f === "--silent" || (/^-[A-Za-z]+$/.test(f) && f.includes("n")));
+        if (!quiet)
+            return `\`sed\` without \`-n\` echoes its whole input — only the -n print-only form is read-classified ${NOT_AUTO_ALLOWED}`;
+        const script = operands[0];
+        if (script === undefined)
+            return `\`sed\` with no script ${NOT_AUTO_ALLOWED}`;
+        for (const piece of script.split(";")) {
+            if (!SED_READONLY_SCRIPT_PIECE.test(piece.trim())) {
+                return `\`sed\` script "${script}" is not a pure print command (N[,M]p) ${NOT_AUTO_ALLOWED}`;
+            }
+        }
+        return undefined;
+    }
+    if (name === "free") {
+        for (const t of toks.slice(1)) {
+            if (/^--seconds(=.*)?$/.test(t) || /^-[A-Za-z0-9]*s[A-Za-z0-9]*$/.test(t)) {
+                return `\`free ${t}\` repeats until killed — it never terminates on its own ${NOT_AUTO_ALLOWED}`;
+            }
+        }
+        return undefined;
+    }
+    if (name === "sleep") {
+        return pollLoopSleepReason(toks.join(" "));
+    }
+    if (name === "seq") {
+        for (const t of toks.slice(1)) {
+            if (t.startsWith("-") && t !== "-" && !/^-\d/.test(t))
+                continue;
+            if (!/^-?\d{1,6}$/.test(t)) {
+                return `\`seq ${t}\` is not a small literal integer bound — the output cannot be bounded statically ${NOT_AUTO_ALLOWED}`;
+            }
+        }
+        return undefined;
+    }
+    if (name === "diff") {
+        for (const t of toks.slice(1)) {
+            if (/^--[A-Za-z-]+=-$/.test(t) || /^-[A-Za-z]*[SX]-$/.test(t)) {
+                return `\`diff ${t}\` names stdin inside a fused option — a read this check cannot see through ${NOT_AUTO_ALLOWED}`;
+            }
+        }
+    }
+    return undefined;
+}
 function segmentSelectsRecursiveRead(name, args) {
     const model = RECURSIVE_READ_FORMS[name];
     if (model === undefined)
@@ -577,7 +677,7 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
     }
     return findings;
 }
-export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
+export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts) {
     const trimmed = command.trim();
     if (!trimmed)
         return { reason: "empty command" };
@@ -622,7 +722,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
         }
         return byteBound;
     };
-    const STDIN_FILE_FLOOR = { cat: 1, grep: 2, head: 1, tail: 1, wc: 1, cut: 1, tr: Infinity };
+    const STDIN_FILE_FLOOR = { cat: 1, grep: 2, head: 1, tail: 1, wc: 1, cut: 1, tr: Infinity, diff: 2, cmp: 2, comm: 2, sed: 2 };
     const foldedSegments = [];
     for (let si = 0; si < segments.length; si++) {
         const segmentTokens = tokenizeSegment(segments[si]);
@@ -631,6 +731,9 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
             continue;
         foldedSegments.push(segmentTokens);
         const name = toks[0];
+        const guardReason = guardedVerbFormReason(name, toks, segmentTokens.raw);
+        if (guardReason !== undefined)
+            return { reason: guardReason };
         if (!(pipeFed[si] ?? false)) {
             const floor = STDIN_FILE_FLOOR[name];
             const restArgs = toks.slice(1);
@@ -696,8 +799,17 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
             return { reason: "reads a device/special file that is either unbounded (/dev/zero, /dev/stdin, /proc/<pid>/fd/0, … — blocks the pipeline until the tool timeout) or process-private (/proc/<pid>/environ, /proc/<pid>/mem, …) " + NOT_AUTO_ALLOWED };
         }
     }
+    if (opts?.iterated !== true) {
+        const cdSegments = foldedSegments.filter((st) => st.folded[0] === "cd");
+        if (cdSegments.length > 1) {
+            return { reason: `multiple directory changes in one command require approval for clarity ${NOT_AUTO_ALLOWED}` };
+        }
+    }
     if (boundary !== undefined)
         return evaluateReadBoundary(foldedSegments, boundary);
+    if (foldedSegments.some((st) => st.folded[0] === "cd")) {
+        return { reason: `\`cd\` cannot be judged without a read boundary (no base to resolve the directory change against) ${NOT_AUTO_ALLOWED}` };
+    }
     return {};
 }
 function evaluateReadBoundary(foldedSegments, boundary) {
@@ -705,8 +817,10 @@ function evaluateReadBoundary(foldedSegments, boundary) {
     const inside = [];
     const undecided = [];
     const recursive = [];
+    let currentBase = boundary.cwd ?? boundary.roots[0];
     for (const toks of foldedSegments) {
-        for (const finding of collectSegmentBoundaryFindings(toks, boundary)) {
+        const segBoundary = currentBase === (boundary.cwd ?? boundary.roots[0]) ? boundary : { ...boundary, cwd: currentBase };
+        for (const finding of collectSegmentBoundaryFindings(toks, segBoundary)) {
             if (finding.kind === "unresolvable")
                 return { reason: finding.reason };
             const denied = boundary.denyMatch?.(finding.path);
@@ -738,6 +852,14 @@ function evaluateReadBoundary(foldedSegments, boundary) {
             if (!outside.some((o) => o.path === finding.path))
                 outside.push(finding);
         }
+        if (toks.folded[0] === "cd") {
+            const cdArgs = toks.folded.slice(1);
+            const cdTargetIdx = cdArgs.findIndex((t) => !t.startsWith("-") || t === "-");
+            const cdTarget = cdTargetIdx === -1 ? undefined : cdArgs[cdTargetIdx];
+            if (cdTarget !== undefined && cdTarget !== "-") {
+                currentBase = resolveOperandLexically(currentBase, cdTarget, boundary.homeDir) ?? currentBase;
+            }
+        }
     }
     const undecidedAll = [...undecided, ...recursive.filter((p) => !undecided.includes(p))];
     const undecidedField = {
@@ -851,7 +973,12 @@ export function classifyBoundedReadonlyPollLoop(command, allow, boundary) {
     if (readSegments.length === 0) {
         return "the loop body has no read command — a sleep-only loop observes nothing and is not auto-allowed";
     }
-    const verdict = classifyCompoundReadonlyDetailed(readSegments.join("; "), allow, boundary);
+    const bodyHasCd = readSegments.some((seg) => {
+        const p = parseLeadingCommandName(seg);
+        return "name" in p && p.name === "cd";
+    });
+    const modelled = bodyHasCd ? Array.from({ length: beats }, () => readSegments.join("; ")).join("; ") : readSegments.join("; ");
+    const verdict = classifyCompoundReadonlyDetailed(modelled, allow, boundary, { iterated: bodyHasCd });
     if (verdict.reason !== undefined)
         return verdict.reason;
     if (verdict.recursiveReadPaths !== undefined) {

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

@@ -11,7 +11,7 @@ import { isRemoteExecutionEnv, hasDestroy, isIsolated } from "../../core/remote-
 import { ghRateLimitHint } from "./gh-rate-limit.js";
 import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, createShellOverflowSpoolFence, shellRecoveryHint, CWD_SENTINEL, BASH_READONLY_CONFINEMENT_NOTE, } from "./fs-shared.js";
 import { PROBE_CAUSE_PATH_MAX, inlineUntrusted } from "../../core/untrusted-text.js";
-import { BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoop, classifyCompoundReadonlyDetailed, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
+import { BASH_CLASSIFY_DEFAULT_ALLOW, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoop, classifyCompoundReadonlyDetailed, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
 const RECURSIVE_CAUSE_MAX_PATHS = 3;
 const RECURSIVE_READ_CAUSE_CODE = "shell.recursive_read_unbounded";
 function operandFamily(paths) {
@@ -22,7 +22,7 @@ function operandFamily(paths) {
     };
 }
 export function bashReversibilityProbe(allow, boundary) {
-    const allowSet = new Set(allow ?? BASH_READONLY_DEFAULT_ALLOW);
+    const allowSet = new Set(allow ?? BASH_CLASSIFY_DEFAULT_ALLOW);
     return (args) => {
         const a = args;
         const command = a?.command;
@@ -312,6 +312,13 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
                 isError: true,
             };
         }
+        if (res.error.code === "target_unavailable") {
+            return {
+                content: `Error (${toolName.slice(0, 64)}): the execution target is unavailable (offline/busy/not bound), so the command did NOT start and no effects landed. Retrying the same command is safe once the target is reachable again. (${res.error.message.slice(0, 512)})`,
+                details: { type: "bash", targetUnavailable: true },
+                isError: true,
+            };
+        }
         if (res.error.code === "timeout" || res.error.code === "aborted" || res.error.code === "callback_error") {
             const rawStdout = res.error.partialStdout ?? "";
             const rawStderr = res.error.partialStderr ?? "";

package/dist/tools/fs/fs-write.js

@@ -4,6 +4,16 @@ import { defineTool, errorResult } from "../../core/tools.js";
 import { sha256, resolveKey, violationText, violationDetails, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, READ_REFUSED_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText } from "./encoding.js";
 import { MAX_EDIT_BYTES, decodeEditBytes, tooLargeToEditMessage, truncatedUtf16BodyMessage, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, ipynbRedirect, countLines, } from "./fs-shared.js";
+async function envFinalWrite(env, key, content, signal, opts) {
+    if (env.writeFileGuarded !== undefined) {
+        const r = await env.writeFileGuarded(key, content, { canonicalPath: key, ...(opts?.exclusive === true ? { exclusive: true } : {}) }, signal);
+        return r.ok ? { ok: true } : r;
+    }
+    if (opts?.exclusive === true && env.writeFileExclusive !== undefined) {
+        return env.writeFileExclusive(key, content, signal);
+    }
+    return env.writeFile(key, content, signal);
+}
 async function gateToolWrite(hook, tool, path, key, content) {
     if (hook === undefined)
         return undefined;
@@ -71,13 +81,14 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                     const gated = await gateToolWrite(beforeWrite, "Edit", path, r.key, created);
                     if (gated !== undefined)
                         return errorResult(gated);
-                    const write = env.writeFileExclusive !== undefined
-                        ? await env.writeFileExclusive(r.key, created, ctx.signal)
-                        : await env.writeFile(r.key, created, ctx.signal);
+                    const write = await envFinalWrite(env, r.key, created, ctx.signal, { exclusive: true });
                     if (!write.ok) {
                         if (write.error.code === "already_exists") {
                             return errorResult(`Error (Edit): cannot create "${path}": file already exists (created concurrently since the existence check). Read the file first, then edit it normally (or Write after the Read to overwrite it).`);
                         }
+                        if (write.error.code === "precondition_failed") {
+                            return errorResult(`Error (Edit): cannot create "${path.slice(0, 512)}": the atomic write refused its precondition (${write.error.message.slice(0, 512)}) — the on-disk state at that path changed between the existence check and the write (something may now exist there, or the path may now resolve somewhere else, e.g. through a symlink). Nothing was written. Read the path to see what is actually there before acting on it.`);
+                        }
                         return errorResult(`Error (Edit): cannot write "${path}": ${write.error.message}`);
                     }
                     const createdNorm = normalizeFileText(created);
@@ -121,7 +132,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                 if (gated !== undefined)
                     return errorResult(gated);
                 const encodedOverwrite = encodeTextForFile(newContent, preDec.encoding, preDec.endings);
-                const write = await env.writeFile(r.key, encodedOverwrite, ctx.signal);
+                const write = await envFinalWrite(env, r.key, encodedOverwrite, ctx.signal);
                 if (!write.ok)
                     return errorResult(`Error (Edit): cannot write "${path}": ${write.error.message}`);
                 const persistedOverwrite = persistedTextOf(encodedOverwrite);
@@ -194,7 +205,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
             if (gated !== undefined)
                 return errorResult(gated);
             const encodedEdit = encodeTextForFile(working, decoded.encoding, decoded.endings);
-            const write = await env.writeFile(r.key, encodedEdit, ctx.signal);
+            const write = await envFinalWrite(env, r.key, encodedEdit, ctx.signal);
             if (!write.ok)
                 return errorResult(`Error (Edit): cannot write "${path}": ${write.error.message}`);
             const persistedEdit = persistedTextOf(encodedEdit);
@@ -265,7 +276,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
                 if (gated !== undefined)
                     return errorResult(gated);
                 const encodedWrite = encodeTextForFile(content, decodedPrev.encoding, "preserve");
-                const write = await env.writeFile(r.key, encodedWrite, ctx.signal);
+                const write = await envFinalWrite(env, r.key, encodedWrite, ctx.signal);
                 if (!write.ok)
                     return errorResult(`Error (Write): cannot write "${path}": ${write.error.message}`);
                 const persistedWrite = persistedTextOf(encodedWrite);
@@ -278,7 +289,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             const gatedCreate = await gateToolWrite(beforeWrite, "Write", path, r.key, content);
             if (gatedCreate !== undefined)
                 return errorResult(gatedCreate);
-            const write = await env.writeFile(r.key, content, ctx.signal);
+            const write = await envFinalWrite(env, r.key, content, ctx.signal);
             if (!write.ok)
                 return errorResult(`Error (Write): cannot write "${path}": ${write.error.message}`);
             const totalLines = countLines(content);
@@ -409,7 +420,7 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
             const gated = await gateToolWrite(beforeWrite, "NotebookEdit", notebook_path, r.key, updated);
             if (gated !== undefined)
                 return errorResult(gated);
-            const w = await env.writeFile(r.key, encodeTextForFile(updated, decodedNb.encoding, decodedNb.endings), ctx.signal);
+            const w = await envFinalWrite(env, r.key, encodeTextForFile(updated, decodedNb.encoding, decodedNb.endings), ctx.signal);
             if (!w.ok)
                 return errorResult(`Error (NotebookEdit): cannot write "${notebook_path}": ${w.error.message}`);
             state.set(r.key, { hash: sha256(updated), totalLines: countLines(updated), truncated: false, lastReadAt: Date.now() });

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

@@ -11,6 +11,7 @@ export * from "./fs-search-tools.js";
 export * from "./bash-readonly-classifier.js";
 export * from "./fs-bash.js";
 export * from "./read-deny.js";
+export { BASH_CLASSIFY_DEFAULT_ALLOW } from "./bash-readonly-classifier.js";
 import { type ReadDenyEntry } from "./read-deny.js";
 export * from "./read-face.js";
 import { type CwdRef, type ReadImageDownsamplerOption } from "./fs-shared.js";

package/dist/tools/fs/index.js

@@ -12,6 +12,7 @@ export * from "./bash-readonly-classifier.js";
 export * from "./fs-bash.js";
 export * from "./read-deny.js";
 import { BASH_READONLY_DEFAULT_ALLOW, } from "./bash-readonly-classifier.js";
+export { BASH_CLASSIFY_DEFAULT_ALLOW } from "./bash-readonly-classifier.js";
 import { compileReadDeny } from "./read-deny.js";
 import { deploymentReadFaceClampNotice, resolveReadFace } from "./read-face.js";
 export * from "./read-face.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.63.0",
+  "version": "5.64.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",

package/test/export-surface.snapshot.json

@@ -1,7 +1,7 @@
 {
   "_comment": "design/87 L3 — frozen public export surface of src/index.ts (name -> kind). DO NOT edit by hand to silence a red test. A removed/changed entry = a SemVer-BREAKING change; bump MAJOR and update this fixture in the SAME commit (design/87 §4.2 / §5.2). Regenerate via REGEN in test/export-surface.test.ts.",
   "_tierComment": "#435 v1 — machine-readable layering of the public surface: stable = demonstrated by README.md / src/examples; internal = an `Internal`-marked name or a runner/engine deep-subtree declaration (the model seam src/engine/llm is excluded — it is the BYOM contract, not an engine internal); advanced = a supported export the front door does not walk you through. THIS IS AN INITIAL HEURISTIC, derived mechanically and expected to be refined ticket by ticket: no human reviewed these 1700+ entries one by one, and nothing here claims otherwise. Known bias: a short or English-word export name (ok, err, Result, Usage) can match ordinary prose in README.md and land `stable` on a coincidence. Every export MUST carry a tier — a new export with no row fails the gate in export-surface.test.ts.",
-  "count": 1764,
+  "count": 1766,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -1192,11 +1192,13 @@
     "WorktreeSessionRef": "interface",
     "WorktreeToolsOptions": "interface",
     "WritablePermissionRuleStore": "interface",
+    "WriteExpectation": "interface",
     "WriteProtectedEntry": "type",
     "WriteProtectedHit": "interface",
     "WriteProtectedKind": "type",
     "WriteProtectedRow": "interface",
     "WriteProtectionMatcher": "interface",
+    "WriteReceipt": "interface",
     "ackAdoptionConfig": "function",
     "acquireCcLock": "function",
     "addDotsOf": "function",
@@ -2958,11 +2960,13 @@
     "WorktreeSessionRef": "advanced",
     "WorktreeToolsOptions": "advanced",
     "WritablePermissionRuleStore": "advanced",
+    "WriteExpectation": "internal",
     "WriteProtectedEntry": "advanced",
     "WriteProtectedHit": "advanced",
     "WriteProtectedKind": "advanced",
     "WriteProtectedRow": "advanced",
     "WriteProtectionMatcher": "advanced",
+    "WriteReceipt": "internal",
     "ackAdoptionConfig": "advanced",
     "acquireCcLock": "advanced",
     "addDotsOf": "advanced",