@inflexa-ai/harness 0.45.0 → 0.46.0

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

@@ -12,11 +12,25 @@
  * capture-group references, and exactly one of `replace_all=true` or
  * `expected_matches` gates the write. Provenance hashes the post-edit
  * content — the mutator records it through the fold of this tool.
+ *
+ * Inside a durable step, the edit records its intent before the write lands:
+ * the hash of the file before, the hash after, and the result. A rerun of the
+ * step after the write, before its checkpoint, finds the file at the hash
+ * after and gives back the stored result, thus the edit never applies twice.
+ * The file at the hash before applies the edit again, and any other hash is a
+ * conflict.
  */
-import { ok } from "neverthrow";
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { createHash, randomUUID } from "node:crypto";
+import { errorMessageOf } from "../../lib/thrown.js";
+import { textOf } from "../../lib/unknown-text.js";
+import { err, ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool, withToolCallRecord } from "../define-tool.js";
+import { computeSha256 } from "../../lib/fs-helpers.js";
 import { unwrapOrThrow } from "../../lib/result.js";
+import { stepExecId } from "../../sandbox/exec.js";
+import { noteScriptChange, scriptSha256 } from "./decision-record.js";
 const EditFileInputSchema = z.object({
     path: z
         .string()
@@ -51,6 +65,24 @@ const EditFileInputSchema = z.object({
         "mismatch the edit writes nothing and returns the actual count with " +
         "the matching line numbers."),
 });
+/** The key of the DBOS step that runs the call, or `undefined` outside a workflow, where nothing reruns. */
+export function durableStepKey() {
+    return DBOS.isInStep() ? stepExecId() : undefined;
+}
+const STEP_UUID_NAMESPACE = "1208d858-ffdc-4f80-acec-32131dad545d";
+/** An id that each run of one durable step gives again: the UUIDv5 of the step key. With no step key, nothing reruns, thus the id is random. */
+export function stepUuid(stepKey) {
+    if (stepKey === undefined)
+        return randomUUID();
+    const hash = createHash("sha1")
+        .update(Buffer.from(STEP_UUID_NAMESPACE.replaceAll("-", ""), "hex"))
+        .update(stepKey, "utf8")
+        .digest();
+    hash.writeUInt8((hash.readUInt8(6) & 0x0f) | 0x50, 6);
+    hash.writeUInt8((hash.readUInt8(8) & 0x3f) | 0x80, 8);
+    const hex = hash.subarray(0, 16).toString("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
 function replaceString(content, oldString, newString, replaceAll) {
     if (!content.includes(oldString))
         return { kind: "not_found" };
@@ -91,10 +123,11 @@ function lineNumbersAt(content, offsets) {
 function replaceRegex(content, pattern, replacement, expected) {
     let compiled;
     try {
+        // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the caller-supplied match pattern is the tool's input; the dynamic form is the feature, and an invalid pattern is the handled error below.
         compiled = new RegExp(pattern, "gm");
     }
     catch (err) {
-        return { kind: "invalid_pattern", error: err instanceof Error ? err.message : String(err) };
+        return { kind: "invalid_pattern", error: errorMessageOf(err) ?? textOf(err) };
     }
     const matches = [...content.matchAll(compiled)];
     if (matches.length === 0)
@@ -106,6 +139,7 @@ function replaceRegex(content, pattern, replacement, expected) {
     return { kind: "ok", content: content.replace(compiled, replacement), replacements: matches.length, lines };
 }
 export function createEditFileTool(deps) {
+    const stepKey = deps.stepKey ?? durableStepKey;
     return defineTool({
         id: "edit_file",
         description: "Edit a file in your working directory by replacing specific text. " +
@@ -120,9 +154,7 @@ export function createEditFileTool(deps) {
         inputSchema: EditFileInputSchema,
         // The path only. The replaced text is file content, not a description.
         describeCall: ({ path }) => path,
-        execute: async ({ path, old_string, new_string, replace_all, regex, expected_matches }, ctx) => {
-            const replaceAll = replace_all === true;
-            const useRegex = regex === true;
+        execute: async ({ path, old_string, new_string, replace_all: replaceAll, regex: useRegex, expected_matches }, ctx) => {
             if (!useRegex && expected_matches !== undefined) {
                 return ok({ status: "invalid_arguments", path, reason: "expected_matches requires regex=true." });
             }
@@ -136,12 +168,25 @@ export function createEditFileTool(deps) {
             const read = unwrapOrThrow(await deps.workspaceFilesystem.readFile({
                 session: ctx.session,
                 path,
-                ...(deps.workingDir !== undefined ? { workingDir: deps.workingDir } : {}),
+                workingDir: deps.workingDir,
             }));
             if (read.kind === "not_found")
                 return ok({ status: "file_not_found", path });
             if (read.kind === "out_of_scope")
                 return ok({ status: "out_of_scope", path });
+            const currentHash = computeSha256(read.content);
+            const key = stepKey();
+            if (key !== undefined) {
+                const intent = unwrapOrThrow(await deps.intents.get(key));
+                if (intent !== null && currentHash === intent.hashAfter)
+                    return ok(withToolCallRecord(intent.result, intent.callRecord));
+                if (intent !== null && currentHash !== intent.hashBefore) {
+                    return err({
+                        error: `The file ${path} changed after an earlier run of this edit, thus the edit was not applied. Read the file again before you edit it.`,
+                        retryable: false,
+                    });
+                }
+            }
             const content = read.content.toString("utf8");
             const replaced = useRegex
                 ? replaceRegex(content, old_string, new_string, expected_matches)
@@ -163,24 +208,62 @@ export function createEditFileTool(deps) {
                     lines: replaced.lines,
                 });
             }
+            const lines = replaced.lines;
+            const resultOf = (landed) => ({
+                status: "ok",
+                path: landed.path,
+                replacements: replaced.replacements,
+                bytesWritten: landed.bytesWritten,
+                lines,
+            });
+            const intentOf = (stepKey, landed, result, callRecord) => ({
+                key: stepKey,
+                analysisId: ctx.session.scope.analysisId,
+                path: landed.path,
+                hashBefore: currentHash,
+                hashAfter: landed.record.hash,
+                result,
+                callRecord,
+            });
             const write = await deps.mutator.writeFile({
                 path,
                 content: replaced.content,
                 toolName: "edit_file",
                 invocationId: ctx.invocationId,
                 session: ctx.session,
+                beforeLand: async (landed) => {
+                    if (key !== undefined)
+                        unwrapOrThrow(await deps.intents.put(intentOf(key, landed, resultOf(landed), [landed.record])));
+                },
             });
             if (write.status !== "ok")
                 return ok(write);
-            const lines = replaced.lines;
-            return ok(withToolCallRecord({
-                status: "ok",
-                path: write.path,
-                replacements: replaced.replacements,
-                bytesWritten: write.bytesWritten,
-                ...(lines === undefined ? {} : { lines }),
-            }, write.record));
+            // A rendered script carries a decision record. The edit is a change the curator did not vet, and the
+            // record keeps it with the digest after the change, thus an empty `unvetted_edits` stays a fact.
+            const noted = await noteScriptChange({
+                filesystem: deps.workspaceFilesystem,
+                mutator: deps.mutator,
+                session: ctx.session,
+                workingDir: deps.workingDir,
+                invocationId: ctx.invocationId,
+                toolName: "edit_file",
+                scriptPath: path,
+                note: `edit_file: ${replaced.replacements} replacement(s)`,
+                sha256: scriptSha256(replaced.content),
+            });
+            const result = resultOf(write);
+            if (noted.status !== "noted")
+                return ok(withToolCallRecord(result, [write.record]));
+            result.decision_record_noted = true;
+            const callRecord = [write.record, noted.write];
+            // The first put holds the edit already, thus a failed update costs a rerun only the note of the decision record.
+            if (key !== undefined)
+                await deps.intents.put(intentOf(key, write, result, callRecord)).unwrapOr(undefined);
+            return ok(withToolCallRecord(result, callRecord));
+        },
+        foldCallRecord: (records) => {
+            for (const record of records)
+                deps.mutator.recordWrite(record);
         },
-        foldCallRecord: (record) => deps.mutator.recordWrite(record),
     });
 }

package/dist/tools/workspace/execute-command.d.ts

@@ -18,24 +18,41 @@
  * `sandbox-provenance-tracking`), and artifact registration reconciles them.
  * The frame of each exec rides the call record, and the fold feeds it to the
  * lineage collector of the step.
+ *
+ * A script the command names that carries a decision record is compared
+ * with the digest the record expects before it runs. A difference is a
+ * change that no file tool recorded, and the record gets it with the digest
+ * of the bytes that run, thus the record connects the cited decision to the
+ * code that ran.
  */
-import { type WithToolCallRecord } from "../define-tool.js";
+import { z } from "zod";
+import { type Tool, type WithToolCallRecord } from "../define-tool.js";
 import type { SandboxClient } from "../../sandbox/client.js";
 import type { ProvenanceFrame, SandboxRef } from "../../sandbox/types.js";
 import type { ProvenanceCollector } from "../../provenance/collector.js";
+import type { WorkspaceMutator, WriteRecord } from "./mutator.js";
 import { type BoundedExecResult } from "./result-bounds.js";
+import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
 import type { Logger } from "../../lib/logger.js";
+declare const ExecuteCommandInputSchema: z.ZodObject<{
+    command: z.ZodArray<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 /** What one exec leaves for the lineage collector of the step. */
-interface ExecCallRecord {
+type ExecCallRecord = {
     readonly command: readonly string[];
     readonly exitCode: number | null;
     readonly durationMs: number | null;
-    readonly provenance?: ProvenanceFrame;
-}
+    provenance?: ProvenanceFrame;
+    /** The decision-record writes of the script check before the exec, for the mutator. */
+    recordWrites?: readonly WriteRecord[];
+};
 type ExecuteCommandResult = {
     readonly status: "ok";
 } & BoundedExecResult;
-export interface ExecuteCommandDeps {
+export type ExecuteCommandDeps = {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     readonly sandboxClient: SandboxClient;
@@ -58,11 +75,13 @@ export interface ExecuteCommandDeps {
     readonly lineageCollector?: ProvenanceCollector;
     /** Analysis resource mount root (`/{resourceId}`) — strips frame paths to relative. */
     readonly mountRoot?: string;
-}
-export declare function createExecuteCommandTool(deps: ExecuteCommandDeps): import("../define-tool.js").Tool<{
-    command: string[];
-    cwd?: string | undefined;
-    env?: Record<string, string> | undefined;
-    timeoutSeconds?: number | undefined;
-}, ExecuteCommandResult | WithToolCallRecord<ExecuteCommandResult, ExecCallRecord>>;
+    /**
+     * The workspace filesystem and the mutator of the step, for the record check of a
+     * script the command runs. Both absent (a read-only agent), no record is
+     * read or written.
+     */
+    readonly workspaceFilesystem?: WorkspaceFilesystem;
+    readonly mutator?: WorkspaceMutator;
+};
+export declare function createExecuteCommandTool(deps: ExecuteCommandDeps): Tool<z.infer<typeof ExecuteCommandInputSchema>, ExecuteCommandResult | WithToolCallRecord<ExecuteCommandResult, ExecCallRecord>>;
 export {};

package/dist/tools/workspace/execute-command.js

@@ -18,12 +18,19 @@
  * `sandbox-provenance-tracking`), and artifact registration reconciles them.
  * The frame of each exec rides the call record, and the fold feeds it to the
  * lineage collector of the step.
+ *
+ * A script the command names that carries a decision record is compared
+ * with the digest the record expects before it runs. A difference is a
+ * change that no file tool recorded, and the record gets it with the digest
+ * of the bytes that run, thus the record connects the cited decision to the
+ * code that ran.
  */
 import { posix as posixPath } from "node:path";
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool, withToolCallRecord } from "../define-tool.js";
 import { feedExecFrame } from "../../provenance/exec-frame.js";
+import { reconcileScriptRecord } from "./decision-record.js";
 import { EXEC_STREAM_BYTE_CAP, boundExecResult } from "./result-bounds.js";
 import { runSandboxExec } from "./run-exec.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
@@ -44,10 +51,10 @@ const ExecuteCommandInputSchema = z.object({
     timeoutSeconds: z.number().int().positive().optional().describe("Per-command timeout in seconds; capped by the step deadline."),
 });
 /** Extensions that mark an argv token as the thing being run, not a flag or a data path. */
-const SCRIPT_EXTENSIONS = /\.(py|R|r|sh|js|ts|ipynb)$/;
+const SCRIPT_EXTENSIONS = [".py", ".R", ".r", ".sh", ".js", ".ts", ".ipynb"];
 /** The first script-like token in an argv, or `undefined` when none looks like one. */
 function scriptToken(command) {
-    return command.find((arg) => SCRIPT_EXTENSIONS.test(arg));
+    return command.find((arg) => SCRIPT_EXTENSIONS.some((extension) => arg.endsWith(extension)));
 }
 export function createExecuteCommandTool(deps) {
     const { sandboxClient, sandbox, deadlineMs, defaultCwd, lineageCollector, mountRoot } = deps;
@@ -86,29 +93,51 @@ export function createExecuteCommandTool(deps) {
         describeCall: ({ command }) => scriptToken(command) ?? command.join(" "),
         execute: async ({ command, cwd, env, timeoutSeconds }, ctx) => {
             const effectiveCwd = cwd === undefined ? defaultCwd : cwd.startsWith("/") ? cwd : posixPath.join(defaultCwd, cwd);
+            // Each script the argv names, as the sandbox resolves it. A relative token resolves against the cwd of the
+            // command, which is a `/{analysisId}/...` path, thus the workspace filesystem resolves it the same way.
+            const recordWrites = [];
+            if (deps.workspaceFilesystem && deps.mutator) {
+                for (const token of command.filter((arg) => SCRIPT_EXTENSIONS.some((extension) => arg.endsWith(extension)))) {
+                    const noted = await reconcileScriptRecord({
+                        filesystem: deps.workspaceFilesystem,
+                        mutator: deps.mutator,
+                        session: ctx.session,
+                        invocationId: ctx.invocationId,
+                        toolName: "execute_command",
+                        scriptPath: token.startsWith("/") ? token : posixPath.join(effectiveCwd, token),
+                    });
+                    if (noted.status === "noted")
+                        recordWrites.push(noted.write);
+                }
+            }
             const result = await runSandboxExec({
                 sandboxClient,
                 sandbox,
                 command,
                 cwd: effectiveCwd,
-                ...(env === undefined ? {} : { env }),
-                ...(timeoutSeconds === undefined ? {} : { timeoutSeconds }),
+                env,
+                timeoutSeconds,
                 deadlineMs: deadlineMs(),
                 emit: ctx.emit,
             });
             const bounded = { status: "ok", ...boundExecResult(result) };
-            if (!lineageCollector || !mountRoot)
+            if ((!lineageCollector || !mountRoot) && recordWrites.length === 0)
                 return ok(bounded);
             const record = {
                 command,
                 exitCode: result.exitCode,
                 durationMs: result.durationMs,
-                ...(result.provenance ? { provenance: result.provenance } : {}),
             };
+            if (result.provenance)
+                record.provenance = result.provenance;
+            if (recordWrites.length > 0)
+                record.recordWrites = recordWrites;
             return ok(withToolCallRecord(bounded, record));
         },
         // Best-effort: a collector failure must never fail the exec.
         foldCallRecord: (record) => {
+            for (const write of record.recordWrites ?? [])
+                deps.mutator?.recordWrite(write);
             if (!lineageCollector || !mountRoot)
                 return;
             try {
@@ -118,8 +147,8 @@ export function createExecuteCommandTool(deps) {
                     command: record.command,
                     exitCode: record.exitCode,
                     durationMs: record.durationMs,
-                    ...(deps.logger ? { logger: deps.logger } : {}),
-                    ...(record.provenance ? { provenance: record.provenance } : {}),
+                    logger: deps.logger,
+                    provenance: record.provenance,
                 });
             }
             catch (err) {

package/dist/tools/workspace/file-stat.d.ts

@@ -5,6 +5,8 @@
  * and the optional working directory relative paths resolve against (see the harness-workspace-tools spec).
  * Expected outcomes are data variants — `not_found` / `out_of_scope`.
  */
+import { z } from "zod";
+import { type Tool } from "../define-tool.js";
 import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
 type FileStatOutput = {
     status: "ok";
@@ -18,7 +20,8 @@ type FileStatOutput = {
     status: "out_of_scope";
     path: string;
 };
-export declare function createFileStatTool(fs: WorkspaceFilesystem, workingDir?: string): import("../define-tool.js").Tool<{
-    path: string;
-}, FileStatOutput>;
+declare const FileStatInputSchema: z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strip>;
+export declare function createFileStatTool(fs: WorkspaceFilesystem, workingDir?: string): Tool<z.infer<typeof FileStatInputSchema>, FileStatOutput>;
 export {};

package/dist/tools/workspace/grep.d.ts

@@ -7,12 +7,19 @@
  * `truncated` with a marker; missing path → `not_found`; escape attempt →
  * `out_of_scope`. Only unexpected I/O failures throw.
  */
+import { z } from "zod";
+import { type Tool } from "../define-tool.js";
 import type { ListEntry, WorkspaceFilesystem } from "../../workspace/filesystem.js";
-interface Match {
+declare const GrepInputSchema: z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodString;
+    ignoreCase: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type Match = {
     readonly file: string;
     readonly line: number;
     readonly preview: string;
-}
+};
 type GrepOutput = {
     status: "invalid_pattern";
     pattern: string;
@@ -42,11 +49,7 @@ type GrepOutput = {
     pattern: string;
     matches: Match[];
 };
-export declare function createGrepTool(fs: WorkspaceFilesystem, workingDir?: string): import("../define-tool.js").Tool<{
-    pattern: string;
-    path: string;
-    ignoreCase?: boolean | undefined;
-}, GrepOutput>;
+export declare function createGrepTool(fs: WorkspaceFilesystem, workingDir?: string): Tool<z.infer<typeof GrepInputSchema>, GrepOutput>;
 /** Exposed for tests — the caps `grep` enforces. */
 export declare const GREP_LIMITS: {
     readonly DEFAULT_MAX_MATCHES: 50;

package/dist/tools/workspace/grep.js

@@ -7,8 +7,12 @@
  * `truncated` with a marker; missing path → `not_found`; escape attempt →
  * `out_of_scope`. Only unexpected I/O failures throw.
  */
+import { errorMessageOf } from "../../lib/thrown.js";
+import { textOf } from "../../lib/unknown-text.js";
 import { posix as posixPath } from "node:path";
 import { ok } from "neverthrow";
+import { presentAt } from "../../lib/present.js";
+import { splitLines } from "../../lib/text.js";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { unwrapOrThrow } from "../../lib/result.js";
@@ -46,13 +50,14 @@ export function createGrepTool(fs, workingDir) {
         execute: async ({ pattern, path, ignoreCase }, ctx) => {
             let regex;
             try {
+                // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the caller-supplied grep pattern is the tool's input; the dynamic form is the feature, and an invalid pattern is the handled error below.
                 regex = new RegExp(pattern, ignoreCase === true ? "i" : "");
             }
             catch (err) {
                 return ok({
                     status: "invalid_pattern",
                     pattern,
-                    error: err instanceof Error ? err.message : String(err),
+                    error: errorMessageOf(err) ?? textOf(err),
                 });
             }
             const statResult = unwrapOrThrow(await fs.stat({ session: ctx.session, path, workingDir }));
@@ -84,13 +89,13 @@ export function createGrepTool(fs, workingDir) {
                 const text = buf.toString("utf8");
                 if (read.kind === "truncated")
                     truncated = true;
-                const lines = text.split(/\r?\n/);
+                const lines = splitLines(text);
                 for (let i = 0; i < lines.length; i++) {
                     if (matches.length >= DEFAULT_MAX_MATCHES) {
                         truncated = true;
                         return;
                     }
-                    const line = lines[i];
+                    const line = presentAt(lines, i, "the scanned line");
                     if (regex.test(line)) {
                         matches.push({
                             file: filePath,
@@ -133,6 +138,7 @@ export function createGrepTool(fs, workingDir) {
             if (matches.length === 0) {
                 return ok({ status: "no_matches", path, pattern });
             }
+            // oxlint-disable-next-line no-unnecessary-condition -- tsgolint cannot see the walk/searchFile closures that set truncated; the check is live (it returns the truncated result).
             if (truncated) {
                 return ok({
                     status: "truncated",

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

@@ -21,5 +21,6 @@ export * from "./mutator.js";
 export * from "./execute-command.js";
 export * from "./write-file.js";
 export * from "./edit-file.js";
+export * from "./decision-record.js";
 export { EXEC_STREAM_BYTE_CAP, boundExecResult } from "./result-bounds.js";
 export type { BoundedExecResult } from "./result-bounds.js";

package/dist/tools/workspace/index.js

@@ -23,4 +23,5 @@ export * from "./mutator.js";
 export * from "./execute-command.js";
 export * from "./write-file.js";
 export * from "./edit-file.js";
+export * from "./decision-record.js";
 export { EXEC_STREAM_BYTE_CAP, boundExecResult } from "./result-bounds.js";

package/dist/tools/workspace/list-files.d.ts

@@ -6,6 +6,8 @@
  * Expected outcomes are data variants — a missing path is `not_found`, a path
  * escaping the analysis tree is `out_of_scope`.
  */
+import { z } from "zod";
+import { type Tool } from "../define-tool.js";
 import type { ListEntry, WorkspaceFilesystem } from "../../workspace/filesystem.js";
 type ListFilesOutput = {
     status: "ok";
@@ -18,7 +20,8 @@ type ListFilesOutput = {
     status: "out_of_scope";
     path: string;
 };
-export declare function createListFilesTool(fs: WorkspaceFilesystem, workingDir?: string): import("../define-tool.js").Tool<{
-    path: string;
-}, ListFilesOutput>;
+declare const ListFilesInputSchema: z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strip>;
+export declare function createListFilesTool(fs: WorkspaceFilesystem, workingDir?: string): Tool<z.infer<typeof ListFilesInputSchema>, ListFilesOutput>;
 export {};

package/dist/tools/workspace/mutator.d.ts

@@ -26,8 +26,13 @@
  * The landing is hardened beyond the lexical resolver: missing parent
  * directories are created only inside the write prefix, the deepest existing
  * ancestor is realpath-checked against the realpath'd prefix (a symlinked
- * ancestor cannot re-aim the write), and the final open uses `O_NOFOLLOW`
- * (a symlinked final component is refused, never followed).
+ * ancestor cannot re-aim the write), and a symlinked final component is
+ * refused, never followed.
+ *
+ * The landing is atomic: the bytes go to a temporary file in the target's
+ * directory, and a rename puts that file over the target. A reader of the
+ * target sees the old file or the new file whole, never a part of one, and a
+ * process that dies mid-write leaves the target as it was.
  */
 import type { AgentSession } from "../../auth/types.js";
 import type { Logger } from "../../lib/logger.js";
@@ -54,24 +59,26 @@ export type WriteFileResult = {
  * exact bytes on disk, computed at the landing. Plain JSON, because the step
  * cache of the tool call holds it.
  */
-export interface WriteRecord {
+export type WriteRecord = {
     readonly analysisId: string;
     /** The thread of a session write; absent under a run. */
-    readonly threadId?: string;
+    threadId?: string;
     /** Analysis-root-relative, forward-slashed. */
     readonly path: string;
     readonly hash: string;
     readonly size: number;
     readonly toolName: MutateToolName;
     readonly invocationId: string;
-}
-/** `writeFile` gives back the result, and on success the record of the write for `recordWrite`. */
-export type WriteOutcome = {
+};
+/** A write that lands: the result, and the record of the write for `recordWrite`. */
+export type LandedWrite = {
     readonly status: "ok";
     readonly path: string;
     readonly bytesWritten: number;
     readonly record: WriteRecord;
-} | Exclude<WriteFileResult, {
+};
+/** `writeFile` gives back the result, and on success the record of the write for `recordWrite`. */
+export type WriteOutcome = LandedWrite | Exclude<WriteFileResult, {
     status: "ok";
 }>;
 /**
@@ -80,8 +87,9 @@ export type WriteOutcome = {
  * (`inflexa:tool` in the signed document) — the seam records the write without
  * inspecting its caller.
  */
-export type MutateToolName = "write_file" | "edit_file";
-export interface WorkspaceMutatorDeps {
+export declare const MUTATE_TOOL_NAMES: readonly ["write_file", "edit_file", "knowledge_template", "execute_command"];
+export type MutateToolName = (typeof MUTATE_TOOL_NAMES)[number];
+export type WorkspaceMutatorDeps = {
     /** Absolute host root of this analysis's workspace tree — used by the resolver. */
     readonly workspaceRoot: string;
     readonly analysisId: string;
@@ -94,8 +102,8 @@ export interface WorkspaceMutatorDeps {
      * write itself proceeds unchanged.
      */
     readonly lineageCollector?: ProvenanceCollector;
-}
-export interface WorkspaceMutator {
+};
+export type WorkspaceMutator = {
     /**
      * Resolve `path` against the working directory (relative) or analysis root
      * (absolute `/{analysisId}/...`), confine the result to the working
@@ -109,6 +117,10 @@ export interface WorkspaceMutator {
      * and its provenance attribution from it.
      *
      * Records nothing: a successful write gives back its record for `recordWrite`.
+     *
+     * `beforeLand` runs when the new bytes wait in the temporary file and the
+     * target is still unchanged. It gets the outcome that the write gives back.
+     * A rejection lands nothing, and the write rejects with it.
      */
     writeFile(args: {
         readonly path: string;
@@ -116,16 +128,17 @@ export interface WorkspaceMutator {
         readonly toolName: MutateToolName;
         readonly invocationId: string;
         readonly session: AgentSession;
+        readonly beforeLand?: (write: LandedWrite) => Promise<void>;
     }): Promise<WriteOutcome>;
     /**
      * Record one landed write in provenance. A tool calls it from its call-record
      * fold, thus the record reaches process-local state on each replay too.
      */
     recordWrite(record: WriteRecord): void;
-}
+};
 export declare function createWorkspaceMutator(deps: WorkspaceMutatorDeps): WorkspaceMutator;
 /** Construction deps of the session-scoped realization — see {@link createSessionWorkspaceMutator}. */
-export interface SessionWorkspaceMutatorDeps {
+export type SessionWorkspaceMutatorDeps = {
     /** Workspace-root resolution seam — the write coordinates resolve per call from the session's analysis scope. */
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     /**
@@ -137,7 +150,7 @@ export interface SessionWorkspaceMutatorDeps {
      */
     readonly provenance?: ProvenanceSeam;
     readonly logger?: Logger;
-}
+};
 /**
  * The session-scoped `WorkspaceMutator` realization — the conversation agent's
  * write path. Where `createWorkspaceMutator` closes over fixed per-step