@inflexa-ai/harness 0.46.2 → 0.48.0

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

@@ -2,12 +2,11 @@
  * `execute_command` — the single chokepoint through which sandbox commands
  * run.
  *
- * 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.
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures the
+ * lease of the step. The sandbox module gives the machine of the lease, or a new
+ * one when the machine went away, thus the durability, idempotency, and liveness
+ * story of `harness-sandbox-exec` holds for each command. A command with no lease
+ * gives an error result that names `acquire_sandbox`.
  *
  * 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
@@ -27,8 +26,8 @@
  */
 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 { BoundLease } from "../../sandbox/leases.js";
+import type { ProvenanceFrame } 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";
@@ -55,11 +54,8 @@ type ExecuteCommandResult = {
 export type 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;
-    /** Absolute unix-ms deadline of the exec. Typically derived from `step.timeout`. */
-    readonly deadlineMs: () => number;
+    /** The lease of the step: `acquire_sandbox` takes it, and each command runs on its machine. */
+    readonly lease: BoundLease;
     /**
      * In-sandbox absolute path of the agent's working directory (e.g.
      * `/{resourceId}/runs/{runId}/{stepId}`). Used as the default `cwd` so a

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

@@ -2,12 +2,11 @@
  * `execute_command` — the single chokepoint through which sandbox commands
  * run.
  *
- * 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.
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures the
+ * lease of the step. The sandbox module gives the machine of the lease, or a new
+ * one when the machine went away, thus the durability, idempotency, and liveness
+ * story of `harness-sandbox-exec` holds for each command. A command with no lease
+ * gives an error result that names `acquire_sandbox`.
  *
  * 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
@@ -26,7 +25,7 @@
  * code that ran.
  */
 import { posix as posixPath } from "node:path";
-import { ok } from "neverthrow";
+import { err, ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool, withToolCallRecord } from "../define-tool.js";
 import { feedExecFrame } from "../../provenance/exec-frame.js";
@@ -39,16 +38,17 @@ const ExecuteCommandInputSchema = z.object({
         .array(z.string().min(1))
         .min(1)
         .describe("argv array — e.g. ['python', 'scripts/run.py'] or ['head', '-n', '50', 'data/inputs/x.csv']. " +
-        "A one-element array runs through `sh -c`, so pipes, `&&`, quoting, and globbing work; " +
-        "an array of two or more elements runs directly, with no shell, and nothing is expanded."),
+        "A one-element array runs through `sh -c`, so pipes, `&&`, quoting, and globbing work, and a path that holds a space " +
+        "needs double quotes there; an array of two or more elements runs directly, with no shell, and nothing is expanded."),
     cwd: z
         .string()
         .optional()
         .describe("Working directory inside the sandbox. Defaults to your working " +
         "directory; a relative value is resolved against it, an absolute " +
-        "'/<analysisId>/...' value is used as-is."),
+        "'/<analysisId>/...' value is used as-is. Each call starts here: a `cd` in an earlier call " +
+        "does not carry over, thus pass `cwd` or chain the commands with `&&` in one call."),
     env: z.record(z.string(), z.string()).optional().describe("Extra environment variables for this command."),
-    timeoutSeconds: z.number().int().positive().optional().describe("Per-command timeout in seconds; capped by the step deadline."),
+    timeoutSeconds: z.number().int().positive().optional().describe("Per-command timeout in seconds. Default 3600."),
 });
 /** 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"];
@@ -57,18 +57,21 @@ function scriptToken(command) {
     return command.find((arg) => SCRIPT_EXTENSIONS.some((extension) => arg.endsWith(extension)));
 }
 export function createExecuteCommandTool(deps) {
-    const { sandboxClient, sandbox, deadlineMs, defaultCwd, lineageCollector, mountRoot } = deps;
+    const { lease, defaultCwd, lineageCollector, mountRoot } = deps;
     return defineTool({
         id: "execute_command",
+        ownStep: true,
         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 ` +
             "of a longer stream is dropped, and the result carries its truncation flag. A long result comes back as an " +
             "excerpt of its start and its end, with a reference to read the rest when the harness keeps it. " +
             "Failures are returned as data, not thrown: `status` is `ok` whenever the call completed, so read " +
-            "`exitCode` for the outcome of the command. `timedOut: true` means the timeout stopped the command, and a " +
-            "`syntheticFailure` with `exitCode: null` means the sandbox died under the command (its reason names an " +
-            "out-of-memory kill). stdout and stderr are not a deliverable: they are ephemeral, " +
+            "`exitCode` for the outcome of the command. `timedOut: true` means the timeout stopped the command. A " +
+            "`syntheticFailure` with `exitCode: null` means the sandbox ended under the command: `sandbox-oom-killed` " +
+            "(the command passed `memoryLimitGb`), `sandbox-dead`, or `sandbox-replaced`. The command may have left " +
+            "partial files, and nothing runs it again. The next command runs on a new sandbox of the same size; call " +
+            "`acquire_sandbox` with a larger size for more memory. stdout and stderr are not a deliverable: they are ephemeral, " +
             "so use them to confirm that a command ran. A result that you compute with 'python -c' or an inline " +
             "one-liner and read from stdout is lost. Write a script and persist its outputs to output/.",
         inputSchema: ExecuteCommandInputSchema,
@@ -110,16 +113,17 @@ export function createExecuteCommandTool(deps) {
                         recordWrites.push(noted.write);
                 }
             }
-            const result = await runSandboxExec({
-                sandboxClient,
-                sandbox,
+            const ran = await runSandboxExec({
+                lease,
                 command,
                 cwd: effectiveCwd,
                 env,
                 timeoutSeconds,
-                deadlineMs: deadlineMs(),
                 emit: ctx.emit,
             });
+            if (ran.isErr())
+                return err(ran.error);
+            const result = ran.value;
             const bounded = { status: "ok", ...boundExecResult(result) };
             if ((!lineageCollector || !mountRoot) && recordWrites.length === 0)
                 return ok(bounded);

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

@@ -19,7 +19,7 @@ export function createFileStatTool(fs, workingDir) {
     return defineTool({
         id: "file_stat",
         description: "Stat a workspace path: whether it is a file or directory and its size " +
-            "in bytes. Use before reading to size a file. Missing and out-of-scope " +
+            "in bytes. It reads the workspace directly and runs no sandbox command. Use before reading to size a file. Missing and out-of-scope " +
             "paths return a data variant, not an error.",
         inputSchema: FileStatInputSchema,
         describeCall: "none",

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

@@ -8,7 +8,8 @@
  * `out_of_scope`. Only unexpected I/O failures throw.
  */
 import { z } from "zod";
-import { type Tool } from "../define-tool.js";
+import { type Tool, type WithToolCallRecord } from "../define-tool.js";
+import type { WorkspaceReadLineage, WorkspaceReadRecord } from "../../provenance/workspace-reads.js";
 import type { ListEntry, WorkspaceFilesystem } from "../../workspace/filesystem.js";
 declare const GrepInputSchema: z.ZodObject<{
     pattern: z.ZodString;
@@ -49,7 +50,9 @@ type GrepOutput = {
     pattern: string;
     matches: Match[];
 };
-export declare function createGrepTool(fs: WorkspaceFilesystem, workingDir?: string): Tool<z.infer<typeof GrepInputSchema>, GrepOutput>;
+type GrepToolOutput = GrepOutput | WithToolCallRecord<GrepOutput, WorkspaceReadRecord>;
+/** `lineage` records each file whose lines the result returns in the lineage of a step. */
+export declare function createGrepTool(fs: WorkspaceFilesystem, workingDir?: string, lineage?: WorkspaceReadLineage): Tool<z.infer<typeof GrepInputSchema>, GrepToolOutput>;
 /** Exposed for tests — the caps `grep` enforces. */
 export declare const GREP_LIMITS: {
     readonly DEFAULT_MAX_MATCHES: 50;

package/dist/tools/workspace/grep.js

@@ -14,7 +14,7 @@ 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 { defineTool, withToolCallRecord } from "../define-tool.js";
 import { unwrapOrThrow } from "../../lib/result.js";
 const DEFAULT_MAX_MATCHES = 50;
 const DEFAULT_MAX_MATCH_BYTES = 512;
@@ -33,11 +33,12 @@ const GrepInputSchema = z.object({
         .describe("Workspace path to a file or directory. Directories are searched " + "recursively up to a bounded depth."),
     ignoreCase: z.boolean().optional().describe("Case-insensitive match. Defaults to false."),
 });
-export function createGrepTool(fs, workingDir) {
+/** `lineage` records each file whose lines the result returns in the lineage of a step. */
+export function createGrepTool(fs, workingDir, lineage) {
     return defineTool({
         id: "grep",
         description: "Regex search over the text files of the workspace (input data, prior runs, step " +
-            "outputs, summaries, syntheses). Pass a file or a " +
+            "outputs, summaries, syntheses). It reads the workspace directly and runs no sandbox command. Pass a file or a " +
             `directory path; directories are walked recursively, to a depth of ${MAX_DIR_DEPTH}. Results are ` +
             `capped at ${DEFAULT_MAX_MATCHES} matches, and each preview at ${DEFAULT_MAX_MATCH_BYTES} characters of its line. ` +
             `Only the first ${MAX_GREP_FILE_BYTES / (1024 * 1024)} MiB of each file is searched, and a file with a NUL byte ` +
@@ -47,6 +48,7 @@ export function createGrepTool(fs, workingDir) {
         // Both fields, because either alone loses the call: the same pattern over
         // two trees and two patterns over one tree are both ordinary sequences.
         describeCall: ({ pattern, path }) => `${pattern} in ${path}`,
+        foldCallRecord: lineage === undefined ? undefined : (record) => lineage.track(record.reads),
         execute: async ({ pattern, path, ignoreCase }, ctx) => {
             let regex;
             try {
@@ -68,6 +70,7 @@ export function createGrepTool(fs, workingDir) {
                 return ok({ status: "not_found", path });
             }
             const matches = [];
+            const reads = [];
             let truncated = false;
             const session = ctx.session;
             async function searchFile(filePath) {
@@ -90,10 +93,11 @@ export function createGrepTool(fs, workingDir) {
                 if (read.kind === "truncated")
                     truncated = true;
                 const lines = splitLines(text);
+                const before = matches.length;
                 for (let i = 0; i < lines.length; i++) {
                     if (matches.length >= DEFAULT_MAX_MATCHES) {
                         truncated = true;
-                        return;
+                        break;
                     }
                     const line = presentAt(lines, i, "the scanned line");
                     if (regex.test(line)) {
@@ -104,6 +108,11 @@ export function createGrepTool(fs, workingDir) {
                         });
                     }
                 }
+                if (matches.length === before)
+                    return;
+                const noted = lineage?.readOf(filePath, read.kind === "ok" ? buf : null);
+                if (noted !== undefined)
+                    reads.push(noted);
             }
             async function walk(dirPath, depth) {
                 if (depth > MAX_DIR_DEPTH)
@@ -138,17 +147,17 @@ 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({
+            // oxlint-disable-next-line no-unnecessary-condition -- tsgolint cannot see the walk/searchFile closures that set truncated; the check is live (it selects the truncated result).
+            const output = truncated
+                ? {
                     status: "truncated",
                     path,
                     pattern,
                     matches,
                     cap: { maxMatches: DEFAULT_MAX_MATCHES, maxBytesPerLine: DEFAULT_MAX_MATCH_BYTES },
-                });
-            }
-            return ok({ status: "ok", path, pattern, matches });
+                }
+                : { status: "ok", path, pattern, matches };
+            return ok(reads.length === 0 ? output : withToolCallRecord(output, { reads }));
         },
     });
 }

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

@@ -19,9 +19,9 @@
  * 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).
+ * write prefix is the analysis root, less the staged inputs — 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
@@ -38,6 +38,7 @@ import type { AgentSession } from "../../auth/types.js";
 import type { Logger } from "../../lib/logger.js";
 import type { ProvenanceCollector } from "../../provenance/collector.js";
 import { type ProvenanceSeam } from "../../provenance/seam.js";
+import { type SyncSessionFile } from "../../workspace/session-files.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 = {
@@ -53,6 +54,10 @@ export type WriteFileResult = {
 } | {
     readonly status: "symlink_denied";
     readonly path: string;
+} | {
+    readonly status: "read_only";
+    readonly path: string;
+    readonly reason: string;
 };
 /**
  * What one landed write leaves for provenance: the hash and the size of the
@@ -136,6 +141,44 @@ export type WorkspaceMutator = {
      */
     recordWrite(record: WriteRecord): void;
 };
+/** Outcome of the hardened landing — the disk-touching half of a confined write. */
+type LandingStatus = "ok" | "out_of_prefix" | "symlink_denied" | "read_only";
+/** One landed confined write: the paths in both frames, and the exact bytes on disk. */
+export type ConfinedWriteOk = {
+    readonly status: "ok";
+    /** Analysis-root-relative, forward-slashed — the provenance-facing form. */
+    readonly relative: string;
+    /** The `/{analysisId}/…` frame-independent form — the agent-facing result path. */
+    readonly agentPath: string;
+    readonly bytes: Buffer;
+};
+/** A refused confined write: the status, and the reason when the status alone does not give it. */
+type ConfinedWriteRefusal = {
+    readonly status: Exclude<LandingStatus, "ok" | "read_only"> | "out_of_scope";
+} | {
+    readonly status: "read_only";
+    readonly reason: string;
+};
+/**
+ * The shared write gauntlet both realizations run: resolve + confine
+ * (`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. `beforeLand` gets
+ * the same ok while the bytes wait in the temporary file. With
+ * `refuseStagedInputs`, a write under the staged inputs is refused before any
+ * I/O, and the landing refuses a symlink that aims into them.
+ */
+export declare function confinedWrite(args: {
+    readonly workspaceRoot: string;
+    readonly analysisId: string;
+    readonly workingDir: string;
+    readonly path: string;
+    /** Text lands as UTF-8. */
+    readonly content: string | Uint8Array;
+    readonly invocationId: string;
+    readonly beforeLand: ((staged: ConfinedWriteOk) => Promise<void>) | undefined;
+    readonly refuseStagedInputs: boolean;
+}): Promise<ConfinedWriteRefusal | ConfinedWriteOk>;
 export declare function createWorkspaceMutator(deps: WorkspaceMutatorDeps): WorkspaceMutator;
 /** Construction deps of the session-scoped realization — see {@link createSessionWorkspaceMutator}. */
 export type SessionWorkspaceMutatorDeps = {
@@ -149,6 +192,8 @@ export type SessionWorkspaceMutatorDeps = {
      * proceeds unchanged.
      */
     readonly provenance?: ProvenanceSeam;
+    /** The host copy of each file that lands, owned by the analysis: the path is anywhere in its tree. */
+    readonly syncSessionFile?: SyncSessionFile;
     readonly logger?: Logger;
 };
 /**
@@ -158,10 +203,12 @@ export type SessionWorkspaceMutatorDeps = {
  * 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.
+ * the same gauntlet. The staged inputs are the one part of the tree that it
+ * cannot write: a write under them comes back `read_only`, with the reason.
  *
  * 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;
+export {};

package/dist/tools/workspace/mutator.js

@@ -19,9 +19,9 @@
  * 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).
+ * write prefix is the analysis root, less the staged inputs — 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
@@ -43,7 +43,8 @@ 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 { syncWrittenFile } from "../../workspace/session-files.js";
+import { resolveForWrite, STAGED_INPUT_ROOT } from "../../workspace/paths.js";
 /**
  * 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
@@ -51,6 +52,15 @@ import { resolveForWrite } from "../../workspace/paths.js";
  * inspecting its caller.
  */
 export const MUTATE_TOOL_NAMES = ["write_file", "edit_file", "knowledge_template", "execute_command"];
+/** The refusal of a write that lands under the staged inputs. */
+const STAGED_INPUT_REFUSAL = {
+    status: "read_only",
+    reason: `${STAGED_INPUT_ROOT}/ holds the staged inputs of the analysis, and they are immutable. Write the file to a different directory.`,
+};
+/** True when `path` is `dir` or a path under it. */
+function isWithin(dir, path) {
+    return path === dir || path.startsWith(dir + sep);
+}
 /**
  * Land `bytes` at `absolute`, hardened against a symlink re-aiming the write.
  * `absolute` is already lexically confined under `prefix` by the resolver;
@@ -70,12 +80,20 @@ export const MUTATE_TOOL_NAMES = ["write_file", "edit_file", "knowledge_template
  *      temporary file beside it and rename that file over it. The rename
  *      replaces a symlink raced in after the check, and never follows it.
  *
+ * `readOnlyDir` is a directory under `prefix` that takes no write. The landing
+ * refuses a canonical target under it as `read_only`, before the mkdir of
+ * step 3 and again before step 4. Thus a symlinked ancestor cannot aim a write
+ * into it.
+ *
  * Refusals are data; a genuine I/O failure throws (the loop's dispatch catch
  * maps it to an error tool result). A throw removes the temporary file.
  */
-async function landBytes(prefix, absolute, bytes, stagingKey, beforeRename) {
+async function landBytes(prefix, absolute, bytes, stagingKey, beforeRename, readOnlyDir) {
     unwrapOrThrow(await tryFsWrite("mutator.mkdirPrefix", () => mkdir(prefix, { recursive: true }), { path: prefix }));
     const realPrefix = unwrapOrThrow(await tryFs("mutator.realpathPrefix", () => realpath(prefix), { path: prefix }));
+    const realReadOnly = readOnlyDir === undefined
+        ? undefined
+        : (unwrapOrThrow(await tryFs("mutator.realpathReadOnly", () => realpath(readOnlyDir), { path: readOnlyDir, onAbsent: () => null })) ?? joinPath(realPrefix, relativePath(prefix, readOnlyDir)));
     // 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);
@@ -91,6 +109,8 @@ async function landBytes(prefix, absolute, bytes, stagingKey, beforeRename) {
     if (realDeepest !== realPrefix && !realDeepest.startsWith(realPrefix + sep))
         return "out_of_prefix";
     const targetDir = joinPath(realDeepest, relativePath(deepest, dirname(absolute)));
+    if (realReadOnly !== undefined && isWithin(realReadOnly, joinPath(targetDir, basename(absolute))))
+        return "read_only";
     let landingDir = realDeepest;
     if (targetDir !== realDeepest) {
         unwrapOrThrow(await tryFsWrite("mutator.mkdirParents", () => mkdir(targetDir, { recursive: true }), { path: targetDir }));
@@ -108,6 +128,8 @@ async function landBytes(prefix, absolute, bytes, stagingKey, beforeRename) {
         landingDir = realTarget;
     }
     const finalPath = joinPath(landingDir, basename(absolute));
+    if (realReadOnly !== undefined && isWithin(realReadOnly, finalPath))
+        return "read_only";
     const finalStat = unwrapOrThrow(await tryFs("mutator.lstatFinal", () => lstat(finalPath), { path: finalPath, onAbsent: () => null }));
     if (finalStat !== null && finalStat.isSymbolicLink())
         return "symlink_denied";
@@ -158,9 +180,11 @@ async function stageBytes(stagingPath, bytes, replacedMode) {
  * (`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. `beforeLand` gets
- * the same ok while the bytes wait in the temporary file.
+ * the same ok while the bytes wait in the temporary file. With
+ * `refuseStagedInputs`, a write under the staged inputs is refused before any
+ * I/O, and the landing refuses a symlink that aims into them.
  */
-async function confinedWrite(args) {
+export async function confinedWrite(args) {
     const scoped = resolveForWrite({
         workspaceRoot: args.workspaceRoot,
         analysisId: args.analysisId,
@@ -175,12 +199,17 @@ async function confinedWrite(args) {
     // 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("/");
+    if (args.refuseStagedInputs && (relative === STAGED_INPUT_ROOT || relative.startsWith(`${STAGED_INPUT_ROOT}/`)))
+        return STAGED_INPUT_REFUSAL;
     const agentPath = `/${args.analysisId}/${relative}`;
-    const bytes = Buffer.from(args.content, "utf8");
+    const bytes = typeof args.content === "string" ? Buffer.from(args.content, "utf8") : Buffer.from(args.content);
     const prefix = resolvePath(args.workingDir);
     const confined = { status: "ok", relative, agentPath, bytes };
     const { beforeLand } = args;
-    const landed = await landBytes(prefix, scoped.absolute, bytes, args.invocationId, beforeLand === undefined ? undefined : () => beforeLand(confined));
+    const readOnlyDir = args.refuseStagedInputs ? resolvePath(args.workspaceRoot, STAGED_INPUT_ROOT) : undefined;
+    const landed = await landBytes(prefix, scoped.absolute, bytes, args.invocationId, beforeLand === undefined ? undefined : () => beforeLand(confined), readOnlyDir);
+    if (landed === "read_only")
+        return STAGED_INPUT_REFUSAL;
     if (landed !== "ok")
         return { status: landed };
     return confined;
@@ -212,9 +241,10 @@ export function createWorkspaceMutator(deps) {
                 content,
                 invocationId,
                 beforeLand: beforeLand === undefined ? undefined : (staged) => beforeLand(landedWrite(staged)),
+                refuseStagedInputs: false,
             });
             if (landed.status !== "ok")
-                return { status: landed.status, path };
+                return { ...landed, path };
             return landedWrite(landed);
         },
         recordWrite(record) {
@@ -235,7 +265,8 @@ export function createWorkspaceMutator(deps) {
  * 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.
+ * the same gauntlet. The staged inputs are the one part of the tree that it
+ * cannot write: a write under them comes back `read_only`, with the reason.
  *
  * 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
@@ -271,10 +302,20 @@ export function createSessionWorkspaceMutator(deps) {
                 content,
                 invocationId,
                 beforeLand: beforeLand === undefined ? undefined : (staged) => beforeLand(landedWrite(staged)),
+                refuseStagedInputs: true,
             });
             if (landed.status !== "ok")
-                return { status: landed.status, path };
-            return landedWrite(landed);
+                return { ...landed, path };
+            const write = landedWrite(landed);
+            await syncWrittenFile(deps.syncSessionFile, logger, {
+                session,
+                owner: { kind: "analysis" },
+                path: write.record.path,
+                hash: write.record.hash,
+                size: write.record.size,
+                content: landed.bytes,
+            });
+            return write;
         },
         recordWrite(record) {
             const event = {

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

@@ -8,7 +8,8 @@
  * wraps them as `is_error`.
  */
 import { z } from "zod";
-import { type Tool } from "../define-tool.js";
+import { type Tool, type WithToolCallRecord } from "../define-tool.js";
+import type { WorkspaceReadLineage, WorkspaceReadRecord } from "../../provenance/workspace-reads.js";
 import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
 type ReadFileOutput = {
     status: "invalid_input";
@@ -43,5 +44,7 @@ declare const ReadFileInputSchema: z.ZodObject<{
     headLines: z.ZodOptional<z.ZodNumber>;
     tailLines: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
-export declare function createReadFileTool(fs: WorkspaceFilesystem, workingDir?: string): Tool<z.infer<typeof ReadFileInputSchema>, ReadFileOutput>;
+type ReadFileToolOutput = ReadFileOutput | WithToolCallRecord<ReadFileOutput, WorkspaceReadRecord>;
+/** `lineage` records each read that gave text to the agent in the lineage of a step. */
+export declare function createReadFileTool(fs: WorkspaceFilesystem, workingDir?: string, lineage?: WorkspaceReadLineage): Tool<z.infer<typeof ReadFileInputSchema>, ReadFileToolOutput>;
 export {};

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

@@ -9,7 +9,7 @@
  */
 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";
 /** Default cap — large enough for typical CSV/MD/JSON, small enough to keep tool results out of context-blowing territory. */
 const DEFAULT_MAX_BYTES = 256 * 1024;
@@ -49,11 +49,17 @@ const ReadFileInputSchema = z.object({
         .optional()
         .describe("Read only the last N complete lines (tail). Use for logs and any " + "file where the tail is what matters. Mutually exclusive with headLines."),
 });
-export function createReadFileTool(fs, workingDir) {
+/** `lineage` records each read that gave text to the agent in the lineage of a step. */
+export function createReadFileTool(fs, workingDir, lineage) {
+    /** The output, with the read of `path` as its call record when a lineage records it. */
+    function withRead(output, path, wholeFile) {
+        const read = lineage?.readOf(path, wholeFile);
+        return read === undefined ? output : withToolCallRecord(output, { reads: [read] });
+    }
     return defineTool({
         id: "read_file",
         description: "Read a workspace file: input data, prior-run outputs, current-run " +
-            "outputs, step summaries, or run syntheses. Returns the file content " +
+            "outputs, step summaries, or run syntheses. It reads the workspace directly and runs no sandbox command. Returns the file content " +
             "as UTF-8 text. Output is capped at " +
             `${DEFAULT_MAX_BYTES} bytes; pass headLines or tailLines to read a ` +
             "specific window of a large file (typical for bio CSV/TSV/log files). " +
@@ -70,6 +76,7 @@ export function createReadFileTool(fs, workingDir) {
                 return `${path} (last ${tailLines} lines)`;
             return path;
         },
+        foldCallRecord: lineage === undefined ? undefined : (record) => lineage.track(record.reads),
         execute: async ({ path, headLines, tailLines }, ctx) => {
             if (headLines !== undefined && tailLines !== undefined) {
                 return ok({
@@ -91,23 +98,20 @@ export function createReadFileTool(fs, workingDir) {
                 case "ok":
                     if (looksBinary(result.content))
                         return ok({ status: "binary", path, mode });
-                    return ok({
-                        status: "ok",
-                        path,
-                        mode,
-                        content: result.content.toString("utf8"),
-                    });
+                    return ok(withRead({ status: "ok", path, mode, content: result.content.toString("utf8") }, path, 
+                    // A line window is a part of the file, even when the window holds each line.
+                    mode === "full" ? result.content : null));
                 case "truncated":
                     if (looksBinary(result.content))
                         return ok({ status: "binary", path, mode, totalSize: result.totalSize });
-                    return ok({
+                    return ok(withRead({
                         status: "truncated",
                         path,
                         mode,
                         content: result.content.toString("utf8"),
                         totalSize: result.totalSize,
                         returnedBytes: result.content.length,
-                    });
+                    }, path, null));
                 case "not_found":
                     return ok({ status: "not_found", path });
                 case "out_of_scope":

package/dist/tools/workspace/read-surface.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The read-only surface of the workspace for an agent that plans or interprets the work of a run: the file reads,
+ * the semantic search, and the data profile. Each tool reads the tree of the analysis of its session, and no tool
+ * writes.
+ */
+import type { Querier } from "../../state/db.js";
+import type { EmbeddingProvider } from "../../providers/types.js";
+import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
+import type { Tool } from "../define-tool.js";
+import type { WorkspaceSearchQuerier } from "./workspace-search.js";
+export type ReadSurfaceDeps = {
+    readonly workspaceFs: WorkspaceFilesystem;
+    readonly pool: Querier & WorkspaceSearchQuerier;
+    /** Absent: the agent gets no `workspace_search`. */
+    readonly embedding?: EmbeddingProvider;
+};
+export declare function createReadSurfaceTools(deps: ReadSurfaceDeps): Tool[];

package/dist/tools/workspace/read-surface.js

@@ -0,0 +1,17 @@
+/**
+ * The read-only surface of the workspace for an agent that plans or interprets the work of a run: the file reads,
+ * the semantic search, and the data profile. Each tool reads the tree of the analysis of its session, and no tool
+ * writes.
+ */
+import { createInspectDataProfileTool } from "../research/inspect-data-profile.js";
+import { createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createWorkspaceSearchTool } from "./index.js";
+export function createReadSurfaceTools(deps) {
+    return [
+        createReadFileTool(deps.workspaceFs),
+        createListFilesTool(deps.workspaceFs),
+        createFileStatTool(deps.workspaceFs),
+        createGrepTool(deps.workspaceFs),
+        ...(deps.embedding ? [createWorkspaceSearchTool(deps.pool, deps.embedding)] : []),
+        createInspectDataProfileTool(deps.pool),
+    ];
+}