humanish 0.113.0 → 0.115.0

package/dist/cli/telemetry.js

@@ -12,9 +12,9 @@
 import { isCuaDiagnosticCategory, isCuaDiagnosticStopCause, } from "../routes/computer-use/diagnostics.js";
 import { randomUUID } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import path from "node:path";
 import { STUDY_RESULT_SCHEMA } from "../run/study-result.js";
+import { envFlag, humanishConfigFile } from "./user-config.js";
 /** Write-only PostHog project key. Public by design: it can ingest, and can read nothing. */
 const INGEST_KEY = "phc_oeMeBqxDZhZ9tCHMSnuDFimLqHpU5Myc847WD33hAh4C";
 const INGEST_HOST = "https://us.i.posthog.com";
@@ -26,26 +26,16 @@ const STARTER_STUDIES = new Set([
     "local-browser",
     "lobby-trivia-3player",
 ]);
-export function telemetryStatePath(env = process.env, home = homedir()) {
-    const declared = env.XDG_CONFIG_HOME?.trim();
-    // Same XDG rule the key store uses: a relative value must be ignored, or state becomes
-    // cwd-relative and follows people between projects.
-    const configHome = declared !== undefined && declared !== "" && path.isAbsolute(declared)
-        ? declared
-        : path.join(home, ".config");
-    return path.join(configHome, "humanish", "telemetry.json");
+export function telemetryStatePath(env = process.env, home) {
+    return humanishConfigFile(env, "telemetry.json", home);
 }
 /**
  * Off means off, from any of the three switches people already expect: the cross-tool
  * `DO_NOT_TRACK` standard, our own env var, and the persisted opt-out.
  */
 export function disabledByEnvironment(env) {
-    const truthy = (value) => value !== undefined &&
-        value.trim() !== "" &&
-        value.trim() !== "0" &&
-        value.trim().toLowerCase() !== "false";
-    return (truthy(env.DO_NOT_TRACK) ||
-        truthy(env.HUMANISH_TELEMETRY_DISABLED) ||
+    return (envFlag(env.DO_NOT_TRACK) ||
+        envFlag(env.HUMANISH_TELEMETRY_DISABLED) ||
         // Our own development and test runs must never reach the adoption dataset. In the first two
         // days after telemetry shipped, 82% of events (4,042 of 4,932, from 49 of 59 anonymous ids)
         // came from humanish's own CI and suite: ~50 ids each running nearly every subcommand about
@@ -55,7 +45,7 @@ export function disabledByEnvironment(env) {
         // Deliberately not keyed on CI. An adopter running humanish in their pipeline is real usage
         // and stays countable; the `ci` property already separates it, which is what Next.js does.
         // This keys on being inside the humanish source tree, which only we ever are.
-        truthy(env.HUMANISH_DEV));
+        envFlag(env.HUMANISH_DEV));
 }
 /**
  * True when this process is running from a humanish source checkout rather than an install.
@@ -101,7 +91,7 @@ export function inHumanishCheckout(startDir, readFileSyncFn) {
 export function isOwnCheckoutRun(cwd, cliDir, readFileSyncFn) {
     return inHumanishCheckout(cwd, readFileSyncFn) || inHumanishCheckout(cliDir, readFileSyncFn);
 }
-export async function readTelemetryState(env = process.env, home = homedir()) {
+export async function readTelemetryState(env = process.env, home) {
     try {
         const raw = await readFile(telemetryStatePath(env, home), "utf8");
         const parsed = JSON.parse(raw);
@@ -115,7 +105,7 @@ export async function readTelemetryState(env = process.env, home = homedir()) {
         return { enabled: true, anonymousId: randomUUID(), noticed: false };
     }
 }
-export async function writeTelemetryState(state, env = process.env, home = homedir()) {
+export async function writeTelemetryState(state, env = process.env, home) {
     const file = telemetryStatePath(env, home);
     await mkdir(path.dirname(file), { recursive: true });
     await writeFile(file, `${JSON.stringify(state, null, 2)}\n`, "utf8");
@@ -162,15 +152,13 @@ export function buildPayload(args) {
         version: args.version,
         os: args.platform ?? process.platform,
         node: (args.nodeVersion ?? process.version).split(".")[0].replace("v", ""),
-        ci: env.CI !== undefined && env.CI !== "" && env.CI !== "0",
+        ci: envFlag(env.CI),
         // A humanish study participant is a real cold install on a machine we do not own, so it emits
         // like any other new adopter and is indistinguishable from one. It is also the exact
         // population we are trying to count, so a busy self-study day reads as an adoption spike.
         // Stamped rather than suppressed, the same shape as `ci`: participant runs stay visible and
         // stay separable, and we keep a genuine measurement of what a cold install does.
-        studyParticipant: env.HUMANISH_STUDY_PARTICIPANT !== undefined &&
-            env.HUMANISH_STUDY_PARTICIPANT !== "" &&
-            env.HUMANISH_STUDY_PARTICIPANT !== "0",
+        studyParticipant: envFlag(env.HUMANISH_STUDY_PARTICIPANT),
     };
     const given = args.properties ?? {};
     if (given.command !== undefined)

package/dist/cli/update-check.js

@@ -4,20 +4,12 @@
 // the command that started it.
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { disabledByEnvironment } from "./telemetry.js";
+import { envFlag, humanishConfigFile } from "./user-config.js";
 const DAY_MS = 24 * 60 * 60 * 1000;
 const REGISTRY_DIST_TAGS = "https://registry.npmjs.org/-/package/humanish/dist-tags";
-/** Next to telemetry.json, under the same XDG rule the key store uses. */
-function updateCachePath(env, home = homedir()) {
-    const declared = env.XDG_CONFIG_HOME?.trim();
-    const configHome = declared !== undefined && declared !== "" && path.isAbsolute(declared)
-        ? declared
-        : path.join(home, ".config");
-    return path.join(configHome, "humanish", "update-check.json");
-}
 function readUpdateCache(cachePath) {
     try {
         const parsed = JSON.parse(readFileSync(cachePath, "utf8"));
@@ -65,10 +57,6 @@ function dayPassed(timestamp, now) {
     const then = timestamp === undefined ? Number.NaN : Date.parse(timestamp);
     return Number.isNaN(then) || now - then >= DAY_MS;
 }
-const truthy = (value) => value !== undefined &&
-    value.trim() !== "" &&
-    value.trim() !== "0" &&
-    value.trim().toLowerCase() !== "false";
 /**
  * Only a person at a terminal is told, and only when nothing has switched the check off. A pipe,
  * CI and a JSON document have a program reading them. A study participant runs the version the
@@ -80,9 +68,9 @@ function checkAllowed(context) {
     return (context.terminal &&
         !context.json &&
         !context.ownCheckout &&
-        !truthy(env.CI) &&
-        !truthy(env.HUMANISH_NO_UPDATE_CHECK) &&
-        !truthy(env.HUMANISH_STUDY_PARTICIPANT) &&
+        !envFlag(env.CI) &&
+        !envFlag(env.HUMANISH_NO_UPDATE_CHECK) &&
+        !envFlag(env.HUMANISH_STUDY_PARTICIPANT) &&
         !disabledByEnvironment(env));
 }
 /**
@@ -94,7 +82,7 @@ export function checkForUpdate(context) {
     try {
         if (!checkAllowed(context))
             return undefined;
-        const cachePath = updateCachePath(context.env, context.home);
+        const cachePath = humanishConfigFile(context.env, "update-check.json", context.home);
         const cache = readUpdateCache(cachePath);
         const stamp = new Date(context.now).toISOString();
         const next = { ...cache };
@@ -126,7 +114,7 @@ export function checkForUpdate(context) {
  * cache only; undefined until a check has succeeded on this machine.
  */
 export function recordedVersion(installed, env, home) {
-    const cache = readUpdateCache(updateCachePath(env, home));
+    const cache = readUpdateCache(humanishConfigFile(env, "update-check.json", home));
     if (cache.latest === undefined)
         return undefined;
     const checked = cache.checkedAt === undefined ? "" : ` (checked ${cache.checkedAt.slice(0, 10)})`;

package/dist/cli/user-config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `$XDG_CONFIG_HOME/humanish/<fileName>`, or `<home>/.config/humanish/<fileName>`. The XDG spec
+ * says to ignore a relative XDG_CONFIG_HOME. Honoring one would put the file in whichever project
+ * is open, and for the key store that writes a secret into the repo.
+ */
+export declare function humanishConfigFile(env: NodeJS.ProcessEnv, fileName: string, home?: string): string;
+/**
+ * Whether a flag variable such as `CI` or `DO_NOT_TRACK` is on. Unset, blank, `0` and `false` (any
+ * case, surrounding spaces ignored) are off, as is-in-ci reads `CI`; any other value is on.
+ */
+export declare function envFlag(value: string | undefined): boolean;

package/dist/cli/user-config.js

@@ -0,0 +1,25 @@
+// Where humanish keeps per-user files (the key store, telemetry state, the update-check cache) and
+// how it reads an on/off environment variable. The key store, telemetry and the update check each
+// had their own copy of both.
+import { homedir } from "node:os";
+import path from "node:path";
+/**
+ * `$XDG_CONFIG_HOME/humanish/<fileName>`, or `<home>/.config/humanish/<fileName>`. The XDG spec
+ * says to ignore a relative XDG_CONFIG_HOME. Honoring one would put the file in whichever project
+ * is open, and for the key store that writes a secret into the repo.
+ */
+export function humanishConfigFile(env, fileName, home = homedir()) {
+    const declared = env.XDG_CONFIG_HOME?.trim();
+    const configHome = declared !== undefined && declared !== "" && path.isAbsolute(declared)
+        ? declared
+        : path.join(home, ".config");
+    return path.join(configHome, "humanish", fileName);
+}
+/**
+ * Whether a flag variable such as `CI` or `DO_NOT_TRACK` is on. Unset, blank, `0` and `false` (any
+ * case, surrounding spaces ignored) are off, as is-in-ci reads `CI`; any other value is on.
+ */
+export function envFlag(value) {
+    const trimmed = value?.trim() ?? "";
+    return trimmed !== "" && trimmed !== "0" && trimmed.toLowerCase() !== "false";
+}

package/dist/comms/email-catch.js

@@ -9,6 +9,7 @@
 //
 // 127.0.0.1 only; request bodies are never logged; request size is capped.
 import { createServer } from "node:http";
+import { readBodyAtMost } from "../observer/http.js";
 import { capturedInlineImages } from "./images.js";
 // ---------------------------------------------------------------- shared parse helpers
 function str(value) {
@@ -116,26 +117,6 @@ export const DEFAULT_EMAIL_PROFILES = [
     sendgridEmailProfile,
 ];
 // ---------------------------------------------------------------- server
-class BodyTooLargeError extends Error {
-}
-function readBody(req, limit) {
-    return new Promise((resolve, reject) => {
-        let size = 0;
-        const chunks = [];
-        req.on("data", (chunk) => {
-            size += chunk.length;
-            if (size > limit) {
-                // Reject without destroying the socket here: the handler responds 413 cleanly first (a
-                // write-after-destroy would otherwise reset the connection), then tears the request down.
-                reject(new BodyTooLargeError("request body too large"));
-                return;
-            }
-            chunks.push(chunk);
-        });
-        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
-        req.on("error", reject);
-    });
-}
 const MAX_BODY_BYTES = 5 * 1024 * 1024;
 /**
  * Start the vendor-neutral email catch, routing accepted sends into `channel`. Returns the loopback
@@ -170,21 +151,16 @@ export async function startEmailCatchServer(channel, options = {}) {
             respondJson(res, 404, { error: "not found" });
             return;
         }
-        let raw;
-        try {
-            raw = await readBody(req, MAX_BODY_BYTES);
-        }
-        catch (error) {
-            if (!res.headersSent)
-                respondJson(res, error instanceof BodyTooLargeError ? 413 : 400, {
-                    error: "request body could not be read",
-                });
-            req.destroy();
+        const body = await readBodyAtMost(req, MAX_BODY_BYTES).catch(() => undefined);
+        if (body === null || body === undefined) {
+            // The rest of the body is never read, so the connection closes after this answer.
+            res.setHeader("connection", "close");
+            respondJson(res, body === null ? 413 : 400, { error: "request body could not be read" });
             return;
         }
         let parsed;
         try {
-            parsed = JSON.parse(raw.length > 0 ? raw : "{}");
+            parsed = JSON.parse(body.length > 0 ? body.toString("utf8") : "{}");
         }
         catch {
             respondJson(res, 422, { error: "invalid JSON body" });

package/dist/evidence/encoded-text.d.ts

@@ -1,5 +1,19 @@
-/** Undoes JSON and JS escapes, percent-encoding and HTML character references, one pass each. */
+/** Each run of characters U+0080 to U+00FF read as the UTF-8 bytes they may be: é as é. */
+export declare const latin1RunsAsUtf8: (text: string) => string;
+/**
+ * Undoes JSON and JS escapes, percent-encoding and HTML character references, one pass each. Each
+ * percent escape is one character, the byte's code, so `caf%C3%A9` reads as `café`; readingsOf
+ * also gives the reading as UTF-8, `café`.
+ */
 export declare function decodeEscapes(text: string): string;
+/**
+ * Every reading of the text a scan matches, each once: as written, decodeEscapes, with percent
+ * escapes read as UTF-8, decodeEscapes with transfer escapes expanded, and the text as written and
+ * decoded with each run of U+0080 to U+00FF characters read as UTF-8 bytes, which undoes text that
+ * a reader already decoded one byte per character. Either percent reading can split a value that
+ * the other keeps whole, as `%E2%80%80` (U+2000, a space, in UTF-8) does.
+ */
+export declare function readingsOf(text: string): string[];
 /** How scanEncodedText reads text. */
 export interface EncodedTextScanOptions {
     /** Do not count an encoded binary run as opaque. */
@@ -14,8 +28,8 @@ export interface EncodedTextScan {
     readonly opaque: boolean;
 }
 /**
- * Scans text for secrets as written, after decodeEscapes and transfer escapes, and inside each
- * base64 (standard, URL-safe or line-wrapped) and hex run. A run that decodes to text is scanned in
+ * Scans text for secrets in each of its readingsOf, and inside each base64 (standard, URL-safe or
+ * line-wrapped) and hex run. A run that decodes to text is scanned in
  * turn. A run that decodes to an archive, or to other binary past MIN_OPAQUE_BASE64_RUN characters,
  * is opaque unless the caller allows opaque runs.
  */

package/dist/evidence/encoded-text.js

@@ -2,58 +2,138 @@
 // undoes the encodings a reader undoes for free (JSON and JS escapes, percent-encoding, HTML
 // entities) and looks inside base64 runs. verify and bundle export share decodeEscapes, so they
 // judge the same decoded text.
+import { isUtf8 } from "node:buffer";
 import { createHash } from "node:crypto";
 import { readPlainText } from "./plain-text.js";
 import { containsSensitive } from "./redaction.js";
 // HTML5 named references that stand for printable ASCII. Letters and digits have only numeric
 // references, which decodeEscapes handles.
-const ASCII_ENTITIES = {
-    amp: "&",
-    apos: "'",
-    ast: "*",
-    bsol: "\\",
-    colon: ":",
-    comma: ",",
-    commat: "@",
-    dollar: "$",
-    equals: "=",
-    excl: "!",
-    grave: "`",
-    gt: ">",
-    hat: "^",
-    lcub: "{",
-    lowbar: "_",
-    lpar: "(",
-    lsqb: "[",
-    lt: "<",
-    num: "#",
-    percnt: "%",
-    period: ".",
-    plus: "+",
-    quest: "?",
-    quot: '"',
-    rcub: "}",
-    rpar: ")",
-    rsqb: "]",
-    semi: ";",
-    sol: "/",
-    verbar: "|",
-};
+const ASCII_ENTITIES = new Map([
+    ["amp", "&"],
+    ["apos", "'"],
+    ["ast", "*"],
+    ["bsol", "\\"],
+    ["colon", ":"],
+    ["comma", ","],
+    ["commat", "@"],
+    ["dollar", "$"],
+    ["equals", "="],
+    ["excl", "!"],
+    ["grave", "`"],
+    ["gt", ">"],
+    ["hat", "^"],
+    ["lcub", "{"],
+    ["lowbar", "_"],
+    ["lpar", "("],
+    ["lsqb", "["],
+    ["lt", "<"],
+    ["num", "#"],
+    ["percnt", "%"],
+    ["period", "."],
+    ["plus", "+"],
+    ["quest", "?"],
+    ["quot", '"'],
+    ["rcub", "}"],
+    ["rpar", ")"],
+    ["rsqb", "]"],
+    ["semi", ";"],
+    ["sol", "/"],
+    ["verbar", "|"],
+]);
 function codePoint(value, original) {
     return Number.isInteger(value) && value >= 0 && value <= 0x10ffff
         ? String.fromCodePoint(value)
         : original;
 }
-/** Undoes JSON and JS escapes, percent-encoding and HTML character references, one pass each. */
+// The length of the UTF-8 sequence a lead byte starts, or 0 for a byte that starts none.
+function sequenceLength(lead) {
+    if (lead < 0x80)
+        return 1;
+    if (lead >= 0xc2 && lead <= 0xdf)
+        return 2;
+    if (lead >= 0xe0 && lead <= 0xef)
+        return 3;
+    if (lead >= 0xf0 && lead <= 0xf4)
+        return 4;
+    return 0;
+}
+/**
+ * Bytes read as UTF-8, as a browser reads a URL. A byte that starts no valid sequence stands for
+ * itself, the character with that code, as decodeEscapes reads every byte.
+ */
+function utf8Characters(bytes) {
+    if (isUtf8(bytes))
+        return bytes.toString("utf8");
+    let text = "";
+    for (let at = 0; at < bytes.length;) {
+        const length = sequenceLength(bytes[at]);
+        const sequence = bytes.subarray(at, at + length);
+        // isUtf8 refuses an overlong form, a surrogate half and a bad continuation byte.
+        if (length > 0 && sequence.length === length && isUtf8(sequence)) {
+            text += sequence.toString("utf8");
+            at += length;
+        }
+        else {
+            text += String.fromCharCode(bytes[at]);
+            at += 1;
+        }
+    }
+    return text;
+}
+const decodePercentRun = (run) => utf8Characters(Buffer.from(run.replace(/%/g, ""), "hex"));
+// A character from U+0080 to U+00FF, which a byte of 0x80 or more becomes when read one per
+// character.
+const HIGH_BYTE = /[\x80-\xff]/;
+/** Each run of characters U+0080 to U+00FF read as the UTF-8 bytes they may be: é as é. */
+export const latin1RunsAsUtf8 = (text) => text.replace(/[\x80-\xff]+/g, (run) => utf8Characters(Buffer.from(run, "latin1")));
+function decodePercentBytes(run) {
+    return Buffer.from(run.replace(/%/g, ""), "hex").toString("latin1");
+}
+/**
+ * Undoes JSON and JS escapes, percent-encoding and HTML character references, one pass each. Each
+ * percent escape is one character, the byte's code, so `caf%C3%A9` reads as `café`; readingsOf
+ * also gives the reading as UTF-8, `café`.
+ */
 export function decodeEscapes(text) {
+    return decodeWith(text, decodePercentBytes);
+}
+/** The readings a scan matches, with the two that scanEncodedText also searches for runs. */
+function readings(text) {
+    const decoded = decodeEscapes(text);
+    // The UTF-8 reading differs only where a percent escape holds a byte of 0x80 or more, which
+    // decodeEscapes writes as a character from U+0080 to U+00FF. Testing the decoded text also
+    // catches a `%` that a `\u0025` wrote.
+    const utf8 = HIGH_BYTE.test(decoded) ? decodeWith(text, decodePercentRun) : decoded;
+    const expanded = decodeTransferEscapes(decoded);
+    const recovered = [text, decoded].filter((reading) => HIGH_BYTE.test(reading));
+    return {
+        decoded,
+        expanded,
+        all: [...new Set([text, decoded, utf8, expanded, ...recovered.map(latin1RunsAsUtf8)])],
+    };
+}
+/**
+ * Every reading of the text a scan matches, each once: as written, decodeEscapes, with percent
+ * escapes read as UTF-8, decodeEscapes with transfer escapes expanded, and the text as written and
+ * decoded with each run of U+0080 to U+00FF characters read as UTF-8 bytes, which undoes text that
+ * a reader already decoded one byte per character. Either percent reading can split a value that
+ * the other keeps whole, as `%E2%80%80` (U+2000, a space, in UTF-8) does.
+ */
+export function readingsOf(text) {
+    return readings(text).all;
+}
+function decodeWith(text, percent) {
     return text
         .replace(/\\u([0-9a-f]{4})/gi, (match, hex) => codePoint(Number.parseInt(hex, 16), match))
         .replace(/\\x([0-9a-f]{2})/gi, (match, hex) => codePoint(Number.parseInt(hex, 16), match))
         .replace(/\\\//g, "/")
-        .replace(/%([0-9a-f]{2})/gi, (match, hex) => codePoint(Number.parseInt(hex, 16), match))
+        .replace(/(?:%[0-9a-f]{2})+/gi, percent)
         .replace(/&#x([0-9a-f]{1,6});?/gi, (match, hex) => codePoint(Number.parseInt(hex, 16), match))
         .replace(/&#(\d{1,7});?/g, (match, digits) => codePoint(Number.parseInt(digits, 10), match))
-        .replace(/&([a-z]+);/gi, (match, name) => ASCII_ENTITIES[name.toLowerCase()] ?? match);
+        .replace(/&([a-z]+);/gi, namedReference);
+}
+function namedReference(match, name) {
+    return ASCII_ENTITIES.get(name.toLowerCase()) ?? match;
 }
 // Sixteen characters hold twelve bytes, enough for the start of a key. Shorter runs are mostly
 // words and identifiers.
@@ -201,8 +281,7 @@ function inspectDecoded(bytes, run, options, depth) {
     if (inner !== undefined) {
         if (depth < MAX_DEPTH)
             return scanEncodedText(inner, options, depth + 1);
-        const innerDecoded = decodeEscapes(inner);
-        return matches(inner) || (innerDecoded !== inner && matches(innerDecoded)) ? SENSITIVE : CLEAN;
+        return readingsOf(inner).some(matches) ? SENSITIVE : CLEAN;
     }
     // A key next to a few binary bytes is still a printable stretch.
     if (matches(printableStretches(bytes)))
@@ -215,19 +294,15 @@ function inspectDecoded(bytes, run, options, depth) {
     };
 }
 /**
- * Scans text for secrets as written, after decodeEscapes and transfer escapes, and inside each
- * base64 (standard, URL-safe or line-wrapped) and hex run. A run that decodes to text is scanned in
+ * Scans text for secrets in each of its readingsOf, and inside each base64 (standard, URL-safe or
+ * line-wrapped) and hex run. A run that decodes to text is scanned in
  * turn. A run that decodes to an archive, or to other binary past MIN_OPAQUE_BASE64_RUN characters,
  * is opaque unless the caller allows opaque runs.
  */
 export function scanEncodedText(text, options = {}, depth = 0) {
     const matches = matcherOf(options);
-    const decoded = decodeEscapes(text);
-    const expanded = decodeTransferEscapes(decoded);
-    // A decoding that returns the same string would match the same way, so it is not matched again.
-    if (matches(text) ||
-        (decoded !== text && matches(decoded)) ||
-        (expanded !== decoded && matches(expanded)))
+    const { decoded, expanded, all } = readings(text);
+    if (all.some(matches))
         return SENSITIVE;
     const runs = [];
     // A piece or a run decoded from a slash only adds findings; its bytes are not judged opaque.
@@ -277,7 +352,7 @@ export function scanEncodedText(text, options = {}, depth = 0) {
 // Bump when scanEncodedText, decodeEscapes or the sensitive patterns change what they return. The
 // cache lives in one process, so the version guards results across a hot reload or a test that
 // swaps the scanner.
-const ENCODED_SCAN_VERSION = 3;
+const ENCODED_SCAN_VERSION = 5;
 // Distinct files one process verifies in a burst (a run's files, a serve library's runs).
 const SCAN_CACHE_LIMIT = 256;
 const scanCache = new Map();

package/dist/evidence/redaction.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Every marker humanish writes in place of what it withholds. The known-value scrub leaves text
+ * wholly inside one of these as it is, so a writer of a new marker adds it here.
+ */
+export declare const REDACTION_MARKERS: {
+    readonly secret: "[REDACTED_SECRET]";
+    readonly localPath: "[REDACTED_LOCAL_PATH]";
+    readonly runtimePath: "[REDACTED_RUNTIME_PATH]";
+    readonly promptText: "[REDACTED_PROMPT_TEXT]";
+    readonly lobbyCode: "[REDACTED_LOBBY_CODE]";
+};
 /** Every pattern containsSensitive tests. A test pins each to ASCII, which scanEncodedText relies on. */
 export declare function sensitivePatterns(): readonly RegExp[];
 /** True if the text contains a credential. Local paths and a URL on an E2B host alone do not count. */

package/dist/evidence/redaction.js

@@ -126,18 +126,29 @@ const SECRET_PATTERNS = [
     SANDBOX_URL,
     /BEGIN (RSA|OPENSSH|PRIVATE) KEY/gi,
 ];
+/**
+ * Every marker humanish writes in place of what it withholds. The known-value scrub leaves text
+ * wholly inside one of these as it is, so a writer of a new marker adds it here.
+ */
+export const REDACTION_MARKERS = {
+    secret: "[REDACTED_SECRET]",
+    localPath: "[REDACTED_LOCAL_PATH]",
+    runtimePath: "[REDACTED_RUNTIME_PATH]",
+    promptText: "[REDACTED_PROMPT_TEXT]",
+    lobbyCode: "[REDACTED_LOBBY_CODE]",
+};
 const LOCAL_PATH_PATTERNS = [
-    [/\/private\/var\/folders\/[^\s"'`<>)]*/g, "[REDACTED_LOCAL_PATH]"],
-    [/\/var\/folders\/[^\s"'`<>)]*/g, "[REDACTED_LOCAL_PATH]"],
-    [/\/private\/tmp\/[^\s"'`<>)]*/g, "[REDACTED_LOCAL_PATH]"],
-    [/\/tmp\/[^\s"'`<>)]*/g, "[REDACTED_LOCAL_PATH]"],
-    [/\/Users\/[A-Za-z0-9._-]+(?:\/[^\s"'`<>)]*)?/g, "[REDACTED_LOCAL_PATH]"],
-    [/\/home\/[A-Za-z0-9._-]+(?:\/[^\s"'`<>)]*)?/g, "[REDACTED_RUNTIME_PATH]"],
+    [/\/private\/var\/folders\/[^\s"'`<>)]*/g, REDACTION_MARKERS.localPath],
+    [/\/var\/folders\/[^\s"'`<>)]*/g, REDACTION_MARKERS.localPath],
+    [/\/private\/tmp\/[^\s"'`<>)]*/g, REDACTION_MARKERS.localPath],
+    [/\/tmp\/[^\s"'`<>)]*/g, REDACTION_MARKERS.localPath],
+    [/\/Users\/[A-Za-z0-9._-]+(?:\/[^\s"'`<>)]*)?/g, REDACTION_MARKERS.localPath],
+    [/\/home\/[A-Za-z0-9._-]+(?:\/[^\s"'`<>)]*)?/g, REDACTION_MARKERS.runtimePath],
     // A Windows profile path, with `\`, `\\` (JSON-escaped) or `/` between segments. A match never
     // ends in a backslash, so it cannot swallow the escape of a closing quote.
     [
         /\b[A-Za-z]:(?:\\\\|\\|\/)Users(?:\\\\|\\|\/)[^\\/\s"'`<>)]+[^\s"'`<>)]*/g,
-        "[REDACTED_LOCAL_PATH]",
+        REDACTION_MARKERS.localPath,
     ],
 ];
 /** Every pattern containsSensitive tests. A test pins each to ASCII, which scanEncodedText relies on. */
@@ -265,7 +276,7 @@ function redactSecrets(text) {
     return SECRET_PATTERNS.reduce((current, pattern) => current.replace(pattern, (...args) => {
         const groups = args.at(-1);
         const keep = isRecord(groups) && typeof groups.keep === "string" ? groups.keep : "";
-        return `${keep}[REDACTED_SECRET]`;
+        return `${keep}${REDACTION_MARKERS.secret}`;
     }), text);
 }
 /** Redact secrets to [REDACTED_SECRET] and local paths to their path labels. */
@@ -274,7 +285,7 @@ export function redactText(text) {
 }
 /** Redact every sensitive match (secrets and paths) to a single [REDACTED_SECRET] label. */
 export function redactToSecretLabel(text) {
-    return redactLocalPaths(redactSecrets(text), "[REDACTED_SECRET]");
+    return redactLocalPaths(redactSecrets(text), REDACTION_MARKERS.secret);
 }
 function canonicalizePath(value) {
     const resolved = path.resolve(value);
@@ -526,7 +537,7 @@ function blurPass(src, width, height, radius, horizontal) {
  * pattern-match, such as provisioned keys and subject env values. `values` is read on each call,
  * so a value registered later is scrubbed too.
  */
-export function scrubLiterals(values, marker = "[REDACTED_SECRET]") {
+export function scrubLiterals(values, marker = REDACTION_MARKERS.secret) {
     return (text) => values.reduce((current, value) => current.split(value).join(marker), text);
 }
 /**

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

@@ -1,10 +1,17 @@
 /**
  * A value as written, and percent-encoded, JSON-escaped once (also with non-ASCII characters as
- * `\u` escapes) and twice, base64 at each byte offset, base64url and hex. Twice, because a JSON event can carry a command's JSON output as a string. An
+ * `\u` escapes) and twice, its UTF-8 bytes read one per character and the reverse, base64 at each
+ * byte offset, base64url and hex. Twice, because a JSON event can carry a command's JSON output as
+ * a string. An
  * escaped form is searched for at any length, as the value is: it holds a backslash or a `%`, so it
  * is not ordinary text.
  */
 export declare function encodedForms(value: string): string[];
+/**
+ * A check that the text holds one of the values' forms outside the markers in any of its
+ * readingsOf. A scrub's output must pass it.
+ */
+export declare function holdsSecretValue(values: readonly string[]): (text: string) => boolean;
 /**
  * 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
@@ -12,5 +19,11 @@ export declare function encodedForms(value: string): string[];
  * 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.
+ *
+ * The result's other readingsOf only detect. If one still holds a form, the scrub returns
+ * `[REDACTED_SECRET]` in place of the whole text. That happens for a value encoded twice, which
+ * the decoded text shows encoded once; for a value the UTF-8 or transfer reading holds, such as
+ * one with one of two non-ASCII characters percent-encoded; and for a value that holds part of a
+ * marker, such as `ET]x`, which the marker that replaced it can spell again.
  */
 export declare function scrubSecretValues(values: readonly string[]): (text: string) => string;