humanish 0.106.0 → 0.107.0

package/dist/cli/doctor.js

@@ -73,6 +73,9 @@ export async function doctor(cwdInput, options = {}) {
             env,
             agents,
             keyPresent: (name) => probes.some((probe) => probe.name === name && probe.source !== null),
+            ...(options.codexParticipantReadiness === undefined
+                ? {}
+                : { codexParticipantReadiness: options.codexParticipantReadiness }),
         })
         : undefined;
     const checks = [
@@ -158,7 +161,7 @@ async function projectChecks(projectRoot) {
     ];
 }
 /**
- * The optional peer dep every live browser and terminal lane needs (#346). `npx -y humanish` does
+ * The optional peer dep every live browser and terminal route needs (#346). `npx -y humanish` does
  * not pull optional peers, so an adopter's FIRST live run used to fail on it — safely and at $0,
  * but as a burned first impression on the flagship path. Answering it here means the readiness
  * command actually answers readiness.
@@ -250,11 +253,16 @@ function keyChecks(probes, receivingKey, setup, agents) {
             : probe.name === "E2B_API_KEY" ||
                 (probe.name === "OPENAI_API_KEY" &&
                     !agents.some((agent) => agent.authStatus === "authenticated"));
+        // A key the lab is known not to read says so, so a present but unused key does not read as
+        // one the run will use.
+        const unused = setup?.reads !== undefined && !setup.reads.has(probe.name);
         return {
             name: `key ${probe.name}`,
             ok: present || !required,
             message: present
-                ? `supplied by ${probe.source}; presence only, validity not tested`
+                ? unused
+                    ? `present (${probe.source}), not used by this lab`
+                    : `supplied by ${probe.source}; presence only, validity not tested`
                 : required
                     ? `missing from every source — ${hint}`
                     : `not required for ${setup ? "the selected participant route" : "every route"}; ${hint}`,

package/dist/cli/io.d.ts

@@ -18,14 +18,13 @@ export interface LabCommandOptions {
     dryRun?: boolean | undefined;
     envFile?: string | undefined;
     json?: boolean | undefined;
-    lanes?: string | undefined;
     open?: boolean | undefined;
+    participants?: string | undefined;
     port?: string | undefined;
     rerunFailedFrom?: string | undefined;
     runId?: string | undefined;
     /** #316: repo-relative path to an adopter scorer module; overrides review.scorer.ref when set. */
     scorer?: string | undefined;
-    sims?: string | undefined;
     expose?: boolean | undefined;
     tunnel?: "ngrok" | undefined;
     tunnelDomain?: string | undefined;
@@ -59,13 +58,15 @@ export declare function discoverCliKeys(args: {
     cwd: string;
     env?: NodeJS.ProcessEnv;
     onDiscovered?: (names: string[]) => void;
+    /** Announce only the fills of these names; every key is still filled. Undefined announces all. */
+    announced?: ReadonlySet<string>;
 }): Promise<void>;
 export declare function parseLabCount(value: string | undefined, fallback: number): number | null;
 export declare function parseParticipantIds(value: string | undefined): string[];
 export declare function writeResult<T>(command: Command, io: CliIo, result: T, formatHuman: (result: T) => string): void;
-export declare function noteStudyFacts(command: Command, facts: TelemetryProperties): void;
+export declare function noteRunFacts(command: Command, facts: TelemetryProperties): void;
 /** Exported for tests: the facts writeResult read off a command's result document. */
-export declare function studyFactsFor(command: Command): TelemetryProperties;
+export declare function runFactsFor(command: Command): TelemetryProperties;
 export declare function formatRunHuman(result: RunResult): string;
 export declare function parsePositiveInteger(value: string): number | null;
 export declare function parseTimeoutMs(value: string): number | null;

package/dist/cli/io.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { loadEnvFile } from "../keys/env-file.js";
 import { discoverProviderKeys } from "../keys/key-resolution.js";
-import { deriveStudyFacts } from "./telemetry.js";
+import { deriveRunFacts } from "./telemetry.js";
 import { forTerminal } from "../routes/terminal/encoding.js";
 export const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
 function readCliVersion() {
@@ -89,6 +89,7 @@ export async function discoverCliKeys(args) {
             cwd: args.cwd,
             env: args.env ?? process.env,
             announce: (line) => args.io.writeErr(`${line}\n`),
+            ...(args.announced === undefined ? {} : { announced: args.announced }),
         });
         args.onDiscovered?.(discovered.map((fill) => fill.name));
     }
@@ -129,6 +130,9 @@ export function writeResult(command, io, result, formatHuman) {
             const analysis = output.automaticAnalysis;
             if (analysis)
                 io.writeOut(`analysis: ${analysis.state}${analysis.reason ? ` (${analysis.reason})` : ""}\n`);
+            const rejected = analysis?.result?.rejectedOutputPath;
+            if (rejected)
+                io.writeOut(`analysis: ${analysis.result?.error?.code ?? "rejected"}; the rejected output is kept locally at ${rejected}\n`);
             if (defaultAnalysisOverBudget(output))
                 io.writeOut(overBudgetAnalysisHint(output));
         }
@@ -136,17 +140,17 @@ export function writeResult(command, io, result, formatHuman) {
     markInvocationEnvelopeWritten(command);
     // Every backend's result passes through here, so this is where a study's facts get read for
     // telemetry — not in each backend, which is how they went unreported for two releases.
-    noteStudyFacts(command, deriveStudyFacts(result));
+    noteRunFacts(command, deriveRunFacts(result));
 }
-const studyFactsByCommand = new WeakMap();
-export function noteStudyFacts(command, facts) {
+const runFactsByCommand = new WeakMap();
+export function noteRunFacts(command, facts) {
     if (Object.keys(facts).length === 0)
         return;
-    studyFactsByCommand.set(command, { ...studyFactsByCommand.get(command), ...facts });
+    runFactsByCommand.set(command, { ...runFactsByCommand.get(command), ...facts });
 }
 /** Exported for tests: the facts writeResult read off a command's result document. */
-export function studyFactsFor(command) {
-    return { ...studyFactsByCommand.get(command) };
+export function runFactsFor(command) {
+    return { ...runFactsByCommand.get(command) };
 }
 export function formatRunHuman(result) {
     if (!result.ok) {
@@ -155,7 +159,7 @@ export function formatRunHuman(result) {
     return ([
         `humanish run ${result.mode}`,
         `run: ${result.runId}`,
-        ...(result.simCount === undefined ? [] : [`sims: ${result.simCount}`]),
+        ...(result.simCount === undefined ? [] : [`participants: ${result.simCount}`]),
         `bundle: ${result.bundlePath}`,
         `review: ${result.reviewPath}`,
         ...result.warnings.map((warning) => `warning: ${warning}`),

package/dist/cli/program.js

@@ -16,7 +16,7 @@ import { registerCleanupCommand, registerExportCommand, registerReclaimCommand,
 import { registerDoctorCommand, registerInitCommand, registerKeysCommand, registerTelemetryCommand, } from "./commands/setup.js";
 import { defaultTuiRuntime, registerTuiCommand } from "./commands/tui.js";
 import { registerWatchCommand } from "./commands/watch.js";
-import { CLI_RESPONSE_SCHEMA, CLI_VERSION, defaultIo, invocationEnvelopeAlreadyWritten, studyFactsFor, wantsJson, } from "./io.js";
+import { CLI_RESPONSE_SCHEMA, CLI_VERSION, defaultIo, invocationEnvelopeAlreadyWritten, runFactsFor, wantsJson, } from "./io.js";
 // Command boundary catch-all (fix set point 1): every leaf command is created
 // through HumanishCommand.createCommand, and HumanishCommand.action wraps the caller's
 // handler so an uncaught throw or promise rejection can never escape as a raw
@@ -75,7 +75,7 @@ async function recordCommandTelemetry(command, ok, durationMs, exitCode) {
             // result document when it was written; see writeResult. Without them every `run` event
             // looked the same whether it was a dry run or the first live study that ever worked.
             properties: {
-                ...studyFactsFor(command),
+                ...runFactsFor(command),
                 command: name,
                 ok: ok && exitCode === 0,
                 exitCode,
@@ -97,7 +97,7 @@ async function recordCommandTelemetry(command, ok, durationMs, exitCode) {
  * HUMANISH_DEBUG_HANDLES=1: after a command's handler settles, name what is still keeping the
  * process alive (#581). A live terminal run wrote its result 64 s in and the CLI stayed up for
  * sixteen more minutes; nothing in the bundle could say what held it, and an in-process probe of
- * the lane found nothing of ours. This is the one line that answers it next time: the resource
+ * the run found nothing of ours. This is the one line that answers it next time: the resource
  * types Node reports, once, to stderr, after one macrotask so settled work has cleared.
  */
 function reportActiveHandles(command, io) {

package/dist/cli/renamed-options.d.ts

@@ -0,0 +1,11 @@
+import type { CliIo } from "./io.js";
+/** `--participants`, or `--lanes` when only the older spelling is set. */
+export declare function participantsOption(io: CliIo, options: {
+    participants?: string | undefined;
+    lanes?: string | undefined;
+}): string | undefined;
+/** `--count`, or `--sims` when only the older spelling is set. */
+export declare function countOption(io: CliIo, options: {
+    count?: string | undefined;
+    sims?: string | undefined;
+}): string | undefined;

package/dist/cli/renamed-options.js

@@ -0,0 +1,18 @@
+// Options renamed in this minor keep their older name for one more minor, so a skill installed
+// before the rename still runs. The older name is hidden from --help, sets the same value and
+// prints one stderr line naming the new name. Each command reads its options through these
+// functions once, at the top of its action, so one invocation prints the line once.
+function renamedOption(io, name, value, olderName, olderValue) {
+    if (olderValue !== undefined) {
+        io.writeErr(`warning: --${olderName} is deprecated and is removed in the next minor. Use --${name}.\n`);
+    }
+    return value ?? olderValue;
+}
+/** `--participants`, or `--lanes` when only the older spelling is set. */
+export function participantsOption(io, options) {
+    return renamedOption(io, "participants", options.participants, "lanes", options.lanes);
+}
+/** `--count`, or `--sims` when only the older spelling is set. */
+export function countOption(io, options) {
+    return renamedOption(io, "count", options.count, "sims", options.sims);
+}

package/dist/cli/telemetry.d.ts

@@ -15,7 +15,7 @@ export interface TelemetryProperties {
     /** One of humanish's OWN error codes (`HUMANISH_*`), never a message. Which failure ends a
      *  first run is the question the funnel exists to answer. */
     errorCode?: string;
-    /** Finite result categories and recorded stop causes; never raw errors or lane details. */
+    /** Finite result categories and recorded stop causes; never raw errors or participant details. */
     diagnosticCategory?: string;
     stopCause?: string;
 }
@@ -87,7 +87,7 @@ export declare function buildPayload(args: {
  * or an outcome — the vocabulary existed, nothing populated it — so the one question telemetry
  * was added to answer ("does anyone get to a working LIVE first run") had no answer in the data.
  */
-export declare function deriveStudyFacts(result: unknown): TelemetryProperties;
+export declare function deriveRunFacts(result: unknown): TelemetryProperties;
 /** The notice, shown once, before anything is sent. */
 export declare const TELEMETRY_NOTICE: string;
 export interface SendDeps {

package/dist/cli/telemetry.js

@@ -241,7 +241,7 @@ function asRecord(value) {
  * or an outcome — the vocabulary existed, nothing populated it — so the one question telemetry
  * was added to answer ("does anyone get to a working LIVE first run") had no answer in the data.
  */
-export function deriveStudyFacts(result) {
+export function deriveRunFacts(result) {
     const r = asRecord(result);
     if (!r)
         return {};

package/dist/comms/capture-surface.d.ts

@@ -1,7 +1,7 @@
 import type { ReceivingSurfaceFile } from "./receiving-types.js";
 import type { CommsMessage } from "./types.js";
 /** [fromOrigin, toOrigin] pairs: rewrite a link/href whose origin is the app's in-sandbox origin into a
- *  lane-reachable origin, so the persona's browser can actually follow the verify link when it clicks. */
+ *  participant-reachable origin, so the persona's browser can actually follow the verify link when it clicks. */
 export type OriginMap = Array<[string, string]>;
 export interface InboxRenderOptions {
     originMap?: OriginMap;

package/dist/comms/catch-host.d.ts

@@ -10,7 +10,7 @@ export interface CommsCatchHostOptions {
     /** Bearer token required on GET /deliveries. Strongly recommended when the host is reachable. */
     token?: string;
     /** SECOND port for the READ-ONLY inbox listener bound to 0.0.0.0, so a persona on another machine
-     *  (or in a per-lane desktop) can reach the inbox. Omit to stay loopback-only. */
+     *  (or on a participant's desktop) can reach the inbox. Omit to stay loopback-only. */
     inboxPort?: number;
     /** Optional loopback SMTP listener sharing the HTTP capture and inbox pipeline. */
     smtpPort?: number;

package/dist/comms/connections.js

@@ -4,10 +4,10 @@ import path from "node:path";
 import { parse, stringify } from "yaml";
 import { COMMS_PROVIDERS, DEFAULT_COMMS_PROVIDER, isReceivingProviderId, } from "./providers.js";
 import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, prepareManagedHumanishOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
+import { isRecord } from "../run/type-guards.js";
 const COMMS_CONNECTIONS_SCHEMA = "humanish.comms-connections.v1";
 export const COMMS_CONFIG_PATH = ".humanish/local/comms.yaml";
 export { COMMS_PROVIDERS };
-const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const validName = (name) => /^[a-z][a-z0-9-]{0,47}$/.test(name) && name !== "constructor" && name !== "prototype";
 const empty = () => ({ schema: COMMS_CONNECTIONS_SCHEMA, connections: {} });
 async function exists(file) {
@@ -22,16 +22,16 @@ async function exists(file) {
     }
 }
 function parseConnections(raw) {
-    if (!record(raw) ||
+    if (!isRecord(raw) ||
         raw.schema !== COMMS_CONNECTIONS_SCHEMA ||
-        !record(raw.connections) ||
+        !isRecord(raw.connections) ||
         Object.keys(raw).some((key) => key !== "schema" && key !== "connections") ||
         Object.keys(raw.connections).length > 32)
         throw new Error("Invalid connection configuration.");
     const connections = {};
     for (const [name, value] of Object.entries(raw.connections)) {
         if (!validName(name) ||
-            !record(value) ||
+            !isRecord(value) ||
             !isReceivingProviderId(value.provider) ||
             typeof value.apiKeyEnv !== "string" ||
             !/^[A-Z][A-Z0-9_]{0,99}$/.test(value.apiKeyEnv) ||

package/dist/comms/external-evidence.d.ts

@@ -0,0 +1,27 @@
+import type { LabCommsEmail, LabCommsExternal } from "../lab/types.js";
+import type { PreparedRunArtifactPaths } from "../run/paths.js";
+/**
+ * Why a catch token cannot be used, or undefined when it can. An unset or empty token is none. A
+ * token that is not well-formed Unicode cannot be sent as a header or encoded as a URL, so it is
+ * refused with the short ones.
+ */
+export declare function catchTokenRefusal(token: string | undefined): string | undefined;
+/** The catch token the run sends: the value of `authTokenEnv`, when the lab names one. */
+export declare function catchTokenOf(external: LabCommsExternal, env: Record<string, string | undefined>): string | undefined;
+/**
+ * Drains the catch, routes its sends to the declared recipients' inboxes and writes the thread to
+ * `comms/thread.json`. Returns that path when a message matched, and the warnings to add to the
+ * run, each scrubbed of the run's known secret values and the catch token, then redacted. It never
+ * throws: the run continues without comms evidence.
+ */
+export declare function collectExternalCommsEvidence(args: {
+    external: LabCommsExternal;
+    email: LabCommsEmail;
+    env: Record<string, string | undefined>;
+    runPaths: PreparedRunArtifactPaths;
+    /** The run's known secret values. The route may add to it until the drain runs. */
+    knownSecretValues: readonly string[];
+}): Promise<{
+    path?: string;
+    warnings: string[];
+}>;

package/dist/comms/external-evidence.js

@@ -0,0 +1,93 @@
+// An adopter-hosted catch's thread, collected into a run. The computer-use and shared-world routes
+// both call this, so every warning it returns is scrubbed the same way on both: an error or the
+// catch URL can carry the catch's bearer token or a provisioned value, and neither has a secret's
+// shape for pattern redaction to find.
+import { redactText, toErrorMessage } from "../evidence/redaction.js";
+import { scrubSecretValues } from "../evidence/secret-scrub.js";
+import { addressedRecipients } from "../lab/parse/comms.js";
+import { writeContainedOutputFile } from "../run/contained-output.js";
+import { FakeInbox } from "./fake-inbox.js";
+import { collectExternalCommsThread } from "./sandbox-catch.js";
+/**
+ * The shortest catch bearer token humanish uses. The token guards GET /deliveries on a host the run
+ * reaches over the network, so it must not be guessable: 16 random base64 characters are 96 bits.
+ * The run also scrubs the token from every warning as a literal, and a short token would scrub
+ * ordinary words.
+ */
+const MIN_CATCH_TOKEN_LENGTH = 16;
+/** String.prototype.isWellFormed (ES2024, Node 20+); the ES2023 lib types do not declare it. */
+function isWellFormed(value) {
+    return value.isWellFormed();
+}
+/**
+ * Why a catch token cannot be used, or undefined when it can. An unset or empty token is none. A
+ * token that is not well-formed Unicode cannot be sent as a header or encoded as a URL, so it is
+ * refused with the short ones.
+ */
+export function catchTokenRefusal(token) {
+    if (token === undefined || token.length === 0)
+        return undefined;
+    if (!isWellFormed(token))
+        return "The comms catch token is not well-formed Unicode; use printable ASCII, such as the output of `openssl rand -hex 16`, on the catch and in the run.";
+    if (token.length >= MIN_CATCH_TOKEN_LENGTH)
+        return undefined;
+    return `The comms catch token is ${token.length} characters; it must be at least ${MIN_CATCH_TOKEN_LENGTH}, such as the output of \`openssl rand -hex 16\`, on the catch and in the run.`;
+}
+/** The catch token the run sends: the value of `authTokenEnv`, when the lab names one. */
+export function catchTokenOf(external, env) {
+    return external.authTokenEnv === undefined ? undefined : env[external.authTokenEnv];
+}
+/**
+ * Drains the catch, routes its sends to the declared recipients' inboxes and writes the thread to
+ * `comms/thread.json`. Returns that path when a message matched, and the warnings to add to the
+ * run, each scrubbed of the run's known secret values and the catch token, then redacted. It never
+ * throws: the run continues without comms evidence.
+ */
+export async function collectExternalCommsEvidence(args) {
+    const { external, email, env, runPaths, knownSecretValues } = args;
+    const authToken = catchTokenOf(external, env);
+    // Pattern redaction alone until the literal scrub exists, so a warning built in the catch below
+    // is never unredacted. The scrub is built inside the try, where a failure becomes that warning.
+    let scrubbed = (warnings) => warnings.map(redactText);
+    try {
+        const scrub = scrubSecretValues([
+            ...knownSecretValues,
+            ...(authToken === undefined ? [] : [authToken]),
+        ]);
+        scrubbed = (warnings) => warnings.map((warning) => redactText(scrub(warning)));
+        const channel = new FakeInbox();
+        const inboxes = [];
+        for (const recipient of addressedRecipients(email)) {
+            inboxes.push(await channel.provisionAddress(recipient.participantId, recipient.address));
+        }
+        const collected = await collectExternalCommsThread({
+            external: { ...external, ...(authToken === undefined ? {} : { authToken }) },
+            channel,
+            inboxes,
+        });
+        if (collected.artifact) {
+            const path = "comms/thread.json";
+            await writeContainedOutputFile(runPaths, path, `${JSON.stringify(collected.artifact, null, 2)}\n`, "utf8");
+            return { path, warnings: [] };
+        }
+        if (collected.captured > 0) {
+            return {
+                warnings: scrubbed([
+                    `Comms catch captured ${collected.captured} email send(s) but none matched a declared recipient inbox — no comms evidence written. Declare comms.email.recipients[].address to match the address the app sends to.`,
+                ]),
+            };
+        }
+        return {
+            warnings: scrubbed([
+                `Comms catch captured ZERO email sends — your app never delivered mail through the catch at ${external.catchBaseUrl}. Verify the app's email-API base URL points at it and that the flow reached an email step.`,
+            ]),
+        };
+    }
+    catch (error) {
+        return {
+            warnings: scrubbed([
+                `Comms evidence collection failed against the adopter-hosted catch (run continues): ${String(toErrorMessage(error))}`,
+            ]),
+        };
+    }
+}

package/dist/comms/lease-store.js

@@ -4,6 +4,7 @@ import { constants } from "node:fs";
 import { lstat, mkdir, open, readdir, realpath, rename, unlink } from "node:fs/promises";
 import { homedir, hostname } from "node:os";
 import path from "node:path";
+import { isRecord } from "../run/type-guards.js";
 import { isReceivingProviderId } from "./providers.js";
 const SCHEMA = "humanish.comms-lease-journal.v1";
 const MAX_BYTES = 1_048_576;
@@ -30,7 +31,6 @@ function fail(code = "authority_unavailable") {
 }
 const digest = (value) => createHash("sha256").update(value).digest("hex");
 const clone = (value) => structuredClone(value);
-const plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const safeString = (value, max = 512) => typeof value === "string" &&
     value.length > 0 &&
     value.length <= max &&
@@ -45,14 +45,14 @@ export function sameReceivingIdentity(a, b) {
         a.scopeId === b.scopeId);
 }
 export function validReceivingIdentity(value) {
-    return (plain(value) &&
+    return (isRecord(value) &&
         isReceivingProviderId(value.provider) &&
         safeString(value.accountId) &&
         ["organization", "pod", "inbox"].includes(String(value.scopeType)) &&
         safeString(value.scopeId));
 }
 export function validReceivingLease(value, clientId) {
-    return (plain(value) &&
+    return (isRecord(value) &&
         value.clientId === clientId &&
         safeString(value.resourceId) &&
         safeString(value.address, 320) &&
@@ -79,7 +79,7 @@ function ownerLiveness(owner) {
     }
 }
 function validateOwner(value) {
-    return (plain(value) &&
+    return (isRecord(value) &&
         Number.isSafeInteger(value.pid) &&
         value.pid > 0 &&
         safeString(value.host) &&
@@ -95,9 +95,9 @@ function parseJournal(text) {
     catch {
         return fail();
     }
-    if (!plain(value) ||
+    if (!isRecord(value) ||
         value.schema !== SCHEMA ||
-        !plain(value.project) ||
+        !isRecord(value.project) ||
         !safeString(value.project.path, 4096) ||
         !path.isAbsolute(value.project.path) ||
         !Number.isSafeInteger(value.project.dev) ||
@@ -123,7 +123,7 @@ function parseJournal(text) {
     const leaseIds = new Set();
     const resources = new Set();
     for (const item of value.leases) {
-        if (!plain(item) ||
+        if (!isRecord(item) ||
             typeof item.participantId !== "string" ||
             !LOCAL_ID.test(item.participantId) ||
             participants.has(item.participantId) ||

package/dist/comms/types.js

@@ -1,5 +1,5 @@
 // The addressed message bus for captured mail (#297): the email or SMS a persona receives off the
-// app, as a testable surface. One port, addressed by lane, so the inbox surface and the evidence
+// app, as a testable surface. One port, addressed by participant, so the inbox surface and the evidence
 // writer read messages without knowing how they were captured.
 //
 // PUBLIC-SAFETY: raw address values, message bodies, links, and codes are RUNTIME-ONLY. Only the

package/dist/evidence/browser-hygiene.d.ts

@@ -1,7 +1,7 @@
 /**
  * Browser chrome that belongs to the host environment (update prompts, password
  * save bubbles, first-run UI) pollutes product evidence. Keep these knobs in one
- * place so browser-backed lanes can prefer product pixels over browser UI.
+ * place so browser-backed routes can prefer product pixels over browser UI.
  */
 export declare const CHROMIUM_EVIDENCE_HYGIENE_FLAGS: readonly ["--disable-background-networking", "--disable-component-update", "--disable-default-apps", "--disable-domain-reliability", "--disable-extensions", "--disable-sync", "--no-default-browser-check", "--no-first-run", "--password-store=basic", "--use-mock-keychain"];
 export declare function chromiumEvidenceProfilePreferencesJson(): string;

package/dist/evidence/browser-hygiene.js

@@ -1,7 +1,7 @@
 /**
  * Browser chrome that belongs to the host environment (update prompts, password
  * save bubbles, first-run UI) pollutes product evidence. Keep these knobs in one
- * place so browser-backed lanes can prefer product pixels over browser UI.
+ * place so browser-backed routes can prefer product pixels over browser UI.
  */
 export const CHROMIUM_EVIDENCE_HYGIENE_FLAGS = [
     "--disable-background-networking",

package/dist/evidence/redaction.js

@@ -101,7 +101,7 @@ export function publicPathForTrace(value, rootCwd) {
 // ---------------------------------------------------------------------------
 // Screenshot redaction.
 //
-// Computer-use lanes capture raw desktop frames that can contain secrets, PII,
+// Computer-use participants capture raw desktop frames that can contain secrets, PII,
 // or a logged-in third-party UI. A raw frame must never reach a public artifact.
 // redactScreenshot is the fail-closed primitive that gates that surface. It
 // always returns a freshly re-encoded, downscaled, box-blurred thumbnail (or a

package/dist/evidence/secret-scrub.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A scrub that replaces each non-empty value and its encoded forms with `[REDACTED_SECRET]`. Every
+ * occurrence of every form is found on its own, and overlapping finds are merged into one span, so
+ * a value that overlaps another is removed whole wherever each starts. The scrub reads the text
+ * through decodeEscapes, the decoder verify uses, and returns the decoded text: a warning with
+ * percent-encoding, JSON escapes or HTML references shows them decoded, with the values removed.
+ * That finds a value written partly encoded, which no single encoded form matches.
+ */
+export declare function scrubSecretValues(values: readonly string[]): (text: string) => string;

package/dist/evidence/secret-scrub.js

@@ -0,0 +1,96 @@
+// Literal scrubbing of secret values from text that leaves the host, such as an error quoted in a
+// run's warnings. A value is found as written and in the encoded forms an HTTP client, a log line or
+// a JSON body gives it, so a token that reaches the text percent-encoded or base64-encoded is still
+// removed. Pattern redaction (redactText) runs after this and finds secrets by shape.
+import { decodeEscapes } from "./encoded-text.js";
+const REDACTED = "[REDACTED_SECRET]";
+// A marker already in the text, from this scrub or from redactText. No value is matched inside one.
+const MARKER = /\[REDACTED_[A-Z0-9_]+\]/g;
+// The shortest encoded form searched for. Shorter base64 or hex runs are ordinary text often enough
+// that matching them would redact words. A value itself is searched for at any length.
+const MIN_ENCODED_FORM = 8;
+/**
+ * The characters of a value's base64 encoding that do not depend on its neighbours, with 0, 1 or
+ * 2 bytes before it. A prefix byte shares the next character with the value, and so does the byte
+ * after a partial last group, so those characters are dropped.
+ */
+function base64Middles(bytes, encoding) {
+    return [0, 1, 2].map((offset) => {
+        const encoded = Buffer.concat([Buffer.alloc(offset), bytes])
+            .toString(encoding)
+            .replace(/=+$/, "");
+        const total = offset + bytes.length;
+        const start = offset === 0 ? 0 : offset + 1;
+        const end = Math.floor(total / 3) * 4 + (total % 3);
+        return encoded.slice(start, end);
+    });
+}
+/** A value as written, and percent-encoded, JSON-escaped, base64 at each byte offset, base64url and hex. */
+function encodedForms(value) {
+    const bytes = Buffer.from(value, "utf8");
+    const encoded = [
+        JSON.stringify(value).slice(1, -1),
+        bytes.toString("base64"),
+        bytes.toString("base64url"),
+        bytes.toString("hex"),
+        ...base64Middles(bytes, "base64"),
+        ...base64Middles(bytes, "base64url"),
+    ];
+    // encodeURIComponent throws on a lone surrogate. Such a value is still found as written.
+    try {
+        encoded.push(encodeURIComponent(value));
+    }
+    catch {
+        // no percent-encoded form
+    }
+    return [value, ...encoded.filter((form) => form.length >= MIN_ENCODED_FORM)];
+}
+/** Every occurrence of every form, outside the markers, merged where they overlap or touch. */
+function secretSpans(text, forms) {
+    const markers = [];
+    for (const match of text.matchAll(MARKER)) {
+        const start = match.index ?? 0;
+        markers.push([start, start + match[0].length]);
+    }
+    const spans = [];
+    for (const form of forms) {
+        for (let at = text.indexOf(form); at !== -1; at = text.indexOf(form, at + 1)) {
+            const end = at + form.length;
+            if (!markers.some(([start, stop]) => at < stop && end > start))
+                spans.push([at, end]);
+        }
+    }
+    spans.sort((left, right) => left[0] - right[0]);
+    const merged = [];
+    for (const span of spans) {
+        const last = merged.at(-1);
+        if (last !== undefined && span[0] <= last[1])
+            last[1] = Math.max(last[1], span[1]);
+        else
+            merged.push([span[0], span[1]]);
+    }
+    return merged;
+}
+/**
+ * A scrub that replaces each non-empty value and its encoded forms with `[REDACTED_SECRET]`. Every
+ * occurrence of every form is found on its own, and overlapping finds are merged into one span, so
+ * a value that overlaps another is removed whole wherever each starts. The scrub reads the text
+ * through decodeEscapes, the decoder verify uses, and returns the decoded text: a warning with
+ * percent-encoding, JSON escapes or HTML references shows them decoded, with the values removed.
+ * That finds a value written partly encoded, which no single encoded form matches.
+ */
+export function scrubSecretValues(values) {
+    const forms = [...new Set(values.filter((value) => value.length > 0).flatMap(encodedForms))];
+    if (forms.length === 0)
+        return (text) => text;
+    return (text) => {
+        const decoded = decodeEscapes(text);
+        let result = "";
+        let cursor = 0;
+        for (const [start, end] of secretSpans(decoded, forms)) {
+            result += decoded.slice(cursor, start) + REDACTED;
+            cursor = end;
+        }
+        return result + decoded.slice(cursor);
+    };
+}