humanish 0.111.3 → 0.112.0

package/dist/run/participant-caption.js

@@ -0,0 +1,50 @@
+// The words a reader sees for one participant. Routes write the caption as the stream label, and
+// the Observer, the TUI and findings show that label, so every surface names the participant the
+// same way. The participant's taxonomy and ids stay in the bundle data, out of the caption.
+/** Ids `participantIdAt` makes for an undeclared roster entry. They number a position. */
+const NUMBERED_ID = /^(lane|role)-\d+$/;
+/** An id in words: `lobby-host` reads "Lobby host". */
+function inWords(id) {
+    const words = id
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .join(" ");
+    return `${words.charAt(0).toUpperCase()}${words.slice(1)}`;
+}
+/** A phone or a tablet. A desktop of any size goes unnamed, since most participants use one. */
+function deviceInWords(device) {
+    if (device === undefined)
+        return undefined;
+    if (device.preset.isMobile)
+        return "phone";
+    return device.name === "tablet" ? "tablet" : undefined;
+}
+/** "Lobby host", or "Player two, phone" for a participant on a phone. */
+export function participantCaption(participant) {
+    const { id, personaId } = participant;
+    const name = inWords(id === undefined || NUMBERED_ID.test(id) ? personaId : id);
+    const device = deviceInWords(participant.device);
+    return device === undefined ? name : `${name}, ${device}`;
+}
+const OLDER_SHARED_WORLD_LABEL = /^Concurrent persona (\S+)/;
+const OLDER_COMPUTER_USE_LABEL = /^CUA |^\S+ · browser$/;
+/**
+ * The caption a saved stream shows: its label, which a route writes with `participantCaption`.
+ * Earlier releases wrote ids and taxonomy into the label (`lane-01 · browser`, `CUA participant
+ * <id>: <study>`, `Concurrent persona <id> (type:<t> / ...) · <study>`), so a stream saved that way
+ * is captioned again from the id it names, without a device.
+ */
+export function savedCaption(stream) {
+    const { label, participantId, personaId } = stream;
+    const sharedWorldId = OLDER_SHARED_WORLD_LABEL.exec(label)?.[1];
+    if (sharedWorldId !== undefined) {
+        return participantCaption({ id: sharedWorldId, personaId: personaId ?? sharedWorldId });
+    }
+    if (OLDER_COMPUTER_USE_LABEL.test(label) && personaId !== undefined) {
+        return participantCaption({
+            ...(participantId === undefined ? {} : { id: participantId }),
+            personaId,
+        });
+    }
+    return label;
+}

package/dist/run/participant-records.d.ts

@@ -25,4 +25,4 @@ export declare function recordIdOf(stream: RunStream): string;
 /** The record id a saved event names, when it names one. */
 export declare function eventRecordIdOf(event: RunEvent): string | undefined;
 /** The participant id an adapter recorded on a saved stream (a fan-out `lane-NN` id), when it has one. */
-export declare function streamParticipantIdOf(stream: RunStream): string | undefined;
+export declare function streamParticipantIdOf(stream: Pick<RunStream, "laneId">): string | undefined;

package/dist/run/review-markdown.d.ts

@@ -0,0 +1,11 @@
+import type { RunBundle } from "./bundle.js";
+type ReviewBundle = Pick<RunBundle, "runId" | "mode" | "review"> & Partial<Pick<RunBundle, "outcome" | "simulations">> & {
+    scenario: Pick<RunBundle["scenario"], "title">;
+};
+/** The review's common head and gaps, around the route's evidence lines. */
+export declare function renderReviewMarkdown(bundle: ReviewBundle, middle: readonly string[], options?: {
+    beforeVerdict?: readonly string[];
+    style?: "preview";
+    status?: unknown;
+}): string;
+export {};

package/dist/run/review-markdown.js

@@ -0,0 +1,22 @@
+import { reviewOutcome } from "./display.js";
+import { verdictText } from "./judge.js";
+/** The review's common head and gaps, around the route's evidence lines. */
+export function renderReviewMarkdown(bundle, middle, options = {}) {
+    const preview = options.style === "preview";
+    const field = (name, value) => preview ? [`${name[0].toUpperCase()}${name.slice(1)}: ${value}`, ""] : [`- ${name}: ${value}`];
+    return [
+        `# ${preview ? "humanish Run Review" : bundle.scenario.title}`,
+        "",
+        ...field("run", bundle.runId),
+        ...field("mode", bundle.mode),
+        ...(options.beforeVerdict ?? []),
+        ...field("verdict", verdictText(bundle.review.verdict, bundle.mode)),
+        ...field("outcome", reviewOutcome(bundle, options.status)),
+        ...(preview ? [bundle.review.summary, ""] : field("summary", bundle.review.summary)),
+        ...middle,
+        ...(preview || bundle.review.gaps.length > 0
+            ? ["", "## Gaps", ...(preview ? [""] : []), ...bundle.review.gaps.map((gap) => `- ${gap}`)]
+            : []),
+        "",
+    ].join("\n");
+}

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

@@ -34,6 +34,13 @@ export interface RunCost {
 }
 /** The accounting's analysis spend, or null when the run sent no analysis request. */
 export declare function analysisCostOf(accounting: Pick<AnalysisAccounting, "dispatched" | "unresolved" | "unpriced" | "estimatedUsd" | "providers" | "warnings">): RunAnalysisCost | null;
+/** The recorded estimate, or a supported zero for a dry run with no cost record. */
+export declare function runEstimateUsd(entry: {
+    estimatedCostUsd?: number | null | undefined;
+    mode?: string | null | undefined;
+}): number | null;
+/** Add known estimates, retaining unknown when neither component has a price. */
+export declare function sumEstimatedUsd(a: number | null, b: number | null): number | null;
 export declare function runCost(subtotal: RunCostSubtotal | null | undefined, analysis?: RunAnalysisCost | null): RunCost;
 /**
  * A run index entry's cost: its participants-and-desktops figure, complete or a lower bound when

package/dist/run/run-cost.js

@@ -11,25 +11,45 @@ export function analysisCostOf(accounting) {
         providers: [...accounting.providers],
     };
 }
+/** The recorded estimate, or a supported zero for a dry run with no cost record. */
+export function runEstimateUsd(entry) {
+    const usd = entry.estimatedCostUsd;
+    if (typeof usd === "number" && Number.isFinite(usd) && usd >= 0)
+        return usd;
+    return usd === undefined && entry.mode === "dry-run" ? 0 : null;
+}
+/** Add known estimates, retaining unknown when neither component has a price. */
+export function sumEstimatedUsd(a, b) {
+    const left = runEstimateUsd({ estimatedCostUsd: a });
+    const right = runEstimateUsd({ estimatedCostUsd: b });
+    return left === null && right === null ? null : round6((left ?? 0) + (right ?? 0));
+}
 export function runCost(subtotal, analysis) {
     if (subtotal === null || subtotal === undefined)
         return { run: null, analysis: null, total: null };
     const run = {
-        usd: typeof subtotal.estimatedTotalUsd === "number" ? subtotal.estimatedTotalUsd : null,
+        usd: runEstimateUsd({ estimatedCostUsd: subtotal.estimatedTotalUsd }),
         complete: subtotal.fullyEstimated === undefined ? null : subtotal.fullyEstimated,
         ratesAsOf: subtotal.ratesAsOf ?? null,
         placeholder: subtotal.placeholder === true,
     };
-    const spent = analysis ?? null;
-    const known = [run.usd, spent?.estimatedUsd].filter((usd) => typeof usd === "number");
-    if (known.length === 0)
+    const spent = analysis == null
+        ? null
+        : {
+            ...analysis,
+            estimatedUsd: runEstimateUsd({ estimatedCostUsd: analysis.estimatedUsd }),
+            complete: analysis.complete &&
+                runEstimateUsd({ estimatedCostUsd: analysis.estimatedUsd }) !== null,
+        };
+    const totalUsd = sumEstimatedUsd(run.usd, spent?.estimatedUsd ?? null);
+    if (totalUsd === null)
         return { run, analysis: spent, total: null };
     const lowerBound = run.usd === null || run.complete === false || spent?.complete === false;
     return {
         run,
         analysis: spent,
         total: {
-            usd: round6(known.reduce((sum, usd) => sum + usd, 0)),
+            usd: totalUsd,
             complete: lowerBound ? false : run.complete,
         },
     };

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

@@ -1,6 +1,6 @@
 import { AnalysisCostCache } from "./run-index-analysis.js";
 import type { RunAnalysisCost } from "./run-cost.js";
-import { type RunLiveness, type RunStatusRecord } from "./status.js";
+import { type RunLiveness } from "./status.js";
 import { type RunStudyProvenance } from "./study-provenance.js";
 import type { ExecutionFailure } from "./judge.js";
 declare const RUN_INDEX_SCHEMA = "humanish.run-index.v1";
@@ -51,13 +51,6 @@ export interface RunIndexResult {
     /** Directories that could not be read at all, by name: surfaced, never silently dropped. */
     unreadable: string[];
 }
-/** What a cached entry was derived from, so a changed file invalidates exactly that entry. */
-interface CacheKey {
-    file: string;
-    mtimeMs: number;
-    size: number;
-    ino: number;
-}
 /**
  * A process-lifetime cache. Deliberately explicit rather than module-global state: a caller that
  * refreshes on a cadence keeps one and passes it back, and a caller that wants a cold read passes
@@ -67,51 +60,12 @@ export declare class RunIndexCache {
     private readonly slots;
     /** Analysis costs, keyed on their own fingerprint: analysis lands after the status record. */
     readonly analysis: AnalysisCostCache;
-    get(runId: string, key: CacheKey): RunIndexEntry | undefined;
-    set(runId: string, key: CacheKey, entry: RunIndexEntry): void;
+    get(runId: string, key: string): RunIndexEntry | undefined;
+    set(runId: string, key: string, entry: RunIndexEntry): void;
     /** Drop entries for runs that no longer exist, so a long-lived surface cannot leak. */
     retain(runIds: Iterable<string>): void;
     get size(): number;
 }
-/** The legacy shape this reads out of a bundle. Narrow on purpose: only listing facts. */
-interface BundleFacts {
-    runId?: string;
-    mode?: string;
-    createdAt?: string;
-    study?: unknown;
-    lab?: unknown;
-    persona?: {
-        source?: string;
-    };
-    scenario?: {
-        source?: string;
-    };
-    simulations?: {
-        status?: string;
-    }[];
-    review?: {
-        verdict?: string;
-        participants?: {
-            total: number;
-            reachedGoal: number;
-            reportedFriction?: number;
-        };
-    };
-    cost?: {
-        estimatedTotalUsd?: number | null;
-        fullyEstimated?: unknown;
-    };
-    outcome?: unknown;
-}
-/**
- * One run's liveness from files already read: its status record when usable, else its bundle.
- * `readRunIndex` reads in the same order; `humanish verify` calls this with both in hand. `record`
- * is the status record the liveness came from, when there was one.
- */
-export declare function runLiveness(runId: string, status: unknown, bundle: Pick<BundleFacts, "simulations" | "outcome">, nowMs: number): {
-    liveness: RunLiveness;
-    record?: RunStatusRecord;
-};
 export interface ReadRunIndexOptions {
     /** Reused across refreshes so unchanged runs are not re-read. */
     cache?: RunIndexCache;
@@ -122,7 +76,7 @@ export interface ReadRunIndexOptions {
     limit?: number;
 }
 /**
- * Read every run in `.humanish/runs`, cheapest source first. Never throws for a bad run directory;
+ * Read every run in `.humanish/runs`, from its cached source files. Never throws for a bad run directory;
  * an unreadable one is named in `unreadable`.
  */
 export declare function readRunIndex(cwdInput: string, options?: ReadRunIndexOptions): Promise<RunIndexResult>;

package/dist/run/run-index.js

@@ -1,20 +1,9 @@
-// The run index: list and classify every run in a project without parsing bundles.
-//
-// The existing `listRuns` walks each run tree, screenshots included, validating symlinks and
-// then parses each `run.json`: measured 197ms cold / 152ms warm at 25 runs. That is fine for a
-// command that prints once and exits, and much too hot for a surface that refreshes on a cadence
-// over SSH. This module reads the small `status.json` record each run now writes (586 bytes beside
-// a 92KB bundle) and caches per-run entries keyed on the stat of the file each was derived from.
-//
-// Rules, unchanged from the record itself:
-//   - `run.json` is the evidence-of-record. Every field here is a projection for listing and
-//     classification; nothing here is a claim about what a participant did.
-//   - A run with no status record is not assumed finished. It is classified from what is on disk:
-//     a bundle means finished, receipts without a bundle mean interrupted. That is the
-//     reading of a run whose process died (and, before this contract existed, of every run).
-//   - One unreadable run directory degrades that run, never the listing.
+// The run index caches listing facts by both source files. run.json's outcome wins over status,
+// including when a process stopped between publishing its bundle and finalizing its heartbeat.
+// A status record supplies freshness only when the bundle has no outcome.
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
+import { runLiveness } from "./liveness.js";
 import { AnalysisCostCache, readIndexedAnalysisCost } from "./run-index-analysis.js";
 import { RUN_STATUS_FILE, classifyRunStatus, isRunStatusRecord, } from "./status.js";
 import { studyProvenanceOf } from "./study-provenance.js";
@@ -34,11 +23,7 @@ export class RunIndexCache {
         const slot = this.slots.get(runId);
         if (slot === undefined)
             return undefined;
-        const same = slot.key.file === key.file &&
-            slot.key.mtimeMs === key.mtimeMs &&
-            slot.key.size === key.size &&
-            slot.key.ino === key.ino;
-        return same ? slot.entry : undefined;
+        return slot.key === key ? slot.entry : undefined;
     }
     set(runId, key, entry) {
         this.slots.set(runId, { key, entry });
@@ -81,7 +66,7 @@ function entryFromStatus(record, nowMs) {
     return {
         runId: record.runId,
         derivedFrom: "status",
-        liveness: classifyRunStatus(record, nowMs),
+        liveness: runLiveness(record.runId, record, {}, nowMs).liveness,
         mode: record.mode,
         ...(typeof record.pid === "number" ? { pid: record.pid } : {}),
         ...studyEntry(studyProvenanceOf(record)),
@@ -109,29 +94,6 @@ function entryFromStatus(record, nowMs) {
 function usableStatusRecord(raw, runId) {
     return isRunStatusRecord(raw) && raw.runId === runId;
 }
-/**
- * The bundle-only reading, for a run with no usable status record. A bundle on disk usually means
- * the run reached its final write. But a live run now flushes an in-progress bundle as it goes (so
- * anything asking what a participant is doing has something to read), and that bundle marks its
- * simulations `running`. With no status record there is no freshness to judge, and the
- * reading of "it started, and nothing here says it finished" is interrupted, not finished.
- */
-function bundleLiveness(bundle) {
-    if (isRunOutcome(bundle.outcome))
-        return bundle.outcome.state;
-    const inProgress = (bundle.simulations ?? []).some((simulation) => simulation?.status === "running");
-    return inProgress ? "interrupted" : "finished";
-}
-/**
- * One run's liveness from files already read: its status record when usable, else its bundle.
- * `readRunIndex` reads in the same order; `humanish verify` calls this with both in hand. `record`
- * is the status record the liveness came from, when there was one.
- */
-export function runLiveness(runId, status, bundle, nowMs) {
-    return usableStatusRecord(status, runId)
-        ? { liveness: classifyRunStatus(status, nowMs), record: status }
-        : { liveness: bundleLiveness(bundle) };
-}
 function studyEntry(study) {
     return study === undefined ? {} : { study };
 }
@@ -141,7 +103,7 @@ function entryFromBundle(runId, bundle) {
     return {
         runId,
         derivedFrom: "bundle",
-        liveness: bundleLiveness(bundle),
+        liveness: runLiveness(runId, undefined, { simulations: bundle.simulations, outcome }, Date.now()).liveness,
         ...(bundle.mode === "dry-run" || bundle.mode === "live" ? { mode: bundle.mode } : {}),
         ...studyEntry(studyProvenanceOf(bundle)),
         ...(bundle.createdAt === undefined ? {} : { startedAt: bundle.createdAt }),
@@ -160,7 +122,7 @@ function entryFromBundle(runId, bundle) {
     };
 }
 /**
- * Read every run in `.humanish/runs`, cheapest source first. Never throws for a bad run directory;
+ * Read every run in `.humanish/runs`, from its cached source files. Never throws for a bad run directory;
  * an unreadable one is named in `unreadable`.
  */
 export async function readRunIndex(cwdInput, options = {}) {
@@ -199,52 +161,60 @@ export async function readRunIndex(cwdInput, options = {}) {
         unreadable,
     };
 }
-/** One run's entry, cheapest source first, or "unreadable" when its bundle cannot be parsed. */
+/** One run's entry, from its cached source files, or "unreadable" when its bundle cannot be parsed. */
 async function readEntry(runId, runDir, cache, nowMs) {
     const statusFile = path.join(runDir, RUN_STATUS_FILE);
     const bundleFile = path.join(runDir, RUN_BUNDLE_FILE);
-    // Cheapest source first: the status record. Its stat is the cache key, so a live run whose
-    // record ticks every 5s re-reads 586 bytes and nothing else.
-    const statusKey = await statKey(statusFile);
-    if (statusKey !== null) {
-        const cached = cache?.get(runId, statusKey);
-        if (cached !== undefined) {
-            // A running record's liveness is time-dependent, so it is recomputed even on a cache hit:
-            // an unchanged record can still have gone stale. An ended record (finished or
-            // interrupted, both with completedAt) keeps the liveness it was cached with.
-            return cached.derivedFrom === "status" &&
-                cached.updatedAt !== undefined &&
-                cached.completedAt === undefined
-                ? {
-                    ...cached,
-                    liveness: classifyRunStatus({ state: "running", updatedAt: cached.updatedAt }, nowMs),
-                }
-                : cached;
-        }
-        const raw = await readJson(statusFile);
-        if (usableStatusRecord(raw, runId)) {
-            const entry = entryFromStatus(raw, nowMs);
-            cache?.set(runId, statusKey, entry);
-            return entry;
-        }
+    const [statusKey, bundleKey] = await Promise.all([statKey(statusFile), statKey(bundleFile)]);
+    const key = JSON.stringify([statusKey, bundleKey]);
+    const cached = cache?.get(runId, key);
+    if (cached !== undefined) {
+        return cached.derivedFrom === "status" &&
+            cached.updatedAt !== undefined &&
+            cached.completedAt === undefined
+            ? {
+                ...cached,
+                liveness: classifyRunStatus({ state: "running", updatedAt: cached.updatedAt }, nowMs),
+            }
+            : cached;
+    }
+    const [status, raw] = await Promise.all([
+        statusKey === null ? undefined : readJson(statusFile),
+        bundleKey === null ? undefined : readJson(bundleFile),
+    ]);
+    const record = usableStatusRecord(status, runId) ? status : undefined;
+    const bundle = raw !== null && typeof raw === "object" ? raw : undefined;
+    let entry;
+    if (bundle !== undefined && isRunOutcome(bundle.outcome)) {
+        const metadata = record === undefined ? undefined : entryFromStatus(record, nowMs);
+        entry = {
+            ...(metadata === undefined
+                ? {}
+                : {
+                    pid: metadata.pid,
+                    startedAt: metadata.startedAt,
+                    updatedAt: metadata.updatedAt,
+                    ...(metadata.completedAt === undefined ? {} : { completedAt: metadata.completedAt }),
+                    ...(metadata.durationMs === undefined ? {} : { durationMs: metadata.durationMs }),
+                    ...studyEntry(metadata.study),
+                }),
+            ...entryFromBundle(runId, bundle),
+        };
+    }
+    else if (record !== undefined) {
+        entry = entryFromStatus(record, nowMs);
+    }
+    else if (bundle !== undefined) {
+        entry = entryFromBundle(runId, bundle);
+    }
+    else if (bundleKey !== null) {
+        return "unreadable";
     }
-    // No usable status record: fall back to the bundle. This is every run written before the
-    // contract existed, and it is why an old project still lists correctly.
-    const bundleKey = await statKey(bundleFile);
-    if (bundleKey !== null) {
-        const cached = cache?.get(runId, bundleKey);
-        if (cached !== undefined)
-            return cached;
-        const raw = await readJson(bundleFile);
-        if (raw === null || typeof raw !== "object")
-            return "unreadable";
-        const entry = entryFromBundle(runId, raw);
-        cache?.set(runId, bundleKey, entry);
-        return entry;
+    else {
+        return { runId, derivedFrom: "directory", liveness: "interrupted" };
     }
-    // Neither record nor bundle: receipts without an outcome. That is precisely an interrupted
-    // run (the shape a dropped connection leaves), and saying so is more useful than hiding it.
-    return { runId, derivedFrom: "directory", liveness: "interrupted" };
+    cache?.set(runId, key, entry);
+    return entry;
 }
 /** Newest-first ordering: the most recent thing known about a run, else its id's own timestamp. */
 function sortKey(entry) {

package/dist/run/run.d.ts

@@ -15,7 +15,7 @@ interface StartRunOptions {
     /** `none` when the route creates no sandbox for this run; status.json records it for reclaim. */
     sandboxes?: "none" | undefined;
     /** review.md for the published bundle. */
-    renderReview: (bundle: RunBundle) => string;
+    renderReview: (bundle: RunBundle, status?: unknown) => string;
     /** Used by `FinishedRun.renderObserver`; `render` is the `StudyDeps.renderObserver` seam. */
     observer?: {
         open: boolean;
@@ -53,7 +53,7 @@ interface RouteRunOptions {
     cwd: string;
     prefix: RunIdPrefix;
     /** review.md for the published bundle. */
-    renderReview: (bundle: RunBundle) => string;
+    renderReview: (bundle: RunBundle, status?: unknown) => string;
     /** `none` when the route creates no sandbox for this run; status.json records it for reclaim. */
     sandboxes?: "none" | undefined;
     /** Clock for `createdAt` and the latest pointer. The minted id reads the wall clock. */

package/dist/run/run.js

@@ -14,7 +14,8 @@ import { registerActiveRun } from "./active-runs.js";
 import { writeContainedOutputFile, writePreparedRunLatestPointer } from "./contained-output.js";
 import { scrubRunSandboxIds, withPublicSandboxIds } from "./sandbox-ids.js";
 import { RunSecrets } from "./secrets.js";
-import { beginRunStatus, runStatusOutcome, } from "./status.js";
+import { RUN_STATUS_FILE, beginRunStatus, runStatusOutcome, } from "./status.js";
+import { readRunJsonIfExists } from "./locate.js";
 /** An entry point called in a state that does not admit it. */
 class RunLifecycleError extends Error {
     name = "RunLifecycleError";
@@ -165,11 +166,12 @@ 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;
         await writeContainedOutputFile(paths, "review.json", json(publicBundle.review), "utf8");
-        await writeContainedOutputFile(paths, "review.md", options.renderReview(publicBundle), "utf8");
+        await writeContainedOutputFile(paths, "review.md", options.renderReview(publicBundle, status), "utf8");
         const events = publicBundle.events.map((event) => JSON.stringify(event)).join("\n");
         await writeContainedOutputFile(paths, "events.ndjson", `${events}\n`, "utf8");
-        await writeContainedOutputFile(paths, "observer/observer-data.json", json(buildObserverData(publicBundle)), "utf8");
+        await writeContainedOutputFile(paths, "observer/observer-data.json", json(buildObserverData(publicBundle, undefined, status)), "utf8");
     };
     const snapshot = async (bundle) => {
         await writeBundleFiles(bundle, undefined, async () => { });

package/dist/run/secrets.d.ts

@@ -8,8 +8,10 @@ interface RunSecretsOptions {
 export declare class RunSecrets {
     #private;
     /**
-     * Replaces every held value with the marker. 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.
+     * 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.
      */
     readonly scrub: (text: string) => string;
     /** `seed` keeps its order; values shorter than the floor are dropped. */
@@ -18,5 +20,16 @@ export declare class RunSecrets {
     add(values: readonly string[]): void;
     /** The held values, seed first, in one array that later `add` calls extend. */
     values(): readonly string[];
+    /**
+     * Every held value as written and in each encoded form, longest first, in one array that later
+     * `add` calls extend. The terminal recorder sizes the output it keeps past its cap from these.
+     */
+    forms(): readonly string[];
+    /**
+     * Where `text` holds a held value: each encoded form as written, and each form in the text's
+     * view without terminal escape sequences and with percent escapes decoded. Sorted, with
+     * overlapping spans merged. A scrub that replaces across chunk boundaries reads these.
+     */
+    spans(text: string): Array<[number, number]>;
 }
 export {};