@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/input-scan/enrich.js

@@ -16,8 +16,12 @@
  * enrichment reads a bounded number of members per shape whatever the tree's size.
  */
 import { readFile } from "node:fs/promises";
+import { z } from "zod";
 import { runSandboxExec } from "../tools/workspace/run-exec.js";
 import { READOUT_PREFIX_BYTES, readPrefix } from "./readout.js";
+import { safeParseJsonAs } from "../lib/parse-json.js";
+import { presentAt } from "../lib/present.js";
+import { collapseWhitespace } from "../lib/text.js";
 /** Members decoded per shape. One is enough to characterise a set whose names already match. */
 export const MEMBERS_DECODED_PER_SHAPE = 1;
 /** Wall-clock bound on the container-decode exec. It opens footers, nothing more. */
@@ -57,7 +61,7 @@ export async function readHeaders(args) {
     let next = 0;
     await Promise.all(Array.from({ length: Math.min(READOUT_CONCURRENCY, prefixed.length) }, async () => {
         for (let i = next++; i < prefixed.length; i = next++) {
-            const target = prefixed[i];
+            const target = presentAt(prefixed, i, "readout targets");
             readouts.set(target.path, await readFromPrefix(args, target));
         }
     }));
@@ -85,7 +89,7 @@ export async function enrichShapes(args) {
         return [...args.shapes];
     const readouts = await readHeaders({
         ...args,
-        targets: [...targets.entries()].map(([path, shape]) => ({ path, format: shape.format, ...(shape.wrapper ? { wrapper: shape.wrapper } : {}) })),
+        targets: [...targets.entries()].map(([path, shape]) => ({ path, format: shape.format, wrapper: shape.wrapper })),
     });
     const byShape = new Map();
     for (const [path, shape] of targets) {
@@ -105,9 +109,15 @@ async function readFromPrefix(args, target) {
         .unwrapOr({ kind: "read_failed" });
     if (read.kind !== "ok")
         return { path, fields: {}, unavailable: `prefix unreadable (${read.kind})` };
-    const readout = await readPrefix({ prefix: read.bytes, format: target.format, ...(target.wrapper ? { wrapper: target.wrapper } : {}) });
-    return { path, fields: readout.fields, ...(readout.unavailable ? { unavailable: readout.unavailable } : {}) };
+    const readout = await readPrefix({ prefix: read.bytes, format: target.format, wrapper: target.wrapper });
+    return { path, fields: readout.fields, unavailable: readout.unavailable };
 }
+/** One JSON line the decoder prints on stdout: the path it read, its fields, or why it could not. */
+const ReadoutLineSchema = z.object({
+    path: z.string().optional(),
+    fields: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+    unavailable: z.string().optional(),
+});
 async function decodeContainers(args, machine, containers) {
     const readouts = new Map();
     const source = await readFile(CONTAINER_DECODER, "utf8").catch(() => undefined);
@@ -133,18 +143,21 @@ async function decodeContainers(args, machine, containers) {
             continue;
         let parsed;
         try {
-            parsed = JSON.parse(trimmed);
+            parsed = safeParseJsonAs(trimmed, ReadoutLineSchema);
         }
         catch {
+            // The sandbox caps stdout and a timeout can stop the decoder mid-write, so the last line can be cut.
             continue;
         }
-        const target = parsed.path ? byAbsolute.get(parsed.path) : undefined;
+        if (!parsed.success)
+            continue;
+        const target = parsed.data.path ? byAbsolute.get(parsed.data.path) : undefined;
         if (!target)
             continue;
         readouts.set(target.path, {
             path: target.path,
-            fields: parsed.fields ?? {},
-            ...(parsed.unavailable ? { unavailable: parsed.unavailable } : {}),
+            fields: parsed.data.fields ?? {},
+            unavailable: parsed.data.unavailable,
         });
     }
     // A target the decoder said nothing about is told WHY, from the exec's own outcome: the
@@ -158,14 +171,18 @@ async function decodeContainers(args, machine, containers) {
     }
     return readouts;
 }
+const CUT_OUTPUT_REASON = "container decoder output was cut at the sandbox byte cap";
 function describeExecFailure(result) {
+    const cut = result.stdoutTruncated ? ` (${CUT_OUTPUT_REASON})` : "";
     if (result.timedOut)
-        return `container decoder timed out after ${ENRICH_TIMEOUT_SECONDS}s`;
+        return `container decoder timed out after ${ENRICH_TIMEOUT_SECONDS}s${cut}`;
     if (result.syntheticFailure)
-        return `container decoder did not complete: ${result.syntheticFailure.reason}`;
+        return `container decoder did not complete: ${result.syntheticFailure.reason}${cut}`;
     if (result.exitCode !== 0) {
-        const stderr = result.stderr.replace(/\s+/g, " ").trim().slice(0, MAX_STDERR_CHARS);
-        return `container decoder exited ${result.exitCode ?? "with no code"}${stderr ? `: ${stderr}` : ""}`;
+        const stderr = collapseWhitespace(result.stderr).slice(0, MAX_STDERR_CHARS);
+        return `container decoder exited ${result.exitCode ?? "with no code"}${stderr ? `: ${stderr}` : ""}${cut}`;
     }
+    if (result.stdoutTruncated)
+        return CUT_OUTPUT_REASON;
     return "container decoder reported nothing for this member";
 }

package/dist/input-scan/formats.d.ts

@@ -30,10 +30,10 @@ export declare const KNOWN_EXTENSIONS: ReadonlySet<string>;
 export declare function extensionChain(fileName: string): string[];
 /** The extension chain with any compression wrappers stripped from the tail. */
 export declare function innerExtensions(extensions: readonly string[]): string[];
-export interface DetectedFormat {
+export type DetectedFormat = {
     readonly format: string;
     readonly wrapper?: string;
-}
+};
 /**
  * Identify a file's format from a bounded prefix of its bytes, falling back to the
  * extension chain — which is all a wrapped file can offer the host, since reading

package/dist/input-scan/formats.js

@@ -139,6 +139,8 @@ function gzipWrapper(buf) {
     if (buf.length < 12)
         return "gzip";
     const flags = buf[3];
+    if (flags === undefined)
+        return "gzip";
     const hasExtra = (flags & 0x04) !== 0;
     if (!hasExtra)
         return "gzip";
@@ -209,7 +211,7 @@ function textFormat(buf) {
         return "cel";
     if (head.startsWith("track ") || head.startsWith("fixedStep") || head.startsWith("variableStep"))
         return "wig";
-    if (/^<\?xml/.test(head)) {
+    if (head.startsWith("<?xml")) {
         if (head.includes("<indexedmzML") || head.includes("<mzML"))
             return "mzml";
         if (head.includes("<mzXML"))
@@ -239,8 +241,12 @@ export function extensionChain(fileName) {
 /** The extension chain with any compression wrappers stripped from the tail. */
 export function innerExtensions(extensions) {
     const inner = [...extensions];
-    while (inner.length > 0 && WRAPPER_EXTENSIONS.has(inner[inner.length - 1]))
+    for (;;) {
+        const last = inner[inner.length - 1];
+        if (last === undefined || !WRAPPER_EXTENSIONS.has(last))
+            break;
         inner.pop();
+    }
     return inner;
 }
 /**

package/dist/input-scan/markers.d.ts

@@ -9,11 +9,11 @@
  * The catalogue is a floor, not a closed set.
  */
 import type { MemberFile } from "./set-types.js";
-export interface MarkerUnit {
+export type MarkerUnit = {
     readonly label: string;
     readonly root: string;
     readonly members: readonly MemberFile[];
-}
+};
 /** The marker-claimed units of a tree, and the members no marker claimed. */
 export declare function applyMarkers(files: readonly MemberFile[]): {
     units: MarkerUnit[];

package/dist/input-scan/markers.js

@@ -9,11 +9,16 @@
  * The catalogue is a floor, not a closed set.
  */
 import { basenameOf, dirnameOf } from "./tokens.js";
+import { presentFirst } from "../lib/present.js";
 /** A marker whose presence claims the directory it sits in, and nothing below it. */
 const DIRECTORY_MARKERS = [
     {
         label: "feature-barcode-matrix",
-        requires: [/^matrix\.mtx(\.gz)?$/, /^barcodes\.tsv(\.gz)?$/, /^(features|genes)\.tsv(\.gz)?$/],
+        requires: [
+            nameIs("matrix.mtx", "matrix.mtx.gz"),
+            nameIs("barcodes.tsv", "barcodes.tsv.gz"),
+            nameIs("features.tsv", "features.tsv.gz", "genes.tsv", "genes.tsv.gz"),
+        ],
     },
 ];
 /**
@@ -25,11 +30,15 @@ const DIRECTORY_MARKERS = [
  */
 const SUBTREE_MARKERS = [
     { label: "study-manifest", name: "meta_study.txt" },
-    { label: "dataset-descriptor", name: "dataset_description.json", corroborate: /^sub-/ },
+    { label: "dataset-descriptor", name: "dataset_description.json", corroborate: (segment) => segment.startsWith("sub-") },
 ];
-function hasCorroboratingChild(files, root, pattern) {
+function nameIs(...names) {
+    const known = new Set(names);
+    return (name) => known.has(name);
+}
+function hasCorroboratingChild(files, root, matches) {
     const prefix = root === "" ? "" : `${root}/`;
-    return files.some((file) => file.path.startsWith(prefix) && pattern.test(file.path.slice(prefix.length).split("/")[0]));
+    return files.some((file) => file.path.startsWith(prefix) && matches(presentFirst(file.path.slice(prefix.length).split("/"), "the first path segment")));
 }
 /** The marker-claimed units of a tree, and the members no marker claimed. */
 export function applyMarkers(files) {
@@ -47,7 +56,7 @@ export function applyMarkers(files) {
     for (const [directory, members] of byDirectory) {
         const names = members.map((member) => basenameOf(member.path));
         for (const marker of DIRECTORY_MARKERS) {
-            if (marker.requires.every((pattern) => names.some((name) => pattern.test(name))))
+            if (marker.requires.every((matches) => names.some((name) => matches(name))))
                 directories.push({ label: marker.label, root: directory });
         }
         for (const marker of SUBTREE_MARKERS) {

package/dist/input-scan/menu.d.ts

@@ -43,13 +43,13 @@ export declare const MAX_CROSSED_SLOTS = 3;
  * a full 24-member crossing or 8 members each at one timepoint, and the two are different
  * experimental designs. The margins alone cannot tell them apart.
  */
-export interface SetCrossing {
+export type SetCrossing = {
     readonly setId: string;
     readonly slotIds: readonly string[];
     readonly observedCombinations: number;
     /** The full cross product, or `null` when it is past counting. */
     readonly possibleCombinations: number | null;
-}
+};
 /**
  * Measured overlap between two sets' slots, with its gaps.
  *
@@ -57,7 +57,7 @@ export interface SetCrossing {
  * dimension plausible; the values present in one and absent from the other are what make
  * it checkable.
  */
-export interface SlotCorrespondence {
+export type SlotCorrespondence = {
     readonly sets: readonly [string, string];
     readonly slots: readonly [string, string];
     readonly shared: number;
@@ -66,15 +66,15 @@ export interface SlotCorrespondence {
     readonly sharedSample: readonly string[];
     readonly onlyInFirstSample: readonly string[];
     readonly onlyInSecondSample: readonly string[];
-}
+};
 /** The tail the menu did not list, in aggregate. */
-export interface UnlistedSets {
+export type UnlistedSets = {
     readonly sets: number;
     readonly members: number;
     readonly files: number;
     readonly totalBytes: number;
-}
-export interface SetMenu {
+};
+export type SetMenu = {
     readonly fileCount: number;
     readonly keptFileCount: number;
     /** The addressable entries. An operation may name one of these ids and no other. */
@@ -95,7 +95,7 @@ export interface SetMenu {
     readonly truncated: boolean;
     /** Leftovers whose header readout was elided by the readout budget. */
     readonly readoutsElided: number;
-}
+};
 /**
  * Slot overlap across the listed sets, strongest first.
  *
@@ -110,12 +110,12 @@ export declare function buildCorrespondences(detected: DetectedSets, sets: reado
  * which is the whole content of the observation.
  */
 export declare function buildCrossings(detected: DetectedSets, sets: readonly DetectedSet[]): SetCrossing[];
-export interface BuildSetMenuOptions {
+export type BuildSetMenuOptions = {
     readonly headers?: ReadonlyMap<string, HeaderReadout>;
     /** The walk stopped at its ceiling; see {@link SetMenu.truncated}. */
     readonly truncated?: boolean;
     readonly readoutsElided?: number;
-}
+};
 /** Project a scan into the bounded menu the agent authors against. */
 export declare function buildSetMenu(detected: DetectedSets, options?: BuildSetMenuOptions): SetMenu;
 /**

package/dist/input-scan/quarantine.d.ts

@@ -10,8 +10,8 @@ import type { QuarantineReason, QuarantineSummary } from "./set-types.js";
 import type { ScannedFile } from "./types.js";
 /** The rule a path trips, or `undefined` when it trips none. */
 export declare function quarantineReason(path: string): QuarantineReason | undefined;
-export interface QuarantineResult {
+export type QuarantineResult = {
     readonly kept: readonly ScannedFile[];
     readonly summary: QuarantineSummary;
-}
+};
 export declare function quarantine(files: readonly ScannedFile[]): QuarantineResult;

package/dist/input-scan/quarantine.js

@@ -7,38 +7,43 @@
  * be reported: a wrongly quarantined file that no one can see is worse than the junk.
  */
 import { MAX_QUARANTINE_SAMPLE } from "./tuning.js";
+import { presentLast } from "../lib/present.js";
 const EXACT_JUNK_NAMES = new Set([".DS_Store", "Thumbs.db", "desktop.ini"]);
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- LibreOffice-style atomic writes suffix `.tmp-` with a full UUID; the dashed hex groups are the shape.
+const TMP_UUID_SUFFIX = /\.tmp-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the same writer without a UUID: `.tmp-` and at least eight hex digits.
+const TMP_HEX_SUFFIX = /\.tmp-[0-9a-fA-F]{8,}$/;
 const NAME_RULES = [
-    { pattern: /^\._/, reason: "os-junk" },
-    { pattern: /^~\$/, reason: "editor-temp" },
-    { pattern: /~$/, reason: "editor-temp" },
-    { pattern: /^\.~lock\..*#$/, reason: "editor-temp" },
-    { pattern: /\.swp$/, reason: "editor-temp" },
-    { pattern: /\.part$/, reason: "partial-download" },
-    { pattern: /\.filepart$/, reason: "partial-download" },
-    { pattern: /\.crdownload$/, reason: "partial-download" },
-    { pattern: /\.download$/, reason: "partial-download" },
-    { pattern: /\.tmp$/, reason: "atomic-write-temp" },
-    { pattern: /^\.nfs/, reason: "atomic-write-temp" },
-    { pattern: /\.tmp-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/, reason: "atomic-write-temp" },
-    { pattern: /\.tmp-[0-9a-fA-F]{8,}$/, reason: "atomic-write-temp" },
+    { matches: (name) => name.startsWith("._"), reason: "os-junk" },
+    { matches: (name) => name.startsWith("~$"), reason: "editor-temp" },
+    { matches: (name) => name.endsWith("~"), reason: "editor-temp" },
+    { matches: (name) => name.startsWith(".~lock.") && name.endsWith("#"), reason: "editor-temp" },
+    { matches: (name) => name.endsWith(".swp"), reason: "editor-temp" },
+    { matches: (name) => name.endsWith(".part"), reason: "partial-download" },
+    { matches: (name) => name.endsWith(".filepart"), reason: "partial-download" },
+    { matches: (name) => name.endsWith(".crdownload"), reason: "partial-download" },
+    { matches: (name) => name.endsWith(".download"), reason: "partial-download" },
+    { matches: (name) => name.endsWith(".tmp"), reason: "atomic-write-temp" },
+    { matches: (name) => name.startsWith(".nfs"), reason: "atomic-write-temp" },
+    { matches: (name) => TMP_UUID_SUFFIX.test(name), reason: "atomic-write-temp" },
+    { matches: (name) => TMP_HEX_SUFFIX.test(name), reason: "atomic-write-temp" },
 ];
 const SEGMENT_RULES = [
-    { pattern: /^__MACOSX$/, reason: "os-junk" },
-    { pattern: /^\.Trash-/, reason: "os-junk" },
+    { matches: (segment) => segment === "__MACOSX", reason: "os-junk" },
+    { matches: (segment) => segment.startsWith(".Trash-"), reason: "os-junk" },
 ];
 /** The rule a path trips, or `undefined` when it trips none. */
 export function quarantineReason(path) {
     const segments = path.split("/");
-    const name = segments[segments.length - 1];
+    const name = presentLast(segments, "the path name");
     if (EXACT_JUNK_NAMES.has(name))
         return "os-junk";
     for (const rule of NAME_RULES)
-        if (rule.pattern.test(name))
+        if (rule.matches(name))
             return rule.reason;
     for (const segment of segments)
         for (const rule of SEGMENT_RULES)
-            if (rule.pattern.test(segment))
+            if (rule.matches(segment))
                 return rule.reason;
     return undefined;
 }

package/dist/input-scan/readout-budget.d.ts

@@ -19,11 +19,11 @@ import type { DetectedSet, DetectedSets, MemberFile, ReadoutSelection } from "./
  */
 export declare const MAX_LEFTOVER_READOUTS = 64;
 /** A file the selection named, with what the scan already knows about its bytes. */
-export interface ReadoutTarget {
+export type ReadoutTarget = {
     readonly path: string;
     readonly format: string;
     readonly wrapper?: string;
-}
+};
 export declare function selectReadouts(sets: readonly DetectedSet[], leftovers: readonly MemberFile[]): ReadoutSelection;
 /**
  * The selection as readout targets. The format the scan detected rides along, so the

package/dist/input-scan/readout-budget.js

@@ -55,7 +55,7 @@ export function readoutTargets(detected) {
         if (!member || seen.has(path))
             continue;
         seen.add(path);
-        targets.push({ path, format: member.format, ...(member.wrapper ? { wrapper: member.wrapper } : {}) });
+        targets.push({ path, format: member.format, wrapper: member.wrapper });
     }
     return targets;
 }

package/dist/input-scan/readout.d.ts

@@ -14,11 +14,11 @@ export declare const READOUT_PREFIX_BYTES = 262144;
 /** Cap on the text window a readout inspects, whether decompressed or raw. */
 export declare const READOUT_TEXT_BYTES = 262144;
 export type ReadoutFields = Record<string, string | number | boolean>;
-export interface PrefixReadout {
+export type PrefixReadout = {
     readonly fields: ReadoutFields;
     /** Why the fields are thin or empty. Present alongside whatever WAS read. */
     readonly unavailable?: string;
-}
+};
 /**
  * Read what a bounded prefix can say about a file.
  *

package/dist/input-scan/readout.js

@@ -10,6 +10,12 @@
  * `enrich.ts`), which is what makes the whole surface testable from synthetic bytes.
  */
 import { constants as zlibConstants, createGunzip, createZstdDecompress } from "node:zlib";
+import { z } from "zod";
+import { parseJsonAs } from "../lib/parse-json.js";
+import { isUnknownArray } from "../lib/unknown-array.js";
+import { parseUnknownRecord } from "../lib/unknown-containers.js";
+import { collapseWhitespace, splitLines } from "../lib/text.js";
+import { presentAt, presentFirst } from "../lib/present.js";
 /** Bytes read from each file. The readout's whole per-file I/O budget. */
 export const READOUT_PREFIX_BYTES = 262_144;
 /** Cap on the text window a readout inspects, whether decompressed or raw. */
@@ -110,7 +116,7 @@ function decodeText(buf, format) {
     return textFields(buf.subarray(0, READOUT_TEXT_BYTES).toString("utf8"), format);
 }
 function textFields(text, format) {
-    const lines = text.split(/\r?\n/).filter((line) => line.trim() !== "");
+    const lines = splitLines(text).filter((line) => line.trim() !== "");
     const head = lines[0];
     if (head === undefined)
         return { fields: {}, unavailable: "no text in the prefix" };
@@ -127,7 +133,7 @@ function textFields(text, format) {
     if (head.startsWith("@HD") || head.startsWith("@SQ"))
         return samFields(lines);
     if (head.startsWith("@") && lines.length > 1)
-        return { fields: { firstRecord: clip(head.slice(1), MAX_RECORD_CHARS), readLength: lines[1].length } };
+        return { fields: { firstRecord: clip(head.slice(1), MAX_RECORD_CHARS), readLength: presentAt(lines, 1, "prefix lines").length } };
     return delimitedFields(lines) ?? { fields: { firstLine: clip(head, MAX_LINE_CHARS), linesInPrefix: lines.length } };
 }
 /**
@@ -163,14 +169,16 @@ function metaHeaderFields(lines) {
     }
     return { fields };
 }
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the SAM header sort order: `SO:<value>` at the line start or after a tab, ending at the next tab.
+const SAM_SORT_ORDER_FIELD = /(?:^|\t)SO:([^\t]+)/;
 function samFields(lines) {
     const fields = {
         referenceSequences: countPrefixed(lines, "@SQ"),
         readGroups: countPrefixed(lines, "@RG"),
     };
-    const sortOrder = /(?:^|\t)SO:([^\t]+)/.exec(lines.find((line) => line.startsWith("@HD")) ?? "");
+    const sortOrder = SAM_SORT_ORDER_FIELD.exec(lines.find((line) => line.startsWith("@HD")) ?? "");
     if (sortOrder)
-        fields.sortOrder = clip(sortOrder[1], 20);
+        fields.sortOrder = clip(presentAt(sortOrder, 1, "the SO: capture group"), 20);
     return { fields };
 }
 const DELIMITERS = [
@@ -200,7 +208,7 @@ function delimitedFields(lines) {
     const headerIndex = lines.findIndex((line) => !line.startsWith("#"));
     if (headerIndex < 0)
         return undefined;
-    const header = lines[headerIndex];
+    const header = presentAt(lines, headerIndex, "the header line");
     const delimiter = sniffDelimiter(header);
     if (delimiter === undefined)
         return undefined;
@@ -228,10 +236,11 @@ function looksLikeHeader(columns) {
 }
 function splitDelimited(line, delimiter) {
     const cells = [];
+    const chars = line.split("");
     let current = "";
     let quoted = false;
     for (let index = 0; index < line.length; index++) {
-        const char = line[index];
+        const char = presentAt(chars, index, "line characters");
         if (quoted) {
             if (char !== '"')
                 current += char;
@@ -257,18 +266,17 @@ function splitDelimited(line, delimiter) {
 }
 function jsonFields(text, lines) {
     const whole = parseJson(text.slice(0, READOUT_TEXT_BYTES));
-    if (Array.isArray(whole)) {
+    if (isUnknownArray(whole)) {
         const first = whole[0];
-        return {
-            fields: {
-                jsonType: "array",
-                elementCount: whole.length,
-                ...(isRecord(first) ? { firstElementKeys: joinKeys(Object.keys(first)) } : {}),
-            },
-        };
+        const fields = { jsonType: "array", elementCount: whole.length };
+        const firstRecord = parseUnknownRecord(first);
+        if (firstRecord !== undefined)
+            fields.firstElementKeys = joinKeys(Object.keys(firstRecord));
+        return { fields };
     }
-    if (isRecord(whole)) {
-        const keys = Object.keys(whole);
+    const wholeRecord = parseUnknownRecord(whole);
+    if (wholeRecord !== undefined) {
+        const keys = Object.keys(wholeRecord);
         return { fields: { jsonType: "object", keyCount: keys.length, keys: joinKeys(keys) } };
     }
     if (whole !== undefined)
@@ -277,35 +285,43 @@ function jsonFields(text, lines) {
     const candidates = lines.slice(0, MAX_META_LINES);
     const parsed = candidates.map((line) => parseJson(line));
     const complete = parsed.filter((value) => value !== undefined);
-    const record = parsed.find(isRecord);
+    const record = parsed.reduce((found, value) => found ?? parseUnknownRecord(value), undefined);
     if (record !== undefined && complete.length >= Math.max(1, candidates.length - 1)) {
         return { fields: { jsonType: "json-lines", recordsInPrefix: lines.length, keys: joinKeys(Object.keys(record)) } };
     }
-    return { fields: { firstLine: clip(lines[0], MAX_LINE_CHARS) }, unavailable: "JSON document extends past the readout prefix" };
+    return { fields: { firstLine: clip(presentFirst(lines, "prefix lines"), MAX_LINE_CHARS) }, unavailable: "JSON document extends past the readout prefix" };
 }
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- a top-level YAML key: an identifier from the line start, then `:` and end of line or whitespace.
+const YAML_TOP_LEVEL_KEY = /^([A-Za-z_][\w.-]*):(\s|$)/;
 /** Top-level keys, read positionally: an unindented `key:` line opens a mapping entry. */
 function yamlFields(lines) {
     const keys = [];
     for (const line of lines.slice(0, MAX_META_LINES)) {
-        const match = /^([A-Za-z_][\w.-]*):(\s|$)/.exec(line);
+        const match = YAML_TOP_LEVEL_KEY.exec(line);
         if (match)
-            keys.push(match[1]);
+            keys.push(presentAt(match, 1, "the yaml key capture"));
     }
     const documents = lines.filter((line) => line.trim() === "---").length;
-    return {
-        fields: {
-            topLevelKeyCount: keys.length,
-            topLevelKeys: joinKeys(keys),
-            linesInPrefix: lines.length,
-            ...(documents > 0 ? { documentSeparators: documents } : {}),
-        },
+    const fields = {
+        topLevelKeyCount: keys.length,
+        topLevelKeys: joinKeys(keys),
+        linesInPrefix: lines.length,
     };
+    if (documents > 0)
+        fields.documentSeparators = documents;
+    return { fields };
 }
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- an ATX heading opens with one to six `#` and a whitespace character.
+const MARKDOWN_HEADING = /^#{1,6}\s/;
 function markdownFields(lines) {
-    const headings = lines.filter((line) => /^#{1,6}\s/.test(line));
+    const headings = lines.filter((line) => MARKDOWN_HEADING.test(line));
+    const first = headings[0] ?? presentFirst(lines, "prefix lines");
+    let markers = 0;
+    while (first.charAt(markers) === "#")
+        markers++;
     return {
         fields: {
-            title: clip((headings[0] ?? lines[0]).replace(/^#+\s*/, ""), MAX_LINE_CHARS),
+            title: clip(first.slice(markers).trimStart(), MAX_LINE_CHARS),
             headings: headings.length,
             linesInPrefix: lines.length,
         },
@@ -313,15 +329,12 @@ function markdownFields(lines) {
 }
 function parseJson(text) {
     try {
-        return JSON.parse(text);
+        return parseJsonAs(text, z.json());
     }
     catch {
         return undefined;
     }
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function joinKeys(keys) {
     return clip(keys
         .slice(0, MAX_COLUMNS_REPORTED)
@@ -332,5 +345,5 @@ function countPrefixed(lines, prefix) {
     return lines.filter((line) => line.startsWith(prefix)).length;
 }
 function clip(text, limit) {
-    return text.replace(/\s+/g, " ").trim().slice(0, limit);
+    return collapseWhitespace(text).slice(0, limit);
 }

package/dist/input-scan/scan.d.ts

@@ -26,7 +26,7 @@ import type { InputScan, InputScanManifest, ScannedFile } from "./types.js";
  * capability exists to remove.
  */
 export declare const MAX_SCANNED_FILES = 100000;
-export interface ScanInputTreeArgs {
+export type ScanInputTreeArgs = {
     readonly session: AgentSession;
     readonly fs: WorkspaceFilesystem;
     /** Directory to scan, relative to the analysis root (e.g. `data/inputs`). */
@@ -34,7 +34,7 @@ export interface ScanInputTreeArgs {
     /** Walk ceiling; defaults to {@link MAX_SCANNED_FILES}. */
     readonly limit?: number;
     readonly signal?: AbortSignal;
-}
+};
 /** Assemble a manifest from an already-walked file set. Pure — the seam of the unit tests. */
 export declare function buildManifest(root: string, files: readonly ScannedFile[], truncated: boolean, limit?: number): InputScan;
 /** Walk a staged input tree and observe its shapes. No model, no container. */

package/dist/input-scan/scan.js

@@ -36,6 +36,8 @@ async function walk(args) {
     while (queue.length > 0) {
         signal?.throwIfAborted();
         const dir = queue.shift();
+        if (dir === undefined)
+            break;
         const listing = unwrapOrThrow(await fs.list({ session, path: dir }));
         // A directory that vanished mid-walk, or one the seam refuses, is not a scan
         // failure — the tree is being described, not validated.
@@ -60,7 +62,7 @@ async function walk(args) {
                 size: entry.size ?? 0,
                 extensions,
                 format,
-                ...(wrapper ? { wrapper } : {}),
+                wrapper,
             });
         }
     }
@@ -75,18 +77,18 @@ function formatCensus(files) {
 /** Assemble a manifest from an already-walked file set. Pure — the seam of the unit tests. */
 export function buildManifest(root, files, truncated, limit = MAX_SCANNED_FILES) {
     const observed = observeShapes(files);
-    const manifest = {
+    const base = {
         root,
         fileCount: files.length,
         totalBytes: files.reduce((sum, f) => sum + f.size, 0),
         truncated,
-        ...(truncated ? { scanLimit: limit } : {}),
         shapesTruncated: observed.shapesTruncated,
         formats: formatCensus(files),
         shapes: observed.shapes,
         valueOverlaps: observed.valueOverlaps,
         unstructured: observed.unstructured,
     };
+    const manifest = truncated ? { ...base, scanLimit: limit } : base;
     return { files, manifest, positionValues: observed.positionValues };
 }
 /** Walk a staged input tree and observe its shapes. No model, no container. */
@@ -105,7 +107,7 @@ export function formatBytes(bytes) {
         value /= 1024;
         unit++;
     }
-    return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
+    return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${String(units[unit])}`;
 }
 /**
  * Render a manifest for a briefing or a tool result.
@@ -145,7 +147,7 @@ export function renderInputScanManifest(manifest) {
             }
             if (shape.header) {
                 const fields = Object.entries(shape.header.fields)
-                    .map(([key, value]) => `${key}=${value}`)
+                    .map(([key, value]) => `${key}=${String(value)}`)
                     .join(", ");
                 lines.push(`  - header (${shape.header.path}): ${fields || shape.header.unavailable || "no fields read"}`);
             }