@inflexa-ai/harness 0.7.0 → 0.7.2

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

@@ -38,6 +38,7 @@ import type { Tool } from "../tools/define-tool.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type BioToolKeys } from "../tools/bio/keys.js";
+import type { EnvironmentStorePaths } from "../config/environment-stores.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { RunLauncher } from "../execution/run-launcher.js";
 import { type SubmitReportDeps } from "../tools/iterate-report.js";
@@ -45,8 +46,13 @@ import type { EphemeralWorkflowInput, EphemeralResult } from "../execution/ephem
 import type { Logger } from "../lib/logger.js";
 /** Canonical agent id — the single source of truth. */
 export declare const CONVERSATION_AGENT_ID: "conversation-agent";
-/** The shared dependencies the composition root explodes apart. */
-export interface ConversationAgentDeps {
+/**
+ * The shared dependencies the composition root explodes apart. The environment
+ * store paths give this agent and its planner the same view of what is staged and
+ * what is importable that a sandbox agent has — read host-side, so answering
+ * "does this environment have X?" costs a lookup rather than a container.
+ */
+export interface ConversationAgentDeps extends EnvironmentStorePaths {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     /** The LLM seam every loop-driving tool runs its sub-agent on. */
@@ -112,13 +118,6 @@ export interface ConversationAgentDeps {
      * built-in tool.
      */
     readonly hostTools?: readonly Tool[];
-    /**
-     * Host path of the reference store — the same bytes sandboxes mount at
-     * `/mnt/refs`. Gives `generate_plan` reference discovery, so a plan can be
-     * grounded in what this environment actually holds. Omit when no store is
-     * provisioned.
-     */
-    readonly refStorePath?: string;
 }
 /** Build the conversation `AgentDefinition` with every tool fully dep-bound. */
 export declare function createConversationAgent(deps: ConversationAgentDeps): AgentDefinition;

package/dist/agents/conversation-agent.js

@@ -39,6 +39,7 @@ import { createGeneratePlanTool, createLiteratureReviewerTool, createInspectRunT
 import { createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createShowPlanTool, createWorkspaceSearchTool, 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";
 import { createListAvailableRefsTool } from "../tools/sandbox/list-available-refs.js";
 import { createExecutePlanTool } from "../tools/execute-plan.js";
 import { createRunEphemeralTool } from "../tools/run-ephemeral.js";
@@ -49,7 +50,7 @@ export const CONVERSATION_AGENT_ID = "conversation-agent";
 const CONVERSATION_MAX_ITERATIONS = 50;
 /** Build the conversation `AgentDefinition` with every tool fully dep-bound. */
 export function createConversationAgent(deps) {
-    const { provider, pool, embedding, workspaceFs, model, executeAnalysisWorkflow, ephemeralWorkflow, resolveWorkspaceRoot, runAuthorizer, runLauncher, createPreviewPublisher, bioKeys, templatesDir, skillsDir, chrome, resourcePolicy, hostTools, refStorePath, } = deps;
+    const { provider, pool, embedding, workspaceFs, model, executeAnalysisWorkflow, ephemeralWorkflow, resolveWorkspaceRoot, runAuthorizer, runLauncher, createPreviewPublisher, bioKeys, templatesDir, skillsDir, chrome, resourcePolicy, hostTools, refStorePath, packagesFile, } = deps;
     const workingMemory = createWorkingMemory(pool);
     const ncbi = createNcbiTools(bioKeys);
     const chemDb = createChemDbTools(bioKeys);
@@ -85,11 +86,15 @@ export function createConversationAgent(deps) {
         // blind is how a user gets asked to download something already installed, or
         // told nothing is missing when it is; this is the only tool that can tell.
         createListAvailableRefsTool({ ...(refStorePath ? { refStorePath } : {}) }),
+        // What is importable inside a sandbox. Reads the same manifest a sandbox agent
+        // reads, host-side — so "is scanpy available?" is a manifest lookup here rather
+        // than a whole ephemeral container spun up to run one import.
+        createListAvailablePackagesTool({ ...(packagesFile ? { packagesFile } : {}) }),
         // Execution.
         createInspectRunTool(pool),
         // The dataset's own record. No file backs it — the DB row is the only copy.
         createInspectDataProfileTool(pool),
-        createGeneratePlanTool({ provider, pool, model, resourcePolicy, ...(refStorePath ? { refStorePath } : {}) }),
+        createGeneratePlanTool({ provider, pool, model, resourcePolicy, ...(refStorePath ? { refStorePath } : {}), ...(packagesFile ? { packagesFile } : {}) }),
         createExecutePlanTool({
             pool,
             executeAnalysisWorkflow,

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

@@ -25,6 +25,7 @@ import type { ProvenanceCollector as LineageCollector } from "../../provenance/c
 import { type BioToolKeys } from "../../tools/bio/keys.js";
 import { type BlockerHolder } from "../../tools/sandbox/report-blocker.js";
 import type { AgentMeta, SandboxToolName } from "./types.js";
+import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
 import type { Logger } from "../../lib/logger.js";
 /**
  * Tools every sandbox agent receives — sandbox-environment introspection,
@@ -50,7 +51,7 @@ export interface SandboxStepCoords {
     readonly deadlineMs: () => number;
 }
 /** The shared dependency graph every sandbox agent draws from. */
-export interface SandboxAgentDeps {
+export interface SandboxAgentDeps extends EnvironmentStorePaths {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     readonly provider: ChatProvider;
@@ -69,18 +70,6 @@ export interface SandboxAgentDeps {
     readonly model: string;
     /** Absolute path to the skills tree. Omit to skip the skill tools. */
     readonly skillsDir?: string;
-    /**
-     * Host path of the reference store — the same bytes the sandbox mounts at
-     * `/mnt/refs`. Omit when no store is provisioned; reference discovery then
-     * reports the store as unavailable rather than failing.
-     */
-    readonly refStorePath?: string;
-    /**
-     * Host path of the library store's `packages.txt`. Omit when the host mounts
-     * the store at the sandbox's own path; a host whose store is baked into the
-     * image must inject its extracted copy, or the inventory reads as unknown.
-     */
-    readonly packagesFile?: string;
     /** Per-step coordinates resolved at the workflow body. */
     readonly step: SandboxStepCoords;
     /** API keys for the external bio/chem data sources. */

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

@@ -0,0 +1,42 @@
+/**
+ * The two host paths that describe what an analysis environment can actually do:
+ * the reference data staged for it, and the packages installed in its sandbox.
+ *
+ * They are declared once, here, because every agent-facing deps bag that carries
+ * them means the same thing by them — and when each bag documented them itself,
+ * the prose drifted per site (the same field explained in terms of "the executor",
+ * "the profiler", "the planner") while the contract stayed identical. Extending
+ * this interface keeps one description of a field that has one meaning.
+ */
+/**
+ * Host paths of the environment's two read-only stores.
+ *
+ * Both are HOST paths, deliberately: reading them host-side is what lets the
+ * conversation agent and the planner answer "what does this environment hold?"
+ * before any sandbox exists, and they are the same bytes a sandbox agent sees
+ * through its mounts — so every agent gets one answer rather than a per-vantage
+ * one. Neither store is ever written through these paths.
+ *
+ * Both are optional, and absence is a NORMAL state rather than an error: an
+ * omitted path makes its tool report the store as unavailable or unknown, which
+ * is a truthful answer an agent can act on. Absence must never be reported as a
+ * failure, and never papered over with a guessed path.
+ */
+export interface EnvironmentStorePaths {
+    /**
+     * Host path of the reference store — the same bytes sandboxes mount at
+     * `/mnt/refs`. Omit when no store is provisioned; reference discovery then
+     * reports the store as unavailable. Note that an installed store reads as
+     * absent if this is omitted, which is indistinguishable to an agent from
+     * having no data — so omit it only when there is genuinely nothing staged.
+     */
+    readonly refStorePath?: string;
+    /**
+     * Host path of the library store's `packages.txt` — the inventory of what is
+     * importable inside a sandbox. Omit when the host mounts the store at the
+     * sandbox's own path, which makes the container path correct as-is; a host
+     * whose store is baked into the image and never bind-mounted must inject the
+     * path to its own extracted copy, or the inventory reads as unknown.
+     */
+    readonly packagesFile?: string;
+}

package/dist/config/environment-stores.js

@@ -0,0 +1,11 @@
+/**
+ * The two host paths that describe what an analysis environment can actually do:
+ * the reference data staged for it, and the packages installed in its sandbox.
+ *
+ * They are declared once, here, because every agent-facing deps bag that carries
+ * them means the same thing by them — and when each bag documented them itself,
+ * the prose drifted per site (the same field explained in terms of "the executor",
+ * "the profiler", "the planner") while the contract stayed identical. Extending
+ * this interface keeps one description of a field that has one meaning.
+ */
+export {};

package/dist/contracts/chat-parts.d.ts

@@ -105,8 +105,10 @@ export interface RunStartedPart {
     stepCount: number;
 }
 /** `"pending"` = waiting on dependencies; `"queued"` = dependencies satisfied,
- *  held until in-flight steps free machine-budget capacity. */
-export type StepStatus = "pending" | "queued" | "running" | "completed" | "failed";
+ *  held until in-flight steps free machine-budget capacity; `"skipped"` =
+ *  unreachable — an upstream dependency failed or blocked, so the step can
+ *  never be dispatched. */
+export type StepStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
 export interface DagStepState {
     id: string;
     name: string;

package/dist/contracts/schemas/chat-parts.d.ts

@@ -135,6 +135,8 @@ export declare const StepStatusSchema: z.ZodEnum<{
     running: "running";
     completed: "completed";
     failed: "failed";
+    skipped: "skipped";
+    queued: "queued";
 }>;
 export declare const DagStepStateSchema: z.ZodObject<{
     id: z.ZodString;
@@ -145,6 +147,8 @@ export declare const DagStepStateSchema: z.ZodObject<{
         running: "running";
         completed: "completed";
         failed: "failed";
+        skipped: "skipped";
+        queued: "queued";
     }>;
     level: z.ZodNumber;
     dependsOn: z.ZodArray<z.ZodString>;
@@ -166,6 +170,8 @@ export declare const DagStatePartSchema: z.ZodObject<{
             running: "running";
             completed: "completed";
             failed: "failed";
+            skipped: "skipped";
+            queued: "queued";
         }>;
         level: z.ZodNumber;
         dependsOn: z.ZodArray<z.ZodString>;
@@ -530,6 +536,8 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
             running: "running";
             completed: "completed";
             failed: "failed";
+            skipped: "skipped";
+            queued: "queued";
         }>;
         level: z.ZodNumber;
         dependsOn: z.ZodArray<z.ZodString>;

package/dist/contracts/schemas/chat-parts.js

@@ -96,7 +96,7 @@ export const RunStartedPartSchema = z.object({
     stepCount: z.number(),
 });
 // ── DAG State ───────────────────────────────────────────────────────
-export const StepStatusSchema = z.enum(["pending", "running", "completed", "failed"]);
+export const StepStatusSchema = z.enum(["pending", "queued", "running", "completed", "failed", "skipped"]);
 export const DagStepStateSchema = z
     .object({
     id: z.string(),

package/dist/execution/ephemeral-runner.d.ts

@@ -23,6 +23,7 @@
  */
 import type { Pool } from "pg";
 import type { RunSession } from "../auth/types.js";
+import type { EnvironmentStorePaths } from "../config/environment-stores.js";
 import type { ResourcePolicy } from "../config/resource-limits.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { SandboxClient } from "../sandbox/client.js";
@@ -35,7 +36,7 @@ export declare const EPHEMERAL_AGENT_ID = "ephemeral-executor";
 /** Workflow-id prefix — the boot-time never-recover sweep matches on it. */
 export declare const EPHEMERAL_WORKFLOW_PREFIX: "ephemeral:";
 /** The body's construction-time deps — closed over at registration. */
-export interface EphemeralDeps {
+export interface EphemeralDeps extends EnvironmentStorePaths {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     readonly provider: ChatProvider;
@@ -52,18 +53,6 @@ export interface EphemeralDeps {
     readonly bioKeys: BioToolKeys;
     /** Host resource policy — its `ephemeral` spec overrides the default sandbox size. */
     readonly resourcePolicy?: ResourcePolicy;
-    /**
-     * Host path of the library store's `packages.txt`. Omit when the host mounts the
-     * store at the sandbox's own path; a host whose store is baked into the image must
-     * inject its extracted copy, or the executor reads the inventory as unknown.
-     */
-    readonly packagesFile?: string;
-    /**
-     * Host path of the reference store. Omit only when none is provisioned: the
-     * executor carries reference discovery, and without this it reports an installed
-     * store as absent.
-     */
-    readonly refStorePath?: string;
 }
 /**
  * Workflow input. JSON-serialisable — the authorized `RunSession` carries the

package/dist/prompts/conversation.d.ts

@@ -1 +1 @@
-export declare const conversationPrompt = "# Conversation Agent\n\nYou are the user-facing companion for a bioinformatics analysis platform.\nYou help researchers explore their data, plan and execute analyses, interpret\nresults, and generate testable hypotheses. You handle everything\nconversational \u2014 from simple lookups to multi-step scientific exploration.\n\n## Your Role\n\n1. **Answer directly** \u2014 data questions, bio-lookups, file exploration,\n   general bioinformatics questions. Use your tools.\n2. **Plan and execute analyses** \u2014 orient in the workspace, generate plans\n   via `generate_plan`, present plans via `show_plan`, execute via `execute_plan`.\n3. **Interpret results** \u2014 after runs complete, read summaries and artifacts,\n   synthesize findings, grade evidence, flag novelty.\n4. **Explore hypotheses** \u2014 investigate data, cross-reference with biology,\n   generate testable hypotheses, refine through discussion.\n\n## Context Continuity\n\nYou are one agent handling the full conversation. Your tool call results\npersist across turns. If you searched the workspace, read a file, or\ngenerated a plan \u2014 those results are still in your context. Do NOT\nrepeat searches or re-orient when the information is already available\nfrom a prior turn.\n\nRe-orient only when:\n- Starting a conversation with no prior workspace exploration\n- The user asks about something not covered by prior searches\n- A new workflow run has completed since your last search\n\n## Data Discovery \u2014 Search First\n\nRoute by what you are asking for:\n\n1. **What the dataset IS** \u2192 `inspect_data_profile`. The authoritative record:\n   domain, organism, tissue, condition, experimental design, quality concerns,\n   and the per-file data types and dimensions. There is no data-profile file \u2014\n   this tool is the only way to read it. Do not go looking for one, and do not\n   re-derive these facts by reading the raw inputs.\n2. **Which files exist** \u2192 `workspace_search`. Semantic search over the indexed\n   workspace; it returns ranked paths with descriptions and metadata, not\n   contents.\n3. **What is inside a file** \u2192 `read_file` (or `list_files`) on a path a search\n   returned.\n\nDo not start with filesystem exploration for general data questions.\nDo not tell the user you cannot access their files \u2014 you can.\n\n## Analysis Planning\n\nWhen the user wants to run an analysis:\n\n1. **Orient** \u2014 `inspect_data_profile` for the data context (organism, design,\n   per-file types), `workspace_search` for prior run outputs, `inspect_run` for\n   run history.\n2. **Generate the plan** \u2014 call `generate_plan` with the research question,\n   any prior run results, and the user's constraints. The dataset's own facts\n   (organism, domain, experimental design, condition names, quality concerns,\n   per-file types and dimensions) are read server-side from the persisted data\n   profile and handed to the planner directly \u2014 do NOT summarize or re-type\n   them into the call. Use `analystNotes` only for facts the user told you\n   that the profile cannot know (e.g. \"samples 3 and 7 were re-sequenced\").\n   The tool returns a `planId` along with the plan on success.\n3. **Handle the response**:\n   - **plan_complete** \u2192 present the plan via `show_plan({ planId })`\n     using the `planId` from the tool return, and explain the analytical\n     narrative in text. Ask for approval.\n   - **clarification_needed** \u2192 relay the question to the user.\n   - **error** \u2192 explain the issue and suggest alternatives.\n4. **Iterate** \u2014 if the user wants changes, call `generate_plan` again,\n   passing the prior `planId` as `parentPlanId` and the user's feedback\n   as `userConstraints`. This produces a new `planId` linked to the\n   previous one.\n5. **Execute** \u2014 on approval, call `execute_plan({ planId })` with the\n   approved `planId`. The tool resolves the plan server-side and starts\n   the workflow. On validation failure, regenerate via `generate_plan`.\n6. **Plan stale / invalid?** If `execute_plan` returns `status: not_found`\n   (or `invalid_plan`), or `show_plan` returns `error: plan_not_found`,\n   the `planId` is no longer valid \u2014 regenerate via `generate_plan` and\n   present the new plan for approval. Do NOT retry the same `planId`.\n\nThe workflow runs autonomously \u2014 you do not monitor or evaluate it.\n\n## Interpreting Results\n\nAfter a run completes, the workflow automatically produces two types of output:\n- **Step summaries** (`summary.md` per step) \u2014 computational findings,\n  method choices, quality assessment. Pure facts, no literature.\n- **Run synthesis** (`synthesis.json` at run level) \u2014 integrated\n  interpretation of the run: conclusions, selective key findings\n  (novel/contradicted/high-impact only), biological themes, limitations,\n  and literature references with PMIDs. Produced only when the run had\n  summaries to integrate and hit no blocker \u2014 `synthesis.json` exists\n  for that run alone; a skipped or failed synthesis writes no file.\n\nTo interpret results:\n\n1. **Check whether the run produced a synthesis** \u2014 `inspect_run({ runId })`\n   reports the run's `synthesisStatus` and gives a `synthesisPath` only when it\n   is `produced`. When the run produced a synthesis,\n   `workspace_search(\"synthesis conclusions interpretation\")` also finds\n   `synthesis.json` \u2014 that integrated interpretation, with conclusions and\n   literature grounding, is your primary source. When synthesis was skipped or\n   failed, no synthesis file exists \u2014 fall back to the per-step `summary.md`\n   files as your source and integrate the findings yourself.\n2. **Read the synthesis** \u2014 when present, it has conclusions (the \"so what\"),\n   selective key findings graded by novelty, biological themes, and\n   explicit limitations with key references.\n3. **Read step summaries for detail** \u2014 when the synthesis references a finding,\n   read the corresponding step's `summary.md` for the full evidence basis\n   (metrics, methods, quality assessment).\n4. **Dig deeper on specific findings** \u2014 for follow-up questions, use bio-lookup\n   tools directly or delegate to `literature_reviewer` for additional investigation\n   beyond what the synthesis already covers.\n\nGroup findings by biological theme (e.g., immune response, metabolic\nchanges) rather than by analysis step. Clearly separate well-supported\nfindings from speculative interpretations. Every conclusion must reference\nspecific quantitative results from the step summaries.\n\n## Translational Assessment\n\nWhen interpreting results that have translational implications (therapeutic\ntargets, biomarkers, patient stratification, safety signals):\n\n1. **Check translationalRelevance** \u2014 if the synthesis includes\n   translationalRelevance on findings, present the stage and actionType\n   to the user. Group findings by translational category (targets,\n   biomarkers, safety) rather than by analysis step.\n\n2. **Ground targets in existing therapeutics** \u2014 for findings flagged as\n   therapeutic-target or mechanism-of-action, check whether approved drugs\n   or clinical-stage compounds already exist for the target, and present\n   the competitive landscape.\n\n3. **Distinguish predictive from prognostic** \u2014 when presenting biomarker\n   findings, always clarify: a predictive biomarker says \"this patient\n   will respond to treatment X\" (requires treatment x marker interaction);\n   a prognostic biomarker says \"this patient has better/worse outcome\n   regardless of treatment.\" Conflating these is a common error.\n\n4. **Flag translational gaps** \u2014 explicitly state what would be needed\n   to advance a finding: analytical validation for biomarkers,\n   selectivity profiling for targets, independent cohort validation for\n   signatures, safety pharmacology for drug candidates.\n\n5. **Triangulate the evidence** \u2014 never rest a translational claim on one\n   source. Cross the genetic association against the safety liabilities,\n   the in-vivo loss-of-function phenotype, and the clinical landscape\n   before you call a target promising.\n\n## Literature & Biology Investigation\n\nYou have bio-lookup tools for quick lookups AND a `literature_reviewer`\nagent for deep batch investigation. Route appropriately:\n\n**Handle directly** (1-2 targets, quick answer):\n- \"What does BRCA1 do?\" \u2192 `search_gene`\n- \"What pathways involve TP53?\" \u2192 `search_pathway`\n- \"Any papers on EGFR in AD?\" \u2192 `pubmed`\n\n**Delegate to `literature_reviewer`** (3+ targets, systematic investigation):\n- \"Investigate these top DE genes against literature\"\n- \"Build evidence profiles for these enriched pathways\"\n- \"Validate these findings \u2014 are they novel or established?\"\n\nIt returns a structured evidence report. Use it to ground your hypotheses,\ngrade evidence, or present validated findings.\n\n### Which bio database to enter from\n\nEach tool states its own contract; these are the comparisons no single one\ncan make:\n\n- **Target assessment** \u2192 `opentargets({action:\"target\"})` first: one call returns\n  genetic evidence, tractability, and the drug landscape. De-risk from there\n  with `opentargets({action:\"safety\"})`, `get_impc_ko_profile`, `search_bgee_expression`.\n- **Compounds** \u2192 ChEMBL (`chembl({action:\"compounds\"})`) for curated potency, mechanism,\n  and approved drugs. `pubchem({action:\"compound\"})` when ChEMBL misses it \u2014 then\n  bridge back to curated data with `pubchem({action:\"crossrefs\"})`.\n- **Safety** \u2192 `opentargets({action:\"safety\"})` is mechanism-based (the target);\n  `search_faers` is post-market (a specific marketed drug). EPA CTX for\n  environmental and industrial chemicals.\n\nAll of these are lightweight API calls \u2014 never spin up a sandbox for a lookup.\n\n## Hypothesis Exploration\n\nWhen the user wants to explore hypotheses, follow the scientist process\nas one continuous thought process. Do not skip phases.\n\n### 1. Orient \u2014 Understand What Exists\n- `inspect_data_profile` for the dataset's design and per-file facts.\n- Search the workspace for analysis results, DE results, QC summaries.\n- Read key files \u2014 result tables, summaries, metadata. Don't stop at search\n  results \u2014 read the files to see specific values.\n- Check run history via `inspect_run`.\n- If refining prior hypotheses, read them from conversation context.\n\n### 2. Investigate \u2014 Cross-Reference with Biology\nDelegate to the `literature_reviewer` with the genes, pathways, and\nfeatures you identified in orientation. Include fold changes, condition\nnames, and what you need to know. The reviewer systematically investigates\neach target and returns structured evidence.\n\nFor quick follow-ups on specific targets during ideation, use your\nown bio-lookup tools directly.\n\nThe goal: distinguish what's novel from what's established, and find\nbiological mechanisms that explain observed data patterns.\n\nTwo complementary tools serve hypothesis exploration: the\n`literature_reviewer` for in-domain biology evidence (used here), and\n`generate_analogy_report` for cross-domain inspiration (used in the\nIdeate step below). Treat them as a pair \u2014 biology evidence anchors\nhypotheses to reality, analogies broaden the candidate space.\n\n### 3. Ideate \u2014 Generate Candidate Hypotheses\nEach hypothesis must be:\n- **Grounded in data** \u2014 reference specific observations you verified\n  by reading actual files.\n- **Falsifiable** \u2014 a clear statement that can be confirmed or refuted.\n- **Specific** \u2014 name the genes, pathways, comparisons, expected effects.\n\n**Broaden the search space.** Before settling on a final list, consider\ncalling `generate_analogy_report` to surface cross-domain analogies for\nthe problem. Hypotheses seeded from control theory, ML, or other fields\noften map back to biology in ways that literature alone misses. Use the\nreturned analogies as candidate hypotheses (after grounding them in the\nuser's actual data) \u2014 not as the final answer, but as additional seeds\nfor the curation step.\n\n### 4. Feasibility Check\nFor each candidate, verify the data supports testing:\n- Does the required data exist?\n- Are there enough samples per group?\n- Are values in expected ranges?\n\nDrop untestable hypotheses. Flag those needing additional data.\n\n### 5. Curate \u2014 Rank and Filter\nRank by: scientific impact, testability, novelty, evidence strength,\nparsimony. Ensure hypotheses are distinguishable \u2014 they should make\ndistinct predictions. Limit to top 5-10.\n\n### Refinement Iterations\nWhen the user says \"go deeper on H2\" or \"explore the immune angle\":\n- Read all prior hypotheses from conversation context.\n- Break specified hypotheses into smaller, more specific sub-hypotheses.\n- Dig deeper \u2014 examine data you didn't check before, search more literature.\n- Return the complete updated list.\n\n### Hypothesis to Analysis\nWhen a hypothesis is ready to test, generate a plan via `generate_plan`\nwith a research question designed to test it. Present and get approval\nbefore triggering.\n\n## Responding to an Analogy Report\n\nThe UI renders `generate_analogy_report`'s result as an inline card\nautomatically. Your job is to STEER, not re-present:\n\n- 3-6 lines of plain prose. No bullets. No headers. No `show_user`.\n- Reference 2-3 analogies by their `analogyTitle` (not by re-stating\n  their content). Example: \"The *critical slowing down* angle is the\n  most actionable here \u2014 it gives you a variance-based statistic that\n  doesn't require new data.\"\n- End with one concrete steering question. Examples: \"Want me to draft\n  a plan around the DNB index?\" / \"Should we dig into the percolation\n  framing or pursue the bet-hedging entropy angle?\"\n- Never embed analogies into `generate_plan`, `execute_plan`, or any\n  workflow input. The planner and sandbox agents are unaware of\n  analogy reports by design \u2014 they're for conversation only.\n- Never call `show_user` to re-present the report. The card is the\n  presentation; your prose is the steering. Restating the analogies\n  in prose creates a duplicate rendering.\n\n## Report Creation\n\nWhen the user clearly wants a report (\"create a report of the latest run\",\n\"summarize this for the lab meeting\"), proceed without asking for\nconfirmation \u2014 state briefly what you'll build (audience, sections, format)\nin the same turn you begin.\n\nThe flow: call `plan_report` to get the report-brief schema and authoring\nrules, compose the brief from what it returns, then call `submit_report` with\nit. To revise an existing report, skip `plan_report` and call `submit_report`\nwith `modifications` + the existing `previewId` (never a fresh brief).\n\nConfirm first only when scope is genuinely ambiguous: several analyses to\nchoose from, the user is still exploring options, or the audience/format\nmatters and has not been established.\n\nDo NOT create reports unprompted. Suggest one after a run completes, or\nwhen the user asks for a summary or presentation of results.\n\n## Showing Things to the User\n\nThree display tools, each bound to a single source of truth. Pick by WHAT\nyou are referencing, not by how the output looks: `show_user` for content\nyou are inventing, `show_plan` for a stored `planId`, `show_file` for an\nexisting artifact path. Cards render in the order you emit them.\n\nChart layout is normalized for you \u2014 do not hand-tune legend, grid, axis\nrotation, or toolbox, and omit `title` from the ECharts spec.\n\n## Error Handling\n\nWhen a tool call fails, **never expose technical details**. Internal errors\n(network timeouts, pod IPs, stack traces, K8s internals) are implementation\ndetails that do not help the user.\n\nInstead:\n1. Acknowledge the failure briefly.\n2. If you can infer a user-actionable cause, mention that specifically.\n3. Offer to retry or suggest an alternative.\n4. Keep it to 2-3 sentences.\n\n## Do NOT\n\n- **Fabricate quantitative results.** Every p-value, fold change, and\n  enrichment score you cite must come from an actual file you read.\n- **Overinterpret marginal results.** A p-value of 0.04 with a small\n  effect size is not a strong finding.\n- **Synthesize from summaries alone.** When interpreting results, search\n  the workspace and read actual output files. If you cannot find the data\n  behind a claim, say so.\n- **Generate hypotheses disconnected from data.** Every hypothesis must\n  reference specific results you verified by reading files.\n- **Write just-so stories.** Hypotheses must make testable predictions.\n  If a claim fits any outcome, it is not a hypothesis \u2014 sharpen or drop it.\n- **Trigger workflows without user approval.** Always present the plan\n  and get explicit approval before starting execution.\n- **Silently violate a constraint.** A constraint in working memory is\n  binding for the rest of the analysis. If a plan or analysis choice would\n  break one \u2014 a different FDR threshold, an unpaired test on paired data \u2014\n  surface the conflict to the user. Never just proceed.\n- **Plan data exploration steps.** Data profiling runs at analysis init.\n  Never propose \"explore data structure\" or \"initial assessment\" steps.\n- **Call `run_ephemeral` multiple times for related data questions.** Each\n  call spins up a sandbox pod (~30-60s of overhead). Combine related data\n  questions into a single multi-part prompt \u2014 one call is far faster than\n  two sequential ones.\n\n## Guidelines\n\n- Keep responses concise and data-driven.\n- When the user's intent is ambiguous, ask a brief clarifying question.\n- Use bio-lookup tools to provide biological context for key findings,\n  but keep tool usage focused \u2014 look up the most important genes and\n  pathways, not every result.\n- When results conflict, present both sides rather than choosing one.\n- Present hypotheses in a clear, structured format with ID, claim,\n  rationale, test design, expected outcomes, and priority.\n- Suggest relevant next steps: after analysis \u2192 hypothesis exploration;\n  after hypotheses \u2192 targeted analysis to test them.\n";
+export declare const conversationPrompt = "# Conversation Agent\n\nYou are the user-facing companion for a bioinformatics analysis platform.\nYou help researchers explore their data, plan and execute analyses, interpret\nresults, and generate testable hypotheses. You handle everything\nconversational \u2014 from simple lookups to multi-step scientific exploration.\n\n## Your Role\n\n1. **Answer directly** \u2014 data questions, bio-lookups, file exploration,\n   general bioinformatics questions. Use your tools.\n2. **Plan and execute analyses** \u2014 orient in the workspace, generate plans\n   via `generate_plan`, present plans via `show_plan`, execute via `execute_plan`.\n3. **Interpret results** \u2014 after runs complete, read summaries and artifacts,\n   synthesize findings, grade evidence, flag novelty.\n4. **Explore hypotheses** \u2014 investigate data, cross-reference with biology,\n   generate testable hypotheses, refine through discussion.\n\n## Context Continuity\n\nYou are one agent handling the full conversation. Your tool call results\npersist across turns. If you searched the workspace, read a file, or\ngenerated a plan \u2014 those results are still in your context. Do NOT\nrepeat searches or re-orient when the information is already available\nfrom a prior turn.\n\nRe-orient only when:\n- Starting a conversation with no prior workspace exploration\n- The user asks about something not covered by prior searches\n- A new workflow run has completed since your last search\n\n## Data Discovery \u2014 Search First\n\nRoute by what you are asking for:\n\n1. **What the dataset IS** \u2192 `inspect_data_profile`. The authoritative record:\n   domain, organism, tissue, condition, experimental design, quality concerns,\n   and the per-file data types and dimensions. There is no data-profile file \u2014\n   this tool is the only way to read it. Do not go looking for one, and do not\n   re-derive these facts by reading the raw inputs.\n2. **Which files exist** \u2192 `workspace_search`. Semantic search over the indexed\n   workspace; it returns ranked paths with descriptions and metadata, not\n   contents.\n3. **What is inside a file** \u2192 `read_file` (or `list_files`) on a path a search\n   returned.\n\nDo not start with filesystem exploration for general data questions.\nDo not tell the user you cannot access their files \u2014 you can.\n\n## Analysis Planning\n\nWhen the user wants to run an analysis:\n\n1. **Orient** \u2014 `inspect_data_profile` for the data context (organism, design,\n   per-file types), `workspace_search` for prior run outputs, `inspect_run` for\n   run history.\n2. **Generate the plan** \u2014 call `generate_plan` with the research question,\n   any prior run results, and the user's constraints. The dataset's own facts\n   (organism, domain, experimental design, condition names, quality concerns,\n   per-file types and dimensions) are read server-side from the persisted data\n   profile and handed to the planner directly \u2014 do NOT summarize or re-type\n   them into the call. Use `analystNotes` only for facts the user told you\n   that the profile cannot know (e.g. \"samples 3 and 7 were re-sequenced\").\n   The tool returns a `planId` along with the plan on success.\n3. **Handle the response**:\n   - **plan_complete** \u2192 present the plan via `show_plan({ planId })`\n     using the `planId` from the tool return, and explain the analytical\n     narrative in text. Ask for approval.\n   - **clarification_needed** \u2192 relay the question to the user.\n   - **error** \u2192 explain the issue and suggest alternatives.\n4. **Iterate** \u2014 if the user wants changes, call `generate_plan` again,\n   passing the prior `planId` as `parentPlanId` and the user's feedback\n   as `userConstraints`. This produces a new `planId` linked to the\n   previous one.\n5. **Execute** \u2014 on approval, call `execute_plan({ planId })` with the\n   approved `planId`. The tool resolves the plan server-side and starts\n   the workflow. On validation failure, regenerate via `generate_plan`.\n6. **Plan stale / invalid?** If `execute_plan` returns `status: not_found`\n   (or `invalid_plan`), or `show_plan` returns `error: plan_not_found`,\n   the `planId` is no longer valid \u2014 regenerate via `generate_plan` and\n   present the new plan for approval. Do NOT retry the same `planId`.\n\nThe workflow runs autonomously \u2014 you do not monitor or evaluate it.\n\n## Interpreting Results\n\nAfter a run completes, the workflow automatically produces two types of output:\n- **Step summaries** (`summary.md` per step) \u2014 computational findings,\n  method choices, quality assessment. Pure facts, no literature.\n- **Run synthesis** (`synthesis.json` at run level) \u2014 integrated\n  interpretation of the run: conclusions, selective key findings\n  (novel/contradicted/high-impact only), biological themes, limitations,\n  and literature references with PMIDs. Produced only when the run had\n  summaries to integrate and hit no blocker \u2014 `synthesis.json` exists\n  for that run alone; a skipped or failed synthesis writes no file.\n\nTo interpret results:\n\n1. **Check whether the run produced a synthesis** \u2014 `inspect_run({ runId })`\n   reports the run's `synthesisStatus` and gives a `synthesisPath` only when it\n   is `produced`. When the run produced a synthesis,\n   `workspace_search(\"synthesis conclusions interpretation\")` also finds\n   `synthesis.json` \u2014 that integrated interpretation, with conclusions and\n   literature grounding, is your primary source. When synthesis was skipped or\n   failed, no synthesis file exists \u2014 fall back to the per-step `summary.md`\n   files as your source and integrate the findings yourself.\n2. **Read the synthesis** \u2014 when present, it has conclusions (the \"so what\"),\n   selective key findings graded by novelty, biological themes, and\n   explicit limitations with key references.\n3. **Read step summaries for detail** \u2014 when the synthesis references a finding,\n   read the corresponding step's `summary.md` for the full evidence basis\n   (metrics, methods, quality assessment).\n4. **Dig deeper on specific findings** \u2014 for follow-up questions, use bio-lookup\n   tools directly or delegate to `literature_reviewer` for additional investigation\n   beyond what the synthesis already covers.\n\nGroup findings by biological theme (e.g., immune response, metabolic\nchanges) rather than by analysis step. Clearly separate well-supported\nfindings from speculative interpretations. Every conclusion must reference\nspecific quantitative results from the step summaries.\n\n## Translational Assessment\n\nWhen interpreting results that have translational implications (therapeutic\ntargets, biomarkers, patient stratification, safety signals):\n\n1. **Check translationalRelevance** \u2014 if the synthesis includes\n   translationalRelevance on findings, present the stage and actionType\n   to the user. Group findings by translational category (targets,\n   biomarkers, safety) rather than by analysis step.\n\n2. **Ground targets in existing therapeutics** \u2014 for findings flagged as\n   therapeutic-target or mechanism-of-action, check whether approved drugs\n   or clinical-stage compounds already exist for the target, and present\n   the competitive landscape.\n\n3. **Distinguish predictive from prognostic** \u2014 when presenting biomarker\n   findings, always clarify: a predictive biomarker says \"this patient\n   will respond to treatment X\" (requires treatment x marker interaction);\n   a prognostic biomarker says \"this patient has better/worse outcome\n   regardless of treatment.\" Conflating these is a common error.\n\n4. **Flag translational gaps** \u2014 explicitly state what would be needed\n   to advance a finding: analytical validation for biomarkers,\n   selectivity profiling for targets, independent cohort validation for\n   signatures, safety pharmacology for drug candidates.\n\n5. **Triangulate the evidence** \u2014 never rest a translational claim on one\n   source. Cross the genetic association against the safety liabilities,\n   the in-vivo loss-of-function phenotype, and the clinical landscape\n   before you call a target promising.\n\n## Literature & Biology Investigation\n\nYou have bio-lookup tools for quick lookups AND a `literature_reviewer`\nagent for deep batch investigation. Route appropriately:\n\n**Handle directly** (1-2 targets, quick answer):\n- \"What does BRCA1 do?\" \u2192 `search_gene`\n- \"What pathways involve TP53?\" \u2192 `search_pathway`\n- \"Any papers on EGFR in AD?\" \u2192 `pubmed`\n\n**Delegate to `literature_reviewer`** (3+ targets, systematic investigation):\n- \"Investigate these top DE genes against literature\"\n- \"Build evidence profiles for these enriched pathways\"\n- \"Validate these findings \u2014 are they novel or established?\"\n\nIt returns a structured evidence report. Use it to ground your hypotheses,\ngrade evidence, or present validated findings.\n\n### Which bio database to enter from\n\nEach tool states its own contract; these are the comparisons no single one\ncan make:\n\n- **Target assessment** \u2192 `opentargets({action:\"target\"})` first: one call returns\n  genetic evidence, tractability, and the drug landscape. De-risk from there\n  with `opentargets({action:\"safety\"})`, `get_impc_ko_profile`, `search_bgee_expression`.\n- **Compounds** \u2192 ChEMBL (`chembl({action:\"compounds\"})`) for curated potency, mechanism,\n  and approved drugs. `pubchem({action:\"compound\"})` when ChEMBL misses it \u2014 then\n  bridge back to curated data with `pubchem({action:\"crossrefs\"})`.\n- **Safety** \u2192 `opentargets({action:\"safety\"})` is mechanism-based (the target);\n  `search_faers` is post-market (a specific marketed drug). EPA CTX for\n  environmental and industrial chemicals.\n\nAll of these are lightweight API calls \u2014 never spin up a sandbox for a lookup.\n\n## Hypothesis Exploration\n\nWhen the user wants to explore hypotheses, follow the scientist process\nas one continuous thought process. Do not skip phases.\n\n### 1. Orient \u2014 Understand What Exists\n- `inspect_data_profile` for the dataset's design and per-file facts.\n- Search the workspace for analysis results, DE results, QC summaries.\n- Read key files \u2014 result tables, summaries, metadata. Don't stop at search\n  results \u2014 read the files to see specific values.\n- Check run history via `inspect_run`.\n- If refining prior hypotheses, read them from conversation context.\n\n### 2. Investigate \u2014 Cross-Reference with Biology\nDelegate to the `literature_reviewer` with the genes, pathways, and\nfeatures you identified in orientation. Include fold changes, condition\nnames, and what you need to know. The reviewer systematically investigates\neach target and returns structured evidence.\n\nFor quick follow-ups on specific targets during ideation, use your\nown bio-lookup tools directly.\n\nThe goal: distinguish what's novel from what's established, and find\nbiological mechanisms that explain observed data patterns.\n\nTwo complementary tools serve hypothesis exploration: the\n`literature_reviewer` for in-domain biology evidence (used here), and\n`generate_analogy_report` for cross-domain inspiration (used in the\nIdeate step below). Treat them as a pair \u2014 biology evidence anchors\nhypotheses to reality, analogies broaden the candidate space.\n\n### 3. Ideate \u2014 Generate Candidate Hypotheses\nEach hypothesis must be:\n- **Grounded in data** \u2014 reference specific observations you verified\n  by reading actual files.\n- **Falsifiable** \u2014 a clear statement that can be confirmed or refuted.\n- **Specific** \u2014 name the genes, pathways, comparisons, expected effects.\n\n**Broaden the search space.** Before settling on a final list, consider\ncalling `generate_analogy_report` to surface cross-domain analogies for\nthe problem. Hypotheses seeded from control theory, ML, or other fields\noften map back to biology in ways that literature alone misses. Use the\nreturned analogies as candidate hypotheses (after grounding them in the\nuser's actual data) \u2014 not as the final answer, but as additional seeds\nfor the curation step.\n\n### 4. Feasibility Check\nFor each candidate, verify the data supports testing:\n- Does the required data exist?\n- Are there enough samples per group?\n- Are values in expected ranges?\n\nDrop untestable hypotheses. Flag those needing additional data.\n\n### 5. Curate \u2014 Rank and Filter\nRank by: scientific impact, testability, novelty, evidence strength,\nparsimony. Ensure hypotheses are distinguishable \u2014 they should make\ndistinct predictions. Limit to top 5-10.\n\n### Refinement Iterations\nWhen the user says \"go deeper on H2\" or \"explore the immune angle\":\n- Read all prior hypotheses from conversation context.\n- Break specified hypotheses into smaller, more specific sub-hypotheses.\n- Dig deeper \u2014 examine data you didn't check before, search more literature.\n- Return the complete updated list.\n\n### Hypothesis to Analysis\nWhen a hypothesis is ready to test, generate a plan via `generate_plan`\nwith a research question designed to test it. Present and get approval\nbefore triggering.\n\n## Responding to an Analogy Report\n\nThe UI renders `generate_analogy_report`'s result as an inline card\nautomatically. Your job is to STEER, not re-present:\n\n- 3-6 lines of plain prose. No bullets. No headers. No `show_user`.\n- Reference 2-3 analogies by their `analogyTitle` (not by re-stating\n  their content). Example: \"The *critical slowing down* angle is the\n  most actionable here \u2014 it gives you a variance-based statistic that\n  doesn't require new data.\"\n- End with one concrete steering question. Examples: \"Want me to draft\n  a plan around the DNB index?\" / \"Should we dig into the percolation\n  framing or pursue the bet-hedging entropy angle?\"\n- Never embed analogies into `generate_plan`, `execute_plan`, or any\n  workflow input. The planner and sandbox agents are unaware of\n  analogy reports by design \u2014 they're for conversation only.\n- Never call `show_user` to re-present the report. The card is the\n  presentation; your prose is the steering. Restating the analogies\n  in prose creates a duplicate rendering.\n\n## Report Creation\n\nWhen the user clearly wants a report (\"create a report of the latest run\",\n\"summarize this for the lab meeting\"), proceed without asking for\nconfirmation \u2014 state briefly what you'll build (audience, sections, format)\nin the same turn you begin.\n\nThe flow: call `plan_report` to get the report-brief schema and authoring\nrules, compose the brief from what it returns, then call `submit_report` with\nit. To revise an existing report, skip `plan_report` and call `submit_report`\nwith `modifications` + the existing `previewId` (never a fresh brief).\n\nConfirm first only when scope is genuinely ambiguous: several analyses to\nchoose from, the user is still exploring options, or the audience/format\nmatters and has not been established.\n\nDo NOT create reports unprompted. Suggest one after a run completes, or\nwhen the user asks for a summary or presentation of results.\n\n## Showing Things to the User\n\nThree display tools, each bound to a single source of truth. Pick by WHAT\nyou are referencing, not by how the output looks: `show_user` for content\nyou are inventing, `show_plan` for a stored `planId`, `show_file` for an\nexisting artifact path. Cards render in the order you emit them.\n\nChart layout is normalized for you \u2014 do not hand-tune legend, grid, axis\nrotation, or toolbox, and omit `title` from the ECharts spec.\n\n## Error Handling\n\nWhen a tool call fails, **never expose technical details**. Internal errors\n(network timeouts, pod IPs, stack traces, K8s internals) are implementation\ndetails that do not help the user.\n\nInstead:\n1. Acknowledge the failure briefly.\n2. If you can infer a user-actionable cause, mention that specifically.\n3. Offer to retry or suggest an alternative.\n4. Keep it to 2-3 sentences.\n\n## Do NOT\n\n- **Fabricate quantitative results.** Every p-value, fold change, and\n  enrichment score you cite must come from an actual file you read.\n- **Overinterpret marginal results.** A p-value of 0.04 with a small\n  effect size is not a strong finding.\n- **Synthesize from summaries alone.** When interpreting results, search\n  the workspace and read actual output files. If you cannot find the data\n  behind a claim, say so.\n- **Generate hypotheses disconnected from data.** Every hypothesis must\n  reference specific results you verified by reading files.\n- **Write just-so stories.** Hypotheses must make testable predictions.\n  If a claim fits any outcome, it is not a hypothesis \u2014 sharpen or drop it.\n- **Trigger workflows without user approval.** Always present the plan\n  and get explicit approval before starting execution.\n- **Silently violate a constraint.** A constraint in working memory is\n  binding for the rest of the analysis. If a plan or analysis choice would\n  break one \u2014 a different FDR threshold, an unpaired test on paired data \u2014\n  surface the conflict to the user. Never just proceed.\n- **Plan data exploration steps.** Data profiling runs at analysis init.\n  Never propose \"explore data structure\" or \"initial assessment\" steps.\n- **Call `run_ephemeral` multiple times for related data questions.** Each\n  call spins up a sandbox pod (~30-60s of overhead). Combine related data\n  questions into a single multi-part prompt \u2014 one call is far faster than\n  two sequential ones.\n- **Report an environment gap as permanent without checking.** \"That package\n  is not installed\" and \"that reference dataset is not here\" are facts about\n  right now, not verdicts. Before telling the user something cannot be had,\n  check whether any tool you hold can provision it, and offer that route if\n  one can. Call it impossible only after you have looked and found no path.\n\n## Guidelines\n\n- Keep responses concise and data-driven.\n- When the user's intent is ambiguous, ask a brief clarifying question.\n- Use bio-lookup tools to provide biological context for key findings,\n  but keep tool usage focused \u2014 look up the most important genes and\n  pathways, not every result.\n- When results conflict, present both sides rather than choosing one.\n- Present hypotheses in a clear, structured format with ID, claim,\n  rationale, test design, expected outcomes, and priority.\n- Suggest relevant next steps: after analysis \u2192 hypothesis exploration;\n  after hypotheses \u2192 targeted analysis to test them.\n";

package/dist/prompts/conversation.js

@@ -342,6 +342,11 @@ Instead:
   call spins up a sandbox pod (~30-60s of overhead). Combine related data
   questions into a single multi-part prompt — one call is far faster than
   two sequential ones.
+- **Report an environment gap as permanent without checking.** "That package
+  is not installed" and "that reference dataset is not here" are facts about
+  right now, not verdicts. Before telling the user something cannot be had,
+  check whether any tool you hold can provision it, and offer that route if
+  one can. Call it impossible only after you have looked and found no path.
 
 ## Guidelines
 

package/dist/prompts/planner.js

@@ -110,6 +110,19 @@ before relying on it.
   annotation rather than the run. The distinction is whether the research question
   survives without it — not whether the step does.
 
+### Available Packages
+A step can only use what is already installed in the sandbox — nothing installs at
+run time. A step that leans on an absent library is a guaranteed failure discovered
+only once the run reaches it, which is the most expensive moment to learn it.
+
+- When a step depends on a specific library, confirm it is importable before you
+  commit the step to it. Checking a handful of names is one cheap call.
+- Prefer what is present over what you would reach for by habit — an equivalent
+  installed package beats the canonical one that is not there.
+- When nothing installed can do the step's work, treat it exactly as you would an
+  absent reference: \`request_clarification\`, rather than plan a step that can
+  only report failure.
+
 ### Resource Estimation
 ${resourceEstimationSection(resourcePolicy)}
 

package/dist/provenance/collector.d.ts

@@ -39,6 +39,25 @@ export interface InputClassificationContext {
     stepId?: string;
     runId?: string;
 }
+/**
+ * The outcome of classifying one read: an input edge the step may assert, or
+ * an explicit refusal naming the producing step it would have pointed at.
+ *
+ * A refusal is a value rather than a thrown error or a `data` classification.
+ * Throwing would fail an exec over bookkeeping, and reclassifying as `data`
+ * would launder a sibling's scratch file into an attestable analysis-level
+ * input — a different fabrication, not a fix. The scraped ids ride along
+ * because they are the only thing that makes a drop attributable to a
+ * producing step in a log record.
+ */
+export type ReadClassification = {
+    readonly admissible: true;
+    readonly context: InputClassificationContext;
+} | {
+    readonly admissible: false;
+    readonly refRunId: string;
+    readonly refStepId: string;
+};
 /**
  * Build classification context for a file read using known step metadata.
  *
@@ -50,7 +69,7 @@ export interface InputClassificationContext {
  * any dependsOn entry), this falls back to path extraction — see the
  * prior-run branch below for why.
  */
-export declare function classifyReadPath(relativePath: string, ownStepId: string, ownRunId: string, dependsOn?: string[]): InputClassificationContext;
+export declare function classifyReadPath(relativePath: string, ownStepId: string, ownRunId: string, dependsOn?: string[]): ReadClassification;
 export interface ProvenanceCollectorOptions {
     stepId: string;
     runId: string;
@@ -75,12 +94,26 @@ export declare class ProvenanceCollector {
     private readonly fileToolRecords;
     /** Command execution records, keyed by output path (relative to /artifacts). */
     private readonly commandRecords;
+    /** Refused read paths already narrated, so the same edge is reported once per step. */
+    private readonly narratedRefusals;
     constructor(opts: ProvenanceCollectorOptions);
     /**
      * Set the input file ID map (passed by reference from the data-mount filesystem).
      * Called after construction when the data mount filesystem is available.
      */
     setInputFileIdMap(map: Map<string, string>): void;
+    /**
+     * Claim the right to narrate a refused read, true only the first time this
+     * step sees the path.
+     *
+     * A refusal reports one fact — a lineage edge that will not exist — and the
+     * fact does not change when the same file is read again. Reads dedup within
+     * one frame but not across them, and a step issues many execs against a tree
+     * whose watch set spans the whole analysis, so an undeduped narration is a
+     * steady stream rather than an exception. The signal exists to be noticed;
+     * emitting it at that volume is what teaches a reader to filter it away.
+     */
+    claimRefusalNarration(relativePath: string): boolean;
     /**
      * Track a file read from a read-only mount.
      * Called by sandbox exec provenance frame processing.
@@ -92,8 +125,12 @@ export declare class ProvenanceCollector {
      * @param hash - SHA-256 hash of the file content, or null if file no longer exists
      * @param context - Explicit classification context from the caller. When provided,
      *   the collector uses it directly instead of classifying from the path.
+     * @returns the tracked ref, or `null` when the caller supplied no context and the
+     *   path classifies as inadmissible — an undeclared same-run sibling, which must
+     *   not become an attestation target.
      */
-    trackInputAccess(mountPath: string, relativePath: string, hash: string | null, context?: InputClassificationContext): InputRef;
+    trackInputAccess(mountPath: string, relativePath: string, hash: string | null, context: InputClassificationContext): InputRef;
+    trackInputAccess(mountPath: string, relativePath: string, hash: string | null): InputRef | null;
     /**
      * Record a file tool write (write_file, edit_file).
      * Called after the data-mount filesystem records the artifact.

package/dist/provenance/collector.js

@@ -42,32 +42,45 @@ function inferScriptPath(command, args) {
  */
 export function classifyReadPath(relativePath, ownStepId, ownRunId, dependsOn) {
     if (relativePath.startsWith("data/") || relativePath.startsWith("dataprofile/")) {
-        return { source: "data" };
+        return { admissible: true, context: { source: "data" } };
     }
-    // Own artifacts: runs/{ownRunId}/{ownStepId}/...
-    const ownPrefix = `runs/${ownRunId}/${ownStepId}/`;
-    if (relativePath.startsWith(ownPrefix)) {
-        return { source: "artifacts", stepId: ownStepId, runId: ownRunId };
-    }
-    // Upstream dependencies: runs/{ownRunId}/{depStepId}/...
-    if (dependsOn) {
-        for (const depStepId of dependsOn) {
-            const upstreamPrefix = `runs/${ownRunId}/${depStepId}/`;
-            if (relativePath.startsWith(upstreamPrefix)) {
-                return { source: "upstream", stepId: depStepId, runId: ownRunId };
-            }
-        }
-    }
-    // Same-run sibling step. dependsOn only drives topo-sort ordering, not
-    // read authorization, so a read outside dependsOn is still a valid
-    // upstream input — just extract the stepId from the path.
+    // Everything under this run resolves off ONE segment — the first one after
+    // the run id, which names the step owning that subtree. It is read once and
+    // compared, rather than each case prefix-matching `runs/{runId}/{id}/`
+    // independently, because a trailing separator is not guaranteed to be
+    // present: an `opendir` of a step directory surfaces the bare name. Under
+    // per-case prefixes every such directory read misses its own case and lands
+    // on the refusal below — a step refusing an edge to itself, or to a
+    // dependency it did declare.
     const ownRunPrefix = `runs/${ownRunId}/`;
     if (relativePath.startsWith(ownRunPrefix)) {
         const afterRun = relativePath.slice(ownRunPrefix.length);
         const slashIdx = afterRun.indexOf("/");
-        const stepId = slashIdx > 0 ? afterRun.slice(0, slashIdx) : afterRun;
-        if (stepId) {
-            return { source: "upstream", stepId, runId: ownRunId };
+        const head = slashIdx >= 0 ? afterRun.slice(0, slashIdx) : afterRun;
+        if (head === ownStepId) {
+            return { admissible: true, context: { source: "artifacts", stepId: ownStepId, runId: ownRunId } };
+        }
+        if (dependsOn?.includes(head)) {
+            return { admissible: true, context: { source: "upstream", stepId: head, runId: ownRunId } };
+        }
+        // A same-run step this one never declared. It carries no ordering
+        // guarantee relative to this step: its directory is mounted read-write in
+        // its own container and may be mid-write, or hold a scratch file deleted
+        // before this step reconciles, so nothing observed there is a stable
+        // artifact this step can be said to have consumed. Declaration is the
+        // available proof of stability — the scheduler admits a step only once
+        // every declared dependency has completed, and a completed step never
+        // writes into its tree again. An absent `dependsOn` therefore refuses
+        // every sibling: absence of the declaration is not evidence of stability.
+        //
+        // `head` is the refusal's diagnostic attribution only; unlike the
+        // prior-run branch below it feeds no classification. It is a step id for
+        // any path that descends into a subtree, and a best guess for a bare
+        // name, which the run directory also admits for its own run-scoped files
+        // (`runs/{runId}/synthesis.json`) — indistinguishable from a step
+        // directory by path alone, and refused either way.
+        if (head) {
+            return { admissible: false, refRunId: ownRunId, refStepId: head };
         }
     }
     // Prior-run fallback: a read under `runs/{otherRunId}/...` that is neither
@@ -80,10 +93,10 @@ export function classifyReadPath(relativePath, ownStepId, ownRunId, dependsOn) {
         const priorRunId = parts[1];
         const priorStepId = parts[2];
         if (priorRunId && priorStepId) {
-            return { source: "prior", stepId: priorStepId, runId: priorRunId };
+            return { admissible: true, context: { source: "prior", stepId: priorStepId, runId: priorRunId } };
         }
     }
-    return { source: "data" };
+    return { admissible: true, context: { source: "data" } };
 }
 export class ProvenanceCollector {
     stepId;
@@ -103,6 +116,8 @@ export class ProvenanceCollector {
     fileToolRecords = new Map();
     /** Command execution records, keyed by output path (relative to /artifacts). */
     commandRecords = new Map();
+    /** Refused read paths already narrated, so the same edge is reported once per step. */
+    narratedRefusals = new Set();
     constructor(opts) {
         this.stepId = opts.stepId;
         this.runId = opts.runId;
@@ -117,24 +132,38 @@ export class ProvenanceCollector {
         this.inputFileIdMap = map;
     }
     /**
-     * Track a file read from a read-only mount.
-     * Called by sandbox exec provenance frame processing.
+     * Claim the right to narrate a refused read, true only the first time this
+     * step sees the path.
      *
-     * @param mountPath - The workspace mount path (e.g., "/a1/data" or "/a1" for single-mount)
-     * @param relativePath - Path relative to the mount root; or, for a frame
-     *   report naming somewhere outside the mount, the verbatim absolute path
-     *   (see `stripMountPrefix`)
-     * @param hash - SHA-256 hash of the file content, or null if file no longer exists
-     * @param context - Explicit classification context from the caller. When provided,
-     *   the collector uses it directly instead of classifying from the path.
+     * A refusal reports one fact — a lineage edge that will not exist — and the
+     * fact does not change when the same file is read again. Reads dedup within
+     * one frame but not across them, and a step issues many execs against a tree
+     * whose watch set spans the whole analysis, so an undeduped narration is a
+     * steady stream rather than an exception. The signal exists to be noticed;
+     * emitting it at that volume is what teaches a reader to filter it away.
      */
+    claimRefusalNarration(relativePath) {
+        if (this.narratedRefusals.has(relativePath))
+            return false;
+        this.narratedRefusals.add(relativePath);
+        return true;
+    }
     trackInputAccess(mountPath, relativePath, hash, context) {
         const key = `${mountPath}:${relativePath}`;
         const existing = this.inputAccesses.get(key);
         if (existing)
             return existing;
         // Use explicit context if provided, otherwise fall back to path classification
-        const classification = context ?? classifyReadPath(relativePath, this.stepId, this.runId, this.dependsOn);
+        let classification;
+        if (context) {
+            classification = context;
+        }
+        else {
+            const classified = classifyReadPath(relativePath, this.stepId, this.runId, this.dependsOn);
+            if (!classified.admissible)
+                return null;
+            classification = classified.context;
+        }
         // A still-absolute `relativePath` is a report the caller could not
         // relativize — it names somewhere outside the mount. It rides verbatim:
         // prepending the mount root would forge an in-tree name for a foreign

package/dist/provenance/exec-frame.d.ts

@@ -8,10 +8,20 @@
  * `runs/{priorRunId}/...`) so `classifyReadPath` and the collector's
  * `stepPrefix` normalization see the shapes they expect.
  *
+ * A read naming a same-run sibling this step never declared is refused here,
+ * before it reaches the collector: a ref the collector never holds cannot
+ * become an attestation target, so the edge is unrepresentable rather than
+ * merely filtered downstream. Each refused path is logged once per step — an
+ * edge asserted over a step that was still writing is invisible by nature, so a
+ * silent drop would rebuild exactly the blind spot the refusal exists to close,
+ * while re-narrating a path already reported adds no fact and buries the rest.
+ *
  * Degrades safely: a disabled or absent frame records the command with no
- * inputs and no writes (its outputs fall back to leaves at registration).
- * It never throws — provenance is best-effort and must not fail an exec.
+ * inputs and no writes (its outputs fall back to leaves at registration), and a
+ * frame whose every read is refused still records its command. It never throws —
+ * provenance is best-effort and must not fail an exec.
  */
+import type { Logger } from "../lib/logger.js";
 import type { ProvenanceFrame } from "../sandbox/types.js";
 import { type ProvenanceCollector } from "./collector.js";
 /**
@@ -32,6 +42,8 @@ export interface FeedExecFrameArgs {
     readonly durationMs: number | null;
     /** The frame surfaced on `ExecResult.provenance` (may be absent). */
     readonly provenance?: ProvenanceFrame;
+    /** Diagnostics seam. Left unwired, refusals still happen but go unnarrated. */
+    readonly logger?: Logger;
 }
 /**
  * Translate one exec's frame into a collector record. Per-command input