@cruxy/cli 1.11.1 → 1.11.3

package/dist/session/resume.js

@@ -1,7 +1,9 @@
+import { formatTokens } from "../render/state.js";
 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 +77,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);
@@ -114,8 +128,95 @@ export function loadResume(session, cwd) {
         warnings.push(`this session was redacted ${state.redactions === 1 ? "once" : `${state.redactions} times`} — ` +
             `secrets are masked in the restored history, but the original text is still in ${session.file}`);
     }
+    if (state.externalChanges > 0) {
+        // A refused write is a fact about the user's TREE, not about cruxy: while
+        // they were being asked to approve a change, something else wrote to the
+        // file. It reached the model as an error at the time; on resume it is
+        // said once more, because "was my tree written to by something else"
+        // is a question people ask after the fact.
+        warnings.push(`${state.externalChanges} write${state.externalChanges === 1 ? " was" : "s were"} refused in this session ` +
+            `because the file changed on disk while awaiting approval — nothing was written by cruxy; ` +
+            `the session log names each path`);
+    }
+    if (state.compactions.count > 0) {
+        // What compaction has cost this conversation (P3 context quality), said
+        // once on resume because it is the moment a user decides whether to
+        // continue in a history that has been summarised N times. The freed and
+        // spent figures cover only the compactions that recorded them; the clause
+        // saying so is not optional when they differ.
+        warnings.push(describeCompactions(state.compactions));
+    }
+    if (state.compactions.instructionLosses > 0) {
+        // The heuristic's finding, restated where it can still be acted on: the
+        // sentences are in the session log; the remedy is to say them again.
+        const n = state.compactions.instructionLosses;
+        warnings.push(`${n} compaction${n === 1 ? "" : "s"} in this session may have dropped an instruction you gave — ` +
+            `the session log names the sentences; restate anything that still applies`);
+    }
+    if (state.lastVerification) {
+        // Not a warning in spirit, but this is the one channel a resume has, and
+        // the sentence is the same one `/status` shows: what last ran and how it
+        // exited, dated. A resumed session's "the tests passed" is a claim about
+        // the tree as it was THEN; the age is what keeps it honest.
+        const v = state.lastVerification;
+        const exit = v.exitCode === null ? "no exit code" : `exit ${v.exitCode}`;
+        warnings.push(`last verification ${relativeAge(v.at)}: ${v.tool} \`${v.command}\` → ${exit}`);
+    }
+    if (state.plan) {
+        // The last approved plan and where it got to (plan-durability). Same
+        // channel, same reasoning as the verification line: a fact the user
+        // decides on before continuing. The sentence ends by saying the approval
+        // is not carried over, because the one thing a reader of "approved" might
+        // reasonably expect is that the consent came back with the session.
+        warnings.push(describePlan(state.plan));
+    }
     return { session, state, warnings };
 }
+/**
+ * One sentence for the last approved plan (plan-durability): when it was
+ * approved and how, how many steps finished, which failed, and — the fact a
+ * resume exists to surface — whether a step was still running when the
+ * session ended. Says in so many words that the approval is not carried over:
+ * `[g]`'s grants lived in the allowlist of the process that asked, and this
+ * process has not asked.
+ */
+export function describePlan(p, now = Date.now()) {
+    const n = p.steps.length;
+    const count = (status) => p.steps.filter((s) => s.status === status).length;
+    const done = count("done");
+    const failed = count("failed");
+    const pending = count("pending");
+    const running = p.steps.find((s) => s.status === "running");
+    const how = p.decision === "approve-grant"
+        ? "with safe steps auto-allowed"
+        : "step by step";
+    const parts = [`${done}/${n} step${n === 1 ? "" : "s"} done`];
+    if (failed > 0)
+        parts.push(`${failed} failed`);
+    if (running) {
+        parts.push(`step ${running.id} (${running.title}) was still running when the session ended`);
+    }
+    if (pending > 0)
+        parts.push(`${pending} never started`);
+    return (`last plan approved ${relativeAge(p.approvedAt, now)} ${how}: ${parts.join(", ")} — ` +
+        `that approval is not carried into this session; every action asks again`);
+}
+/**
+ * One sentence for what compaction has cost a session (P3 context quality).
+ * Shared by the resume notice and nothing else; `/context` and the one-shot
+ * summary render the same tally as lines (`render/context-view.ts`).
+ */
+export function describeCompactions(c) {
+    const times = `compacted ${c.count === 1 ? "once" : `${c.count} times`} in this session`;
+    if (c.measured === 0) {
+        return `${times} — cost not recorded (written before it was measured)`;
+    }
+    const scope = c.measured < c.count
+        ? ` (${c.count - c.measured} of them recorded no cost)`
+        : "";
+    return (`${times} — freed ~${formatTokens(c.freedTokens)} tokens; ` +
+        `the summaries cost ~${formatTokens(c.summaryInputTokens)} in / ~${formatTokens(c.summaryOutputTokens)} out${scope}`);
+}
 /**
  * VALIDATE `--resume <id>` — which session does this name? — without loading it.
  *
@@ -189,9 +290,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/session/types.js

@@ -154,6 +154,43 @@ export const CompactionEventSchema = z
     replaced: z.number().int().nonnegative(),
     /** What replaced them (the synthetic pair). */
     summary: z.array(MessageSchema),
+    /**
+     * What the compaction COST (P3 context quality) — the four facts in hand
+     * at the write site and, until P3, thrown away there. All optional: a log
+     * written before P3 carries none, and absence means "not measured", never
+     * zero. Freed tokens is `estimatedBefore - estimatedAfter` and is NOT
+     * stored — one derivation, in the fold, rather than a fifth field that
+     * could disagree with the other two.
+     *
+     * The estimates are `estimateTokens` over the history — the same chars/4
+     * heuristic the trigger uses — WITHOUT the fixed reserve, which is a
+     * setting and would cancel out of the difference anyway.
+     */
+    estimatedBefore: z.number().int().nonnegative().optional(),
+    estimatedAfter: z.number().int().nonnegative().optional(),
+    /**
+     * The summarize call's own usage, as the provider reported it. Absent
+     * when the provider reported nothing — the same honesty rule as the usage
+     * record: unknown is not zero.
+     */
+    summaryInputTokens: z.number().int().nonnegative().optional(),
+    summaryOutputTokens: z.number().int().nonnegative().optional(),
+})
+    .passthrough();
+/**
+ * A compaction after which the user's instructions could not all be found in
+ * the synopsis (P3 context quality). Written by the heuristic in
+ * `agent/instruction-loss.ts`, which can be wrong both ways and says so; the
+ * event is what makes a suspected loss auditable after the fact instead of a
+ * warning that scrolled away. `sentences` are the user's own words, bounded
+ * and truncated — enough to recognise what may need restating.
+ */
+export const InstructionLossEventSchema = z
+    .object({
+    kind: z.literal("instruction-loss"),
+    at: z.string(),
+    runId: z.string().optional(),
+    sentences: z.array(z.string()),
 })
     .passthrough();
 /** `/clear`: history dropped, session kept. Replay resets to an empty array. */
@@ -283,6 +320,111 @@ export const ResumedEventSchema = z
     cliVersion: z.string().optional(),
 })
     .passthrough();
+/**
+ * One run that ACTUALLY EXECUTED (P2 verification): `run_tests`, or a
+ * `run_command` the model chose. An index over what happened, keyed to the
+ * turn it happened in — NOT a copy of the run's output. The `append` event
+ * already holds the tool_result the model saw, as the string built for the
+ * model; this is the structured claim beside it, written from the same
+ * object the tool built rather than re-parsed from that string (the same
+ * reasoning as the `run_tests` renderer side channel, P3).
+ *
+ * `passed` is the exit code and nothing else. `tool` and `source` are plain
+ * strings so a newer build's tool or provenance parses here instead of
+ * poisoning the line. A refused attempt, a denied approval or a spawn failure
+ * ran nothing, so no event is written for it — writing one would be a
+ * fabrication.
+ *
+ * Evidence, not enforcement: nothing reads this to decide whether a turn may
+ * end. See `verification/types.ts` for why that decision stands.
+ */
+export const VerificationEventSchema = z
+    .object({
+    kind: z.literal("verification"),
+    at: z.string(),
+    runId: z.string().optional(),
+    tool: z.string(),
+    command: z.string(),
+    source: z.string().optional(),
+    passed: z.boolean(),
+    exitCode: z.number().int().nullable(),
+    durationMs: z.number().nonnegative(),
+    total: z.number().int().nonnegative().optional(),
+    failureCount: z.number().int().nonnegative().default(0),
+    failureNames: z.array(z.string()).default([]),
+    outputTruncated: z.boolean().default(false),
+    substrate: z.string(),
+})
+    .passthrough();
+/**
+ * A write refused because its target moved during the approval wait (P1).
+ *
+ * The refusal itself is an error string handed to the model; before this
+ * event the user learned of it only by opening a rollback preview later.
+ * Something else wrote to a file in their tree while they were being asked to
+ * approve a change to it, and that is recorded here as a fact about the
+ * session — separate from `verification` so the fold never mistakes one for
+ * the other. No content is recorded: the path and what moved are the whole
+ * fact.
+ */
+export const ExternalChangeEventSchema = z
+    .object({
+    kind: z.literal("external-change"),
+    at: z.string(),
+    runId: z.string().optional(),
+    path: z.string(),
+    what: z.string(),
+})
+    .passthrough();
+/**
+ * The user approved a plan (plan-durability).
+ *
+ * Recorded as a FACT — the decision kind and the steps as approved, dated —
+ * because it is stronger than the mode toggle, which was already journaled,
+ * and it used to evaporate with the process: the plan lived in a local holder
+ * inside one `runPlanSession` call and nowhere else. The plan's text was
+ * already on disk as the model's own `submit_plan` tool_use; this is the
+ * typed record beside it, the one a reader can fold without parsing a tool
+ * call.
+ *
+ * IT IS NEVER RE-ARMED ON RESUME. `decision: "approve-grant"` says the user
+ * chose `[g]`, which wrote grants into the session allowlist — RAM, in the
+ * process that asked. A resumed session reading this event and restoring
+ * those grants would pre-authorize writes the user consented to in a
+ * different process, against a tree that has since changed. The fold hands
+ * back a description; nothing on the consent side reads it.
+ *
+ * `decision` and `kind` are plain strings so a log written by a newer build
+ * parses here rather than poisoning the line.
+ */
+export const PlanApprovedEventSchema = z
+    .object({
+    kind: z.literal("plan-approved"),
+    at: z.string(),
+    runId: z.string().optional(),
+    /** `approve` or `approve-grant`, as the user chose. */
+    decision: z.string(),
+    steps: z.array(z
+        .object({ id: z.string(), title: z.string(), kind: z.string() })
+        .passthrough()),
+})
+    .passthrough();
+/**
+ * One step of the last approved plan changed status (plan-durability):
+ * `running` when its turn began, `done` or `failed` when it ended. A step
+ * whose last event is `running` is the signature of an interrupted plan —
+ * the process died before the step could report either outcome — and that
+ * is exactly the fact the resume notice needs.
+ */
+export const PlanStepEventSchema = z
+    .object({
+    kind: z.literal("plan-step"),
+    at: z.string(),
+    runId: z.string().optional(),
+    stepId: z.string(),
+    status: z.string(),
+})
+    .passthrough();
 /** Every event, discriminated on `kind`. */
 export const SessionEventSchema = z.discriminatedUnion("kind", [
     SessionMetaSchema,
@@ -294,6 +436,11 @@ export const SessionEventSchema = z.discriminatedUnion("kind", [
     UsageEventSchema,
     RedactEventSchema,
     ResumedEventSchema,
+    VerificationEventSchema,
+    ExternalChangeEventSchema,
+    InstructionLossEventSchema,
+    PlanApprovedEventSchema,
+    PlanStepEventSchema,
 ]);
 /**
  * Every `kind` this build understands, derived from the union itself so the two
@@ -304,3 +451,14 @@ export const SessionEventSchema = z.discriminatedUnion("kind", [
  * they used to be counted as one.
  */
 export const KNOWN_EVENT_KINDS = new Set(SessionEventSchema.options.map((option) => option.shape.kind.value));
+/** A tally with nothing in it — a fresh session, or a log with no compaction. */
+export function emptyCompactionTally() {
+    return {
+        count: 0,
+        measured: 0,
+        freedTokens: 0,
+        summaryInputTokens: 0,
+        summaryOutputTokens: 0,
+        instructionLosses: 0,
+    };
+}

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/testing/run-tests-tool.js

@@ -147,7 +147,9 @@ export function makeRunTestsTool(deps = {}) {
             // The structured result goes to the renderer here, from the same object
             // the payload below is built from — never from re-reading that payload.
             try {
-                deps.onResult?.(result, resolved);
+                deps.onResult?.(result, resolved, {
+                    substrate: ctx.sandbox ? "sandbox" : "host",
+                });
             }
             catch {
                 // A renderer problem is not a test-run problem.

package/dist/tools/create-pull-request.js

@@ -25,7 +25,8 @@ const parameters = z.object({
     body: z
         .string()
         .optional()
-        .describe("PR body in markdown (what changed · why · verification). Omit to auto-generate."),
+        .describe("PR body in markdown (what changed · why). Omit to auto-generate. " +
+        "Do not write a Verification section: it is added from the record of what actually ran this session, and one you write is replaced by it."),
     base: z
         .string()
         .optional()
@@ -58,6 +59,12 @@ export const createPullRequestTool = {
                     ...i,
                     scopes: guidance.scopes,
                     skillBody: guidance.skillBody,
+                    // The PR body's Verification section is the record's (P2): the
+                    // runs this session actually executed, with their exit codes —
+                    // or no such section at all. The model's own body keeps its
+                    // prose; a Verification section it wrote is replaced by this.
+                    // Never a manufactured "ran typecheck + lint + test".
+                    verification: { runs: ctx.verification?.sessionRuns() ?? [] },
                 }),
             });
             const outcome = await service.openPullRequest({

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,24 @@ 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.message);
+                // One record per path that moved (P2 verification): the user learns
+                // which files something else wrote to, not just that the patch failed.
+                ctx.verification?.record({ kind: "external-change", ...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 +214,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 +264,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 +297,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 +323,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,16 @@ 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) {
+            // Told to the model as the error, and recorded for the user (P2
+            // verification) — see write-file.ts.
+            ctx.verification?.record({ kind: "external-change", ...moved });
+            return { ok: false, error: moved.message };
+        }
         try {
             await fs.writeFile(abs, updated, "utf8");
             return { ok: true, output: `edited ${input.path}` };

package/dist/tools/file/snapshot.js

@@ -0,0 +1,68 @@
+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 — its `message` is the tool's error (one sentence on what moved,
+ * and the same next step every time: read it again and retry), and its
+ * `path`/`what` are what the tool records so the user learns of it too.
+ *
+ * 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 {
+        path: rel,
+        what,
+        message: `${ErrorCode.FileChangedSinceRead}: ${rel} ${what}, so the approval no longer ` +
+            `covers this write; nothing was written — read the file again and retry`,
+    };
+}