humanish 0.110.0 → 0.110.2

package/dist/evidence/encoded-text.js

@@ -4,7 +4,7 @@
 // judge the same decoded text.
 import { createHash } from "node:crypto";
 import { readPlainText } from "./plain-text.js";
-import { containsSensitive } from "./redaction.js";
+import { containsSecret, 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 = {
@@ -57,15 +57,13 @@ export function decodeEscapes(text) {
 }
 // Sixteen characters hold twelve bytes, enough for the start of a key. Shorter runs are mostly
 // words and identifiers.
-const BASE64_RUN = /[A-Za-z0-9+/]{16,}={0,2}/g;
+// Each open-ended repeat is written `[...]{n}[...]*`: V8 runs `{n,}` with a backtrack entry per
+// character and overflows its stack on a run of several megabytes.
+const BASE64_RUN = /[A-Za-z0-9+/]{16}[A-Za-z0-9+/]*={0,2}/g;
 // The URL-safe alphabet swaps `+/` for `-_`. Only runs that use `-` or `_` need this pass.
-const BASE64URL_RUN = /[A-Za-z0-9_-]{16,}={0,2}/g;
-// MIME and PEM wrap base64 at 64 or 76 characters a line. The lookbehind starts a match only at the
-// start of a run, and each lookahead-backreference pair takes a line whole, so a long unwrapped run
-// cannot backtrack.
-const WRAPPED_BASE64 = /(?<![A-Za-z0-9+/])(?=([A-Za-z0-9+/]{16,}))\1(?:[ \t]*\r?\n[ \t]*(?=([A-Za-z0-9+/]{4,}))\2)+={0,2}/g;
+const BASE64URL_RUN = /[A-Za-z0-9_-]{16}[A-Za-z0-9_-]*={0,2}/g;
 // Hex-encoded text, at least sixteen bytes of it.
-const HEX_RUN = /(?:[0-9a-f]{2}){16,}/gi;
+const HEX_RUN = /[0-9a-f]{32}[0-9a-f]*/gi;
 // A base64 run that decodes to bytes that are neither text nor an archive is unreadable only past
 // this length. Across 173 real run folders surveyed on 2026-10-01, the longest such run outside
 // observer/index.html was a 69-character URL path in a terminal log; base64 of a 94-byte payload,
@@ -84,6 +82,61 @@ const ARCHIVE_MAGIC = [
     [0x28, 0xb5, 0x2f, 0xfd],
 ];
 const CONTROL_CHARACTERS = /[\x00-\x08\x0b\x0c\x0e-\x1f]/;
+// A run such as `com/x/<base64>` from a URL path starts with segments that shift the alignment of
+// the base64 after them. A run up to this long is also decoded one slash-separated piece at a time,
+// and from just after each slash in its first SLASH_START_SPAN characters, for base64 that holds a
+// slash itself. Longer runs are images, fonts and archives, not URLs.
+const MAX_SLASH_START_RUN = 4096;
+const SLASH_START_SPAN = 64;
+function isBase64Code(code) {
+    return ((code >= 0x30 && code <= 0x39) ||
+        (code >= 0x41 && code <= 0x5a) ||
+        (code >= 0x61 && code <= 0x7a) ||
+        code === 0x2b ||
+        code === 0x2f);
+}
+/**
+ * Base64 that MIME and PEM wrap at 64 or 76 characters a line: a run of 16 or more characters that
+ * ends its line, then the leading run of 4 or more on each following line, for as long as a line
+ * holds nothing else. Read line by line, so a long wrapped block costs linear time and no regex
+ * stack.
+ */
+function wrappedBase64Runs(text) {
+    const runs = [];
+    let current = [];
+    const flush = () => {
+        if (current.length > 1)
+            runs.push(current.join(""));
+        current = [];
+    };
+    for (const raw of text.split("\n")) {
+        const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+        let end = line.length;
+        while (end > 0 && (line[end - 1] === " " || line[end - 1] === "\t"))
+            end -= 1;
+        let start = 0;
+        while (start < end && (line[start] === " " || line[start] === "\t"))
+            start += 1;
+        if (current.length > 0) {
+            let lead = start;
+            while (lead < end && isBase64Code(line.charCodeAt(lead)))
+                lead += 1;
+            if (lead - start >= 4) {
+                current.push(line.slice(start, lead));
+                if (lead === end)
+                    continue;
+            }
+            flush();
+        }
+        let tail = end;
+        while (tail > 0 && isBase64Code(line.charCodeAt(tail - 1)))
+            tail -= 1;
+        if (end - tail >= 16)
+            current = [line.slice(tail, end)];
+    }
+    flush();
+    return runs;
+}
 // Base64 inside base64 is read this many levels deep.
 const MAX_DEPTH = 2;
 function startsWithArchive(bytes) {
@@ -136,9 +189,11 @@ function decodeTransferEscapes(text) {
         .replace(/=\r?\n/g, "")
         .replace(/=([0-9A-F]{2})/g, (match, hex) => codePoint(Number.parseInt(hex, 16), match));
 }
+const matcherOf = (options) => options.secretsOnly === true ? containsSecret : containsSensitive;
 const CLEAN = Object.freeze({ sensitive: false, opaque: false });
 const SENSITIVE = Object.freeze({ sensitive: true, opaque: false });
 function inspectDecoded(bytes, run, options, depth) {
+    const matches = matcherOf(options);
     if (startsWithArchive(bytes))
         return { sensitive: false, opaque: options.allowOpaqueBase64 !== true };
     const plain = readPlainText(bytes);
@@ -147,12 +202,10 @@ function inspectDecoded(bytes, run, options, depth) {
         if (depth < MAX_DEPTH)
             return scanEncodedText(inner, options, depth + 1);
         const innerDecoded = decodeEscapes(inner);
-        return containsSensitive(inner) || (innerDecoded !== inner && containsSensitive(innerDecoded))
-            ? SENSITIVE
-            : CLEAN;
+        return matches(inner) || (innerDecoded !== inner && matches(innerDecoded)) ? SENSITIVE : CLEAN;
     }
     // A key next to a few binary bytes is still a printable stretch.
-    if (containsSensitive(printableStretches(bytes)))
+    if (matches(printableStretches(bytes)))
         return SENSITIVE;
     return {
         sensitive: false,
@@ -168,28 +221,36 @@ function inspectDecoded(bytes, run, options, depth) {
  * 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 (containsSensitive(text) ||
-        (decoded !== text && containsSensitive(decoded)) ||
-        (expanded !== decoded && containsSensitive(expanded)))
+    if (matches(text) ||
+        (decoded !== text && matches(decoded)) ||
+        (expanded !== decoded && matches(expanded)))
         return SENSITIVE;
     const runs = [];
+    // A piece or a run decoded from a slash only adds findings; its bytes are not judged opaque.
+    const slashStarts = [];
     for (const [match] of expanded.matchAll(BASE64_RUN)) {
         // Hex digests and ids decode to noise; the hex pass below reads hex as hex.
         if (/^[0-9a-f]+$/i.test(match.replace(/=+$/, "")))
             continue;
         runs.push({ run: match, bytes: Buffer.from(match, "base64") });
+        if (match.length > MAX_SLASH_START_RUN)
+            continue;
+        for (const piece of match.split("/"))
+            if (piece.length >= 16 && piece.length < match.length)
+                slashStarts.push(Buffer.from(piece, "base64"));
+        for (let slash = match.indexOf("/"); slash !== -1 && slash < SLASH_START_SPAN && match.length - slash > 16; slash = match.indexOf("/", slash + 1))
+            slashStarts.push(Buffer.from(match.slice(slash + 1), "base64"));
     }
     for (const [match] of expanded.matchAll(BASE64URL_RUN)) {
         if (/[-_]/.test(match))
             runs.push({ run: match, bytes: Buffer.from(match, "base64url") });
     }
-    for (const [match] of expanded.matchAll(WRAPPED_BASE64)) {
-        const run = match.replace(/\s+/g, "");
+    for (const run of wrappedBase64Runs(expanded))
         runs.push({ run, bytes: Buffer.from(run, "base64") });
-    }
     let opaque = false;
     for (const { run, bytes } of runs) {
         const result = inspectDecoded(bytes, run, options, depth);
@@ -197,6 +258,9 @@ export function scanEncodedText(text, options = {}, depth = 0) {
             return result;
         opaque ||= result.opaque;
     }
+    for (const bytes of slashStarts)
+        if (inspectDecoded(bytes, "", { ...options, allowOpaqueBase64: true }, depth).sensitive)
+            return SENSITIVE;
     for (const [match] of expanded.matchAll(HEX_RUN)) {
         const plain = readPlainText(Buffer.from(match, "hex"));
         if (plain.ok && depth < MAX_DEPTH && scanEncodedText(plain.text, options, depth + 1).sensitive)
@@ -207,7 +271,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 = 1;
+const ENCODED_SCAN_VERSION = 2;
 // 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();
@@ -222,6 +286,7 @@ export function scanEncodedTextCached(text, options = {}) {
     const key = [
         ENCODED_SCAN_VERSION,
         options.allowOpaqueBase64 === true ? "opaque-allowed" : "opaque-unscanned",
+        options.secretsOnly === true ? "secrets-only" : "secrets-and-paths",
         createHash("sha256").update(Buffer.from(text, "utf16le")).digest("hex"),
     ].join(":");
     const cached = scanCache.get(key);

package/dist/evidence/redaction.d.ts

@@ -1,5 +1,7 @@
 /** 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 secret-shaped token. Local paths do not count. */
+export declare function containsSecret(text: string): boolean;
 /** True if the text contains any secret-shaped token or known local path. */
 export declare function containsSensitive(text: string): boolean;
 /**

package/dist/evidence/redaction.js

@@ -3,26 +3,113 @@ import { realpathSync } from "node:fs";
 import path from "node:path";
 import { PNG } from "pngjs";
 import { SCREENSHOT_MAX_WIDTH_CAP, pngDecodeRefusal } from "./image.js";
+import { isRecord } from "../run/type-guards.js";
 // Single source of truth for public-safety redaction patterns. Producers and the verify gate
 // both use these, so the denylist cannot drift between them. See docs/contracts/policy.md for
 // the enforcement-scope policy.
+// A whole value that stands in for a secret rather than being one, as written or percent-encoded:
+// a redaction marker, a shell or template variable, a placeholder in angle brackets, or a mask of
+// asterisks. A context pattern skips a value only when one of these is all of it, up to a
+// character that ends that pattern's value, so a password that merely starts with `*` or `$`
+// still counts.
+const PLACEHOLDER = [
+    String.raw `\[REDACTED_[A-Z0-9_]{1,40}\]`,
+    String.raw `%5[Bb]REDACTED_[A-Z0-9_]{1,40}%5[Dd]`,
+    String.raw `\$\{[A-Za-z_][A-Za-z0-9_]{0,63}\}`,
+    String.raw `%24%7[Bb][A-Za-z_][A-Za-z0-9_]{0,63}%7[Dd]`,
+    String.raw `\$[A-Za-z_][A-Za-z0-9_]{0,63}`,
+    String.raw `%24[A-Za-z_][A-Za-z0-9_]{0,63}`,
+    String.raw `\{\{[A-Za-z0-9_. -]{1,64}\}\}`,
+    String.raw `<[A-Za-z0-9_. -]{1,64}>`,
+    String.raw `%3[Cc][A-Za-z0-9_.-]{1,64}%3[Ee]`,
+    String.raw `\*{3,64}`,
+    String.raw `(?:%2[Aa]){3,64}`,
+].join("|");
+const notAPlaceholder = (valueEnd) => String.raw `(?!(?:${PLACEHOLDER})(?:${valueEnd}|$))`;
+// An optional quote around a name or a value, also as JSON writes it inside other JSON strings,
+// four levels deep (\", \\\", ...).
+const QUOTE = String.raw `(?:\\{0,15}["'])?`;
+// A JSON number, which a credential-named key can hold and redaction must not turn into a string.
+// The bounds are far past any number a run writes and keep the lookahead linear.
+const NOT_A_NUMBER = String.raw `(?!-?[0-9]{1,512}(?:\.[0-9]{0,512})?(?:[eE][+-]?[0-9]{1,64})?(?:[\s,}\]]|$))`;
+// The characters that end each context pattern's value.
+const USERINFO_END = String.raw `[\s@/?#"'<>\\]`;
+const PARAMETER_END = String.raw `[\s&#"'<>\\]`;
+const VARIABLE_END = String.raw `[\s"'\\,;&]`;
+// Query and fragment parameters that carry a credential. `page_token` and other cursors match too;
+// their values are long and opaque, so a reader cannot tell them from a credential either.
+const CREDENTIAL_PARAMETER = [
+    String.raw `(?:[a-z0-9]{1,24}[_-]){0,2}token`,
+    String.raw `api[_-]?key`,
+    String.raw `(?:client[_-])?secret`,
+    "password",
+    "passwd",
+    "pwd",
+    "sig",
+    "signature",
+    String.raw `session[_-]?id`,
+    "jwt",
+    "x-vercel-protection-bypass",
+    "_vercel_share",
+    String.raw `x-amz-(?:signature|security-token|credential)`,
+    String.raw `x-goog-(?:signature|credential)`,
+    "auth",
+].join("|");
+// Upper-case variable names that hold a credential, as an env file, a shell or a JSON dump writes
+// them: GITHUB_TOKEN, VERCEL_TOKEN, AWS_SECRET_ACCESS_KEY, DATABASE_PASSWORD.
+const CREDENTIAL_VARIABLE = String.raw `\b(?:[A-Z][A-Z0-9_]{0,48}_)?(?:TOKEN|SECRET|SECRET_KEY|PASSWORD|PASSWD|API_KEY|APIKEY|ACCESS_KEY|PRIVATE_KEY)`;
+// A pattern that matches a credential by its context puts the context in a `keep` group, which
+// redaction leaves in place: `?token=[REDACTED_SECRET]`. Context goes in a group and not in a
+// lookbehind, because a pattern that starts with a lookbehind is tried at every position of the
+// text and scans many times slower. An open-ended repeat is written `[...]{n}[...]*`: V8 runs
+// `{n,}` with a backtrack entry per character and overflows its stack on a run of several
+// megabytes, and a star loop does not.
 const SECRET_PATTERNS = [
-    /\bsk-(?:proj-|svcacct-)?[A-Za-z0-9_-]{20,}\b/g,
-    /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g,
-    /\be2b_[A-Za-z0-9]{16,}\b/g,
-    /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b/g,
-    /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
-    /\bAKIA[0-9A-Z]{16}\b/g,
-    /\bAIza[0-9A-Za-z_-]{20,}\b/g,
-    /\b(?:sk|rk)_live_[A-Za-z0-9]{16,}\b/g,
-    /\bhf_[A-Za-z0-9]{30,}\b/g,
-    /\bxox[baprs]-[A-Za-z0-9-]{20,}\b/g,
-    /\beyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}\b/g,
+    /\bsk-(?:proj-|svcacct-)?[A-Za-z0-9_-]{20}[A-Za-z0-9_-]*\b/g,
+    /\bsk-ant-[A-Za-z0-9_-]{20}[A-Za-z0-9_-]*\b/g,
+    /\be2b_[A-Za-z0-9]{16}[A-Za-z0-9]*\b/g,
+    /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20}[A-Za-z0-9_]*\b/g,
+    /\bgithub_pat_[A-Za-z0-9_]{20}[A-Za-z0-9_]*\b/g,
+    /\bglpat-[A-Za-z0-9_-]{20}[A-Za-z0-9_-]*/g,
+    /\bnpm_[A-Za-z0-9]{36}\b/g,
+    // Vercel personal, integration, app access, app refresh and API key tokens.
+    /\bvc[pciark]_[A-Za-z0-9]{24}[A-Za-z0-9]*\b/g,
+    /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
+    /\bAIza[0-9A-Za-z_-]{20}[0-9A-Za-z_-]*\b/g,
+    /\bya29\.[0-9A-Za-z_-]{20}[0-9A-Za-z_-]*/g,
+    /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16}[A-Za-z0-9]*\b/g,
+    /\bwhsec_[A-Za-z0-9]{24}[A-Za-z0-9]*\b/g,
+    /\bSG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}\b/g,
+    /\bhf_[A-Za-z0-9]{30}[A-Za-z0-9]*\b/g,
+    /\bxox[abeoprs]-[A-Za-z0-9-]{20}[A-Za-z0-9-]*\b/g,
+    /\bxapp-[0-9]-[A-Za-z0-9-]{20}[A-Za-z0-9-]*\b/g,
+    /\bhooks\.slack\.com\/(?:services|workflows|triggers)\/[A-Za-z0-9_/-]{20}[A-Za-z0-9_/-]*/g,
+    // A JWT starts only where a token run starts, so a run of `eyJ-` repeated is read once.
+    /eyJ(?<![A-Za-z0-9_-]eyJ)[A-Za-z0-9_-]{20}[A-Za-z0-9_-]*\.[A-Za-z0-9_-]{20}[A-Za-z0-9_-]*\.[A-Za-z0-9_-]{10}[A-Za-z0-9_-]*\b/g,
     /-----BEGIN [A-Z ]*PRIVATE KEY-----/g,
-    /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis):\/\/[^:@/\s]+:[^@/\s]+@\S+/g,
-    /_authToken\s*=\s*[A-Za-z0-9._~+/=-]{20,}/g,
-    /\bBearer\s+[A-Za-z0-9._~+/-]{24,}\b/g,
-    /https?:\/\/[^/\s]*e2b[^)\s]+/gi,
+    /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis):\/\/[^:@/\s"'<>\\]+:[^@/\s"'<>\\]+@[^\s"'<>\\]+/g,
+    /_authToken\s*=\s*[A-Za-z0-9._~+/=-]{20}[A-Za-z0-9._~+/=-]*/g,
+    /\bBearer\s+[A-Za-z0-9._~+/-]{24}[A-Za-z0-9._~+/-]*\b/g,
+    new RegExp(String.raw `(?<keep>\bAuthorization${QUOTE}[ \t]{0,4}[:=][ \t]{0,4}${QUOTE}Basic[ \t]{1,4})[A-Za-z0-9+/]{16}[A-Za-z0-9+/]*={0,2}`, "gi"),
+    // The password in a URL's userinfo, any scheme, with or without a user name:
+    // https://user:password@host, https://:password@host.
+    new RegExp(String.raw `(?<keep>\b[a-z][a-z0-9+.-]{0,31}:\/\/[^\s:@/?#"'<>\\[\]]{0,256}:)${notAPlaceholder(USERINFO_END)}[^\s@/?#"'<>\\]{1,256}(?=@)`, "gi"),
+    // A credential-named query or fragment parameter's value, up to the next delimiter, so a
+    // password with punctuation in it counts whole. `;` also follows an HTML `&amp;`.
+    new RegExp(String.raw `(?<keep>[?&#;](?:${CREDENTIAL_PARAMETER})=)${notAPlaceholder(PARAMETER_END)}[^\s&#"'<>\\]{16}[^\s&#"'<>\\]*`, "gi"),
+    // An Amazon Web Services secret access key next to its name, as a credentials file, an env
+    // line or a temporary-credentials JSON response writes it. The key is 40 characters, no prefix.
+    new RegExp(String.raw `(?<keep>\b(?:aws_?)?secret_?access_?key${QUOTE}[ \t]{0,4}[:=][ \t]{0,4}${QUOTE})${NOT_A_NUMBER}[A-Za-z0-9/+]{40}(?![A-Za-z0-9/+=])`, "gi"),
+    // A credential-named variable set to a value of 16 characters or more, up to the next space,
+    // quote or separator, with a digit and a letter in its first 256 characters. Words, placeholders
+    // such as humanish-egress-auth-placeholder and JSON numbers do not count. The lookaheads are
+    // bounded, so a long run of `TOKEN=` costs linear time.
+    new RegExp(String.raw `(?<keep>${CREDENTIAL_VARIABLE}${QUOTE}[ \t]{0,4}[:=][ \t]{0,4}${QUOTE})${notAPlaceholder(VARIABLE_END)}${NOT_A_NUMBER}(?=[^\s"'\\,;&]{0,255}[0-9])(?=[^\s"'\\,;&]{0,255}[A-Za-z])[^\s"'\\,;&]{16}[^\s"'\\,;&]*`, "g"),
+    // Any URL on an E2B host: a sandbox host names its sandbox, and a stream URL carries its auth
+    // key. One URL is exempt: E2B's dashboard, as the SDK's missing-key error names it
+    // (https://e2b.dev/dashboard?tab=keys), with no userinfo, no path below /dashboard, no query but
+    // one short `tab`, and only closing punctuation before the next space or ")".
+    /(?!https:\/\/(?:www\.)?e2b\.dev\/dashboard\/?(?:\?tab=[a-z]{1,16})?[.,;:!?'"]*(?:[)\s]|$))https?:\/\/[^/\s]*e2b[^)\s]+/gi,
     /BEGIN (RSA|OPENSSH|PRIVATE) KEY/gi,
 ];
 const LOCAL_PATH_PATTERNS = [
@@ -32,6 +119,12 @@ const LOCAL_PATH_PATTERNS = [
     [/\/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]"],
+    // 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]",
+    ],
 ];
 /** Every pattern containsSensitive tests. A test pins each to ASCII, which scanEncodedText relies on. */
 export function sensitivePatterns() {
@@ -43,10 +136,13 @@ function matchesPattern(pattern, text) {
     pattern.lastIndex = 0;
     return pattern.test(text);
 }
+/** True if the text contains a secret-shaped token. Local paths do not count. */
+export function containsSecret(text) {
+    return SECRET_PATTERNS.some((pattern) => matchesPattern(pattern, text));
+}
 /** True if the text contains any secret-shaped token or known local path. */
 export function containsSensitive(text) {
-    return (SECRET_PATTERNS.some((pattern) => matchesPattern(pattern, text)) ||
-        LOCAL_PATH_PATTERNS.some(([pattern]) => matchesPattern(pattern, text)));
+    return (containsSecret(text) || LOCAL_PATH_PATTERNS.some(([pattern]) => matchesPattern(pattern, text)));
 }
 // A local-path match may end in the backslashes escaping its closing quote in
 // serialized JSON (including JSON nested inside a terminal event). Keep that
@@ -142,15 +238,21 @@ export function redactSandboxIds(value) {
         entries.some(([key, child]) => child !== value[key]);
     return changed ? Object.fromEntries(entries) : value;
 }
+/** Each secret replaced by [REDACTED_SECRET], with the context a pattern keeps left in place. */
+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]`;
+    }), text);
+}
 /** Redact secrets to [REDACTED_SECRET] and local paths to their path labels. */
 export function redactText(text) {
-    const withoutSecrets = SECRET_PATTERNS.reduce((current, pattern) => current.replace(pattern, "[REDACTED_SECRET]"), text);
-    return redactLocalPaths(withoutSecrets);
+    return redactLocalPaths(redactSecrets(text));
 }
 /** Redact every sensitive match (secrets and paths) to a single [REDACTED_SECRET] label. */
 export function redactToSecretLabel(text) {
-    const withoutSecrets = SECRET_PATTERNS.reduce((current, pattern) => current.replace(pattern, "[REDACTED_SECRET]"), text);
-    return redactLocalPaths(withoutSecrets, "[REDACTED_SECRET]");
+    return redactLocalPaths(redactSecrets(text), "[REDACTED_SECRET]");
 }
 function canonicalizePath(value) {
     const resolved = path.resolve(value);

package/dist/feedback/export-bundle.js

@@ -18,6 +18,7 @@ import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
 import {} from "../run/bundle.js";
 import { runIdOf, isPathInside, prepareRunArtifactPaths, validatePreparedRunArtifactPaths, } from "../run/paths.js";
 import { isAnalysisRecordPath } from "../analysis/sharing.js";
+import { LOCAL_ONLY_RUN_FILES } from "../run/local-only-files.js";
 import { assertPreparedSelectedOutputDirectory, prepareManagedHumanishOutputDirectory, prepareSelectedOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
 const DERIVATION_SCHEMA = "humanish.redacted-derivation.v1";
 const MAX_FILES = 10_000;
@@ -36,8 +37,7 @@ const OMITTED = new Map([
     ["observer/index.html", "regenerated Observer"],
     ["observer/observer-data.json", "regenerated Observer projection"],
     ["observer/study-analysis.json", "analysis must be regenerated against derivative evidence"],
-    ["status.json", "local process status is not a new attempt"],
-    ["sandbox-receipts.ndjson", "operational journal does not confer a derivative resource lease"],
+    ...LOCAL_ONLY_RUN_FILES,
 ]);
 const PNG_MAGIC = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
 function hash(bytes) {

package/dist/keys/env-file.d.ts

@@ -11,5 +11,9 @@ export interface EnvFileLoadResult {
         message: string;
     };
 }
+/** Records in `env` the names a `--dotenv` file set there. */
+export declare function recordDotenvNames(env: NodeJS.ProcessEnv, names: readonly string[]): void;
+/** The names `--dotenv` set in `env`, as recordDotenvNames recorded them. */
+export declare function dotenvSetNames(env: Readonly<Record<string, string | undefined>>): Set<string>;
 export declare function loadEnvFile(cwd: string, envFile: string, env?: NodeJS.ProcessEnv): Promise<EnvFileLoadResult>;
 export {};

package/dist/keys/env-file.js

@@ -2,6 +2,23 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 const ENV_FILE_RESULT_SCHEMA = "humanish.env-file-result.v1";
 const envNamePattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Names a `--dotenv` file set, kept as a comma list in the environment the values went into, so a
+ * process humanish starts with that environment (a run the TUI launches) knows them too. A
+ * host-side participant (the Claude Code local agent) never gets these names, even ones it would
+ * otherwise keep, such as a proxy.
+ */
+const DOTENV_NAMES = "HUMANISH_DOTENV_NAMES";
+/** Records in `env` the names a `--dotenv` file set there. */
+export function recordDotenvNames(env, names) {
+    if (names.length === 0)
+        return;
+    env[DOTENV_NAMES] = [...new Set([...dotenvSetNames(env), ...names])].join(",");
+}
+/** The names `--dotenv` set in `env`, as recordDotenvNames recorded them. */
+export function dotenvSetNames(env) {
+    return new Set((env[DOTENV_NAMES] ?? "").split(",").filter((name) => name.length > 0));
+}
 export async function loadEnvFile(cwd, envFile, env = process.env) {
     const resolvedCwd = path.resolve(cwd);
     const envPath = path.resolve(resolvedCwd, envFile);

package/dist/keys/key-resolution.js

@@ -21,6 +21,7 @@ import { chmodSync, closeSync, constants as fsConstants, existsSync, ftruncateSy
 import { homedir } from "node:os";
 import path from "node:path";
 import { loadEnvFile } from "./env-file.js";
+import { cli } from "../cli/invocation.js";
 /** The only names implicit discovery may fill (and `humanish keys set` may store). Everything
  *  else in an overlay/store file is ignored-and-named: a repo-planted NODE_OPTIONS/LD_PRELOAD
  *  must never enter process env off a file the operator did not explicitly pass (an explicit
@@ -235,16 +236,16 @@ function storeLabel(env, deps) {
 export function missingKeyHint(name) {
     switch (name) {
         case "E2B_API_KEY":
-            return "run `e2b auth login`, or `humanish keys set e2b`";
+            return `run \`e2b auth login\`, or \`${cli("keys set e2b")}\``;
         case "GH_TOKEN":
         case "GITHUB_TOKEN":
-            return "run `gh auth login`, or `humanish keys set github`";
+            return `run \`gh auth login\`, or \`${cli("keys set github")}\``;
         case "OPENAI_API_KEY":
-            return "run `humanish keys set openai`";
+            return `run \`${cli("keys set openai")}\``;
         case "ANTHROPIC_API_KEY":
-            return "run `humanish keys set anthropic`";
+            return `run \`${cli("keys set anthropic")}\``;
         default:
-            return `run \`humanish keys set ${name}\``;
+            return `run \`${cli(`keys set ${name}`)}\``;
     }
 }
 /** One shared suffix for *_KEYS_MISSING messages: where discovery looked, and what fills each

package/dist/observer/data.d.ts

@@ -1,5 +1,6 @@
 import { type ActorEnding } from "../actors/stop-cause.js";
 import type { RunBundle, RunCostSummary, RunEvent, RunSimulation } from "../run/bundle.js";
+import { type RunDisplay } from "../run/display.js";
 import type { RunStream, RunStreamKind } from "../run/streams.js";
 export declare const OBSERVER_DATA_SCHEMA = "humanish.observer-data.v1";
 interface ObserverArtifactLink {
@@ -20,7 +21,14 @@ export interface ObserverData {
     run: {
         runId: string;
         mode: RunBundle["mode"];
+        /** The participants' verdict. `display` says whether the run passed. */
         status: RunBundle["review"]["verdict"];
+        /**
+         * How the run reads (runDisplay in src/run/display.ts): `passed` only when the verdict is pass
+         * and run.json's outcome does not say the run failed. Absent in observer-data.json written
+         * before it existed.
+         */
+        display?: RunDisplay;
         title: string;
         createdAt: string;
         simCount: number;
@@ -109,7 +117,12 @@ interface ObserverLaneGroup {
     surface?: string;
     caseGroup?: string;
 }
-export declare function buildObserverData(bundle: RunBundle, generatedAt?: string): ObserverData;
+/**
+ * The Observer's projection of a bundle. `statusRecord` is the run's status.json, read for a
+ * bundle with no outcome in run.json: a run in progress, interrupted, or recorded before run.json
+ * carried its outcome.
+ */
+export declare function buildObserverData(bundle: RunBundle, generatedAt?: string, statusRecord?: unknown): ObserverData;
 /** Refresh presentation from recorded actor evidence, including older exported snapshots. */
 export declare function withObserverEndings(data: ObserverData): ObserverData;
 export {};

package/dist/observer/data.js

@@ -2,6 +2,7 @@ import { actorEnding } from "../actors/stop-cause.js";
 import { isCommsReceivingEvidence, receivingAnalysisContext } from "../comms/receiving-evidence.js";
 import { formatParticipantOutcomes, formatRunTaskFunnel, participantOutcomeDetails, withCuaReviewProvenance, } from "../run/outcomes.js";
 import { cuaGoalSource, CUA_COMPLETION_NOTE } from "../actors/goal-source.js";
+import { bundleDisplayFacts, runDisplay } from "../run/display.js";
 export const OBSERVER_DATA_SCHEMA = "humanish.observer-data.v1";
 /** Discard a forged or stale runtime grant before projecting persisted evidence. */
 export function recordedStreamEmbed(embed) {
@@ -19,7 +20,12 @@ const allKinds = [
     "artifact",
     "summary",
 ];
-export function buildObserverData(bundle, generatedAt = new Date().toISOString()) {
+/**
+ * The Observer's projection of a bundle. `statusRecord` is the run's status.json, read for a
+ * bundle with no outcome in run.json: a run in progress, interrupted, or recorded before run.json
+ * carried its outcome.
+ */
+export function buildObserverData(bundle, generatedAt = new Date().toISOString(), statusRecord) {
     const byKind = Object.fromEntries(allKinds.map((kind) => [kind, 0]));
     const events = [...(bundle.events ?? [])];
     // Analysis cites this source-backed aggregate as context, not a participant
@@ -32,14 +38,17 @@ export function buildObserverData(bundle, generatedAt = new Date().toISOString()
     const streams = (bundle.streams ?? []).map((stream) => {
         const sim = bundle.simulations.find((candidate) => candidate.id === stream.simId) ??
             fallbackSimulation(bundle, stream);
-        // A natural session can finish its protocol while the participant explicitly reports a
-        // blocker. Match the review's typed-outcome rule without rewriting the raw trace or
-        // guessing from prose. Never turn an active or failed harness into a participant outcome.
-        const status = (stream.status === "passed" || stream.status === "complete") &&
-            stream.actor?.completionReason === "goal_satisfied" &&
-            stream.actor.declaredOutcome === "blocked"
-            ? "blocked"
-            : stream.status;
+        // The judge's status for the participant wins where the run recorded one, so a participant
+        // the verdict counted as blocked or as never engaging shows that way here. A bundle written
+        // before the judge's status was recorded keeps the typed-outcome reading: a natural session
+        // that finished while declaring a blocker. Never turn an active or failed harness into a
+        // participant outcome.
+        const status = stream.judgedStatus ??
+            ((stream.status === "passed" || stream.status === "complete") &&
+                stream.actor?.completionReason === "goal_satisfied" &&
+                stream.actor.declaredOutcome === "blocked"
+                ? "blocked"
+                : stream.status);
         byKind[stream.kind] += 1;
         return {
             ...stream,
@@ -77,6 +86,7 @@ export function buildObserverData(bundle, generatedAt = new Date().toISOString()
             runId: bundle.runId,
             mode: bundle.mode,
             status: bundle.review.verdict,
+            display: runDisplay(bundleDisplayFacts(bundle, statusRecord)),
             title: `${bundle.scenario.title} - ${bundle.persona.name}`,
             createdAt: bundle.createdAt,
             simCount: bundle.simCount ?? bundle.simulations.length,

package/dist/observer/exposure.js

@@ -73,7 +73,7 @@ export function validateExposure(surface, request, live) {
         // admit nothing and expose nothing: watch --expose always requires edge auth, and the live-follow
         // preconditions are checked first so `--dry-run`/`--detach`/`--json` fail with the clearer reason.
         if (live && (live.dryRun || live.detach || live.json)) {
-            return fail("EXPOSE_REQUIRES_LIVE_FOLLOW", "watch --expose streams a live desktop over an attached follow channel; it cannot combine with --dry-run, --detach, or --json.");
+            return fail("EXPOSE_REQUIRES_LIVE_FOLLOW", "watch --expose streams a live desktop over an attached follow channel. It cannot combine with --dry-run, --detach or --json, and without an interactive terminal it needs --serve.");
         }
         // --safe is a share_ready library filter for `serve`; watch streams a single live run that is
         // never share_ready, so --safe would silently do nothing here. Reject it rather than ignore it.

package/dist/observer/library.d.ts

@@ -1,3 +1,4 @@
+import type { RunDisplay } from "../run/display.js";
 export interface LibraryHistory {
     latestRunId: string | null;
     runs: Array<{
@@ -5,7 +6,10 @@ export interface LibraryHistory {
         createdAt: string | null;
         mode: string | null;
         href: string;
+        /** The participants' verdict. `display` says whether the run passed. */
         status: string;
+        /** How the run reads (runDisplay in src/run/display.ts); absent when its data could not be read. */
+        display?: RunDisplay;
         /** Current contained status-record observation, separate from the evidence verdict. */
         runtimeState?: "running" | "finished" | "interrupted" | "unknown";
         streamCount: number;