@inflexa-ai/harness 0.31.1 → 0.33.0

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

@@ -79,6 +79,18 @@ export type SandboxError = {
     readonly sandboxId?: string;
     readonly status?: number;
     readonly cause: unknown;
+} | {
+    /**
+     * The farm source refused the analysis: the resolver returned
+     * `unavailable`, or it threw. `reason` carries the text of the
+     * embedder verbatim, thus the surface can show why the farm is
+     * not usable yet.
+     */
+    readonly type: "farm_unavailable";
+    readonly op: string;
+    readonly analysisId: string;
+    readonly reason: string;
+    readonly cause?: unknown;
 };
 /**
  * The HTTP/driver status a backend SDK error carries. dockerode exposes it on

package/dist/sandbox/sandbox-error.js

@@ -66,6 +66,8 @@ export function describeSandboxError(e) {
             return `sandbox teardown failed (${e.op}${e.sandboxId ? `: ${e.sandboxId}` : ""})`;
         case "liveness_failed":
             return `sandbox liveness probe failed (${e.op}${e.sandboxId ? `: ${e.sandboxId}` : ""})`;
+        case "farm_unavailable":
+            return `farm unavailable (${e.op}: ${e.analysisId}) — ${e.reason}`;
     }
 }
 /**

package/dist/sandbox/types.d.ts

@@ -30,6 +30,124 @@ export declare const SandboxTransportSchema: z.ZodEnum<{
     callback: "callback";
 }>;
 export type SandboxTransport = z.infer<typeof SandboxTransportSchema>;
+/**
+ * The declared owner of the sandbox toolchain. `"image"` states that the
+ * image owns the interpreters, conda, and Node. `"store"` states that the
+ * mounted store owns them. An absent config field means `"store"`, thus an
+ * old embedder keeps its environment and its prompt prefix. The harness keys
+ * the resolver env and the orient-core prompt text on this declared value
+ * only, and it never infers its host.
+ */
+export type ToolchainSource = "image" | "store";
+/**
+ * A resolved farm. `farmPath` is a host directory for the Docker backend,
+ * and a PVC-relative path for the K8s backend. `cachePath` is the optional
+ * per-analysis read-write cache. When it is present, the backend mounts it
+ * at `/mnt/libs/cache`.
+ */
+export interface FarmLocation {
+    readonly farmPath: string;
+    readonly cachePath?: string;
+}
+/** The answer of a farm resolver: a usable farm, or a refusal that carries the reason of the embedder. */
+export type FarmResolution = {
+    readonly kind: "available";
+    readonly location: FarmLocation;
+} | {
+    readonly kind: "unavailable";
+    readonly reason: string;
+};
+/**
+ * Resolve the farm of one analysis. A backend calls this at each
+ * `createSandbox`, thus a new farm reaches the next sandbox with no restart.
+ *
+ * The resolver carries the mount gate when the backend cannot. On a
+ * volume-backed farm (K8s) the host cannot stat `farmPath`, thus the
+ * resolver MUST answer `unavailable` when the `inflexa.lock` of the farm
+ * does not parse. A backend with a host-readable path (Docker) proves the
+ * lock itself, after the resolution.
+ */
+export type ResolveAnalysisFarm = (analysisId: string) => Promise<FarmResolution>;
+/**
+ * Where the farm of an analysis comes from. A required field of each sandbox
+ * backend config — the harness never invents a farm location, and it reads
+ * no store-root `current` pointer. `fixed` names one farm for every
+ * analysis. `per-analysis` supplies a resolver.
+ */
+export type FarmSource = {
+    readonly kind: "fixed";
+    readonly location: FarmLocation;
+} | {
+    readonly kind: "per-analysis";
+    readonly resolve: ResolveAnalysisFarm;
+};
+/**
+ * One package ask of the farm-extension seam. `version` pins one exact
+ * version. `ecosystem` qualifies a name that both tracks can hold. Without
+ * it, a name that both tracks hold comes back as a `collision` outcome.
+ */
+export interface PackageRequest {
+    readonly name: string;
+    readonly version?: string;
+    readonly ecosystem?: "python" | "r";
+}
+/**
+ * One outcome per request, index-aligned with the request array.
+ *
+ * `name` echoes the REQUESTED spelling verbatim, never a normalized form. A
+ * caller quotes it into a remedy (`inflexa store add <name>`), and an R name
+ * is case-sensitive with dots, thus a normalized echo would name a package
+ * that no repository holds.
+ *
+ * - `linked` — the pool held the package, and this call linked it.
+ * - `present` — the farm linked it already.
+ * - `absent` — the pool does not hold it. `acquisitionPossible` states that
+ *   the host can acquire that ecosystem, or that it cannot. `detail`, when
+ *   the realization gives one, classifies the miss in host terms — in
+ *   flight, failed with a recorded reason, or never requested — and the
+ *   launch refusal renders it beside the name.
+ * - `collision` — the request resolves to two store directories: two
+ *   versions of one distribution, or one name that both tracks hold. The
+ *   outcome is terminal for the request. `detail`, when the realization
+ *   gives one, names the two pins and the packages that need each side —
+ *   without it, a caller must guess which package pulls each pin, and a
+ *   wrong guess sends it into store surgery.
+ * - `unavailable` — the link pass itself could not answer: an unreadable
+ *   dependency graph, a locked farm. The reason says why. It says NOTHING
+ *   about the presence of the package, and it must never render as an
+ *   absence — a false absence sends a caller chasing packages the pool
+ *   holds.
+ */
+export type PackageRequestOutcome = {
+    readonly kind: "linked";
+    readonly name: string;
+    readonly version: string;
+} | {
+    readonly kind: "present";
+    readonly name: string;
+    readonly version: string;
+} | {
+    readonly kind: "absent";
+    readonly name: string;
+    readonly acquisitionPossible: boolean;
+    readonly detail?: string;
+} | {
+    readonly kind: "collision";
+    readonly name: string;
+    readonly storeDirs: readonly [string, string];
+    readonly detail?: string;
+} | {
+    readonly kind: "unavailable";
+    readonly name: string;
+    readonly reason: string;
+};
+/**
+ * The farm-extension seam. The realization of the embedder links host-staged
+ * packages into the farm of the analysis. It never installs, downloads, or
+ * acquires. A link is live in a sandbox that already runs, because the farm
+ * rides a bind mount.
+ */
+export type ExtendAnalysisFarm = (analysisId: string, requests: readonly PackageRequest[]) => Promise<readonly PackageRequestOutcome[]>;
 /**
  * Per-sandbox-machine liveness verdict. `oomKilled` is meaningful only when
  * `alive` is false: true when the backend reports the machine was killed for

package/dist/schemas/artifact-manifest.d.ts

@@ -8,9 +8,9 @@ import { z } from "zod";
 /** Artifact type inferred from the step subdirectory. */
 export declare const ArtifactTypeSchema: z.ZodEnum<{
     output: "output";
-    script: "script";
-    figure: "figure";
     log: "log";
+    figure: "figure";
+    script: "script";
     notebook: "notebook";
 }>;
 export type ArtifactType = z.infer<typeof ArtifactTypeSchema>;
@@ -22,9 +22,9 @@ export declare const ArtifactManifestEntrySchema: z.ZodObject<{
     size: z.ZodNumber;
     type: z.ZodEnum<{
         output: "output";
-        script: "script";
-        figure: "figure";
         log: "log";
+        figure: "figure";
+        script: "script";
         notebook: "notebook";
     }>;
     hash: z.ZodOptional<z.ZodString>;

package/dist/schemas/plan-schemas.d.ts

@@ -17,6 +17,7 @@ export declare const PlanStepSchema: z.ZodObject<{
     constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
     acceptance_criteria: z.ZodArray<z.ZodString>;
     caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    packages: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;
     depends_on: z.ZodArray<z.ZodString>;
     resources: z.ZodNonOptional<z.ZodOptional<z.ZodObject<{
         cpu: z.ZodNumber;
@@ -49,6 +50,7 @@ export declare const PlannerPlanSchema: z.ZodObject<{
         constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
         acceptance_criteria: z.ZodArray<z.ZodString>;
         caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        packages: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;
         depends_on: z.ZodArray<z.ZodString>;
         resources: z.ZodNonOptional<z.ZodOptional<z.ZodObject<{
             cpu: z.ZodNumber;
@@ -90,6 +92,7 @@ export declare const PlanningAgentOutputSchema: z.ZodObject<{
             constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
             acceptance_criteria: z.ZodArray<z.ZodString>;
             caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            packages: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;
             depends_on: z.ZodArray<z.ZodString>;
             resources: z.ZodNonOptional<z.ZodOptional<z.ZodObject<{
                 cpu: z.ZodNumber;

package/dist/schemas/plan-schemas.js

@@ -17,7 +17,7 @@ export const PlanStepSchema = AnalysisStepSchema.omit({
     error: true,
     maxSteps: true,
 })
-    .required({ agent: true, resources: true })
+    .required({ agent: true, resources: true, packages: true })
     .extend({
     agent: z.enum(plannableAgentIds).describe("Sandbox agent ID, routed by the step's primary data object. Must be one of the available agents."),
 });

package/dist/schemas/validate-plan.js

@@ -109,7 +109,26 @@ export function validatePlan(plan, options) {
                 `step-directory convention; "${SYNTHESIS_STEP_ID}" is the run-level synthesis phase)`);
         }
     }
-    // 6. Step-id path safety. The id becomes the `runs/{runId}/{stepId}` directory
+    // 6. Package entries are requirements, never locations. A path, a URL, or
+    //    a store directory in a plan would publish an installer detail as an
+    //    interface — the link pass resolves names against the pool. An absent
+    //    array passes, because stored plans from before the field carry none.
+    //    The specifier check exists because the link pass splits on `==` only:
+    //    an unrefused `numpy>=1.26` becomes a package NAME, and the pool then
+    //    refuses a package it holds.
+    for (const step of plan.steps) {
+        for (const entry of step.packages ?? []) {
+            if (/^[.~]|[/\\]|:\/\//.test(entry)) {
+                errors.push(`Step "${step.id}" names a package location "${entry}" — name each package as a requirement ` +
+                    `(a bare name, or name==version), never a path, a URL, or a store directory`);
+            }
+            else if (/[<>!~]/.test(entry) || (entry.includes("=") && !entry.includes("=="))) {
+                errors.push(`Step "${step.id}" pins "${entry}" with a specifier the link pass cannot honor — ` +
+                    `use a bare name, or name==version with one exact version`);
+            }
+        }
+    }
+    // 7. Step-id path safety. The id becomes the `runs/{runId}/{stepId}` directory
     //    segment and a `/{analysisId}/…` container mount path; an unsafe segment
     //    (a slash, or `.`/`..`) could traverse or widen the mount. The sandbox
     //    mount boundary also rejects these (assertSafeId), but catching it here

package/dist/schemas/workflow-state.d.ts

@@ -21,6 +21,7 @@ export declare const AnalysisStepSchema: z.ZodObject<{
     constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
     acceptance_criteria: z.ZodArray<z.ZodString>;
     caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
     depends_on: z.ZodArray<z.ZodString>;
     status: z.ZodDefault<z.ZodEnum<{
         pending: "pending";
@@ -57,6 +58,7 @@ export declare const AnalysisPlanSchema: z.ZodObject<{
         constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
         acceptance_criteria: z.ZodArray<z.ZodString>;
         caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
         depends_on: z.ZodArray<z.ZodString>;
         status: z.ZodDefault<z.ZodEnum<{
             pending: "pending";
@@ -128,6 +130,7 @@ export declare const ContentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
             acceptance_criteria: z.ZodArray<z.ZodString>;
             caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
             depends_on: z.ZodArray<z.ZodString>;
             status: z.ZodDefault<z.ZodEnum<{
                 pending: "pending";
@@ -247,6 +250,7 @@ export declare const SuspensionPayloadSchema: z.ZodObject<{
                 constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 acceptance_criteria: z.ZodArray<z.ZodString>;
                 caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 depends_on: z.ZodArray<z.ZodString>;
                 status: z.ZodDefault<z.ZodEnum<{
                     pending: "pending";

package/dist/schemas/workflow-state.js

@@ -24,6 +24,16 @@ export const AnalysisStepSchema = z.object({
     constraints: z.array(z.string()).optional().describe("Requirements the sandbox agent must follow exactly — not suggestions."),
     acceptance_criteria: z.array(z.string()).describe("What the result must satisfy for the step to count as successful."),
     caveats: z.array(z.string()).optional().describe("Pitfalls the sandbox agent should watch for."),
+    // Optional on the persistence schema so historical plans (pre-packages)
+    // still parse on the read side. `PlanStepSchema` re-requires it for
+    // planner output. The briefing withholds it from the rendered task — the
+    // pre-launch link pass consumes it, and a step agent must not re-litigate it.
+    packages: z
+        .array(z.string())
+        .optional()
+        .describe('The packages this step imports, each as a requirement: a bare name ("scanpy") or a name with one exact version ("numpy==1.26.4"). ' +
+        "Never a path, a URL, or a store directory. An empty array means the step needs nothing beyond the baked toolchain. " +
+        "The set is not a promise of completeness — the execution agent can still link a missing package."),
     depends_on: z
         .array(z.string())
         .describe("IDs of steps in this plan that must complete before this one runs. Empty when the step has no prerequisites. The graph must be acyclic."),

package/dist/tasks/data-profile.d.ts

@@ -20,8 +20,10 @@
 import type { Pool } from "pg";
 import { type AuthContext, type RunSession } from "../auth/types.js";
 import type { EnvironmentStorePaths } from "../config/environment-stores.js";
+import type { ExtendAnalysisFarm } from "../sandbox/types.js";
 import type { RunAuthorization, RunAuthorizer } from "../execution/run-authorizer.js";
 import type { StagedInput } from "../execution/staged-input.js";
+import type { SandboxAgentDeps } from "../agents/sandbox/shared.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
@@ -65,6 +67,13 @@ export interface DataProfileDeps extends EnvironmentStorePaths {
      * the pod then carries the harness's own labels only.
      */
     readonly resolvePodLabels?: (session: RunSession) => Promise<Record<string, string>>;
+    /**
+     * The farm-extension seam of the embedder. Bound, it rides into the
+     * profiler agent deps, and the substrate attaches `link_packages`. Thus
+     * the profiler links a reader by need before the first plan exists.
+     * Unbound keeps the current shape: no link tool, and no error.
+     */
+    readonly extendAnalysisFarm?: ExtendAnalysisFarm;
 }
 /**
  * Workflow input. JSON-serialisable — DBOS persists it as the workflow's
@@ -125,6 +134,12 @@ export declare function buildAbsorbedResult(prior: DataProfileResult, resolution
  * Register the data-profile workflow with DBOS. Returns the registered
  * callable so `triggerDataProfile` can dispatch via `DBOS.startWorkflow`.
  */
+/**
+ * Project the workflow deps onto the profiler agent bag. The farm-extension
+ * seam rides only when the embedder bound one, and the substrate then gates
+ * `link_packages` on its presence (the data-profile-init spec).
+ */
+export declare function profilerSandboxAgentDeps(deps: DataProfileDeps, step: SandboxAgentDeps["step"]): SandboxAgentDeps;
 export declare function registerDataProfileWorkflow(deps: DataProfileDeps): (input: DataProfileWorkflowInput) => Promise<void>;
 /**
  * Body extracted so tests can drive it without registering a workflow.

package/dist/tasks/data-profile.js

@@ -247,6 +247,28 @@ function logProfileMonitoring(logger, args) {
  * Register the data-profile workflow with DBOS. Returns the registered
  * callable so `triggerDataProfile` can dispatch via `DBOS.startWorkflow`.
  */
+/**
+ * Project the workflow deps onto the profiler agent bag. The farm-extension
+ * seam rides only when the embedder bound one, and the substrate then gates
+ * `link_packages` on its presence (the data-profile-init spec).
+ */
+export function profilerSandboxAgentDeps(deps, step) {
+    return {
+        provider: deps.provider,
+        pool: deps.pool,
+        sandboxClient: deps.sandboxClient,
+        workspaceFs: deps.workspaceFs,
+        embedding: deps.embedding,
+        model: deps.model,
+        skillsDir: deps.skillsDir,
+        ...(deps.farmLockFile ? { farmLockFile: deps.farmLockFile } : {}),
+        ...(deps.imagePackagesFile ? { imagePackagesFile: deps.imagePackagesFile } : {}),
+        ...(deps.refStorePath ? { refStorePath: deps.refStorePath } : {}),
+        ...(deps.extendAnalysisFarm ? { extendAnalysisFarm: deps.extendAnalysisFarm } : {}),
+        bioKeys: deps.bioKeys,
+        step,
+    };
+}
 export function registerDataProfileWorkflow(deps) {
     return DBOS.registerWorkflow((input) => runDataProfileBody(input, deps), { name: "data-profile" });
 }
@@ -454,32 +476,20 @@ export async function runDataProfileBody(input, deps) {
                         `description needs content the scan did not capture, then call \`submit_profile\` once.`,
                     ]),
             ].join("\n");
-            const sandboxAgentDeps = {
-                provider: deps.provider,
-                pool: deps.pool,
-                sandboxClient: deps.sandboxClient,
-                workspaceFs: deps.workspaceFs,
-                embedding: deps.embedding,
-                model: deps.model,
-                skillsDir: deps.skillsDir,
-                ...(deps.packagesFile ? { packagesFile: deps.packagesFile } : {}),
-                ...(deps.refStorePath ? { refStorePath: deps.refStorePath } : {}),
-                bioKeys: deps.bioKeys,
-                step: {
-                    sandbox,
-                    workspaceRoot,
-                    analysisId,
-                    runId: DATA_PROFILE_RUN_LITERAL,
-                    stepId: DATA_PROFILE_STEP_LITERAL,
-                    workflowId,
-                    // The profiler writes Python scripts and intermediate artifacts under
-                    // the synthetic step path; the post-agent `rm -rf runs/data-profile/`
-                    // cleanup wipes them.
-                    allowedWritePrefix: profileWritePrefix,
-                    nextFunctionId,
-                    deadlineMs: () => deadlineAbs,
-                },
-            };
+            const sandboxAgentDeps = profilerSandboxAgentDeps(deps, {
+                sandbox,
+                workspaceRoot,
+                analysisId,
+                runId: DATA_PROFILE_RUN_LITERAL,
+                stepId: DATA_PROFILE_STEP_LITERAL,
+                workflowId,
+                // The profiler writes Python scripts and intermediate artifacts under
+                // the synthetic step path; the post-agent `rm -rf runs/data-profile/`
+                // cleanup wipes them.
+                allowedWritePrefix: profileWritePrefix,
+                nextFunctionId,
+                deadlineMs: () => deadlineAbs,
+            });
             let accepted = null;
             let rounds = 0;
             const submitProfileTool = defineTool({

package/dist/tools/display/show-user.d.ts

@@ -23,7 +23,7 @@ type ShowUserOutput = {
     id: string;
 };
 export declare const showUserTool: import("../define-tool.js").Tool<{
-    kind: "code" | "markdown" | "echart" | "svg" | "table";
+    kind: "code" | "markdown" | "table" | "echart" | "svg";
     title?: string | undefined;
     spec?: Record<string, unknown> | undefined;
     dataPath?: string | undefined;

package/dist/tools/execute-analysis.d.ts

@@ -8,6 +8,7 @@ import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { RunLauncher } from "../execution/run-launcher.js";
 import type { Logger } from "../lib/logger.js";
 import type { ChatProvider } from "../providers/types.js";
+import type { ExtendAnalysisFarm } from "../sandbox/types.js";
 import { type AnalysisPlan } from "../schemas/workflow-state.js";
 import type { ExecuteAnalysisInput, ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
 import { type AdHocRoute } from "./ad-hoc-router.js";
@@ -21,6 +22,12 @@ export interface ExecuteAnalysisToolDeps {
     readonly utilityProvider: ChatProvider;
     readonly utilityModel: string;
     readonly logger?: Logger;
+    /**
+     * The farm-extension seam of the embedder. When it is bound, the launch
+     * links the packages of the plan into the farm of the analysis before the
+     * run reserves anything. Without it, the link pass returns at once.
+     */
+    readonly extendAnalysisFarm?: ExtendAnalysisFarm;
 }
 export declare class PlanNotFoundError extends Error {
     constructor(planId: string);
@@ -32,6 +39,17 @@ export declare class PlanValidationError extends Error {
     readonly errors: string[];
     constructor(planId: string, errors: string[]);
 }
+/**
+ * A pool miss at the pre-launch link pass. The message names the missing
+ * packages and no remedy command — the remedy belongs to the embedder, and
+ * its wrapper appends it.
+ */
+export declare class PlanPackagesMissingError extends Error {
+    readonly missing: string[];
+    readonly collisions: string[];
+    readonly unavailable?: string | undefined;
+    constructor(missing: string[], collisions: string[], unavailable?: string | undefined);
+}
 export declare function buildAdHocPlan(request: string, route: AdHocRoute, createdAt?: string): AnalysisPlan;
 export declare function createExecuteAnalysisTool(deps: ExecuteAnalysisToolDeps): import("./define-tool.js").Tool<{
     mode: "plan" | "adhoc";

package/dist/tools/execute-analysis.js

@@ -54,6 +54,90 @@ export class PlanValidationError extends Error {
 function isDedupCollision(err) {
     return err instanceof RunDedupCollisionError || (err instanceof Error && err.name === "RunDedupCollisionError");
 }
+/**
+ * A pool miss at the pre-launch link pass. The message names the missing
+ * packages and no remedy command — the remedy belongs to the embedder, and
+ * its wrapper appends it.
+ */
+export class PlanPackagesMissingError extends Error {
+    missing;
+    collisions;
+    unavailable;
+    constructor(missing, collisions, unavailable) {
+        const parts = [
+            // The store-level reason FIRST, because it invalidates the rest: with an
+            // unreadable graph, no per-package claim below it is trustworthy.
+            unavailable !== undefined
+                ? `the store cannot answer (${unavailable}) — this says nothing about the packages themselves, so do not re-request them`
+                : null,
+            missing.length > 0 ? `the pool does not hold: ${missing.join(", ")}` : null,
+            collisions.length > 0 ? `a collision refused: ${collisions.join(", ")}` : null,
+        ].filter((p) => p !== null);
+        super(`The packages of this plan cannot link — ${parts.join("; ")}`);
+        this.missing = missing;
+        this.collisions = collisions;
+        this.unavailable = unavailable;
+        this.name = "PlanPackagesMissingError";
+    }
+}
+/** One plan package entry, in requirement form: a bare name, or a name with one exact version. */
+function parseRequirement(entry) {
+    const split = entry.indexOf("==");
+    if (split < 0)
+        return { name: entry.trim() };
+    return { name: entry.slice(0, split).trim(), version: entry.slice(split + 2).trim() };
+}
+/**
+ * Link the packages of the plan into the farm of the analysis, before the
+ * run reserves anything. The linked set is the union of the packages of each
+ * step. A pool miss and a collision refuse the launch with the names. Without
+ * a bound seam, the pass returns at once.
+ */
+async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
+    if (!extendAnalysisFarm)
+        return;
+    const union = new Map();
+    for (const step of plan.steps) {
+        for (const entry of step.packages ?? []) {
+            // The FIRST spelling of the plan rides the request. An outcome
+            // echoes the requested spelling, and a last-writer fold could
+            // echo `seurat` where the plan said `Seurat` — a remedy in that
+            // case names a package that no repository holds.
+            const key = entry.trim().toLowerCase();
+            if (!union.has(key))
+                union.set(key, parseRequirement(entry));
+        }
+    }
+    if (union.size === 0)
+        return;
+    let outcomes;
+    try {
+        outcomes = await extendAnalysisFarm(analysisId, [...union.values()]);
+    }
+    catch (cause) {
+        // A realization throw is an `unavailable` answer, not a driver error.
+        // The sibling resolver seam maps a throw the same way (farm.ts), and
+        // the planner can act on "the store cannot answer" — not on a stack.
+        throw new PlanPackagesMissingError([], [], cause instanceof Error ? cause.message : String(cause));
+    }
+    // An `unavailable` outcome preempts everything: the link pass could not
+    // answer at all (an unreadable graph, a locked farm), so a per-package
+    // absence list would be a fabrication. One reason covers the batch.
+    const unavailable = outcomes.find((o) => o.kind === "unavailable");
+    if (unavailable !== undefined) {
+        throw new PlanPackagesMissingError([], [], unavailable.reason);
+    }
+    // A seam-supplied detail classifies the miss in host terms (in flight,
+    // failed with its reason, never requested), and it rides beside the name
+    // so the agent replans from the true state instead of re-asking. A
+    // collision's detail names the two pins and what needs each side — the
+    // remedy is to drop or re-pin a DEPENDENT, so the refusal must name it.
+    const missing = outcomes.filter((o) => o.kind === "absent").map((o) => (o.detail === undefined ? o.name : `${o.name} — ${o.detail}`));
+    const collisions = outcomes.filter((o) => o.kind === "collision").map((o) => (o.detail === undefined ? o.name : `${o.name} — ${o.detail}`));
+    if (missing.length > 0 || collisions.length > 0) {
+        throw new PlanPackagesMissingError(missing, collisions);
+    }
+}
 function planSummary(plan) {
     return plan.title?.trim() || plan.analytical_narrative.trim().slice(0, 280);
 }
@@ -183,6 +267,9 @@ export function createExecuteAnalysisTool(deps) {
             else {
                 plan = await persistedAdHocPlan(deps, { analysisId, request: input.request, ctx, planId });
             }
+            // The link pass comes before the run reserves anything, thus a pool
+            // miss leaves no run row and no revoked authorization behind.
+            await linkPlanPackages(deps.extendAnalysisFarm, analysisId, plan);
             const runId = input.mode === "plan" ? randomUUID() : adHocRunId(analysisId, ctx.invocationId);
             if (input.mode === "plan") {
                 try {

package/dist/tools/report-authoring/authoring-tools.d.ts

@@ -19,6 +19,8 @@
 import { type Result } from "neverthrow";
 import { z } from "zod";
 import type { Scope } from "../../auth/types.js";
+import type { Logger } from "../../lib/logger.js";
+import { type ProvenanceSeam } from "../../provenance/seam.js";
 import { type DraftRefusal } from "../../report-model/draft-operations.js";
 import { type OutlineEntry, type ReadableBlock } from "../../report-model/draft-read.js";
 import { type FinishResult } from "../../report-model/draft-finish.js";
@@ -289,12 +291,25 @@ export interface ReportAuthoringTools {
     readonly read_block: Tool<ReadBlockInput, ReadBlockResult>;
     readonly finish_draft: Tool<FinishDraftInput, FinishToolResult>;
 }
+/**
+ * The optional deps of the authoring surface. The gateway is the one mandatory part, thus it stays a
+ * parameter of its own and this bag holds what a composition can leave out.
+ */
+export interface ReportAuthoringToolDeps {
+    /** The provenance seam; an unbound session emit emits nothing and each tool acts the same. */
+    readonly provenance?: ProvenanceSeam;
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
+}
 /**
  * Make the eight authoring tools over a session-state gateway.
  *
  * Each tool reads the thread id from the scope of the call, and it loads the state of that thread through
  * the gateway. Thus one factory serves every thread, and two threads never share one draft. A mutation
  * persists the new document before it reports `applied: true`, thus a reported landing is never lost.
+ *
+ * A landed mutation emits one observation. The emit sits after the persist, thus a refused operation and a
+ * failed persist each emit nothing.
  */
-export declare function createReportAuthoringTools(gateway: ReportSessionStateGateway): ReportAuthoringTools;
+export declare function createReportAuthoringTools(gateway: ReportSessionStateGateway, deps?: ReportAuthoringToolDeps): ReportAuthoringTools;
 export {};