@cruxy/cli 1.11.1 → 1.11.2

package/dist/session/log.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { APP_VERSION } from "../constants.js";
 import { formatBytes } from "../utils/disk.js";
 import { sessionFile } from "./paths.js";
+import { claimSession, describeHolder, releaseSession, sessionHeldBy, } from "./owner.js";
 import { pruneSessions } from "./prune.js";
 import { SESSION_FILE_VERSION, } from "./types.js";
 /**
@@ -20,6 +21,8 @@ export class SessionLog {
     currentRunId;
     /** Set once a write fails: the log goes inert rather than warning per turn. */
     broken = false;
+    /** Whether this process has stamped itself as the file's owner (P1). */
+    claimed = false;
     /**
      * A NEW session's `meta` line, held until the session records something.
      * Null on a reopen (the file already has its meta) and null again the moment
@@ -77,6 +80,14 @@ export class SessionLog {
         const log = new SessionLog(file, opts);
         log.pruneOnce(opts);
         if (hasContent(file)) {
+            // OWNERSHIP (P1). A reopen is the moment a second process would start
+            // interleaving its turns into this file, so the stamp is taken here,
+            // eagerly, like the `resumed` event below. `loadResume` has already
+            // refused a file another live cruxy holds; this is the claim that makes
+            // the NEXT resume see us. A fresh session claims at its first flush
+            // instead — see {@link write} — for the same reason `meta` is buffered:
+            // a conversation with nothing in it should leave nothing on disk.
+            log.claim();
             log.write({
                 kind: "resumed",
                 at: new Date().toISOString(),
@@ -232,9 +243,46 @@ export class SessionLog {
             this.pendingMeta = null;
             if (!this.writeLine(meta))
                 return false;
+            this.claim(); // the file now exists — so can a second `--resume` of it
         }
         return this.writeLine(event);
     }
+    /**
+     * Stamp this process as the file's owner (P1 — see `owner.ts`). Idempotent.
+     * The stamp is released on process exit; a crash leaves it behind, and that
+     * is fine — a stamp is pid + start-time, so the next reader sees a dead
+     * owner and ignores it. Never fatal: an unwritable stamp is the pre-P1
+     * behaviour (no ownership), and a session must still run without one.
+     */
+    claim() {
+        if (this.claimed)
+            return;
+        // Never overwrite a LIVE owner's stamp. `loadResume` refuses that file
+        // before we get here, so this is the guard for any other writer that
+        // opens a log — and for the race two resumes in the same instant would
+        // be. Recording continues (the format tolerates it); ownership does not
+        // move, so the third process to come along still sees the real holder.
+        const holder = sessionHeldBy(this.file);
+        if (holder) {
+            this.logger?.warn(`session is open in another cruxy (${describeHolder(holder)}) — this process is not taking it over`);
+            return;
+        }
+        this.claimed = claimSession(this.file);
+        if (this.claimed)
+            releaseOnExit(this.file);
+    }
+    /**
+     * Give the file up: remove our stamp. The exit hook does this for the
+     * normal case; this is for a caller that ends a session while the process
+     * lives on (tests, and any future in-process session switch).
+     */
+    close() {
+        if (!this.claimed)
+            return;
+        this.claimed = false;
+        releaseSession(this.file);
+        claimedFiles.delete(this.file);
+    }
     /**
      * Append one event as a single line. Returns whether it landed. The first
      * failure warns and latches `broken`, so a persistent problem (a full disk)
@@ -255,6 +303,24 @@ export class SessionLog {
         }
     }
 }
+/**
+ * Every session file this process has stamped, released together on exit.
+ * ONE listener for the process rather than one per log: a test opens dozens
+ * of logs, and `process.on` warns past ten listeners.
+ */
+const claimedFiles = new Set();
+let exitHookInstalled = false;
+function releaseOnExit(file) {
+    claimedFiles.add(file);
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    process.on("exit", () => {
+        for (const f of claimedFiles)
+            releaseSession(f);
+        claimedFiles.clear();
+    });
+}
 /**
  * Whether `file` is an existing log with content — i.e. this is a reopen.
  *

package/dist/session/owner.js

@@ -0,0 +1,123 @@
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { describeOwner, selfStamp, } from "../utils/process-owner.js";
+import { SESSION_FILE_EXT } from "./paths.js";
+/**
+ * Session ownership across processes (P1).
+ *
+ * A session log is one append-only file, and `SessionLog` was built so that
+ * concurrent appenders interleave whole lines rather than tearing them. That
+ * keeps the file PARSEABLE under two writers; it does not keep it MEANINGFUL.
+ * Two processes that `--resume` the same id each replay the same history,
+ * each append their own turns, and the result is one transcript with two
+ * conversations shuffled into it — replayable, and wrong.
+ *
+ * The fix is ownership, and the minimum that prevents the observed failure is
+ * a stamp, not a lock:
+ *
+ * - `<id>.owner.json` beside the log holds the {@link ProcessStamp} of the
+ *   cruxy that has it open. It is written when the session first lands on
+ *   disk (a new session) or on reopen (a resume), and removed on exit.
+ * - `--resume` reads it BEFORE replaying. A stamp whose process is still
+ *   running is a refusal; a stamp whose process is gone — or whose pid has
+ *   been recycled onto something else — is ignored and overwritten.
+ *
+ * WHY A STAMP AND NOT A LOCK. A lock file that must be deleted to be released
+ * outlives every crash, and a lock that outlives a crash is worse than no
+ * lock: the next `--resume` is refused with nothing to refuse it for, and the
+ * user learns to `rm` it — at which point it stops meaning anything. A pid +
+ * start-time stamp is self-invalidating: liveness is decided by asking the OS,
+ * never by whether cleanup ran. See `utils/process-owner.ts` for why the pid
+ * marker refused for JOB logs is category-correct for sessions.
+ *
+ * WHY NOT A PROJECT-LEVEL LOCK. Several cruxy processes in one project is the
+ * multi-agent case, not a misuse of it. What must not happen is two of them
+ * on ONE session; the stamp is scoped to exactly that.
+ */
+const OwnerSchema = z.object({
+    pid: z.number().int().positive(),
+    token: z.string().min(1),
+    startedAt: z.string(),
+    /** When the stamp was written — for messages. */
+    claimedAt: z.string(),
+});
+/** `<id>.owner.json` next to `<id>.jsonl`. */
+export function ownerFile(sessionFile) {
+    const dir = path.dirname(sessionFile);
+    const id = path.basename(sessionFile, SESSION_FILE_EXT);
+    return path.join(dir, `${id}.owner.json`);
+}
+/** The recorded owner, or null when there is none (absent, unreadable, malformed). */
+export function readOwner(sessionFile) {
+    let raw;
+    try {
+        raw = readFileSync(ownerFile(sessionFile), "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = OwnerSchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Who has the session open right now, if anyone other than this process.
+ * A stale stamp is not a holder; neither is our own.
+ */
+export function sessionHeldBy(sessionFile) {
+    const owner = readOwner(sessionFile);
+    if (!owner)
+        return null;
+    return describeOwner(owner) === "live" ? owner : null;
+}
+/**
+ * Record this process as the session's owner. Temp-then-rename so a reader
+ * never sees a half-written stamp; `0600` like everything else in `~/.cruxy`.
+ * Never throws: a stamp that cannot be written degrades to the pre-P1
+ * behaviour (no ownership), and the session must still run.
+ */
+export function claimSession(sessionFile) {
+    const file = ownerFile(sessionFile);
+    const me = selfStamp();
+    const record = { ...me, claimedAt: new Date().toISOString() };
+    try {
+        mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(record), { mode: 0o600 });
+        renameSync(tmp, file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Remove our stamp — only ours; a later owner's is left alone. Never throws. */
+export function releaseSession(sessionFile) {
+    const owner = readOwner(sessionFile);
+    if (!owner || describeOwner(owner) !== "self")
+        return;
+    try {
+        unlinkSync(ownerFile(sessionFile));
+    }
+    catch {
+        // already gone, or unwritable — nothing to do either way
+    }
+}
+/** Drop a session's stamp unconditionally — for deleting the session itself. */
+export function removeOwnerFile(sessionFile) {
+    try {
+        unlinkSync(ownerFile(sessionFile));
+    }
+    catch {
+        // no stamp to remove
+    }
+}
+/** One line for a refusal or a picker row: which process, since when. */
+export function describeHolder(stamp) {
+    return `pid ${stamp.pid}, started ${stamp.startedAt}`;
+}

package/dist/session/prune.js

@@ -4,6 +4,7 @@ import { INTERRUPTED, idKey, jobLogFilesByRecency, readJobLogTerminal, sessionKe
 import { SESSION_RETENTION_FLOOR, } from "../config/index.js";
 import { sessionFilesByRecency } from "./list.js";
 import { SESSION_FILE_EXT } from "./paths.js";
+import { removeOwnerFile, sessionHeldBy } from "./owner.js";
 /** `<sessionId>.jsonl` → `<sessionId>`. */
 function idOf(file) {
     return path.basename(file, SESSION_FILE_EXT);
@@ -59,6 +60,15 @@ export function pruneSessions(cwd, opts) {
             result.kept++;
             continue;
         }
+        // A session ANOTHER live cruxy has open is spared for the same reason our
+        // own is (P1): its writer would recreate the file on its next append with
+        // no `meta` line, and that session would be unloadable from then on. The
+        // stamp is pid + start-time, so a crashed owner's file is prunable again
+        // the moment it is looked at — nothing outlives the crash.
+        if (sessionHeldBy(ref.file)) {
+            result.kept++;
+            continue;
+        }
         const tooOld = ref.mtimeMs < cutoff;
         const beyondCap = index >= retention;
         if (!tooOld && !beyondCap) {
@@ -67,6 +77,7 @@ export function pruneSessions(cwd, opts) {
         }
         try {
             unlinkSync(ref.file);
+            removeOwnerFile(ref.file); // a stale stamp has nothing left to own
             result.removed.push({ ...ref, sessionId });
             result.bytesFreed += ref.size;
         }

package/dist/session/resume.js

@@ -2,6 +2,7 @@ import { selectList } from "../components/index.js";
 import { usageError } from "../errors/index.js";
 import { listSessionRefs, listSessions, matchSessionRefs, summarizeSession, } from "./list.js";
 import { replaySession } from "./replay.js";
+import { describeHolder, ownerFile, sessionHeldBy } from "./owner.js";
 /** How many sessions the bare-`--resume` picker offers. */
 export const PICKER_LIMIT = 10;
 /** Short, stable id form — enough to identify a session, short enough to type. */
@@ -75,6 +76,18 @@ export function priorDirectoriesWarning(state, cwd) {
  * worth failing loudly on, unlike an individual torn line.
  */
 export function loadResume(session, cwd) {
+    // OWNERSHIP (P1). Asked BEFORE the replay, and answered by the OS rather
+    // than by a file's presence: a stamp whose process is gone is not a holder.
+    // Two processes appending to one log produce a transcript that replays
+    // cleanly and means nothing, so this is a refusal, not a warning.
+    const holder = sessionHeldBy(session.file);
+    if (holder) {
+        throw usageError(`session ${shortId(session.sessionId)} is open in another cruxy (${describeHolder(holder)})`, [
+            "continue it there, or quit that cruxy and resume here",
+            "start a new session with `cruxy`",
+            `if that process is not a cruxy, remove ${ownerFile(session.file)}`,
+        ]);
+    }
     let state;
     try {
         state = replaySession(session.file);
@@ -189,9 +202,15 @@ export async function resumePicker(cwd, opts = {}) {
     ];
     const picked = await selectList(rows, {
         title: "resume a session",
-        toLabel: (row) => row.kind === "new"
-            ? "+ new session"
-            : describeSession(row.session, now),
+        toLabel: (row) => {
+            if (row.kind === "new")
+                return "+ new session";
+            const label = describeSession(row.session, now);
+            // A row another live cruxy holds is offered — the user may want to
+            // see it — but says so, so picking it is not a surprise refusal.
+            const holder = sessionHeldBy(row.session.file);
+            return holder ? `${label} · open in another cruxy` : label;
+        },
         // Non-interactive with no id named: starting fresh is the safe default,
         // never an arbitrary session picked on the user's behalf.
         defaultValue: { kind: "new" },

package/dist/subagent/orchestrator.js

@@ -7,7 +7,7 @@ import { UNRESOLVED_TIER, } from "../budget/index.js";
 import { resolveTaskModel } from "../routing/index.js";
 import { Workspace } from "../workspace/index.js";
 import { Budget, resolveBudget } from "../agent/budget.js";
-import { scopeRegistry, SUBAGENT_WRITE_TOOLS } from "./registry-scope.js";
+import { isWriteTool, scopeRegistry } from "./registry-scope.js";
 import { Semaphore } from "./semaphore.js";
 import { makeSpawnSubagentTool } from "./spawn-tool.js";
 /** Longest task excerpt shown in render chrome — display, not record. */
@@ -556,7 +556,7 @@ function taskLabel(task) {
 /** A child that holds any mutating tool — the disjoint-scope check's unit. A
  * spec with no `tools` gets the default READ-ONLY set, so it is never a writer. */
 function isWriter(spec) {
-    return (spec.tools ?? []).some((t) => SUBAGENT_WRITE_TOOLS.has(t));
+    return (spec.tools ?? []).some(isWriteTool);
 }
 /**
  * The tokens a child is KNOWN to have spent, or `undefined` when no request

package/dist/subagent/registry-scope.js

@@ -17,8 +17,20 @@ export const SPAWN_SUBAGENTS_TOOL_NAME = "spawn_subagents";
 /**
  * Mutating tools (C.33): a child holding ANY of these is a "writer" for the
  * disjoint-scope check. Two writers in one parallel batch must target distinct
- * roots, or the batch is refused pre-dispatch. Kept in sync with the gated,
- * side-effecting tool set (file writes, shell/test, VCS).
+ * roots, or the batch is refused pre-dispatch.
+ *
+ * This is the set of REGISTERED tool names that gate on `ctx.requestApproval`
+ * and act on a workspace root: file writes, shell/test, the PR tool, and the
+ * background-job dispatcher (a job is a whole agent run that may be granted
+ * any of the others). `registry-scope.test.ts` pins every name here to a tool
+ * that actually exists — until P1 this set named three tools that never did
+ * (`git_commit`, `git_branch`, `open_pr`) and omitted `create_pull_request`,
+ * so a child holding the PR tool was never counted as a writer and two of them
+ * could be dispatched against one root.
+ *
+ * Deliberately NOT here: `remember` (writes the memory store, not a root —
+ * root-disjointness says nothing about it) and the spawn tools (stripped from
+ * every child scope). MCP tools are covered by prefix in {@link isWriteTool}.
  */
 export const SUBAGENT_WRITE_TOOLS = new Set([
     "write_file",
@@ -26,10 +38,21 @@ export const SUBAGENT_WRITE_TOOLS = new Set([
     "apply_patch",
     "run_command",
     "run_tests",
-    "git_commit",
-    "git_branch",
-    "open_pr",
+    "create_pull_request",
+    "run_in_background",
 ]);
+/** The wire-name prefix every MCP-proxied tool carries (see `mcp/adapter.ts`). */
+const MCP_TOOL_PREFIX = "mcp__";
+/**
+ * Whether granting `name` to a child makes it a writer. The named set above,
+ * plus every MCP tool: the adapter gates each call on approval precisely
+ * because a server's tool can mutate anything, and the classifier never lets
+ * the server declare itself read-only — so the disjointness check must not
+ * either.
+ */
+export function isWriteTool(name) {
+    return SUBAGENT_WRITE_TOOLS.has(name) || name.startsWith(MCP_TOOL_PREFIX);
+}
 /**
  * The default child toolset: read-only investigation plus skills. Mirrors the
  * C.31 propose-phase set — no writes, no shell, no VCS unless the parent

package/dist/tools/file/apply-patch.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { z } from "zod";
 import { resolveToolPath, toPosix } from "./paths.js";
 import { applyEol, detectEol, findMatch, tierLabel } from "./match.js";
+import { changedSince, snapshotFile, snapshotOf, } from "./snapshot.js";
 /** How many leading lines of a created file the approval preview shows. */
 const PREVIEW_LINES = 20;
 /**
@@ -162,6 +163,20 @@ export const applyPatchTool = {
         if (!decision.allow) {
             return { ok: false, error: decision.feedback ?? "patch denied" };
         }
+        // The approval covered THESE files in THE states they were read in. Any
+        // path that moved during the wait — rewritten, deleted, or created by
+        // something else — voids the whole patch: nothing is applied, so the model
+        // re-reads and resubmits rather than landing a half-stale patch (P1).
+        // Every drifted path is named, not just the first: a retry that knows one
+        // of two moved re-reads one file and trips over the other.
+        const drifted = [];
+        for (const p of planned) {
+            const moved = await changedSince(p.abs, p.approved, p.rel);
+            if (moved)
+                drifted.push(moved);
+        }
+        if (drifted.length > 0)
+            return { ok: false, error: drifted.join("\n") };
         // Validation passed and the user approved; apply everything. A mid-apply I/O
         // failure is rare but reported with what already landed.
         const applied = [];
@@ -195,28 +210,44 @@ async function openTrack(i, op, abs, ctx) {
     // messages), consistent with every other path tool — see {@link toPosix}.
     const rel = toPosix(path.relative(ctx.cwd, abs));
     const base = { abs, rel, firstOp: i, hunks: [] };
-    if (op.type === "create") {
-        if (await exists(abs)) {
-            return { ok: false, error: opError(i, op, "file already exists") };
+    if (op.type === "create" || op.type === "delete") {
+        let approved;
+        try {
+            approved = await snapshotFile(abs);
         }
-        const content = op.content ?? "";
-        return {
-            ok: true,
-            track: { ...base, kind: "create", content, eol: detectEol(content) },
-        };
-    }
-    if (op.type === "delete") {
-        if (!(await exists(abs))) {
+        catch (err) {
+            return { ok: false, error: opError(i, op, err.message) };
+        }
+        if (op.type === "create") {
+            if (approved.kind === "present") {
+                return { ok: false, error: opError(i, op, "file already exists") };
+            }
+            const content = op.content ?? "";
+            return {
+                ok: true,
+                track: {
+                    ...base,
+                    kind: "create",
+                    content,
+                    eol: detectEol(content),
+                    approved,
+                },
+            };
+        }
+        if (approved.kind === "absent") {
             return { ok: false, error: opError(i, op, "file not found") };
         }
         return {
             ok: true,
-            track: { ...base, kind: "delete", content: "", eol: "\n" },
+            track: { ...base, kind: "delete", content: "", eol: "\n", approved },
         };
     }
     let content;
+    let approved;
     try {
-        content = await fs.readFile(abs, "utf8");
+        const bytes = await fs.readFile(abs);
+        approved = snapshotOf(bytes);
+        content = bytes.toString("utf8");
     }
     catch (err) {
         if (err.code === "ENOENT") {
@@ -229,6 +260,7 @@ async function openTrack(i, op, abs, ctx) {
         kind: "update",
         content,
         eol: detectEol(content),
+        approved,
     };
     const failure = applyHunk(i, op, track);
     return failure ? { ok: false, error: failure } : { ok: true, track };
@@ -261,12 +293,12 @@ function applyHunk(i, op, track) {
 }
 /** Collapse a finished track into the single write it represents. */
 function toPlanned(track) {
-    const { kind, abs, rel, content, hunks } = track;
+    const { kind, abs, rel, content, hunks, approved } = track;
     if (kind === "delete")
-        return { op: "delete", abs, rel };
+        return { op: "delete", abs, rel, approved };
     if (kind === "create")
-        return { op: "create", abs, rel, content };
-    return { op: "update", abs, rel, content, hunks };
+        return { op: "create", abs, rel, content, approved };
+    return { op: "update", abs, rel, content, hunks, approved };
 }
 /** Shape a planned op into its approval-preview form. */
 function toPreview(p) {
@@ -287,9 +319,3 @@ function toPreview(p) {
 function opError(i, op, reason) {
     return `operation ${i + 1} (${op.type} ${op.path}): ${reason}`;
 }
-async function exists(abs) {
-    return fs
-        .access(abs)
-        .then(() => true)
-        .catch(() => false);
-}

package/dist/tools/file/edit-file.js

@@ -2,10 +2,15 @@ import { promises as fs } from "node:fs";
 import { z } from "zod";
 import { resolveToolPath } from "./paths.js";
 import { applyEol, detectEol, findMatch, tierLabel } from "./match.js";
+import { changedSince, snapshotOf } from "./snapshot.js";
 /**
  * Replace one exact, unique occurrence of `old_str` with `new_str` in a file.
  * The uniqueness requirement is checked before approval so the model can fix an
  * ambiguous match without burning a prompt; gated on `ctx.approve` before writing.
+ *
+ * The bytes read before approval are the state the approval is granted
+ * against; the write is refused if the file is no longer in that state when
+ * the write is about to happen (P1 — see `snapshot.ts`).
  */
 export const editFileTool = {
     name: "edit_file",
@@ -29,8 +34,11 @@ export const editFileTool = {
             return { ok: false, error: err.message };
         }
         let content;
+        let approvedState;
         try {
-            content = await fs.readFile(abs, "utf8");
+            const bytes = await fs.readFile(abs);
+            approvedState = snapshotOf(bytes);
+            content = bytes.toString("utf8");
         }
         catch (err) {
             if (err.code === "ENOENT") {
@@ -64,6 +72,12 @@ export const editFileTool = {
         const updated = content.slice(0, match.start) +
             applyEol(input.new_str, detectEol(content)) +
             content.slice(match.end);
+        // The approval covered a diff against the bytes read above. Anything that
+        // changed the file during the wait makes `updated` a splice of stale
+        // content — refuse rather than overwrite what is there now (P1).
+        const moved = await changedSince(abs, approvedState, input.path);
+        if (moved)
+            return { ok: false, error: moved };
         try {
             await fs.writeFile(abs, updated, "utf8");
             return { ok: true, output: `edited ${input.path}` };

package/dist/tools/file/snapshot.js

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { ErrorCode } from "../../errors/index.js";
+/** Snapshot the bytes a tool has ALREADY read (no second read). */
+export function snapshotOf(bytes) {
+    return {
+        kind: "present",
+        digest: createHash("sha256").update(bytes).digest("hex"),
+    };
+}
+/**
+ * Read `abs` and snapshot it. A missing path is a legitimate state (`absent`)
+ * — it is what `write_file` and a patch `create` are approved against. Every
+ * other failure (a directory at the path, EACCES) propagates: the caller
+ * cannot build a truthful preview of a file it cannot read.
+ */
+export async function snapshotFile(abs) {
+    try {
+        return snapshotOf(await fs.readFile(abs));
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return { kind: "absent" };
+        }
+        throw err;
+    }
+}
+/**
+ * Re-read `abs` and compare it with the state the approval was granted
+ * against. Returns `null` when the file is exactly as it was, otherwise the
+ * refusal to hand back as the tool's error — one sentence on what moved, and
+ * the same next step every time: read it again and retry.
+ *
+ * Call this AFTER approval and IMMEDIATELY before the write, with nothing
+ * awaited in between — the point is to make the gap as small as the platform
+ * allows, not to check early and then wait.
+ */
+export async function changedSince(abs, approved, rel) {
+    let now;
+    try {
+        now = await snapshotFile(abs);
+    }
+    catch (err) {
+        return refusal(rel, `could not be re-read before the approved write (${err.message})`);
+    }
+    if (approved.kind === "absent") {
+        return now.kind === "absent"
+            ? null
+            : refusal(rel, "was created by something else after it was approved as a new file");
+    }
+    if (now.kind === "absent") {
+        return refusal(rel, "was deleted after it was read");
+    }
+    if (now.digest !== approved.digest) {
+        return refusal(rel, "changed on disk after it was read");
+    }
+    return null;
+}
+/** The one refusal shape: what moved, that nothing was written, what to do. */
+function refusal(rel, what) {
+    return (`${ErrorCode.FileChangedSinceRead}: ${rel} ${what}, so the approval no longer ` +
+        `covers this write; nothing was written — read the file again and retry`);
+}

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

@@ -2,11 +2,18 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import { resolveToolPath } from "./paths.js";
+import { changedSince, snapshotFile } from "./snapshot.js";
 /** How many leading lines of new content the approval preview shows. */
 const PREVIEW_LINES = 20;
 /**
  * Create or overwrite a file within the project root. Gated on `ctx.approve`
  * before anything is written.
+ *
+ * The target is snapshotted before approval — its current bytes, or its
+ * absence — and the write is refused if that state has moved by the time the
+ * write is about to happen (P1 — see `snapshot.ts`). This tool used to have
+ * no read at all: an "overwrite" approved against one version of a file would
+ * land on whatever version was there by the time the user pressed `y`.
  */
 export const writeFileTool = {
     name: "write_file",
@@ -25,11 +32,19 @@ export const writeFileTool = {
         catch (err) {
             return { ok: false, error: err.message };
         }
-        // Does the target already exist? Drives create-vs-overwrite in the preview.
-        const exists = await fs
-            .access(abs)
-            .then(() => true)
-            .catch(() => false);
+        // Does the target already exist? Drives create-vs-overwrite in the preview,
+        // and its bytes (or absence) are the state the approval is granted against.
+        let approvedState;
+        try {
+            approvedState = await snapshotFile(abs);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: `cannot read ${input.path}: ${err.message}`,
+            };
+        }
+        const exists = approvedState.kind === "present";
         // First N lines of the new content, with a count of what's omitted.
         const allLines = input.content.split("\n");
         const lines = allLines.slice(0, PREVIEW_LINES);
@@ -46,6 +61,12 @@ export const writeFileTool = {
                 error: decision.feedback ?? `write to ${input.path} denied`,
             };
         }
+        // A create approved against "no file here" must not overwrite a file that
+        // appeared during the wait; an overwrite approved against one version must
+        // not land on another (P1).
+        const moved = await changedSince(abs, approvedState, input.path);
+        if (moved)
+            return { ok: false, error: moved };
         try {
             await fs.mkdir(path.dirname(abs), { recursive: true });
             await fs.writeFile(abs, input.content, "utf8");