@agentwhy/cli 0.0.0-dev

package/dist/core/policy/policy.js

@@ -0,0 +1,20 @@
+import { matchesGlob } from './glob.js';
+/**
+ * The entry that protects this path, or undefined. An exception wins over every protecting pattern, so a path
+ * someone deliberately excluded stays excluded however many rules would otherwise cover it.
+ */
+export function protectionOf(policy, path) {
+    // A directory is written both ways - `ls secrets` and `cat secrets/x` - while `**/secrets/**` only matches
+    // the form with the separator. Both are tried, so how the command happened to be typed does not decide.
+    const forms = path.endsWith('/') ? [path] : [path, `${path}/`];
+    if (forms.some((form) => policy.allowed.some((pattern) => matchesGlob(form, pattern))))
+        return undefined;
+    return policy.protected.find((entry) => forms.some((form) => matchesGlob(form, entry.pattern)));
+}
+export function protects(policy, path) {
+    return protectionOf(policy, path) !== undefined;
+}
+/** The same policy with only what is kept from the agent: what a hook that stops a command may act on (F57). */
+export function blockingOnly(policy) {
+    return { ...policy, protected: policy.protected.filter((entry) => entry.mode !== 'tell') };
+}

package/dist/core/policy/resolve-policy.js

@@ -0,0 +1,16 @@
+import { DEFAULT_POLICY } from './default-policy.js';
+/**
+ * Chooses the policy: an explicit file, else the environment's own deny rules, else the built-in default.
+ *
+ * **A policy file that cannot be read is an error, never a fallback.** Falling back would run the whole analysis
+ * under rules nobody chose while the header claimed a policy was in force - the failure mode this tool exists to
+ * describe, in its own output. Absence is a different thing from breakage: absence falls through, breakage stops.
+ */
+export function resolvePolicy(candidates) {
+    const { file, settings } = candidates;
+    if (file !== undefined)
+        return 'errors' in file ? { errors: file.errors } : { policy: file.policy };
+    if (settings !== undefined)
+        return { policy: settings };
+    return { policy: DEFAULT_POLICY };
+}

package/dist/core/project-catalogue.js

@@ -0,0 +1 @@
+export {};

package/dist/core/project-root.js

@@ -0,0 +1,133 @@
+/**
+ * One recorded directory is the root. None and several are both "no root" - but they are different answers to
+ * the reader, so they stay different here rather than collapsing into `undefined`.
+ */
+export function projectRootOf(directories) {
+    const distinct = [...new Set(directories)];
+    const [only] = distinct;
+    if (distinct.length === 1 && only !== undefined)
+        return { kind: 'known', path: only };
+    return distinct.length === 0 ? { kind: 'absent' } : { kind: 'ambiguous', count: distinct.length };
+}
+/** How the root itself is shown once paths are relative to it. An empty string would render as no path at all. */
+export const PROJECT_ROOT_ITSELF = '.';
+/** What a path outside the project becomes in a shared report: the signal kept, the location dropped (R3). */
+export const OUTSIDE_THE_PROJECT = 'outside the project';
+/** Either separator: a transcript recorded on Windows carries the other one, and its paths are paths too. */
+const SEPARATOR = /[\\/]/;
+/** The characters a path is made of. What sits next to a match decides whether the match is a path at all. */
+const PATH_CHARACTER = String.raw `[\w.~@+\-\\/]`;
+/**
+ * Absolute means "says where it starts": at the root, at a home directory, or at a drive. Anything else was
+ * recorded **relative to the working directory**, which is to say inside the project - that is what makes
+ * `apps/web/.env` from a shell command a path inside the project and not one above it.
+ */
+function isAbsolute(value) {
+    return value.startsWith('/') || value.startsWith('~') || /^[A-Za-z]:[\\/]/.test(value);
+}
+/** The root without its trailing separator, whichever kind it was written with. */
+function baseOf(root) {
+    return SEPARATOR.test(root.path.slice(-1)) ? root.path.slice(0, -1) : root.path;
+}
+/**
+ * Whether a path walks back up through a `..` segment. Comparing prefixes cannot see one: `<root>/../../.ssh/x`
+ * starts with the root and is above it, and `../../.ssh/x` is relative and is above it too. Both were shown in a
+ * shared report until this was written.
+ *
+ * A segment, never a substring: `..config` and `a..b` are names, not a climb.
+ */
+function climbs(value) {
+    return value.split(SEPARATOR).includes('..');
+}
+function escapeForPattern(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
+}
+/**
+ * How a path is shown: relative to the project root where it lies under one, and exactly as written where it
+ * does not (`specs/2026-09-14-path-display-and-share.md` R1-R3).
+ *
+ * Two things this buys beyond brevity. A reader of a monorepo sees `apps/web/.env` and `packages/widget/.env`
+ * as two files rather than two identical labels. And the part that names the account, the machine and the
+ * employer is not the finding, so it stops being repeated on every line of the report.
+ */
+export function displayPath(value, root) {
+    if (root.kind !== 'known')
+        return value;
+    const base = baseOf(root);
+    if (value === base || (value.length === base.length + 1 && value.startsWith(base)))
+        return PROJECT_ROOT_ITSELF;
+    if (!value.startsWith(base) || !SEPARATOR.test(value.charAt(base.length)))
+        return value;
+    return value.slice(base.length + 1);
+}
+/**
+ * Whether a path can be said to lie inside the project - the question the shared view asks before it decides
+ * to drop a location.
+ *
+ * **Corrected 2026-09-14 after a review.** This used to be "the display path is unchanged, so it is outside",
+ * and that is false for every path a transcript records relative to the working directory: a `grep` line or a
+ * shell argument carries `apps/web/.env`, which no root prefix matches, so the shared view replaced the common
+ * case with a category and merged unrelated files into one node.
+ */
+export function insideProject(value, root) {
+    // A path that climbs names something the root does not contain, whichever end it starts from. It is the one
+    // case where "recorded relative to the working directory" does not mean "inside the project".
+    if (climbs(value))
+        return false;
+    if (!isAbsolute(value))
+        return true;
+    if (root.kind !== 'known')
+        return false;
+    return displayPath(value, root) !== value;
+}
+/**
+ * The same transformation for a path that sits **inside** free text - a delegation description, a label. Without
+ * it the absolute form would simply move out of a path field and into a sentence, which is the failure L010
+ * names: a rule applied to one position rather than to the thing itself.
+ *
+ * The root is replaced only where it **is** the start of a path. `/a/proj` sits inside `/backup/a/proj/x` as
+ * text and names nothing there; replacing it produced `/backupx`, a file that exists nowhere. It is also
+ * replaced when it stands alone, and to the same `.` that a path field would show - one directory cannot be
+ * inside the project in one place and above it in another.
+ */
+export function displayPathsIn(text, root) {
+    if (root.kind !== 'known')
+        return text;
+    const base = escapeForPattern(baseOf(root));
+    const pattern = new RegExp(`(?<!${PATH_CHARACTER})${base}(?:[\\\\/]|(?!${PATH_CHARACTER}))`, 'g');
+    return text.replace(pattern, (match) => (SEPARATOR.test(match.slice(-1)) ? '' : PROJECT_ROOT_ITSELF));
+}
+/**
+ * An absolute path, conservatively: something that says where it starts - the root, a home directory or a
+ * drive - and has at least two segments. Used **only** in the shared view, and only on free text.
+ *
+ * The leading boundary is load-bearing. Without it the rule matched inside a path that had **already** been made
+ * relative - `apps/web/.env` contains `/web/.env` - and a correct display path was destroyed by the step meant
+ * to protect it.
+ *
+ * This is pattern-matching prose, which this project distrusts on principle - so it is pointed in the safe
+ * direction. Over-matching costs a reader some detail in a report they chose to share; under-matching puts an
+ * account name on a slide. A URL is over-matched on purpose rather than carved out with a second rule.
+ */
+const ABSOLUTE_PATH = /(?<![\w.~@+-])(?:[A-Za-z]:[\\/]|~|\/)[^\s"'`,;:()<>|{}[\]]*[\\/][^\s"'`,;:()<>|{}[\]]+/g;
+/** Free text as a shared report may carry it: nothing above the project root survives, in any position. */
+export function withoutAbsolutePaths(text) {
+    return text.replace(ABSOLUTE_PATH, OUTSIDE_THE_PROJECT);
+}
+/** What a machine-issued identifier becomes in a shared report. */
+export const IDENTIFIER_NOT_SHOWN = 'id not shown';
+/**
+ * A UUID: how a session, a message or a request is named on the machine that recorded it. Used only in the
+ * shared view, on text that is shown - the same place and the same safe direction as `ABSOLUTE_PATH`.
+ */
+const UUID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi;
+/**
+ * Text as a shared report may carry it: no absolute path and no machine-issued identifier, in any position.
+ *
+ * **Added 2026-09-14 after running `start --share` on a real project.** Identifiers were already replaced where the
+ * report emits them, and that was not enough: a session's own transcript can quote another session's records, and
+ * a quoted `uuid` travels inside whatever text carried it.
+ */
+export function forSharing(text) {
+    return withoutAbsolutePaths(text).replace(UUID, IDENTIFIER_NOT_SHOWN);
+}

package/dist/core/provider-titles.js

@@ -0,0 +1,10 @@
+/** Each session recognised by the titles of the AI that wrote it (`2026-09-27-what-codex-wrote.md` X28, step 5). */
+export class ProviderTitles {
+    #titles;
+    constructor(titles) {
+        this.#titles = titles;
+    }
+    recognise(session) {
+        return this.#titles[session.provider].recognise(session);
+    }
+}

package/dist/core/redaction/entropy.js

@@ -0,0 +1,46 @@
+/**
+ * Class C of spec §5.4: entropy alone. It **redacts and never reports** — a high-entropy string is not
+ * evidence of anything, and lesson L001 measured what happens without that rule: in one session, 385 `toolu_`
+ * identifiers and 1264 UUIDs, every one of them above this threshold. An unguarded class C would have produced
+ * over 1600 findings, none of them real.
+ *
+ * The exclusion list is therefore not an optimisation; it is the only thing that makes the class usable.
+ */
+const THRESHOLD_BITS = 4.0;
+const MINIMUM_LENGTH = 20;
+const EXCLUDED = [
+    // The tool's own identifiers - the single most important exclusion on the list (L001).
+    /^toolu_[A-Za-z0-9]{20,}$/,
+    /^msg_[A-Za-z0-9]{10,}$/,
+    /^(agent-)?a[0-9a-f]{16}$/,
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    /^[0-9a-f]{40}$/i,
+    /^[0-9a-f]{64}$/i,
+    /^sha(256|512)-[A-Za-z0-9+/=]+$/,
+    /^data:[\w/+.-]+;base64,/,
+    /^[\w.-]+\.(ts|js|mjs|cjs|css|map|json)$/i,
+    /^https?:\/\//i,
+    /^[~.]{0,2}\//,
+    // A path is not a secret by shape, and a long one is random-looking enough to cross the threshold: a
+    // path like `apps/web/.env.development` was once replaced by a pseudonym, which turned the finding into
+    // gibberish. A slash-separated run of ordinary path characters is a path. The cost is a base64 blob that
+    // happens to contain a slash and no padding, which class A and class B both still see.
+    /^[\w.@+-]+(\/[\w.@+-]+)+$/,
+];
+export function shannonBits(text) {
+    const counts = new Map();
+    for (const character of text)
+        counts.set(character, (counts.get(character) ?? 0) + 1);
+    return [...counts.values()].reduce((bits, count) => {
+        const probability = count / text.length;
+        return bits - probability * Math.log2(probability);
+    }, 0);
+}
+/** High entropy, long enough, and none of the shapes this tool produces by the thousand. */
+export function looksRandom(token) {
+    if (token.length < MINIMUM_LENGTH)
+        return false;
+    if (EXCLUDED.some((pattern) => pattern.test(token)))
+        return false;
+    return shannonBits(token) >= THRESHOLD_BITS;
+}

package/dist/core/redaction/redacted.js

@@ -0,0 +1,4 @@
+/** The only place a `Redacted` comes into being. Not exported beyond this directory. */
+export function brand(text) {
+    return text;
+}

package/dist/core/redaction/redactor.js

@@ -0,0 +1,339 @@
+import { createHash } from 'node:crypto';
+import { displayPath, displayPathsIn, insideProject, forSharing, OUTSIDE_THE_PROJECT, } from '../project-root.js';
+import { looksRandom } from './entropy.js';
+import { brand } from './redacted.js';
+import { CLASS_A, RULESET_VERSION } from './secret-patterns.js';
+import { ValueTrace } from './value-trace.js';
+import { isConfigName, isExcludedValue, isSensitiveName, unquote } from './value-shapes.js';
+const RANK = { knownFormat: 1, urlPassword: 2, sensitiveName: 3, entropy: 4 };
+/** Step 1: a known format. It **ignores every exclusion** - a real `ghp_…` in a `NEXT_PUBLIC_` name is the case
+ * we most want to see. */
+function classAMatches(text) {
+    return CLASS_A.flatMap(({ name, pattern }) => [...text.matchAll(pattern)].map((match) => {
+        // A pattern may keep a prefix - `:_authToken=` stays, the token after it does not.
+        const prefix = typeof match[1] === 'string' ? match[1] : '';
+        return { name, rank: RANK.knownFormat, start: match.index + prefix.length, end: match.index + match[0].length };
+    }));
+}
+/**
+ * Step 2: only the password of a URL, so `postgres://app:[redacted]@db/main` stays readable as a finding.
+ *
+ * The scheme is bounded, and the bound is the whole point. Written as `[\w+.-]*`, the run before `://` was retried
+ * from every position of a line, and a transcript's lines are long - measured at about 31 KB each on real sessions.
+ * That made one line quadratic: a CPU profile of a 65 MB session put **3.7 of its 4.4 seconds inside this one
+ * pattern**, which is most of what `report`, `check`, `start` and the `Stop` hook were spending per run. Bounding the
+ * scheme to what a scheme can be - 32 characters, against `postgres`, `mongodb+srv`, `jdbc` - took the same text from
+ * 113 ms to 1 ms, with the same matches. The password itself stays unbounded: a long one is rare, it is reached only
+ * after a scheme and a host have already matched, and refusing to redact it would be the wrong way to save time.
+ *
+ * The lookbehind is the same argument once more. A bounded scheme is still tried from every letter of a run, which
+ * on 65 MB of text was another 1.3 seconds; a scheme cannot begin in the middle of a *letter* run, so those
+ * positions are refused in one character each. It must be letters only, not `\w` - a scheme glued to a *digit*
+ * (a timestamp, a line number) still begins right there, and excluding digits too silently dropped that password.
+ * Measured on the same line: 6 ms to none at all, and the same matches for `postgres://`, `mongodb+srv://`, a
+ * scheme after `=`, and one welded to a word before it.
+ */
+const URL_PASSWORD = /(?<![A-Za-z])([a-z][\w+.-]{0,31}:\/\/[^\s:/@]+:)([^\s@]+)(?=@)/gi;
+function urlPasswords(text) {
+    return [...text.matchAll(URL_PASSWORD)].map((match) => ({
+        name: 'url-password',
+        rank: RANK.urlPassword,
+        start: match.index + (match[1] ?? '').length,
+        end: match.index + match[0].length,
+    }));
+}
+/**
+ * Steps 3 and 4: a value beside a sensitive name, once the value-shape exclusions have had their say. The key
+ * name is never touched - it is the finding (§5.4).
+ */
+/**
+ * `NAME=value`, `"name": "value"`, `name: value`.
+ *
+ * The name must start at a boundary and hold no dots, which two failures taught: without the boundary,
+ * `apps/web/.env.development:12:KEY=value` read `env.development` as the name and swallowed the rest of the
+ * line as its value, and without the optional quotes a JSON key was never seen at all.
+ */
+const KEY_VALUE = /(^|[\s,;:{[(]["']?)([A-Za-z_][A-Za-z0-9_-]*)(["']?\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;]+)/g;
+/** What a replacement looks like. A value that is already one is not a value: re-reading it mangles the text. */
+const PSEUDONYM = '[redacted:';
+/**
+ * C0 and C1 control characters, and DEL - everything but the tab and the newline a text legitimately carries.
+ *
+ * A transcript is written by the very party the report is about, and a report is read in a terminal. Left in, an
+ * escape sequence of the transcript's choosing reaches that terminal and rewrites what the reader is shown: a
+ * `\u001b[2K\u001b[1G` in an agent's own prose overwrites the verdict line above it. `hooks/hook-output.ts` keeps
+ * the same guard over the one other channel that reaches a terminal, and for the same reason.
+ *
+ * A space, not nothing, so a sequence never welds the words on either side of it into one.
+ */
+const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+function withoutControls(text) {
+    return text.replace(CONTROL, ' ');
+}
+function keyContext(text) {
+    return [...text.matchAll(KEY_VALUE)].flatMap((match) => {
+        const [, prefix = '', name = '', separator = '', value = ''] = match;
+        if (value.startsWith(PSEUDONYM))
+            return [];
+        if (!isSensitiveName(name) || isExcludedValue(value))
+            return [];
+        // The quotes stay in the text; only what they hold is replaced.
+        const bare = unquote(value);
+        const start = match.index + prefix.length + name.length + separator.length + (value.length === bare.length ? 0 : 1);
+        return [{ name: 'value beside a sensitive name', key: name, rank: RANK.sensitiveName, start, end: start + bare.length }];
+    });
+}
+/**
+ * Step 5: entropy. Redacts, never reports, and only after its own exclusions (lesson L001). The token may end
+ * in base64 padding but may not contain `=` inside it: a token that swallows an `=` swallows a whole
+ * `KEY=value` and reports the pair as one anonymous blob.
+ */
+const TOKEN = /[A-Za-z0-9_+/~.-]{20,}={0,2}/g;
+function randomTokens(text) {
+    return [...text.matchAll(TOKEN)]
+        .filter((match) => looksRandom(match[0]))
+        .map((match) => ({
+        name: 'high-entropy value',
+        rank: RANK.entropy,
+        start: match.index,
+        end: match.index + match[0].length,
+    }));
+}
+/**
+ * The boundary. Everything that reaches the report model passes through here, on the way **in** - never on the
+ * way out to a file, because the next renderer would bypass that (spec §5.4, mechanics rule 5).
+ *
+ * Four doors, each narrow and each a decision at its call site:
+ *
+ * - `scan`      — free text that may hold anything.
+ * - `content`   — text that came out of a protected resource: redacted **wholesale**, key names kept.
+ * - `path`      — a path, shown relative to the project root where it lies under one; `--share` is next.
+ * - `term`      — a tool name, a status, a pattern: vocabulary, not content.
+ *
+ * There is no general "trust me" door. A value never appears, a fragment of one never appears (rule 4: a prefix
+ * is leakage too), and the same value always gets the same pseudonym so a reader can see it is the same one
+ * without being told which (rule 3).
+ */
+/**
+ * The two key shapes of a protected resource's lines: `KEY=value` and `"key": value`. The first group is the key with
+ * what joins it to the value, the second the value. `content` replaces the second and `keysIn` reads the first, from
+ * these same expressions. `[ \t]` rather than `\s`: `\s` crosses a newline, so a key with an empty value swallowed
+ * the line below it and deleted the next key's name - the one thing this promises to keep.
+ */
+const ASSIGNED = /([A-Za-z_][A-Za-z0-9_]*[ \t]*=[ \t]*)("[^"]*"|'[^']*'|\S+)/g;
+const QUOTED_KEY = /("[A-Za-z_][A-Za-z0-9_-]*"[ \t]*:[ \t]*)("[^"]*"|[^,\s]+)/g;
+/**
+ * Of matches that overlap, the one of highest precedence - a known format over a password in a URL over a value beside a
+ * sensitive name over an entropy guess - and then by position; the result in the order the matches start. The one
+ * resolution both the redaction and a count of keys use, so the two can never name the same value differently.
+ */
+function strongest(found) {
+    const chosen = [];
+    for (const match of [...found].sort((a, b) => a.rank - b.rank || a.start - b.start || b.end - a.end)) {
+        if (chosen.some((taken) => match.start < taken.end && taken.start < match.end))
+            continue;
+        chosen.push(match);
+    }
+    return chosen.sort((a, b) => a.start - b.start);
+}
+export class Redactor {
+    #salt;
+    #projectRoot;
+    /** The shared view of `specs/2026-09-14-path-display-and-share.md`: nothing above the project root leaves the tool. */
+    #share;
+    /** Hash of a value -> the pseudonym already given to it. The value itself is never kept (rule 6). */
+    #pseudonyms = new Map();
+    #counts = new Map();
+    /** Occurrences, not distinct values: one key seen fifty times is fifty replacements in the output. */
+    #replacements = 0;
+    #protectedContents = 0;
+    constructor(salt, projectRoot = { kind: 'absent' }, share = false) {
+        this.#salt = salt;
+        this.#projectRoot = projectRoot;
+        this.#share = share;
+    }
+    /**
+     * Free text: class A matches are replaced, everything else is left as written - except that a path inside it
+     * is shown the way a path in a path field is (R8). A description that quotes an absolute path is still a
+     * description carrying an absolute path.
+     */
+    scan(text) {
+        const shown = displayPathsIn(withoutControls(text), this.#projectRoot);
+        return brand(this.#scanText(this.#share ? forSharing(shown) : shown));
+    }
+    /**
+     * Text that came out of a protected resource. The scanner recognises the minority of secrets, so nothing here
+     * is trusted to be safe, and the decision is made **line by line**: deciding once for the whole text let a
+     * single `FOO=bar` anywhere hand the rest of the file through untouched.
+     *
+     * A line shaped `KEY=value` or `"key": "value"` keeps its key - the key name is the finding - and loses its
+     * value. A line of any other shape goes whole. A text where no line has a key shape is replaced by its size,
+     * which is all that can be said about it.
+     */
+    content(text) {
+        this.#protectedContents += 1;
+        const lines = withoutControls(text).split('\n');
+        const redacted = lines.map((line) => this.#contentLine(line));
+        if (redacted.every((line, index) => line === lines[index] || line.startsWith('[redacted: line'))) {
+            return brand(`[redacted: content of a protected resource — ${lines.length} lines, ${Buffer.byteLength(text)} bytes]`);
+        }
+        return brand(redacted.join('\n'));
+    }
+    /**
+     * A path is the finding, not the secret, and §7.3 shows it as written. It is still scanned: these come from
+     * splitting untrusted result text, so a value that happens to match a path pattern arrives through this door
+     * as readily as through any other.
+     */
+    path(value) {
+        const cleaned = withoutControls(value);
+        // The shared view drops a location only for a path that says where it starts and is not under the root.
+        // A path recorded relative to the working directory is already inside the project, and asking "did the
+        // string change" instead of "is it inside" turned every one of those into a category.
+        if (this.#share && !insideProject(cleaned, this.#projectRoot))
+            return brand(OUTSIDE_THE_PROJECT);
+        // What reaches this door as a path is not always one. A command, or a fragment of quoted JSON, can be taken
+        // for a candidate and still end in the file a policy protects; it does not start with a root, so it counts as
+        // inside the project - and an absolute path or an identifier further along it was shown whole. Found by
+        // running `start --share` on a real project. A path field is no weaker than a sentence (R8).
+        const shown = displayPath(cleaned, this.#projectRoot);
+        return brand(this.#scanText(this.#share ? forSharing(shown) : shown));
+    }
+    /**
+     * A trace of values read from protected resources (`specs/2026-09-15-what-came-back.md` R3), salted with this run's salt so
+     * that its digests mean nothing outside this one report (rule 6). The values are hashed here and not kept.
+     */
+    trace(values) {
+        return new ValueTrace(values, (run) => createHash('sha256').update(`${this.#salt}:trace:${run}`).digest('hex'));
+    }
+    /**
+     * Vocabulary: a tool name, an outcome, a policy pattern. No value passes here - but a tool name is still read
+     * out of the transcript, so the control characters go, as they do through every other door.
+     */
+    term(value) {
+        return brand(withoutControls(value));
+    }
+    /**
+     * Which known key formats appear in a piece of text, by class name and never by value. This is the `S-shape`
+     * source of §5.4: a secret can be recognised in output that touched no protected path at all, and saying
+     * "a key of this kind came back here" is a fact worth reporting without quoting a character of it.
+     */
+    classesIn(text) {
+        // Entropy never issues a finding on its own (§5.4): it redacts, and it says nothing. Only what was
+        // recognised - a known format, or a value beside a sensitive name - is reported.
+        // The report's threshold, not redaction's: a class B match is worth stating only when the key reads as one a
+        // configuration would carry. Measured on a real session: 139 matches, of which 129 stood beside names from the
+        // repository's own code - `sessionId`, `key`, `secretShapes` - and 10 beside names like `WEBHOOK_SECRET`.
+        return [
+            ...new Set([...classAMatches(text), ...urlPasswords(text), ...keyContext(text)]
+                .filter((match) => match.key === undefined || isConfigName(match.key))
+                .map((match) => match.name)),
+        ];
+    }
+    /**
+     * The names on the keyed lines of a protected resource - `STRIPE_SECRET_KEY` of `STRIPE_SECRET_KEY=sk_…` - and never
+     * their values. They are the same keys `content` keeps, read by the same two expressions, so a name given here is one
+     * the redacted text already shows. Each is scanned like any other text, in case a name is itself a key.
+     */
+    keysIn(text) {
+        const names = new Set();
+        for (const line of withoutControls(text).split('\n')) {
+            if (line.trim() === '' || line.trimStart().startsWith('#'))
+                continue;
+            for (const match of line.matchAll(ASSIGNED))
+                names.add((match[1] ?? '').replace(/[ \t]*=[ \t]*$/, ''));
+            for (const match of line.matchAll(QUOTED_KEY))
+                names.add((match[1] ?? '').replace(/^"|"[ \t]*:[ \t]*$/g, ''));
+        }
+        return [...names].filter((name) => name !== '').map((name) => brand(this.#scanText(name)));
+    }
+    /**
+     * The names of the lines whose value is a key - `STRIPE_SECRET_KEY` of `STRIPE_SECRET_KEY=sk_…`, not `NODE_ENV` of
+     * `NODE_ENV=development` - each with what its value was recognised as (`specs/2026-09-23-the-report-page.md` M2a):
+     * the same resolution `content` redacts by, a known format first and a random value last. A random value is counted
+     * here, where §5.4 lets it issue no finding, because it says only which of a protected file's lines hold a key, of a
+     * file already on the list. Names only, in the order first read, once each; never a value.
+     */
+    keyedIn(text) {
+        const found = new Map();
+        for (const line of withoutControls(text).split('\n')) {
+            if (line.trim() === '' || line.trimStart().startsWith('#'))
+                continue;
+            const secrets = strongest([...classAMatches(line), ...urlPasswords(line), ...keyContext(line), ...randomTokens(line)]
+                .filter((match) => match.key === undefined || isConfigName(match.key)));
+            if (secrets.length === 0)
+                continue;
+            for (const [expression, clean] of [[ASSIGNED, /[ \t]*=[ \t]*$/g], [QUOTED_KEY, /^"|"[ \t]*:[ \t]*$/g]]) {
+                for (const match of line.matchAll(expression)) {
+                    const start = match.index + (match[1] ?? '').length;
+                    const end = start + (match[2] ?? '').length;
+                    const secret = secrets.find((each) => each.start < end && start < each.end);
+                    const name = (match[1] ?? '').replace(clean, '');
+                    if (secret !== undefined && name !== '' && !found.has(name))
+                        found.set(name, secret.name);
+                }
+            }
+        }
+        return [...found].map(([name, key]) => ({ name: brand(this.#scanText(name)), key }));
+    }
+    /**
+     * The key format of each value in a text, one class per value: where two classes match the same value - a Stripe key
+     * standing beside `STRIPE_SECRET_KEY=` - the one the redaction itself would choose wins, the known format. What
+     * `classesIn` lists is every class seen; this is what each key is (`specs/2026-09-23-the-report-page.md` M1), so a
+     * file of Stripe keys is not also said to hold a key nobody can name. In the order the values appear, once each.
+     */
+    keyClassesIn(text) {
+        const found = [...classAMatches(text), ...urlPasswords(text), ...keyContext(text)]
+            .filter((match) => match.key === undefined || isConfigName(match.key));
+        return [...new Set(strongest(found).map((match) => match.name))];
+    }
+    /** What the report header has to say about redaction (§5.4, versioning). */
+    summary() {
+        return {
+            rulesetVersion: RULESET_VERSION,
+            redactions: this.#replacements,
+            distinctValues: this.#pseudonyms.size,
+            protectedContents: this.#protectedContents,
+        };
+    }
+    /**
+     * One pass over the text, not one pass per pattern. Replacing pattern by pattern lets a later pattern match
+     * inside an earlier replacement - `:_authToken=` swallowed the `[redacted: …]` a token pattern had just
+     * written, and left half of it in the output. Matches are collected first, overlaps resolved by taking the
+     * one that starts earliest and reaches furthest, and the text is rebuilt once.
+     */
+    /** Blank lines and comments carry nothing; `=` and `:` shapes keep their key; everything else goes whole. */
+    #contentLine(line) {
+        if (line.trim() === '' || line.trimStart().startsWith('#'))
+            return line;
+        const keyed = line
+            .replace(ASSIGNED, (_, key, value) => `${key}${this.#pseudonym('value from a protected resource', value)}`)
+            .replace(QUOTED_KEY, (_, key, value) => `${key}${this.#pseudonym('value from a protected resource', value)}`);
+        return keyed === line ? `[redacted: line of a protected resource — ${line.length} characters]` : this.#scanText(keyed);
+    }
+    #scanText(text) {
+        const chosen = strongest([...classAMatches(text), ...urlPasswords(text), ...keyContext(text), ...randomTokens(text)]);
+        let output = '';
+        let taken = 0;
+        for (const match of chosen) {
+            output += text.slice(taken, match.start) + this.#pseudonym(match.name, text.slice(match.start, match.end));
+            taken = match.end;
+        }
+        return output + text.slice(taken);
+    }
+    /**
+     * The same value twice is the same pseudonym, so "this key is also in that other file" can be read off the
+     * report. A per-run salt makes the hash useless outside this one report (rule 6).
+     */
+    #pseudonym(className, value) {
+        this.#replacements += 1;
+        const digest = createHash('sha256').update(`${this.#salt}:${value}`).digest('hex');
+        const known = this.#pseudonyms.get(digest);
+        if (known !== undefined)
+            return known;
+        const index = (this.#counts.get(className) ?? 0) + 1;
+        this.#counts.set(className, index);
+        const pseudonym = `[redacted: ${className} #${index}]`;
+        this.#pseudonyms.set(digest, pseudonym);
+        return pseudonym;
+    }
+}

package/dist/core/redaction/secret-patterns.js

@@ -0,0 +1,22 @@
+// v1: class A alone, with content from a protected resource redacted wholesale.
+// v2 (2026-09-14): classes B and C, with the exclusion lists of §5.4 that make them usable at all.
+export const RULESET_VERSION = 2;
+export const CLASS_A = [
+    { name: 'anthropic-key', pattern: /sk-ant-[A-Za-z0-9_-]{32,}/g },
+    { name: 'openai-key', pattern: /sk-(?:proj-)?[A-Za-z0-9]{20,}/g },
+    { name: 'github-token', pattern: /(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}/g },
+    { name: 'gitlab-token', pattern: /glpat-[A-Za-z0-9_-]{10,}/g },
+    { name: 'slack-token', pattern: /xox[baprs]-[A-Za-z0-9-]{10,}|xapp-[A-Za-z0-9-]{10,}/g },
+    { name: 'aws-access-key-id', pattern: /(?:AKIA|ASIA)[A-Z0-9]{16}/g },
+    { name: 'google-key', pattern: /AIza[A-Za-z0-9_-]{35}|ya29\.[A-Za-z0-9_-]{10,}/g },
+    { name: 'stripe-key', pattern: /(?:sk|rk)_live_[A-Za-z0-9]{10,}|whsec_[A-Za-z0-9]{10,}/g },
+    { name: 'supabase-key', pattern: /sbp_[A-Za-z0-9]{10,}/g },
+    { name: 'npm-token', pattern: /npm_[A-Za-z0-9]{36}/g },
+    { name: 'digitalocean-token', pattern: /do[op]_v1_[a-f0-9]{30,}/g },
+    { name: 'sendgrid-key', pattern: /SG\.[A-Za-z0-9_-]{15,}\.[A-Za-z0-9_-]{15,}/g },
+    { name: 'private-key', pattern: /-----BEGIN[A-Z ]*PRIVATE KEY-----[\s\S]*?-----END[A-Z ]*PRIVATE KEY-----/g },
+    // Three base64url segments, the first of which starts a JSON object: `SUPABASE_SERVICE_ROLE_KEY` is one.
+    { name: 'jwt', pattern: /eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]+/g },
+    // The GitHub token that sat in git history since 2024 was an `.npmrc` auth token.
+    { name: 'npmrc-auth-token', pattern: /(:_authToken=)\S+/g },
+];