humanish 0.110.1 → 0.110.3

package/dist/cli/io.d.ts

@@ -3,7 +3,7 @@ import { discoverProviderKeys, type DotenvLoad } from "../keys/key-resolution.js
 import { type TelemetryProperties } from "./telemetry.js";
 import type { RunResult } from "../run/results.js";
 export declare const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
-export declare const CLI_VERSION: string;
+export { CLI_VERSION } from "./version.js";
 export interface CliIo {
     writeOut(text: string): void;
     writeErr(text: string): void;
@@ -17,7 +17,8 @@ export declare const DOTENV_OPTION_DESCRIPTION = "Load unset variables from this
 /**
  * The hidden `--env-file <path>` that `--dotenv` replaced. Node scans the whole argv for
  * `--env-file` before a script runs, and stops only at `--` (src/node_dotenv.cc), so a missing file
- * exits 9 through Node and never reaches humanish. `--dotenv` does not collide. Removed in 0.111.0.
+ * exits 9 through Node and never reaches humanish. `--dotenv` does not collide.
+ * Removed in 0.112.0: deprecated in 0.110.0 on 2026-10-03, it stays 30 days and one minor release.
  */
 export declare function envFileAliasOption(): Option;
 /** The dotenv path a command was given: `--dotenv`, or the `--env-file` alias with its warning. */
@@ -41,6 +42,8 @@ export interface StudyCommandOptions {
     port?: string | undefined;
     rerunFailedFrom?: string | undefined;
     runId?: string | undefined;
+    /** watch only: serve and follow the Observer even without an interactive terminal. */
+    serve?: boolean | undefined;
     /** Repo-relative path to an adopter scorer module; overrides review.scorer.ref when set. */
     scorer?: string | undefined;
     expose?: boolean | undefined;

package/dist/cli/io.js

@@ -1,34 +1,26 @@
 import { automaticAnalysisSucceeded, defaultAnalysisOverBudget, } from "../analysis/automatic-completion.js";
 import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
-import { readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
 import { Command, Option } from "commander";
 import { loadEnvFile, recordDotenvNames } from "../keys/env-file.js";
 import { discoverProviderKeys } from "../keys/key-resolution.js";
 import { deriveRunFacts } from "./telemetry.js";
 import { warnAndQueue, withQueuedWarnings } from "./deprecations.js";
 import { forTerminal } from "../routes/terminal/encoding.js";
+import { cli } from "./invocation.js";
 export const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
-function readCliVersion() {
-    const packageJsonPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
-    return typeof packageJson.version === "string" && packageJson.version.trim()
-        ? packageJson.version
-        : "0.0.0";
-}
-export const CLI_VERSION = readCliVersion();
+export { CLI_VERSION } from "./version.js";
 // One text per shared flag, so the same flag reads the same on every command.
 // tests/cli/shared-options.test.ts walks the program and holds every use to these.
 export const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response.";
 export const CWD_OPTION_DESCRIPTION = "Project directory.";
 export const RUN_OPTION_DESCRIPTION = "Run id, or latest.";
 export const DOTENV_OPTION_DESCRIPTION = "Load unset variables from this dotenv file. Values are never printed or saved.";
-const ENV_FILE_RENAMED = "`--env-file` is now `--dotenv`; `--env-file` is removed in 0.111.0.";
+const ENV_FILE_RENAMED = "`--env-file` is now `--dotenv`; `--env-file` is removed in 0.112.0.";
 /**
  * The hidden `--env-file <path>` that `--dotenv` replaced. Node scans the whole argv for
  * `--env-file` before a script runs, and stops only at `--` (src/node_dotenv.cc), so a missing file
- * exits 9 through Node and never reaches humanish. `--dotenv` does not collide. Removed in 0.111.0.
+ * exits 9 through Node and never reaches humanish. `--dotenv` does not collide.
+ * Removed in 0.112.0: deprecated in 0.110.0 on 2026-10-03, it stays 30 days and one minor release.
  */
 export function envFileAliasOption() {
     return new Option("--env-file <path>").hideHelp().conflicts("dotenv");
@@ -147,11 +139,12 @@ export function parseParticipantIds(value) {
  * command: the run-not-found and missing-study messages do.
  */
 const NEXT_COMMAND = {
-    HUMANISH_STUDY_NOT_FOUND: "humanish study list",
+    HUMANISH_STUDY_NOT_FOUND: "study list",
 };
 /** `<command> failed: <message>`, then `code: <CODE>`, then `next: <command>` when one is known. */
 export function formatCliError(command, error) {
-    const next = error.code === undefined ? undefined : NEXT_COMMAND[error.code];
+    const rest = error.code === undefined ? undefined : NEXT_COMMAND[error.code];
+    const next = rest === undefined ? undefined : cli(rest);
     return ([
         `${command} failed: ${error.message}`,
         ...(error.code === undefined ? [] : [`code: ${error.code}`]),
@@ -316,7 +309,7 @@ function overBudgetAnalysisHint(result) {
     const estimate = result.automaticAnalysis?.result?.admission?.estimatedCostUsd ?? null;
     const suggested = Math.ceil(estimate ?? DEFAULT_ANALYSIS_MAX_COST_USD + 1);
     const shown = estimate === null ? "" : ` ($${estimate.toFixed(2)})`;
-    return `analysis: its estimate${shown} is over the default $${DEFAULT_ANALYSIS_MAX_COST_USD} cap, so no request was sent. To analyze this run: humanish analyze --run ${result.runId ?? "latest"} --max-cost ${suggested}\n`;
+    return `analysis: its estimate${shown} is over the default $${DEFAULT_ANALYSIS_MAX_COST_USD} cap, so no request was sent. To analyze this run: ${cli(`analyze --run ${result.runId ?? "latest"} --max-cost ${suggested}`)}\n`;
 }
 export function automaticAnalysisEnvelope(result) {
     if (result === null ||

package/dist/cli/observer-follow.d.ts

@@ -8,7 +8,30 @@ export interface ObserverPlan {
     /** Open the page: the served URL when following, the static file otherwise. */
     shouldOpen: boolean;
     wantsFollow: boolean;
+    /** Set when the command would have followed, but nobody is at a terminal to stop it. */
+    unattended?: boolean;
 }
+/**
+ * Whether a person can stop a served Observer: stdin and stdout are terminals, and no agent runner
+ * claims the session. An agent's shell or a pipe has nobody to press Ctrl-C, so a server there
+ * waits forever. A TTY alone is not enough, since Codex gives the commands it runs a terminal.
+ */
+export declare function personAtTerminal(env?: NodeJS.ProcessEnv): boolean;
+/** Whether `watch` or `observe` serves the Observer and stays attached. */
+export declare function followDecision(args: {
+    wantsMachine: boolean;
+    detach?: boolean | undefined;
+    serve?: boolean | undefined;
+}): {
+    follow: boolean;
+    unattended: boolean;
+};
+/**
+ * The warning a command adds when it printed the Observer and exited because nobody was attached.
+ * It names the reason personAtTerminal found: an agent runner's marker, which can sit beside a real
+ * terminal, or no terminal at all.
+ */
+export declare function unattendedObserverWarning(command: "watch" | "observe", env?: NodeJS.ProcessEnv): string;
 /**
  * Parse --port and decide open and follow. On an invalid port it writes the failure, sets exit
  * code 2 and returns null, so a caller refuses before starting a run.
@@ -20,6 +43,7 @@ export declare function planObserver(args: {
     io: CliIo;
     open?: boolean | undefined;
     port: string;
+    serve?: boolean | undefined;
 }): ObserverPlan | null;
 /** The `open` a run's static Observer render takes: a followed Observer opens its served URL. */
 export declare function staticObserverOpen(plan: ObserverPlan): boolean;

package/dist/cli/observer-follow.js

@@ -1,6 +1,40 @@
 import { Command } from "commander";
 import { serveObserver } from "../observer/render.js";
+import { detectAgentSession } from "../actors/agent-session.js";
 import { formatRunHuman, parseObserverPort, wantsJson, writeResult, humanError, } from "./io.js";
+/**
+ * Whether a person can stop a served Observer: stdin and stdout are terminals, and no agent runner
+ * claims the session. An agent's shell or a pipe has nobody to press Ctrl-C, so a server there
+ * waits forever. A TTY alone is not enough, since Codex gives the commands it runs a terminal.
+ */
+export function personAtTerminal(env = process.env) {
+    return (process.stdin.isTTY === true &&
+        process.stdout.isTTY === true &&
+        detectAgentSession(env) === undefined);
+}
+/** Whether `watch` or `observe` serves the Observer and stays attached. */
+export function followDecision(args) {
+    if (args.detach === true)
+        return { follow: false, unattended: false };
+    if (args.serve === true)
+        return { follow: true, unattended: false };
+    if (args.wantsMachine)
+        return { follow: false, unattended: false };
+    const attended = personAtTerminal();
+    return { follow: attended, unattended: !attended };
+}
+/**
+ * The warning a command adds when it printed the Observer and exited because nobody was attached.
+ * It names the reason personAtTerminal found: an agent runner's marker, which can sit beside a real
+ * terminal, or no terminal at all.
+ */
+export function unattendedObserverWarning(command, env = process.env) {
+    const agent = detectAgentSession(env);
+    const reason = agent === undefined
+        ? "No interactive terminal"
+        : `An agent environment was detected (${agent.marker} is set, which ${agent.runner} sets)`;
+    return `${reason}, so ${command} printed the Observer path and exited instead of serving it until Ctrl-C. Pass --serve to keep serving, or open the file.`;
+}
 /**
  * Parse --port and decide open and follow. On an invalid port it writes the failure, sets exit
  * code 2 and returns null, so a caller refuses before starting a run.
@@ -28,7 +62,13 @@ export function planObserver(args) {
         : args.open === true
             ? true
             : !wantsMachine && process.stdout.isTTY === true;
-    return { port, shouldOpen, wantsFollow: !wantsMachine && args.detach !== true };
+    const decision = followDecision({ wantsMachine, detach: args.detach, serve: args.serve });
+    return {
+        port,
+        shouldOpen,
+        wantsFollow: decision.follow,
+        ...(decision.unattended ? { unattended: true } : {}),
+    };
 }
 /** The `open` a run's static Observer render takes: a followed Observer opens its served URL. */
 export function staticObserverOpen(plan) {
@@ -43,6 +83,9 @@ export async function showObserver(args) {
         server = await serveObserver(rendered, { open: plan.shouldOpen, port: plan.port });
         result = withObserverServer(rendered, server);
     }
+    else if (rendered.ok && plan.unattended === true) {
+        result = { ...rendered, warnings: [...rendered.warnings, unattendedObserverWarning("watch")] };
+    }
     writeResult(args.command, args.io, result, formatObserverHuman);
     args.io.setExitCode(result.ok ? 0 : 2);
     if (result.ok && server) {
@@ -77,8 +120,6 @@ export function formatObserverHuman(result) {
     ].join("\n") + "\n");
 }
 export async function followObserver(io, result, server, options = {}) {
-    io.writeOut(`watching: ${result.serverUrl ?? result.observerUrl ?? result.observerPath}\n`);
-    io.writeOut("watching: press Ctrl-C to stop\n");
     await new Promise((resolve) => {
         const signalTarget = options.signalTarget ?? process;
         const signals = options.signals ?? ["SIGINT", "SIGTERM", "SIGHUP"];
@@ -120,6 +161,10 @@ export async function followObserver(io, result, server, options = {}) {
             handlers.set(signal, handler);
             signalTarget.once(signal, handler);
         }
+        // Print the prompt only once the handlers are in place: a Ctrl-C that arrives sooner would
+        // take Node's default action and end the process without closing the server.
+        io.writeOut(`watching: ${result.serverUrl ?? result.observerUrl ?? result.observerPath}\n`);
+        io.writeOut("watching: press Ctrl-C to stop\n");
     });
 }
 export function exitCodeForSignal(signal) {

package/dist/cli/orientation.js

@@ -17,6 +17,7 @@ import { listRuns } from "../run/stored-runs.js";
 import { plural } from "../run/text.js";
 import { supportsLocalBrowser } from "./first-run-path.js";
 import { PRODUCT_SENTENCE } from "./product-sentence.js";
+import { cli } from "./invocation.js";
 export const ORIENTATION_SCHEMA = "humanish.orientation.v1";
 /**
  * Read the project's state. Pure-ish: it only reads, never writes, and never touches the network or
@@ -69,7 +70,7 @@ function nextCommandsFor(args) {
             ? []
             : [
                 {
-                    command: "humanish migrate --dry-run",
+                    command: cli("migrate --dry-run"),
                     why: `${plural(v2, "study file")} ${v2 === 1 ? "uses" : "use"} humanish.lab.v2, which humanish no longer reads; this lists the conversion, and humanish migrate writes it`,
                 },
             ]),
@@ -77,41 +78,42 @@ function nextCommandsFor(args) {
             ? []
             : [
                 {
-                    command: "humanish study list",
+                    command: cli("study list"),
                     why: `${plural(moved, "study file")} ${moved === 1 ? "is" : "are"} in a labs/ directory, which humanish no longer reads; this names each one and the studies/ directory to move it to`,
                 },
             ]),
     ];
-    // A fix that is already `humanish study list` replaces the plain suggestion of the same command.
+    // A fix that is already `study list` replaces the plain suggestion of the same command.
     const named = new Set(fixes.map((fix) => fix.command));
     return [...fixes, ...nextCommandsForStudies(args).filter((next) => !named.has(next.command))];
 }
 function nextCommandsForStudies(args) {
     const dryRun = {
-        command: "humanish run first-run",
+        command: cli("run first-run"),
         why: "a dry run: no browser or model runs, no keys, no spend",
     };
     if (!args.initialized) {
         return [
             {
-                command: "humanish init --yes",
+                command: cli("init --yes"),
                 why: "write starter studies, personas and an AGENTS.md (--dry-run lists every file first)",
             },
             dryRun,
         ];
     }
-    // The starter live study this host can run. The other starter studies are templates whose subject
-    // still names your-org/your-app, so they are never suggested.
+    // The starter live study this host can run: the hosted try-live study first, since it needs no
+    // local Docker or VM, then the local one where the host shape supports it. The other starter
+    // studies are templates whose subject still names your-org/your-app, so they are never suggested.
     const liveStudy = (supportsLocalBrowser(args.host.platform, args.host.arch)
-        ? ["local-browser", "try-live"]
+        ? ["try-live", "local-browser"]
         : ["try-live"]).find((id) => args.studyIds.includes(id));
     if (!args.hasRun) {
         return [
             dryRun,
             liveStudy === undefined
-                ? { command: "humanish study list", why: "see the studies this project declares" }
+                ? { command: cli("study list"), why: "see the studies this project declares" }
                 : {
-                    command: `humanish doctor --study ${liveStudy}`,
+                    command: cli(`doctor --study ${liveStudy}`),
                     why: `check what the ${liveStudy} study still needs before a live run`,
                 },
         ];
@@ -119,12 +121,12 @@ function nextCommandsForStudies(args) {
     return [
         ...(liveStudy === undefined
             ? []
-            : [{ command: `humanish run ${liveStudy}`, why: "run a real participant against an app" }]),
+            : [{ command: cli(`run ${liveStudy}`), why: "run a real participant against an app" }]),
         {
-            command: "humanish verify --run latest",
+            command: cli("verify --run latest"),
             why: "check the last run's evidence and public-safety gates",
         },
-        { command: "humanish observe --run latest", why: "reopen the last run's Observer" },
+        { command: cli("observe --run latest"), why: "reopen the last run's Observer" },
     ];
 }
 /**
@@ -151,6 +153,6 @@ export function formatOrientationHuman(state) {
         lines.push(`      ${next.why}`);
     }
     lines.push("");
-    lines.push("`humanish --help` lists every command.");
+    lines.push(`\`${cli("--help")}\` lists every command.`);
     return `${lines.join("\n")}\n`;
 }

package/dist/cli/version.d.ts

@@ -0,0 +1 @@
+export declare const CLI_VERSION: string;

package/dist/cli/version.js

@@ -0,0 +1,11 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+function readCliVersion() {
+    const packageJsonPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    return typeof packageJson.version === "string" && packageJson.version.trim()
+        ? packageJson.version
+        : "0.0.0";
+}
+export const CLI_VERSION = readCliVersion();

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

@@ -1,5 +1,12 @@
 /** Undoes JSON and JS escapes, percent-encoding and HTML character references, one pass each. */
 export declare function decodeEscapes(text: string): string;
+/** How scanEncodedText reads text. */
+export interface EncodedTextScanOptions {
+    /** Do not count an encoded binary run as opaque. */
+    readonly allowOpaqueBase64?: boolean;
+    /** Match secret shapes only, leaving local paths out, as a URL's path may look like one. */
+    readonly secretsOnly?: boolean;
+}
 export interface EncodedTextScan {
     /** A secret or private path, in the text or in a decoding of it. */
     readonly sensitive: boolean;
@@ -12,9 +19,7 @@ export interface EncodedTextScan {
  * 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 declare function scanEncodedText(text: string, options?: {
-    allowOpaqueBase64?: boolean;
-}, depth?: number): EncodedTextScan;
+export declare function scanEncodedText(text: string, options?: EncodedTextScanOptions, depth?: number): EncodedTextScan;
 /**
  * scanEncodedText, cached in this process. The key is the sha256 of the scanned string's UTF-16
  * code units, the options and ENCODED_SCAN_VERSION. Encoding as UTF-16LE keeps every code unit,
@@ -22,6 +27,4 @@ export declare function scanEncodedText(text: string, options?: {
  * scan of the same string would give. Repeated verifies of an unchanged file, as serve admission
  * and the Observer render do, skip the scan.
  */
-export declare function scanEncodedTextCached(text: string, options?: {
-    allowOpaqueBase64?: boolean;
-}): EncodedTextScan;
+export declare function scanEncodedTextCached(text: string, options?: EncodedTextScanOptions): EncodedTextScan;

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;
 /**