@inflexa-ai/harness 0.34.0 → 0.35.1

package/dist/sandbox/image-packages.js

@@ -0,0 +1,107 @@
+/**
+ * `image-packages.json` — the self-description of the sandbox image.
+ *
+ * The image bakes two package tracks that the content-addressed store cannot
+ * hold: the conda tools at `/opt/conda` and the Node packages at `/opt/node`.
+ * The image writes one record of them at `/opt/inflexa/image-packages.json`,
+ * and the catalog build copies that record verbatim into the root of the
+ * package store it packed beside it. Thus every reader of a store learns the
+ * image inventory from the store alone — with no container engine, no
+ * registry client, and no path outside the store.
+ *
+ * The record is JSON with a `schema` number, the same convention as
+ * {@link FarmLockSchema}: an additive field passes through untouched, and a
+ * breaking change to the shape moves the number instead. A structured record
+ * is what lets a row carry its version, and what lets a later change compare
+ * the recorded image against the configured one.
+ *
+ * This schema is the ONE definition of the shape. The image writes the bytes
+ * and the harness validates them, thus a producer that drifts is refused here
+ * rather than half-read downstream.
+ */
+import { readFileSync } from "node:fs";
+import { err, ok } from "neverthrow";
+import { z } from "zod";
+/**
+ * The file name of the record, at the root of the package store. Exported,
+ * as `FARM_LOCK_FILE` is, thus an embedder that joins the path onto its own
+ * store root never spells the name by hand.
+ */
+export const IMAGE_PACKAGES_FILE = "image-packages.json";
+/** The image the record describes. The pair of tags shares one version string. */
+export const ImageIdentitySchema = z
+    .object({
+    repository: z.string(),
+    version: z.string(),
+    arch: z.enum(["amd64", "arm64"]),
+})
+    .passthrough();
+/** The interpreter versions of the image, so a reader can compare them against the lock. */
+export const ImageRuntimesSchema = z
+    .object({
+    python: z.string(),
+    r: z.string(),
+    node: z.string(),
+})
+    .passthrough();
+/**
+ * One conda tool of the image. `executable` carries the binary name when it
+ * differs from the package name (the manifest `binaries:` map holds those
+ * exceptions), because an agent invokes the binary and not the package.
+ */
+export const ImageSystemToolSchema = z
+    .object({
+    name: z.string(),
+    version: z.string(),
+    executable: z.string().optional(),
+})
+    .passthrough();
+/** One Node package of the image. */
+export const ImageNodePackageSchema = z
+    .object({
+    name: z.string(),
+    version: z.string(),
+})
+    .passthrough();
+/**
+ * `image-packages.json` at schema version 1. The keys `system_tools` and
+ * `node` are the keys of the image manifest, thus one name means one track
+ * across the build and the reader.
+ */
+export const ImagePackagesSchema = z
+    .object({
+    schema: z.literal(1),
+    image: ImageIdentitySchema,
+    runtimes: ImageRuntimesSchema,
+    system_tools: z.array(ImageSystemToolSchema),
+    node: z.array(ImageNodePackageSchema),
+})
+    .passthrough();
+/**
+ * Read and validate one `image-packages.json` by its file path. The read is
+ * synchronous, the same as {@link readFarmLockFile}, because the caller reads
+ * the record on each call and a store download can land while the process
+ * runs. Both errors are normal states of a host that reads a store from
+ * before this record existed.
+ */
+export function readImagePackagesFile(recordPath) {
+    let raw;
+    try {
+        raw = readFileSync(recordPath, "utf8");
+    }
+    catch (cause) {
+        return err({ type: "record_unreadable", recordPath, cause });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        return err({ type: "record_invalid", recordPath, cause });
+    }
+    const record = ImagePackagesSchema.safeParse(parsed);
+    if (!record.success) {
+        return err({ type: "record_invalid", recordPath, cause: record.error });
+    }
+    return ok(record.data);
+}

package/dist/sandbox/k8s-client.d.ts

@@ -71,6 +71,17 @@ export interface K8sClientConfig {
     farmSource: FarmSource;
     /** The declared toolchain owner. Absent means `"store"`, the legacy environment. */
     toolchainSource?: ToolchainSource;
+    /**
+     * The deployment cannot run an analysis without the package store. Under
+     * the fact, a farm that fails the `inflexa.lock` gate refuses the create
+     * with `farm_unusable` and no Job is made. Absent keeps the degrade: the
+     * store mounts drop, a warning is logged, and the Job is still made. The
+     * field names the deployment fact rather than the remediation, so how the
+     * harness answers it can evolve without changing the embedder surface; a
+     * single-valued union (not a boolean) so future store classes extend it
+     * without a breaking change.
+     */
+    packageStore?: "required";
     /** PVC claim mounted read-only at `/mnt/refs` when set. */
     refStorePvc?: string;
     /** Node selector pinning sandbox pods to the dedicated agent pool. Omit for default scheduling. */

package/dist/sandbox/k8s-client.js

@@ -465,14 +465,30 @@ export function createK8sSandboxOps(config) {
                 // The `inflexa.lock` gate, for a host that mounts the libs
                 // volume itself. The resolver owes the proof either way,
                 // but a farm half-written between the resolution and this
-                // create still mounts without a second look. A gate failure
-                // degrades exactly as the Docker backend does: no store
-                // mount, the Job is still made, and the sandbox reports the
-                // store as unavailable.
+                // create still mounts without a second look. The failure
+                // has the two outcomes of the Docker backend. Under the
+                // declared fact the call refuses with `farm_unusable`
+                // before any cluster work, and it logs nothing: the
+                // returned value carries the reason, and the consumer logs
+                // the throw, thus a warning here would record the one fault
+                // twice. Without the fact it degrades — no store mount, the
+                // Job is still made, and the sandbox reports the store as
+                // unavailable.
                 let libsMounted = !!config.libStorePvc;
                 if (config.libStorePvc && config.libStorePvcRoot && farm) {
                     const lock = readFarmLock(join(config.libStorePvcRoot, farm.farmPath));
                     libsMounted = lock.isOk();
+                    if (lock.isErr() && config.packageStore === "required") {
+                        return err({
+                            type: "farm_unusable",
+                            op: "k8s.createSandbox",
+                            analysisId: meta.analysisId,
+                            farmPath: farm.farmPath,
+                            lockPath: lock.error.lockPath,
+                            lockError: lock.error.type,
+                            cause: lock.error.cause,
+                        });
+                    }
                     if (lock.isErr()) {
                         (config.logger ?? createNoopLogger())
                             .named("k8s-client")

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

@@ -26,10 +26,12 @@
  *    ever wraps the single SDK/HTTP call handed to it.
  *
  * The public `SandboxClient` interface keeps `Promise<T>` method signatures.
- * `create-sandbox.ts` is the composition seam: it builds the backend ops, then
- * `unwrapOrThrow`s each op's `ResultAsync` so the seam re-throws a genuine
- * `SandboxError`. (`submitExec` is the exception — it is already its own DBOS
- * step and throws directly, so the seam forwards its `Promise<void>` as-is.)
+ * `create-sandbox.ts` is the composition seam: it builds the backend ops, maps
+ * each `err` of an op to a `SandboxFailure`, and `unwrapOrThrow`s it, so the
+ * seam throws the described failure with the variant on `.cause` and on
+ * `.error`. A `catch` never sees the raw variant. (`submitExec` is the
+ * exception — it is already its own DBOS step and throws directly, so the seam
+ * forwards its `Promise<void>` as-is.)
  * Workflow consumers (`sandbox-step.ts`) already wrap each seam call in
  * `DBOS.runStep`, so the re-thrown error records the step as failed;
  * non-workflow consumers (`reaper`, `watchdog`,
@@ -37,6 +39,7 @@
  * untouched by this wave.
  */
 import { ResultAsync } from "neverthrow";
+import type { FarmLockError } from "./farm.js";
 /**
  * A sandbox backend failure. Absence / idempotent "already gone" is NOT
  * modelled — those ride the OK channel (`ok(false)` for a dead/missing machine,
@@ -91,6 +94,22 @@ export type SandboxError = {
     readonly analysisId: string;
     readonly reason: string;
     readonly cause?: unknown;
+} | {
+    /**
+     * The gate proved the `inflexa.lock` at the resolved farm and the
+     * farm is not usable. Raised only when the config declares
+     * `packageStore: "required"`; without the fact the same gate
+     * failure degrades to no store mount. The sibling
+     * `farm_unavailable` is the resolver refusing to name a farm at
+     * all — here a farm was named, and its lock does not hold up.
+     */
+    readonly type: "farm_unusable";
+    readonly op: string;
+    readonly analysisId: string;
+    readonly farmPath: string;
+    readonly lockPath: string;
+    readonly lockError: FarmLockError["type"];
+    readonly cause: unknown;
 };
 /**
  * The HTTP/driver status a backend SDK error carries. dockerode exposes it on
@@ -100,8 +119,24 @@ export type SandboxError = {
  * `typeof === "number"` to avoid returning it as a status.
  */
 export declare function sandboxStatusOf(cause: unknown): number | undefined;
-/** A one-line, user-facing description of a `SandboxError` for logs/error bodies. */
+/**
+ * A one-line, user-facing description of a `SandboxError` for logs/error
+ * bodies. The variant gives the head. Where the cause names a reason, that
+ * bounded line closes the description, thus the engine or the parser says why
+ * on the operator surfaces.
+ */
 export declare function describeSandboxError(e: SandboxError): string;
+/**
+ * The throw of the `SandboxClient` seam. The message is
+ * `describeSandboxError`, thus a surface that renders a message alone still
+ * names the fault and its reason. The variant rides two ways: on `cause`, so
+ * a cause-chain reader keeps working, and on `error`, so a consumer that
+ * matches the class reads the typed fields without a walk.
+ */
+export declare class SandboxFailure extends Error {
+    readonly error: SandboxError;
+    constructor(error: SandboxError);
+}
 /**
  * Wrap a single sandbox backend call (Docker SDK op, K8s API op, or the
  * `/exec` POST). A throw becomes `err(toError(status, cause))`; the caller

package/dist/sandbox/sandbox-error.js

@@ -26,10 +26,12 @@
  *    ever wraps the single SDK/HTTP call handed to it.
  *
  * The public `SandboxClient` interface keeps `Promise<T>` method signatures.
- * `create-sandbox.ts` is the composition seam: it builds the backend ops, then
- * `unwrapOrThrow`s each op's `ResultAsync` so the seam re-throws a genuine
- * `SandboxError`. (`submitExec` is the exception — it is already its own DBOS
- * step and throws directly, so the seam forwards its `Promise<void>` as-is.)
+ * `create-sandbox.ts` is the composition seam: it builds the backend ops, maps
+ * each `err` of an op to a `SandboxFailure`, and `unwrapOrThrow`s it, so the
+ * seam throws the described failure with the variant on `.cause` and on
+ * `.error`. A `catch` never sees the raw variant. (`submitExec` is the
+ * exception — it is already its own DBOS step and throws directly, so the seam
+ * forwards its `Promise<void>` as-is.)
  * Workflow consumers (`sandbox-step.ts`) already wrap each seam call in
  * `DBOS.runStep`, so the re-thrown error records the step as failed;
  * non-workflow consumers (`reaper`, `watchdog`,
@@ -37,6 +39,7 @@
  * untouched by this wave.
  */
 import { ResultAsync, err, ok } from "neverthrow";
+import { ZodError } from "zod";
 const _assertDomainError = true;
 /**
  * The HTTP/driver status a backend SDK error carries. dockerode exposes it on
@@ -51,8 +54,62 @@ export function sandboxStatusOf(cause) {
         return e.code;
     return e.statusCode ?? e.response?.statusCode;
 }
-/** A one-line, user-facing description of a `SandboxError` for logs/error bodies. */
+/**
+ * The bound on the appended cause line — the same 200 characters the profile
+ * ledger keeps (`tasks/data-profile.ts`), because a description reaches that
+ * ledger and the run row. A stack trace and an engine response body must stay
+ * out of a row, so the line is cut and marked rather than carried whole.
+ */
+const CAUSE_LINE_MAX = 200;
+/**
+ * The one bounded line that names the reason of a cause, or `undefined` when
+ * the cause carries no reason to name.
+ *
+ * A `ZodError` is special-cased: its `message` is multi-line JSON whose first
+ * line is `[`, which names nothing. Thus a zod cause renders as its first
+ * issue — the path and the message — and the reader sees which field broke.
+ * Any other cause gives the first line of its message.
+ */
+function causeLine(cause) {
+    let text;
+    if (cause instanceof ZodError) {
+        const issue = cause.issues[0];
+        if (!issue)
+            return undefined;
+        const path = issue.path.join(".");
+        text = path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+    }
+    else if (cause instanceof Error) {
+        text = cause.message;
+    }
+    else if (typeof cause === "string") {
+        text = cause;
+    }
+    else {
+        return undefined;
+    }
+    const first = text.split("\n", 1)[0].trim();
+    if (first.length === 0)
+        return undefined;
+    return first.length > CAUSE_LINE_MAX ? `${first.slice(0, CAUSE_LINE_MAX - 1)}…` : first;
+}
+/**
+ * A one-line, user-facing description of a `SandboxError` for logs/error
+ * bodies. The variant gives the head. Where the cause names a reason, that
+ * bounded line closes the description, thus the engine or the parser says why
+ * on the operator surfaces.
+ */
 export function describeSandboxError(e) {
+    // `farm_unavailable` is the one variant whose head already carries its
+    // reason, the text of the resolver. A cause line after it would put two
+    // dashes on one row, and the throw of a resolver is in the log with its
+    // stack. Every other variant names its reason only through the cause.
+    const line = e.type === "farm_unavailable" ? undefined : causeLine(e.cause);
+    const head = describeVariant(e);
+    return line === undefined ? head : `${head} — ${line}`;
+}
+/** The head of a description: what failed, at which op, on which subject. */
+function describeVariant(e) {
     switch (e.type) {
         case "container_create_failed":
             return `sandbox create failed (${e.op}${e.sandboxId ? `: ${e.sandboxId}` : ""})`;
@@ -68,6 +125,23 @@ export function describeSandboxError(e) {
             return `sandbox liveness probe failed (${e.op}${e.sandboxId ? `: ${e.sandboxId}` : ""})`;
         case "farm_unavailable":
             return `farm unavailable (${e.op}: ${e.analysisId}) — ${e.reason}`;
+        case "farm_unusable":
+            return `farm unusable (${e.op}: ${e.analysisId}, ${e.lockError} at ${e.lockPath})`;
+    }
+}
+/**
+ * The throw of the `SandboxClient` seam. The message is
+ * `describeSandboxError`, thus a surface that renders a message alone still
+ * names the fault and its reason. The variant rides two ways: on `cause`, so
+ * a cause-chain reader keeps working, and on `error`, so a consumer that
+ * matches the class reads the typed fields without a walk.
+ */
+export class SandboxFailure extends Error {
+    error;
+    constructor(error) {
+        super(describeSandboxError(error), { cause: error });
+        this.error = error;
+        this.name = "SandboxFailure";
     }
 }
 /**

package/dist/tools/sandbox/list-available-packages.d.ts

@@ -9,12 +9,10 @@
  * planning surface reads the pool-scope inventory (`readPoolInventory`) —
  * everything the store holds, whether or not a farm links it yet — because
  * the ask flow marks the packages the POOL does not hold, and the farm of a
- * new analysis is empty. The baked image inventory fragment
- * (`image-packages.txt`, at `/opt/inflexa` in the image) merges into either
- * report when the host can read one. The fragment keeps the section format:
- *
- *     ## System tools (CLI)
- *     samtools, bcftools, ...
+ * new analysis is empty. The image inventory record (`image-packages.json`,
+ * at the root of the package store) merges into either report when the host
+ * can read one: it carries the conda tools and the Node packages the image
+ * owns, which the content-addressed store cannot hold.
  *
  * Each entry renders as `name==version` where the source pins a version, and
  * a targeted `names` lookup also carries the store directory and the full
@@ -23,6 +21,7 @@
  */
 import type { EnvironmentStorePaths, PoolInventoryPackage, PoolInventorySection } from "../../config/environment-stores.js";
 import { type FarmLock } from "../../sandbox/farm.js";
+import { type ImagePackages } from "../../sandbox/image-packages.js";
 /**
  * Group the lock packages into sections, one per track, in a stable order:
  * the known tracks first, then an unknown track at its first occurrence.
@@ -30,9 +29,19 @@ import { type FarmLock } from "../../sandbox/farm.js";
  * targeted `names` path can report the exact store identity.
  */
 export declare function lockSections(lock: FarmLock): Section[];
+/**
+ * Group the image record into its two sections, in the order of the record.
+ * An empty track yields no section, so the report never carries a heading
+ * with nothing under it.
+ *
+ * A `system_tools` row renders its `executable` name where the record gives
+ * one, because an agent invokes the binary rather than the conda package
+ * (the manifest `binaries:` map holds the pairs that differ).
+ */
+export declare function imageSections(record: ImagePackages): Section[];
 /** One package entry of a section, with the store identity where the source records it. */
 export type SectionPackage = PoolInventoryPackage;
-/** One language track of the store, in `packages.txt` section order. The seam shape and the render shape are one. */
+/** One language track of the store, in the section order of its source. The seam shape and the render shape are one. */
 export type Section = PoolInventorySection;
 /** One `names` lookup: present + canonical spelling + track + store identity, or absent. */
 export type CheckedPackage = {
@@ -65,13 +74,6 @@ export type PackagesResult = {
     readonly hasMore: boolean;
     readonly content: string;
 };
-/**
- * Parse `packages.txt` into its sections. `#` lines are the advisory header,
- * `## X` opens a section, and every other non-empty line contributes
- * comma-separated package names to the open section. Unknown section headings
- * are preserved as-is — a downstream image may add its own track.
- */
-export declare function parsePackagesFile(content: string): Section[];
 /** The tool's input, as parsed from `inputSchema`. */
 export interface PackagesQuery {
     readonly names?: readonly string[];
@@ -83,7 +85,7 @@ export interface PackagesQuery {
  * Answer a packages query against a parsed catalog. Pure — the tool's `execute`
  * is only the file read plus this call.
  */
-export declare function queryPackages(sections: readonly Section[], { names, query, language, limit }: PackagesQuery): PackagesResult;
+export declare function queryPackages(rawSections: readonly Section[], { names, query, language, limit }: PackagesQuery): PackagesResult;
 export type ListAvailablePackagesDeps = Pick<EnvironmentStorePaths, "farmLockFile" | "imagePackagesFile" | "readPoolInventory"> & {
     /**
      * True when the composition also attaches the `link_packages` tool. The
@@ -96,7 +98,7 @@ export type ListAvailablePackagesDeps = Pick<EnvironmentStorePaths, "farmLockFil
  * Create the package inventory over the bound source: the pool-scope reader
  * when the embedder binds one (a conversation or planning surface), the
  * host-readable farm `inflexa.lock` otherwise (a sandbox agent). The image
- * fragment merges into either report.
+ * record merges into either report.
  */
 export declare function createListAvailablePackagesTool(deps?: ListAvailablePackagesDeps): import("../define-tool.js").Tool<{
     names?: string[] | undefined;

package/dist/tools/sandbox/list-available-packages.js

@@ -9,25 +9,23 @@
  * planning surface reads the pool-scope inventory (`readPoolInventory`) —
  * everything the store holds, whether or not a farm links it yet — because
  * the ask flow marks the packages the POOL does not hold, and the farm of a
- * new analysis is empty. The baked image inventory fragment
- * (`image-packages.txt`, at `/opt/inflexa` in the image) merges into either
- * report when the host can read one. The fragment keeps the section format:
- *
- *     ## System tools (CLI)
- *     samtools, bcftools, ...
+ * new analysis is empty. The image inventory record (`image-packages.json`,
+ * at the root of the package store) merges into either report when the host
+ * can read one: it carries the conda tools and the Node packages the image
+ * owns, which the content-addressed store cannot hold.
  *
  * Each entry renders as `name==version` where the source pins a version, and
  * a targeted `names` lookup also carries the store directory and the full
  * content hash where the source records them. A full listing carries no
  * hashes — a thousand rows of sha256 would bury the signal.
  */
-import { readFile } from "node:fs/promises";
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { capCodePoints, DETAIL_NEEDLE_MAX_LENGTH } from "../../loop/tool-detail.js";
 import { LIBS_CONTAINER_PATH } from "../../sandbox/mount-plan.js";
 import { readFarmLockFile } from "../../sandbox/farm.js";
+import { IMAGE_PACKAGES_FILE, readImagePackagesFile } from "../../sandbox/image-packages.js";
 /**
  * Where the lock lives when the host mounts the farm at the same path the
  * sandbox does. Both farm container paths are tried, because the path keys on
@@ -36,15 +34,30 @@ import { readFarmLockFile } from "../../sandbox/farm.js";
  * reads the farm somewhere else injects its own path instead.
  */
 const DEFAULT_FARM_LOCK_FILES = [`${LIBS_CONTAINER_PATH}/farm/inflexa.lock`, `${LIBS_CONTAINER_PATH}/current/inflexa.lock`];
-/** Where the baked image inventory fragment lives inside the image. */
-const DEFAULT_IMAGE_PACKAGES_FILE = "/opt/inflexa/image-packages.txt";
+/**
+ * Where the image inventory record lives: at the root of the package store,
+ * which the catalog build copied it into. The default names the container
+ * mountpoint of that store, the same rule as {@link DEFAULT_FARM_LOCK_FILES}
+ * — a host whose own process sees the store the way a sandbox does needs no
+ * configuration. A host that reads the store somewhere else injects
+ * `imagePackagesFile`.
+ */
+const DEFAULT_IMAGE_PACKAGES_FILE = `${LIBS_CONTAINER_PATH}/${IMAGE_PACKAGES_FILE}`;
+/**
+ * The two headings that a lock track and the image record can both carry.
+ * Declared once, because {@link LANGUAGE_MATCHERS} keys the `language` filter
+ * on the heading text, and {@link foldSections} merges two sources by it: a
+ * second spelling of either would split one track into two headings.
+ */
+const CLI_TITLE = "System tools (CLI)";
+const NODE_TITLE = "Node (npm)";
 /** The section title of each known lock track. An unknown track titles itself. */
 const TRACK_TITLES = {
     python: "Python (pip)",
     cran: "R (CRAN)",
     bioconductor: "R (Bioconductor)",
     github: "R (GitHub)",
-    node: "Node (npm)",
+    node: NODE_TITLE,
 };
 /**
  * Group the lock packages into sections, one per track, in a stable order:
@@ -66,6 +79,56 @@ export function lockSections(lock) {
     }
     return [...byTrack.entries()].filter(([, packages]) => packages.length > 0).map(([track, packages]) => ({ title: TRACK_TITLES[track] ?? track, packages }));
 }
+/**
+ * Group the image record into its two sections, in the order of the record.
+ * An empty track yields no section, so the report never carries a heading
+ * with nothing under it.
+ *
+ * A `system_tools` row renders its `executable` name where the record gives
+ * one, because an agent invokes the binary rather than the conda package
+ * (the manifest `binaries:` map holds the pairs that differ).
+ */
+export function imageSections(record) {
+    const sections = [];
+    if (record.system_tools.length > 0) {
+        sections.push({
+            title: CLI_TITLE,
+            packages: record.system_tools.map((tool) => ({ name: tool.executable ?? tool.name, version: tool.version })),
+        });
+    }
+    if (record.node.length > 0) {
+        sections.push({ title: NODE_TITLE, packages: record.node.map((pkg) => ({ name: pkg.name, version: pkg.version })) });
+    }
+    return sections;
+}
+/**
+ * Merge the sections that share a title, in first-occurrence order, and keep
+ * the first entry of each name inside a merged section.
+ *
+ * Two sources can carry one track: the `node` track of a farm lock and the
+ * `node` track of the image record. Rendered as they arrive, a listing would
+ * print one heading twice and read as two tracks. The fold keeps the first
+ * writer, which is the same rule the `names` index applies, thus the listing
+ * and the presence check agree on which entry a colliding name resolves to.
+ */
+function foldSections(sections) {
+    const byTitle = new Map();
+    for (const section of sections) {
+        let open = byTitle.get(section.title);
+        if (!open) {
+            open = { title: section.title, packages: [], seen: new Set() };
+            byTitle.set(section.title, open);
+        }
+        for (const pkg of section.packages) {
+            const key = pkg.name.toLowerCase();
+            if (open.seen.has(key))
+                continue;
+            open.seen.add(key);
+            open.packages.push(pkg);
+        }
+    }
+    return [...byTitle.values()].map(({ title, packages }) => ({ title, packages }));
+}
 /**
  * Default cap on a listing — high enough that the real store is never truncated.
  * The shipped catalog is ~270 packages (~3 KB, well under a thousand tokens), so
@@ -98,39 +161,10 @@ const LANGUAGE_MATCHERS = {
     // The R triple: `R (CRAN)`, `R (Bioconductor)`, `R (GitHub)`.
     r: (t) => /^r\b/i.test(t),
     python: (t) => /^python\b/i.test(t),
-    // `System tools (CLI)` — the conda-installed bioinformatics executables.
+    // `CLI_TITLE` — the conda-installed bioinformatics executables.
     cli: (t) => /system tools|\bcli\b/i.test(t),
     node: (t) => /^node\b/i.test(t),
 };
-/**
- * Parse `packages.txt` into its sections. `#` lines are the advisory header,
- * `## X` opens a section, and every other non-empty line contributes
- * comma-separated package names to the open section. Unknown section headings
- * are preserved as-is — a downstream image may add its own track.
- */
-export function parsePackagesFile(content) {
-    const sections = [];
-    for (const line of content.split("\n")) {
-        const trimmed = line.trim();
-        if (!trimmed)
-            continue;
-        if (trimmed.startsWith("##")) {
-            sections.push({ title: trimmed.slice(2).trim(), packages: [] });
-            continue;
-        }
-        if (trimmed.startsWith("#"))
-            continue;
-        const open = sections.at(-1);
-        if (!open)
-            continue;
-        for (const name of trimmed.split(",")) {
-            const pkg = name.trim();
-            if (pkg)
-                open.packages.push({ name: pkg });
-        }
-    }
-    return sections;
-}
 /** One entry as the listing renders it: `name==version` where the source pins a version, the bare name otherwise. */
 function renderPackage(entry) {
     return entry.version === undefined ? entry.name : `${entry.name}==${entry.version}`;
@@ -160,15 +194,16 @@ function renderListing(sections, limit) {
  * Answer a packages query against a parsed catalog. Pure — the tool's `execute`
  * is only the file read plus this call.
  */
-export function queryPackages(sections, { names, query, language, limit }) {
+export function queryPackages(rawSections, { names, query, language, limit }) {
+    const sections = foldSections(rawSections);
     // Presence check — the cheap, targeted path. Answers "is X available, and in
     // which track" without returning the catalog.
     if (names && names.length > 0) {
         const index = new Map();
         for (const section of sections) {
             for (const pkg of section.packages) {
-                // First writer wins: `packages.txt` sections are ordered, so a name
-                // colliding across tracks resolves to the earliest one.
+                // First writer wins: the sections arrive in a fixed order, so a
+                // name colliding across tracks resolves to the earliest one.
                 if (!index.has(pkg.name.toLowerCase()))
                     index.set(pkg.name.toLowerCase(), { entry: pkg, section: section.title });
             }
@@ -219,7 +254,7 @@ export function queryPackages(sections, { names, query, language, limit }) {
  * Create the package inventory over the bound source: the pool-scope reader
  * when the embedder binds one (a conversation or planning surface), the
  * host-readable farm `inflexa.lock` otherwise (a sandbox agent). The image
- * fragment merges into either report.
+ * record merges into either report.
  */
 export function createListAvailablePackagesTool(deps = {}) {
     const lockCandidates = deps.farmLockFile ? [deps.farmLockFile] : DEFAULT_FARM_LOCK_FILES;
@@ -284,12 +319,15 @@ export function createListAvailablePackagesTool(deps = {}) {
             return "full package list";
         },
         execute: async (input) => {
-            // The baked image fragment merges in when the host can read one; a
-            // missing fragment merges nothing, and that is the normal state for
-            // a host that runs outside the image.
-            const fragmentSections = await readFile(imagePackagesFile, "utf-8")
-                .then(parsePackagesFile)
-                .catch(() => []);
+            // The image record merges in when the host can read a valid one.
+            // An absent record and an invalid record both merge nothing, and
+            // neither is an error: the record is an enrichment, and the farm
+            // or pool inventory stays whole without it. A store packed before
+            // the record existed carries none. The tool holds no logger, thus
+            // an invalid record cannot be reported here — the schema of the
+            // harness refuses it, and the report degrades to the tracks it
+            // could read.
+            const recordSections = readImagePackagesFile(imagePackagesFile).map(imageSections).unwrapOr([]);
             // An unreadable inventory is an expected environment state — model it as an
             // `available: false` data variant telling the caller the set is UNKNOWN,
             // WITH the reason: without it, a structural fault (a damaged dependency
@@ -301,7 +339,7 @@ export function createListAvailablePackagesTool(deps = {}) {
                 }));
                 if (pool.kind === "unavailable")
                     return ok({ available: false, content: `${POOL_UNAVAILABLE_NOTE} The reason: ${pool.reason}.` });
-                return ok(queryPackages([...pool.sections, ...fragmentSections], input));
+                return ok(queryPackages([...pool.sections, ...recordSections], input));
             }
             let lock = null;
             for (const candidate of lockCandidates) {
@@ -312,7 +350,7 @@ export function createListAvailablePackagesTool(deps = {}) {
             if (lock === null) {
                 return ok({ available: false, content: UNAVAILABLE_NOTE });
             }
-            return ok(queryPackages([...lockSections(lock), ...fragmentSections], input));
+            return ok(queryPackages([...lockSections(lock), ...recordSections], input));
         },
     });
 }