@giovannijecha/jecode 0.7.1 → 0.7.3

package/dist/providers/http.js

@@ -2,6 +2,7 @@
 // event stream. Only idempotent reads retry. Once a POST starts or response
 // bytes flow, a failure is surfaced rather than silently replayed.
 import { readSseJson } from "./sse.js";
+import { sseStreamCharacterLimit } from "./stream-limits.js";
 const RETRYABLE = new Set([408, 409, 429, 500, 502, 503, 504]);
 const MAX_JSON_CHARS = 5_000_000;
 const MAX_ERROR_CHARS = 2_000;
@@ -33,11 +34,12 @@ async function asJson(url, res) {
         throw httpError(`${url} returned non-JSON`, res.status, text.slice(0, 500));
     }
 }
-export async function postSse(url, headers, body, signal, onStatus) {
+export async function postSse(url, headers, body, maxOutputTokens, signal, onStatus) {
+    const maximumChars = sseStreamCharacterLimit(maxOutputTokens);
     const res = await request(url, { accept: "text/event-stream", ...headers }, body, signal, onStatus);
     if (res.body === null)
         throw httpError(`${url} returned no body`, res.status);
-    return readSseJson(withIdleTimeout(url, res.body));
+    return readSseJson(withIdleTimeout(url, res.body), maximumChars);
 }
 async function request(url, headers, body, signal, onStatus) {
     const maxRetries = body === undefined ? GET_RETRIES : 0;

package/dist/providers/ollama.js

@@ -88,7 +88,7 @@ export const ollama = {
             max_tokens: req.maxTokens,
             reasoning_effort: effort,
             stream: true,
-        }, req.signal, req.onStatus);
+        }, req.maxTokens, req.signal, req.onStatus);
         const reply = await assembleOllama(events, req.onStream);
         const notice = stopNotice(reply);
         if (notice !== undefined)

package/dist/providers/openai-codex.js

@@ -71,7 +71,7 @@ export const openaiCodex = {
                 text: { verbosity: "low" },
                 include: ["reasoning.encrypted_content"],
                 prompt_cache_key: SESSION_ID,
-            }, req.signal, req.onStatus);
+            }, req.maxTokens, req.signal, req.onStatus);
             const data = await assembleOpenAI(events, req.onStream);
             const notice = stopNotice(data);
             if (notice !== undefined)

package/dist/providers/openai.js

@@ -86,7 +86,7 @@ export const openai = {
             store: false,
             include: ["reasoning.encrypted_content"],
             stream: true,
-        }, req.signal, req.onStatus);
+        }, req.maxTokens, req.signal, req.onStatus);
         const data = await assembleOpenAI(events, req.onStream);
         const notice = stopNotice(data);
         if (notice !== undefined)

package/dist/providers/sse.js

@@ -3,15 +3,15 @@
 // The format is small: `field: value` lines, a blank line ends an event. Only
 // `data` matters here — both providers put the event discriminator inside the
 // JSON payload, so the `event:` line is redundant and skipped.
-import { addBounded, MAX_SSE_EVENT_CHARS, MAX_SSE_STREAM_CHARS, } from "./stream-limits.js";
-export async function* readSseJson(body) {
+import { addBounded, MAX_SSE_EVENT_CHARS, } from "./stream-limits.js";
+export async function* readSseJson(body, maximumChars) {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
     let finished = false;
     let total = 0;
     const append = (text) => {
-        total = addBounded(total, text.length, MAX_SSE_STREAM_CHARS, "SSE stream");
+        total = addBounded(total, text.length, maximumChars, "SSE stream");
         buffer += text;
     };
     try {

package/dist/providers/stream-limits.js

@@ -1,8 +1,20 @@
 // Response streams are remote input. Bound the pieces that otherwise grow
-// independently of the request's output-token setting.
+// independently, while letting a larger requested output carry its necessarily
+// larger framing, terminal envelope, and opaque reasoning payloads.
 export const MAX_SSE_EVENT_CHARS = 1_000_000;
-export const MAX_SSE_STREAM_CHARS = 4_000_000;
+export const MAX_SSE_STREAM_CHARS = 256_000_000;
 export const MAX_TOOL_ARGUMENT_CHARS = 1_000_000;
+const MIN_SSE_STREAM_CHARS = 4_000_000;
+const SSE_CHARS_PER_OUTPUT_TOKEN = 512;
+export function sseStreamCharacterLimit(maxOutputTokens) {
+    if (!Number.isSafeInteger(maxOutputTokens) || maxOutputTokens <= 0) {
+        throw new Error("max output tokens must be a positive safe integer");
+    }
+    const scaled = maxOutputTokens > Math.floor(MAX_SSE_STREAM_CHARS / SSE_CHARS_PER_OUTPUT_TOKEN)
+        ? MAX_SSE_STREAM_CHARS
+        : maxOutputTokens * SSE_CHARS_PER_OUTPUT_TOKEN;
+    return Math.max(MIN_SSE_STREAM_CHARS, scaled);
+}
 export function addBounded(total, added, maximum, label) {
     if (added > maximum - total) {
         throw new Error(`${label} exceeded ${maximum} characters`);

package/dist/sessions/codec.js

@@ -1,17 +1,21 @@
 // Strict codecs for session files. Disk is an untrusted boundary even when
 // the directory is owner-only: every value is bounded and re-owned before it
 // can become conversation or provider input.
+import { Buffer } from "node:buffer";
 import { CONTEXT_LIMITS } from "../context/projection.js";
-export const SESSION_SCHEMA = 2;
+export const SESSION_SCHEMA = 3;
 export const SESSION_FILE_LIMITS = Object.freeze({
     text: 1_048_576,
+    metadataBytes: 64 * 1_024,
+    nodeBytes: 20 * 1_024 * 1_024,
     jsonDepth: 24,
     jsonNodes: 32_768,
     blocks: 8_192,
     details: 8_192,
 });
 export function encodeMeta(meta) {
-    return line(meta);
+    decodeMeta(meta);
+    return boundedLine(meta, SESSION_FILE_LIMITS.metadataBytes);
 }
 export function decodeMeta(value) {
     if (!record(value) || !keys(value, "createdAt,id,version,workspaceDigest,workspaceRoot")) {
@@ -32,7 +36,8 @@ export function decodeMeta(value) {
     });
 }
 export function encodeHead(head) {
-    return line(head);
+    decodeHead(head);
+    return boundedLine(head, SESSION_FILE_LIMITS.metadataBytes);
 }
 export function decodeHead(value) {
     if (!record(value) || !keys(value, "nodeId,parentId,revision,sequence,updatedAt,version")) {
@@ -55,7 +60,16 @@ export function decodeHead(value) {
     });
 }
 export function encodeNode(node, sequence, updatedAt) {
-    return line({
+    const envelope = nodeEnvelope(node, sequence, updatedAt);
+    decodeNode(envelope);
+    return boundedLine(envelope, SESSION_FILE_LIMITS.nodeBytes);
+}
+/** Enforce the exact current-disk boundary before a turn enters the tree. */
+export function assertPersistableNode(node) {
+    encodeNode(node, 1, node.createdAt);
+}
+function nodeEnvelope(node, sequence, updatedAt) {
+    return {
         version: SESSION_SCHEMA,
         sequence,
         updatedAt,
@@ -69,8 +83,9 @@ export function encodeNode(node, sequence, updatedAt) {
             messages: node.messages.map(messageRecord),
             blocks: node.blocks.flatMap(blockRecord),
             context: node.context ?? null,
+            failure: node.failure ?? null,
         },
-    });
+    };
 }
 export function decodeNode(value) {
     if (!record(value) || !keys(value, "node,sequence,updatedAt,version"))
@@ -82,7 +97,9 @@ export function decodeNode(value) {
     const raw = value["node"];
     const nodeKeys = version === 1
         ? "blocks,createdAt,id,identity,messages,parentId,revision,settlement"
-        : "blocks,context,createdAt,id,identity,messages,parentId,revision,settlement";
+        : version === 2
+            ? "blocks,context,createdAt,id,identity,messages,parentId,revision,settlement"
+            : "blocks,context,createdAt,failure,id,identity,messages,parentId,revision,settlement";
     if (!record(raw) || !keys(raw, nodeKeys)) {
         throw invalid();
     }
@@ -93,7 +110,7 @@ export function decodeNode(value) {
         !integer(raw["parentId"], 0) ||
         !integer(raw["revision"], 1) ||
         !timestamp(raw["createdAt"]) ||
-        (raw["settlement"] !== "checkpointed" && raw["settlement"] !== "completed") ||
+        !settlement(raw["settlement"], version) ||
         !record(identity) || !keys(identity, "effort,model,providerId") ||
         !bounded(identity["providerId"], 128) || !bounded(identity["model"], 512) ||
         !bounded(identity["effort"], 32) ||
@@ -103,6 +120,9 @@ export function decodeNode(value) {
     const context = version === 1
         ? undefined
         : contextFromRecord(raw["context"], raw["id"], messages.length);
+    const failure = version < 3
+        ? undefined
+        : failureFromRecord(raw["failure"], raw["settlement"]);
     const node = Object.freeze({
         id: raw["id"],
         parentId: raw["parentId"],
@@ -117,9 +137,25 @@ export function decodeNode(value) {
         messages: Object.freeze(messages.map(messageFromRecord)),
         blocks: Object.freeze(blocks.map(blockFromRecord)),
         ...(context === undefined ? {} : { context: Object.freeze(context) }),
+        ...(failure === undefined ? {} : { failure: Object.freeze(failure) }),
     });
     return Object.freeze({ sequence: value["sequence"], updatedAt: value["updatedAt"], node });
 }
+function failureFromRecord(value, settlement) {
+    const failed = settlement === "failed" || settlement === "interrupted";
+    if (value === null) {
+        if (failed)
+            throw invalid();
+        return undefined;
+    }
+    if (!failed || !record(value) || !keys(value, "text,tone"))
+        throw invalid();
+    if (!bounded(value["text"]) ||
+        (settlement === "failed" && value["tone"] !== "error") ||
+        (settlement === "interrupted" && value["tone"] !== "warn"))
+        throw invalid();
+    return { text: value["text"], tone: value["tone"] };
+}
 function contextFromRecord(value, ownerId, ownerMessages) {
     if (value === null)
         return undefined;
@@ -340,6 +376,12 @@ function jsonValue(value, budget, depth) {
 function line(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
+function boundedLine(value, maxBytes) {
+    const encoded = line(value);
+    if (Buffer.byteLength(encoded, "utf8") > maxBytes)
+        throw invalid();
+    return encoded;
+}
 function keys(value, expected) {
     return Object.keys(value).sort().join(",") === expected;
 }
@@ -356,7 +398,11 @@ function integer(value, minimum) {
     return typeof value === "number" && Number.isSafeInteger(value) && value >= minimum;
 }
 function schema(value) {
-    return value === 1 || value === SESSION_SCHEMA;
+    return value === 1 || value === 2 || value === SESSION_SCHEMA;
+}
+function settlement(value, version) {
+    return value === "checkpointed" || value === "completed" ||
+        (version >= 3 && (value === "failed" || value === "interrupted"));
 }
 function nullableInteger(value, minimum) {
     return value === null || integer(value, minimum);

package/dist/sessions/runtime.js

@@ -21,9 +21,9 @@ export class SessionPersistence {
         const lease = await store.claim(id);
         try {
             const snapshot = await store.load(id);
-            const conversation = snapshot.conversation.latestCompleted();
+            const conversation = snapshot.conversation.latestResumable();
             if (conversation === undefined)
-                throw new Error("session has no completed turn to resume");
+                throw new Error("session has no resumable turn");
             return Object.freeze({
                 conversation,
                 persistence: new SessionPersistence(store, id, lease),

package/dist/sessions/store.js

@@ -4,17 +4,17 @@
 // after that node is durable, so a crash leaves either the prior checkpoint or
 // one strictly recoverable mutation -- never an ambiguous partial history.
 import { createHash, randomUUID } from "node:crypto";
-import { chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat, } from "node:fs/promises";
+import { chmod, lstat, mkdir, open, opendir, readFile, readdir, realpath, rename, rm, stat, } from "node:fs/promises";
 import * as path from "node:path";
 import { atomicWrite } from "../atomic.js";
 import { CONVERSATION_LIMITS, ConversationTree } from "../conversation.js";
 import { userDataPath } from "../user-data.js";
-import { decodeHead, decodeMeta, decodeNode, encodeHead, encodeMeta, encodeNode, SESSION_SCHEMA, } from "./codec.js";
+import { decodeHead, decodeMeta, decodeNode, encodeHead, encodeMeta, encodeNode, SESSION_FILE_LIMITS, SESSION_SCHEMA, } from "./codec.js";
 import { leaseOwner, leaseToken, pidIsAlive, removeLease, sessionLease, } from "./lease.js";
 const DIRECTORY_MODE = 0o700;
 const FILE_MODE = 0o600;
-const MAX_CATALOG_SCAN = 128;
-const MAX_JSON_BYTES = 20 * 1024 * 1024;
+const MAX_CATALOG_ENTRIES = 4_096;
+const CATALOG_READ_CONCURRENCY = 8;
 const SESSION_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
 const NODE_NAME = /^(\d{6})\.json$/;
 const ATOMIC_NODE_TEMP = /^\.\d{6}\.json\.\d+\.[a-f0-9-]+\.tmp$/;
@@ -37,45 +37,45 @@ export class DurableSessionStore {
         if (!Number.isSafeInteger(limit) || limit < 1 || limit > 64) {
             throw new Error("session catalogue limit is invalid");
         }
-        const entries = await directoryEntries(this.#bucket);
-        const names = entries
-            .filter((entry) => entry.isDirectory() && SESSION_NAME.test(entry.name))
-            .map((entry) => entry.name)
-            .sort((left, right) => right.localeCompare(left))
-            .slice(0, MAX_CATALOG_SCAN);
+        const names = await catalogNames(this.#bucket);
         const catalog = [];
-        for (const id of names) {
-            try {
-                const snapshot = await this.load(id);
-                const conversation = snapshot.conversation.latestCompleted();
-                if (conversation === undefined)
-                    continue;
-                catalog.push({
-                    id,
-                    createdAt: snapshot.meta.createdAt,
-                    updatedAt: snapshot.head.updatedAt,
-                    turns: selectedTurnCount(conversation),
-                    preview: firstUserText(conversation),
-                    active: await this.#leaseIsActive(id),
-                });
-            }
-            catch {
-                // Corrupt or foreign data never becomes a resume candidate.
-            }
+        for (let start = 0; start < names.length; start += CATALOG_READ_CONCURRENCY) {
+            const batch = await Promise.all(names.slice(start, start + CATALOG_READ_CONCURRENCY)
+                .map(async (id) => {
+                try {
+                    const snapshot = await this.load(id);
+                    const conversation = snapshot.conversation.latestResumable();
+                    if (conversation === undefined)
+                        return undefined;
+                    return {
+                        id,
+                        createdAt: snapshot.meta.createdAt,
+                        updatedAt: snapshot.head.updatedAt,
+                        turns: selectedTurnCount(conversation),
+                        preview: firstUserText(conversation),
+                        active: await this.#leaseIsActive(id),
+                    };
+                }
+                catch {
+                    // Corrupt or foreign data never becomes a resume candidate.
+                    return undefined;
+                }
+            }));
+            catalog.push(...batch.filter((entry) => entry !== undefined));
         }
         return catalog
-            .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
+            .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) || right.id.localeCompare(left.id))
             .slice(0, limit);
     }
     async load(id) {
         assertSessionId(id);
         const directory = this.#sessionDirectory(id);
         await assertDirectory(directory);
-        const meta = decodeMeta(await readJson(path.join(directory, "meta.json"), 64 * 1024));
+        const meta = decodeMeta(await readJson(path.join(directory, "meta.json"), SESSION_FILE_LIMITS.metadataBytes));
         if (meta.id !== id || meta.workspaceDigest !== this.workspaceDigest ||
             workspaceKey(meta.workspaceRoot) !== workspaceKey(this.workspaceRoot))
             throw new Error("session belongs to a different workspace");
-        let head = decodeHead(await readJson(path.join(directory, "head.json"), 64 * 1024));
+        let head = decodeHead(await readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes));
         const stored = await readNodes(path.join(directory, "nodes"));
         const ahead = stored.filter((entry) => entry.sequence > head.sequence);
         if (ahead.some((entry) => entry.sequence !== head.sequence + 1) || ahead.length > 1) {
@@ -242,6 +242,28 @@ export class DurableSessionStore {
         return owner !== undefined && pidIsAlive(owner.pid);
     }
 }
+async function catalogNames(directory) {
+    try {
+        await assertDirectory(directory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const names = [];
+    let entries = 0;
+    const handle = await opendir(directory);
+    for await (const entry of handle) {
+        entries++;
+        if (entries > MAX_CATALOG_ENTRIES) {
+            throw new Error(`session catalogue exceeds ${MAX_CATALOG_ENTRIES} entries`);
+        }
+        if (entry.isDirectory() && SESSION_NAME.test(entry.name))
+            names.push(entry.name);
+    }
+    return names.sort((left, right) => right.localeCompare(left));
+}
 function assertSharedNodes(previous, next, replacedId) {
     for (const node of previous.nodes) {
         if (node.id === replacedId)
@@ -278,7 +300,7 @@ async function readNodes(directory) {
         const id = Number(NODE_NAME.exec(name)?.[1]);
         if (id !== index + 1)
             throw new Error("session conversation nodes are not contiguous");
-        const decoded = decodeNode(await readJson(path.join(directory, name), MAX_JSON_BYTES));
+        const decoded = decodeNode(await readJson(path.join(directory, name), SESSION_FILE_LIMITS.nodeBytes));
         if (decoded.node.id !== id || sequences.has(decoded.sequence)) {
             throw new Error("session conversation node identity is invalid");
         }

package/dist/timeline.js

@@ -7,7 +7,7 @@ import { usageFromHistory } from "./usage.js";
 import { heading } from "./tui/picker.js";
 export function timelinePicker(conversation, palette) {
     const entries = timelineEntries(conversation);
-    const selectedId = conversation.latestCompleted()?.activeNodeId ?? 0;
+    const selectedId = conversation.latestResumable()?.activeNodeId ?? 0;
     const index = Math.max(0, entries.findIndex((entry) => entry.node.id === selectedId));
     return Object.freeze({
         picker: {
@@ -18,7 +18,7 @@ export function timelinePicker(conversation, palette) {
             options: entries.map((entry) => ({
                 label: `${entry.prefix}${preview(entry.node)}`,
                 hint: stamp(entry.node.createdAt),
-                ...(entry.node.id === selectedId ? { value: "active" } : {}),
+                ...timelineValue(entry.node, selectedId),
             })),
             index,
         },
@@ -38,12 +38,12 @@ export async function selectTimeline(session, choose) {
     return true;
 }
 function timelineEntries(conversation) {
-    const completed = conversation.nodes.filter((node) => node.settlement === "completed");
-    const completedIds = new Set(completed.map((node) => node.id));
+    const resumable = conversation.nodes.filter((node) => node.settlement !== "checkpointed");
+    const resumableIds = new Set(resumable.map((node) => node.id));
     const children = new Map();
-    for (const node of completed) {
+    for (const node of resumable) {
         let parentId = node.parentId;
-        while (parentId !== 0 && !completedIds.has(parentId)) {
+        while (parentId !== 0 && !resumableIds.has(parentId)) {
             parentId = conversation.node(parentId)?.parentId ?? 0;
         }
         const siblings = children.get(parentId) ?? [];
@@ -70,6 +70,12 @@ function timelineEntries(conversation) {
     visit(0, []);
     return entries;
 }
+function timelineValue(node, selectedId) {
+    const state = node.settlement === "completed" ? undefined : node.settlement;
+    const active = node.id === selectedId ? "active" : undefined;
+    const value = [state, active].filter((part) => part !== undefined).join(" · ");
+    return value === "" ? {} : { value };
+}
 function preview(node) {
     for (const message of node.messages) {
         if (message.role !== "user")

package/dist/tools/fs.js

@@ -4,12 +4,13 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { optionalBool, optionalInt, optionalString, requireString } from "./args.js";
 import { assertDirectWritableInRoot, displayPath, resolveDirectWritableInRoot, resolveExistingInRoot, } from "./paths.js";
-import { assertEditableText, assertReplacementFits, MAX_EDITABLE_CHARS, MAX_EDITABLE_LINES, readEditableText, } from "./text-boundary.js";
+import { assertEditableText, assertReplacementFits, leadingText, MAX_EDITABLE_CHARS, MAX_EDITABLE_LINES, readEditableText, } from "./text-boundary.js";
 import { atomicWrite } from "../atomic.js";
 const MAX_READ_CHARS = 60_000;
 const MAX_LIST_CHARS = 60_000;
 const MAX_LIST_ENTRIES = 2_000;
 const READ_CHUNK_BYTES = 64 * 1024;
+const DEFAULT_MUTATION_DEPENDENCIES = { atomicWrite };
 export const readFile = {
     name: "read_file",
     description: "Read a regular UTF-8 text file inside the workspace. Optionally start at a line " +
@@ -111,24 +112,35 @@ export const writeFile = {
         assertEditableText(content);
         // A write against a file that is already there is a replacement, and the
         // user is owed the difference rather than a wall of green.
-        return { before: await current(target), after: content };
+        const before = await current(target);
+        return { before: before.text, after: content, beforeExists: before.exists };
     },
     async run(args, ctx) {
-        const root = await resolveExistingInRoot(ctx.root, ".");
-        const target = await resolveDirectWritableInRoot(root, requireString(args, "path"));
-        const content = requireString(args, "content", true);
-        assertEditableText(content);
-        await fs.mkdir(path.dirname(target), { recursive: true });
-        const validate = () => assertDirectWritableInRoot(root, target);
-        await validate();
-        await unchangedSinceApproval(target, ctx.preview?.before);
-        await atomicWrite(target, content, { validate });
-        return {
-            output: `wrote ${displayPath(root, target)} (${content.length} characters)`,
-            summary: count(content, "line"),
-        };
+        return runWriteFile(args, ctx);
     },
 };
+export async function runWriteFile(args, ctx, dependencies = DEFAULT_MUTATION_DEPENDENCIES) {
+    const root = await resolveExistingInRoot(ctx.root, ".");
+    const target = await resolveDirectWritableInRoot(root, requireString(args, "path"));
+    const content = requireString(args, "content", true);
+    assertEditableText(content);
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await assertDirectWritableInRoot(root, target);
+    const before = await current(target);
+    assertApproved(before, ctx.preview, "write");
+    await dependencies.atomicWrite(target, content, {
+        async validate(phase) {
+            await assertDirectWritableInRoot(root, target);
+            if (phase === "before-rename") {
+                await assertUnchanged(target, before, "write", ctx.preview !== undefined);
+            }
+        },
+    });
+    return {
+        output: `wrote ${displayPath(root, target)} (${content.length} characters)`,
+        summary: count(content, "line"),
+    };
+}
 export const editFile = {
     name: "edit_file",
     description: "Replace an exact string in a file. The old text must appear exactly once " +
@@ -150,32 +162,43 @@ export const editFile = {
     async preview(args, ctx) {
         const root = await resolveExistingInRoot(ctx.root, ".");
         const target = await resolveDirectWritableInRoot(root, requireString(args, "path"), true);
-        const before = await current(target);
+        const before = await current(target, true);
         // An edit that will not apply gets no preview: the run is about to say so
         // properly, and a diff of a match that does not exist would be a lie.
         try {
-            return { before, after: applied(before, args).after };
+            return {
+                before: before.text,
+                after: applied(before.text, args).after,
+                beforeExists: true,
+            };
         }
         catch {
             return undefined;
         }
     },
     async run(args, ctx) {
-        const root = await resolveExistingInRoot(ctx.root, ".");
-        const target = await resolveDirectWritableInRoot(root, requireString(args, "path"), true);
-        const before = await readEditableText(target);
-        if (ctx.preview !== undefined && before !== ctx.preview.before) {
-            throw new Error("file changed after the preview — inspect it and retry the edit");
-        }
-        const { after, made } = applied(before, args);
-        const validate = () => assertDirectWritableInRoot(root, target, true);
-        await atomicWrite(target, after, { validate });
-        return {
-            output: `edited ${displayPath(root, target)} (${made} replacement${made === 1 ? "" : "s"})`,
-            summary: plural(made, "replacement", "replacements"),
-        };
+        return runEditFile(args, ctx);
     },
 };
+export async function runEditFile(args, ctx, dependencies = DEFAULT_MUTATION_DEPENDENCIES) {
+    const root = await resolveExistingInRoot(ctx.root, ".");
+    const target = await resolveDirectWritableInRoot(root, requireString(args, "path"), true);
+    const before = await current(target, true);
+    assertApproved(before, ctx.preview, "edit");
+    const { after, made } = applied(before.text, args);
+    await dependencies.atomicWrite(target, after, {
+        async validate(phase) {
+            await assertDirectWritableInRoot(root, target, true);
+            if (phase === "before-rename") {
+                await assertUnchanged(target, before, "edit", ctx.preview !== undefined);
+            }
+        },
+    });
+    return {
+        output: `edited ${displayPath(root, target)} (${made} replacement${made === 1 ? "" : "s"})`,
+        summary: plural(made, "replacement", "replacements"),
+    };
+}
 async function readRange(target, offset, limit, signal) {
     throwIfAborted(signal);
     const firstLine = Math.max(1, offset ?? 1);
@@ -203,8 +226,7 @@ async function readRange(target, offset, limit, signal) {
             return;
         const room = MAX_READ_CHARS - text.length;
         if (fragment.length > room) {
-            if (room > 0)
-                text += fragment.slice(0, room);
+            text += leadingText(fragment, room);
             truncated = true;
             stopped = true;
             return;
@@ -284,9 +306,17 @@ function applied(before, args) {
     assertEditableText(after, "edited content");
     return { after, made };
 }
-/** What is on disk now, or nothing at all — a file that is not there yet. */
-async function current(target) {
-    return readEditableText(target, { missingAsEmpty: true });
+/** What is on disk now, preserving the difference between absent and empty. */
+async function current(target, mustExist = false) {
+    try {
+        return { exists: true, text: await readEditableText(target) };
+    }
+    catch (error) {
+        if (!mustExist && error.code === "ENOENT") {
+            return { exists: false, text: "" };
+        }
+        throw error;
+    }
 }
 function countOccurrences(haystack, needle) {
     let occurrences = 0;
@@ -295,12 +325,24 @@ function countOccurrences(haystack, needle) {
     }
     return occurrences;
 }
-async function unchangedSinceApproval(target, approved) {
+function assertApproved(current, preview, operation) {
+    if (preview === undefined)
+        return;
+    const existenceChanged = preview.beforeExists !== undefined && current.exists !== preview.beforeExists;
+    if (existenceChanged || current.text !== preview.before) {
+        throw changedFile(operation, true);
+    }
+}
+async function assertUnchanged(target, expected, operation, previewed) {
     const onDisk = await current(target);
-    if (approved !== undefined && onDisk !== approved) {
-        throw new Error("file changed after the preview — inspect it and retry the write");
+    if (onDisk.exists !== expected.exists || onDisk.text !== expected.text) {
+        throw changedFile(operation, previewed);
     }
 }
+function changedFile(operation, previewed) {
+    const when = previewed ? "after the preview" : "while preparing the change";
+    return new Error(`file changed ${when} — inspect it and retry the ${operation}`);
+}
 function count(text, noun) {
     if (text === "")
         return "empty";