humanish 0.104.3 → 0.106.0

package/dist/run/streams.d.ts

@@ -0,0 +1,257 @@
+import type { CodexAppServerTrace } from "../actors/codex/app-server-trace.js";
+import type { ActorTrace, ActorTraceItem } from "../actors/contract.js";
+import type { RunDesktopRecording } from "../evidence/desktop-recording-types.js";
+export type RunStreamKind = "ui" | "browser" | "terminal" | "tui" | "codex-ui" | "artifact" | "summary";
+export type RunSimulationStatus = "queued" | "preparing" | "running" | "passed" | "abandoned" | "incomplete" | "complete" | "blocked" | "timed_out" | "failed" | "contract_proof_only";
+/** Statuses a stream ends in. Analysis requires every stream of a run in one of these. */
+export declare const TERMINAL_SIMULATION_STATUSES: ReadonlySet<RunSimulationStatus>;
+interface RunStreamCompletion {
+    actorLogPath?: string;
+    actorLogTail?: string;
+    actorLastMessageTail?: string;
+    actorPid?: number;
+    actorStatus?: "not_started" | "running" | "passed" | "failed" | "blocked" | "timed_out" | "suspended" | "unknown";
+    appLogPath?: string;
+    appPid?: number;
+    appReason?: string;
+    appStatus?: "not_started" | "running" | "blocked" | "failed" | "missing" | "unknown";
+    appUrl?: string;
+    checkedAt: string;
+    exitCode?: number;
+    logTail?: string;
+    nestedObserverPresent?: boolean;
+    nestedVerifyPassed?: boolean;
+    reason: string;
+    status: "running" | "passed" | "failed" | "blocked" | "timed_out";
+    visualReason?: string;
+    visualStatus?: "not_started" | "visible" | "blocked" | "unknown";
+    visualWindowCount?: number;
+    meaningfulUse?: RunMeaningfulUseScore;
+}
+/**
+ * The CLOSED set of core meaningful-use scoring components. Closed by design: these are the generic
+ * dimensions core itself meters (setup/filesystem/nested/actor/product/feedback). A
+ * product-specific scorecard does NOT extend this enum, so adopters' nouns stay out of core. It
+ * ships as a thin in-repo extension that emits a namespaced `RunAdapterScore` via the lane's
+ * `score` hook, leaving its own component breakdown in that score's `data`. Exported so a thin
+ * adapter can type against core's score shape without forking.
+ */
+type RunMeaningfulUseComponentId = "setup-correctness" | "filesystem-evidence" | "nested-humanish-evidence" | "actor-activity" | "product-surface" | "feedback-quality";
+interface RunMeaningfulUseScore {
+    schema: "humanish.meaningful-use-score.v1";
+    status: "pass" | "partial" | "fail";
+    score: number;
+    summary: string;
+    hardFailures: string[];
+    components: Array<{
+        id: RunMeaningfulUseComponentId;
+        label: string;
+        status: "pass" | "partial" | "fail";
+        score: number;
+        detail: string;
+    }>;
+}
+export interface RunDesktopGeometry {
+    /** E2B/X display geometry. Requested config and verified runtime evidence stay distinct. */
+    screen: {
+        requested: {
+            width: number;
+            height: number;
+        };
+        verified?: {
+            width: number;
+            height: number;
+            source: "xdpyinfo";
+        };
+        /**
+         * The device preset as DECLARED by the lab, present only when it differs from `requested`
+         * because the rendered width was floored to MIN_DESKTOP_RENDER_WIDTH.
+         *
+         * Without this, a floored run is indistinguishable from a faithful one: `verified` compares
+         * the floored number with itself and reports a match, so a reader of the bundle sees
+         * requested 500 / verified 500 and reasonably concludes a 500-wide preset was asked for. A
+         * `mobile` (414) and a `small-mobile` (360) seat both render at 500 and look identical here.
+         * When this field is set, the preset width did NOT render; see #221.
+         */
+        declared?: {
+            width: number;
+            height: number;
+            preset: string;
+        };
+    };
+    /** Measured browser bounds after the fill attempt. X client bounds take precedence for
+     * physical visibility; CDP page-reported outer bounds can reflect mobile emulation. */
+    browserWindow?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        source: "cdp" | "xdotool" | "xwininfo";
+    };
+    /** Browser CSS layout viewport measured from the running page, never copied from config. */
+    viewport?: {
+        width: number;
+        height: number;
+        deviceScaleFactor: number;
+        source: "cdp";
+    };
+    /**
+     * Mobile fidelity beyond viewport size (#221), present only when the lab asked for it. `requested`
+     * is what was applied through CDP; `resolved` is what the page reported about itself afterwards
+     * and is the proof, never copied from the request. A run without this block is a
+     * responsive-viewport study, whatever its preset is named.
+     */
+    fidelity?: {
+        tier: "mobile-emulated";
+        requested: {
+            width: number;
+            height: number;
+            deviceScaleFactor: number;
+            touch: boolean;
+            userAgent: string;
+        };
+        applied: string[];
+        resolved?: {
+            userAgent: string;
+            devicePixelRatio: number;
+            innerWidth: number;
+            innerHeight: number;
+            maxTouchPoints: number;
+            coarsePointer: boolean;
+            source: "cdp";
+        };
+        /**
+         * Page targets the participant drove AFTER the launch page (a link that opened in a new tab)
+         * whose own read-back reported the requested viewport width (#623). Absent when the
+         * participant never left the launch tab; a later tab that did NOT report the width is a lane
+         * warning instead.
+         */
+        laterTargets?: {
+            targetId: string;
+            innerWidth: number;
+            devicePixelRatio: number;
+            maxTouchPoints: number;
+        }[];
+        /**
+         * The emulation holder's log after its announce, one JSON line per later target it attached
+         * to (`attached`, `sent`) and per reply that came back as an error (`replyError`), at most 50
+         * lines. Absent when no later target appeared.
+         */
+        holderLog?: string[];
+    };
+    /** Public-safe geometry measurement/fill warnings retained with the stream evidence. */
+    warnings?: string[];
+}
+/** The original participant-facing assignment, before runtime access/coordination details. */
+export interface RunParticipantAssignment {
+    mission: string;
+    focus?: string;
+    tasks?: Array<{
+        id: string;
+        goal: string;
+    }>;
+}
+export interface RunStream {
+    id: string;
+    simId: string;
+    /** Adapter-owned lane id for fan-out / target-swarm runs. Safe categorical metadata only. */
+    laneId?: string;
+    /** Adapter-owned actor class for grouping lanes, e.g. viewer/reviewer/admin. */
+    actorType?: string;
+    /** Adapter-owned product surface label for grouping lanes without parsing URLs. */
+    surface?: string;
+    /** Adapter-owned scenario/case grouping label. */
+    caseGroup?: string;
+    /** Authored/default mission and lane focus, redacted before persistence. Missing on older
+     * bundles and uninstrumented routes; never reconstructed from study context or narration. */
+    assignment?: RunParticipantAssignment;
+    kind: RunStreamKind;
+    label: string;
+    status: RunSimulationStatus;
+    transport: "snapshot" | "polling" | "sse" | "pty" | "app-server";
+    updatedAt: string;
+    url?: string;
+    embed?: {
+        kind: "iframe" | "terminal" | "screenshot" | "placeholder";
+        url?: string;
+        title?: string;
+    };
+    /** Set by the attached watch server when the lane's sandbox is gone: the injected live URL
+     *  would render a provider error page, so viewers fall back to recorded evidence. Runtime-only
+     *  and never persisted into bundles; declared here because the served observer-data carries it
+     *  and the client is typed against this contract. */
+    liveEnded?: boolean;
+    /**
+     * Browser CSS layout viewport. Deterministic browser adapters may declare and render this
+     * exactly; hosted-desktop CUA producers set it only from a runtime measurement. Historical
+     * hosted CUA bundles may contain the requested screen size here instead.
+     */
+    viewport?: {
+        width: number;
+        height: number;
+        deviceScaleFactor?: number;
+        isMobile?: boolean;
+    };
+    /** Truthful screen/window/viewport evidence for hosted desktop browser lanes. */
+    desktopGeometry?: RunDesktopGeometry;
+    terminal?: {
+        title: string;
+        format: "ansi" | "plain";
+        stdin: "disabled" | "planned" | "sent";
+        tail: string;
+    };
+    ui?: {
+        actorStatus?: string;
+        appStatus?: string;
+        appUrl?: string;
+        route?: string;
+        intent?: string;
+        nestedObserverPath?: string;
+        nestedObserverUrl?: string;
+        screenshotUrl?: string;
+        state?: string;
+        visualStatus?: string;
+    };
+    codex?: {
+        provider: "codex-app-server";
+        eventCount?: number;
+        experimentalApi?: boolean;
+        model?: string;
+        sessionId?: string;
+        state: "not_connected" | "connecting" | "watching" | "running" | "completed" | "failed" | "blocked" | "timed_out";
+        contract: string;
+        threadId?: string;
+        trace?: CodexAppServerTrace;
+        tracePath?: string;
+        turnId?: string;
+    };
+    actor?: ActorTrace;
+    /**
+     * Mid-run partial actor evidence (#441): the redacted trace items recorded SO FAR,
+     * flushed while a live lane is still running so the attached Observer's timeline can
+     * grow. Deliberately NOT an ActorTrace — a running lane has no honest status,
+     * completionReason, or completedAt, and this shape cannot claim them. Present ONLY on
+     * `inProgress` bundles; the final write replaces it with the real `actor` and never
+     * carries it.
+     */
+    liveActor?: {
+        schema: "humanish.live-actor.v1";
+        executionProfile?: ActorTrace["executionProfile"];
+        providerRequests?: ActorTrace["providerRequests"];
+        historyTurnsOmitted?: number;
+        tokenUsage?: ActorTrace["tokenUsage"];
+        estimatedCost?: ActorTrace["estimatedCost"];
+        ids?: ActorTrace["ids"];
+        /** When this flush was written (ISO-8601). */
+        updatedAt: string;
+        items: ActorTraceItem[];
+    };
+    completion?: RunStreamCompletion;
+    recording?: RunDesktopRecording;
+    artifacts: Array<{
+        label: string;
+        path: string;
+        kind: "bundle" | "review" | "observer" | "events" | "screenshot" | "trace" | "log" | "filesystem" | "recording";
+    }>;
+}
+export {};

package/dist/run/streams.js

@@ -0,0 +1,12 @@
+// The streams[] records of run.json: one live or recorded view of a participant, with its
+// completion, desktop geometry and assignment.
+/** Statuses a stream ends in. Analysis requires every stream of a run in one of these. */
+export const TERMINAL_SIMULATION_STATUSES = new Set([
+    "complete",
+    "passed",
+    "failed",
+    "blocked",
+    "timed_out",
+    "abandoned",
+    "incomplete",
+]);

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

@@ -0,0 +1,35 @@
+import { type PreparedOutputRoot } from "./contained-output.js";
+/**
+ * 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
+ * encoded `..` or separator cannot survive into a later decode.
+ */
+export declare function isStudyEvidencePath(value: string): boolean;
+/**
+ * True when `value` (at most `maxLength` characters) stays a plain relative path through up to five
+ * rounds of percent-decoding: no round may match `unsafe`, have an empty, `.` or `..` segment, or
+ * change the segment count. A value that stops decoding is accepted once it has no escapes left.
+ */
+export declare function decodesToPlainRelativePath(value: string, maxLength: number, unsafe: RegExp): boolean;
+/**
+ * Bounded companion to readContainedRegularFile. A growing or swapped file must
+ * not turn an analysis budget into an unbounded read. No returned bytes have
+ * authority to select another file or initiate a network request.
+ */
+export declare function readBoundedStudyFile(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<Buffer | null>;
+/**
+ * After a bounded read returned nothing: true when the file is absent, false when something is
+ * there that could not be read. Errors other than ENOENT propagate.
+ */
+export declare function pathMissing(filePath: string): Promise<boolean>;
+export type BoundedStudyFileResult = {
+    state: "read";
+    bytes: Buffer;
+} | {
+    state: "limit";
+    size: bigint;
+} | {
+    state: "unavailable";
+};
+/** Size refusals are distinguished only after the same contained regular-file checks. */
+export declare function readBoundedStudyFileResult(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<BoundedStudyFileResult>;

package/dist/run/study-files.js

@@ -0,0 +1,164 @@
+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 { 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.
+/**
+ * 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
+ * encoded `..` or separator cannot survive into a later decode.
+ */
+export function isStudyEvidencePath(value) {
+    return decodesToPlainRelativePath(value, 1024, /[\\:\x00-\x1f\x7f]|^\//);
+}
+/**
+ * True when `value` (at most `maxLength` characters) stays a plain relative path through up to five
+ * rounds of percent-decoding: no round may match `unsafe`, have an empty, `.` or `..` segment, or
+ * change the segment count. A value that stops decoding is accepted once it has no escapes left.
+ */
+export function decodesToPlainRelativePath(value, maxLength, unsafe) {
+    if (!value || value.length > maxLength)
+        return false;
+    try {
+        encodeURIComponent(value);
+    }
+    catch {
+        return false;
+    }
+    let checked = value;
+    for (let attempt = 0; attempt < 5; attempt++) {
+        if (unsafe.test(checked) ||
+            checked.split("/").some((part) => part === "" || part === "." || part === ".."))
+            return false;
+        let decoded;
+        try {
+            decoded = decodeURIComponent(checked);
+        }
+        catch {
+            return !/%[0-9a-f]{2}/i.test(checked);
+        }
+        if (decoded === checked)
+            return true;
+        if (decoded.split("/").length !== checked.split("/").length)
+            return false;
+        checked = decoded;
+    }
+    return false;
+}
+/**
+ * Bounded companion to readContainedRegularFile. A growing or swapped file must
+ * not turn an analysis budget into an unbounded read. No returned bytes have
+ * authority to select another file or initiate a network request.
+ */
+export async function readBoundedStudyFile(root, relativePath, maxBytes) {
+    const result = await readBoundedStudyFileResult(root, relativePath, maxBytes);
+    return result.state === "read" ? result.bytes : null;
+}
+/**
+ * Still the same single-link regular file, unchanged since `before`. Every recheck uses this one
+ * field set; ctime catches a chmod or link change that leaves size and mtime alone.
+ */
+function sameFile(before, current) {
+    return (current.isFile() &&
+        !current.isSymbolicLink() &&
+        current.nlink === 1n &&
+        current.dev === before.dev &&
+        current.ino === before.ino &&
+        current.size === before.size &&
+        current.mtimeNs === before.mtimeNs &&
+        current.ctimeNs === before.ctimeNs);
+}
+/**
+ * After a bounded read returned nothing: true when the file is absent, false when something is
+ * there that could not be read. Errors other than ENOENT propagate.
+ */
+export async function pathMissing(filePath) {
+    try {
+        await lstat(filePath);
+        return false;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return true;
+        throw error;
+    }
+}
+const unavailable = { state: "unavailable" };
+/** Size refusals are distinguished only after the same contained regular-file checks. */
+export async function readBoundedStudyFileResult(root, relativePath, maxBytes) {
+    if (!isStudyEvidencePath(relativePath) || !Number.isSafeInteger(maxBytes) || maxBytes < 1)
+        return unavailable;
+    const validateRoot = async () => {
+        if ("physicalRunRoot" in root) {
+            await validatePreparedRunRootIdentity(root);
+            return root.physicalRunRoot;
+        }
+        await assertPreparedSelectedOutputDirectory(root);
+        return root.physicalPath;
+    };
+    try {
+        const physicalRoot = await validateRoot();
+        const candidate = path.join(physicalRoot, relativePath);
+        if (!isPathInside(physicalRoot, candidate) || candidate === physicalRoot)
+            return unavailable;
+        const validateParents = async () => {
+            let current = physicalRoot;
+            for (const segment of relativePath.split("/").slice(0, -1)) {
+                current = path.join(current, segment);
+                const info = await lstat(current);
+                if (!info.isDirectory() || info.isSymbolicLink())
+                    throw new Error("Unsafe analysis input directory.");
+            }
+        };
+        await validateParents();
+        const before = await lstat(candidate, { bigint: true });
+        if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n)
+            return unavailable;
+        if ((await realpath(candidate)) !== candidate)
+            return unavailable;
+        if (before.size > BigInt(maxBytes)) {
+            if ((await validateRoot()) !== physicalRoot)
+                return unavailable;
+            await validateParents();
+            if (!sameFile(before, await lstat(candidate, { bigint: true })))
+                return unavailable;
+            return { state: "limit", size: before.size };
+        }
+        // O_NONBLOCK avoids hanging if a regular leaf is raced into a special file.
+        const handle = await open(candidate, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            if (!sameFile(before, await handle.stat({ bigint: true })))
+                return unavailable;
+            const chunks = [];
+            let total = 0;
+            while (total <= maxBytes) {
+                const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes + 1 - total));
+                const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+                if (bytesRead === 0)
+                    break;
+                total += bytesRead;
+                if (total > maxBytes)
+                    return unavailable;
+                chunks.push(chunk.subarray(0, bytesRead));
+            }
+            if (!sameFile(before, await handle.stat({ bigint: true })) || total !== Number(before.size))
+                return unavailable;
+            if ((await validateRoot()) !== physicalRoot)
+                return unavailable;
+            await validateParents();
+            if (!sameFile(before, await lstat(candidate, { bigint: true })))
+                return unavailable;
+            return { state: "read", bytes: Buffer.concat(chunks, total) };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return unavailable;
+    }
+}

package/dist/run/terminal-contract.d.ts

@@ -0,0 +1,25 @@
+export declare const TERMINAL_EVENTS_ARTIFACT = "terminal-events.ndjson";
+export declare const TERMINAL_TRANSCRIPT_ARTIFACT = "terminal-transcript.txt";
+export declare const TERMINAL_LEDGERS_ARTIFACT = "terminal-ledgers.json";
+/** The cost categories the lane meters. product/media/payment are adapter signals; core can
+ *  populate the provider line from the actor trace's tokenUsage.costUsd when present. */
+export type CostCategory = "product" | "media" | "payment" | "provider";
+/** The four cost categories, in a fixed order so the ledger shape is stable across runs. */
+export declare const COST_CATEGORIES: readonly CostCategory[];
+/**
+ * Strip ANSI/control noise from a captured terminal transcript into stable, scannable text. Pure
+ * (no IO). Exported so the terminal-product lane (src/routes/terminal/live-sandbox.ts) normalizes
+ * its captured exec stream EXACTLY as the local-actor lanes do — the verdict-nonce scorer is only
+ * sound against the same normalization the marker is matched on, so the logic must not diverge.
+ */
+export declare function normalizeLocalActorTranscript(transcript: string): string;
+type ActorVerdict = "passed" | "blocked" | "failed";
+/**
+ * Extract the per-run verdict from a normalized transcript: the agent must print exactly
+ * `HUMANISH_ACTOR_VERDICT=<status> HUMANISH_ACTOR_NONCE=<nonce>`, and the nonce is mandatory so a
+ * bare marker (echoed or replayed from untrusted text) can never forge a verdict. Pure (no IO).
+ * Exported so the terminal-product lane scores its in-sandbox `codex exec` run by the same marker;
+ * divergent verdict logic would let the two lanes disagree about what "passed" means.
+ */
+export declare function extractLocalActorVerdict(transcript: string, verdictNonce: string): ActorVerdict | null;
+export {};

package/dist/run/terminal-contract.js

@@ -0,0 +1,47 @@
+// The terminal-product bundle contract shared by its producer (src/routes/terminal/) and verify: the
+// artifact file names, the cost categories, and the local-actor verdict marker. One definition, so
+// the producer and verifier cannot drift.
+import { escapeRegExp } from "./text.js";
+export const TERMINAL_EVENTS_ARTIFACT = "terminal-events.ndjson";
+export const TERMINAL_TRANSCRIPT_ARTIFACT = "terminal-transcript.txt";
+export const TERMINAL_LEDGERS_ARTIFACT = "terminal-ledgers.json";
+/** The four cost categories, in a fixed order so the ledger shape is stable across runs. */
+export const COST_CATEGORIES = [
+    "product",
+    "media",
+    "payment",
+    "provider",
+];
+/**
+ * Strip ANSI/control noise from a captured terminal transcript into stable, scannable text. Pure
+ * (no IO). Exported so the terminal-product lane (src/routes/terminal/live-sandbox.ts) normalizes
+ * its captured exec stream EXACTLY as the local-actor lanes do — the verdict-nonce scorer is only
+ * sound against the same normalization the marker is matched on, so the logic must not diverge.
+ */
+export function normalizeLocalActorTranscript(transcript) {
+    return transcript
+        .replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, "")
+        .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+        .replace(/\x1b[78=>]/g, "")
+        .replace(/\r\n/g, "\n")
+        .replace(/\r/g, "\n")
+        .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "");
+}
+/**
+ * Extract the per-run verdict from a normalized transcript: the agent must print exactly
+ * `HUMANISH_ACTOR_VERDICT=<status> HUMANISH_ACTOR_NONCE=<nonce>`, and the nonce is mandatory so a
+ * bare marker (echoed or replayed from untrusted text) can never forge a verdict. Pure (no IO).
+ * Exported so the terminal-product lane scores its in-sandbox `codex exec` run by the same marker;
+ * divergent verdict logic would let the two lanes disagree about what "passed" means.
+ */
+export function extractLocalActorVerdict(transcript, verdictNonce) {
+    const compactTranscript = transcript.replace(/\s+/g, "");
+    // The per-run nonce is mandatory: a bare HUMANISH_ACTOR_VERDICT=<status>
+    // marker echoed by an actor (or replayed from untrusted text) must never
+    // satisfy verdict extraction.
+    const match = new RegExp(`HUMANISH_ACTOR_VERDICT=(passed|blocked|failed)HUMANISH_ACTOR_NONCE=${escapeRegExp(verdictNonce)}`, "i").exec(compactTranscript);
+    if (!match) {
+        return null;
+    }
+    return match[1]?.toLowerCase();
+}

package/dist/run/text.d.ts

@@ -0,0 +1,2 @@
+/** Escape a literal string for use inside a RegExp source. */
+export declare function escapeRegExp(value: string): string;

package/dist/run/text.js

@@ -0,0 +1,4 @@
+/** Escape a literal string for use inside a RegExp source. */
+export function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

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

@@ -0,0 +1,72 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { escapeRegExp } from "./text.js";
+const scopes = new AsyncLocalStorage();
+const MAX_VALUES = 8192;
+const MAX_BYTES = 1024 * 1024;
+const MAX_VALUE_BYTES = 65_536;
+function usable(scope) {
+    if (scope.closed)
+        throw new Error("TRANSIENT_NARRATION_SCOPE_CLOSED");
+    if (scope.failed)
+        throw new Error("TRANSIENT_NARRATION_SECRET_LIMIT");
+}
+function fail(scope) {
+    scope.failed = true;
+    scope.values.clear();
+    delete scope.pattern;
+    throw new Error("TRANSIENT_NARRATION_SECRET_LIMIT");
+}
+/** Enclose both participant execution and its automatic analysis in one scope. Nested runs isolate too. */
+export async function withTransientCommsSecrets(work) {
+    const scope = { values: new Set(), bytes: 0, closed: false, failed: false };
+    try {
+        return await scopes.run(scope, work);
+    }
+    finally {
+        // Detached work can retain an async context after return. Clear its values and refuse future
+        // scrubbing/registration there; never turn an expired scope into an unprotected analysis.
+        scope.closed = true;
+        scope.values.clear();
+        scope.bytes = 0;
+        delete scope.pattern;
+    }
+}
+export function registerTransientCommsSecrets(values) {
+    const scope = scopes.getStore();
+    if (!scope)
+        return;
+    usable(scope);
+    for (const value of values) {
+        // Values under four characters are ordinary prose (a subject such as "Hi"). Received OTP
+        // extraction starts at four characters; management keys and addresses are longer.
+        if (value.length < 4 || scope.values.has(value))
+            continue;
+        const bytes = Buffer.byteLength(value);
+        if (bytes > MAX_VALUE_BYTES ||
+            scope.values.size >= MAX_VALUES ||
+            scope.bytes + bytes > MAX_BYTES)
+            fail(scope);
+        scope.values.add(value);
+        scope.bytes += bytes;
+        delete scope.pattern;
+    }
+}
+/** Literal, longest-first replacement in one pass; replacement text is never matched recursively. */
+export function scrubTransientCommsText(text) {
+    const scope = scopes.getStore();
+    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, "[REDACTED_SECRET]");
+    }
+    catch {
+        return fail(scope);
+    }
+}

package/dist/run/type-guards.d.ts

@@ -0,0 +1,6 @@
+export declare function isPositiveFiniteNumber(value: unknown): value is number;
+export declare function isFiniteNumber(value: unknown): value is number;
+export declare function isPositiveSafeInteger(value: unknown): value is number;
+export declare function isNonNegativeSafeInteger(value: unknown): value is number;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;

package/dist/run/type-guards.js

@@ -0,0 +1,18 @@
+export function isPositiveFiniteNumber(value) {
+    return isFiniteNumber(value) && value > 0;
+}
+export function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+export function isPositiveSafeInteger(value) {
+    return Number.isSafeInteger(value) && typeof value === "number" && value >= 1;
+}
+export function isNonNegativeSafeInteger(value) {
+    return Number.isSafeInteger(value) && typeof value === "number" && value >= 0;
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}