@inflexa-ai/harness 0.33.1 → 0.35.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.
@@ -19,7 +20,7 @@ import type { Pool } from "pg";
 import type { AgentDefinition } from "../../loop/types.js";
 import type { ChatProvider, EmbeddingProvider } from "../../providers/types.js";
 import type { SandboxClient } from "../../sandbox/client.js";
-import type { ExtendAnalysisFarm, SandboxRef, ToolchainSource } from "../../sandbox/types.js";
+import type { ExtendAnalysisFarm, SandboxRef } from "../../sandbox/types.js";
 import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
 import type { ProvenanceCollector as LineageCollector } from "../../provenance/collector.js";
 import { type BioToolKeys } from "../../tools/bio/keys.js";
@@ -90,12 +91,6 @@ export interface SandboxAgentDeps extends EnvironmentStorePaths {
      * and the package-link prompt layer appends. Without it, neither exists.
      */
     readonly extendAnalysisFarm?: ExtendAnalysisFarm;
-    /**
-     * The declared toolchain owner. Keys the orient-core environment text.
-     * Absent keeps the legacy text, thus an old embedder keeps its cached
-     * prompt prefix.
-     */
-    readonly toolchainSource?: ToolchainSource;
 }
 /** Per-agent override for the prompt composition and tool surface. */
 export interface SandboxAgentPromptOptions {

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 })];
@@ -189,10 +183,13 @@ function buildWorkspaceTools(deps, readOnly) {
 export function createSandboxAgent(deps, meta, body, opts = {}) {
     const appendStandards = opts.appendAnalysisStepStandards ?? true;
     // The layer order is fixed by the harness-sandbox-agents spec: the agent
-    // body, the orient core keyed on the declared toolchain, the package-link
-    // layer only when the seam is bound, then the step standards.
+    // body, the orient core keyed on the toolchain of the sandbox client, the
+    // package-link layer only when the seam is bound, then the step standards.
+    // The client is the one declaration: the environment it provisions and the
+    // text that describes it come from the same value, thus a bag cannot
+    // describe a toolchain the sandbox does not have.
     const sandboxLayer = [
-        sandboxOrientCorePromptFor(deps.toolchainSource),
+        sandboxOrientCorePromptFor(deps.sandboxClient.toolchainSource),
         ...(deps.extendAnalysisFarm ? [sandboxPackageLinkPrompt] : []),
         ...(appendStandards ? [sandboxAnalysisStepStandardsPrompt] : []),
     ];

package/dist/config/environment-stores.d.ts

@@ -45,11 +45,14 @@ export interface EnvironmentStorePaths {
      */
     readonly farmLockFile?: string;
     /**
-     * Host path of the baked image inventory fragment
-     * (`image-packages.txt`) — the image-owned tools that
-     * `list_available_packages` merges into its report. Omit when the host
-     * cannot read one; a missing fragment merges nothing, and that is a
-     * normal state.
+     * Host path of the image inventory record, `image-packages.json` at the
+     * root of the package store — the image-owned tools and Node packages
+     * that `list_available_packages` merges into its report. Omit when the
+     * host's own process sees the store at the container mountpoint, which
+     * makes `/mnt/libs/image-packages.json` correct as-is; set it when the
+     * host reads the store somewhere else. An absent or invalid record
+     * merges nothing, and that is a normal state: a store packed before the
+     * record existed carries none, and the rest of the report stays whole.
      */
     readonly imagePackagesFile?: string;
     /**
@@ -81,7 +84,7 @@ export type PoolInventoryRead = {
 /** One package entry of an inventory section, with the store identity where the source records it. */
 export interface PoolInventoryPackage {
     readonly name: string;
-    /** The pinned version, rendered as `name==version`. Absent for an image-fragment tool. */
+    /** The pinned version, rendered as `name==version`. Absent where the source pins none. */
     readonly version?: string;
     /** The content-addressed store directory of the package. */
     readonly storeDir?: string;

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/index.d.ts

@@ -134,9 +134,12 @@ export type { ResolveWorkspaceRoot } from "./workspace/paths.js";
 export { createSandboxClient } from "./sandbox/create-sandbox.js";
 export type { CreateSandboxClientConfig, SandboxBackendConfig } from "./sandbox/create-sandbox.js";
 export type { SandboxClient } from "./sandbox/client.js";
+export { describeSandboxError, SandboxFailure } from "./sandbox/sandbox-error.js";
+export type { SandboxError } from "./sandbox/sandbox-error.js";
 export type { ExtendAnalysisFarm, FarmLocation, FarmResolution, FarmSource, PackageRequest, PackageRequestOutcome, ResolveAnalysisFarm, ToolchainSource, } from "./sandbox/types.js";
 export { FARM_LOCK_FILE, FarmLockSchema, readFarmLock, readFarmLockFile } from "./sandbox/farm.js";
 export type { FarmLock, FarmLockError } from "./sandbox/farm.js";
+export { IMAGE_PACKAGES_FILE } from "./sandbox/image-packages.js";
 export type { EnvironmentStorePaths, PoolInventoryPackage, PoolInventoryRead, PoolInventorySection } from "./config/environment-stores.js";
 export { MachineBudgetSchema, ResourceLimitsSchema, ResourcePolicySchema, ResourceSpecSchema, parseResourcePolicy } from "./config/resource-limits.js";
 export type { MachineBudget, ResourceLimits, ResourcePolicy, ResourceSpec } from "./config/resource-limits.js";

package/dist/index.js

@@ -237,9 +237,15 @@ export { createAnalysisPurge } from "./state/purge-analysis.js";
 // the failure a fixed-width comparand exists to prevent.
 export { computeInputSignature } from "./execution/input-signature.js";
 export { createSandboxClient } from "./sandbox/create-sandbox.js";
+// The throw of the client seam. An embedder matches the class and reads the
+// typed variant on `error`, instead of a string match on the message.
+export { describeSandboxError, SandboxFailure } from "./sandbox/sandbox-error.js";
 // The farm contract: one `inflexa.lock` per farm. An embedder that composes
 // farms writes this shape, and the mount gate reads it — one schema, no copy.
 export { FARM_LOCK_FILE, FarmLockSchema, readFarmLock, readFarmLockFile } from "./sandbox/farm.js";
+// The image record: one file name at the root of the store. An embedder joins
+// it onto its own store root for `imagePackagesFile`.
+export { IMAGE_PACKAGES_FILE } from "./sandbox/image-packages.js";
 export { MachineBudgetSchema, ResourceLimitsSchema, ResourcePolicySchema, ResourceSpecSchema, parseResourcePolicy } from "./config/resource-limits.js";
 export { createWorkspaceFilesystem } from "./workspace/filesystem.js";
 // Exec-callback ingress building blocks. Delivery goes through

package/dist/prompts/sandbox-standards.d.ts

@@ -22,20 +22,20 @@
  * `prompts/briefing.ts`), which is composed per dispatch and where per-step
  * content belongs.
  *
- * The orient-core text keys on the declared `toolchainSource`
- * (`sandboxOrientCorePromptFor`). The absent field gives the legacy constant
- * untouched, thus an old embedder keeps its cached prefix byte-identical.
- * Both variants are composition-time constants, thus each composition stays
- * byte-stable across its own steps.
+ * The orient-core text keys on the `toolchainSource` of the sandbox client
+ * (`sandboxOrientCorePromptFor`). `"store"` gives the legacy constant
+ * untouched, thus an embedder that declares no toolchain keeps its cached
+ * prefix byte-identical. Both variants are composition-time constants, thus
+ * each composition stays byte-stable across its own steps.
  */
 import type { ToolchainSource } from "../sandbox/types.js";
 export declare const sandboxOrientCorePrompt = "# Sandbox Orient-Core\n\nThese apply to every agent that talks to a sandbox.\n\n## Your Briefing Is Authoritative\n\nYour first message is your briefing, composed for this step at the instant it was\ndispatched \u2014 after every step it depends on had finished. It names your task, your\nworking directory and the read-only analysis root, what the input dataset is\n(domain, organism, design, quality concerns, files), and what each upstream step\nproduced and where it put it. Work from it.\n\nDo NOT re-derive what it already gives you: no filesystem hunt for your inputs, no\nre-reading an upstream step whose summary you were handed, no re-deriving the\norganism or the dimensions from raw bytes. Reach further only where the briefing is\ngenuinely thin for what you must do:\n\n- `inspect_data_profile` \u2014 the full dataset profile: `scope:'overview'` for the\n  identity and the file census, `scope:'groups'` for the groups and the dimensions\n  that vary across them, `scope:'files'` for the members the profiler annotated\n  individually. It is the ONLY record of what the input data IS; no file on disk\n  carries it. Use it when the briefing's orientation is not enough, or when it\n  carried none.\n- `read_file` on an upstream step's summary \u2014 its path is in your briefing \u2014 when\n  the excerpt you were handed is not enough to build on.\n- `workspace_search({ query })` \u2014 natural-language search for a file the briefing\n  does not name. Optional `type` filter (`input-group` | `input-dimension` |\n  `input` | `output` | `summary` | `synthesis`) and `limit` (1-50, default 8).\n  Returns paths, descriptions, and metadata \u2014 not file contents. Most input files\n  carry no entry of their own; reach them through their group and `list_files`.\n\n## Your Workspace\n\nYour **working directory** \u2014 writable, and your cwd \u2014 and the read-only\n**analysis root** are named in your briefing. Use those paths exactly; do not\ninvent or guess one.\n\n- **Relative paths resolve against your working directory** \u2014 in `read_file`,\n  `list_files`, `file_stat`, `grep`, `write_file`, `edit_file`,\n  `execute_command`, and any script you run. `output/de.csv` means\n  `<working directory>/output/de.csv` everywhere \u2014 a file you write at a\n  relative path is read back at the same relative path.\n- **You may write only inside your working directory.** A write outside it\n  comes back as an `out_of_prefix` result (no I/O performed); fix the path.\n- The rest of the analysis is mounted **read-only** at the analysis root. Reach\n  input data (under `data/inputs/`) and other steps' outputs (under `runs/`)\n  with an **absolute** path beneath it.\n- **Absolute analysis-root paths are canonical** \u2014 use one whenever you\n  reference a file you didn't create in this step.\n\n`write_file` creates parent directories as needed \u2014 no separate mkdir.\n\n## Scope \u2014 Analysis Starts at Processed Data\n\nThis environment does **tertiary analysis**: turning processed data into\nbiological findings. Read processing \u2014 alignment, quantification, variant\ncalling, peak calling \u2014 belongs upstream, wherever the instrument output was\nhandled. No tool for it is installed, and none can be.\n\nYour inputs are count and expression matrices, called variants, peak sets,\nsignal tracks, and the metadata describing them. When a request arrives as raw\nreads or unprocessed instrument output, name the processed form you need and\nstop. Do not improvise a pipeline, do not substitute a Python reimplementation\nof an aligner or peak caller, and do not treat a missing upstream tool as an\nobstacle to route around \u2014 it is the boundary of the product, not a gap.\n\nData that has already been processed can still be **read**: `samtools`,\n`bcftools`, `tabix`, `bedtools` and `vcftools` are installed so you can\ninspect, subset, and convert existing BAM/CRAM, VCF and BED. Reading evidence at\nsites you already have is in scope; producing the calls is not.\n\n## Environment \u2014 No Network, No Installs\n\n**There is no egress from this sandbox.** Outbound connections are blocked at the\nfirewall, not merely discouraged: every download, API call, package install, and\n`ExperimentHub`/`AnnotationHub`/`models.download_*` style fetch fails outright.\nThere is no proxy, no mirror, and no retry that succeeds. Packages and reference\ndata were staged onto read-only mounts by the host **before** this container\nstarted, and that is the whole of what exists. Work that genuinely requires the\ninternet \u2014 fetching a dataset, querying an external API, literature lookup \u2014 is\ndone **outside** the sandbox through the host's tools, not from your scripts.\n\nSo: check what you need when you need it \u2014 a targeted lookup, never a catalog dump\nup front.\n\n- **Packages** \u2014 before importing a package you are not certain is present, look it\n  up with `list_available_packages`, narrowed to the packages you actually intend\n  to import. Importing one that isn't installed fails the script; the lookup costs\n  one call.\n- **Reference data** \u2014 `list_available_refs` resolves reference data into a real\n  path against the store mounted read-only at `/mnt/refs`. **Search by what the\n  data IS, not by where you expect it** (\"TF-target regulons\", \"hallmark gene\n  sets\", \"mouse\"): the store's directory layout is an installer detail, it differs\n  between hosts, and no path you have seen before is guaranteed to exist here.\n  Catalogued entries come back with the organism, the format, and the file's\n  internal shape, so read the entry and use the reader and species it names rather\n  than assuming \u2014 formats vary per dataset, and there is no guarantee any given\n  collection ships in the format your tool prefers.\n  The store is OPTIONAL and may be absent or hold none of what you want \u2014 a normal\n  state, not an error. Never assume a reference path exists and never hardcode one:\n  if a reference you need is not in the inventory, say so plainly and proceed with\n  what you do have (or state what must be provisioned) rather than inventing a path\n  or substituting something else unannounced. Pass reference paths EXPLICITLY to the\n  library \u2014 nothing in the image points a library at the store, so a library that\n  resolves data by name from an env var (CellTypist reads `$CELLTYPIST_FOLDER`)\n  will not find it unless you export that variable yourself, in the same command,\n  using a path the inventory actually returned.\n- Do NOT call a library's built-in data fetcher \u2014 `dc.op.collectri()`,\n  `dc.op.progeny()`, `dc.op.msigdb()` and every other `dc.op.*()`, CellTypist's\n  `models.download_models()`, gseapy's Enrichr library names, `ExperimentHub`/\n  `AnnotationHub` \u2014 they all reach for the network and will fail. Load from an\n  inventory path instead. Do NOT download data or install packages at runtime.\n\n## CPU Budget and Parallelism\n\nYour briefing names this step's CPU quota and memory limit. The container's\ncore-count calls (`parallel::detectCores()`, `os.cpu_count()`) report the\nquota, so worker counts sized from them are safe.\n\nBLAS/OpenMP thread pools default to **1 thread** (`OMP_NUM_THREADS`,\n`OPENBLAS_NUM_THREADS`, `MKL_NUM_THREADS`, \u2026). A forked worker inherits its\nparent's pool size, so this default is what keeps `mclapply` /\n`multiprocessing` from running workers \u00D7 threads on a quota sized for one of\nthem. The rule: **workers \u00D7 threads-per-worker must not exceed the quota.** A\nmix is fine while the product stays inside it.\n\n- **Fork/worker parallelism** (`mclapply`, `BiocParallel`, `joblib`,\n  `multiprocessing`): size the workers from the reported core count and leave\n  the thread defaults alone \u2014 there is nothing to raise. `joblib` also\n  divides its own thread budget across its workers; do not manage it.\n- **Thread parallelism** (one process: xgboost, WGCNA, data.table, polars, a\n  single large BLAS fit): raise the thread variables for that command through\n  `execute_command`'s `env`, e.g.\n  `env: { \"OMP_NUM_THREADS\": \"4\", \"OPENBLAS_NUM_THREADS\": \"4\" }` on a 4-CPU\n  quota.\n\nExceeding the quota does not kill the step \u2014 the cgroup throttles it \u2014 but an\noversubscribed step runs slower and can starve the exec server that runs your\ncommands.\n\n## Output Contract \u2014 Persisted Files Are the Deliverable\n\nThis is a hard requirement, not a convention. **Your deliverable is persisted\nfiles**, nothing else:\n\n- the **script** you wrote, in `scripts/`,\n- the **data it computed** (derived from the input data), in `output/`,\n- any **figures**, in `figures/`.\n\nConclusions are drawn from those computed output files \u2014 never narrated from\n`execute_command` stdout. stdout/stderr are ephemeral; they are gone the\nmoment the command returns. **A step that ends without persisted\nscripts + outputs has produced nothing**, even if its transcript reads as if\nwork was done. In particular: running the analysis as an inline `python -c` /\n`Rscript -e` one-liner and reporting the numbers it printed produces nothing \u2014\nwrite the script to `scripts/` and persist what it computes to `output/`.\n\nA genuine verdict / QC / decision step that has no tabular result may instead\nwrite a short Markdown memo to `output/` (e.g. `output/qc-verdict.md`) stating\nthe finding and the evidence it rests on \u2014 a real persisted artifact. Do not\nfabricate a CSV just to have one.\n\nIf you genuinely cannot fulfill the step \u2014 required input data is missing, a\ntool you need is unavailable, or the environment is broken \u2014 call\n`report_blocker({ reason })` with a clear, specific reason. Do NOT improvise an\ninline result, fabricate outputs, or end on a prose narrative pretending the\nwork was done. `report_blocker` is the honest exit; an empty step that claims\nsuccess is not.\n\n## Skills \u2014 Method Selection and API Details\n\nSkills hold the full decision trees, API references, contrast syntax, worked\nexamples, and domain anti-patterns that do not fit in prompts. Use them\nactively \u2014 they are your authoritative source on methods.\n\n- `skill_search(query)` \u2014 keyword search across the skills available to you.\n  Start here when picking a method or verifying an API detail. Examples:\n  `skill_search(\"PyDESeq2 contrast syntax\")`,\n  `skill_search(\"Leiden clustering resolution\")`.\n- `skill_read(skill, path)` \u2014 read a file from one of your skills, e.g.\n  `skill_read(\"bulk-transcriptomics\", \"SKILL.md\")` or\n  `skill_read(\"bulk-transcriptomics\", \"references/pydeseq2-api.md\")`.\n\nThe skills you have access to are listed in your agent instructions.\n\n## Context7 \u2014 Documentation Lookup\n\nLook up current documentation via context7 before writing non-trivial code:\n1. `resolve_library_id` with the package name to get the library ID.\n2. `query_docs` with the library ID and the specific function or method.\n\nCritical for rapidly-evolving packages (scvi-tools, spatialdata, cellrank,\npertpy, muon) but applies broadly. Do NOT guess API details from memory \u2014\nverify with context7 or skill references first.\n\n## Command Execution\n\n`execute_command` runs analysis work \u2014 scripts, bioinformatics CLI tools,\nshell pipes, and anything the workspace tools don't express. It starts in your\nworking directory; a relative `cwd` argument is resolved against it.\n\nFor these tasks, prefer the dedicated workspace tools \u2014 they are faster than\nshelling out and don't waste a turn on path discovery:\n\n| Task                            | Use this tool   | Instead of                 |\n|-|-|-|\n| List files in a directory       | `list_files`    | `ls` / `ls -la` / `find -name` |\n| Read a text/source/result file  | `read_file`     | `cat` / `less`             |\n| Search file contents by pattern | `grep`          | shell `grep` / `rg`        |\n| Size / type of a path           | `file_stat`     | `stat` / `wc -c`           |\n\n**Use `execute_command` for everything else**, including:\n\n- **Running scripts** \u2014 `python scripts/run.py`, `Rscript scripts/de.R`,\n  `ruff check scripts/foo.py`.\n- **Previewing huge / binary files** \u2014 `wc -l file.tsv`, `zcat file.gz | head`.\n  For text files, prefer `read_file` with `headLines` / `tailLines`.\n- **Shell pipes / chaining** \u2014 `sort | uniq -c | sort -rn | head`.\n- **`find` with non-name predicates** \u2014 `find . -mtime -1`, `find . -size +10M`.\n- **Real CLI tools** \u2014 `samtools`, `bcftools`, `tabix`, `bedtools`,\n  `vcftools`, version probes like `python -c \"import x; print(x.__version__)\"`.\n\n**Shell behavior to know:**\n\n- `cd` does NOT persist across calls \u2014 each exec starts in your working\n  directory. For cross-call state, pass `cwd` or chain with `&&` in one exec.\n- Quote paths with spaces: `head \"data/inputs/My Folder/file.csv\"`. In Python,\n  use `pathlib.Path` or `os.path`.\n\n## Editing Files\n\n`edit_file` replaces `old_string` with `new_string`. Read the file first to\nget the exact text. When `replace_all` is false (default), `old_string` must\noccur exactly once \u2014 include surrounding context to make it unique.\n";
 /**
  * The orient-core layer for one declared toolchain. `"image"` states that an
  * acquisition is a host action and directs the agent to report a missing
- * package. The absent field gives the legacy constant untouched.
+ * package. `"store"` gives the legacy constant untouched.
  */
-export declare function sandboxOrientCorePromptFor(toolchainSource: ToolchainSource | undefined): string;
+export declare function sandboxOrientCorePromptFor(toolchainSource: ToolchainSource): string;
 /**
  * The package-link layer — appended to the sandbox system prompt only when
  * the embedder binds the `ExtendAnalysisFarm` seam. A composition-time

package/dist/prompts/sandbox-standards.js

@@ -22,11 +22,11 @@
  * `prompts/briefing.ts`), which is composed per dispatch and where per-step
  * content belongs.
  *
- * The orient-core text keys on the declared `toolchainSource`
- * (`sandboxOrientCorePromptFor`). The absent field gives the legacy constant
- * untouched, thus an old embedder keeps its cached prefix byte-identical.
- * Both variants are composition-time constants, thus each composition stays
- * byte-stable across its own steps.
+ * The orient-core text keys on the `toolchainSource` of the sandbox client
+ * (`sandboxOrientCorePromptFor`). `"store"` gives the legacy constant
+ * untouched, thus an embedder that declares no toolchain keeps its cached
+ * prefix byte-identical. Both variants are composition-time constants, thus
+ * each composition stays byte-stable across its own steps.
  */
 export const sandboxOrientCorePrompt = `# Sandbox Orient-Core
 
@@ -291,7 +291,7 @@ sandbox.`), `- **Packages** — before importing a package you are not certain i
 /**
  * The orient-core layer for one declared toolchain. `"image"` states that an
  * acquisition is a host action and directs the agent to report a missing
- * package. The absent field gives the legacy constant untouched.
+ * package. `"store"` gives the legacy constant untouched.
  */
 export function sandboxOrientCorePromptFor(toolchainSource) {
     return toolchainSource === "image" ? imageToolchainOrientCorePrompt : sandboxOrientCorePrompt;

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/sandbox/client.d.ts

@@ -25,8 +25,17 @@
  * `tasks/derive-table-exec.ts` are the two worked examples. No type carries this
  * rule yet, thus a new caller must read this paragraph.
  */
-import type { CreateSandboxMeta, ExecEmit, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SubmitExecBody } from "./types.js";
+import type { CreateSandboxMeta, ExecEmit, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SubmitExecBody, ToolchainSource } from "./types.js";
 export interface SandboxClient {
+    /**
+     * The declared owner of the sandbox toolchain, as the client was composed
+     * with it: `"image"` when the config declared it, `"store"` when the config
+     * declared nothing. The mount plan and the orient-core prompt both key on
+     * this one value, thus the environment a sandbox gets and the text that
+     * describes it cannot disagree. Required rather than optional, because an
+     * optional field would carry two meanings, undeclared and unknown.
+     */
+    readonly toolchainSource: ToolchainSource;
     /**
      * DBOS step (`sandbox.create`) — the spawn half of the two-step create
      * (see the harness-sandbox-exec spec). Launches the sandbox-base container/Job under the

package/dist/sandbox/create-sandbox.d.ts

@@ -80,6 +80,18 @@ export interface CreateSandboxClientConfig {
      * this field existed.
      */
     toolchainSource?: ToolchainSource;
+    /**
+     * The deployment cannot run an analysis without the package store. Under
+     * the fact, a farm that fails the `inflexa.lock` gate refuses the create
+     * with `farm_unusable`, and neither backend makes a machine. Absent keeps
+     * the degrade: the store mounts drop, a warning is logged, and the
+     * sandbox reports the store as unavailable. The field names the
+     * deployment fact rather than the remediation, so how the harness answers
+     * it can evolve without changing the embedder surface; a single-valued
+     * union (not a boolean) so future store classes extend it without a
+     * breaking change.
+     */
+    packageStore?: "required";
     /** Docker: host dir bind-mounted read-only at `/mnt/refs`. */
     refStorePath?: string;
     /** Docker: force the container platform (e.g. `linux/amd64`) so the sandbox matches the mounted lib store's arch. */