humanish 0.115.0 → 0.117.0

package/dist/run/contained-output.js

@@ -150,73 +150,162 @@ export async function createContainedOutputFile(rootInput, relativePath, data) {
     }
     await handle.close();
 }
-/** Read one regular file only when both lexical and physical paths stay in root. */
-export async function readContainedRegularFile(rootInput, relativePath) {
-    const handle = await openContainedRegularFile(rootInput, relativePath);
-    if (!handle)
-        return null;
+// The most humanish reads of one file of each kind. A larger file is refused unread.
+/**
+ * A file in a run directory or a preflight journal. verify reads every run file whole to scan it,
+ * and a frame whole to check it, so this covers the largest screenshot src/evidence/image.ts
+ * accepts (32 MiB). Every other reader of a run file uses the same limit, so no command reads a
+ * run file that verify could not scan.
+ */
+export const RUN_ARTIFACT_MAX_BYTES = 32 * 1024 * 1024;
+/** `.humanish/runs/latest.json`: a run id and a path. */
+export const LATEST_POINTER_MAX_BYTES = 64 * 1024;
+/** A file a person writes in the project: study, persona and scenario YAML, package.json, agent instructions. */
+export const PROJECT_FILE_MAX_BYTES = 4 * 1024 * 1024;
+/** `relativePath` and why it was refused, as a clause: "x.yaml is larger than 4194304 bytes, ...". */
+export function refusalText(relativePath, refusal) {
+    switch (refusal.reason) {
+        case "too-large":
+            return `${relativePath} is larger than ${refusal.limit} bytes, the most humanish reads of it`;
+        case "changed":
+            return `${relativePath} changed while humanish read it`;
+        case "directory":
+            return `${relativePath} is a folder`;
+        case "not-regular":
+            return `${relativePath} is not a single-link regular file`;
+        case "unsafe-path":
+            return `${relativePath} leaves its folder or passes through a link`;
+        case "unreadable":
+            return `${relativePath} could not be read`;
+    }
+}
+/** A refused contained read, for a caller that stops on one. The message names the file. */
+export class ContainedReadRefusedError extends Error {
+    relativePath;
+    refusal;
+    constructor(relativePath, refusal) {
+        super(`${refusalText(relativePath, refusal)}.`);
+        this.relativePath = relativePath;
+        this.refusal = refusal;
+        this.name = "ContainedReadRefusedError";
+    }
+}
+/**
+ * Read one regular file only when both lexical and physical paths stay in root and it holds at
+ * most `maxBytes`. A larger file is refused without being read, and one that grows past
+ * `maxBytes` while it is read is refused after at most `maxBytes + 1` bytes. `missing` means
+ * nothing is at the path, or a folder on it is missing.
+ */
+export async function readContainedRegularFile(rootInput, relativePath, maxBytes) {
+    const opened = await openContained(rootInput, relativePath);
+    if (opened.status === "missing")
+        return opened;
+    const refused = (reason) => ({
+        status: "refused",
+        reason,
+        limit: maxBytes,
+    });
+    if (opened.status === "refused")
+        return refused(opened.reason);
+    const { handle } = opened;
     try {
-        return await handle.readFile();
+        if ((await handle.stat()).size > maxBytes)
+            return refused("too-large");
+        const bytes = await readOpenedAtMost(handle, maxBytes);
+        return bytes === null ? refused("changed") : { status: "read", bytes };
     }
     catch {
-        return null;
+        return refused("unreadable");
     }
     finally {
         await handle.close().catch(() => { });
     }
 }
 /**
- * Whether a contained path is confirmed absent. A present entry that readContainedRegularFile
- * refuses or fails to read is not absent.
+ * At most `maxBytes` from the start of an opened file, or null when it holds more. It reads by
+ * position, in chunks of up to 64 KiB, and stops one byte past the limit, so a file that grew
+ * after it was opened is never read whole.
  */
-export async function containedPathAbsent(rootInput, relativePath) {
-    try {
-        assertSafeRelativeOutputPath(relativePath, false);
-        const root = await resolveOutputRoot(rootInput);
-        await lstat(path.resolve(root, normalizeRelativeOutputPath(relativePath)));
-        return false;
-    }
-    catch (error) {
-        return error.code === "ENOENT";
+export async function readOpenedAtMost(handle, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes + 1 - total));
+        const { bytesRead } = await handle.read(chunk, 0, chunk.length, total);
+        if (bytesRead === 0)
+            return Buffer.concat(chunks, total);
+        total += bytesRead;
+        if (total > maxBytes)
+            return null;
+        chunks.push(chunk.subarray(0, bytesRead));
     }
 }
 /** The caller owns this checked descriptor and must close it after reading/streaming. */
 export async function openContainedRegularFile(rootInput, relativePath) {
-    let handle;
+    const opened = await openContained(rootInput, relativePath);
+    return opened.status === "open" ? opened.handle : null;
+}
+/** The open behind both readers: every check, and what stopped it when one failed. */
+async function openContained(rootInput, relativePath) {
+    const refused = (reason) => ({ status: "refused", reason });
+    const missingOr = (error, reason) => isNodeError(error) && error.code === "ENOENT"
+        ? { status: "missing" }
+        : isNodeError(error) && (error.code === "EACCES" || error.code === "EPERM")
+            ? refused("unreadable")
+            : refused(reason);
     try {
         assertSafeRelativeOutputPath(relativePath, false);
-        const root = await resolveOutputRoot(rootInput);
-        const candidate = path.resolve(root, normalizeRelativeOutputPath(relativePath));
-        if (!isPathInside(root, candidate) || candidate === root) {
-            return null;
-        }
+    }
+    catch {
+        return refused("unsafe-path");
+    }
+    let root;
+    try {
+        root = await resolveOutputRoot(rootInput);
+    }
+    catch {
+        return refused("changed");
+    }
+    const candidate = path.resolve(root, normalizeRelativeOutputPath(relativePath));
+    if (!isPathInside(root, candidate) || candidate === root)
+        return refused("unsafe-path");
+    let before;
+    try {
         await assertContainedDirectoryChain(root, path.dirname(candidate));
-        const before = await lstat(candidate, { bigint: true });
-        if (before.isSymbolicLink() || !before.isFile() || before.nlink > 1n) {
-            return null;
-        }
-        const physicalFile = await realpath(candidate);
-        if (!isPathInside(root, physicalFile)) {
-            return null;
-        }
-        handle = await open(candidate, constants.O_RDONLY | constants.O_NOFOLLOW);
+        before = await lstat(candidate, { bigint: true });
+    }
+    catch (error) {
+        return missingOr(error, "unsafe-path");
+    }
+    if (before.isDirectory())
+        return refused("directory");
+    if (before.isSymbolicLink() || !before.isFile() || before.nlink > 1n)
+        return refused("not-regular");
+    let handle;
+    try {
+        if (!isPathInside(root, await realpath(candidate)))
+            return refused("unsafe-path");
+        // O_NONBLOCK: a file swapped for a FIFO after the lstat opens at once and fails the fstat
+        // below, where a blocking open would wait for a writer.
+        handle = await open(candidate, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        return missingOr(error, "changed");
+    }
+    try {
         const after = await handle.stat({ bigint: true });
         if (!after.isFile() ||
             after.nlink > 1n ||
             after.dev !== before.dev ||
-            after.ino !== before.ino) {
+            after.ino !== before.ino ||
+            (await resolveOutputRoot(rootInput)) !== root)
             throw new Error("Artifact identity changed.");
-        }
-        const revalidatedRoot = await resolveOutputRoot(rootInput);
-        if (revalidatedRoot !== root) {
-            throw new Error("Artifact root changed.");
-        }
         await assertContainedDirectoryChain(root, path.dirname(candidate));
-        return handle;
+        return { status: "open", handle };
     }
     catch {
-        await handle?.close().catch(() => { });
-        return null;
+        await handle.close().catch(() => { });
+        return refused("changed");
     }
 }
 export function assertSafeOutputPathSegment(value, label = "Output path segment") {
@@ -229,6 +318,16 @@ export function assertSafeOutputPathSegment(value, label = "Output path segment"
         throw new Error(`${label} must be one non-empty path segment.`);
     }
 }
+/** A non-empty relative path with no empty, `.` or `..` segment: the names a contained read accepts. */
+export function isSafeRelativeFilePath(value) {
+    try {
+        assertSafeRelativeOutputPath(value, false);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function assertSafeRelativeOutputPath(value, allowEmpty) {
     if ((!allowEmpty && value.length === 0) || value.includes("\0")) {
         throw new Error("Output path must be a non-empty relative path.");

package/dist/run/detail.d.ts

@@ -50,7 +50,8 @@ export interface RunDetail {
 }
 /**
  * Read one run's participants. Returns null when the run has no readable bundle yet, an ordinary
- * state for a run that has just started, not a failure.
+ * state for a run that has just started, not a failure. Throws when run.json is there and cannot
+ * be read: larger than RUN_ARTIFACT_MAX_BYTES, a link, or refused by the system.
  *
  * Reads the bundle narrowly rather than through `loadRunBundle`, which applies the strict
  * evidence-of-record guard. That guard is right for verification and wrong here: a mid-run flush is

package/dist/run/detail.js

@@ -14,7 +14,7 @@ import { resolveRunPath } from "./locate.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { savedCaption } from "./participant-caption.js";
 import { recordedPersonaId, streamParticipantIdOf } from "./participant-records.js";
-import { readContainedRegularFile } from "./contained-output.js";
+import { ContainedReadRefusedError, readContainedRegularFile, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
 import { isPathInside, resolvePhysicalCwd } from "./paths.js";
 const RUN_DETAIL_SCHEMA = "humanish.run-detail.v1";
 /**
@@ -105,7 +105,8 @@ function costOf(trace) {
 }
 /**
  * Read one run's participants. Returns null when the run has no readable bundle yet, an ordinary
- * state for a run that has just started, not a failure.
+ * state for a run that has just started, not a failure. Throws when run.json is there and cannot
+ * be read: larger than RUN_ARTIFACT_MAX_BYTES, a link, or refused by the system.
  *
  * Reads the bundle narrowly rather than through `loadRunBundle`, which applies the strict
  * evidence-of-record guard. That guard is right for verification and wrong here: a mid-run flush is
@@ -118,13 +119,17 @@ export async function readRunDetail(cwdInput, runId) {
     const runPaths = await resolveRunPath(cwd, runId).catch(() => null);
     if (runPaths === null)
         return null;
+    // A contained read: a run.json swapped for a symlink or hardlink after resolve is refused.
+    const raw = await readContainedRegularFile(runPaths, RUN_BUNDLE_FILE, RUN_ARTIFACT_MAX_BYTES);
+    // One that changed while it was read is being written now, as a torn one is below. One that is
+    // there and refused for another reason is not a run that has yet to write it.
+    if (raw.status === "refused" && raw.reason !== "changed")
+        throw new ContainedReadRefusedError(RUN_BUNDLE_FILE, raw);
+    if (raw.status !== "read")
+        return null;
     let bundle;
     try {
-        // A contained read: a run.json swapped for a symlink or hardlink after resolve is refused.
-        const raw = await readContainedRegularFile(runPaths, RUN_BUNDLE_FILE);
-        if (raw === null)
-            return null;
-        const parsed = JSON.parse(raw.toString("utf8"));
+        const parsed = JSON.parse(raw.bytes.toString("utf8"));
         if (parsed === null || typeof parsed !== "object")
             return null;
         bundle = parsed;

package/dist/run/escape-sequences.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The stretches of the text a value's view drops or decodes, in order and without overlap, each
+ * as [start, end): operating-system commands (`ESC ]`), control sequences (`ESC [`) and the
+ * two-byte escapes `ESC 7`, `ESC 8`, `ESC =` and `ESC >`, raw or JSON-escaped (`\u001b`), and runs
+ * of percent escapes. An operating-system command ends at the first bell character after it or,
+ * with none after it, at the last `ESC \` in the text. A JSON-escaped one ends at the first
+ * backslash after it, which must start `\u0007` or `\u001b\\`. A start with no end is left as
+ * written. One regex of the six shapes finds the same stretches, in time quadratic in a run of
+ * unterminated commands; this takes time linear in the text.
+ */
+export declare function escapeSequences(text: string): [number, number][];

package/dist/run/escape-sequences.js

@@ -0,0 +1,93 @@
+// What a terminal draws with and what a URL encodes with, found in one pass. RunSecrets looks for a
+// value in a view of the text with the first dropped and the second decoded, so that a color code
+// or a percent escape inside a value does not hide it.
+const BEL = "\x07";
+const STRING_TERMINATOR = "\x1b\\";
+const between = (code, low, high) => code >= low && code <= high;
+const isHexDigit = (code) => between(code, 0x30, 0x39) || between(code, 0x41, 0x46) || between(code, 0x61, 0x66);
+/**
+ * The end of a control sequence whose parameter bytes start at `from`: parameter bytes, then
+ * intermediate bytes, then one final byte. -1 when no final byte follows.
+ */
+function controlSequenceEnd(text, from) {
+    let at = from;
+    while (at < text.length && between(text.charCodeAt(at), 0x30, 0x3f))
+        at += 1;
+    while (at < text.length && between(text.charCodeAt(at), 0x20, 0x2f))
+        at += 1;
+    return at < text.length && between(text.charCodeAt(at), 0x40, 0x7e) ? at + 1 : -1;
+}
+/** The end of the run of percent escapes that starts at `from`, or `from` when none does. */
+function percentRunEnd(text, from) {
+    let end = from;
+    while (end + 2 < text.length &&
+        text[end] === "%" &&
+        isHexDigit(text.charCodeAt(end + 1)) &&
+        isHexDigit(text.charCodeAt(end + 2)))
+        end += 3;
+    return end;
+}
+/**
+ * The stretches of the text a value's view drops or decodes, in order and without overlap, each
+ * as [start, end): operating-system commands (`ESC ]`), control sequences (`ESC [`) and the
+ * two-byte escapes `ESC 7`, `ESC 8`, `ESC =` and `ESC >`, raw or JSON-escaped (`\u001b`), and runs
+ * of percent escapes. An operating-system command ends at the first bell character after it or,
+ * with none after it, at the last `ESC \` in the text. A JSON-escaped one ends at the first
+ * backslash after it, which must start `\u0007` or `\u001b\\`. A start with no end is left as
+ * written. One regex of the six shapes finds the same stretches, in time quadratic in a run of
+ * unterminated commands; this takes time linear in the text.
+ */
+export function escapeSequences(text) {
+    const lastTerminator = text.lastIndexOf(STRING_TERMINATOR);
+    // The first bell character at or after the last place searched from. Starts only move forward,
+    // so each stretch of text is searched once.
+    let bel = text.indexOf(BEL);
+    const commandEnd = (start) => {
+        if (bel !== -1 && bel < start + 2)
+            bel = text.indexOf(BEL, start + 2);
+        if (bel !== -1)
+            return bel + 1;
+        return lastTerminator >= start + 2 ? lastTerminator + STRING_TERMINATOR.length : -1;
+    };
+    const jsonCommandEnd = (start) => {
+        const backslash = text.indexOf("\\", start + 7);
+        if (backslash === -1)
+            return -1;
+        if (text.startsWith("\\u0007", backslash))
+            return backslash + 6;
+        return text.startsWith("\\u001b\\\\", backslash) ? backslash + 8 : -1;
+    };
+    const endAt = (at) => {
+        switch (text[at]) {
+            case "\x1b": {
+                const next = text[at + 1];
+                if (next === "]")
+                    return commandEnd(at);
+                if (next === "[")
+                    return controlSequenceEnd(text, at + 2);
+                return next !== undefined && "78=>".includes(next) ? at + 2 : -1;
+            }
+            case "\\":
+                if (text.startsWith("\\u001b]", at))
+                    return jsonCommandEnd(at);
+                return text.startsWith("\\u001b[", at) ? controlSequenceEnd(text, at + 7) : -1;
+            case "%": {
+                const end = percentRunEnd(text, at);
+                return end === at ? -1 : end;
+            }
+            default:
+                return -1;
+        }
+    };
+    const sequences = [];
+    for (let at = 0; at < text.length;) {
+        const end = endAt(at);
+        if (end === -1)
+            at += 1;
+        else {
+            sequences.push([at, end]);
+            at = end;
+        }
+    }
+    return sequences;
+}

package/dist/run/evidence-files.d.ts

@@ -1,4 +1,3 @@
-import { type FileHandle } from "node:fs/promises";
 import { type PreparedOutputRoot } from "./contained-output.js";
 /**
  * Analysis inputs are retained local artifacts, never URLs or caller-selected outputs. The path is
@@ -23,12 +22,6 @@ export declare function readBoundedFile(root: PreparedOutputRoot, relativePath:
  * there that could not be read. Errors other than ENOENT propagate.
  */
 export declare function pathMissing(filePath: string): Promise<boolean>;
-/**
- * At most `maxBytes` from the start of an opened file, or null when it holds more. It reads by
- * position, in chunks of up to 64 KiB, and stops one byte past the limit, so a file that grew
- * after it was opened is never read whole.
- */
-export declare function readOpenedAtMost(handle: FileHandle, maxBytes: number): Promise<Buffer | null>;
 export type BoundedFileResult = {
     state: "read";
     bytes: Buffer;
@@ -38,5 +31,12 @@ export type BoundedFileResult = {
 } | {
     state: "unavailable";
 };
-/** Size refusals are distinguished only after the same contained regular-file checks. */
+/** readUnchangedFile for an analysis input, whose path must also be an evidence path. */
 export declare function readBoundedFileResult(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<BoundedFileResult>;
+/**
+ * At most `maxBytes` of a contained single-link regular file that stays the same file, with the
+ * same size and times, from the first check to the last. Size refusals are distinguished only after
+ * the same checks. `relativePath` uses `/`, and any name a contained read accepts
+ * (isSafeRelativeFilePath) is read: verify and export read the names they always did.
+ */
+export declare function readUnchangedFile(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<BoundedFileResult>;

package/dist/run/evidence-files.js

@@ -2,11 +2,12 @@ import { constants } from "node:fs";
 import { lstat, open, realpath } from "node:fs/promises";
 import path from "node:path";
 import { isPathInside, validatePreparedRunRootIdentity } from "./paths.js";
-import { assertPreparedSelectedOutputDirectory, } from "./contained-output.js";
+import { assertPreparedSelectedOutputDirectory, isSafeRelativeFilePath, readOpenedAtMost, } from "./contained-output.js";
 import { isNodeError } from "./type-guards.js";
 // Reading a file from a retained run directory for analysis: the path must be a plain relative path
 // inside the run, the file a single-link regular file that stays inside it, and the read bounded.
-// Evidence capture, analysis jobs, the analysis store, cost reading and export all read through here.
+// Evidence capture, analysis jobs, the analysis store, cost reading, verify and export all read
+// through here.
 /**
  * Analysis inputs are retained local artifacts, never URLs or caller-selected outputs. The path is
  * percent-decoded up to five times, and each round must still be a plain relative path, so an
@@ -87,29 +88,24 @@ export async function pathMissing(filePath) {
         throw error;
     }
 }
-/**
- * At most `maxBytes` from the start of an opened file, or null when it holds more. It reads by
- * position, in chunks of up to 64 KiB, and stops one byte past the limit, so a file that grew
- * after it was opened is never read whole.
- */
-export async function readOpenedAtMost(handle, maxBytes) {
-    const chunks = [];
-    let total = 0;
-    for (;;) {
-        const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes + 1 - total));
-        const { bytesRead } = await handle.read(chunk, 0, chunk.length, total);
-        if (bytesRead === 0)
-            return Buffer.concat(chunks, total);
-        total += bytesRead;
-        if (total > maxBytes)
-            return null;
-        chunks.push(chunk.subarray(0, bytesRead));
-    }
-}
 const unavailable = { state: "unavailable" };
-/** Size refusals are distinguished only after the same contained regular-file checks. */
+/** readUnchangedFile for an analysis input, whose path must also be an evidence path. */
 export async function readBoundedFileResult(root, relativePath, maxBytes) {
-    if (!isEvidencePath(relativePath) || !Number.isSafeInteger(maxBytes) || maxBytes < 1)
+    return isEvidencePath(relativePath)
+        ? readUnchangedFile(root, relativePath, maxBytes)
+        : unavailable;
+}
+/**
+ * At most `maxBytes` of a contained single-link regular file that stays the same file, with the
+ * same size and times, from the first check to the last. Size refusals are distinguished only after
+ * the same checks. `relativePath` uses `/`, and any name a contained read accepts
+ * (isSafeRelativeFilePath) is read: verify and export read the names they always did.
+ */
+export async function readUnchangedFile(root, relativePath, maxBytes) {
+    if (!isSafeRelativeFilePath(relativePath) ||
+        relativePath.includes("\\") ||
+        !Number.isSafeInteger(maxBytes) ||
+        maxBytes < 1)
         return unavailable;
     const validateRoot = async () => {
         if ("physicalRunRoot" in root) {

package/dist/run/locate.d.ts

@@ -1,14 +1,43 @@
 import { type PreparedRunArtifactPaths } from "./paths.js";
-import { type PreparedSelectedOutputDirectory } from "./contained-output.js";
+import { type ContainedRefusal, type PreparedSelectedOutputDirectory } from "./contained-output.js";
 import type { RunPointer } from "./results.js";
 import { type RunBundle } from "./bundle.js";
+import { type BoundedFileResult } from "./evidence-files.js";
 /** The run input that resolves through latest.json rather than naming a run directory. */
 export declare const LATEST_RUN_ALIAS = "latest";
 /** Resolve "latest" or an explicit run id to its prepared artifact paths. */
 export declare function resolveRunPath(cwd: string, runInput: string): Promise<PreparedRunArtifactPaths | null>;
 export declare function readLatest(runsRoot: PreparedSelectedOutputDirectory): Promise<RunPointer | null>;
-export declare function readRunJsonIfExists(runPaths: PreparedRunArtifactPaths, ...segments: string[]): Promise<unknown>;
-export declare function readRunTextIfExists(runPaths: PreparedRunArtifactPaths, ...segments: string[]): Promise<string | null>;
+/** A run file as text: its text, nothing at the path, or why it was refused. */
+export type RunTextRead = {
+    status: "read";
+    text: string;
+} | {
+    status: "missing";
+} | ContainedRefusal;
+/** A run file as JSON. `value` is undefined when the file is there but is not valid JSON. */
+export type RunJsonRead = {
+    status: "read";
+    value: unknown;
+} | {
+    status: "missing";
+} | ContainedRefusal;
+/**
+ * The JSON, or null for a file that is missing, refused or not valid JSON: for a caller that
+ * treats the three alike, as every reader did before a refusal had its own state.
+ */
+export declare function runJsonValue(read: RunJsonRead): unknown;
+/** A run file as JSON, within RUN_ARTIFACT_MAX_BYTES. */
+export declare function readRunJsonIfExists(runPaths: PreparedRunArtifactPaths, ...segments: string[]): Promise<RunJsonRead>;
+/** A run file as text, within RUN_ARTIFACT_MAX_BYTES. */
+export declare function readRunTextIfExists(runPaths: PreparedRunArtifactPaths, ...segments: string[]): Promise<RunTextRead>;
+/**
+ * A run file, read whole through readUnchangedFile: `limit` when it holds more than
+ * RUN_ARTIFACT_MAX_BYTES, `unavailable` when it is missing, unsafe, or changes while it is read.
+ * A `\` in the path reads as `/`.
+ */
+export declare function readSafeRunArtifact(runPaths: PreparedRunArtifactPaths, relativePath: string): Promise<BoundedFileResult>;
+/** readSafeRunArtifact's bytes, or null for any file it does not read. */
 export declare function readSafeRunArtifactBytes(runPaths: PreparedRunArtifactPaths, relativePath: string): Promise<Buffer | null>;
 export declare function readSafeRunArtifactJson(runPaths: PreparedRunArtifactPaths, relativePath: string): Promise<unknown>;
 export declare function loadRunBundle(cwdInput: string, runInput: string): Promise<{

package/dist/run/locate.js

@@ -1,10 +1,9 @@
-import { lstat } from "node:fs/promises";
 import path from "node:path";
-import { bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveExistingRunDirectory, resolveLatestRunDirectory, validatePreparedRunArtifactPaths, } from "./paths.js";
-import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, readContainedRegularFile, } from "./contained-output.js";
+import { bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveExistingRunDirectory, resolveLatestRunDirectory, RUNS_RELATIVE_ROOT, validatePreparedRunArtifactPaths, } from "./paths.js";
+import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, ContainedReadRefusedError, LATEST_POINTER_MAX_BYTES, readContainedRegularFile, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { isRunBundle, isRunPointer } from "./bundle-shape.js";
-import { isNodeError } from "./type-guards.js";
+import { readUnchangedFile } from "./evidence-files.js";
 /** The run input that resolves through latest.json rather than naming a run directory. */
 export const LATEST_RUN_ALIAS = "latest";
 /** Resolve "latest" or an explicit run id to its prepared artifact paths. */
@@ -33,59 +32,61 @@ export async function resolveRunPath(cwd, runInput) {
     return bindExistingRunArtifactPaths(cwd, runInput);
 }
 export async function readLatest(runsRoot) {
-    const latestPath = path.join(runsRoot.physicalPath, "latest.json");
-    let latestStats;
-    try {
-        latestStats = await lstat(latestPath, { bigint: true });
-    }
-    catch (error) {
-        if (isNodeError(error) && error.code === "ENOENT") {
-            return null;
-        }
-        throw error;
-    }
-    if (latestStats.isSymbolicLink() || !latestStats.isFile() || latestStats.nlink !== 1n) {
-        throw new Error("Latest run pointer must be a single-link regular file.");
-    }
-    const bytes = await readContainedRegularFile(runsRoot, "latest.json");
-    if (!bytes) {
-        throw new Error("Latest run pointer changed while it was being read.");
+    const read = await readContainedRegularFile(runsRoot, "latest.json", LATEST_POINTER_MAX_BYTES);
+    if (read.status === "missing")
+        return null;
+    if (read.status === "refused") {
+        if (read.reason === "too-large")
+            throw new ContainedReadRefusedError(path.join(RUNS_RELATIVE_ROOT, "latest.json"), read);
+        throw new Error(read.reason === "not-regular" || read.reason === "directory"
+            ? "Latest run pointer must be a single-link regular file."
+            : "Latest run pointer changed while it was being read.");
     }
     let latest;
     try {
-        latest = JSON.parse(bytes.toString("utf8"));
+        latest = JSON.parse(read.bytes.toString("utf8"));
     }
     catch {
         return null;
     }
     return isRunPointer(latest) ? latest : null;
 }
+/**
+ * The JSON, or null for a file that is missing, refused or not valid JSON: for a caller that
+ * treats the three alike, as every reader did before a refusal had its own state.
+ */
+export function runJsonValue(read) {
+    return read.status === "read" ? (read.value ?? null) : null;
+}
+/** A run file as JSON, within RUN_ARTIFACT_MAX_BYTES. */
 export async function readRunJsonIfExists(runPaths, ...segments) {
-    const text = await readRunTextIfExists(runPaths, ...segments);
-    if (text === null) {
-        return null;
-    }
+    const read = await readRunTextIfExists(runPaths, ...segments);
+    if (read.status !== "read")
+        return read;
     try {
-        return JSON.parse(text);
+        return { status: "read", value: JSON.parse(read.text) };
     }
     catch {
-        return null;
+        return { status: "read", value: undefined };
     }
 }
+/** A run file as text, within RUN_ARTIFACT_MAX_BYTES. */
 export async function readRunTextIfExists(runPaths, ...segments) {
-    const bytes = await readContainedRegularFile(runPaths, segments.join("/"));
-    return bytes?.toString("utf8") ?? null;
+    const read = await readContainedRegularFile(runPaths, segments.join("/"), RUN_ARTIFACT_MAX_BYTES);
+    return read.status === "read" ? { status: "read", text: read.bytes.toString("utf8") } : read;
 }
+/**
+ * A run file, read whole through readUnchangedFile: `limit` when it holds more than
+ * RUN_ARTIFACT_MAX_BYTES, `unavailable` when it is missing, unsafe, or changes while it is read.
+ * A `\` in the path reads as `/`.
+ */
+export async function readSafeRunArtifact(runPaths, relativePath) {
+    return readUnchangedFile(runPaths, relativePath.replace(/\\/g, "/"), RUN_ARTIFACT_MAX_BYTES);
+}
+/** readSafeRunArtifact's bytes, or null for any file it does not read. */
 export async function readSafeRunArtifactBytes(runPaths, relativePath) {
-    const normalized = relativePath.replace(/\\/g, "/");
-    const segments = normalized.split("/");
-    if (path.isAbsolute(relativePath) ||
-        path.win32.isAbsolute(relativePath) ||
-        segments.length === 0 ||
-        segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
-        return null;
-    }
-    return readContainedRegularFile(runPaths, normalized);
+    const read = await readSafeRunArtifact(runPaths, relativePath);
+    return read.state === "read" ? read.bytes : null;
 }
 export async function readSafeRunArtifactJson(runPaths, relativePath) {
     const bytes = await readSafeRunArtifactBytes(runPaths, relativePath);
@@ -112,7 +113,11 @@ export async function loadRunBundlePrepared(cwdInput, runPaths) {
     const cwd = path.resolve(cwdInput);
     await validatePreparedRunArtifactPaths(runPaths);
     const bundlePath = path.join(runPaths.absoluteRunRoot, RUN_BUNDLE_FILE);
-    const bundle = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
+    const read = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
+    // A run.json it refuses is no reason to call the run absent: the caller reports why.
+    if (read.status === "refused")
+        throw new ContainedReadRefusedError(RUN_BUNDLE_FILE, read);
+    const bundle = read.status === "read" ? read.value : null;
     if (!isRunBundle(bundle)) {
         return null;
     }