@inflexa-ai/harness 0.31.0 → 0.32.0

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

@@ -35,6 +35,7 @@ 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 { ProvenanceSeam } from "../provenance/seam.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { CitationResolver } from "../citations/types.js";
@@ -111,6 +112,12 @@ export interface ConversationAgentDeps extends EnvironmentStorePaths {
      * at a page reads that same answer.
      */
     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.
+     */
+    readonly provenance?: ProvenanceSeam;
     /**
      * Host resource policy — per-step ceilings + machine budget. `generate_plan`
      * states the ceilings to the planner and validates against them;

package/dist/agents/conversation-agent.js

@@ -122,6 +122,7 @@ export function createConversationAgent(deps) {
             chrome,
             anchorSession: deps.anchorReportSession,
             ...(deps.eyes ? { eyes: deps.eyes } : {}),
+            ...(deps.provenance ? { provenance: deps.provenance } : {}),
             ...(deps.logger ? { logger: deps.logger } : {}),
         }),
         // Display.

package/dist/agents/report-session-agent.d.ts

@@ -38,6 +38,7 @@ import type { ThreadStore } from "../memory/thread-store.js";
 import type { ReferenceResolver } from "../report-model/reference-resolver.js";
 import type { ReportVersionStore } from "../state/report-versions.js";
 import type { ReportSessionStateGateway } from "../tools/report-authoring/authoring-tools.js";
+import type { ProvenanceSeam } from "../provenance/seam.js";
 import { type MakeSessionPagePublisher, type ResolvePageAsset, type ResolvePageUrl } from "../tools/report-session/index.js";
 /** Canonical agent id -- distinct from the id of the old templating agent. */
 export declare const REPORT_SESSION_AGENT_ID: "report-session";
@@ -114,6 +115,14 @@ export interface ReportSessionAgentDeps {
      * tool navigates through a `file://` URL of the page path.
      */
     readonly resolvePageUrl?: ResolvePageUrl;
+    /**
+     * The provenance seam -- the acts of the session as typed events, and the frozen document of the
+     * analysis as opaque bytes. The tools that change the draft, derive a table, preview the page, and
+     * record a version each emit through the session member, thus one bound member carries the whole
+     * session. The preview asks the read member before each render, and the page then carries the
+     * document. An unbound member emits nothing, or gives absence, and every tool acts the same.
+     */
+    readonly provenance?: ProvenanceSeam;
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
 }

package/dist/agents/report-session-agent.js

@@ -39,8 +39,11 @@ const REPORT_SESSION_MAX_ITERATIONS = 200;
 /** Build the report `AgentDefinition` with every tool bound to its deps. */
 export function createReportSessionAgent(deps) {
     const { model, pool, embedding, workspaceFs, gateway, resolveWorkspaceRoot, store, threads, chrome, eyes, makeResolver, resolvePageAsset, logger } = deps;
-    const { derivations, runDerivation, runAuthorizer, makeSessionPages, resolvePageUrl } = deps;
-    const authoring = createReportAuthoringTools(gateway);
+    const { derivations, runDerivation, runAuthorizer, makeSessionPages, resolvePageUrl, provenance } = deps;
+    // The seam rides into each tool that lands an act of the session, thus the composition binds it one
+    // time and no tool reads a second source.
+    const observation = provenance ? { provenance } : {};
+    const authoring = createReportAuthoringTools(gateway, { ...observation, ...(logger ? { logger } : {}) });
     const tools = [
         // The read surface toward the analysis. It roams the tree read-only.
         createReadFileTool(workspaceFs),
@@ -75,6 +78,7 @@ export function createReportSessionAgent(deps) {
             derivations,
             ...(runDerivation ? { runDerivation } : {}),
             ...(runAuthorizer ? { runAuthorizer } : {}),
+            ...observation,
             ...(logger ? { logger } : {}),
         }),
         // The render-and-preview tool. It resolves the page root per call.
@@ -84,6 +88,9 @@ export function createReportSessionAgent(deps) {
             ...(makeResolver ? { makeResolver } : {}),
             ...(resolvePageAsset ? { resolvePageAsset } : {}),
             ...(makeSessionPages ? { makeSessionPages } : {}),
+            // The preview is the one site that carries the document into the page, thus the read member
+            // reaches this tool alone.
+            ...observation,
             ...(logger ? { logger } : {}),
         }),
         // The eyes tool. It opens the rendered page in headless Chrome.
@@ -103,6 +110,7 @@ export function createReportSessionAgent(deps) {
             threads,
             resolveWorkspaceRoot,
             ...(makeResolver ? { makeResolver } : {}),
+            ...observation,
             ...(logger ? { logger } : {}),
         }),
     ];

package/dist/app/chat-turn.d.ts

@@ -16,10 +16,21 @@ import type { Pool } from "pg";
 import { type ThreadType } from "../memory/thread-store.js";
 import { type AssembledMessages } from "./message-assembly.js";
 import type { Logger } from "../lib/logger.js";
+import { type ProvenanceSeam } from "../provenance/seam.js";
 export interface PrepareChatTurnDeps {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     readonly pool: Pool;
+    /**
+     * The provenance seam. The turn reads its session emit member, and no other
+     * member. The turn holds the one site that writes the conversation thread of
+     * an analysis, thus it is the one site that can tell the embedder the true
+     * moment of that creation.
+     *
+     * The member is optional and fire-and-forget, the same as it is at each site
+     * of a report session.
+     */
+    readonly provenance?: ProvenanceSeam;
 }
 export interface PrepareChatTurnParams {
     readonly analysisId: string;

package/dist/app/chat-turn.js

@@ -21,6 +21,7 @@ import { loadAnalysisStatus, queryNonTerminalRunsByAnalysis } from "../state/ind
 import { assembleMessages } from "./message-assembly.js";
 import { renderRunActivity, renderRunActivityUnavailable, RUN_ACTIVITY_DETAIL_LIMIT } from "./run-activity.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { bindSessionEmit } from "../provenance/seam.js";
 /**
  * Prepare one chat turn: resolve thread ownership, seed the title, load
  * analysis status, and assemble the message array. Input sanitization stays
@@ -29,6 +30,10 @@ import { createNoopLogger } from "../lib/console-logger.js";
 export async function prepareChatTurn(deps, params) {
     const { pool } = deps;
     const { analysisId, threadId, userInput } = params;
+    const logger = (deps.logger ?? createNoopLogger()).named("harness.chat");
+    // An unbound member gives a call that does nothing, thus the emit below needs
+    // no test of its own.
+    const observe = bindSessionEmit(deps.provenance, logger);
     // Ownership check before any read/write of the thread — a `threadId`
     // owned by a different analysis is indistinguishable from a missing one.
     const store = createThreadStore(pool);
@@ -54,13 +59,24 @@ export async function prepareChatTurn(deps, params) {
                 title: deriveThreadTitle(userInput),
             }));
             threadType = created.threadType;
+            // The row that comes back is not proof that this call wrote it. The read
+            // above hides an archived thread, and the idempotent insert then reads
+            // that same row back. Thus a turn on an archived thread reaches here with
+            // a row that a different site created, and an emit would record a start
+            // that never happened.
+            //
+            // This site writes a live conversation thread and nothing else. An
+            // archived row, or a row of another kind, is therefore one that already
+            // existed. A root session has no parent, thus the event carries none.
+            if (created.deletedAt === null && created.threadType === "conversation") {
+                observe({ type: "create-session", analysisId, threadId, sessionKind: created.threadType });
+            }
         }
         else if (!existing.title || existing.title.length === 0) {
             unwrapOrThrow(await store.updateTitle(threadId, deriveThreadTitle(userInput)));
         }
     }
     catch (err) {
-        const logger = (deps.logger ?? createNoopLogger()).named("harness.chat");
         logger.warn("title-seed failed (non-fatal)", logger.errorFields(err));
     }
     const analysisState = await loadAnalysisStatus(pool, analysisId).unwrapOr(null);

package/dist/app/spawn-report-session.d.ts

@@ -66,6 +66,7 @@ import type { AcquireEyes } from "../lib/eyes.js";
 import type { Logger } from "../lib/logger.js";
 import type { CapturePage } from "../lib/page-capture.js";
 import { type Thread, type ThreadInputError, type ThreadPage, type ThreadType } from "../memory/thread-store.js";
+import { type ProvenanceSeam } from "../provenance/seam.js";
 import type { EnsureSessionStateResult } from "./report-session-runtime.js";
 /**
  * A spawn the operation refuses before it writes a row. Distinct from
@@ -192,6 +193,17 @@ export interface ReportSessionSpawnDeps {
      * is idempotent.
      */
     readonly anchorSession?: (threadId: string) => Promise<EnsureSessionStateResult>;
+    /**
+     * The provenance seam. The spawn reads its session emit member, and no other
+     * member. The spawn is the birth of the session, thus it is the one site that
+     * can tell the embedder the true moment of the ask. A consumer that waits for
+     * the first authoring act reads a later moment, and it reads nothing at all
+     * for a session that stays empty.
+     *
+     * The member is optional and fire-and-forget, the same as it is at each
+     * authoring site.
+     */
+    readonly provenance?: ProvenanceSeam;
     /** Operational logging seam. An omitted logger falls back to the no-op. */
     readonly logger?: Logger;
 }

package/dist/app/spawn-report-session.js

@@ -65,6 +65,7 @@ import { createNoopLogger } from "../lib/console-logger.js";
 import { conversationRecordTurn, createThreadHistory } from "../memory/thread-history.js";
 import { createThreadStore } from "../memory/thread-store.js";
 import { createWorkingMemory } from "../memory/working-memory.js";
+import { bindSessionEmit } from "../provenance/seam.js";
 const _assertDomainError = true;
 /**
  * Whether the composition gives a route to a look at the rendered page. The
@@ -165,6 +166,9 @@ export function createReportSessionSpawn(deps) {
     // The routes are fixed at construction, thus the gate reads one boolean and
     // never a live probe of the sidecar.
     const eyesAvailable = compositionHasEyes(deps);
+    // An unbound member gives a call that does nothing, thus the spawn emits at
+    // one site with no test of its own.
+    const observe = bindSessionEmit(deps.provenance, log);
     /**
      * Write the one seed message of the child and give the child back. The
      * message rides as a record, not as user input: nobody typed it in the child
@@ -250,7 +254,7 @@ export function createReportSessionSpawn(deps) {
         if (!eyesAvailable) {
             return errAsync({ type: "no_browser", op: OP, parentThreadId, detail: NO_BROWSER_DETAIL });
         }
-        return store.getThread(parentThreadId).andThen((parent) => {
+        const spawned = store.getThread(parentThreadId).andThen((parent) => {
             // An absent parent and an archived one arrive the same way — `getThread`
             // filters the tombstone — and both refuse as `parent_not_found`.
             if (parent === null) {
@@ -288,6 +292,22 @@ export function createReportSessionSpawn(deps) {
                     .andThen((child) => ResultAsync.fromSafePromise(pinSessionSnapshot(child))));
             });
         });
+        // The emit rides the ok channel alone, thus a refusal and a fault tell the
+        // embedder nothing. The child row is on disk at this point, and no
+        // authoring act of the session ran yet.
+        //
+        // The kind comes from the row and not from the input, because the insert
+        // is idempotent and the store tells a caller to read the type back.
+        return spawned.map((child) => {
+            observe({
+                type: "create-session",
+                analysisId: child.analysisId,
+                threadId: child.threadId,
+                sessionKind: child.threadType,
+                parentThreadId,
+            });
+            return child;
+        });
     }
     function listReportSessions(analysisId, paging = {}) {
         return store.listThreads({ analysisId, type: "report", ...paging });

package/dist/contracts/report-blocks.d.ts

@@ -200,15 +200,15 @@ export declare const ChartAxesSchema: z.ZodObject<{
     x: z.ZodOptional<z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         scale: z.ZodOptional<z.ZodEnum<{
-            log: "log";
             linear: "linear";
+            log: "log";
         }>>;
     }, z.core.$strict>>;
     y: z.ZodOptional<z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         scale: z.ZodOptional<z.ZodEnum<{
-            log: "log";
             linear: "linear";
+            log: "log";
         }>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -297,15 +297,15 @@ export declare const ChartCompositionSchema: z.ZodObject<{
         x: z.ZodOptional<z.ZodObject<{
             title: z.ZodOptional<z.ZodString>;
             scale: z.ZodOptional<z.ZodEnum<{
-                log: "log";
                 linear: "linear";
+                log: "log";
             }>>;
         }, z.core.$strict>>;
         y: z.ZodOptional<z.ZodObject<{
             title: z.ZodOptional<z.ZodString>;
             scale: z.ZodOptional<z.ZodEnum<{
-                log: "log";
                 linear: "linear";
+                log: "log";
             }>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
@@ -724,15 +724,15 @@ export declare const ChartBlockSchema: z.ZodObject<{
             x: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    log: "log";
                     linear: "linear";
+                    log: "log";
                 }>>;
             }, z.core.$strict>>;
             y: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    log: "log";
                     linear: "linear";
+                    log: "log";
                 }>>;
             }, z.core.$strict>>;
         }, z.core.$strict>>;
@@ -1168,15 +1168,15 @@ export declare const ATOM_BLOCK_SCHEMAS: readonly [z.ZodObject<{
             x: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    log: "log";
                     linear: "linear";
+                    log: "log";
                 }>>;
             }, z.core.$strict>>;
             y: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    log: "log";
                     linear: "linear";
+                    log: "log";
                 }>>;
             }, z.core.$strict>>;
         }, z.core.$strict>>;

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

@@ -240,9 +240,9 @@ export declare const StepOutputFileSchema: z.ZodObject<{
     fileType: z.ZodEnum<{
         output: "output";
         summary: "summary";
-        script: "script";
-        figure: "figure";
         log: "log";
+        figure: "figure";
+        script: "script";
         notebook: "notebook";
     }>;
     description: z.ZodString;
@@ -259,9 +259,9 @@ export declare const StepOutputPartSchema: z.ZodObject<{
         fileType: z.ZodEnum<{
             output: "output";
             summary: "summary";
-            script: "script";
-            figure: "figure";
             log: "log";
+            figure: "figure";
+            script: "script";
             notebook: "notebook";
         }>;
         description: z.ZodString;
@@ -597,9 +597,9 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         fileType: z.ZodEnum<{
             output: "output";
             summary: "summary";
-            script: "script";
-            figure: "figure";
             log: "log";
+            figure: "figure";
+            script: "script";
             notebook: "notebook";
         }>;
         description: z.ZodString;

package/dist/index.d.ts

@@ -36,6 +36,9 @@ export type { ProvenanceCollector } from "./provenance/collector.js";
 export { UnavailableSessionPagePublisher } from "./tools/report-session/session-page-publisher.js";
 export type { MakeSessionPagePublisher, SessionPagePublisher, SessionPageMintResult } from "./tools/report-session/session-page-publisher.js";
 export type { ResolvePageUrl, SessionPageAccess } from "./tools/report-session/index.js";
+export { bindReadExport, bindSessionEmit } from "./provenance/seam.js";
+export type { ProvenanceExport, ProvenanceSeam, RunProvenanceEvent, SessionProvenanceEvent } from "./provenance/seam.js";
+export type { DerivationSource } from "./state/report-session-state.js";
 export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 export type { RunLauncher, LaunchOptions } from "./execution/run-launcher.js";
 export { createDbosWorkflowPurger } from "./execution/dbos-workflow-purger.js";
@@ -140,7 +143,7 @@ export { deliverExecEvent, execEventTopic } from "./sandbox/deliver-exec-event.j
 export { ExecEventMessageSchema } from "./sandbox/types.js";
 export type { ExecEventMessage, DoneMarker } from "./sandbox/types.js";
 export { registerExecuteAnalysis } from "./workflows/execute-analysis.js";
-export type { ExecuteAnalysisDeps, ExecuteAnalysisInput, ExecuteAnalysisResult, RunObservation, RunProvenanceEvent, RunStepObservation, StepRuntimeStatus, } from "./workflows/execute-analysis.js";
+export type { ExecuteAnalysisDeps, ExecuteAnalysisInput, ExecuteAnalysisResult, RunObservation, RunStepObservation, StepRuntimeStatus, } from "./workflows/execute-analysis.js";
 export { registerSandboxStep } from "./workflows/sandbox-step.js";
 export type { SandboxStepDeps, SandboxStepInput, SandboxStepResult, SandboxAgentBuildContext } from "./workflows/sandbox-step.js";
 export { DEFAULT_CLAIM_INVESTIGATION_CONFIG } from "./workflows/target-assessment/investigation/index.js";

package/dist/index.js

@@ -47,6 +47,14 @@ export { createNoopArtifactRegistry } from "./execution/noop-artifact-registry.j
 // state. The URL seam of the eyes rides beside the publisher factory: a host whose
 // browser cannot reach the workspace tree binds a served URL for the look.
 export { UnavailableSessionPagePublisher } from "./tools/report-session/session-page-publisher.js";
+// Seam: the one provenance surface. The embedder records the facts of a run and the acts of a
+// session in the document of the analysis that it owns, and it gives the bytes of that document
+// back for the report page. Thus the seam and its vocabulary belong on the front door: an embedder
+// cannot type its realization without them. The two binders ride beside the types, because an
+// embedder that calls `prepareChatTurn` or one tool factory directly binds the same total forms
+// that the assembly binds. `DerivationSource` rides beside the event union, because the derivation
+// event carries the chain of the derived table.
+export { bindReadExport, bindSessionEmit } from "./provenance/seam.js";
 // Run launching.
 export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 // Seam: workflow-ledger reclamation — cancels and deletes an analysis's rows in

package/dist/prompts/briefing.d.ts

@@ -36,7 +36,9 @@ export declare const STEP_TASK_FIELDS: readonly ["name", "question", "descriptio
  * threaded separately through the workflow input, execution knobs, and result
  * fields populated after the step runs. `depends_on` is not rendered here
  * because the dependencies appear as {@link renderUpstream} blocks — with their
- * results — rather than as bare ids.
+ * results — rather than as bare ids. `resources` renders as its own
+ * {@link renderResources} section, because the budget is an execution bound,
+ * not a task instruction.
  */
 export declare const STEP_NON_TASK_FIELDS: readonly ["id", "track", "step_type", "depends_on", "status", "resources", "agent", "timeout", "maxSteps", "summary", "artifactIds", "error"];
 /**
@@ -66,6 +68,15 @@ export interface WorkspaceFrame {
 /** The in-sandbox analysis root of a frame — the read-only mount of the whole tree. */
 export declare function analysisRootOf(frame: WorkspaceFrame): string;
 export declare function renderWorkspace(frame: WorkspaceFrame): string;
+/**
+ * The cpu and memory budget of the step, with the one rule that keeps a
+ * parallel workload inside it. The mounted cpu files make `detectCores()` and
+ * `os.cpu_count()` report the quota, thus the fork count is right by default.
+ * The thread pools default to one thread (see `sandbox/thread-env.ts`), and
+ * only the agent knows when a step is thread-parallel. Thus the briefing names
+ * the budget and the rule, and the agent raises a pool per command.
+ */
+export declare function renderResources(resources: AnalysisStep["resources"]): string;
 /**
  * What dataset the analysis is holding, projected from the persisted profile.
  * Absent or not-yet-profiled → `""`, and the agent falls back to its always-on

package/dist/prompts/briefing.js

@@ -45,7 +45,9 @@ export const STEP_TASK_FIELDS = [
  * threaded separately through the workflow input, execution knobs, and result
  * fields populated after the step runs. `depends_on` is not rendered here
  * because the dependencies appear as {@link renderUpstream} blocks — with their
- * results — rather than as bare ids.
+ * results — rather than as bare ids. `resources` renders as its own
+ * {@link renderResources} section, because the budget is an execution bound,
+ * not a task instruction.
  */
 export const STEP_NON_TASK_FIELDS = [
     "id",
@@ -117,6 +119,29 @@ export function renderWorkspace(frame) {
         `Analysis root (read-only): \`${analysisRoot}\` — inputs at \`${analysisRoot}/data/inputs/\`, prior runs at \`${analysisRoot}/runs/\`.`,
     ]));
 }
+// ── (2b) Resources ────────────────────────────────────────────────────
+/**
+ * The cpu and memory budget of the step, with the one rule that keeps a
+ * parallel workload inside it. The mounted cpu files make `detectCores()` and
+ * `os.cpu_count()` report the quota, thus the fork count is right by default.
+ * The thread pools default to one thread (see `sandbox/thread-env.ts`), and
+ * only the agent knows when a step is thread-parallel. Thus the briefing names
+ * the budget and the rule, and the agent raises a pool per command.
+ */
+export function renderResources(resources) {
+    if (!resources)
+        return "";
+    const cores = Math.max(1, Math.floor(resources.cpu));
+    const items = [
+        `CPU: ${resources.cpu} ${resources.cpu === 1 ? "core" : "cores"} (hard quota). Memory: ${resources.memoryGb} GB (hard limit — exceeding it kills the process).`,
+        `Core-count calls (\`parallel::detectCores()\`, \`os.cpu_count()\`) report this quota — worker counts sized from them are already right, nothing to raise.`,
+        `BLAS/OpenMP thread pools default to **1 thread** (\`OMP_NUM_THREADS\` etc.). For a thread-parallel single-process step, raise them per command via \`execute_command\`'s \`env\`, up to ${cores}.`,
+        `The one rule: workers × threads-per-worker must stay ≤ ${cores}. A mix is fine while the product holds.`,
+    ];
+    if (resources.gpu)
+        items.push(`GPU: ${resources.gpu.count}.`);
+    return section("Resources (hard limits)", bullets(items));
+}
 // ── (3) Data orientation ──────────────────────────────────────────────
 /**
  * What dataset the analysis is holding, projected from the persisted profile.
@@ -168,6 +193,7 @@ export function composeStepBriefing(briefing) {
     return [
         renderTask(briefing.step),
         renderWorkspace(briefing.workspace),
+        renderResources(briefing.step.resources),
         renderOrientation(briefing.profile, briefing.workspace.analysisId),
         renderUpstream(briefing.upstream),
     ]

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

@@ -22,5 +22,5 @@
  * `prompts/briefing.ts`), which is composed per dispatch and where per-step
  * content belongs.
  */
-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## 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";
+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";
 export declare const sandboxAnalysisStepStandardsPrompt = "# Sandbox Analysis-Step Conventions\n\nThese apply to plannable analysis steps \u2014 agents that produce reproducible\nscript + output + figure artifacts. They do NOT apply to data profiling or\nreport building (those agents opt out via\n`appendAnalysisStepStandards: false`).\n\n## Language Policy\n\nPython is the DEFAULT language. Use R when:\n(a) No adequate Python equivalent (e.g. minfi, ANCOM-BC2, ChAMP).\n(b) The R implementation is significantly more mature.\n(c) The task explicitly requires an R-only package.\n\nChoose native R or rpy2 based on scope:\n- **Isolated R calls** in a Python pipeline \u2192 rpy2 bridge.\n  Example: DESeq2 for one DE step, fgsea for enrichment.\n- **R-dominant pipeline** where most steps use R packages \u2192 write\n  **native R scripts**. Do not wrap an entire R pipeline in rpy2.\n  Examples: microbiome (DADA2 \u2192 phyloseq \u2192 vegan \u2192 ANCOM-BC2),\n  DNA methylation (minfi \u2192 ChAMP \u2192 DMRcate), untargeted metabolomics\n  (XCMS \u2192 CAMERA).\n\nNative R scripts follow the same standards as Python: structured logging\n(`message()`), named constants, documented functions. Save final outputs\nas CSV (and optionally AnnData) for cross-agent consumption.\n\n## Data Format Standards\n\n- **AnnData (.h5ad)** is the UNIVERSAL container for sample-by-feature\n  data across ALL modalities \u2014 bulk RNA-seq, proteomics, metabolomics,\n  microarray, methylation, single-cell. Samples in `.obs`, features in\n  `.var`, values in `.X`, layers in `.layers`, embeddings in `.obsm`,\n  unstructured results in `.uns`.\n- **MuData (.h5mu)** for multi-modal data (CITE-seq, Multiome,\n  multi-omics integration).\n- Store sample metadata in `.obs`, feature annotations in `.var`. Do\n  NOT write separate metadata CSV files unless explicitly needed.\n- **Intermediate analysis objects**: save as `.h5ad` or `.h5mu`. Do\n  NOT save as `.rds` or `.pkl`. When R packages produce R objects\n  (DESeqDataSet, phyloseq, SingleCellExperiment), convert key results\n  back to AnnData or pandas.\n- **Tabular results**: CSV with human-readable column names\n  (`log2_fold_change`, `adjusted_pvalue`, not `lfc`/`padj`).\n- **Genomic data**: VCF/BED/BAM are acceptable primary containers.\n  Derived summary statistics go in AnnData or CSV.\n- **Dual-format output**: when producing modality-specific results,\n  also output a generic CSV for downstream cross-cutting agents.\n\n## Figure Standards\n\n- **PNG at 300 DPI** for preview AND **PDF (vector)** for publication,\n  same base filename with different extensions.\n- **Colorblind-safe palettes** \u2014 viridis family as default. Never use\n  red-green as the sole distinguishing feature.\n- **Clean minimal themes**: matplotlib `seaborn-v0_8-whitegrid` or\n  equivalent; ggplot2 `theme_classic()` or `theme_minimal()`.\n- **Complete labels**: title, axis labels with units, legend.\n- **Statistical annotations** where applicable (p-values, significance\n  brackets, effect sizes).\n- No default matplotlib/ggplot styling, no cut-off labels, no\n  overlapping text.\n\n## Directory Structure\n\nYour working directory has five subdirectories \u2014 write each kind of artifact\nto its own (paths are relative to your working directory):\n\n```\nscripts/    Analysis scripts (.py, .R)\noutput/     Results: CSV, AnnData (.h5ad), MuData (.h5mu), JSON\nfigures/    Visualizations: PNG (300 DPI) + PDF (vector), same base name\nlogs/       Execution logs from long-running commands\nnotebooks/  Reserved (currently unused)\n```\n\nPut data results in `output/`, not at the working-directory root. For\nlong-running commands, redirect stdout/stderr to a file in `logs/`:\n```python\nsubprocess.run(cmd, stdout=open(\"logs/deseq2_run.log\", \"w\"), stderr=subprocess.STDOUT)\n```\n\n## Code Quality\n\n**Functions** for any non-trivial logic. Each logical operation\n(load, QC, fit, plot) gets its own function with a docstring. Top-level\nscript flow should read like an outline \u2014 call functions, not inline\nlogic.\n\n```python\n# %% [markdown]\n# ## Differential Expression\n\n# %%\ndef run_deseq2(counts: pd.DataFrame, metadata: pd.DataFrame, design: str) -> pd.DataFrame:\n    \"\"\"Run DESeq2 via rpy2 and return results as a DataFrame.\"\"\"\n    ...\n\nde_results = run_deseq2(counts, metadata, \"~ condition + batch\")\n```\n\n**Structured logging**, not `print()`:\n\n- Python \u2014 `logging.getLogger()`:\n  `logger.info(\"Loaded %d samples, %d genes\", n_samples, n_genes)`\n- R \u2014 `message()` / `warning()`:\n  `message(sprintf(\"Loaded %d samples\", n_samples))`\n\nReserve `print()` / `cat()` for intentional data display in notebook\ncells only.\n\n**Validate at function boundaries**. Fail fast with clear messages.\nUse `try/except` only when recovery is meaningful.\n\n**Type hints** on Python function signatures. Add them \u2014 they document\nintent and catch mistakes early.\n\n**Named constants** for thresholds, cutoffs, parameters in the first\ncode cell:\n```python\n# %% Parameters\nRANDOM_SEED = 42\nFDR_THRESHOLD = 0.05\nMIN_LOG2FC = 1.0\n```\n\n**R specifics**: load packages at the top (never inside functions).\nUse `<-` for assignment. Use `message()` / `warning()` not `cat()` /\n`print()`.\n\n## Scripts\n\n- Start with a header comment (title + description).\n- Parameters go in the first code block.\n- Set random seeds for reproducibility.\n- Scripts must be independently re-runnable.\n- **Lint Python scripts with `ruff check <script.py>`** via\n  `execute_command` before executing. `ruff` is pre-installed. This\n  catches import errors, undefined names, and common bugs early.\n\n## Cleanup\n\nWhen a script fails, delete the failed script from `scripts/` and any\npartial output files before writing a corrected version. Only final\nworking scripts should remain. Use `list_files` to verify.\n\n## Interpretation & Literature Grounding\n\nGround findings in the research literature as you work \u2014 not as a\nfinal step:\n\n1. When you identify a significant finding (DE genes, enriched\n   pathways, hub genes, quality issues), search PubMed with\n   `pubmed({action:\"search\"})`.\n2. For relevant hits, call `pubmed({action:\"details\"})` for abstracts and\n   PMIDs. Note short citations (e.g. \"Smith et al., Nature 2023\").\n3. Assess novelty per finding: **novel** (searched, nothing found),\n   **confirmed** (directly supported), **partially confirmed**,\n   **contradicted**, **expected** (domain knowledge, no citation\n   needed).\n4. Document the search even when no references are found. \"Novel\"\n   means you looked and found nothing \u2014 not that you didn't look.\n\nYour structured output captures this interpretation. It is your\nscientific assessment of what the results mean.\n\n## Analysis-Step Anti-Patterns\n\n- **Ignoring script errors.** Read the error, diagnose the root\n  cause, fix the script. Do not move on.\n- **Placeholder or dummy output.** If an analysis cannot produce\n  meaningful results, report the reason clearly instead of faking\n  results.\n- **Monolithic scripts.** Keep scripts under 300 lines. Split into\n  logical sections with markdown annotations.\n- **`print()` for logging.** Use `logging` (Python) or `message()`\n  (R). `print()` is for intentional data display only.\n- **Inline logic without functions.** Wrap non-trivial operations in\n  functions with docstrings and typed parameters.\n- **Magic numbers.** Define thresholds and cutoffs as named constants.\n";

package/dist/prompts/sandbox-standards.js

@@ -135,6 +135,33 @@ up front.
   \`AnnotationHub\` — they all reach for the network and will fail. Load from an
   inventory path instead. Do NOT download data or install packages at runtime.
 
+## CPU Budget and Parallelism
+
+Your briefing names this step's CPU quota and memory limit. The container's
+core-count calls (\`parallel::detectCores()\`, \`os.cpu_count()\`) report the
+quota, so worker counts sized from them are safe.
+
+BLAS/OpenMP thread pools default to **1 thread** (\`OMP_NUM_THREADS\`,
+\`OPENBLAS_NUM_THREADS\`, \`MKL_NUM_THREADS\`, …). A forked worker inherits its
+parent's pool size, so this default is what keeps \`mclapply\` /
+\`multiprocessing\` from running workers × threads on a quota sized for one of
+them. The rule: **workers × threads-per-worker must not exceed the quota.** A
+mix is fine while the product stays inside it.
+
+- **Fork/worker parallelism** (\`mclapply\`, \`BiocParallel\`, \`joblib\`,
+  \`multiprocessing\`): size the workers from the reported core count and leave
+  the thread defaults alone — there is nothing to raise. \`joblib\` also
+  divides its own thread budget across its workers; do not manage it.
+- **Thread parallelism** (one process: xgboost, WGCNA, data.table, polars, a
+  single large BLAS fit): raise the thread variables for that command through
+  \`execute_command\`'s \`env\`, e.g.
+  \`env: { "OMP_NUM_THREADS": "4", "OPENBLAS_NUM_THREADS": "4" }\` on a 4-CPU
+  quota.
+
+Exceeding the quota does not kill the step — the cgroup throttles it — but an
+oversubscribed step runs slower and can starve the exec server that runs your
+commands.
+
 ## Output Contract — Persisted Files Are the Deliverable
 
 This is a hard requirement, not a convention. **Your deliverable is persisted