@inflexa-ai/harness 0.42.1 → 0.43.0

package/dist/tools/sandbox/list-available-packages.js

@@ -400,7 +400,7 @@ export function queryPackages(rawSections, { names, query, language, limit }) {
  * here, thus the census a model sees and the check a launch runs never
  * disagree about what the source holds.
  */
-export async function readInventorySections(deps) {
+export async function readInventorySections(deps, analysisId) {
     // The image record merges in when the host can read a valid one. An absent
     // record and an invalid record both merge nothing, and neither is an
     // error: the record is an enrichment, and the farm or pool inventory stays
@@ -422,8 +422,9 @@ export async function readInventorySections(deps) {
     }
     // Both farm container paths are tried when the host injects none, because
     // the path keys on the declared toolchain and this read carries none.
+    const farmLockFile = typeof deps.farmLockFile === "function" ? deps.farmLockFile(analysisId) : deps.farmLockFile;
     let lock = null;
-    for (const candidate of deps.farmLockFile ? [deps.farmLockFile] : DEFAULT_FARM_LOCK_FILES) {
+    for (const candidate of farmLockFile ? [farmLockFile] : DEFAULT_FARM_LOCK_FILES) {
         lock = readFarmLockFile(candidate).unwrapOr(null);
         if (lock !== null)
             break;
@@ -502,8 +503,8 @@ export function createListAvailablePackagesTool(deps = {}) {
                 return `${language} packages`;
             return "full package list";
         },
-        execute: async (input) => {
-            const read = await readInventorySections(deps);
+        execute: async (input, ctx) => {
+            const read = await readInventorySections(deps, ctx.session.scope.analysisId);
             // An unreadable inventory is an expected environment state — model it as an
             // `available: false` data variant telling the caller the set is UNKNOWN,
             // WITH the reason: without it, a structural fault (a damaged dependency

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

@@ -11,10 +11,11 @@
  * (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.
+ * content — the mutator records it through the fold of this tool.
  */
+import { type WithToolCallRecord } from "../define-tool.js";
 import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
-import type { WorkspaceMutator, WriteFileResult } from "./mutator.js";
+import type { WorkspaceMutator, WriteFileResult, WriteRecord } from "./mutator.js";
 /** Outcome of an `edit_file` call — expected outcomes are data variants, never throws. */
 export type EditFileResult = {
     readonly status: "file_not_found";
@@ -43,14 +44,14 @@ export type EditFileResult = {
     readonly lines: readonly number[];
 } | Exclude<WriteFileResult, {
     status: "ok";
-}> | {
+}> | WithToolCallRecord<{
     readonly status: "ok";
     readonly path: string;
     readonly replacements: number;
     readonly bytesWritten: number;
     /** Regex mode only: 1-based line numbers where the matches started. */
     readonly lines?: readonly number[];
-};
+}, WriteRecord>;
 export interface EditFileDeps {
     readonly mutator: WorkspaceMutator;
     /** Read seam used to fetch current file content for search/replace. */

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

@@ -11,11 +11,11 @@
  * (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.
+ * content — the mutator records it through the fold of this tool.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
-import { defineTool } from "../define-tool.js";
+import { defineTool, withToolCallRecord } from "../define-tool.js";
 import { unwrapOrThrow } from "../../lib/result.js";
 const EditFileInputSchema = z.object({
     path: z
@@ -108,9 +108,6 @@ function replaceRegex(content, pattern, replacement, expected) {
 export function createEditFileTool(deps) {
     return defineTool({
         id: "edit_file",
-        // 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. For a bulk pattern " +
@@ -166,24 +163,24 @@ export function createEditFileTool(deps) {
                     lines: replaced.lines,
                 });
             }
-            const result = await deps.mutator.writeFile({
+            const write = await deps.mutator.writeFile({
                 path,
                 content: replaced.content,
                 toolName: "edit_file",
                 invocationId: ctx.invocationId,
-                runStep: ctx.runStep,
                 session: ctx.session,
             });
-            if (result.status !== "ok")
-                return ok(result);
+            if (write.status !== "ok")
+                return ok(write);
             const lines = replaced.lines;
-            return ok({
+            return ok(withToolCallRecord({
                 status: "ok",
-                path: result.path,
+                path: write.path,
                 replacements: replaced.replacements,
-                bytesWritten: result.bytesWritten,
+                bytesWritten: write.bytesWritten,
                 ...(lines === undefined ? {} : { lines }),
-            });
+            }, write.record));
         },
+        foldCallRecord: (record) => deps.mutator.recordWrite(record),
     });
 }

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

@@ -2,45 +2,46 @@
  * `execute_command` — the single chokepoint through which sandbox commands
  * run.
  *
- * Dependency-bearing factory (see the harness-durable-runtime spec): captures a `SandboxClient`, the
- * live `SandboxRef` for the step, and the per-call execId minter. No other
- * tool, agent, or workflow step is permitted to POST to sandbox-server's
- * `/exec` directly — `SandboxClient` is intentionally injected only here so
- * the durability / idempotency / liveness story `harness-sandbox-exec`
- * owns holds uniformly across all sandbox command execution.
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures a
+ * `SandboxClient` and the live `SandboxRef` for the step. No other tool, agent,
+ * or workflow step is permitted to POST to sandbox-server's `/exec` directly —
+ * `SandboxClient` is intentionally injected only here so the durability /
+ * idempotency / liveness story `harness-sandbox-exec` owns holds uniformly
+ * across all sandbox command execution.
  *
- * `execId` is derived as `${workflowId}:${stepId}:${functionId}` so replays
- * land on the cached DBOS step output rather than re-submitting; the same
- * `execId` is the step name `submitExec` uses (`sandbox.submit-exec.${execId}`).
+ * The loop runs each call as one durable step, and the exec runs inside it,
+ * thus the exec id is the id of that step and a replay returns the cached
+ * result with no submit.
  *
  * Provenance for files written *inside* the sandbox by the executed command
  * is NOT recorded here — sandbox-server emits provenance frames (see
  * `sandbox-provenance-tracking`), and artifact registration reconciles them.
- * The harness-side mutate tools (`write_file`, `edit_file`) hash and record
- * the writes *they* perform, but `execute_command`'s opaque commands do not.
+ * The frame of each exec rides the call record, and the fold feeds it to the
+ * lineage collector of the step.
  */
+import { type WithToolCallRecord } from "../define-tool.js";
 import type { SandboxClient } from "../../sandbox/client.js";
-import type { SandboxRef } from "../../sandbox/types.js";
+import type { ProvenanceFrame, SandboxRef } from "../../sandbox/types.js";
 import type { ProvenanceCollector } from "../../provenance/collector.js";
+import { type BoundedExecResult } from "./result-bounds.js";
 import type { Logger } from "../../lib/logger.js";
+/** What one exec leaves for the lineage collector of the step. */
+interface ExecCallRecord {
+    readonly command: readonly string[];
+    readonly exitCode: number | null;
+    readonly durationMs: number | null;
+    readonly provenance?: ProvenanceFrame;
+}
+type ExecuteCommandResult = {
+    readonly status: "ok";
+} & BoundedExecResult;
 export interface ExecuteCommandDeps {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     readonly sandboxClient: SandboxClient;
     /** Live sandbox handle for the step. Created once per step at composition root. */
     readonly sandbox: SandboxRef;
-    /** Stable across replay. The workflow's DBOS workflow id. */
-    readonly workflowId: string;
-    /** Stable across replay. The sandbox step's identifier within the workflow. */
-    readonly stepId: string;
-    /**
-     * Mints a stable per-call function id. The composition root closes over a
-     * monotonic counter; the agent loop's tool-call order is replay-deterministic
-     * (the LLM call wrapping it is a cached DBOS step), so the counter reaches
-     * the same value at each call site on replay.
-     */
-    readonly nextFunctionId: () => string;
-    /** Absolute unix-ms deadline for `awaitExec`. Typically derived from `step.timeout`. */
+    /** Absolute unix-ms deadline of the exec. Typically derived from `step.timeout`. */
     readonly deadlineMs: () => number;
     /**
      * In-sandbox absolute path of the agent's working directory (e.g.
@@ -49,8 +50,6 @@ export interface ExecuteCommandDeps {
      * and as the base a supplied relative `cwd` resolves against (see the harness-workspace-tools spec).
      */
     readonly defaultCwd: string;
-    /** Tag the active-sandbox row with the in-flight execId for the liveness watchdog. */
-    readonly markExecActive?: (execId: string) => Promise<void>;
     /**
      * Step-scoped lineage collector. Each exec's `ExecResult.provenance`
      * frame is fed here (reads → inputs, writes → outputs) so post-step
@@ -65,19 +64,5 @@ export declare function createExecuteCommandTool(deps: ExecuteCommandDeps): impo
     cwd?: string | undefined;
     env?: Record<string, string> | undefined;
     timeoutSeconds?: number | undefined;
-}, {
-    execId: string;
-    exitCode: number | null;
-    stdout: string;
-    stderr: string;
-    stdoutTruncated: boolean;
-    stderrTruncated: boolean;
-    stdoutTotalLength: number;
-    stderrTotalLength: number;
-    durationMs: number | null;
-    timedOut: boolean;
-    syntheticFailure?: {
-        readonly reason: string;
-    };
-    status: "ok";
-}>;
+}, ExecuteCommandResult | WithToolCallRecord<ExecuteCommandResult, ExecCallRecord>>;
+export {};

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

@@ -2,27 +2,27 @@
  * `execute_command` — the single chokepoint through which sandbox commands
  * run.
  *
- * Dependency-bearing factory (see the harness-durable-runtime spec): captures a `SandboxClient`, the
- * live `SandboxRef` for the step, and the per-call execId minter. No other
- * tool, agent, or workflow step is permitted to POST to sandbox-server's
- * `/exec` directly — `SandboxClient` is intentionally injected only here so
- * the durability / idempotency / liveness story `harness-sandbox-exec`
- * owns holds uniformly across all sandbox command execution.
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures a
+ * `SandboxClient` and the live `SandboxRef` for the step. No other tool, agent,
+ * or workflow step is permitted to POST to sandbox-server's `/exec` directly —
+ * `SandboxClient` is intentionally injected only here so the durability /
+ * idempotency / liveness story `harness-sandbox-exec` owns holds uniformly
+ * across all sandbox command execution.
  *
- * `execId` is derived as `${workflowId}:${stepId}:${functionId}` so replays
- * land on the cached DBOS step output rather than re-submitting; the same
- * `execId` is the step name `submitExec` uses (`sandbox.submit-exec.${execId}`).
+ * The loop runs each call as one durable step, and the exec runs inside it,
+ * thus the exec id is the id of that step and a replay returns the cached
+ * result with no submit.
  *
  * Provenance for files written *inside* the sandbox by the executed command
  * is NOT recorded here — sandbox-server emits provenance frames (see
  * `sandbox-provenance-tracking`), and artifact registration reconciles them.
- * The harness-side mutate tools (`write_file`, `edit_file`) hash and record
- * the writes *they* perform, but `execute_command`'s opaque commands do not.
+ * The frame of each exec rides the call record, and the fold feeds it to the
+ * lineage collector of the step.
  */
 import { posix as posixPath } from "node:path";
 import { ok } from "neverthrow";
 import { z } from "zod";
-import { defineTool } from "../define-tool.js";
+import { defineTool, withToolCallRecord } from "../define-tool.js";
 import { feedExecFrame } from "../../provenance/exec-frame.js";
 import { EXEC_STREAM_BYTE_CAP, boundExecResult } from "./result-bounds.js";
 import { runSandboxExec } from "./run-exec.js";
@@ -50,12 +50,9 @@ function scriptToken(command) {
     return command.find((arg) => SCRIPT_EXTENSIONS.test(arg));
 }
 export function createExecuteCommandTool(deps) {
-    const { sandboxClient, sandbox, workflowId, stepId, nextFunctionId, deadlineMs, defaultCwd, markExecActive, lineageCollector, mountRoot } = deps;
+    const { sandboxClient, sandbox, deadlineMs, defaultCwd, lineageCollector, mountRoot } = deps;
     return defineTool({
         id: "execute_command",
-        // `awaitExec`-recv is body-only (`DBOS.recv`), so this runs unwrapped in
-        // the workflow body; durability is self-owned (submit step + body recv). See the harness-tools spec.
-        executionMode: "workflow",
         description: "Run a command in the sandbox and return its stdout/stderr/exit code. " +
             "Use for scripts, CLI tools, shell pipes, and anything the workspace " +
             `tools don't express. stdout and stderr are each capped at ${EXEC_STREAM_BYTE_CAP / (1024 * 1024)} MiB; the end ` +
@@ -88,40 +85,47 @@ export function createExecuteCommandTool(deps) {
         // outlives the turn that ran it.
         describeCall: ({ command }) => scriptToken(command) ?? command.join(" "),
         execute: async ({ command, cwd, env, timeoutSeconds }, ctx) => {
-            const execId = `${workflowId}:${stepId}:${nextFunctionId()}`;
             const effectiveCwd = cwd === undefined ? defaultCwd : cwd.startsWith("/") ? cwd : posixPath.join(defaultCwd, cwd);
             const result = await runSandboxExec({
                 sandboxClient,
                 sandbox,
-                execId,
                 command,
                 cwd: effectiveCwd,
                 ...(env === undefined ? {} : { env }),
                 ...(timeoutSeconds === undefined ? {} : { timeoutSeconds }),
                 deadlineMs: deadlineMs(),
                 emit: ctx.emit,
-                ...(markExecActive ? { markExecActive } : {}),
             });
-            // Thread the runtime file-I/O frame into the step's lineage collector.
-            // Best-effort: a collector failure must never fail the exec.
-            if (lineageCollector && mountRoot) {
-                try {
-                    feedExecFrame({
-                        collector: lineageCollector,
-                        mountRoot,
-                        command,
-                        exitCode: result.exitCode,
-                        durationMs: result.durationMs,
-                        ...(deps.logger ? { logger: deps.logger } : {}),
-                        ...(result.provenance ? { provenance: result.provenance } : {}),
-                    });
-                }
-                catch (err) {
-                    const logger = (deps.logger ?? createNoopLogger()).named("execute_command");
-                    logger.warn("provenance frame handling failed (non-fatal)", { execId, ...logger.errorFields(err) });
-                }
+            const bounded = { status: "ok", ...boundExecResult(result) };
+            if (!lineageCollector || !mountRoot)
+                return ok(bounded);
+            const record = {
+                command,
+                exitCode: result.exitCode,
+                durationMs: result.durationMs,
+                ...(result.provenance ? { provenance: result.provenance } : {}),
+            };
+            return ok(withToolCallRecord(bounded, record));
+        },
+        // Best-effort: a collector failure must never fail the exec.
+        foldCallRecord: (record) => {
+            if (!lineageCollector || !mountRoot)
+                return;
+            try {
+                feedExecFrame({
+                    collector: lineageCollector,
+                    mountRoot,
+                    command: record.command,
+                    exitCode: record.exitCode,
+                    durationMs: record.durationMs,
+                    ...(deps.logger ? { logger: deps.logger } : {}),
+                    ...(record.provenance ? { provenance: record.provenance } : {}),
+                });
+            }
+            catch (err) {
+                const logger = (deps.logger ?? createNoopLogger()).named("execute_command");
+                logger.warn("provenance frame handling failed (non-fatal)", logger.errorFields(err));
             }
-            return ok({ status: "ok", ...boundExecResult(result) });
         },
     });
 }

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

@@ -4,12 +4,11 @@
  * Read surface (sandbox-independent): semantic file search, raw read + grep
  * over the workspace filesystem seam, plus file/plan display.
  *
- * Mutate surface (sandbox-gated): `execute_command` (single chokepoint for
- * sandbox commands), `write_file` and `edit_file` scoped to the step's
- * writable artifact directory. Each mutate factory captures a `SandboxClient`
- * and the step coordinates; only `execute_command` is permitted to drive
- * sandbox-server's `/exec` — `write_file` / `edit_file` ride the same
- * submit/await path through `runSandboxExec`.
+ * Mutate surface: `execute_command` (single chokepoint for sandbox commands,
+ * sandbox-gated), `write_file` and `edit_file` scoped to the writable
+ * directory of the agent. `execute_command` drives sandbox-server's `/exec`
+ * through `runSandboxExec`; `write_file` / `edit_file` write host-side through
+ * the workspace mutator.
  */
 export * from "./workspace-search.js";
 export * from "./show-file.js";

package/dist/tools/workspace/index.js

@@ -4,12 +4,11 @@
  * Read surface (sandbox-independent): semantic file search, raw read + grep
  * over the workspace filesystem seam, plus file/plan display.
  *
- * Mutate surface (sandbox-gated): `execute_command` (single chokepoint for
- * sandbox commands), `write_file` and `edit_file` scoped to the step's
- * writable artifact directory. Each mutate factory captures a `SandboxClient`
- * and the step coordinates; only `execute_command` is permitted to drive
- * sandbox-server's `/exec` — `write_file` / `edit_file` ride the same
- * submit/await path through `runSandboxExec`.
+ * Mutate surface: `execute_command` (single chokepoint for sandbox commands,
+ * sandbox-gated), `write_file` and `edit_file` scoped to the writable
+ * directory of the agent. `execute_command` drives sandbox-server's `/exec`
+ * through `runSandboxExec`; `write_file` / `edit_file` write host-side through
+ * the workspace mutator.
  */
 // Read surface
 export * from "./workspace-search.js";

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

@@ -9,6 +9,12 @@
  * invariant is concentrated in one place instead of being a per-tool
  * convention.
  *
+ * The write and its provenance record are two calls. `writeFile` lands the
+ * bytes and gives back the record of the write; the tool carries the record as
+ * its call record, and its fold hands it to `recordWrite`. The loop caches the
+ * tool call as one step, thus a replay never lands the bytes again, and the
+ * fold still records the write into fresh process state.
+ *
  * 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`
@@ -25,7 +31,6 @@
  */
 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 ProvenanceSeam } from "../../provenance/seam.js";
 import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
@@ -44,6 +49,31 @@ export type WriteFileResult = {
     readonly status: "symlink_denied";
     readonly path: string;
 };
+/**
+ * What one landed write leaves for provenance: the hash and the size of the
+ * exact bytes on disk, computed at the landing. Plain JSON, because the step
+ * cache of the tool call holds it.
+ */
+export interface WriteRecord {
+    readonly analysisId: string;
+    /** The thread of a session write; absent under a run. */
+    readonly 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 = {
+    readonly status: "ok";
+    readonly path: string;
+    readonly bytesWritten: number;
+    readonly record: WriteRecord;
+} | Exclude<WriteFileResult, {
+    status: "ok";
+}>;
 /**
  * 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
@@ -73,20 +103,25 @@ export interface WorkspaceMutator {
      * 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.
+     * call activity gets a deterministic identity. `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.
+     *
+     * Records nothing: a successful write gives back its record for `recordWrite`.
      */
     writeFile(args: {
         readonly path: string;
         readonly content: string;
         readonly toolName: MutateToolName;
         readonly invocationId: string;
-        readonly runStep: RunStep;
         readonly session: AgentSession;
-    }): Promise<WriteFileResult>;
+    }): 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}. */

package/dist/tools/workspace/mutator.js

@@ -9,6 +9,12 @@
  * invariant is concentrated in one place instead of being a per-tool
  * convention.
  *
+ * The write and its provenance record are two calls. `writeFile` lands the
+ * bytes and gives back the record of the write; the tool carries the record as
+ * its call record, and its fold hands it to `recordWrite`. The loop caches the
+ * tool call as one step, thus a replay never lands the bytes again, and the
+ * fold still records the write into fresh process state.
+ *
  * 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`
@@ -107,9 +113,9 @@ async function landBytes(prefix, absolute, bytes) {
 }
 /**
  * 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.
+ * (`resolveForWrite`), then the hardened landing. 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({
@@ -129,51 +135,46 @@ async function confinedWrite(args) {
     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));
+    const landed = await 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, invocationId, runStep }) {
+        async writeFile({ path, content, toolName, invocationId }) {
             const landed = await confinedWrite({
                 workspaceRoot: deps.workspaceRoot,
                 analysisId: deps.analysisId,
                 workingDir: deps.workingDir,
                 path,
                 content,
-                runStep,
             });
             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
-            // 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.
-            //
             // `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: landed.relative,
-                    hash: computeSha256(landed.bytes),
-                    size: landed.bytes.length,
-                    toolName,
-                    invocationId,
-                });
-            }
-            return { status: "ok", path: landed.agentPath, bytesWritten: landed.bytes.length };
+            const record = {
+                analysisId: deps.analysisId,
+                path: landed.relative,
+                hash: computeSha256(landed.bytes),
+                size: landed.bytes.length,
+                toolName,
+                invocationId,
+            };
+            return { status: "ok", path: landed.agentPath, bytesWritten: landed.bytes.length, record };
+        },
+        recordWrite(record) {
+            deps.lineageCollector?.recordFileToolWrite({
+                path: record.path,
+                hash: record.hash,
+                size: record.size,
+                toolName: record.toolName,
+                invocationId: record.invocationId,
+            });
         },
     };
 }
@@ -194,7 +195,7 @@ 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 }) {
+        async writeFile({ path, content, toolName, invocationId, session }) {
             // Only an analysis scope has a workspace tree; under any other
             // scope there is nothing in scope to write.
             const scope = session.scope;
@@ -209,21 +210,31 @@ export function createSessionWorkspaceMutator(deps) {
                 workingDir: workspaceRoot,
                 path,
                 content,
-                runStep,
             });
             if (landed.status !== "ok")
                 return { status: landed.status, path };
-            observe({
-                type: "write-file",
+            const record = {
                 analysisId: scope.analysisId,
                 ...(scope.threadId !== undefined ? { threadId: scope.threadId } : {}),
                 path: landed.relative,
                 hash: computeSha256(landed.bytes),
                 size: landed.bytes.length,
-                tool: toolName,
+                toolName,
                 invocationId,
+            };
+            return { status: "ok", path: landed.agentPath, bytesWritten: landed.bytes.length, record };
+        },
+        recordWrite(record) {
+            observe({
+                type: "write-file",
+                analysisId: record.analysisId,
+                ...(record.threadId !== undefined ? { threadId: record.threadId } : {}),
+                path: record.path,
+                hash: record.hash,
+                size: record.size,
+                tool: record.toolName,
+                invocationId: record.invocationId,
             });
-            return { status: "ok", path: landed.agentPath, bytesWritten: landed.bytes.length };
         },
     };
 }

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

@@ -1,10 +1,8 @@
 /**
  * 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 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.
+ * through the `SandboxClient`. It wraps each sandbox event in a
+ * `data-sandbox-event` part, thus `execute_command` and the container readout
+ * of `scan_inputs` report progress in one shape.
  *
  * Not a registered tool — `defineTool` is called by the user-facing tools
  * (`execute-command.ts`) which wrap this.
@@ -15,18 +13,11 @@ import type { EmitFn } from "../define-tool.js";
 export interface RunExecArgs {
     readonly sandboxClient: SandboxClient;
     readonly sandbox: SandboxRef;
-    readonly execId: string;
     readonly command: readonly string[];
     readonly cwd?: string;
     readonly env?: Record<string, string>;
     readonly timeoutSeconds?: number;
     readonly deadlineMs: number;
     readonly emit: EmitFn;
-    /**
-     * Tag the active-sandbox registry row with this execId before awaiting, so
-     * the liveness watchdog can target the in-flight exec when the sandbox dies
-     * mid-command. Best-effort: a registry write failure must not fail the exec.
-     */
-    readonly markExecActive?: (execId: string) => Promise<void>;
 }
 export declare function runSandboxExec(args: RunExecArgs): Promise<ExecResult>;