humanish 0.115.0 → 0.116.0

package/dist/run/reclaim.js

@@ -8,10 +8,11 @@
 // reclaim-receipt.json is written before the first kill and after each one, so an exit at any
 // point leaves a record of every sandbox not yet confirmed gone. `--check` asks E2B the same
 // questions and kills nothing.
+import { e2bAccount, e2bConnection } from "../substrates/e2b/connection.js";
 import { E2B_DEBUG_ENV, e2bDebugMode, loadE2BDesktopModule, } from "../substrates/e2b/sdk.js";
-import { containedPathAbsent, readContainedRegularFile, } from "./contained-output.js";
+import { readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
 import { discardPreflightJournal, listPreflightJournals, preflightReclaimDecision, } from "./preflight-receipts.js";
-import { readRunJsonIfExists, resolveRunPath } from "./locate.js";
+import { readRunJsonIfExists, resolveRunPath, runJsonValue } from "./locate.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { RUN_STATUS_FILE } from "./status.js";
 import { isRecord } from "./type-guards.js";
@@ -80,7 +81,7 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
         return {
             ...base,
             runId,
-            error: { code: "HUMANISH_RECLAIM_RECEIPTS_UNREADABLE", message: UNREADABLE_MESSAGE },
+            error: { code: "HUMANISH_RECLAIM_RECEIPTS_UNREADABLE", message: reclaimed.message },
         };
     const { state, receiptCount, outcomes, tagSearch, createsInFlight } = reclaimed;
     return {
@@ -105,8 +106,14 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
  * whatever its records say.
  */
 async function recordedNoSandbox(runPaths) {
-    const bundle = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
-    const status = await readRunJsonIfExists(runPaths, RUN_STATUS_FILE);
+    const bundleRead = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
+    const statusRead = await readRunJsonIfExists(runPaths, RUN_STATUS_FILE);
+    // A record that is there and refused could say anything, so neither shortcut applies and
+    // reclaim runs in full. A missing one says nothing, as before.
+    if (bundleRead.status === "refused" || statusRead.status === "refused")
+        return undefined;
+    const bundle = runJsonValue(bundleRead);
+    const status = runJsonValue(statusRead);
     const records = [bundle, status].filter(isRecord);
     const reason = records.length > 0 && records.every((record) => record.mode === "dry-run")
         ? "dry-run"
@@ -118,15 +125,18 @@ async function recordedNoSandbox(runPaths) {
             : undefined;
     if (reason === undefined)
         return undefined;
-    if (!(await containedPathAbsent(runPaths, RECLAIM_RECEIPT_ARTIFACT))) {
-        const earlier = await readRunJsonIfExists(runPaths, RECLAIM_RECEIPT_ARTIFACT);
+    const earlierRead = await readRunJsonIfExists(runPaths, RECLAIM_RECEIPT_ARTIFACT);
+    if (earlierRead.status !== "missing") {
+        const earlier = runJsonValue(earlierRead);
         if (!isRecord(earlier) || !Array.isArray(earlier.outcomes) || earlier.outcomes.length > 0)
             return undefined;
     }
-    if (await containedPathAbsent(runPaths, SANDBOX_RECEIPTS_ARTIFACT))
+    const journal = await readContainedRegularFile(runPaths, SANDBOX_RECEIPTS_ARTIFACT, RUN_ARTIFACT_MAX_BYTES);
+    if (journal.status === "missing")
         return reason;
-    const journal = await readContainedRegularFile(runPaths, SANDBOX_RECEIPTS_ARTIFACT);
-    return journal !== null && journal.toString("utf8").trim() === "" ? reason : undefined;
+    return journal.status === "read" && journal.bytes.toString("utf8").trim() === ""
+        ? reason
+        : undefined;
 }
 /** The execution failure kinds that leave a sandbox or a provider's resources unconfirmed. */
 const CLEANUP_KINDS = new Set(["sandbox-cleanup", "provider-cleanup"]);
@@ -190,7 +200,7 @@ export async function reclaimPreflightSandboxes(cwd, hooks = {}) {
         const reclaimed = await reclaimRoot(journal.root, journal.id, hooks, warnings);
         if (reclaimed.kind === "unreadable") {
             // The receipt may name a live sandbox; the journal stays for a later reclaim.
-            warnings.push(`Preflight ${journal.id} left alone: ${UNREADABLE_MESSAGE}`);
+            warnings.push(`Preflight ${journal.id} left alone: ${reclaimed.message}`);
             states.push("unknown");
             continue;
         }
@@ -241,15 +251,28 @@ const E2B_DEBUG_REFUSAL = {
     message: `${E2B_DEBUG_ENV}=true puts the E2B SDK in debug mode, where Sandbox.kill reports success without contacting E2B. Nothing was killed and the receipts were kept; unset ${E2B_DEBUG_ENV} and run reclaim again.`,
 };
 const UNREADABLE_MESSAGE = "sandbox-receipts.ndjson is present but could not be read safely (not a single regular file, or a read error). Nothing was killed and the receipts were kept; check the file, then run reclaim again.";
+/**
+ * Why reclaim stopped before it killed or wrote anything: the receipts journal, or the receipt an
+ * earlier reclaim wrote, is there and cannot be read.
+ */
+function unreadableMessage(file, refusal) {
+    if (file === SANDBOX_RECEIPTS_ARTIFACT && refusal.reason !== "too-large")
+        return UNREADABLE_MESSAGE;
+    const kept = file === SANDBOX_RECEIPTS_ARTIFACT ? "the receipts were kept" : "the receipt was kept";
+    return `${refusalText(file, refusal)}. Nothing was killed and ${kept}; check the file, then run reclaim again.`;
+}
 /**
  * Find and stop (or, for `--check`, look up) every sandbox one directory owns: its receipts, the
  * creates this process reported, and E2B's tagged list, each once by exact id.
  */
 async function reclaimRoot(root, label, hooks, warnings) {
-    const bytes = await readContainedRegularFile(root, SANDBOX_RECEIPTS_ARTIFACT);
-    if (bytes === null && !(await containedPathAbsent(root, SANDBOX_RECEIPTS_ARTIFACT)))
-        return { kind: "unreadable" };
-    const journal = bytes === null ? "" : bytes.toString("utf8");
+    const journalRead = await readContainedRegularFile(root, SANDBOX_RECEIPTS_ARTIFACT, RUN_ARTIFACT_MAX_BYTES);
+    if (journalRead.status === "refused")
+        return {
+            kind: "unreadable",
+            message: unreadableMessage(SANDBOX_RECEIPTS_ARTIFACT, journalRead),
+        };
+    const journal = journalRead.status === "read" ? journalRead.bytes.toString("utf8") : "";
     const receipts = parseSandboxReceipts(journal);
     const owners = parseSandboxOwners(journal, label);
     const check = hooks.check === true;
@@ -259,7 +282,8 @@ async function reclaimRoot(root, label, hooks, warnings) {
     let e2b;
     let moduleError;
     try {
-        e2b = await (hooks.loadModule ?? loadE2BDesktopModule)();
+        const module = await (hooks.loadModule ?? loadE2BDesktopModule)();
+        e2b = e2bAccount(module, e2bConnection(hooks.env ?? process.env));
     }
     catch (error) {
         moduleError = `Cannot load @e2b/desktop to reach E2B: ${redactText(toErrorMessage(error))}`;
@@ -269,6 +293,9 @@ async function reclaimRoot(root, label, hooks, warnings) {
     // An earlier reclaim may have killed a sandbox no receipt names (the signal handler's creates
     // and tag finds). Its outcome is carried forward, so a later reclaim never erases that record.
     const earlier = check ? [] : await earlierOutcomes(root, label);
+    // The new receipt replaces the old one, so an old one that cannot be read stops reclaim here.
+    if (!Array.isArray(earlier))
+        return { kind: "unreadable", message: unreadableMessage(RECLAIM_RECEIPT_ARTIFACT, earlier) };
     const set = targetSet({
         e2b,
         check,

package/dist/run/run-clock.d.ts

@@ -0,0 +1,50 @@
+import type { ActorTraceItem } from "../actors/contract.js";
+import type { RunDesktopRecording } from "../evidence/desktop-recording-types.js";
+/** What the clock reads from a stream. A run.json stream and an Observer stream both have it. */
+export interface ClockStream {
+    actor?: {
+        items: readonly ActorTraceItem[];
+    };
+    liveActor?: {
+        items: readonly ActorTraceItem[];
+    };
+    recording?: RunDesktopRecording;
+}
+/** Where the run clock starts and ends, in epoch ms. */
+export interface RunClock {
+    startMs: number;
+    endMs: number;
+    /** Every moment on the clock, ascending without repeats, for keyboard seeking. */
+    boundariesMs: number[];
+}
+/** A desktop video's place on the run clock, in epoch ms. */
+export interface RecordingInterval {
+    startMs: number;
+    endMs: number;
+    recording: RunDesktopRecording;
+}
+/**
+ * A stream's recorded trace items: the finished actor's, else the flush of a participant still
+ * running, so every reader of a live run sees the items grow.
+ */
+export declare function traceItems(stream: ClockStream): readonly ActorTraceItem[];
+/**
+ * Whether a trace item is a capture, a frame of the participant's replay: a screenshot, or a
+ * scripted action that carries its own screenshot. A notice can cite an earlier screenshot for
+ * context, and does not capture it again.
+ */
+export declare function isCapture<Item extends Pick<ActorTraceItem, "kind" | "screenshotRef">>(item: Item): item is Item & {
+    screenshotRef: NonNullable<ActorTraceItem["screenshotRef"]>;
+};
+/**
+ * A participant's capture times in epoch ms, in recorded order. Null when a capture has no stamp
+ * or a stamp goes back: such a participant adds nothing to the run clock, and its replay runs at
+ * an average pace. Times are never made up from the actor's duration.
+ */
+export declare function captureTimes(stamps: readonly (number | undefined)[]): number[] | null;
+/** Where a desktop video sits on the run clock; null without a readable start and a length. */
+export declare function recordingInterval(recording: RunDesktopRecording | undefined): RecordingInterval | null;
+/** The run clock of every stream of a run, or null when none has a timed capture or a video. */
+export declare function runClock(streams: readonly ClockStream[]): RunClock | null;
+/** A run clock time or span in whole minutes and seconds: `02:31`. Minutes go past 59. */
+export declare function formatRunTime(ms: number): string;

package/dist/run/run-clock.js

@@ -0,0 +1,66 @@
+// The run clock: the Observer's study timeline, and the clock a reviewer note's time counts from.
+// It runs from the first to the last moment any participant recorded: a timed capture, or the start
+// or end of a desktop video. The Observer bundles this module, so it imports types only
+// (docs/decisions/0002-observer-is-one-self-contained-file.md).
+/**
+ * A stream's recorded trace items: the finished actor's, else the flush of a participant still
+ * running, so every reader of a live run sees the items grow.
+ */
+export function traceItems(stream) {
+    return stream.actor?.items ?? stream.liveActor?.items ?? [];
+}
+/**
+ * Whether a trace item is a capture, a frame of the participant's replay: a screenshot, or a
+ * scripted action that carries its own screenshot. A notice can cite an earlier screenshot for
+ * context, and does not capture it again.
+ */
+export function isCapture(item) {
+    return (item.kind === "screenshot" || item.kind === "ui_action") && Boolean(item.screenshotRef);
+}
+/**
+ * A participant's capture times in epoch ms, in recorded order. Null when a capture has no stamp
+ * or a stamp goes back: such a participant adds nothing to the run clock, and its replay runs at
+ * an average pace. Times are never made up from the actor's duration.
+ */
+export function captureTimes(stamps) {
+    const times = [];
+    for (const time of stamps) {
+        if (time === undefined || !Number.isFinite(time) || time < (times.at(-1) ?? -Infinity))
+            return null;
+        times.push(time);
+    }
+    return times;
+}
+/** Where a desktop video sits on the run clock; null without a readable start and a length. */
+export function recordingInterval(recording) {
+    if (!recording)
+        return null;
+    const startMs = Date.parse(recording.startedAt);
+    const endMs = startMs + recording.durationMs;
+    if (!Number.isFinite(startMs) || !Number.isFinite(endMs) || recording.durationMs <= 0)
+        return null;
+    return { startMs, endMs, recording };
+}
+/** The run clock of every stream of a run, or null when none has a timed capture or a video. */
+export function runClock(streams) {
+    const moments = new Set();
+    for (const stream of streams) {
+        const stamps = traceItems(stream)
+            .filter(isCapture)
+            .map((item) => (item.at === undefined ? Number.NaN : Date.parse(item.at)));
+        for (const time of captureTimes(stamps) ?? [])
+            moments.add(time);
+        const video = recordingInterval(stream.recording);
+        if (video)
+            moments.add(video.startMs).add(video.endMs);
+    }
+    const boundariesMs = [...moments].sort((a, b) => a - b);
+    if (boundariesMs.length === 0)
+        return null;
+    return { startMs: boundariesMs[0], endMs: boundariesMs.at(-1), boundariesMs };
+}
+/** A run clock time or span in whole minutes and seconds: `02:31`. Minutes go past 59. */
+export function formatRunTime(ms) {
+    const seconds = Math.max(0, Math.floor(ms / 1000));
+    return `${String(Math.floor(seconds / 60)).padStart(2, "0")}:${String(seconds % 60).padStart(2, "0")}`;
+}

package/dist/run/run.js

@@ -15,7 +15,7 @@ import { writeContainedOutputFile, writePreparedRunLatestPointer } from "./conta
 import { scrubRunSandboxIds, withPublicSandboxIds } from "./sandbox-ids.js";
 import { RunSecrets } from "./secrets.js";
 import { RUN_STATUS_FILE, beginRunStatus, runStatusOutcome, } from "./status.js";
-import { readRunJsonIfExists } from "./locate.js";
+import { readRunJsonIfExists, runJsonValue } from "./locate.js";
 /** An entry point called in a state that does not admit it. */
 class RunLifecycleError extends Error {
     name = "RunLifecycleError";
@@ -166,7 +166,10 @@ function runPublisher(args) {
         });
         await writeContainedOutputFile(paths, RUN_BUNDLE_FILE, json(publicBundle), "utf8");
         await afterBundle(publicBundle);
-        const status = recorded === undefined ? await readRunJsonIfExists(paths, RUN_STATUS_FILE) : undefined;
+        // The run writes its own status.json; one it refuses renders as a missing one does.
+        const status = recorded === undefined
+            ? runJsonValue(await readRunJsonIfExists(paths, RUN_STATUS_FILE))
+            : undefined;
         await writeContainedOutputFile(paths, "review.json", json(publicBundle.review), "utf8");
         await writeContainedOutputFile(paths, "review.md", options.renderReview(publicBundle, status), "utf8");
         const events = publicBundle.events.map((event) => JSON.stringify(event)).join("\n");

package/dist/run/sandbox-ids.d.ts

@@ -24,7 +24,10 @@ export declare function inventorySandboxIds(files: readonly {
 export declare function holdsKeyedSandboxId(file: string, text: string): boolean;
 /**
  * The raw sandbox ids a run's receipts journal, with any this process receipted whose append
- * failed; empty when there are none or the journal cannot be read.
+ * failed; none from the journal when it is missing or malformed, or when a folder is where it goes
+ * (a failed append can leave one, and the process still holds those ids). A journal refused for
+ * any other reason, a link or one too large to read say, throws ContainedReadRefusedError: every
+ * caller would otherwise write or grade a run's files without the ids it may hold.
  */
 export declare function readRunSandboxIds(root: PreparedOutputRoot): Promise<string[]>;
 /**
@@ -41,7 +44,9 @@ export declare function scrubSandboxIdBytes(file: string, bytes: Buffer, ids: re
  * Rewrite each file of a finished run that names one of its raw sandbox ids, apart from the
  * receipts, with the label in place of the id. Writers such as a participant's actor.json can
  * quote an SDK error that names the sandbox. Run.finish calls it before analysis reads the run.
- * Best effort: verify grades a file this misses.
+ * Best effort for writes and listings: verify grades a file this misses. A text file it refuses
+ * to read, or a journal it refuses, throws once the sweep ends, naming each, since such a file
+ * may still hold an id.
  */
 export declare function scrubRunSandboxIds(paths: PreparedRunArtifactPaths): Promise<void>;
 /**

package/dist/run/sandbox-ids.js

@@ -6,7 +6,7 @@ import { opendir, realpath } from "node:fs/promises";
 import path from "node:path";
 import { readPlainText } from "../evidence/plain-text.js";
 import { collectSandboxIds, redactSandboxIds, sandboxIdDigest, REDACTED_SANDBOX_ID, } from "../evidence/redaction.js";
-import { readContainedRegularFile, writeContainedOutputFile, } from "./contained-output.js";
+import { ContainedReadRefusedError, readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, writeContainedOutputFile, } from "./contained-output.js";
 import { bindExistingRunArtifactPaths, isSafeRunIdSegment, validatePreparedRunRootIdentity, } from "./paths.js";
 import { appendedSandboxIds, parseSandboxReceipts, SANDBOX_RECEIPTS_ARTIFACT, } from "./sandbox-receipts.js";
 /** How text names a sandbox: the marker with the id's digest. */
@@ -96,14 +96,19 @@ export function holdsKeyedSandboxId(file, text) {
 }
 /**
  * The raw sandbox ids a run's receipts journal, with any this process receipted whose append
- * failed; empty when there are none or the journal cannot be read.
+ * failed; none from the journal when it is missing or malformed, or when a folder is where it goes
+ * (a failed append can leave one, and the process still holds those ids). A journal refused for
+ * any other reason, a link or one too large to read say, throws ContainedReadRefusedError: every
+ * caller would otherwise write or grade a run's files without the ids it may hold.
  */
 export async function readRunSandboxIds(root) {
+    const read = await readContainedRegularFile(root, SANDBOX_RECEIPTS_ARTIFACT, RUN_ARTIFACT_MAX_BYTES);
+    if (read.status === "refused" && read.reason !== "directory")
+        throw new ContainedReadRefusedError(SANDBOX_RECEIPTS_ARTIFACT, read);
     let journaled = [];
     try {
-        const bytes = await readContainedRegularFile(root, SANDBOX_RECEIPTS_ARTIFACT);
-        if (bytes)
-            journaled = receiptSandboxIds(bytes);
+        if (read.status === "read")
+            journaled = receiptSandboxIds(read.bytes);
     }
     catch {
         // The ids this process receipted still apply.
@@ -138,7 +143,9 @@ const MAX_SWEPT_ENTRIES = 10_000;
  * Rewrite each file of a finished run that names one of its raw sandbox ids, apart from the
  * receipts, with the label in place of the id. Writers such as a participant's actor.json can
  * quote an SDK error that names the sandbox. Run.finish calls it before analysis reads the run.
- * Best effort: verify grades a file this misses.
+ * Best effort for writes and listings: verify grades a file this misses. A text file it refuses
+ * to read, or a journal it refuses, throws once the sweep ends, naming each, since such a file
+ * may still hold an id.
  */
 export async function scrubRunSandboxIds(paths) {
     const ids = await readRunSandboxIds(paths);
@@ -147,12 +154,15 @@ export async function scrubRunSandboxIds(paths) {
     const valid = await validatePreparedRunRootIdentity(paths).then(() => true, () => false);
     if (!valid)
         return;
+    const refused = [];
     const scrub = async (file) => {
-        const bytes = await readContainedRegularFile(paths, file);
-        if (bytes === null)
+        const read = await readContainedRegularFile(paths, file, RUN_ARTIFACT_MAX_BYTES);
+        if (read.status === "refused")
+            refused.push(refusalText(file, read));
+        if (read.status !== "read")
             return;
-        const scrubbed = scrubSandboxIdBytes(file, bytes, ids);
-        if (scrubbed !== bytes)
+        const scrubbed = scrubSandboxIdBytes(file, read.bytes, ids);
+        if (scrubbed !== read.bytes)
             await writeContainedOutputFile(paths, file, scrubbed);
     };
     let seen = 0;
@@ -179,6 +189,8 @@ export async function scrubRunSandboxIds(paths) {
     await walk("").catch(() => {
         // A directory that changed while it was listed ends the sweep; verify names what it missed.
     });
+    if (refused.length > 0)
+        throw new Error(`The sandbox id sweep could not read every run file, so these may still name a sandbox: ${refused.join("; ")}.`);
 }
 /**
  * A run's result as it may be returned or printed: the same object when it names no sandbox,
@@ -187,12 +199,16 @@ export async function scrubRunSandboxIds(paths) {
 export async function publicRunResult(result, cwd) {
     let ids = [];
     if (typeof result.runId === "string" && isSafeRunIdSegment(result.runId)) {
+        let paths;
         try {
-            ids = await readRunSandboxIds(await bindExistingRunArtifactPaths(cwd, result.runId));
+            paths = await bindExistingRunArtifactPaths(cwd, result.runId);
         }
         catch {
             // A run that never created its directory has no receipts; the keys are still redacted.
         }
+        // A journal that is there and refused throws: the result cannot be printed without its ids.
+        if (paths !== undefined)
+            ids = await readRunSandboxIds(paths);
     }
     return publicSandboxView(result, ids);
 }

package/dist/run/secrets.d.ts

@@ -11,7 +11,8 @@ export declare class RunSecrets {
      * Replaces every held value with the marker, as written, in each encoded form, and where a URL
      * carries it partly percent-encoded or a terminal escape sequence splits it. It reads the values
      * on each call, so a value added after the scrub was handed to a participant or a subject is
-     * scrubbed from then on.
+     * scrubbed from then on. If the result still holds a value in any readingsOf, as when a marker
+     * written before `x` spells the value `SECRET]x`, the whole text becomes the marker.
      */
     readonly scrub: (text: string) => string;
     /** `seed` keeps its order; values shorter than the floor are dropped. */

package/dist/run/secrets.js

@@ -4,7 +4,8 @@
 // replaced as written and in the encoded forms a URL, a JSON body or a log line gives it;
 // redactText runs after the scrub and finds secrets by shape.
 import { scrubLiterals } from "../evidence/redaction.js";
-import { encodedForms } from "../evidence/secret-scrub.js";
+import { encodedForms, holdsSecretValue } from "../evidence/secret-scrub.js";
+import { escapeSequences } from "./escape-sequences.js";
 export class RunSecrets {
     // Private fields stay out of JSON.stringify and object spread, so a Run that reaches a writer
     // whole cannot carry the values with it.
@@ -12,11 +13,14 @@ export class RunSecrets {
     /** Every held value as written and encoded, longest first. */
     #forms = [];
     #minLength;
+    /** holdsSecretValue of the held values, built at its first use after `add` holds a new one. */
+    #holds;
     /**
      * Replaces every held value with the marker, as written, in each encoded form, and where a URL
      * carries it partly percent-encoded or a terminal escape sequence splits it. It reads the values
      * on each call, so a value added after the scrub was handed to a participant or a subject is
-     * scrubbed from then on.
+     * scrubbed from then on. If the result still holds a value in any readingsOf, as when a marker
+     * written before `x` spells the value `SECRET]x`, the whole text becomes the marker.
      */
     scrub;
     /** `seed` keeps its order; values shorter than the floor are dropped. */
@@ -30,7 +34,9 @@ export class RunSecrets {
         const literal = scrubLiterals(this.#forms, marker);
         this.scrub = (text) => {
             const scrubbed = literal(text);
-            return replaceSpans(scrubbed, viewSpans(scrubbed, this.#forms), marker);
+            const result = replaceSpans(scrubbed, viewSpans(scrubbed, this.#forms), marker);
+            this.#holds ??= holdsSecretValue(this.#held);
+            return this.#holds(result) ? marker : result;
         };
     }
     /** Holds each value the run learns while it runs, unless it is under the floor or already held. */
@@ -39,6 +45,7 @@ export class RunSecrets {
             if (value.length < this.#minLength || this.#held.includes(value))
                 continue;
             this.#held.push(value);
+            this.#holds = undefined;
             for (const form of encodedForms(value))
                 if (!this.#forms.includes(form))
                     this.#forms.push(form);
@@ -69,20 +76,9 @@ export class RunSecrets {
         return mergeSpans(found);
     }
 }
-// What a terminal draws with (operating-system commands, control sequences and two-byte escapes,
-// as written or JSON-escaped, as a JSON event carries a command's colored output) and what a URL
-// encodes with (runs of percent escapes). The view a value is looked for in drops the first and
-// decodes the second.
-const VIEW_SEQUENCE = new RegExp([
-    "\\x1b\\][^\\x07]*(?:\\x07|\\x1b\\\\)",
-    "\\x1b\\[[0-?]*[ -/]*[@-~]",
-    "\\x1b[78=>]",
-    "\\\\u001b\\][^\\\\]*(?:\\\\u0007|\\\\u001b\\\\\\\\)",
-    "\\\\u001b\\[[0-?]*[ -/]*[@-~]",
-    "(?:%[0-9A-Fa-f]{2})+",
-].join("|"), "g");
 /**
- * Where a value is found in the text's view. A browser encodes a space or a quote in a URL path
+ * Where a value is found in the text's view, which drops terminal escape sequences and decodes
+ * percent escapes (escapeSequences). A browser encodes a space or a quote in a URL path
  * and leaves a `/` or a `:` as written, so a value with both matches no single encoded form, and a
  * color code inside a value splits it. Each found value maps back to the span of `text` it came
  * from, so the text keeps every other character as written.
@@ -104,21 +100,21 @@ function viewSpans(text, values) {
     };
     let cursor = 0;
     let changed = false;
-    for (const sequence of text.matchAll(VIEW_SEQUENCE)) {
+    for (const [start, end] of escapeSequences(text)) {
         let plain = "";
-        if (sequence[0].startsWith("%")) {
+        if (text[start] === "%") {
             try {
-                plain = decodeURIComponent(sequence[0]);
+                plain = decodeURIComponent(text.slice(start, end));
             }
             catch {
                 // Not UTF-8: the run stays as written and is copied with the text after it.
                 continue;
             }
         }
-        copy(cursor, sequence.index);
-        cursor = sequence.index + sequence[0].length;
+        copy(cursor, start);
+        cursor = end;
         for (let unit = 0; unit < plain.length; unit += 1) {
-            starts.push(sequence.index);
+            starts.push(start);
             ends.push(cursor);
         }
         view += plain;

package/dist/run/stored-runs.js

@@ -2,12 +2,12 @@ import { lstat, readdir } from "node:fs/promises";
 import path from "node:path";
 import { redactText } from "../evidence/redaction.js";
 import { bindExistingRunArtifactPaths, RUNS_RELATIVE_ROOT, isSafeRunIdSegment, resolveRunsRoot, } from "./paths.js";
-import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, } from "./contained-output.js";
+import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, refusalText, } from "./contained-output.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { isReviewSummary, isRunOutcome } from "./bundle-shape.js";
 import { bundleDisplayFacts, displayedReview, runDisplay, } from "./display.js";
 import { RUN_STATUS_FILE } from "./status.js";
-import { readLatest, readRunJsonIfExists, resolveRunPath } from "./locate.js";
+import { readLatest, readRunJsonIfExists, resolveRunPath, runJsonValue } from "./locate.js";
 import { withCuaReviewProvenance } from "./outcomes.js";
 import { isNodeError, isRecord } from "./type-guards.js";
 import { invalidRunStorageVerifyResult, verifyResolvedRun, } from "../verify/verify.js";
@@ -70,7 +70,8 @@ export async function listRuns(cwdInput) {
         if (runsRoot && entryRunPaths.physicalRunsRoot !== runsRoot.physicalPath) {
             return runsUnavailableResult(cwd, new Error("humanish runs root changed physical destination."));
         }
-        const bundle = await readRunJsonIfExists(entryRunPaths, RUN_BUNDLE_FILE);
+        // A listing shows what it can read: a run.json it refuses lists like a missing one.
+        const bundle = runJsonValue(await readRunJsonIfExists(entryRunPaths, RUN_BUNDLE_FILE));
         runs.push({
             runId: entryName,
             createdAt: isRecord(bundle) && typeof bundle.createdAt === "string" ? bundle.createdAt : null,
@@ -105,7 +106,7 @@ async function listedRunDisplay(runPaths, bundle) {
     if (displayed === undefined)
         return {};
     const status = displayed.outcome === undefined
-        ? await readRunJsonIfExists(runPaths, RUN_STATUS_FILE)
+        ? runJsonValue(await readRunJsonIfExists(runPaths, RUN_STATUS_FILE))
         : undefined;
     return { display: runDisplay(bundleDisplayFacts(displayed, status)) };
 }
@@ -155,18 +156,24 @@ export async function readReview(cwdInput, runInput) {
     if (!verified.ok || !verified.bundlePath) {
         return verified;
     }
-    const review = runPaths ? await readRunJsonIfExists(runPaths, "review.json") : null;
+    const reviewRead = runPaths ? await readRunJsonIfExists(runPaths, "review.json") : undefined;
+    const review = reviewRead === undefined ? null : runJsonValue(reviewRead);
     if (!isReviewSummary(review)) {
         return {
             ...verified,
             ok: false,
             error: {
                 code: "HUMANISH_INVALID_RUN_BUNDLE",
-                message: "review.json is missing or invalid.",
+                message: reviewRead?.status === "refused"
+                    ? `${refusalText("review.json", reviewRead)}.`
+                    : "review.json is missing or invalid.",
             },
         };
     }
-    const bundle = runPaths ? await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE) : null;
+    // The display reads what it can: a run.json refused here shows as a missing one does.
+    const bundle = runPaths
+        ? runJsonValue(await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE))
+        : null;
     const projected = isRecord(bundle) && Array.isArray(bundle.streams)
         ? withCuaReviewProvenance(review, bundle.streams.filter(isRecord))
         : review;

package/dist/run/transient-comms-secrets.js

@@ -1,7 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { REDACTION_MARKERS } from "../evidence/redaction.js";
-import { holdsSecretValue, scrubSecretValues } from "../evidence/secret-scrub.js";
-import { escapeRegExp } from "./text.js";
+import { holdsSecretValue, scrubSecretValues, scrubValuesAsWritten, } from "../evidence/secret-scrub.js";
 const scopes = new AsyncLocalStorage();
 const MAX_VALUES = 8192;
 const MAX_BYTES = 1024 * 1024;
@@ -15,7 +14,7 @@ function usable(scope) {
 function fail(scope) {
     scope.failed = true;
     scope.values.clear();
-    delete scope.pattern;
+    delete scope.literal;
     throw new Error("TRANSIENT_NARRATION_SECRET_LIMIT");
 }
 /** Enclose both participant execution and its automatic analysis in one scope. Nested runs isolate too. */
@@ -30,7 +29,7 @@ export async function withTransientCommsSecrets(work) {
         scope.closed = true;
         scope.values.clear();
         scope.bytes = 0;
-        delete scope.pattern;
+        delete scope.literal;
     }
 }
 export function registerTransientCommsSecrets(values) {
@@ -50,7 +49,7 @@ export function registerTransientCommsSecrets(values) {
             fail(scope);
         scope.values.add(value);
         scope.bytes += bytes;
-        delete scope.pattern;
+        delete scope.literal;
     }
 }
 /** Literal, longest-first replacement in one pass; replacement text is never matched recursively. */
@@ -59,18 +58,8 @@ export function scrubTransientCommsText(text) {
     if (!scope)
         return text;
     usable(scope);
-    if (!scope.values.size)
-        return text;
-    try {
-        scope.pattern ??= new RegExp([...scope.values]
-            .sort((a, b) => b.length - a.length)
-            .map(escapeRegExp)
-            .join("|"), "g");
-        return text.replace(scope.pattern, REDACTION_MARKERS.secret);
-    }
-    catch {
-        return fail(scope);
-    }
+    scope.literal ??= scrubValuesAsWritten([...scope.values]);
+    return scope.literal(text);
 }
 const REDACTED = REDACTION_MARKERS.secret;
 /**