@agentwhy/cli 0.0.0-dev

package/dist/report/check/actions-digest.js

@@ -0,0 +1,73 @@
+import { byString } from '../../shared/compare.js';
+/** Merges per-session actions by path and route. Most sessions first, then by name, so the order is stable. */
+export function digestOf(actions, context) {
+    const rotate = new PathCounts();
+    const templates = new Set();
+    const onlyInResults = new PathCounts();
+    const unknown = new PathCounts();
+    const routes = new Map();
+    const shapes = new Map();
+    for (const session of actions) {
+        for (const file of session.rotate) {
+            rotate.add(file.path);
+            if (file.template)
+                templates.add(file.path);
+        }
+        for (const path of new Set(session.onlyInResults))
+            onlyInResults.add(path);
+        for (const path of new Set(session.unknown))
+            unknown.add(path);
+        for (const route of session.openRoutes) {
+            const key = `${route.path}\u0000${route.did}`;
+            const known = routes.get(key);
+            routes.set(key, {
+                route: { path: route.path, did: route.did, ...(route.pattern === undefined ? {} : { pattern: route.pattern }), sessions: 0, occurrences: 0 },
+                sessions: (known?.sessions ?? 0) + 1,
+                occurrences: (known?.occurrences ?? 0) + route.occurrences,
+            });
+        }
+        for (const name of session.secretShapes)
+            shapes.set(name, (shapes.get(name) ?? 0) + 1);
+    }
+    const first = actions[0];
+    return {
+        asked: context.asked,
+        sessionsRead: actions.length,
+        sessionsUnreadable: context.sessionsUnreadable,
+        policyKind: context.policyKind,
+        ...(first === undefined ? {} : { policy: first.policy }),
+        rotate: rotate.sorted().map((entry) => (templates.has(entry.path) ? { ...entry, template: true } : entry)),
+        openRoutes: [...routes.values()]
+            .map(({ route, sessions, occurrences }) => ({ ...route, sessions, occurrences }))
+            .sort((a, b) => b.sessions - a.sessions || b.occurrences - a.occurrences || byString(a.path, b.path) || byString(a.did, b.did)),
+        onlyInResults: onlyInResults.sorted(),
+        unknown: unknown.sorted(),
+        refusedAttempts: actions.reduce((sum, session) => sum + session.refusedAttempts, 0),
+        secretShapes: [...shapes].map(([name, count]) => ({ name, count })).sort((a, b) => b.count - a.count || byString(a.name, b.name)),
+        mentions: actions.reduce((sum, session) => sum + session.mentions, 0),
+        ...(context.marks === undefined ? {} : { marks: context.marks }),
+    };
+}
+/**
+ * Whether anything in the digest asks a person to act. Refusals alone do not: they are the rules holding. An unknown
+ * outcome does: it is a question the transcript could not answer.
+ */
+export function needsAction(digest) {
+    return (digest.rotate.length > 0 ||
+        digest.openRoutes.length > 0 ||
+        digest.onlyInResults.length > 0 ||
+        digest.unknown.length > 0 ||
+        digest.secretShapes.length > 0);
+}
+/** How many sessions each path appeared in, most first. */
+class PathCounts {
+    #counts = new Map();
+    add(key) {
+        this.#counts.set(key, (this.#counts.get(key) ?? 0) + 1);
+    }
+    sorted() {
+        return [...this.#counts]
+            .map(([path, sessions]) => ({ path, sessions }))
+            .sort((a, b) => b.sessions - a.sessions || byString(a.path, b.path));
+    }
+}

package/dist/report/check/check-lines.js

@@ -0,0 +1,83 @@
+import { NAMES_PER_FILE } from '../report-model.js';
+const ORDER = ['rotate', 'template', 'unknown', 'route', 'result'];
+/**
+ * The labels that ask a person to do something: a key to change, a template to confirm, an outcome nobody recorded.
+ * The other two say where a path went and ask for nothing. Every page that counts what is left to do counts these.
+ */
+export const TO_DO_LABELS = ['rotate', 'template', 'unknown'];
+/**
+ * `sessions` are expected with marked files already taken out (`actionsAfterMarks`), so a line here is still to do;
+ * `marks` then says which of them had been marked, and lists the history.
+ */
+export function checkWithMarks(sessions, marks) {
+    const base = checkOf(sessions);
+    const rows = base.rows.map((row) => {
+        const mark = marks.standing.get(row.path);
+        return mark === undefined ? row : { ...row, reopened: { result: mark.result, at: mark.at } };
+    });
+    const open = new Set(rows.map((row) => row.path));
+    const history = marks.lines.map(({ mark, status, endedAt }) => ({
+        path: mark.path,
+        label: mark.label,
+        result: mark.result,
+        at: mark.at,
+        ...(marks.keepNotes && mark.note !== undefined && mark.note !== '' ? { note: mark.note } : {}),
+        sessions: mark.sessions.flatMap((id) => {
+            const name = marks.nameOf(id);
+            return name === undefined ? [] : [name];
+        }),
+        status,
+        ...(endedAt === undefined ? {} : { endedAt }),
+        reopened: status === 'standing' && open.has(mark.path),
+    }));
+    return { rows, refusedAttempts: base.refusedAttempts, history, marksUnreadable: marks.unreadable };
+}
+export function checkOf(sessions) {
+    const found = new Map();
+    const note = (path, label, name, keyed = false, read) => {
+        const rank = ORDER.indexOf(label);
+        const row = found.get(path);
+        if (row === undefined) {
+            found.set(path, { rank, sessions: [name], keyed, ...(read === undefined ? {} : { read }) });
+            return;
+        }
+        row.rank = Math.min(row.rank, rank);
+        // One session that read a key from it is enough: the key is what has to be changed.
+        row.keyed ||= keyed;
+        if (read !== undefined)
+            row.read = row.read === undefined ? read : mergeReads(row.read, read);
+        if (!row.sessions.includes(name))
+            row.sessions.push(name);
+    };
+    for (const { name, actions } of sessions) {
+        for (const file of actions.rotate)
+            note(file.path, file.template ? 'template' : 'rotate', name, file.keyed === true, file.read);
+        for (const path of actions.unknown)
+            note(path, 'unknown', name);
+        for (const route of actions.openRoutes)
+            note(route.path, 'route', name);
+        for (const path of actions.onlyInResults)
+            note(path, 'result', name);
+    }
+    const rows = [...found.entries()]
+        .map(([path, row]) => ({ label: ORDER[row.rank] ?? 'result', path, sessions: row.sessions, rank: row.rank, keyed: row.keyed, read: row.read }))
+        .sort((a, b) => a.rank - b.rank || b.sessions.length - a.sessions.length || a.path.localeCompare(b.path))
+        .map(({ label, path, sessions: names, keyed, read }) => ({
+        label,
+        path,
+        sessions: names,
+        ...(keyed ? { keyed: true } : {}),
+        ...(read === undefined ? {} : { read }),
+    }));
+    return { rows, refusedAttempts: sessions.reduce((sum, { actions }) => sum + actions.refusedAttempts, 0) };
+}
+/** Two sessions' reads of one file: every key format and line either saw, in the order first seen. */
+function mergeReads(a, b) {
+    const keyed = new Map([...a.keyed, ...b.keyed].map((line) => [line.name + '\u0000' + line.key, line]));
+    return {
+        keys: [...new Set([...a.keys, ...b.keys])],
+        names: [...new Set([...a.names, ...b.names])].slice(0, NAMES_PER_FILE),
+        keyed: [...keyed.values()].slice(0, NAMES_PER_FILE),
+        ...(a.mixed === true || b.mixed === true ? { mixed: true } : {}),
+    };
+}

package/dist/report/check/mark-request.js

@@ -0,0 +1,90 @@
+import { NOTE_LIMIT, resultAllowed, standingMarks } from './marks.js';
+/** How many lines a refused mark offers as the ones it could have meant. */
+const SUGGESTIONS = 8;
+const LABEL = {
+    rotate: 'ROTATE',
+    template: 'CHECK',
+    unknown: 'UNKNOWN',
+    route: 'REACHED',
+    result: 'IN RESULT',
+};
+const RESULT = {
+    rotated: 'rotated',
+    'not-secret': 'not a real secret',
+    handled: 'handled',
+    'not-private': 'not private',
+};
+/** A note is one line a person typed; `undefined` when it may be recorded. */
+export function noteProblem(note) {
+    const trimmed = note?.trim();
+    return trimmed !== undefined && (trimmed.length > NOTE_LIMIT || /[\r\n]/.test(trimmed))
+        ? { outcome: 'mark-refused', output: `A note is one line of at most ${NOTE_LIMIT} characters. Nothing was recorded.\n` }
+        : undefined;
+}
+/**
+ * Records a mark against the lines of a check (`worth-running-every-day` R31, R35), for `check --mark` and for the
+ * served page alike (R52): the same rules, the same words. `lines` name sessions by id, and are the check before marks.
+ */
+export async function recordMark(store, lines, request, context) {
+    const problem = noteProblem(request.note);
+    if (problem !== undefined)
+        return problem;
+    const note = request.note?.trim();
+    const line = lines.find((row) => row.path === request.path);
+    if (line === undefined) {
+        const names = lines.slice(0, SUGGESTIONS).map((row) => `  ${LABEL[row.label]}  ${row.path}`);
+        return refused(`${request.path} is not a line of the check for sessions active since ${context.asked}. Nothing was recorded.\n` +
+            (names.length === 0 ? 'The check has no lines in this range.\n' : `Its lines are:\n${names.join('\n')}\n`) +
+            (lines.length > SUGGESTIONS ? `  and ${lines.length - SUGGESTIONS} more (agentwhy check --full)\n` : '') +
+            'A file reached earlier than that is marked with a wider range: --since 30d\n');
+    }
+    if (!resultAllowed(line, request.result)) {
+        return refused(request.result === 'not-secret'
+            ? `${request.path} is a ${LABEL[line.label]} line: a value from it was in an agent's context, so it is marked rotated, not "not a real secret". Nothing was recorded.\n`
+            : `A key was read from ${request.path}, so it is marked rotated once the key is changed, not "${RESULT[request.result]}". Nothing was recorded.\n`);
+    }
+    const written = await store.append({
+        kind: 'mark',
+        path: line.path,
+        label: line.label,
+        result: request.result,
+        at: context.now,
+        ...(note === undefined || note === '' ? {} : { note }),
+        sessions: line.sessions,
+    });
+    if (!written)
+        return { outcome: 'mark-failed', output: 'The mark could not be written, so nothing was recorded.\n' };
+    return {
+        outcome: 'marked',
+        output: `Marked ${line.path} as ${RESULT[request.result]} on ${timeOf(context.now)}.\n` +
+            `It leaves To do until a session active after this reaches the file again. Nothing checks that the key itself changed.\n` +
+            `History: agentwhy start --since ${context.asked}    Undo: agentwhy check --unmark ${quoted(line.path)}\n`,
+    };
+}
+/** Undoes a standing mark by appending, never by removing (R34). */
+export async function recordUnmark(store, path, now) {
+    const reading = await store.read();
+    if (reading.failed)
+        return { outcome: 'mark-failed', output: 'The record of marks could not be read, so nothing was undone.\n' };
+    const standing = standingMarks(reading.records);
+    const mark = standing.get(path);
+    if (mark === undefined) {
+        const names = [...standing.keys()].slice(0, SUGGESTIONS).map((marked) => `  ${marked}`);
+        return refused(`${path} has no standing mark. Nothing was recorded.\n` +
+            (names.length === 0 ? 'Nothing is marked in this project.\n' : `Marked now:\n${names.join('\n')}\n`));
+    }
+    const written = await store.append({ kind: 'unmark', path: mark.path, at: now });
+    if (!written)
+        return { outcome: 'mark-failed', output: 'The undoing could not be written, so the mark still stands.\n' };
+    return { outcome: 'marked', output: `${mark.path} is back in To do. The mark of ${timeOf(mark.at)} stays in History, shown as undone.\n` };
+}
+function refused(output) {
+    return { outcome: 'mark-refused', output };
+}
+/** A path as a shell reads it back: in single quotes, with a quote inside closed and reopened. */
+function quoted(path) {
+    return `'${path.replaceAll("'", "'\\''")}'`;
+}
+function timeOf(epoch) {
+    return new Date(epoch).toISOString().slice(0, 16).replace('T', ' ') + ' UTC';
+}

package/dist/report/check/marks.js

@@ -0,0 +1,84 @@
+/** The mark that stands for each path: the last mark of it, unless an unmark came after (R34). */
+export function standingMarks(records) {
+    const standing = new Map();
+    for (const record of records) {
+        if (record.kind === 'mark')
+            standing.set(record.path, record);
+        else
+            standing.delete(record.path);
+    }
+    return standing;
+}
+/** Every mark ever made, newest first, with what became of it - the record shows what was done and undone (R34, R36). */
+export function markLines(records) {
+    const lines = [];
+    const open = new Map();
+    for (const record of records) {
+        const previous = open.get(record.path);
+        if (previous !== undefined) {
+            previous.status = record.kind === 'mark' ? 'replaced' : 'undone';
+            previous.endedAt = record.at;
+            open.delete(record.path);
+        }
+        if (record.kind === 'mark') {
+            const line = { mark: record, status: 'standing' };
+            lines.push(line);
+            open.set(record.path, line);
+        }
+    }
+    return lines.sort((a, b) => b.mark.at - a.mark.at);
+}
+/**
+ * A session's actions without the files a standing mark covers - when the session was last active no later than the
+ * mark. A session active after it keeps the file, so a file reached again comes back, counted in the sessions since
+ * (R35). Refusals, key shapes and mentions name no file and are kept whole.
+ */
+export function actionsAfterMarks(actions, lastActive, marks) {
+    const hidden = (path) => {
+        const mark = marks.get(path);
+        return mark !== undefined && lastActive <= mark.at;
+    };
+    return {
+        ...actions,
+        rotate: actions.rotate.filter((file) => !hidden(file.path)),
+        openRoutes: actions.openRoutes.filter((route) => !hidden(route.path)),
+        onlyInResults: actions.onlyInResults.filter((path) => !hidden(path)),
+        unknown: actions.unknown.filter((path) => !hidden(path)),
+    };
+}
+/** The paths a session's actions name, whatever the label. */
+export function pathsOf(actions) {
+    return new Set([
+        ...actions.rotate.map((file) => file.path),
+        ...actions.openRoutes.map((route) => route.path),
+        ...actions.onlyInResults,
+        ...actions.unknown,
+    ]);
+}
+/**
+ * What the marks did to a range: how many standing marks took a file out of it entirely, and which marked files a
+ * later session brought back (R35). Only marks whose file this range reached at all are counted.
+ */
+export function marksInRange(before, after, standing) {
+    const reached = new Set(before.flatMap((actions) => [...pathsOf(actions)]));
+    const still = new Set(after.flatMap((actions) => [...pathsOf(actions)]));
+    const inRange = [...standing.values()].filter((mark) => reached.has(mark.path));
+    return {
+        done: inRange.filter((mark) => !still.has(mark.path)).length,
+        reopened: inRange.filter((mark) => still.has(mark.path)),
+    };
+}
+/**
+ * A result means something only for some lines (R31, F25, F50): a key that was in an agent's context is not cleared by
+ * calling it fake, and a file a key was read from is not closed as "handled" or "not private" - the key is what has to
+ * change. *Rotated* fits every line; *not a real secret* a template's.
+ */
+export function resultAllowed(row, result) {
+    if (result === 'rotated')
+        return true;
+    if (result === 'not-secret')
+        return row.label === 'template';
+    return row.keyed !== true;
+}
+/** The longest note kept, in characters. A note says what was done; it is not a place for a key. */
+export const NOTE_LIMIT = 200;

package/dist/report/check/render/text-digest-renderer.js

@@ -0,0 +1,332 @@
+import { paint } from '../../../shared/colour.js';
+import { table } from '../../../shared/text-table.js';
+import { needsAction } from '../actions-digest.js';
+const INDENT = 2;
+/** How many files the brief view names before it says how many more there are (R15a). */
+const BRIEF_ROWS = 5;
+/**
+ * How wide a path may be drawn in the brief view. One long path used to set the column for every row, so five short
+ * paths were pushed across the screen by the sixth. The end of a path is what tells files apart, so the front is what
+ * gives way; the full view and the report print it whole.
+ */
+const PATH_WIDTH = 46;
+/**
+ * What to do about an open route depends on where the rules came from (R13). A rule a person can add is named only
+ * where the person has no rules the tool read; a settings file already has them, and the route is the problem.
+ */
+const OPEN_ROUTE_ADVICE = {
+    settings: () => [
+        'Your deny rules cover these paths, and a route they do not name reached them: a deny rule names a tool, not a',
+        'file. agentwhy init --refuse refuses a shell command that names one of these paths or searches through it. A',
+        'path built at run time still passes; only a boundary below the agent - file permissions, a sandbox - closes',
+        'every route.',
+    ],
+    default: (digest) => {
+        const patterns = [...new Set(digest.openRoutes.flatMap((route) => (route.pattern === undefined ? [] : [route.pattern])))];
+        return [
+            'No deny rules were read, so the built-in default decided what is protected, and nothing refused these calls.',
+            'To have Claude Code refuse file tools on them, add to "permissions.deny" in .claude/settings.json:',
+            ...patterns.map((pattern) => `${' '.repeat(INDENT)}"Read(${pattern})"`),
+            'then read sessions under it: --settings .claude/settings.json. A shell command still passes a Read rule;',
+            'agentwhy init --refuse covers a command line that names the path.',
+        ];
+    },
+    file: () => [
+        'Your policy file protects these paths, and nothing refused these calls. agentwhy reads that file; Claude Code',
+        'enforces only "permissions.deny" in its settings.',
+    ],
+};
+/** What the brief view says about one file, strongest first. The label leads, so a column of them reads down. */
+/** The tool's own word for each kind of line, as `check` prints it; To fix's developer details read the same table. */
+export const LABELS = {
+    rotate: 'ROTATE',
+    template: 'CHECK',
+    unknown: 'UNKNOWN',
+    route: 'REACHED',
+    result: 'IN RESULT',
+};
+/** Strongest first. A file is shown once, under the strongest thing known about it. */
+const ORDER = ['rotate', 'template', 'unknown', 'route', 'result'];
+export class TextDigestRenderer {
+    #view;
+    #colour;
+    /** Colour is decided in the shell and handed here, as the report's is (`findings-worth-reading` R15). */
+    constructor(view, options = {}) {
+        this.#view = view;
+        this.#colour = options.colour === true;
+    }
+    render(digest) {
+        const lines = this.#view === 'full' ? full(digest) : this.#view === 'counts' ? counts(digest) : brief(digest);
+        return `${(this.#colour ? colourise(lines) : lines).join('\n')}\n`;
+    }
+}
+/**
+ * The answer on one screen (R15a): a heading, one line per file with the strongest thing known about it, and where the
+ * rest is. A file reached, seen in a result and carrying a value is **one** line, not three - the sections of the full
+ * view describe the same handful of files, and reading them as separate findings is how a short answer became a wall.
+ */
+function brief(digest) {
+    const heading = headingOf(digest);
+    if (heading !== undefined)
+        return heading;
+    const rows = briefRows(digest);
+    if (rows.length === 0) {
+        return [
+            (digest.marks?.done ?? 0) > 0
+                ? `Nothing left to act on: ${read(digest)}${under(digest)}.`
+                : `Nothing to act on: ${read(digest)}${under(digest)}, and no protected file was reached.`,
+            ...unreadableLines(digest),
+            ...(digest.refusedAttempts === 0 ? [] : [`Your rules held: ${plural(digest.refusedAttempts, 'attempt was', 'attempts were')} refused.`]),
+            ...markLines(digest),
+        ];
+    }
+    const shown = rows.slice(0, BRIEF_ROWS);
+    const width = Math.max(...shown.map((row) => LABELS[row.label].length));
+    const pathWidth = Math.max(...shown.map((row) => shorten(row.path).length));
+    return [
+        `agentwhy · ${read(digest)}${under(digest)}`,
+        ...unreadableLines(digest),
+        '',
+        ...table(shown.map((row) => [`${LABELS[row.label].padEnd(width)}  ${shorten(row.path).padEnd(pathWidth)}`, `${row.says}, ${inSessions(row.sessions)}`]), INDENT),
+        ...(rows.length > shown.length ? [`${' '.repeat(INDENT)}and ${rows.length - shown.length} more`] : []),
+        ...(digest.refusedAttempts === 0
+            ? []
+            : [`${' '.repeat(INDENT)}your rules held: ${plural(digest.refusedAttempts, 'attempt was', 'attempts were')} refused`]),
+        ...(digest.mentions === 0
+            ? []
+            : [`${' '.repeat(INDENT)}${plural(digest.mentions, 'path was', 'paths were')} named in text a call carried, which opens no file; not counted`]),
+        ...markLines(digest, INDENT),
+        '',
+        'What each line means, and what to do:  agentwhy check --full',
+        'Dealt with one:                        agentwhy check --mark rotated <path>',
+        `Session by session, in the browser:    agentwhy start --since ${digest.asked}`,
+    ];
+}
+/** One row per file, strongest first: a value seen beats an unknown outcome, which beats a route, which beats a result. */
+function briefRows(digest) {
+    const rows = new Map();
+    const reopened = new Map((digest.marks?.reopened ?? []).map((mark) => [mark.path, mark]));
+    const add = (label, path, says, sessions) => {
+        if (rows.has(path))
+            return;
+        const mark = reopened.get(path);
+        // A marked file is here only because a session after the mark reached it; the count is of those sessions (R35).
+        const again = mark === undefined ? '' : `; marked ${RESULT_WORDS[mark.result]} ${dayOf(mark.at)}, reached again since`;
+        rows.set(path, { label, path, says: says + again, sessions });
+    };
+    for (const file of digest.rotate) {
+        if (file.template === true)
+            add('template', file.path, 'a value was read from this template', file.sessions);
+        else
+            add('rotate', file.path, "a value was in an agent's context", file.sessions);
+    }
+    for (const file of digest.unknown)
+        add('unknown', file.path, 'a call named it, its outcome is not recorded', file.sessions);
+    for (const route of digest.openRoutes)
+        add('route', route.path, `${route.did}, nothing refused it`, route.sessions);
+    for (const file of digest.onlyInResults)
+        add('result', file.path, 'printed by a search, no call named it', file.sessions);
+    return [...rows.values()].sort((a, b) => ORDER.indexOf(a.label) - ORDER.indexOf(b.label) || b.sessions - a.sessions);
+}
+function full(digest) {
+    const heading = headingOf(digest);
+    if (heading !== undefined)
+        return heading;
+    const unreadable = unreadableLines(digest);
+    const refused = refusedLines(digest);
+    if (!needsAction(digest)) {
+        return [
+            (digest.marks?.done ?? 0) > 0
+                ? `Nothing left to act on: ${read(digest)}${under(digest)}.`
+                : `Nothing to act on: ${read(digest)}${under(digest)}, and no protected file was reached.`,
+            ...unreadable,
+            ...refused,
+            ...markLines(digest),
+        ];
+    }
+    return [
+        `agentwhy check - ${read(digest)}${under(digest)}.`,
+        ...unreadable,
+        ...section(digest.rotate.length > 0, 'Rotate', [
+            "A value from these files was in an agent's context: it was sent to the model provider, and it is kept in the",
+            'transcripts on this machine. Rotating the value is the only step that undoes that. A file named as a template is',
+            'marked: it is meant to be committed, so the question there is whether the value in it is real.',
+        ], table(digest.rotate.map((entry) => [entry.path, `${entry.template === true ? 'template · ' : ''}${inSessions(entry.sessions)}`]), INDENT)),
+        ...section(digest.openRoutes.length > 0, 'Open routes', ['These protected paths were reached, and nothing refused the call.'], [...routeRows(digest.openRoutes), '', ...OPEN_ROUTE_ADVICE[digest.policyKind](digest)]),
+        ...section(digest.onlyInResults.length > 0, 'Seen only in results', [
+            'No call named these paths: they appeared in what a command printed, as a recursive search prints them.',
+            'agentwhy init --refuse refuses a grep -r or rg that would read one; a boundary below the agent closes',
+            'every route.',
+        ], pathRows(digest.onlyInResults)),
+        ...section(digest.unknown.length > 0, 'Outcome unknown', [
+            'A call named or printed these protected paths, and its result was not recorded, so whether the file was read cannot',
+            'be established. The report of the session shows which call.',
+        ], pathRows(digest.unknown)),
+        ...section(digest.secretShapes.length > 0, 'Key shapes', ['Results carried something shaped like a known key. The report of the session shows where; the value is never shown.'], table(digest.secretShapes.map((shape) => [shape.name, times(shape.count)]), INDENT)),
+        ...section(digest.mentions > 0, 'Not counted', [
+            `${plural(digest.mentions, 'protected path was', 'protected paths were')} named in text that a call carried - a message, a report, a question -`,
+            'by a tool this version has no profile for. Such a call opens no file, so it is not a route. The report of the',
+            'session shows them, and says the tool was not recognised.',
+        ], []),
+        ...(refused.length === 0 ? [] : ['', ...refused]),
+        ...(markLines(digest).length === 0 ? [] : ['', ...markLines(digest)]),
+        '',
+        `Each session in detail: agentwhy start --since ${digest.asked}`,
+        'Dealt with a file:      agentwhy check --mark rotated <path>   (not-secret for a template)',
+    ];
+}
+/**
+ * The digest as one line of counts, and where the detail is (R17). "Nothing to act on" is said only of sessions that
+ * were read: a range whose sessions all failed is not a clean range (R15). Found by a review.
+ */
+function counts(digest) {
+    const unreadable = unreadableLines(digest, 'in this range', 'here');
+    if (digest.sessionsRead === 0) {
+        return digest.sessionsUnreadable === 0 ? ['No session was active in this range.'] : unreadable;
+    }
+    // One sentence per line: the counts, what the rules held, and what is already dealt with are three answers, and
+    // run together they were one line long enough to wrap twice in a terminal nobody had made wide for it.
+    const held = digest.refusedAttempts === 0 ? [] : [`Your rules held: ${plural(digest.refusedAttempts, 'attempt was', 'attempts were')} refused.`];
+    const done = doneLine(digest);
+    if (!needsAction(digest)) {
+        return [`Nothing to act on in the ${plural(digest.sessionsRead, 'session', 'sessions')} read.`, ...held, ...done, ...unreadable];
+    }
+    const parts = [
+        ...(digest.rotate.length === 0 ? [] : [`${plural(digest.rotate.length, 'file', 'files')} to rotate`]),
+        ...(digest.openRoutes.length === 0 ? [] : [`${plural(digest.openRoutes.length, 'open route', 'open routes')} to a protected path`]),
+        ...(digest.onlyInResults.length === 0 ? [] : [`${plural(digest.onlyInResults.length, 'path', 'paths')} seen only in results`]),
+        ...(digest.unknown.length === 0 ? [] : [`${plural(digest.unknown.length, 'path', 'paths')} with an unknown outcome`]),
+        ...(digest.secretShapes.length === 0 ? [] : [`${plural(digest.secretShapes.reduce((sum, shape) => sum + shape.count, 0), 'key shape', 'key shapes')}`]),
+    ];
+    return [`To act on: ${parts.join(' · ')}`, ...held, ...done, ...unreadable, `What to do: agentwhy check --since ${digest.asked}`];
+}
+/** The answers that are the whole output: an empty range, and a range in which nothing could be read. */
+function headingOf(digest) {
+    if (digest.sessionsRead === 0 && digest.sessionsUnreadable === 0) {
+        return [
+            `No session of this project was active since ${digest.asked}, so there is nothing to check.`,
+            'To look further back: agentwhy check --since 30d',
+        ];
+    }
+    // Every session in range failed: nothing was read, so nothing can be called clear.
+    return digest.sessionsRead === 0 ? unreadableLines(digest) : undefined;
+}
+function unreadableLines(digest, where = 'inside the range', rest = 'below') {
+    if (digest.sessionsUnreadable === 0)
+        return [];
+    const them = digest.sessionsUnreadable === 1 ? 'it' : 'them';
+    return [`${plural(digest.sessionsUnreadable, 'session', 'sessions')} ${where} could not be read, and nothing ${rest} covers ${them}.`];
+}
+function read(digest) {
+    return `${plural(digest.sessionsRead, 'session', 'sessions')} active since ${digest.asked}`;
+}
+function under(digest) {
+    return digest.policy === undefined ? '' : `, read under ${digest.policy}`;
+}
+function refusedLines(digest) {
+    if (digest.refusedAttempts === 0)
+        return [];
+    return [
+        `Your rules held: ${plural(digest.refusedAttempts, 'attempt was', 'attempts were')} refused. A refused Read raises no hook event, so only the`,
+        'transcripts show these.',
+    ];
+}
+function section(shown, heading, explanation, rows) {
+    return shown ? ['', heading, ...explanation, ...(rows.length === 0 ? [] : ['', ...rows])] : [];
+}
+function pathRows(paths) {
+    return table(paths.map((entry) => [entry.path, inSessions(entry.sessions)]), INDENT);
+}
+function routeRows(routes) {
+    const width = Math.max(...routes.map((route) => route.did.length));
+    return table(routes.map((route) => [route.path, `${route.did.padEnd(width)}  ${times(route.occurrences)}, ${inSessions(route.sessions)}`]), INDENT);
+}
+const RESULT_WORDS = { rotated: 'rotated', 'not-secret': 'not a real secret', handled: 'handled', 'not-private': 'not private' };
+/** What the person's marks did to this range, said once, and where the record is shown (R35, R36). */
+function markLines(digest, indent = 0) {
+    const marks = digest.marks;
+    if (marks === undefined)
+        return [];
+    const pad = ' '.repeat(indent);
+    return [
+        ...(marks.done === 0
+            ? []
+            : [`${pad}${plural(marks.done, 'file was', 'files were')} marked done and not reached since; History: agentwhy start --since ${digest.asked}`]),
+        ...(marks.unreadable ? [`${pad}the record of marks could not be read, so nothing marked was left out`] : []),
+    ];
+}
+function doneLine(digest) {
+    const done = digest.marks?.done ?? 0;
+    return done === 0 ? [] : [`${plural(done, 'file', 'files')} marked done.`];
+}
+function dayOf(epoch) {
+    return new Date(epoch).toISOString().slice(0, 10);
+}
+/** A path cut at the front, so what is left still names the file. Never cut in the full view or in a report. */
+function shorten(path) {
+    return path.length <= PATH_WIDTH ? path : `…${path.slice(path.length - PATH_WIDTH + 1)}`;
+}
+function inSessions(count) {
+    return `in ${plural(count, 'session', 'sessions')}`;
+}
+function times(count) {
+    return count === 1 ? 'once' : `${count} times`;
+}
+function plural(count, one, many) {
+    return `${count} ${count === 1 ? one : many}`;
+}
+/** The headings of the full view. Painted, never changed: the word is the heading, the weight only repeats it. */
+const SECTIONS = new Set(['Rotate', 'Open routes', 'Seen only in results', 'Outcome unknown', 'Key shapes', 'Not counted']);
+/** What each label of the brief view means, as colour: a value that left the machine is red, a question is yellow. */
+const LABEL_HUE = {
+    ROTATE: 'red',
+    CHECK: 'yellow',
+    UNKNOWN: 'yellow',
+    REACHED: 'red',
+    'IN RESULT': 'yellow',
+};
+/**
+ * Colour laid over the lines already written (R14): every coloured word is a word, and removing the escapes gives
+ * back exactly what was written without it. Each rule paints one part of a line and never inside another's, so no
+ * escape is ever nested in another.
+ */
+function colourise(lines) {
+    return lines.map((line) => {
+        // The tool's own name, in the colour that marks the tool and never an outcome.
+        const named = /^agentwhy(?: check)? [·-] /.exec(line);
+        if (named !== null)
+            return `${paint('agentwhy', 'indigo')}${paint(line.slice('agentwhy'.length), 'dim')}`;
+        if (SECTIONS.has(line))
+            return paint(line, 'bold');
+        // A range that is clear, and rules that refused something, are the two things that went well.
+        if (/^Nothing (?:left )?to act on/.test(line))
+            return paint(line, 'green');
+        for (const prefix of ['Your rules held:']) {
+            if (line.startsWith(prefix))
+                return `${paint(prefix, 'green')}${line.slice(prefix.length)}`;
+        }
+        // The counts: the heading says there is something to do, the numbers are what to do it about.
+        if (line.startsWith('To act on:')) {
+            return `${paint('To act on:', 'yellow')}${count(line.slice('To act on:'.length))}`;
+        }
+        if (/could not be read/.test(line))
+            return paint(line, 'yellow');
+        // A row of the brief view: the label leads, and says the same thing the colour does.
+        const labelled = /^( {2})(ROTATE|CHECK|UNKNOWN|REACHED|IN RESULT)/.exec(line);
+        if (labelled !== null) {
+            const [, indent = '', label = ''] = labelled;
+            return `${indent}${paint(label, LABEL_HUE[label] ?? 'bold')}${line.slice(indent.length + label.length)}`;
+        }
+        // Where the rest is: the words are the question, the command is the answer to copy.
+        const command = /^(.*?:)( +)(agentwhy .*)$/.exec(line);
+        if (command !== null) {
+            const [, words = '', gap = '', rest = ''] = command;
+            return `${paint(words, 'dim')}${gap}${paint(rest, 'bold')}`;
+        }
+        return line;
+    });
+}
+/** The numbers in a line of counts, marked as the numbers they are. */
+function count(text) {
+    return text.replace(/\b\d+\b/g, (number) => paint(number, 'bold'));
+}