@inflexa-ai/harness 0.33.1 → 0.34.0

package/dist/agents/conversation-agent.d.ts

@@ -18,7 +18,10 @@
  * It starts a report thread as a child of the conversation, and the Report
  * Builder composes the report in that thread.
  * The workspace read surface (`read_file`, `grep`, `workspace_search`) is
- * wired here over the `WorkspaceFilesystem` seam.
+ * wired here over the `WorkspaceFilesystem` seam, and the write pair
+ * (`write_file`, `edit_file`) over the session-scoped `WorkspaceMutator` —
+ * confined to the analysis root, with one provenance session event per
+ * successful write.
  */
 import type { Pool } from "pg";
 import type { ExecuteAnalysisInput, ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
@@ -115,8 +118,9 @@ export interface ConversationAgentDeps extends EnvironmentStorePaths {
     readonly eyes?: AcquireEyes;
     /**
      * The provenance seam. `start_report_session` hands it to its spawn, which
-     * emits the creation of the session at the moment that the child lands. No
-     * other tool of this roster reads it.
+     * emits the creation of the session at the moment that the child lands.
+     * The session-scoped mutator behind `write_file` and `edit_file` emits one
+     * `write-file` session event for each successful write.
      */
     readonly provenance?: ProvenanceSeam;
     /**

package/dist/agents/conversation-agent.js

@@ -18,7 +18,10 @@
  * It starts a report thread as a child of the conversation, and the Report
  * Builder composes the report in that thread.
  * The workspace read surface (`read_file`, `grep`, `workspace_search`) is
- * wired here over the `WorkspaceFilesystem` seam.
+ * wired here over the `WorkspaceFilesystem` seam, and the write pair
+ * (`write_file`, `edit_file`) over the session-scoped `WorkspaceMutator` —
+ * confined to the analysis root, with one provenance session event per
+ * successful write.
  */
 import { createWorkingMemory } from "../memory/working-memory.js";
 import { conversationPrompt } from "../prompts/conversation.js";
@@ -28,7 +31,7 @@ import { searchGeneTool, lookupAnnotationTool, searchInteractionsTool, chemblToo
 import { createNcbiTools, createChemDbTools } from "../tools/bio/keys.js";
 // Dependency-bearing tool factories.
 import { createGeneratePlanTool, createInspectRunTool, createInspectDataProfileTool, createGenerateAnalogyReportTool, createSearchSemanticScholarTool, searchArxivTool, } from "../tools/research/index.js";
-import { createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createShowPlanTool, createWorkspaceSearchTool, showFileTool, } from "../tools/workspace/index.js";
+import { createEditFileTool, createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createSessionWorkspaceMutator, createShowPlanTool, createWorkspaceSearchTool, createWriteFileTool, showFileTool, } from "../tools/workspace/index.js";
 import { showUserTool } from "../tools/display/index.js";
 import { createUpdateWorkingMemoryTool } from "../tools/memory/index.js";
 import { createListAvailablePackagesTool } from "../tools/sandbox/list-available-packages.js";
@@ -46,6 +49,14 @@ export function createConversationAgent(deps) {
     const workingMemory = createWorkingMemory(pool);
     const ncbi = createNcbiTools(bioKeys);
     const chemDb = createChemDbTools(bioKeys, { ...(deps.logger ? { logger: deps.logger } : {}) });
+    // The write path of this agent: coordinates resolve per call from the
+    // session's analysis scope, the write prefix is the analysis root, and
+    // every successful write emits a `write-file` provenance session event.
+    const mutator = createSessionWorkspaceMutator({
+        resolveWorkspaceRoot: deps.resolveWorkspaceRoot,
+        ...(deps.provenance ? { provenance: deps.provenance } : {}),
+        ...(deps.logger ? { logger: deps.logger } : {}),
+    });
     const tools = [
         // Identifier resolution — the ENSG most other bio tools key off.
         searchGeneTool,
@@ -146,6 +157,13 @@ export function createConversationAgent(deps) {
         createListFilesTool(workspaceFs),
         createFileStatTool(workspaceFs),
         createGrepTool(workspaceFs),
+        // Workspace write pair over the session-scoped mutate seam. The working
+        // directory of this agent is the analysis root, so a write lands
+        // anywhere inside its own analysis tree; `..`, a foreign analysis, and
+        // a symlink escape stay refused. No sandbox is involved — the mutator
+        // writes host-side, exactly as it does for a sandbox agent.
+        createWriteFileTool({ mutator }),
+        createEditFileTool({ mutator, workspaceFilesystem: workspaceFs }),
         // Working memory.
         createUpdateWorkingMemoryTool(workingMemory, pool),
         // Host-contributed tools ride the same context and dispatch path as the

package/dist/agents/sandbox/shared.d.ts

@@ -5,8 +5,9 @@
  * `AgentDefinition` for one sandbox agent (see the harness-durable-runtime spec): SOUL kernel + the
  * agent's own prompt body + sandbox standards composed into a single
  * static `systemPrompt` string (no processors at request time, see the harness-providers spec),
- * the workspace mutate trio (`execute_command`, `write_file`, `edit_file`)
- * bound to the shared `SandboxClient` and the step's `allowedWritePrefix`,
+ * the workspace mutate trio — `execute_command` bound to the shared
+ * `SandboxClient`, and `write_file` / `edit_file` confined to the step's
+ * `allowedWritePrefix` through the host-side `WorkspaceMutator` —,
  * the workspace read tools (`read_file`, `grep`) over the shared
  * `WorkspaceFilesystem`, `inspect_data_profile` over the shared `Pool`, and the
  * bio/literature/context7/run-inspection tools its `meta.tools` allowlist names.

package/dist/agents/sandbox/shared.js

@@ -5,8 +5,9 @@
  * `AgentDefinition` for one sandbox agent (see the harness-durable-runtime spec): SOUL kernel + the
  * agent's own prompt body + sandbox standards composed into a single
  * static `systemPrompt` string (no processors at request time, see the harness-providers spec),
- * the workspace mutate trio (`execute_command`, `write_file`, `edit_file`)
- * bound to the shared `SandboxClient` and the step's `allowedWritePrefix`,
+ * the workspace mutate trio — `execute_command` bound to the shared
+ * `SandboxClient`, and `write_file` / `edit_file` confined to the step's
+ * `allowedWritePrefix` through the host-side `WorkspaceMutator` —,
  * the workspace read tools (`read_file`, `grep`) over the shared
  * `WorkspaceFilesystem`, `inspect_data_profile` over the shared `Pool`, and the
  * bio/literature/context7/run-inspection tools its `meta.tools` allowlist names.
@@ -134,16 +135,9 @@ function buildWorkspaceTools(deps, readOnly) {
         ? []
         : (() => {
             const mutator = createWorkspaceMutator({
-                sandboxClient,
-                sandbox: step.sandbox,
                 workspaceRoot: step.workspaceRoot,
                 analysisId: step.analysisId,
-                stepId: step.stepId,
-                workflowId: step.workflowId,
                 workingDir: hostWorkingDir,
-                sandboxWorkingDir,
-                nextFunctionId: step.nextFunctionId,
-                deadlineMs: step.deadlineMs,
                 ...(lineageCollector ? { lineageCollector } : {}),
             });
             return [createWriteFileTool({ mutator }), createEditFileTool({ mutator, workspaceFilesystem: workspaceFs, workingDir: hostWorkingDir })];

package/dist/execution/artifact-record.d.ts

@@ -1,8 +1,8 @@
 /**
  * Artifact record — the shape post-step deps and the provenance collector
- * read for each file the step produced (hash + size + tool provenance +
- * write timestamp). Pure data type; lives in its own file because it is
- * shared across `execution/` and `provenance/`.
+ * read for each file the step produced (hash + size + tool provenance).
+ * Pure data type; lives in its own file because it is shared across
+ * `execution/` and `provenance/`.
  */
 export interface ArtifactRecord {
     path: string;
@@ -14,6 +14,10 @@ export interface ArtifactRecord {
      * their provenance comes from the collector.
      */
     toolName?: string;
-    /** ISO 8601 timestamp captured at write time. */
-    timestamp: string;
+    /**
+     * The loop's tool-call id of the write — replay-stable (the durably
+     * cached model turn minted it), so the provenance bridge can key a
+     * deterministic call-activity identifier on it.
+     */
+    invocationId: string;
 }

package/dist/execution/artifact-record.js

@@ -1,7 +1,7 @@
 /**
  * Artifact record — the shape post-step deps and the provenance collector
- * read for each file the step produced (hash + size + tool provenance +
- * write timestamp). Pure data type; lives in its own file because it is
- * shared across `execution/` and `provenance/`.
+ * read for each file the step produced (hash + size + tool provenance).
+ * Pure data type; lives in its own file because it is shared across
+ * `execution/` and `provenance/`.
  */
 export {};

package/dist/execution/reconcile-manifest.js

@@ -22,7 +22,7 @@
 import { stat } from "node:fs/promises";
 import path from "node:path";
 import { createNoopLogger } from "../lib/console-logger.js";
-import { computeSha256File, hasValidContentHash } from "../lib/fs-helpers.js";
+import { classifyWithinRoot, computeSha256File, hasValidContentHash } from "../lib/fs-helpers.js";
 import { artifactReconcileDropped, lineageInputDropped } from "../lib/metrics.js";
 export async function reconcileManifestWithDisk(input) {
     const { workspaceRoot, resourceId, runId, stepId, agentId, manifest, collector } = input;
@@ -41,6 +41,18 @@ export async function reconcileManifestWithDisk(input) {
             logger.warn("skipping out-of-bounds entry", { path: entry.path });
             continue;
         }
+        // Physical bound: the check above compares path strings, and `entry.path`
+        // can name a symlink the step planted — the `stat`/`computeSha256File`
+        // below both follow it. A real target outside the analysis tree is not
+        // attestable; same verdict as the lexical skip above. An `absent`
+        // verdict (a dangling link, a missing file) falls through to the stat,
+        // which drops it as a phantom. The sandbox is destroyed before
+        // reconcile runs, so the tree is quiescent and a checked link cannot be
+        // swapped under the hash.
+        if ((await classifyWithinRoot(workspaceRoot, absPath)) === "escaped") {
+            logger.warn("skipping symlink-escape entry", { path: entry.path });
+            continue;
+        }
         let info;
         try {
             info = await stat(absPath);
@@ -139,6 +151,18 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
             collector.dropInput(ref);
             continue;
         }
+        // Physical bound: the two checks above compare path strings, and a
+        // symlink at `hostPath` turns an in-tree string into an out-of-tree
+        // target that `stat`/`computeSha256File` would follow. An escaping
+        // target is not an attestable edge — drop it from lineage exactly like
+        // the lexical out-of-tree reads above; it is not drift. An `absent`
+        // verdict (a dangling link) falls through to the ENOENT drop below.
+        if ((await classifyWithinRoot(resourceRoot, hostPath)) === "escaped") {
+            logger.warn("dropping out-of-tree input from lineage", { ...attestation, hostPath, boundSite: "realpath" });
+            lineageInputDropped.add(1, { agent_id: agentId, step_id: stepId, reason: "symlink-escape" });
+            collector.dropInput(ref);
+            continue;
+        }
         let info;
         try {
             info = await stat(hostPath);

package/dist/provenance/collector.js

@@ -209,7 +209,7 @@ export class ProvenanceCollector {
             producer: {
                 type: "file_tool",
                 tool: artifact.toolName ?? "unknown",
-                timestamp: artifact.timestamp,
+                invocationId: artifact.invocationId,
             },
             inputs: [],
             scriptPath: null,

package/dist/provenance/seam.d.ts

@@ -95,8 +95,9 @@ type BlockAct = {
  * One observation of a session.
  *
  * The union names one event for each act: the start of a session, the four block operations, the title,
- * the derivation, the preview, and the record. Each event carries the analysis and the thread, thus a
- * consumer places it with no lookup. The title sits on the document, thus the title event names no block.
+ * the derivation, the preview, the record, and the file write of a conversation turn. Each event carries
+ * the analysis and the thread, thus a consumer places it with no lookup. The title sits on the document,
+ * thus the title event names no block.
  *
  * Each member carries what its own site holds at the moment that the act lands, and nothing more. The
  * derivation carries the chain of the table, because the site pins it and a consumer cannot rebuild it
@@ -150,6 +151,26 @@ export type SessionProvenanceEvent = {
     threadId: string;
     versionId: string;
     replaced: boolean;
+} | {
+    /**
+     * One file that a conversation turn wrote with a file tool — a write under no run and no
+     * step, thus a session observation rather than a collector record. The hash and the size
+     * come from the exact bytes written, computed in-process at the write site.
+     */
+    type: "write-file";
+    analysisId: string;
+    /** The conversation thread whose turn wrote the file. Absent when the scope carries none. */
+    threadId?: string;
+    /** Analysis-root-relative path of the landed file. */
+    path: string;
+    /** SHA-256 of the bytes written. */
+    hash: string;
+    /** Size in bytes. */
+    size: number;
+    /** The agent-visible file tool that authored the content (`write_file` / `edit_file`). */
+    tool: string;
+    /** The loop's tool-call id of the write — the replay-stable identity of the invocation. */
+    invocationId: string;
 };
 /**
  * The provenance seam of the harness. An embedder realizes the members that it records, and the harness

package/dist/provenance/types.d.ts

@@ -7,11 +7,16 @@
  *   - What script generated it (if any)
  */
 import { z } from "zod";
-/** File tool write (write_file, edit_file). */
+/**
+ * File tool write (write_file, edit_file). Carries the loop's tool-call
+ * `invocationId` — replay-stable, and the identity the bridge mixes into the
+ * deterministic call-activity QName — instead of a wall-clock timestamp,
+ * which would be re-minted on every durable replay.
+ */
 export declare const FileToolProducerSchema: z.ZodObject<{
     type: z.ZodLiteral<"file_tool">;
     tool: z.ZodString;
-    timestamp: z.ZodString;
+    invocationId: z.ZodString;
 }, z.core.$strip>;
 /** Sandbox command execution (execute_command). */
 export declare const CommandProducerSchema: z.ZodObject<{
@@ -25,7 +30,7 @@ export declare const CommandProducerSchema: z.ZodObject<{
 export declare const ProducerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"file_tool">;
     tool: z.ZodString;
-    timestamp: z.ZodString;
+    invocationId: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"command">;
     command: z.ZodString;
@@ -66,7 +71,7 @@ export declare const ProvenanceRecordSchema: z.ZodObject<{
     producer: z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"file_tool">;
         tool: z.ZodString;
-        timestamp: z.ZodString;
+        invocationId: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"command">;
         command: z.ZodString;

package/dist/provenance/types.js

@@ -8,11 +8,16 @@
  */
 import { z } from "zod";
 // ── Producer ────────────────────────────────────────────────────────
-/** File tool write (write_file, edit_file). */
+/**
+ * File tool write (write_file, edit_file). Carries the loop's tool-call
+ * `invocationId` — replay-stable, and the identity the bridge mixes into the
+ * deterministic call-activity QName — instead of a wall-clock timestamp,
+ * which would be re-minted on every durable replay.
+ */
 export const FileToolProducerSchema = z.object({
     type: z.literal("file_tool"),
     tool: z.string(),
-    timestamp: z.string(),
+    invocationId: z.string(),
 });
 /** Sandbox command execution (execute_command). */
 export const CommandProducerSchema = z.object({

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

@@ -1,14 +1,17 @@
 /**
- * `edit_file` — sandbox-gated workspace edit, confined to the agent's writable
- * working directory. Composes the read seam (fetch current content) with a
+ * `edit_file` — workspace edit, confined to the agent's writable working
+ * directory. Composes the read seam (fetch current content) with a
  * search/replace and the `WorkspaceMutator` seam (write the result) — same
  * resolution + confinement contract as `write_file`, no path logic of its own
  * (see the harness-workspace-tools spec).
  *
  * Edit semantics: replace `old_string` with `new_string`. `old_string` MUST
  * occur in the file; when `replace_all` is false (default) it MUST occur
- * exactly once. Provenance hashes the post-edit content — recorded by the
- * mutator.
+ * exactly once. With `regex=true`, `old_string` is a JS RegExp pattern
+ * (compiled with the `gm` flags — multiline anchors), `new_string` may use
+ * capture-group references, and exactly one of `replace_all=true` or
+ * `expected_matches` gates the write. Provenance hashes the post-edit
+ * content — recorded by the mutator.
  */
 import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
 import type { WorkspaceMutator, WriteFileResult } from "./mutator.js";
@@ -23,6 +26,21 @@ export type EditFileResult = {
     readonly status: "not_unique";
     readonly path: string;
     readonly occurrences: number;
+} | {
+    readonly status: "invalid_pattern";
+    readonly path: string;
+    readonly pattern: string;
+    readonly error: string;
+} | {
+    readonly status: "invalid_arguments";
+    readonly path: string;
+    readonly reason: string;
+} | {
+    readonly status: "match_count_mismatch";
+    readonly path: string;
+    readonly expected: number;
+    readonly actual: number;
+    readonly lines: readonly number[];
 } | Exclude<WriteFileResult, {
     status: "ok";
 }> | {
@@ -30,17 +48,25 @@ export type EditFileResult = {
     readonly path: string;
     readonly replacements: number;
     readonly bytesWritten: number;
+    /** Regex mode only: 1-based line numbers where the matches started. */
+    readonly lines?: readonly number[];
 };
 export interface EditFileDeps {
     readonly mutator: WorkspaceMutator;
     /** Read seam used to fetch current file content for search/replace. */
     readonly workspaceFilesystem: WorkspaceFilesystem;
-    /** Absolute host working directory — relative read/write paths resolve here. */
-    readonly workingDir: string;
+    /**
+     * Absolute host working directory — relative read paths resolve here. Omit
+     * for the conversation agent: the read seam then defaults to the analysis
+     * root, matching the session-scoped mutator's write prefix.
+     */
+    readonly workingDir?: string;
 }
 export declare function createEditFileTool(deps: EditFileDeps): import("../define-tool.js").Tool<{
     path: string;
     old_string: string;
     new_string: string;
     replace_all: boolean;
+    regex: boolean;
+    expected_matches?: number | undefined;
 }, EditFileResult>;

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

@@ -1,14 +1,17 @@
 /**
- * `edit_file` — sandbox-gated workspace edit, confined to the agent's writable
- * working directory. Composes the read seam (fetch current content) with a
+ * `edit_file` — workspace edit, confined to the agent's writable working
+ * directory. Composes the read seam (fetch current content) with a
  * search/replace and the `WorkspaceMutator` seam (write the result) — same
  * resolution + confinement contract as `write_file`, no path logic of its own
  * (see the harness-workspace-tools spec).
  *
  * Edit semantics: replace `old_string` with `new_string`. `old_string` MUST
  * occur in the file; when `replace_all` is false (default) it MUST occur
- * exactly once. Provenance hashes the post-edit content — recorded by the
- * mutator.
+ * exactly once. With `regex=true`, `old_string` is a JS RegExp pattern
+ * (compiled with the `gm` flags — multiline anchors), `new_string` may use
+ * capture-group references, and exactly one of `replace_all=true` or
+ * `expected_matches` gates the write. Provenance hashes the post-edit
+ * content — recorded by the mutator.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
@@ -22,15 +25,31 @@ const EditFileInputSchema = z.object({
     old_string: z
         .string()
         .min(1)
-        .describe("The exact text to find and replace. Must occur in the file. When " +
-        "replace_all=false (default), must occur exactly once — include " +
+        .describe("The exact text to find and replace — or, when regex=true, a " +
+        "JavaScript regular expression pattern. In exact mode with " +
+        "replace_all=false (default), it must occur exactly once — include " +
         "enough surrounding context to make it unique."),
-    new_string: z.string().describe("The replacement text."),
+    new_string: z.string().describe("The replacement text. When regex=true it may use capture-group references such as $1."),
     replace_all: z
         .boolean()
         .optional()
         .default(false)
         .describe("If true, replace every occurrence. If false (default), old_string " + "must occur exactly once or the edit returns a `not_unique` data variant."),
+    regex: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("If true, old_string is a JavaScript regular expression compiled with " +
+        "the `gm` flags (^ and $ match line boundaries). Requires exactly one " +
+        "of replace_all=true or expected_matches."),
+    expected_matches: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("Regex mode only: the exact number of matches you expect. On a " +
+        "mismatch the edit writes nothing and returns the actual count with " +
+        "the matching line numbers."),
 });
 function replaceString(content, oldString, newString, replaceAll) {
     if (!content.includes(oldString))
@@ -54,48 +73,115 @@ function replaceString(content, oldString, newString, replaceAll) {
         replacements: 1,
     };
 }
+/** 1-based line numbers of the given start offsets (ascending), deduplicated. */
+function lineNumbersAt(content, offsets) {
+    const lines = [];
+    let line = 1;
+    let cursor = 0;
+    for (const offset of offsets) {
+        for (; cursor < offset; cursor++) {
+            if (content.charCodeAt(cursor) === 10)
+                line++;
+        }
+        if (lines[lines.length - 1] !== line)
+            lines.push(line);
+    }
+    return lines;
+}
+function replaceRegex(content, pattern, replacement, expected) {
+    let compiled;
+    try {
+        compiled = new RegExp(pattern, "gm");
+    }
+    catch (err) {
+        return { kind: "invalid_pattern", error: err instanceof Error ? err.message : String(err) };
+    }
+    const matches = [...content.matchAll(compiled)];
+    if (matches.length === 0)
+        return { kind: "not_found" };
+    const lines = lineNumbersAt(content, matches.map((match) => match.index));
+    if (expected !== undefined && matches.length !== expected) {
+        return { kind: "count_mismatch", expected, actual: matches.length, lines };
+    }
+    return { kind: "ok", content: content.replace(compiled, replacement), replacements: matches.length, lines };
+}
 export function createEditFileTool(deps) {
     return defineTool({
         id: "edit_file",
-        // Body-only `awaitExec`-recv → runs unwrapped in the workflow body (see the harness-tools spec).
+        // The mutator wraps the disk mutation in `ctx.runStep` itself, so the
+        // body runs unwrapped in the workflow body (see the harness-tools spec).
         executionMode: "workflow",
         description: "Edit a file in your working directory by replacing specific text. " +
             "Read the file first to get the exact text. When replace_all is false " +
-            "(default), old_string must occur exactly once. Returns `out_of_prefix` " +
-            "/ `out_of_scope` / `file_not_found` / `not_found` / `not_unique` data " +
-            "variants — never throws on expected outcomes.",
+            "(default), old_string must occur exactly once. For a bulk pattern " +
+            "edit set regex=true: old_string is a JS regex, new_string may use $1 " +
+            "references, and exactly one of replace_all=true or expected_matches " +
+            "gates the write. Returns `out_of_prefix` / `out_of_scope` / " +
+            "`file_not_found` / `not_found` / `not_unique` / `match_count_mismatch` " +
+            "data variants — never throws on expected outcomes.",
         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 }, ctx) => {
+        execute: async ({ path, old_string, new_string, replace_all, regex, expected_matches }, ctx) => {
+            const replaceAll = replace_all === true;
+            const useRegex = regex === true;
+            if (!useRegex && expected_matches !== undefined) {
+                return ok({ status: "invalid_arguments", path, reason: "expected_matches requires regex=true." });
+            }
+            if (useRegex && (expected_matches !== undefined) === replaceAll) {
+                return ok({
+                    status: "invalid_arguments",
+                    path,
+                    reason: "regex=true requires exactly one of replace_all=true or expected_matches.",
+                });
+            }
             const read = unwrapOrThrow(await deps.workspaceFilesystem.readFile({
                 session: ctx.session,
                 path,
-                workingDir: deps.workingDir,
+                ...(deps.workingDir !== undefined ? { 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 replaced = replaceString(read.content.toString("utf8"), old_string, new_string, replace_all);
+            const content = read.content.toString("utf8");
+            const replaced = useRegex
+                ? replaceRegex(content, old_string, new_string, expected_matches)
+                : replaceString(content, old_string, new_string, replaceAll);
             if (replaced.kind === "not_found")
                 return ok({ status: "not_found", path });
             if (replaced.kind === "not_unique") {
                 return ok({ status: "not_unique", path, occurrences: replaced.count });
             }
+            if (replaced.kind === "invalid_pattern") {
+                return ok({ status: "invalid_pattern", path, pattern: old_string, error: replaced.error });
+            }
+            if (replaced.kind === "count_mismatch") {
+                return ok({
+                    status: "match_count_mismatch",
+                    path,
+                    expected: replaced.expected,
+                    actual: replaced.actual,
+                    lines: replaced.lines,
+                });
+            }
             const result = await deps.mutator.writeFile({
                 path,
                 content: replaced.content,
                 toolName: "edit_file",
-                emit: ctx.emit,
+                invocationId: ctx.invocationId,
+                runStep: ctx.runStep,
+                session: ctx.session,
             });
             if (result.status !== "ok")
                 return ok(result);
+            const lines = replaced.lines;
             return ok({
                 status: "ok",
                 path: result.path,
                 replacements: replaced.replacements,
                 bytesWritten: result.bytesWritten,
+                ...(lines === undefined ? {} : { lines }),
             });
         },
     });

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

@@ -3,20 +3,33 @@
  * working directory. The write-side counterpart to `WorkspaceFilesystem`
  * (see the harness-workspace-tools spec).
  *
- * It lives here (next to `run-exec`) rather than under `workspace/` because the
- * write path is sandbox-coupled: a write is one `SandboxClient` exec, not a
- * host `fs` call. The seam owns the whole gauntlet that `write_file` and
- * `edit_file` previously each re-implemented inline — resolve + confine to the
- * working directory, derive the in-sandbox path, and write the bytes through
- * the sandbox — so the confinement invariant is concentrated in one place
- * instead of being a per-tool convention.
+ * The seam owns the whole gauntlet that `write_file` and `edit_file` share —
+ * resolve + confine to the working directory, the symlink-hardened landing,
+ * the host `fs` write, and the provenance record — so the confinement
+ * invariant is concentrated in one place instead of being a per-tool
+ * convention.
+ *
+ * Two realizations serve the two agent contexts. `createWorkspaceMutator`
+ * closes over fixed per-step coordinates and records into the step-scoped
+ * lineage collector (the sandbox agents). `createSessionWorkspaceMutator`
+ * resolves its coordinates per call from the session's analysis scope — the
+ * write prefix is the analysis root — and emits a `write-file` session event
+ * through the provenance seam (the conversation agent, which runs under no
+ * run and no step).
+ *
+ * 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).
  */
+import type { AgentSession } from "../../auth/types.js";
+import type { Logger } from "../../lib/logger.js";
+import type { RunStep } from "../../loop/types.js";
 import type { ProvenanceCollector } from "../../provenance/collector.js";
-import type { SandboxClient } from "../../sandbox/client.js";
-import type { SandboxRef } from "../../sandbox/types.js";
-import type { EmitFn } from "../define-tool.js";
-import { type BoundedExecResult } from "./result-bounds.js";
-/** Outcome of a confined write. Expected outcomes are data variants — never throws. */
+import { type ProvenanceSeam } from "../../provenance/seam.js";
+import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
+/** Outcome of a confined write. Expected outcomes are data variants — never throws on them. */
 export type WriteFileResult = {
     readonly status: "ok";
     readonly path: string;
@@ -27,10 +40,10 @@ export type WriteFileResult = {
 } | {
     readonly status: "out_of_prefix";
     readonly path: string;
-} | ({
-    readonly status: "write_failed";
+} | {
+    readonly status: "symlink_denied";
     readonly path: string;
-} & BoundedExecResult);
+};
 /**
  * Agent-visible name of the tool driving a confined write. Rides the write args
  * so a successful write is attributed to the invoking tool in provenance
@@ -39,25 +52,11 @@ export type WriteFileResult = {
  */
 export type MutateToolName = "write_file" | "edit_file";
 export interface WorkspaceMutatorDeps {
-    readonly sandboxClient: SandboxClient;
-    readonly sandbox: SandboxRef;
     /** Absolute host root of this analysis's workspace tree — used by the resolver. */
     readonly workspaceRoot: string;
     readonly analysisId: string;
-    readonly stepId: string;
-    readonly workflowId: string;
     /** Absolute host working directory: relative paths resolve here AND writes are confined here. */
     readonly workingDir: string;
-    /**
-     * In-sandbox absolute path of `workingDir` (mirrors `execute_command`'s
-     * `defaultCwd`). Passed as the write exec's `cwd` so sandbox-server roots
-     * its tree-differ here and reports the written file as a live delta — an
-     * empty `cwd` disables the differ, so write-only files (e.g. scripts/)
-     * would never reach the live file tree.
-     */
-    readonly sandboxWorkingDir: string;
-    readonly nextFunctionId: () => string;
-    readonly deadlineMs: () => number;
     /**
      * Step-scoped lineage collector. On a successful confined write the seam
      * records a file-tool provenance record here — hash and size computed
@@ -70,14 +69,51 @@ export interface WorkspaceMutator {
     /**
      * Resolve `path` against the working directory (relative) or analysis root
      * (absolute `/{analysisId}/...`), confine the result to the working
-     * directory, and write `content` through the sandbox. `toolName` names the
-     * invoking tool so a successful write is attributed to it in provenance.
+     * directory, and land `content` on the host filesystem. `toolName` names
+     * the invoking tool so a successful write is attributed to it in
+     * provenance. `invocationId` is the tool call's loop id — pass the tool
+     * context's `invocationId`: it rides the provenance record so the write's
+     * call activity gets a deterministic identity. `runStep` wraps the disk
+     * mutation in a replay-cached step — pass the tool context's `runStep`.
+     * `session` is the calling agent's session — pass the tool context's
+     * `session`: the step-scoped realization ignores it, the session-scoped
+     * one resolves its coordinates and its provenance attribution from it.
      */
     writeFile(args: {
         readonly path: string;
         readonly content: string;
         readonly toolName: MutateToolName;
-        readonly emit: EmitFn;
+        readonly invocationId: string;
+        readonly runStep: RunStep;
+        readonly session: AgentSession;
     }): Promise<WriteFileResult>;
 }
 export declare function createWorkspaceMutator(deps: WorkspaceMutatorDeps): WorkspaceMutator;
+/** Construction deps of the session-scoped realization — see {@link createSessionWorkspaceMutator}. */
+export interface SessionWorkspaceMutatorDeps {
+    /** Workspace-root resolution seam — the write coordinates resolve per call from the session's analysis scope. */
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    /**
+     * The provenance seam. On a successful confined write the seam's session
+     * emit receives one `write-file` event — hash and size computed in-process
+     * from the exact bytes written, attributed to the session's analysis and
+     * thread. An unbound session emit records nothing; the write itself
+     * proceeds unchanged.
+     */
+    readonly provenance?: ProvenanceSeam;
+    readonly logger?: Logger;
+}
+/**
+ * The session-scoped `WorkspaceMutator` realization — the conversation agent's
+ * write path. Where `createWorkspaceMutator` closes over fixed per-step
+ * coordinates, this one serves every analysis from one construction: each call
+ * resolves the workspace root from the session's analysis scope, and the write
+ * prefix IS that root — the agent modifies its own analysis tree freely, while
+ * `..` traversal, a foreign analysis, and the symlink escapes stay refused by
+ * the same gauntlet.
+ *
+ * A write here runs under no run and no step, so its provenance is a session
+ * observation, not a collector record: each successful write emits one
+ * `write-file` session event (see `provenance/seam.ts`).
+ */
+export declare function createSessionWorkspaceMutator(deps: SessionWorkspaceMutatorDeps): WorkspaceMutator;

package/dist/tools/workspace/mutator.js

@@ -3,79 +3,227 @@
  * working directory. The write-side counterpart to `WorkspaceFilesystem`
  * (see the harness-workspace-tools spec).
  *
- * It lives here (next to `run-exec`) rather than under `workspace/` because the
- * write path is sandbox-coupled: a write is one `SandboxClient` exec, not a
- * host `fs` call. The seam owns the whole gauntlet that `write_file` and
- * `edit_file` previously each re-implemented inline — resolve + confine to the
- * working directory, derive the in-sandbox path, and write the bytes through
- * the sandbox — so the confinement invariant is concentrated in one place
- * instead of being a per-tool convention.
+ * The seam owns the whole gauntlet that `write_file` and `edit_file` share —
+ * resolve + confine to the working directory, the symlink-hardened landing,
+ * the host `fs` write, and the provenance record — so the confinement
+ * invariant is concentrated in one place instead of being a per-tool
+ * convention.
+ *
+ * Two realizations serve the two agent contexts. `createWorkspaceMutator`
+ * closes over fixed per-step coordinates and records into the step-scoped
+ * lineage collector (the sandbox agents). `createSessionWorkspaceMutator`
+ * resolves its coordinates per call from the session's analysis scope — the
+ * write prefix is the analysis root — and emits a `write-file` session event
+ * through the provenance seam (the conversation agent, which runs under no
+ * run and no step).
+ *
+ * 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).
  */
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath } from "node:fs/promises";
+import { basename, dirname, join as joinPath, relative as relativePath, resolve as resolvePath, sep } from "node:path";
+import { createNoopLogger } from "../../lib/console-logger.js";
 import { computeSha256 } from "../../lib/fs-helpers.js";
+import { tryFs, tryFsWrite } from "../../lib/fs-result.js";
+import { unwrapOrThrow } from "../../lib/result.js";
+import { bindSessionEmit } from "../../provenance/seam.js";
 import { resolveForWrite } from "../../workspace/paths.js";
-import { boundExecResult } from "./result-bounds.js";
-import { runSandboxExec } from "./run-exec.js";
-const WRITE_BYTES_PROGRAM = [
-    "import sys,base64,os",
-    "p=sys.argv[1]",
-    "os.makedirs(os.path.dirname(p), exist_ok=True)",
-    "open(p,'wb').write(base64.b64decode(sys.argv[2]))",
-].join("\n");
+/**
+ * Land `bytes` at `absolute`, hardened against a symlink re-aiming the write.
+ * `absolute` is already lexically confined under `prefix` by the resolver;
+ * this function guards the physical path:
+ *
+ *   1. Realpath the prefix (created if absent — it is workflow-owned
+ *      infrastructure, not agent input).
+ *   2. Realpath the deepest existing ancestor of the target and refuse when it
+ *      lands outside the realpath'd prefix — a symlinked ancestor inside the
+ *      prefix cannot point the write elsewhere. A dangling-symlink ancestor
+ *      has no landing at all and is refused too.
+ *   3. Create the missing parents under that canonical ancestor, then realpath
+ *      the created directory and refuse when it lands outside the prefix — a
+ *      symlink raced into a missing segment between the ancestor check and the
+ *      recursive mkdir would re-aim the tail of the path.
+ *   4. Refuse a symlinked final component (lstat), then open with
+ *      `O_NOFOLLOW` so a symlink raced in after the check still cannot be
+ *      followed.
+ *
+ * Refusals are data; a genuine I/O failure throws (the loop's dispatch catch
+ * maps it to an error tool result).
+ */
+async function landBytes(prefix, absolute, bytes) {
+    unwrapOrThrow(await tryFsWrite("mutator.mkdirPrefix", () => mkdir(prefix, { recursive: true }), { path: prefix }));
+    const realPrefix = unwrapOrThrow(await tryFs("mutator.realpathPrefix", () => realpath(prefix), { path: prefix }));
+    // Deepest existing ancestor of the target. The walk stops at the prefix,
+    // which exists — the resolver already confined the lexical path under it.
+    let deepest = dirname(absolute);
+    while (deepest !== prefix) {
+        const stat = unwrapOrThrow(await tryFs("mutator.lstatAncestor", () => lstat(deepest), { path: deepest, onAbsent: () => null }));
+        if (stat !== null)
+            break;
+        deepest = dirname(deepest);
+    }
+    const realDeepest = unwrapOrThrow(await tryFs("mutator.realpathAncestor", () => realpath(deepest), { path: deepest, onAbsent: () => null }));
+    if (realDeepest === null)
+        return "symlink_denied";
+    if (realDeepest !== realPrefix && !realDeepest.startsWith(realPrefix + sep))
+        return "out_of_prefix";
+    const targetDir = joinPath(realDeepest, relativePath(deepest, dirname(absolute)));
+    let landingDir = realDeepest;
+    if (targetDir !== realDeepest) {
+        unwrapOrThrow(await tryFsWrite("mutator.mkdirParents", () => mkdir(targetDir, { recursive: true }), { path: targetDir }));
+        // Recursive mkdir follows a symlink that already occupies a segment, so
+        // a symlink raced into a missing segment after the ancestor check would
+        // re-aim the tail. The canonical path of the created directory exposes
+        // it; a directory that vanished before the check is hostile too. The
+        // open below uses the canonical path, so the write never traverses the
+        // raced segment again.
+        const realTarget = unwrapOrThrow(await tryFs("mutator.realpathTarget", () => realpath(targetDir), { path: targetDir, onAbsent: () => null }));
+        if (realTarget === null)
+            return "symlink_denied";
+        if (realTarget !== realPrefix && !realTarget.startsWith(realPrefix + sep))
+            return "out_of_prefix";
+        landingDir = realTarget;
+    }
+    const finalPath = joinPath(landingDir, basename(absolute));
+    const finalStat = unwrapOrThrow(await tryFs("mutator.lstatFinal", () => lstat(finalPath), { path: finalPath, onAbsent: () => null }));
+    if (finalStat !== null && finalStat.isSymbolicLink())
+        return "symlink_denied";
+    // `O_NOFOLLOW` backstops the lstat refusal: a symlink raced in between the
+    // two calls fails the open (`ELOOP`) instead of being followed.
+    const handle = unwrapOrThrow(await tryFsWrite("mutator.open", () => open(finalPath, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW), {
+        path: finalPath,
+    }));
+    try {
+        unwrapOrThrow(await tryFsWrite("mutator.writeBytes", () => handle.writeFile(bytes), { path: finalPath }));
+    }
+    finally {
+        unwrapOrThrow(await tryFsWrite("mutator.close", () => handle.close(), { path: finalPath }));
+    }
+    return "ok";
+}
+/**
+ * The shared write gauntlet both realizations run: resolve + confine
+ * (`resolveForWrite`), then the hardened landing wrapped in `runStep`. A
+ * refusal comes back as data; an ok carries what the caller's provenance
+ * record needs — the analysis-relative path and the exact bytes that landed.
+ */
+async function confinedWrite(args) {
+    const scoped = resolveForWrite({
+        workspaceRoot: args.workspaceRoot,
+        analysisId: args.analysisId,
+        workingDir: args.workingDir,
+        path: args.path,
+    });
+    if (scoped.kind === "out_of_scope")
+        return { status: "out_of_scope" };
+    if (scoped.kind === "out_of_prefix")
+        return { status: "out_of_prefix" };
+    // Analysis-root-relative, forward-slashed: the agent-facing result
+    // path prepends the `/{analysisId}` frame; a provenance record uses
+    // the bare tail (the collector normalizes it step-relative itself).
+    const relative = scoped.relative.split("\\").join("/");
+    const agentPath = `/${args.analysisId}/${relative}`;
+    const bytes = Buffer.from(args.content, "utf8");
+    const prefix = resolvePath(args.workingDir);
+    // The loop dispatches a workflow-mode tool body unwrapped (see
+    // `dispatchTools` in loop/run-agent.ts), so a DBOS replay re-runs
+    // this body. The step wrapper caches the landing: a replay returns
+    // the recorded outcome instead of touching the disk again. On the
+    // chat route the injected `runStep` is the passthrough — the same
+    // call, no durability, no fork of this path.
+    const landed = await args.runStep("write", () => landBytes(prefix, scoped.absolute, bytes));
+    if (landed !== "ok")
+        return { status: landed };
+    return { status: "ok", relative, agentPath, bytes };
+}
 export function createWorkspaceMutator(deps) {
     return {
-        async writeFile({ path, content, toolName, emit }) {
-            const scoped = resolveForWrite({
+        async writeFile({ path, content, toolName, invocationId, runStep }) {
+            const landed = await confinedWrite({
                 workspaceRoot: deps.workspaceRoot,
                 analysisId: deps.analysisId,
                 workingDir: deps.workingDir,
                 path,
+                content,
+                runStep,
             });
-            if (scoped.kind === "out_of_scope")
-                return { status: "out_of_scope", path };
-            if (scoped.kind === "out_of_prefix")
-                return { status: "out_of_prefix", path };
-            // Analysis-root-relative, forward-slashed: the sandbox path prepends
-            // the `/{analysisId}` mount; the provenance record uses the bare tail
-            // (the collector normalizes it step-relative itself).
-            const relative = scoped.relative.split("\\").join("/");
-            const sandboxPath = `/${deps.analysisId}/${relative}`;
-            const contentBytes = Buffer.from(content, "utf8");
-            const execId = `${deps.workflowId}:${deps.stepId}:${deps.nextFunctionId()}`;
-            const result = await runSandboxExec({
-                sandboxClient: deps.sandboxClient,
-                sandbox: deps.sandbox,
-                execId,
-                command: ["python3", "-c", WRITE_BYTES_PROGRAM, sandboxPath, contentBytes.toString("base64")],
-                cwd: deps.sandboxWorkingDir,
-                deadlineMs: deps.deadlineMs(),
-                emit,
-            });
-            if (result.exitCode !== 0) {
-                return { status: "write_failed", path: sandboxPath, ...boundExecResult(result) };
-            }
+            if (landed.status !== "ok")
+                return { status: landed.status, path };
             // Attest the write in-process from the exact bytes just written — the
             // seam owns write provenance the same way it owns confinement. The
-            // sandbox exec frame this write produces is deliberately not fed to
-            // `feedExecFrame`: doing so would mint a `python3`+base64 command
-            // record, the very misattribution this file-tool record supersedes.
+            // record lands outside the write step on purpose: the collector is
+            // process-local state, so a recovered replay must re-record into the
+            // fresh collector even while the cached step skips the disk write.
             //
-            // `timestamp` is a write-time wall clock — normally a replay hazard in
-            // provenance, but safe here because the record contributes only producer
-            // IDENTITY downstream: the bridge drops it (the cli's file-tool ref has no
-            // timestamp field) and the signed `inflexa:FileToolWrite` activity carries
-            // just the tool name, so a re-execution's fresh stamp changes nothing in
-            // the attested graph. Do NOT start forwarding it into an identifier or a
-            // formal PROV position without making it replay-stable first.
+            // `invocationId` is replay-stable: the model turn that minted the tool
+            // call is a durably cached step, so a re-execution replays the same id.
+            // That is what lets the bridge key a DETERMINISTIC call-activity
+            // identifier on it — a wall-clock stamp here would be re-minted per
+            // replay and must never reach an identifier or a formal PROV position.
             if (deps.lineageCollector) {
                 deps.lineageCollector.recordFileToolWrite({
-                    path: relative,
-                    hash: computeSha256(contentBytes),
-                    size: contentBytes.length,
+                    path: landed.relative,
+                    hash: computeSha256(landed.bytes),
+                    size: landed.bytes.length,
                     toolName,
-                    timestamp: new Date().toISOString(),
+                    invocationId,
                 });
             }
-            return { status: "ok", path: sandboxPath, bytesWritten: contentBytes.length };
+            return { status: "ok", path: landed.agentPath, bytesWritten: landed.bytes.length };
+        },
+    };
+}
+/**
+ * The session-scoped `WorkspaceMutator` realization — the conversation agent's
+ * write path. Where `createWorkspaceMutator` closes over fixed per-step
+ * coordinates, this one serves every analysis from one construction: each call
+ * resolves the workspace root from the session's analysis scope, and the write
+ * prefix IS that root — the agent modifies its own analysis tree freely, while
+ * `..` traversal, a foreign analysis, and the symlink escapes stay refused by
+ * the same gauntlet.
+ *
+ * A write here runs under no run and no step, so its provenance is a session
+ * observation, not a collector record: each successful write emits one
+ * `write-file` session event (see `provenance/seam.ts`).
+ */
+export function createSessionWorkspaceMutator(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("workspace-mutator");
+    const observe = bindSessionEmit(deps.provenance, logger);
+    return {
+        async writeFile({ path, content, toolName, invocationId, runStep, session }) {
+            // Only an analysis scope has a workspace tree; under any other
+            // scope there is nothing in scope to write.
+            const scope = session.scope;
+            if (scope.kind !== "analysis")
+                return { status: "out_of_scope", path };
+            // Throws on an unknown analysis — the loop's dispatch catch maps
+            // it to an error tool result, like any unexpected host failure.
+            const workspaceRoot = deps.resolveWorkspaceRoot(scope.analysisId);
+            const landed = await confinedWrite({
+                workspaceRoot,
+                analysisId: scope.analysisId,
+                workingDir: workspaceRoot,
+                path,
+                content,
+                runStep,
+            });
+            if (landed.status !== "ok")
+                return { status: landed.status, path };
+            observe({
+                type: "write-file",
+                analysisId: scope.analysisId,
+                ...(scope.threadId !== undefined ? { threadId: scope.threadId } : {}),
+                path: landed.relative,
+                hash: computeSha256(landed.bytes),
+                size: landed.bytes.length,
+                tool: toolName,
+                invocationId,
+            });
+            return { status: "ok", path: landed.agentPath, bytesWritten: landed.bytes.length };
         },
     };
 }

package/dist/tools/workspace/run-exec.d.ts

@@ -1,13 +1,13 @@
 /**
  * Internal helper used by dependency-bearing tools to drive one sandbox exec
  * through the `SandboxClient`. Centralises the submit/await pair, exec-id
- * derivation, and intermediate-event forwarding so all three tools share
- * one chokepoint. `write_file` / `edit_file` are layered on the workspace
- * mutator and environment introspection tools such as `list_available_refs`
- * use this same replay-safe submit/await path rather than a parallel protocol.
+ * derivation, and intermediate-event forwarding in one chokepoint.
+ * `execute_command` and environment introspection tools such as
+ * `list_available_refs` use this same replay-safe submit/await path rather
+ * than a parallel protocol.
  *
  * Not a registered tool — `defineTool` is called by the user-facing tools
- * (`execute-command.ts`, `write-file.ts`, `edit-file.ts`) which wrap this.
+ * (`execute-command.ts`) which wrap this.
  */
 import type { SandboxClient } from "../../sandbox/client.js";
 import type { ExecResult, SandboxRef } from "../../sandbox/types.js";

package/dist/tools/workspace/run-exec.js

@@ -1,13 +1,13 @@
 /**
  * Internal helper used by dependency-bearing tools to drive one sandbox exec
  * through the `SandboxClient`. Centralises the submit/await pair, exec-id
- * derivation, and intermediate-event forwarding so all three tools share
- * one chokepoint. `write_file` / `edit_file` are layered on the workspace
- * mutator and environment introspection tools such as `list_available_refs`
- * use this same replay-safe submit/await path rather than a parallel protocol.
+ * derivation, and intermediate-event forwarding in one chokepoint.
+ * `execute_command` and environment introspection tools such as
+ * `list_available_refs` use this same replay-safe submit/await path rather
+ * than a parallel protocol.
  *
  * Not a registered tool — `defineTool` is called by the user-facing tools
- * (`execute-command.ts`, `write-file.ts`, `edit-file.ts`) which wrap this.
+ * (`execute-command.ts`) which wrap this.
  */
 export async function runSandboxExec(args) {
     const body = {

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

@@ -1,10 +1,10 @@
 /**
- * `write_file` — sandbox-gated workspace write, confined to the agent's
- * writable working directory.
+ * `write_file` — workspace write, confined to the agent's writable working
+ * directory.
  *
  * A thin adapter over the `WorkspaceMutator` seam (see the harness-durable-runtime / harness-workspace-tools specs): the
- * mutator owns resolve + confine + sandbox write + provenance. This tool only
- * declares the input schema and forwards. `edit_file` rides the same seam.
+ * mutator owns resolve + confine + hardened host write + provenance. This tool
+ * only declares the input schema and forwards. `edit_file` rides the same seam.
  */
 import type { WorkspaceMutator } from "./mutator.js";
 export interface WriteFileDeps {

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

@@ -1,10 +1,10 @@
 /**
- * `write_file` — sandbox-gated workspace write, confined to the agent's
- * writable working directory.
+ * `write_file` — workspace write, confined to the agent's writable working
+ * directory.
  *
  * A thin adapter over the `WorkspaceMutator` seam (see the harness-durable-runtime / harness-workspace-tools specs): the
- * mutator owns resolve + confine + sandbox write + provenance. This tool only
- * declares the input schema and forwards. `edit_file` rides the same seam.
+ * mutator owns resolve + confine + hardened host write + provenance. This tool
+ * only declares the input schema and forwards. `edit_file` rides the same seam.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
@@ -21,7 +21,8 @@ const WriteFileInputSchema = z.object({
 export function createWriteFileTool(deps) {
     return defineTool({
         id: "write_file",
-        // Body-only `awaitExec`-recv → runs unwrapped in the workflow body (see the harness-tools spec).
+        // The mutator wraps the disk mutation in `ctx.runStep` itself, so the
+        // body runs unwrapped in the workflow body (see the harness-tools spec).
         executionMode: "workflow",
         description: "Write a UTF-8 text file in your working directory. Relative paths " +
             "resolve against it; a path outside it returns an `out_of_prefix` data " +
@@ -31,6 +32,13 @@ export function createWriteFileTool(deps) {
         // The path only. `content` is a whole file and must never ride a display
         // channel, which the emit-site length cap enforces regardless.
         describeCall: ({ path }) => path,
-        execute: async ({ path, content }, ctx) => ok(await deps.mutator.writeFile({ path, content, toolName: "write_file", emit: ctx.emit })),
+        execute: async ({ path, content }, ctx) => ok(await deps.mutator.writeFile({
+            path,
+            content,
+            toolName: "write_file",
+            invocationId: ctx.invocationId,
+            runStep: ctx.runStep,
+            session: ctx.session,
+        })),
     });
 }

package/dist/workspace/paths.d.ts

@@ -155,7 +155,7 @@ export declare function tailWritePrefix(args: {
  * in-sandbox absolute path. The tree is bind-mounted at `/{resourceId}`, so
  * the sandbox path is the resource id plus the root-relative tail — the host
  * location of the root never leaks into the container. Single source of truth
- * for the `execute_command` / `write_file` cwd and for the working directory
+ * for the `execute_command` cwd and for the working directory
  * a step briefing names (see the harness-workspace-tools spec).
  */
 export declare function toSandboxPath(workspaceRoot: string, resourceId: string, hostAbsPath: string): string;

package/dist/workspace/paths.js

@@ -137,7 +137,7 @@ export function tailWritePrefix(args) {
  * in-sandbox absolute path. The tree is bind-mounted at `/{resourceId}`, so
  * the sandbox path is the resource id plus the root-relative tail — the host
  * location of the root never leaks into the container. Single source of truth
- * for the `execute_command` / `write_file` cwd and for the working directory
+ * for the `execute_command` cwd and for the working directory
  * a step briefing names (see the harness-workspace-tools spec).
  */
 export function toSandboxPath(workspaceRoot, resourceId, hostAbsPath) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.33.1",
+    "version": "0.34.0",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",