@agentwhy/cli 0.0.0-dev

package/dist/core/redaction/value-shapes.js

@@ -0,0 +1,81 @@
+/**
+ * The exclusions of spec §5.4 — "the real work here". Without them class B is a noise generator, because a
+ * sensitive name sits beside a harmless value far more often than beside a secret: `SECRET_ENABLED=true`,
+ * `TOKEN_EXPIRY=3600`, `API_KEY_HEADER=X-Api-Key`.
+ *
+ * They run **before** name matching (resolution order, step 3 before step 4). The reverse order redacts
+ * `SECRET_ENABLED=true`, which is the mistake the order exists to prevent.
+ */
+/** A name that describes a secret, or names something public, rather than holding one. */
+const NAME_EXCLUSIONS = [
+    // `NEXT_PUBLIC_SITE_URL` was the prompt of test B2; these are published in client-side code by design.
+    /PUBLIC/i,
+    /\b(PRIMARY|FOREIGN|SORT|PARTITION|CACHE|IDEMPOTENCY)_KEY\b/i,
+    /KEYWORD|KEYCODE|KEYBOARD/i,
+    /_(ENABLED|EXPIRY|TTL|LENGTH|ROUNDS|ALGO|HEADER|NAME|PATH|FILE|PROVIDER|STRATEGY)$/i,
+];
+const SENSITIVE_NAME = /(SECRET|TOKEN|KEY|PASSWORD|PASSWD|PWD|CREDENTIAL|PRIVATE|AUTH|APIKEY|SALT|SIGNING|BEARER|SESSION|COOKIE|DSN|CONNECTION_STRING)/i;
+/** A value of one of these shapes is not a secret, whatever the name beside it says. */
+const VALUE_EXCLUSIONS = [
+    /^(true|false|yes|no|on|off|enabled|disabled|null|none|undefined)$/i,
+    /^-?\d+(\.\d+)?([a-z%]{1,3})?$/i,
+    /^\d+(ms|s|m|h|d|w)(\d+(ms|s|m|h|d|w))*$/i,
+    /^(development|production|staging|test|local|debug|info|warn|error|postgres|postgresql|mysql|redis|sqlite|utf8|utf-8)$/i,
+    /^(v?\d+(\.\d+)*(-[\w.]+)?|latest|next|\^[\w.]+|~[\w.]+)$/i,
+    /^[\w.-]+:[\w.-]+$/,
+    /^([~.]{0,2}\/|[A-Za-z]:\\)/,
+    /^[\w.-]+\.(ts|js|json|ya?ml|md|txt|log|sql|sh)$/i,
+    /^(https?|postgres(ql)?|mysql|redis|mongodb|amqp):\/\//i,
+    /^[\w.+-]+@[\w.-]+\.\w+$/,
+    /^(#[0-9a-f]{3,8}|rgba?\([\d,.\s]+\))$/i,
+    /^[a-z]{2}([_-][A-Za-z]{2,4})?$/,
+    /^[\w.-]+\/[\w.+-]+$/,
+    /^(changeme|your-[\w-]+|replace_?me|todo|example|dummy|test|xxx+|<.*>|\.{3}|)$/i,
+    /^(.)\1*$/,
+];
+/**
+ * A name as configuration writes them: `WEBHOOK_SECRET`, `aws_access_key_id`, `api-key`. Code writes `sessionId`,
+ * `key` and `tokens`, and on one real session those three shapes alone accounted for 62 of 139 class B matches -
+ * names from a repository's own vocabulary, standing beside values that are not secrets.
+ *
+ * This narrows **reporting only** (spec §5.4, two thresholds): redaction keeps the wider rule, because replacing
+ * something that was not a secret costs nothing and missing one costs everything.
+ */
+export function isConfigName(name) {
+    return /^[A-Z][A-Z0-9_]*$/.test(name) || /[_-]/.test(name);
+}
+export function isSensitiveName(name) {
+    return SENSITIVE_NAME.test(name) && !NAME_EXCLUSIONS.some((pattern) => pattern.test(name));
+}
+/** Prose is many words with spaces: a sentence beside a sensitive name is a description, not a credential. */
+export function isExcludedValue(value) {
+    const trimmed = unquote(value.trim());
+    if (trimmed.length < 8)
+        return true;
+    if (trimmed.split(/\s+/).length > 2)
+        return true;
+    if (VALUE_EXCLUSIONS.some((pattern) => pattern.test(trimmed)))
+        return true;
+    // A list is excluded when every item of it is.
+    const items = trimmed.split(',');
+    return items.length > 1 && items.every((item) => isExcludedValue(item.trim()) || item.trim().length < 8);
+}
+/**
+ * The shape exclusions without the length floor. `specs/2026-09-15-what-came-back.md` §5.2 proposes these to decide which values
+ * read from a protected file are too ordinary to trace, and leaves the floor out on purpose: §2 of that specification
+ * shows a real secret may be shorter than 8 characters. Redaction does not use this - rule 1 redacts every
+ * value of a protected resource, whatever its shape.
+ */
+export function isOrdinaryShape(value) {
+    const trimmed = unquote(value.trim());
+    if (trimmed.split(/\s+/).length > 2)
+        return true;
+    if (VALUE_EXCLUSIONS.some((pattern) => pattern.test(trimmed)))
+        return true;
+    const items = trimmed.split(',');
+    return items.length > 1 && items.every((item) => isOrdinaryShape(item.trim()));
+}
+export function unquote(value) {
+    const quoted = /^(["'])(.*)\1$/.exec(value);
+    return quoted?.[2] ?? value;
+}

package/dist/core/redaction/value-trace.js

@@ -0,0 +1,110 @@
+/**
+ * Values read from protected resources, held as salted digests of their runs and asked about other text
+ * (`specs/2026-09-15-what-came-back.md` R3, R4). No value is kept and no run of one (§5.4 rule 6): what is kept is the digest
+ * of each run, and the position of the value it came from in the list the trace was built from.
+ *
+ * **Thresholds** - spec §5.1's proposal, until the measurement closes it: a run of `RUN_ANYWHERE` characters
+ * anywhere in a value, or of `RUN_AT_EDGE` characters at its start or its end, because a prefix and a suffix were
+ * what leaked. A value shorter than `RUN_AT_EDGE` can therefore never be found.
+ */
+export const RUN_ANYWHERE = 12;
+export const RUN_AT_EDGE = 6;
+/**
+ * The multiplier of the cheap fingerprint below. Any odd number works; 33 is the one Bernstein's string hash uses,
+ * and it is picked for nothing more than being widely read.
+ */
+const FINGERPRINT_BASE = 33;
+/**
+ * A cheap, unsalted fingerprint of a run, used only to decide whether the salted digest is worth computing.
+ * `Math.imul` keeps the arithmetic to 32 bits, which is what makes it rollable in constant time per position.
+ */
+function fingerprintOf(run) {
+    let hash = 0;
+    for (let index = 0; index < run.length; index += 1)
+        hash = (Math.imul(hash, FINGERPRINT_BASE) + run.charCodeAt(index)) | 0;
+    return hash;
+}
+export class ValueTrace {
+    /**
+     * Digest of a run -> positions of the values it came from. Public on purpose: everything a trace holds can be
+     * inspected, and a test holds it to rule 6 by inspecting it. A private field would hide from that test too.
+     */
+    anywhere;
+    /** The same, for the run at a value's start and the run at its end. */
+    edges;
+    /**
+     * Fingerprints of the very same runs, for the prefilter in `#scan`. Public for the same reason the maps are: a
+     * number is not a run of a value, and rule 6 is checked by inspecting everything a trace holds.
+     */
+    anywhereFingerprints;
+    edgeFingerprints;
+    #digest;
+    /** `digest` must be salted per run; the redactor is the one place that has the salt, and builds traces. */
+    constructor(values, digest) {
+        this.#digest = digest;
+        const anywhere = new Map();
+        const edges = new Map();
+        const anywhereFingerprints = new Set();
+        const edgeFingerprints = new Set();
+        values.forEach((value, index) => {
+            for (let start = 0; start + RUN_ANYWHERE <= value.length; start += 1) {
+                const run = value.slice(start, start + RUN_ANYWHERE);
+                remember(anywhere, digest(run), index);
+                anywhereFingerprints.add(fingerprintOf(run));
+            }
+            if (value.length >= RUN_AT_EDGE) {
+                for (const run of [value.slice(0, RUN_AT_EDGE), value.slice(-RUN_AT_EDGE)]) {
+                    remember(edges, digest(run), index);
+                    edgeFingerprints.add(fingerprintOf(run));
+                }
+            }
+        });
+        this.anywhere = anywhere;
+        this.edges = edges;
+        this.anywhereFingerprints = anywhereFingerprints;
+        this.edgeFingerprints = edgeFingerprints;
+    }
+    /** Which traced values have a run in `text`, as positions in the list the trace was built from. Never where. */
+    foundIn(text) {
+        const found = new Set();
+        this.#scan(text, RUN_ANYWHERE, this.anywhere, this.anywhereFingerprints, found);
+        this.#scan(text, RUN_AT_EDGE, this.edges, this.edgeFingerprints, found);
+        return found;
+    }
+    /**
+     * Every window of `text`, asked about. The salted digest is the answer, but computing one per position meant a
+     * cryptographic hash per character of every message and result a session holds: measured at 3.6 seconds of one
+     * run on a record-heavy transcript, and it grows with the session. So each window is first fingerprinted by a
+     * hash that rolls in constant time, and only a window whose fingerprint belongs to a traced run is digested.
+     *
+     * The prefilter can only add work, never remove an answer: equal strings always fingerprint alike, so every run
+     * that was there is still digested and still found. A collision costs one digest and is then refused by the map.
+     */
+    #scan(text, length, runs, fingerprints, found) {
+        if (runs.size === 0 || text.length < length)
+            return;
+        // What the leaving character contributes, so it can be taken back out: the base to the power of the window.
+        let leaving = 1;
+        for (let step = 1; step < length; step += 1)
+            leaving = Math.imul(leaving, FINGERPRINT_BASE) | 0;
+        let fingerprint = fingerprintOf(text.slice(0, length));
+        for (let start = 0; start + length <= text.length; start += 1) {
+            if (fingerprints.has(fingerprint)) {
+                for (const index of runs.get(this.#digest(text.slice(start, start + length))) ?? [])
+                    found.add(index);
+            }
+            const next = start + length;
+            if (next >= text.length)
+                return;
+            const without = (fingerprint - Math.imul(text.charCodeAt(start), leaving)) | 0;
+            fingerprint = (Math.imul(without, FINGERPRINT_BASE) + text.charCodeAt(next)) | 0;
+        }
+    }
+}
+function remember(runs, digest, index) {
+    const known = runs.get(digest);
+    if (known === undefined)
+        runs.set(digest, [index]);
+    else if (!known.includes(index))
+        known.push(index);
+}

package/dist/core/review.js

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

package/dist/core/session-catalogue.js

@@ -0,0 +1,19 @@
+/**
+ * What names a session wherever two AIs' sessions meet - a row, a file, a cached report, `report --input`: its id where
+ * Claude Code wrote it, as it always was, and the id after its AI's name otherwise, so equal ids never overwrite each
+ * other (`.ai/plans/2026-09-29-what-codex-wrote.md` step 5). A Claude Code id is a UUID and never starts with an AI's name.
+ */
+export function sessionKey(session) {
+    return session.provider === 'claude-code' ? session.id : `${session.provider}-${session.id}`;
+}
+/** Every AI whose name `sessionKey` puts before an id: a record, so that an AI added to `Provider` must be named here. */
+const NAMED_IN_KEY = { codex: true };
+/**
+ * The id a key was made from. A short form is cut from it, not from the key: the key of every Codex session starts with
+ * the same `codex-`, and so, for minutes at a time, does a UUIDv7 - its first characters are a timestamp. Anything that
+ * is no key, like a `--share` position, is returned as it is.
+ */
+export function idInKey(key) {
+    const named = Object.keys(NAMED_IN_KEY).find((provider) => key.startsWith(`${provider}-`));
+    return named === undefined ? key : key.slice(named.length + 1);
+}

package/dist/core/session-filter.js

@@ -0,0 +1,42 @@
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+const UNIT = { h: HOUR, d: DAY, w: 7 * DAY };
+/**
+ * `7d`, `12h`, `2w`, or a calendar date. **Now is given, never read**: a filter that looks at the clock for itself
+ * gives a different answer to the same command a minute later, and cannot be tested at all.
+ *
+ * A calendar date is midnight UTC. A local midnight would move with the machine the command runs on, and a
+ * range is only worth stating if it means the same thing to whoever reads the page.
+ */
+export function parseSince(text, now) {
+    const relative = /^(\d+)([hdw])$/.exec(text);
+    if (relative !== null) {
+        const amount = Number(relative[1]);
+        const unit = UNIT[relative[2] ?? ''] ?? DAY;
+        if (amount <= 0)
+            return { error: `--since must be more than nothing: ${text}` };
+        return { since: now - amount * unit, asked: text };
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(text)) {
+        const since = Date.parse(`${text}T00:00:00Z`);
+        // The parser rolls an overflowing day into the next month - 2026-02-30 is read as 2 March - so a date is
+        // accepted only if it names itself back. Otherwise the sessions the person meant to include fall out of the
+        // range without a word. Found by a review; the earlier test tried month 13, which the parser already refused.
+        if (Number.isNaN(since) || new Date(since).toISOString().slice(0, 10) !== text) {
+            return { error: `--since is not a calendar date: ${text}` };
+        }
+        return { since, asked: text };
+    }
+    return { error: `--since takes a span such as 7d, 12h or 2w, or a date such as 2026-09-01: ${text}` };
+}
+/**
+ * Sessions on either side of a start. What is compared is when a session was **last written**, so this means
+ * "active since" and not "started since": a session resumed a week later belongs to this week (L008). The page
+ * says so in those words, until a start time is in the format contract.
+ */
+export function splitBySince(items, since) {
+    return {
+        inRange: items.filter((item) => item.modifiedAt >= since),
+        outOfRange: items.filter((item) => item.modifiedAt < since),
+    };
+}

package/dist/core/session-format.js

@@ -0,0 +1,27 @@
+/** Each AI by its product's name, which is the same in every language a page is written in. */
+export const PROVIDER_NAMES = { 'claude-code': 'Claude Code', codex: 'Codex' };
+/**
+ * The one registry that tells formats apart (XD7), shared by every command that reads a session. Formats are tested in
+ * the order given - the stricter rule first - and the first that recognises the input has it. What each command does
+ * with the provider is its own keyed choice, never a fallback: no format's reader runs on an input it did not recognise.
+ */
+export class SessionFormats {
+    #formats;
+    constructor(formats) {
+        const providers = formats.map((format) => format.provider);
+        if (new Set(providers).size !== providers.length)
+            throw new Error('A provider is registered more than once.');
+        this.#formats = formats;
+    }
+    async select(input) {
+        let unavailable = false;
+        for (const format of this.#formats) {
+            const recognition = await format.recognise(input);
+            if (recognition === 'recognised')
+                return { kind: 'recognised', provider: format.provider };
+            if (recognition === 'unavailable')
+                unavailable = true;
+        }
+        return unavailable ? { kind: 'unavailable' } : { kind: 'unknown' };
+    }
+}

package/dist/core/session-model.js

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

package/dist/core/session-reader.js

@@ -0,0 +1,22 @@
+/**
+ * Reads an input with the format its content names (`2026-09-27-what-codex-wrote.md` X2, XD7), through the registry
+ * `doctor` uses. An input every format read and none recognised is read by none: it is never taken for the nearer one.
+ */
+export class FormatSelectingReader {
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async read(input) {
+        const { formats, sources, whenUnavailable } = this.#dependencies;
+        const selection = await formats.select(input);
+        if (selection.kind === 'unknown')
+            return { kind: 'unknown-format' };
+        const provider = selection.kind === 'recognised' ? selection.provider : whenUnavailable;
+        return { kind: 'read', model: await sources[provider].read(input) };
+    }
+}
+/** A reader of one format alone, for a caller only that format concerns. */
+export function readerOf(source) {
+    return { read: async (input) => ({ kind: 'read', model: await source.read(input) }) };
+}

package/dist/core/session-records.js

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

package/dist/core/session-source.js

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

package/dist/core/session-titles.js

@@ -0,0 +1,21 @@
+/**
+ * How many transcripts are read for a title at once. Each read holds up to a megabyte of a transcript, and a
+ * descriptor for it, until it answers; a project with hundreds of sessions asked for all of them at once would
+ * hold all of that at the same moment, for a list that is one line per session.
+ */
+const TITLES_AT_ONCE = 8;
+/**
+ * What every session is recognised by, in the order given, read a few at a time. A row whose title could not be read
+ * is a row a person reads one line slower, never a list that failed: `recognise` answers nothing only for the failures
+ * the file system port translates, and a descriptor limit reached while reading a long list, or a read that fails part
+ * way, would otherwise unwind the whole list. Found by a review: `start` read titles this way and `sessions` asked for
+ * every one at once, with nothing caught.
+ */
+export async function recogniseAll(titles, sessions) {
+    const recognised = [];
+    for (let from = 0; from < sessions.length; from += TITLES_AT_ONCE) {
+        const batch = sessions.slice(from, from + TITLES_AT_ONCE);
+        recognised.push(...(await Promise.all(batch.map((session) => titles.recognise(session).catch(() => ({}))))));
+    }
+    return recognised;
+}

package/dist/core/turn.js

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

package/dist/doctor/codex-doctor.js

@@ -0,0 +1,14 @@
+/** `doctor` on Codex rollouts (X26): measures, renders, and says when nothing it was given was a Codex session. */
+export class CodexDoctor {
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async run(options) {
+        const report = await this.#dependencies.probe.probe(options.input);
+        return {
+            outcome: report.files.recognised > 0 ? 'complete' : 'unknown-format',
+            output: this.#dependencies.renderers[options.format].render(report),
+        };
+    }
+}

package/dist/doctor/doctor-use-case.js

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

package/dist/doctor/format-selecting-doctor.js

@@ -0,0 +1,28 @@
+/**
+ * What `doctor` says of an input no format recognised, in each output format. The JSON is a closed schema of its own: it
+ * names no provider it guessed and nothing the input held.
+ */
+const UNKNOWN_FORMAT = {
+    text: 'agentwhy doctor: the input is neither a Claude Code session nor a Codex session, so it was not read.\n',
+    json: `${JSON.stringify({ schemaVersion: 1, provider: 'unknown' }, null, 2)}\n`,
+};
+/**
+ * `doctor` on whichever format the input is, told by content through the shared registry (`2026-09-27-what-codex-wrote.md`
+ * X2, XD7). This lifts the coupling of `doctor` to the Claude Code adapter (main spec §13.6). An input every format read
+ * and none recognised is read by none.
+ */
+export class FormatSelectingDoctor {
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async run(options) {
+        const { formats, doctors, whenUnavailable } = this.#dependencies;
+        const selection = await formats.select(options.input);
+        if (selection.kind === 'recognised')
+            return doctors[selection.provider].run(options);
+        if (selection.kind === 'unavailable')
+            return doctors[whenUnavailable].run(options);
+        return { outcome: 'unknown-format', output: UNKNOWN_FORMAT[options.format] };
+    }
+}

package/dist/doctor/render/attention/attention-rule.js

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

package/dist/doctor/render/attention/doctor-attention-rules.js

@@ -0,0 +1,28 @@
+import { DamagedMetaFilesRule } from './rules/damaged-meta-files-rule.js';
+import { DamagedTranscriptsRule } from './rules/damaged-transcripts-rule.js';
+import { IncompleteSubagentPairsRule } from './rules/incomplete-subagent-pairs-rule.js';
+import { MissingMainTranscriptRule } from './rules/missing-main-transcript-rule.js';
+import { MissingSpilledResultsRule } from './rules/missing-spilled-results-rule.js';
+import { MultipleWorkingDirectoriesRule } from './rules/multiple-working-directories-rule.js';
+import { UnknownDenialKindsRule } from './rules/unknown-denial-kinds-rule.js';
+import { UnknownLineTypesRule } from './rules/unknown-line-types-rule.js';
+import { UnrecognisedEntriesRule } from './rules/unrecognised-entries-rule.js';
+import { UnusableDirectoriesRule } from './rules/unusable-directories-rule.js';
+/**
+ * The rules behind "Needs attention", in reading order. Unknown variants lead: they are what `doctor` exists to
+ * surface after a Claude Code update. A new finding is a new rule added here; no existing rule changes.
+ */
+export function createDoctorAttentionRules() {
+    return [
+        new UnknownLineTypesRule(),
+        new UnknownDenialKindsRule(),
+        new MultipleWorkingDirectoriesRule(),
+        new MissingMainTranscriptRule(),
+        new UnusableDirectoriesRule(),
+        new DamagedTranscriptsRule(),
+        new IncompleteSubagentPairsRule(),
+        new DamagedMetaFilesRule(),
+        new MissingSpilledResultsRule(),
+        new UnrecognisedEntriesRule(),
+    ];
+}

package/dist/doctor/render/attention/rules/damaged-meta-files-rule.js

@@ -0,0 +1,8 @@
+export class DamagedMetaFilesRule {
+    findings({ meta }) {
+        return [
+            ...(meta.unparsableFiles > 0 ? [`unparsable meta.json files: ${meta.unparsableFiles}`] : []),
+            ...(meta.unreadableFiles > 0 ? [`unreadable meta.json files: ${meta.unreadableFiles}`] : []),
+        ];
+    }
+}

package/dist/doctor/render/attention/rules/damaged-transcripts-rule.js

@@ -0,0 +1,9 @@
+import { transcriptScopes } from '../transcript-scopes.js';
+export class DamagedTranscriptsRule {
+    findings(report) {
+        return transcriptScopes(report).flatMap(([scope, stats]) => [
+            ...(stats.unparsableLines > 0 ? [`unparsable lines in ${scope}: ${stats.unparsableLines}`] : []),
+            ...(stats.unreadableFiles > 0 ? [`unreadable transcript files in ${scope}: ${stats.unreadableFiles}`] : []),
+        ]);
+    }
+}

package/dist/doctor/render/attention/rules/incomplete-subagent-pairs-rule.js

@@ -0,0 +1,6 @@
+export class IncompleteSubagentPairsRule {
+    findings({ sources }) {
+        const { incompletePairs } = sources.subagentFiles;
+        return incompletePairs > 0 ? [`subagents with an incomplete file pair: ${incompletePairs}`] : [];
+    }
+}

package/dist/doctor/render/attention/rules/missing-main-transcript-rule.js

@@ -0,0 +1,5 @@
+export class MissingMainTranscriptRule {
+    findings({ sources }) {
+        return sources.mainTranscript === 'present' ? [] : [`main transcript: ${sources.mainTranscript}`];
+    }
+}

package/dist/doctor/render/attention/rules/missing-spilled-results-rule.js

@@ -0,0 +1,6 @@
+export class MissingSpilledResultsRule {
+    findings({ toolResultReferences }) {
+        const { missing } = toolResultReferences;
+        return missing > 0 ? [`referenced spilled results missing: ${missing}`] : [];
+    }
+}

package/dist/doctor/render/attention/rules/multiple-working-directories-rule.js

@@ -0,0 +1,15 @@
+/**
+ * A session is expected to carry one working directory. Two would mean the project root cannot be read from the
+ * transcript, and every path a report makes relative to it would be relative to a guess.
+ */
+export class MultipleWorkingDirectoriesRule {
+    findings(report) {
+        const { distinct, invalid } = report.workingDirectories;
+        const findings = [];
+        if (distinct > 1)
+            findings.push(`UNKNOWN variant: ${distinct} working directories in one session`);
+        if (invalid > 0)
+            findings.push(`INVALID cwd on ${invalid} lines: not a string`);
+        return findings;
+    }
+}

package/dist/doctor/render/attention/rules/unknown-denial-kinds-rule.js

@@ -0,0 +1,5 @@
+export class UnknownDenialKindsRule {
+    findings({ denials }) {
+        return denials.unknownKinds.map((kind) => `UNKNOWN toolDenialKind: ${kind} (${denials.byKind[kind] ?? 0})`);
+    }
+}

package/dist/doctor/render/attention/rules/unknown-line-types-rule.js

@@ -0,0 +1,6 @@
+import { transcriptScopes } from '../transcript-scopes.js';
+export class UnknownLineTypesRule {
+    findings(report) {
+        return transcriptScopes(report).flatMap(([scope, stats]) => stats.unknownLineTypes.map((type) => `UNKNOWN line type in ${scope}: ${type} (${stats.lineTypes[type] ?? 0})`));
+    }
+}

package/dist/doctor/render/attention/rules/unrecognised-entries-rule.js

@@ -0,0 +1,6 @@
+export class UnrecognisedEntriesRule {
+    findings({ sources }) {
+        const { unrecognisedEntries } = sources;
+        return unrecognisedEntries > 0 ? [`entries the format contract does not recognise: ${unrecognisedEntries}`] : [];
+    }
+}

package/dist/doctor/render/attention/rules/unusable-directories-rule.js

@@ -0,0 +1,12 @@
+export class UnusableDirectoriesRule {
+    findings({ sources }) {
+        const directories = [
+            ['subagents directory', sources.subagentsDirectory],
+            ['tool-results directory', sources.toolResultsDirectory],
+        ];
+        // `not-found` is normal: a session without subagents or spilled results has no such directory.
+        return directories
+            .filter(([, state]) => state === 'unreadable' || state === 'wrong-kind')
+            .map(([name, state]) => `${name}: ${state}`);
+    }
+}

package/dist/doctor/render/attention/transcript-scopes.js

@@ -0,0 +1,6 @@
+export function transcriptScopes({ main, subagents }) {
+    return [
+        ['main session', main],
+        ['subagents', subagents],
+    ];
+}

package/dist/doctor/render/codex-text-doctor-renderer.js

@@ -0,0 +1,97 @@
+import { countsTable, table } from '../../shared/text-table.js';
+const SECTION_INDENT = 2;
+/**
+ * The Codex section of `doctor` as text (`2026-09-27-what-codex-wrote.md` X26): what the files are, who wrote them, how
+ * they join and what they can answer. Every label comes from the closed report, so nothing a record said is printed.
+ */
+export class CodexTextDoctorRenderer {
+    render(report) {
+        const { files, identity, tree, workingDirectories, order } = report;
+        return [
+            'agentwhy doctor · Codex',
+            `format contract v${report.contractVersion}, verified against Codex ${report.verifiedAgainst.join(', ')}`,
+            '',
+            'Needs attention',
+            ...attention(report).map((item) => `${' '.repeat(SECTION_INDENT)}${item}`),
+            '',
+            'Files',
+            ...table([
+                ['found', String(files.found)],
+                ['recognised as Codex sessions', String(files.recognised)],
+                ['not a Codex session', String(files.unknownFormat)],
+                ['could not be read', String(files.unreadable)],
+                ['lines', `${report.lines.total} (${report.lines.unparsable} unparsable)`],
+            ], SECTION_INDENT),
+            '',
+            'Codex versions (first session_meta)',
+            ...countsTable(report.versions, SECTION_INDENT),
+            '',
+            'History modes',
+            ...countsTable(report.historyModes, SECTION_INDENT),
+            '',
+            'Who started each thread',
+            ...countsTable(report.origins, SECTION_INDENT),
+            '',
+            'Identity and tree',
+            ...table([
+                ['ids one file holds', String(identity.uniqueIds)],
+                ['ids several files hold', `${identity.sharedIds} (${identity.filesSharingIds} files, joined to nothing)`],
+                ['file name names another id', String(identity.fileNameDisagrees)],
+                ['later session_meta lines', String(identity.laterMetadata)],
+                ['conversations', String(tree.roots)],
+                ['threads within them', String(tree.descendants)],
+            ], SECTION_INDENT),
+            '  unresolved relations',
+            ...countsTable(tree.unresolved, SECTION_INDENT * 2),
+            '',
+            'Working directories and order',
+            ...table([
+                ['files with several cwd', String(workingDirectories.filesWithSeveral)],
+                ['files with no cwd', String(workingDirectories.filesWithNone)],
+                ['ordinal lower than the line before', String(order.ordinalBackwards)],
+                ['ordinal equal to the line before', String(order.ordinalRepeats)],
+            ], SECTION_INDENT),
+            '',
+            'Line types',
+            ...countsTable(report.lineTypes, SECTION_INDENT),
+            '',
+            'response_item types',
+            ...countsTable(report.responseItems, SECTION_INDENT),
+            '',
+            'event_msg types',
+            ...countsTable(report.events, SECTION_INDENT),
+            '',
+            'item_completed items',
+            ...countsTable(report.items, SECTION_INDENT),
+            '',
+            'Action items by status',
+            ...countsTable(report.itemStatuses, SECTION_INDENT),
+            '',
+            'Command shapes',
+            ...countsTable(report.commandShapes, SECTION_INDENT),
+            '',
+            'What the files can answer (per file)',
+            ...countsTable(report.capabilities, SECTION_INDENT),
+            '',
+        ].join('\n');
+    }
+}
+/** What a reader should look at first: each an unknown or a join that did not hold, said by its count. */
+function attention(report) {
+    const unknown = (counts) => counts['<unknown>'] ?? 0;
+    const findings = [
+        report.files.unknownFormat > 0 ? `${report.files.unknownFormat} file(s) are not Codex sessions and were not read` : '',
+        report.files.unreadable > 0 ? `${report.files.unreadable} file(s) or folder(s) could not be read` : '',
+        report.identity.sharedIds > 0 ? `${report.identity.sharedIds} session id(s) are held by more than one file; nothing joins them` : '',
+        report.identity.fileNameDisagrees > 0 ? `${report.identity.fileNameDisagrees} file name(s) name another id than the file's own` : '',
+        report.workingDirectories.filesWithSeveral > 0 ? `${report.workingDirectories.filesWithSeveral} file(s) carry more than one cwd` : '',
+        report.order.ordinalBackwards > 0 ? `${report.order.ordinalBackwards} line(s) have a lower ordinal than the line before` : '',
+        Object.values(report.tree.unresolved).some((n) => n > 0) ? 'some threads could not be joined to their conversation' : '',
+        unknown(report.versions) > 0 ? `${unknown(report.versions)} file(s) were written by a Codex version this contract was not measured on` : '',
+        unknown(report.historyModes) > 0 ? `${unknown(report.historyModes)} file(s) have an unknown history mode` : '',
+        unknown(report.lineTypes) + unknown(report.responseItems) + unknown(report.events) + unknown(report.items) > 0
+            ? 'records of a kind this contract does not know were counted as <unknown>'
+            : '',
+    ].filter((finding) => finding !== '');
+    return findings.length > 0 ? findings : ['none'];
+}

package/dist/doctor/render/doctor-renderers.js

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

package/dist/doctor/render/json-doctor-renderer.js

@@ -0,0 +1,7 @@
+const JSON_INDENT = 2;
+/** Either provider's closed report, as JSON: its schema is its type, and nothing else is written. */
+export class JsonDoctorRenderer {
+    render(report) {
+        return `${JSON.stringify(report, null, JSON_INDENT)}\n`;
+    }
+}

package/dist/doctor/render/output-format.js

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