humanish 0.114.0 → 0.116.0

package/dist/routes/terminal/plan.js

@@ -8,7 +8,7 @@ import { actorRegistry, isTerminalActorDescriptor } from "../../actors/registry.
 import { isNonEmpty, planBase } from "../../study/plan-base.js";
 import { studyUrlCredentialReason } from "../../study/url-credentials.js";
 import { desktopMediaValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
-import { MAX_SANDBOX_MS } from "../../substrates/e2b/lifetime.js";
+import { ceilingAdvice } from "../../substrates/e2b/lifetime.js";
 import { NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
 import { terminalSandboxTimeoutMs } from "./lifetime.js";
 import { isExactRuntimeVersion, TERMINAL_RUNTIME_VERSION_TIMEOUT_MS } from "./runtime.js";
@@ -105,13 +105,16 @@ export function planTerminalStudy(config, input) {
     if (maxUsd > 0 && input.hasCostProbe !== true)
         return refuse("HUMANISH_TERMINAL_UNPRICED_CAP", `caps.maxUsd=${maxUsd} cannot be enforced: Codex reports no provider cost for the participant (its token cost is only estimated after the run) and no product, media or payment spend is measured, so a positive dollar cap can never trip. Set caps.maxUsd to 0 and bound the run with caps.maxMinutes, the codex command's wall-clock kill. No sandbox was created and the runtime key was not used.`, descriptor.id);
     // The sandbox's timeout covers the steps before the codex command, maxMinutes and the teardown
-    // buffer, and E2B refuses a sandbox over an hour. Refuse here, with the arithmetic, rather than
-    // after the plan prints, from a provider 400 that names neither knob.
+    // buffer, and E2B refuses a sandbox past the plan's ceiling. Refuse here, with the arithmetic,
+    // rather than after the plan prints, from a provider 400 that names neither knob.
+    const ceiling = input.sandboxCeiling;
+    if (!ceiling.ok)
+        return refuse("HUMANISH_TERMINAL_CAPS_INVALID", ceiling.message, descriptor.id);
     const productInstall = shared.product.install !== undefined;
     const sandboxTimeoutMs = terminalSandboxTimeoutMs({ maxMinutes, productInstall });
-    if (sandboxTimeoutMs > MAX_SANDBOX_MS) {
+    if (sandboxTimeoutMs > ceiling.ms) {
         const headroomMinutes = (sandboxTimeoutMs - maxMinutes * 60_000) / 60_000;
-        return refuse("HUMANISH_TERMINAL_CAPS_INVALID", `caps.maxMinutes ${maxMinutes} derives a ${sandboxTimeoutMs / 60_000}m sandbox deadline, and a sandbox may not live longer than ${MAX_SANDBOX_MS / 60_000}m. The deadline is maxMinutes plus ${headroomMinutes}m: the Node bootstrap (${NODE_BOOTSTRAP_TIMEOUT_MS / 60_000}m), the runtime version check (${TERMINAL_RUNTIME_VERSION_TIMEOUT_MS / 60_000}m)${productInstall ? `, the product setup (${PRODUCT_SETUP_TIMEOUT_MS / 60_000}m)` : ""} and the teardown buffer (${TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS / 60_000}m). Lower caps.maxMinutes to at most ${MAX_SANDBOX_MS / 60_000 - headroomMinutes}. No sandbox was created and the runtime key was not used.`, descriptor.id);
+        return refuse("HUMANISH_TERMINAL_CAPS_INVALID", `caps.maxMinutes ${maxMinutes} derives a ${sandboxTimeoutMs / 60_000}m sandbox deadline, and a sandbox may not live longer than ${ceiling.ms / 60_000}m. The deadline is maxMinutes plus ${headroomMinutes}m: the Node bootstrap (${NODE_BOOTSTRAP_TIMEOUT_MS / 60_000}m), the runtime version check (${TERMINAL_RUNTIME_VERSION_TIMEOUT_MS / 60_000}m)${productInstall ? `, the product setup (${PRODUCT_SETUP_TIMEOUT_MS / 60_000}m)` : ""} and the teardown buffer (${TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS / 60_000}m). Lower caps.maxMinutes to at most ${ceiling.ms / 60_000 - headroomMinutes}.${ceilingAdvice(sandboxTimeoutMs)} No sandbox was created and the runtime key was not used.`, descriptor.id);
     }
     return {
         ok: true,

package/dist/routes/terminal/token-usage.d.ts

@@ -13,6 +13,5 @@ export declare function terminalUsageRecords(lines: string): string[];
  */
 export declare function parseTerminalTokenUsage(transcript: string): ActorTokenUsage | undefined;
 /** Human-readable token statement for the cost ledger and the no-spend proof. Reports what was
- *  counted and says plainly that it is unpriced, so a reader never reads "no charge recorded" as
- *  "nothing was consumed". */
+ *  counted, so a reader never reads "no charge recorded" as "nothing was consumed". */
 export declare function describeTokenUsage(usage: ActorTokenUsage): string;

package/dist/routes/terminal/token-usage.js

@@ -9,10 +9,9 @@
 //   {"type":"turn.completed","usage":{"input_tokens":201536,"cached_input_tokens":170558,
 //    "cache_write_input_tokens":30951,"output_tokens":2283,"reasoning_output_tokens":902}}
 //
-// So the route can record a measured token fact even when it cannot record a priced one. Rates stay
-// out of this module deliberately: pricing lives in src/run/pricing.ts, and the terminal route has no
-// real model id to price against (it records `model: "codex"`), so the output is
-// tokens-known-rate-unknown rather than a guessed dollar figure.
+// So the route records a measured token fact whether or not a rate prices it. Rates stay out of this
+// module: the route prices these counts once, from the model it passed to Codex, with
+// src/run/pricing.ts (live-finish.ts), and the ledger and run.json both read that estimate.
 // Bounded to a single line on purpose. `[^}]*` would run past a truncated record's missing brace
 // and swallow the next, valid record's body, silently dropping a real turn from the count.
 const USAGE_RE = /"type"\s*:\s*"turn\.completed"\s*,\s*"usage"\s*:\s*(\{[^}\n]*\})/g;
@@ -81,8 +80,7 @@ export function parseTerminalTokenUsage(transcript) {
     };
 }
 /** Human-readable token statement for the cost ledger and the no-spend proof. Reports what was
- *  counted and says plainly that it is unpriced, so a reader never reads "no charge recorded" as
- *  "nothing was consumed". */
+ *  counted, so a reader never reads "no charge recorded" as "nothing was consumed". */
 export function describeTokenUsage(usage) {
     const parts = [];
     if (usage.input !== undefined)

package/dist/routes/terminal/types.d.ts

@@ -232,6 +232,11 @@ export interface InterventionRecord {
 export interface CostLine {
     /** known zero (0) | not measured (null). The key is always present when the line is applicable. */
     usd: number | null;
+    /** The provider line's price for its counted tokens, from the trace's `estimatedCost` (the
+     *  figure run.json's model-tokens line gives), when no charge was measured. An estimate from a
+     *  rate table: `usd` stays null, and neither `knownTotalUsd` nor caps.maxUsd counts it. Present
+     *  only with source `estimated-token-usage`. */
+    estimatedUsd?: number;
     /** Optional billable-unit count, same discipline: a known count, or null = not measured. */
     count?: number | null;
     /** How this line's value was established (provenance for the verifier + the human reviewer). */
@@ -239,7 +244,10 @@ export interface CostLine {
     /** Tokens were counted but no rate could price them, so `usd` stays null while the note
      *  carries the measured token totals. Distinct from "unmeasured", which means no
      *  signal at all. */
-     | "unpriced-token-usage";
+     | "unpriced-token-usage"
+    /** Tokens were counted and priced from a rate table: `estimatedUsd` holds the estimate and
+     *  `usd` stays null, since no charge was measured. */
+     | "estimated-token-usage";
     /** A short, public-safe note (never a secret value). */
     note: string;
 }

package/dist/run/bundle-shape.js

@@ -213,10 +213,15 @@ export const ARCHIVE_SHA256_PATTERN = /^[a-f0-9]{64}$/;
 function isRunSubjectProvenance(value) {
     if (!isRecord(value))
         return false;
-    if (value.source !== "clone" && value.source !== "app-url" && value.source !== "local-tree")
+    if (value.source !== "clone" &&
+        value.source !== "app-url" &&
+        value.source !== "local-tree" &&
+        value.source !== "desktop-cli")
         return false;
     if (value.repo !== undefined && typeof value.repo !== "string")
         return false;
+    if (value.product !== undefined && typeof value.product !== "string")
+        return false;
     if (value.commit !== undefined && typeof value.commit !== "string")
         return false;
     if (value.archiveSha256 !== undefined &&

package/dist/run/bundle.d.ts

@@ -158,9 +158,11 @@ export interface RunSubjectStateStepRecord {
  * pre-existing bundles).
  */
 export interface RunSubjectProvenance {
-    source: "clone" | "app-url" | "local-tree";
+    source: "clone" | "app-url" | "local-tree" | "desktop-cli";
     /** Clone-route only. Honors policies.redactRepos exactly as the provenance event does. */
     repo?: string;
+    /** Desktop-cli only: the product the study declares in `subject.product.name`. */
+    product?: string;
     /** Clone-route: the cloned commit SHA. Local-tree route: the host-side HEAD at pack time,
      *  when the packed root was a git work tree. */
     commit?: string;
@@ -184,8 +186,8 @@ export interface RunSubjectProvenance {
          *   an external DB is still unpinned overall).
          * declared-not-run: steps declared but not (all) executed ok: dry-run contract bundles
          *   and failed live provisioning.
-         * undeclared: no subject.state block (stateless apps, app-url subjects), the explicit
-         *   "absence declared" marker that provenance requires when there is none.
+         * undeclared: no subject.state block (stateless apps, app-url and desktop-cli subjects),
+         *   the explicit "absence declared" marker that provenance requires when there is none.
          * external-public: an operator-declared, operator-owned public deployment used
          *   directly as the shared plane; humanish neither provisioned nor seeded it (no getHost, no
          *   clone, no in-sandbox filesystem). It is not "seeded" (nothing was seeded) and not "unpinned" (this is

package/dist/run/contained-output.d.ts

@@ -39,19 +39,68 @@ export declare function prepareContainedOutputDirectoryRoot(rootInput: PreparedO
 export declare function prepareContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string): Promise<string>;
 export declare function writeContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string, data: string | Uint8Array, encoding?: BufferEncoding): Promise<void>;
 /**
- * Writes a new file inside the root without ever replacing one: the bytes go to a temporary file,
- * which link(2) then gives the final name, failing with EEXIST when that name exists, and the
- * temporary name is removed. writeContainedOutputFile renames instead, which replaces a file that
- * took the name in the meantime.
+ * Creates a new file inside the root under its final name, refusing with EEXIST when that name
+ * exists, so it never replaces a file. The file is opened with O_EXCL and O_NOFOLLOW, filled in one
+ * write and synced, so a reader may briefly see it empty or short. It never has a temporary name or
+ * a second link, so the run directory passes its single-link check at every moment.
+ * writeContainedOutputFile renames a finished file into place instead, replacing what is there.
  */
-export declare function writeNewContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string, data: string): Promise<void>;
-/** Read one regular file only when both lexical and physical paths stay in root. */
-export declare function readContainedRegularFile(rootInput: PreparedOutputRoot, relativePath: string): Promise<Buffer | null>;
+export declare function createContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string, data: string): Promise<void>;
 /**
- * Whether a contained path is confirmed absent. A present entry that readContainedRegularFile
- * refuses or fails to read is not absent.
+ * 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 declare function containedPathAbsent(rootInput: PreparedOutputRoot, relativePath: string): Promise<boolean>;
+export declare const RUN_ARTIFACT_MAX_BYTES: number;
+/** `.humanish/runs/latest.json`: a run id and a path. */
+export declare const LATEST_POINTER_MAX_BYTES: number;
+/** A file a person writes in the project: study, persona and scenario YAML, package.json, agent instructions. */
+export declare const PROJECT_FILE_MAX_BYTES: number;
+/**
+ * Why a contained read did not read a file that is there. `too-large`: it holds more than the
+ * limit. `changed`: it, its folder or the root changed while it was opened or read, which
+ * includes growing past the limit. `directory`: a folder is at the path. `not-regular`: a link, a
+ * hard link or a special file. `unsafe-path`: the path leaves the root or passes through a link.
+ * `unreadable`: the system refused the open or the read.
+ */
+export type ContainedRefusalReason = "too-large" | "changed" | "directory" | "not-regular" | "unsafe-path" | "unreadable";
+/** A file that is there and was not read: why, and the most the read would have taken. */
+export interface ContainedRefusal {
+    readonly status: "refused";
+    readonly reason: ContainedRefusalReason;
+    readonly limit: number;
+}
+/** What a contained read found: the bytes, nothing at the path, or a file it refused. */
+export type ContainedRead = {
+    readonly status: "read";
+    readonly bytes: Buffer;
+} | {
+    readonly status: "missing";
+} | ContainedRefusal;
+/** `relativePath` and why it was refused, as a clause: "x.yaml is larger than 4194304 bytes, ...". */
+export declare function refusalText(relativePath: string, refusal: ContainedRefusal): string;
+/** A refused contained read, for a caller that stops on one. The message names the file. */
+export declare class ContainedReadRefusedError extends Error {
+    readonly relativePath: string;
+    readonly refusal: ContainedRefusal;
+    constructor(relativePath: string, refusal: ContainedRefusal);
+}
+/**
+ * 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 declare function readContainedRegularFile(rootInput: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<ContainedRead>;
+/**
+ * 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>;
 /** The caller owns this checked descriptor and must close it after reading/streaming. */
 export declare function openContainedRegularFile(rootInput: PreparedOutputRoot, relativePath: string): Promise<FileHandle | null>;
 export declare function assertSafeOutputPathSegment(value: string, label?: string): void;
+/** A non-empty relative path with no empty, `.` or `..` segment: the names a contained read accepts. */
+export declare function isSafeRelativeFilePath(value: string): boolean;

package/dist/run/contained-output.js

@@ -1,5 +1,5 @@
 import { constants } from "node:fs";
-import { link, lstat, mkdir, open, realpath, rename, unlink, } from "node:fs/promises";
+import { lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { assertDirectoryIdentity, assertRegularFileOrMissing, isPathInside, prepareHumanishStorageDirectory, resolveExistingHumanishStorageDirectory, validatePreparedRunArtifactPaths, validatePreparedRunRootIdentity, } from "./paths.js";
@@ -124,106 +124,188 @@ export async function writeContainedOutputFile(rootInput, relativePath, data, en
     });
 }
 /**
- * Writes a new file inside the root without ever replacing one: the bytes go to a temporary file,
- * which link(2) then gives the final name, failing with EEXIST when that name exists, and the
- * temporary name is removed. writeContainedOutputFile renames instead, which replaces a file that
- * took the name in the meantime.
+ * Creates a new file inside the root under its final name, refusing with EEXIST when that name
+ * exists, so it never replaces a file. The file is opened with O_EXCL and O_NOFOLLOW, filled in one
+ * write and synced, so a reader may briefly see it empty or short. It never has a temporary name or
+ * a second link, so the run directory passes its single-link check at every moment.
+ * writeContainedOutputFile renames a finished file into place instead, replacing what is there.
  */
-export async function writeNewContainedOutputFile(rootInput, relativePath, data) {
+export async function createContainedOutputFile(rootInput, relativePath, data) {
     const filePath = await prepareContainedOutputFile(rootInput, relativePath);
     const root = await resolveOutputRoot(rootInput);
-    const parent = path.dirname(filePath);
-    const revalidate = async () => {
-        if ((await resolveOutputRoot(rootInput)) !== root) {
-            throw new Error("Output root changed after it was prepared.");
-        }
-        await assertContainedDirectoryChain(root, parent);
-    };
-    await revalidate();
-    const temporary = path.join(parent, `.humanish-write-${process.pid}-${randomUUID()}.tmp`);
-    let handle;
+    await assertContainedDirectoryChain(root, path.dirname(filePath));
+    const bytes = Buffer.from(data, "utf8");
+    const handle = await open(filePath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
     try {
-        handle = await open(temporary, "wx", 0o600);
-        await handle.writeFile(data, "utf8");
+        const { bytesWritten } = await handle.write(bytes, 0, bytes.length, 0);
+        if (bytesWritten !== bytes.length)
+            throw new Error("The file was not written in full.");
         await handle.sync();
-        await handle.close();
-        handle = undefined;
-        await revalidate();
-        await link(temporary, filePath);
     }
-    finally {
-        await handle?.close().catch(() => undefined);
-        await unlink(temporary).catch(() => undefined);
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        // O_EXCL created this name here, so removing it removes only this file.
+        await unlink(filePath).catch(() => undefined);
+        throw error;
     }
-    await assertRegularFileOrMissing(filePath, "Selected output files");
+    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") {
@@ -236,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][];