@agentwhy/cli 0.3.0 → 0.3.1

package/dist/core/access/protected-access.js

@@ -1,7 +1,8 @@
 import { matchesGlob } from '../policy/glob.js';
 import { protectionOf } from '../policy/policy.js';
-import { commandPathCandidates, fileOperandsIn, printsContentBesideNames, printsContentOnly } from './command-line.js';
+import { commandPathCandidates, fileOperandsIn, printsContentBesideNames, printsContentOnly, simpleCommandsIn } from './command-line.js';
 import { listingPathCandidates } from './listing.js';
+import { shapedLikePath } from './path-shape.js';
 import { pathTokens, stringsIn } from './path-tokens.js';
 import { outputIsClean, outputShowsReach } from './recorded-effect.js';
 import { hitLines } from './search-output.js';
@@ -74,6 +75,8 @@ function targetOutcome(event, printed, shown) {
 }
 /** A search hit with its line number: `path:12:text`. A diagnostic `path: message` has none. */
 const NUMBERED_HIT = /^[^:]+:\d+:/;
+/** A hit of a search of one file, numbered and with no name: `12:text`. */
+const NUMBERED_LINE = /^\d+:/;
 /** How many lines of each file a succeeded search printed (H1, H2, H12): `printedLines`, counted. */
 export function linesPrinted(event, named) {
     return new Map([...printedLines(event, named)].map(([path, lines]) => [path, lines.length]));
@@ -95,6 +98,16 @@ export function printedLines(event, named) {
         const numbered = stringsIn(event.result?.content).join('\n').split('\n').filter((line) => NUMBERED_HIT.test(line)).join('\n');
         for (const hit of hitLines(numbered, false))
             printed.set(hit.path, [...(printed.get(hit.path) ?? []), hit.text]);
+        // H3 where the exit is not known clean (XD4: a cell records none): a numbered search of the one protected file the
+        // call named prints `12:text` for each hit, and no diagnostic opens with a line number - `rg: x: No such file` names
+        // its program first. Those lines are that file's, and nothing else of the output is.
+        const one = [...new Set(named)];
+        if (printed.size === 0 && search.numbered === true && search.names !== 'always' && one.length === 1) {
+            const lines = stringsIn(event.result?.content).join('\n').split('\n').filter((line) => NUMBERED_LINE.test(line))
+                .map((line) => line.replace(NUMBERED_LINE, ''));
+            if (lines.length > 0)
+                printed.set(one[0], lines);
+        }
         return printed;
     }
     const output = stringsIn(event.result?.content).join('\n');
@@ -119,6 +132,86 @@ export function printedLines(event, named) {
     }
     return printed;
 }
+/** A word that names a file by its own shape: a name with an extension or a leading dot, or a path with a folder in it. */
+const NAMES_A_FILE = /[^.]\.[^.]|^\.[^./]|\//;
+/** A count given to an option: `head -n 2 f.csv` reads one file, not a file called `2`. */
+const COUNT = /^\d+$/;
+/** What a pattern or a script holds and a file name does not: `sed 's#^./##'` names no file. */
+const NOT_A_NAME = /[#^$\\|<>!&;]/;
+/**
+ * Folders every tool that makes them makes as folders, named like a file with a leading dot. A listing that does not say
+ * which is which - `find . -maxdepth 1` - lists them beside `.env` and `.npmrc`, and only the name is left to tell.
+ */
+const TOOL_FOLDERS = new Set(['.git', '.claude', '.codex', '.cursor', '.vscode', '.idea', '.github', '.next', '.cache', '.turbo']);
+/**
+ * What one call shows of files no protected pattern matches (`the-report-page.md` P32, changed 2026-10-05 by the
+ * maintainer: every file of a session is a row, so a person sees what else the AI was among, and may make it private).
+ * Read by the rules that find a protected path, so no prose becomes a file:
+ *
+ * - a word of a shell line shaped like a path is a file the call named; the operand of a program that prints a file,
+ *   where the call succeeded, one it read;
+ * - a search hit's path is a file whose lines came back - read where they are what the model was handed (X10);
+ * - a listing's name, by its place: the last field of `ls -l` where its line is no directory's, or a line that is a path
+ *   whole (`ls -1`, `find`, `rg --files`). A word before a colon is a search hit's place, and outside a search it is a
+ *   diagnostic's (`ls: x: No such file`), so it names no file here.
+ *
+ * `.` and `..` are no files. A tool the adapter has no profile for names nothing (R12b).
+ */
+export function everydayReach(event, policy) {
+    if (!event.toolKnown)
+        return [];
+    const found = new Map();
+    const note = (written, how) => {
+        // `./README.md` and `README.md` are one file, and `./app` the bare folder name `app` (2026-10-05, `find | sed`).
+        const path = written.replace(/^(?:\.\/)+/, '');
+        if (path === '' || path === '.' || path === '..' || TOOL_FOLDERS.has(path) || NOT_A_NAME.test(path))
+            return;
+        if (!pathLike(path, { allowWhitespace: false }) || protectionOf(policy, path) !== undefined || protectionOf(policy, written) !== undefined)
+            return;
+        if (found.get(path) !== 'read')
+            found.set(path, how);
+    };
+    const read = event.outcome === 'succeeded' && readsContent(event);
+    const operands = new Set(fileOperandsIn(event.commands));
+    for (const command of event.commands) {
+        // The line's own words - the program and its arguments, never the code an interpreter is handed (`python3 -c "…"`
+        // held `csv.DictReader`) - each a file where its place says so or its shape does (found 2026-10-05).
+        for (const { program, args } of simpleCommandsIn(command)) {
+            for (const word of [program, ...args]) {
+                if (word.startsWith('-') || COUNT.test(word))
+                    continue;
+                // A printer's operand is a file by its place; any other word is one where it holds a name's dot or a folder's
+                // slash - `README.md`, `app/page.tsx` - and never a program (`ls`), a folder (`app`) or a pattern (`TODO`).
+                if (operands.has(word) || NAMES_A_FILE.test(word.replace(/^(?:\.\/)+/, '')))
+                    note(word, read && operands.has(word) ? 'read' : 'named');
+            }
+        }
+    }
+    const content = event.result?.content;
+    if (content === undefined || !outputShowsReach(event))
+        return [...found].map(([path, how]) => ({ path, how }));
+    const output = stringsIn(content).join('\n');
+    const search = searchOf(event);
+    if (search !== undefined) {
+        // A hit's path by its shape too: a cell's `Output:` header reads as a hit on the word before its colon.
+        for (const hit of hitLines(output, search.context)) {
+            if (NAMES_A_FILE.test(hit.path.replace(/^(?:\.\/)+/, '')))
+                note(hit.path, event.result?.stage === 'model' ? 'read' : 'named');
+        }
+    }
+    else if (event.resultShape === 'listing' && !readsContent(event)) {
+        for (const raw of output.split('\n')) {
+            const line = raw.trim();
+            if (line === '')
+                continue;
+            const name = (listingPathCandidates(line)[0] ?? []).find((candidate) => candidate.listed === 'file' || (candidate.listed === undefined && candidate.text === line && shapedLikePath(line) &&
+                NAMES_A_FILE.test(line.replace(/^(?:\.\/)+/, ''))));
+            if (name !== undefined)
+                note(name.text, 'named');
+        }
+    }
+    return [...found].map(([path, how]) => ({ path, how }));
+}
 /**
  * The call is a search that prints what it matched: a shell search read from its command, or a tool that said so. The
  * Grep tool may or may not name the file on its lines, so that is left to what it printed.

package/dist/core/access/recorded-effect.js

@@ -6,6 +6,14 @@ import { readOptions } from './search-reach.js';
  * operands here: `grep` exits 1 for a file it read and found nothing in, and a script exits however it likes.
  */
 const READS_EVERY_OPERAND = new Set(['cat', 'head', 'tail', 'nl']);
+/**
+ * Searches whose exit is documented: 0 where a line matched, 1 where none did, 2 or more where an operand could not be
+ * read. With 0 or 1 recorded, each operand was opened and searched, whatever was printed. Found 2026-10-05: a search of a
+ * tracked file for a name it does not hold exited 1, and the file was "an attempt with no known end". What a search
+ * printed of a file is read from its output (`search-hits-are-reads` H1). `ag`, `ack` and `git grep` are not listed:
+ * their exit on an unreadable operand is not established here.
+ */
+const SEARCHES_EVERY_OPERAND = new Set(['grep', 'egrep', 'fgrep', 'rg']);
 /**
  * `sed` opens its file operands in turn and exits non-zero on one it cannot open, but a script that quits (`q`) stops
  * before the next: with exit 0, only a lone operand is known to have been read. `-e` and `-f` give the script, so every
@@ -29,7 +37,12 @@ const SED_PLAIN_OPTIONS = new Set([
  *   requested path alone is an attempt. What the output itself shows is read per target by `protectedAccesses`.
  */
 export function outcomeOfExecution(call, execution) {
-    if (!call.toolKnown || execution.status !== 'completed')
+    if (!call.toolKnown)
+        return 'unknown';
+    // A search that matched nothing exits 1, which a runtime records as failed: it opened every operand all the same.
+    if (searchedItsOperands(call, execution))
+        return 'succeeded';
+    if (execution.status !== 'completed')
         return 'unknown';
     if (call.written !== undefined)
         return 'succeeded';
@@ -38,6 +51,14 @@ export function outcomeOfExecution(call, execution) {
     const simple = simpleCommandsIn(call.commands[0] ?? '');
     return simple.length === 1 && simple[0] !== undefined && readsItsOperands(simple[0]) ? 'succeeded' : 'unknown';
 }
+function searchedItsOperands(call, execution) {
+    if (execution.status === 'unrecognised' || call.written !== undefined || call.commands.length !== 1)
+        return false;
+    if (execution.exitCode !== 0 && execution.exitCode !== 1)
+        return false;
+    const simple = simpleCommandsIn(call.commands[0] ?? '');
+    return simple.length === 1 && simple[0] !== undefined && SEARCHES_EVERY_OPERAND.has(simple[0].program);
+}
 function readsItsOperands({ program, args }) {
     if (READS_EVERY_OPERAND.has(program))
         return true;

package/dist/report/build-report.js

@@ -1,7 +1,8 @@
 // Copyright 2026 Nessprim Karol Kozer
 // SPDX-License-Identifier: Apache-2.0
-import { programsIn } from '../core/access/command-line.js';
-import { printedLines, printsOnly, protectedAccesses, readsContent, readsContentBesideNames } from '../core/access/protected-access.js';
+import { fileOperandsIn, programsIn } from '../core/access/command-line.js';
+import { everydayReach, printedLines, printsOnly, protectedAccesses, readsContent, readsContentBesideNames } from '../core/access/protected-access.js';
+import { stringsIn } from '../core/access/path-tokens.js';
 import { keyedLines } from '../core/access/protected-values.js';
 import { filesTracedIn, returnsOf, traceValues } from '../core/access/returns.js';
 import { valueUses } from '../core/access/uses.js';
@@ -70,7 +71,9 @@ export function buildReport(model, policy, redactor, view = FULL_VIEW) {
     // other view of this session - the index among them - must answer it with the same number.
     const graph = graphOf(model, accesses, returns, uses, traced, redactor, view);
     const flows = flowsOf(model, accesses, uses, returns, wordsBefore, traced, redactor, view);
-    const tally = tallyOf(accesses, returns, uses, contentsSeenIn(graph, flows));
+    const seen = contentsSeenIn(graph, flows);
+    const printed = new Set(stories.filter((story) => story.read === true).map((story) => story.path)).size;
+    const tally = { ...tallyOf(accesses, returns, uses, seen), ...(seen === 0 && printed > 0 ? { printedUnseen: printed } : {}) };
     return {
         headline: headlineOf(tally, coverageOf(model), redactor),
         tally,
@@ -100,7 +103,8 @@ export function buildReport(model, policy, redactor, view = FULL_VIEW) {
         uses: uses.map((use) => toUse(use, model, redactor, view)),
         flows,
         privateFiles: privateFilesOf(model, accesses, redactor),
-        everydayFiles: everydayFilesOf(model, accesses, redactor),
+        ...everydayFilesOf(model, accesses, policy, redactor, view),
+        fileSteps: fileStepsOf(model, accesses, graph, policy, redactor),
         missing: gaps.map((gap) => redactor.term(missingWords(gap))),
         gaps,
         recorded: recordedOf(model, redactor, view),
@@ -245,30 +249,132 @@ function readInto(file, content, redactor) {
     }
 }
 /**
- * The files no protected pattern matches that a file tool worked on (M6): a known tool whose result is the named
- * file's text, or which writes it. A call whose outcome was not recorded is left out - it may not have reached the
- * file, and a list of what the AI opened must not grow by what it may have opened.
+ * Where each file of the session first came up (`the-order-it-went.md` OW1, OW2): the first action, in the page's order
+ * of AIs - Your AI, then the helpers by their number - and in each AI's own record order, that reached it by any of the
+ * ways its row was made. Files one action reached share its step, and keep the place the action gave them: named in it
+ * first, then as its output printed them. Never ordered by time across AIs (invariant 3).
  */
-function everydayFilesOf(model, accesses, redactor) {
-    const RANK = { changed: 2, read: 1, stopped: 0 };
+function fileStepsOf(model, accesses, graph, policy, redactor) {
+    const ranked = [graph.main, ...[...graph.agents].sort((a, b) => (a.ordinal ?? Infinity) - (b.ordinal ?? Infinity) || a.index - b.index)];
+    const rank = new Map(ranked.map((agent, at) => [agent.index, at]));
+    const agentIndex = new Map(model.agents.map((agent, index) => [agent.id, index]));
+    const byEvent = new Map();
+    for (const access of accesses)
+        byEvent.set(access.eventId, [...(byEvent.get(access.eventId) ?? []), access.path]);
+    const delegating = new Set(model.delegations.map((delegation) => delegation.id));
+    const events = model.events
+        .filter((event) => event.toolKnown && !delegating.has(event.id) && agentIndex.has(event.agentId))
+        .map((event) => ({ event, index: agentIndex.get(event.agentId) }))
+        .sort((a, b) => (rank.get(a.index) ?? Infinity) - (rank.get(b.index) ?? Infinity) || a.index - b.index || a.event.sequence - b.event.sequence);
+    const accessAt = new Map(accesses.map((access) => [access.eventId + '\u0000' + access.path, access]));
+    // One step per file and thing done to it, the first of each: the page puts a row at the one its status came from.
+    const found = new Map();
+    for (const { event, index } of events) {
+        const output = stringsIn(event.result?.content).join('\n');
+        const reach = new Map(everydayReach(event, policy).map((one) => [one.path, one.how]));
+        const paths = [...new Set([...(byEvent.get(event.id) ?? []), ...event.targets, ...reach.keys()])].filter((path) => path !== '');
+        const operands = new Set(fileOperandsIn(event.commands));
+        const howOf = (path) => {
+            const access = accessAt.get(event.id + '\u0000' + path);
+            if (event.outcome === 'blocked' || access?.outcome === 'blocked')
+                return 'stopped';
+            if (access?.outcome === 'unknown')
+                return 'unknown';
+            if (event.written !== undefined && event.targets.includes(path))
+                return 'changed';
+            if ((access?.lines ?? 0) > 0 || reach.get(path) === 'read')
+                return 'read';
+            const opened = (event.resultShape === 'content' && event.targets.includes(path)) || (readsContent(event) && operands.has(path));
+            return event.outcome === 'succeeded' && opened ? 'read' : 'named';
+        };
+        // Named in the action first, then in the order its output printed them.
+        const placed = paths.map((path) => ({ path, at: output.indexOf(path) })).sort((a, b) => a.at - b.at);
+        placed.forEach(({ path }, place) => {
+            const shown = redactor.path(path);
+            const how = howOf(path);
+            if (!found.has(shown + '\u0000' + how))
+                found.set(shown + '\u0000' + how, { path: shown, agentIndex: index, step: event.sequence, place, how });
+        });
+    }
+    return [...found.values()];
+}
+/** How many names only seen a page lists: `find .` in a real project prints thousands, and each would be a row. */
+export const EVERYDAY_NAMES_LISTED = 200;
+/**
+ * EF8, EFD4: the calls kept per everyday file, for the window its row opens. Measured 2026-10-05: a story window is
+ * ~25.6 KB of a page, so twenty entries is the most one row is worth; the rest are counted.
+ */
+export const EVERYDAY_CALLS_KEPT = 20;
+/**
+ * The files no protected pattern matches (M6): a known file tool whose result is the named file's text, or which writes
+ * it - a call whose outcome was not recorded is left out, since a list of what the AI opened must not grow by what it
+ * may have opened. Changed 2026-10-05 by the maintainer (P32): every other file of the session too, as a command and its
+ * output show it (`everydayReach`) - read where a printer opened it, else a name only seen, which is never counted as
+ * opened (P32a). Names past `EVERYDAY_NAMES_LISTED` are counted, not listed.
+ */
+function everydayFilesOf(model, accesses, policy, redactor, view) {
+    const RANK = { changed: 2, read: 1, stopped: 0, named: -1 };
     const guarded = new Set(accesses.map((access) => access.eventId + '\u0000' + access.path));
     const delegating = new Set(model.delegations.map((delegation) => delegation.id));
+    const agentIndex = new Map(model.agents.map((agent, index) => [agent.id, index]));
     const files = new Map();
+    // EF2: the call itself, beside the count it was kept as. Built from the event in hand - `didOfEvent` names what it
+    // ran in the words a flow step uses, so one file's story reads the same whoever told it.
+    const add = (path, how, event) => {
+        const known = files.get(path) ?? { calls: 0, how, reaches: [], leftOut: 0 };
+        const index = agentIndex.get(event.agentId);
+        // EF8: past the most a window is worth, the rest are counted rather than dropped in silence.
+        if (index === undefined || known.reaches.length >= EVERYDAY_CALLS_KEPT) {
+            if (index !== undefined)
+                known.leftOut += 1;
+        }
+        else {
+            known.reaches.push({
+                agentIndex: index,
+                did: redactor.term(didOfEvent(event)),
+                outcome: event.outcome,
+                evidence: redactor.term(describeEvidence(event.evidence, model, view)),
+                ...atOf(event.evidence, view),
+                how,
+            });
+        }
+        files.set(path, {
+            ...known,
+            calls: known.calls + 1,
+            how: RANK[how] > RANK[known.how] ? how : known.how,
+        });
+    };
     for (const event of model.events) {
-        if (!event.toolKnown || delegating.has(event.id) || event.outcome === 'unknown')
+        if (!event.toolKnown || delegating.has(event.id))
             continue;
         const writes = event.written !== undefined;
-        if (!writes && event.resultShape !== 'content')
-            continue;
-        const how = event.outcome === 'blocked' ? 'stopped' : writes ? 'changed' : 'read';
-        for (const path of new Set(event.targets)) {
-            if (path === '' || guarded.has(event.id + '\u0000' + path))
-                continue;
-            const known = files.get(path);
-            files.set(path, { calls: (known?.calls ?? 0) + 1, how: known === undefined || RANK[how] > RANK[known.how] ? how : known.how });
+        if (event.outcome !== 'unknown' && (writes || event.resultShape === 'content')) {
+            const how = event.outcome === 'blocked' ? 'stopped' : writes ? 'changed' : 'read';
+            for (const path of new Set(event.targets)) {
+                if (path !== '' && !guarded.has(event.id + '\u0000' + path))
+                    add(path, how, event);
+            }
+        }
+        // What a command and its output show of the rest, by the rules that find a protected path.
+        for (const { path, how } of everydayReach(event, policy)) {
+            if (!guarded.has(event.id + '\u0000' + path))
+                add(path, event.outcome === 'blocked' ? 'stopped' : how, event);
         }
     }
-    return [...files].map(([path, file]) => ({ path: redactor.path(path), calls: file.calls, how: file.how }));
+    const all = [...files];
+    const named = all.filter(([, file]) => file.how === 'named');
+    const listed = new Set(named.slice(0, EVERYDAY_NAMES_LISTED).map(([path]) => path));
+    const everydayFiles = all.filter(([path, file]) => file.how !== 'named' || listed.has(path))
+        .map(([path, file]) => ({
+        path: redactor.path(path),
+        calls: file.calls,
+        how: file.how,
+        // EFD1: a file whose name only was seen keeps the simple window, so its calls are not kept at all.
+        ...(file.how === 'named' ? {} : { reaches: file.reaches }),
+        ...(file.how !== 'named' && file.leftOut > 0 ? { reachesLeftOut: file.leftOut } : {}),
+    }));
+    const leftOut = named.length - listed.size;
+    return { everydayFiles, ...(leftOut > 0 ? { everydayNamesLeftOut: leftOut } : {}) };
 }
 /**
  * A recognised key format in what came back - `S-shape` of §5.4. It is reported even when the call touched no

package/dist/report/render/report-page/file-story.js

@@ -15,6 +15,17 @@ export function storyAgents(report) {
         };
     };
 }
+/**
+ * `EverydayCall.how` as a story kind: a write is its own thing, and a name seen is never called a read (P32a). An
+ * everyday file's calls never make `passed`, `saved`, `handed`, `repeated` or `used` - none of that was looked for.
+ */
+const EVERYDAY_KIND = {
+    read: 'read', changed: 'changed', stopped: 'stopped', named: 'named',
+};
+/**
+ * EF3: one story, whichever record holds it. The flows name protected files alone, so a file no flow names is told from
+ * the calls the model kept for it (EF2) - the same entries, minus the kinds that only a traced value can make.
+ */
 export function fileStory(report, path) {
     const agentOf = storyAgents(report);
     const entries = [];
@@ -26,14 +37,32 @@ export function fileStory(report, path) {
                 entries.push(entry);
         }
     }
+    const traced = entries.length > 0;
+    let leftOut = 0;
+    if (!traced) {
+        const everyday = report.everydayFiles.find((file) => String(file.path) === path);
+        leftOut = everyday?.reachesLeftOut ?? 0;
+        for (const call of everyday?.reaches ?? []) {
+            entries.push({
+                agent: agentOf(call.agentIndex),
+                kind: call.outcome === 'unknown' ? 'unknown' : EVERYDAY_KIND[call.how],
+                count: 1,
+                did: call.did,
+                outcome: call.outcome,
+                evidence: [call.evidence],
+                ...(call.at === undefined ? {} : { at: call.at }),
+            });
+        }
+    }
     const holders = new Map();
     for (const entry of entries) {
         const known = holders.get(entry.agent.index) ?? {
-            agent: entry.agent, read: false, passed: false, saved: false, repeated: false, used: false, stopped: false,
+            agent: entry.agent, read: false, changed: false, passed: false, saved: false, repeated: false, used: false, stopped: false,
         };
         holders.set(entry.agent.index, {
             ...known,
             read: known.read || entry.kind === 'read',
+            changed: known.changed || entry.kind === 'changed',
             passed: known.passed || entry.kind === 'passed' || entry.kind === 'handed',
             saved: known.saved || entry.kind === 'saved',
             repeated: known.repeated || entry.kind === 'repeated',
@@ -45,9 +74,11 @@ export function fileStory(report, path) {
     const sum = (kinds) => entries.filter((entry) => kinds.includes(entry.kind) && entry.received !== true).reduce((total, entry) => total + entry.count, 0);
     return {
         entries,
+        traced,
+        ...(leftOut > 0 ? { leftOut } : {}),
         holders: [...holders.values()],
         readers: [...holders.values()].filter((holder) => holder.read).length,
-        opened: sum(['read', 'named']),
+        opened: sum(['read', 'changed', 'named']),
         stopped: sum(['stopped']),
         complete: report.scope.completeness === 'complete',
     };