@agentwhy/cli 0.0.0-dev

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

@@ -0,0 +1,310 @@
+import { matchesGlob } from '../policy/glob.js';
+import { protectionOf } from '../policy/policy.js';
+import { commandPathCandidates, printsContentOnly } from './command-line.js';
+import { listingPathCandidates } from './listing.js';
+import { pathTokens, stringsIn } from './path-tokens.js';
+import { outputIsClean, outputShowsReach } from './recorded-effect.js';
+import { hitLines } from './search-output.js';
+import { printedSearch } from './search-reach.js';
+/**
+ * Every touch of a protected path in a session, from both sides.
+ *
+ * Delegating calls are left out: handing work to another agent reaches no file, and reading a **prompt** for
+ * intent is the detector's job, which this milestone does not do. Their effects appear here through the events
+ * of the agent they started.
+ *
+ * Outcome is carried, not judged. §5.4 attaches `SUCCEEDED` to its definition of `S-input`, but that belongs to
+ * a verdict, and a refused attempt is worth reading too - it says the policy held.
+ */
+export function protectedAccesses(model, policy) {
+    const delegating = new Set(model.delegations.map((delegation) => delegation.id));
+    return model.events
+        .filter((event) => !delegating.has(event.id))
+        .flatMap((event) => accessesOf(event, policy));
+}
+function accessesOf(event, policy) {
+    // A path parameter is a path. A command line is read for its arguments, and a listing for what it enumerates:
+    // both have structure, and using it is what separates a file that was reached from a file that was mentioned.
+    // A path parameter and a quoted shell argument are both positional: something said "this is one thing", so a
+    // space inside belongs to it. Only guessed candidates - a line of output, a word taken out of prose - have to
+    // be whitespace-free.
+    const fromInput = dedupe([
+        ...protectedTargets(event.targets, policy),
+        ...protectedPathsAmong(event.commands.flatMap(commandPathCandidates), policy, { allowWhitespace: true }),
+    ]);
+    const named = new Set(fromInput.map(([path]) => path));
+    // Only a listing says the call reached what it names. The content of a file that mentions `.env` says the
+    // file mentions it - counting that was worth 316 findings on a session that had a handful.
+    // A tool's declared shape is refined by what was actually run: `cat` through a shell prints a file, and the
+    // paths in that file are its text. The shape belongs to the command, one level below the tool.
+    const enumerates = event.resultShape === 'listing' && !readsContent(event);
+    // X11: a process that did not complete cleanly may have printed diagnostics naming what it could not open, so of its
+    // output only a field in a search hit's position names a file it reached.
+    const clean = outputIsClean(event.execution);
+    const listed = enumerates
+        ? stringsIn(event.result?.content).flatMap(listingPathCandidates).map((line) => (clean ? line : line.filter((candidate) => candidate.positional)))
+        : [];
+    const shown = protectedPathsPerLine(listed, policy);
+    // A path the parameters already named is not an `S-result`: the source is what the other tools would miss.
+    const fromResult = shown.filter(([path]) => !named.has(path));
+    const printed = printedLines(event, [...named]);
+    const outcomeOf = targetOutcome(event, printed, new Set(shown.map(([path]) => path)));
+    // H1: lines a search printed are text the agent read only where the result is what its model was handed (X10).
+    const lines = event.result?.stage === 'model' ? new Map([...printed].map(([path, each]) => [path, each.length])) : new Map();
+    return [
+        ...fromInput.map(([path, pattern]) => toAccess(event, 'input', path, pattern, outcomeOf(path, 'input'), lines.get(path))),
+        ...fromResult.map(([path, pattern]) => toAccess(event, 'result', path, pattern, outcomeOf(path, 'result'), lines.get(path))),
+    ];
+}
+/**
+ * The outcome of one target of a call (X11). The call's own outcome where the record establishes it - or where the format
+ * keeps no process record, as Claude Code's does not. Where a process ran and its effect is not established, what its
+ * output shows it reached it reached: a line naming the file, printed by a search or a listing. Any other target is an
+ * attempt whose effect is unknown - never counted as reached because the command ran.
+ */
+function targetOutcome(event, printed, shown) {
+    return (path, source) => {
+        if (event.outcome !== 'unknown' || event.execution === undefined || event.result?.content === undefined)
+            return event.outcome;
+        return source === 'result' || printed.has(path) || shown.has(path) ? 'succeeded' : 'unknown';
+    };
+}
+/** A search hit with its line number: `path:12:text`. A diagnostic `path: message` has none. */
+const NUMBERED_HIT = /^[^:]+:\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]));
+}
+/**
+ * The lines of each file a succeeded search printed, per file (H1, H2, H12). Where the search puts no file's name on its
+ * lines and the call named exactly one protected file - `grep KEY .env` - its whole output is that file's lines (H3), as
+ * a `cat` of it is. Whether it puts one there is the command's to say (`PrintedSearch.names`), not the output's: a
+ * colon in a line of `.env` is not a file name before it. **Raw content**: for the redactor, and nothing else (H11).
+ */
+export function printedLines(event, named) {
+    const printed = new Map();
+    const search = searchOf(event);
+    if (search === undefined || !outputShowsReach(event))
+        return printed;
+    // X11: a process that did not complete cleanly may have printed `.env: Permission denied`, which reads as a hit. Only a
+    // numbered hit line is taken from it, and its whole output is never one named file's (H3).
+    if (!outputIsClean(event.execution)) {
+        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]);
+        return printed;
+    }
+    const output = stringsIn(event.result?.content).join('\n');
+    const only = [...new Set(named)];
+    const whole = () => output.split('\n')
+        .filter((line) => line.trim() !== '' && line !== '--')
+        .map((line) => (search.numbered === true ? line.replace(/^\d+[:-]/, '') : line));
+    // H3: lines with no name on them are the one file the call named - or no one's that can be told.
+    if (search.names === 'never') {
+        if (only.length === 1 && whole().length > 0)
+            printed.set(only[0], whole());
+        return printed;
+    }
+    const hits = hitLines(output, search.context);
+    for (const hit of hits)
+        printed.set(hit.path, [...(printed.get(hit.path) ?? []), hit.text]);
+    // One operand that may be a file: where it is the one protected file named and no line names it, no line names any.
+    if (search.names === 'maybe' && only.length === 1 && !printed.has(only[0])) {
+        printed.clear();
+        if (whole().length > 0)
+            printed.set(only[0], whole());
+    }
+    return printed;
+}
+/**
+ * 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.
+ */
+export function searchOf(event) {
+    if (event.printsMatches === true)
+        return { context: true, names: 'maybe' };
+    if (event.commands.length === 0)
+        return undefined;
+    return event.commands.map(printedSearch).find((search) => search !== undefined);
+}
+/**
+ * Whether what came back is the text of what the call named - a `Read`, or a shell line that only prints (`cat`) -
+ * rather than a list of what it found. A tool's declared shape is refined by what was actually run, as `accessesOf`
+ * reads it: this is the one place that decision is made.
+ */
+export function readsContent(event) {
+    return event.resultShape === 'content' || (event.resultShape === 'listing' && printsContentOnly(event.commands));
+}
+/**
+ * The protected paths one command line names, with the pattern that protects each - read exactly as a report reads the
+ * command of a call, so a hook refusing a command and the report on the session cannot disagree about whether it named
+ * a protected path (`specs/2026-09-16-worth-running-every-day.md` R18). Only what the line names: what the command would
+ * print is not known before it runs.
+ */
+export function protectedPathsInCommand(command, policy) {
+    return protectedPathsAmong(commandPathCandidates(command), policy, { allowWhitespace: true });
+}
+/**
+ * A candidate holding whitespace is not offered to the policy. A path may legitimately contain a space, and
+ * that is the cost; what is bought is every banner, diff header and sentence that happens to end in a path -
+ * `--- apps/web/.npmrc` was reported as a file, and prose that trails off into a path was reported as one too.
+ * Measured on one session: it is the difference between 85 findings and 76.
+ */
+function hasNoWhitespace(candidate) {
+    return !/\s/.test(candidate);
+}
+/**
+ * A backslash in a candidate is an escape, and an escape belongs to a regular expression or to shell quoting -
+ * `grep '\.env'` was being reported as a file called `\.env`. A path may legally hold one, and almost never
+ * does on the systems this reads.
+ */
+function isNotEscaped(candidate) {
+    return !candidate.includes('\\');
+}
+/**
+ * A name with no separator in it is a path only if it is a dotfile. Without this, the `env` property that every
+ * TypeScript repository reads off Node's global process object is reported as a file called `.env`, and so is
+ * `import.meta.env`. Dotted code and a dotted filename look alike; where the dot sits is what tells them apart.
+ *
+ * The cost is a file called `config.env` sitting in the working directory and named without a path. That is
+ * rarer than the code, and it is a rule rather than a list of identifiers to keep extending.
+ *
+ * *Narrowed 2026-09-24* (`protectionFor`): it holds for a guessed candidate only. A person who wrote a rule naming
+ * `customers.csv` had an agent run `cat customers.csv` and `grep -r … .`, whose hit came back as `customers.csv:6:…`
+ * with a customer's name, e-mail and phone in it - and the report said "nothing private" of both.
+ */
+function looksAddressable(candidate) {
+    return candidate.includes('/') || candidate.startsWith('.');
+}
+/**
+ * The entry that protects a candidate, where a candidate of its shape may be a file at all. A bare name - no separator,
+ * no leading dot - is one where either:
+ *
+ * - **its position says so**: the value a tool was handed, or the field before a search hit's first colon, is a file
+ *   name because of where it sits, whatever it looks like; or
+ * - **a rule names it exactly**: a pattern whose last part holds no wildcard - one ending in `customers.csv` - was
+ *   written for that one file. The `env` read off Node's process object is matched only by a wildcard (`*.env`),
+ *   which is what the rule above is for.
+ */
+function protectionFor(policy, candidate, positional) {
+    const protection = protectionOf(policy, candidate);
+    if (protection === undefined || positional || looksAddressable(candidate))
+        return protection;
+    return policy.protected.find((entry) => namesOneFile(entry.pattern) && matchesGlob(candidate, entry.pattern));
+}
+/** A pattern whose last part is a name, not a wildcard: it was written for one file. */
+function namesOneFile(pattern) {
+    const last = pattern.slice(pattern.lastIndexOf('/') + 1);
+    return last !== '' && !GLOB.test(last);
+}
+/**
+ * A bracket or a quote left in a candidate means it is an expression, not a file. A command line has its paths
+ * lifted out of such expressions before they get here (`command-line.ts`); a line of output does not, because
+ * the text of a file is not something this tool is entitled to parse.
+ */
+const CODE_PUNCTUATION = /[()'"`]/;
+const GLOB = /[*?]/;
+/**
+ * A search hit is not a path. `grep -n` prints `path:12:KEY=value`, and that whole string was being reported as the
+ * name of a file - in a report, and then as a line of `check`, where it also carried a redacted value into a column of
+ * paths. The path is the field before the first colon, and `listing.ts` already lifts it out for a result; this rejects
+ * what is left when such a line arrives from somewhere else. Measured on real sessions.
+ */
+const SEARCH_HIT = /:\d+:/;
+/**
+ * An assignment is not a path either: `KEY=value` is what a file holds, not a file. A path may legally contain `=`,
+ * and practically never does.
+ */
+const ASSIGNMENT = /=/;
+/**
+ * Everything that has to be true before a string is offered to the policy as a path someone reached. Each part
+ * was written for a false positive that was actually measured on a real session, and is named for it.
+ */
+function pathLike(candidate, options) {
+    return (candidate !== '' &&
+        isNotEscaped(candidate) &&
+        !CODE_PUNCTUATION.test(candidate) &&
+        // A leading dash is an option or a diff marker: `--- apps/web/.npmrc` is a banner above a file, not a file.
+        !candidate.startsWith('-') &&
+        // A glob is a question, not an answer. `ls .env*` names no file, and reporting `.env*` as one reached puts
+        // a string in the report that exists nowhere on disk. What such a command actually opened, if anything,
+        // comes back in its output and is found there instead.
+        !GLOB.test(candidate) &&
+        !SEARCH_HIT.test(candidate) &&
+        !ASSIGNMENT.test(candidate) &&
+        (options.allowWhitespace || hasNoWhitespace(candidate)));
+}
+/**
+ * A target is not text that happens to contain a path - it is the value the tool was handed, and the tool's
+ * profile says that value names the file. So the whole value is offered first, and only if the policy does not
+ * protect it are its tokens tried.
+ *
+ * Splitting first was wrong in a way that showed up in a report: a project at `/Users/someone/Client Name/app` had
+ * every finding under it cut at the space, so `Client Name/app/apps/web/.env` was reported as a file called
+ * `Name/app/apps/web/.env` - a path that exists nowhere. One target names one file, so the first match wins.
+ */
+function protectedTargets(targets, policy) {
+    const found = new Map();
+    for (const target of targets) {
+        for (const candidate of [target, ...pathTokens(target)]) {
+            // Whitespace disqualifies a token guessed out of text, never the value the tool was given.
+            if (!pathLike(candidate, { allowWhitespace: candidate === target }))
+                continue;
+            const protection = protectionFor(policy, candidate, candidate === target);
+            if (protection === undefined)
+                continue;
+            if (!found.has(candidate))
+                found.set(candidate, protection.pattern);
+            break;
+        }
+    }
+    return [...found];
+}
+/** Each path once, keeping the pattern it was first matched by. */
+function dedupe(entries) {
+    return [...new Map(entries.map(([path, pattern]) => [path, pattern]))];
+}
+/** Pairs of the path and the pattern that protects it, each path once, in the order they were met. */
+function protectedPathsAmong(candidates, policy, options = {}) {
+    const found = new Map();
+    const usable = candidates.filter((entry) => pathLike(entry, { allowWhitespace: options.allowWhitespace === true }));
+    for (const candidate of usable) {
+        if (found.has(candidate))
+            continue;
+        const protection = protectionFor(policy, candidate, false);
+        if (protection !== undefined)
+            found.set(candidate, protection.pattern);
+    }
+    return [...found];
+}
+/** One line of a listing names one file: the first candidate that the policy protects, and no more. */
+function protectedPathsPerLine(lines, policy) {
+    const found = new Map();
+    for (const candidates of lines) {
+        // Whitespace disqualifies a guessed candidate but not a positional one: the field before a search hit's
+        // first colon is a path because of where it sits, space in a directory name and all.
+        const usable = candidates.filter((entry) => pathLike(entry.text, { allowWhitespace: entry.positional }));
+        for (const { text: candidate, positional } of usable) {
+            const protection = protectionFor(policy, candidate, positional);
+            if (protection === undefined)
+                continue;
+            if (!found.has(candidate))
+                found.set(candidate, protection.pattern);
+            break;
+        }
+    }
+    return [...found];
+}
+function toAccess(event, source, path, pattern, outcome, lines) {
+    return {
+        ...(lines === undefined ? {} : { lines }),
+        eventId: event.id,
+        agentId: event.agentId,
+        toolName: event.toolName,
+        source,
+        path,
+        pattern,
+        outcome,
+        evidence: source === 'input' ? event.evidence : (event.result?.evidence ?? event.evidence),
+    };
+}

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

@@ -0,0 +1,102 @@
+import { unquote } from '../redaction/value-shapes.js';
+import { codeReadsNamedFile, printsContentOnly } from './command-line.js';
+const KEYED = /^(?:export\s+)?[A-Za-z_][A-Za-z0-9_.-]*\s*[=:]\s*(.*)$/;
+const JSON_KEYED = /^"[^"]+"\s*:\s*("[^"]*"|[^,\s]+)/;
+/**
+ * An `.npmrc` setting scoped to a registry, as npm documents it: `//registry.npmjs.org/:_authToken=value`. Found by
+ * `docs/detection.md` (`npmrc`): read as a line of its own, the whole setting looked like an address and was dropped as
+ * an ordinary value, so a token `cat ~/.npmrc` printed was never traced.
+ */
+const REGISTRY_KEYED = /^\/\/\S+?:[A-Za-z_][A-Za-z0-9_-]*\s*=\s*(.*)$/;
+/** A `Read` numbers the lines it returns. */
+const LINE_NUMBER = /^\s*\d+→/;
+/**
+ * Every value read out of a protected resource by a call that succeeded, each once per agent and file:
+ *
+ * - from the content a call returned when it named the resource and printed what was in it - a `Read`, a `cat`;
+ * - from what an interpreter printed when the code it was handed names the resource - `python3 -c "print(open('.env').read())"`;
+ * - from a listing line that names a protected path - `path:line:KEY=value`, the motivating case.
+ *
+ * A line shaped `KEY=value` or `"key": "value"` gives its value; any other line gives itself.
+ *
+ * A call's content is read **once for the call**, against every protected path it named. `cat .env .env.local`
+ * concatenates two files with nothing between them, and a line of that output came from one of them; recording
+ * it once against each, as if each file held it, puts a file in the report that the value was never read from.
+ * A listing line carries its own path, so those are attributed one by one and stay exact.
+ *
+ * **Known limit.** A search that names one file prints its matches without the file's name - `grep KEY .env`
+ * answers `12:KEY=value` - and those lines are neither content nor a listing line naming a path, so their values
+ * are not read. Recorded rather than guessed at, until a measurement says how often it happens.
+ */
+export function protectedValues(model, accesses) {
+    const events = new Map(model.events.map((event) => [event.id, event]));
+    const seen = new Set();
+    const values = [];
+    const add = (agentId, paths, line) => {
+        const value = valueOf(line);
+        const key = JSON.stringify([agentId, paths, value]);
+        if (value === undefined || seen.has(key))
+            return;
+        seen.add(key);
+        values.push({ agentId, paths, value });
+    };
+    for (const [eventId, group] of byEvent(accesses)) {
+        const event = events.get(eventId);
+        const content = event?.result?.content;
+        if (event === undefined || content === undefined)
+            continue;
+        const named = [...new Set(group.filter((access) => access.source === 'input').map((access) => access.path))];
+        if (named.length > 0 && (event.resultShape === 'content' || printsContentOnly(event.commands))) {
+            for (const line of content.split('\n'))
+                add(event.agentId, named, line);
+        }
+        else {
+            // An interpreter whose own code opened the file: its output is read as the file's, against the files it named.
+            const opened = named.filter((path) => codeReadsNamedFile(event.commands, path));
+            if (opened.length > 0)
+                for (const line of content.split('\n'))
+                    add(event.agentId, opened, line);
+        }
+        for (const access of group) {
+            if (access.source !== 'result')
+                continue;
+            for (const line of listedLines(content, access.path))
+                add(access.agentId, [access.path], line);
+        }
+    }
+    return values;
+}
+/** The succeeded accesses of each call, in the order the calls were met: one call's content is read once. */
+function byEvent(accesses) {
+    const groups = new Map();
+    for (const access of accesses) {
+        if (access.outcome !== 'succeeded')
+            continue;
+        const group = groups.get(access.eventId);
+        if (group === undefined)
+            groups.set(access.eventId, [access]);
+        else
+            group.push(access);
+    }
+    return groups;
+}
+/**
+ * The value of a `KEY=value`, `"key": "value"` or `//registry/:key=value` line, or the line itself; nothing for a blank
+ * line or a comment.
+ */
+function valueOf(raw) {
+    const line = raw.replace(LINE_NUMBER, '').trim();
+    if (line === '' || line.startsWith('#'))
+        return undefined;
+    const json = JSON_KEYED.exec(line);
+    const keyed = json === null ? (KEYED.exec(line) ?? REGISTRY_KEYED.exec(line)) : null;
+    const value = json !== null ? unquote(json[1] ?? '') : keyed !== null ? unquote((keyed[1] ?? '').trim()) : line;
+    return value === '' ? undefined : value;
+}
+/** The lines of a listing that name this path, with the path and a line number taken off the front. */
+function listedLines(content, path) {
+    return content
+        .split('\n')
+        .filter((line) => line.startsWith(`${path}:`))
+        .map((line) => line.slice(path.length + 1).replace(/^\d+:/, ''));
+}

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

@@ -0,0 +1,67 @@
+import { simpleCommandsIn } from './command-line.js';
+import { readOptions } from './search-reach.js';
+/**
+ * Programs that open every file operand they are given, print it, and exit non-zero when one of them cannot be opened.
+ * With a recorded exit code of 0, each operand was read. Any other program's exit code establishes nothing about its
+ * 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']);
+/**
+ * `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
+ * positional word is then an operand. Any option not listed - `-i`, whose suffix BSD takes from the next word, or `--help`,
+ * which opens nothing - leaves the effect unknown.
+ */
+const SED_OPTIONS = { shortWithValue: new Set(['e', 'f']), longWithValue: new Set(['--expression', '--file']) };
+const SED_SCRIPT_OPTIONS = new Set(['-e', '-f', '--expression', '--file']);
+const SED_PLAIN_OPTIONS = new Set([
+    '-n', '-E', '-r', '-s', '-u', '-z', '--quiet', '--silent', '--regexp-extended', '--separate', '--unbuffered', '--null-data', '--posix',
+    '--sandbox',
+]);
+/**
+ * What a runtime's record of running a call establishes about access (`2026-09-27-what-codex-wrote.md` X9, X11). A
+ * status says that something ran, never what it reached:
+ *
+ * - a recognised call that writes, recorded as completed: its write happened;
+ * - a recognised command line of exactly one simple command whose program reads every operand, or a `sed` given one,
+ *   completed with exit 0: each operand was read;
+ * - anything else - a failure, an interruption, another program, a pipeline, a tool with no profile: `unknown`. A
+ *   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')
+        return 'unknown';
+    if (call.written !== undefined)
+        return 'succeeded';
+    if (call.commands.length !== 1 || execution.exitCode !== 0)
+        return 'unknown';
+    const simple = simpleCommandsIn(call.commands[0] ?? '');
+    return simple.length === 1 && simple[0] !== undefined && readsItsOperands(simple[0]) ? 'succeeded' : 'unknown';
+}
+function readsItsOperands({ program, args }) {
+    if (READS_EVERY_OPERAND.has(program))
+        return true;
+    if (program !== 'sed')
+        return false;
+    const { options, positionals } = readOptions(args, SED_OPTIONS);
+    if (!options.every((option) => SED_SCRIPT_OPTIONS.has(option.name) || SED_PLAIN_OPTIONS.has(option.name)))
+        return false;
+    const scriptGiven = options.some((option) => SED_SCRIPT_OPTIONS.has(option.name));
+    return positionals.length - (scriptGiven ? 0 : 1) === 1;
+}
+/**
+ * Whether a call's recorded output shows what it reached, whatever its event outcome: a result the record establishes, or
+ * the output of a process that ran - where a line naming its file (`path:12:…`) shows that file was read even when the
+ * process then failed on another (X11).
+ */
+export function outputShowsReach(event) {
+    return event.outcome === 'succeeded' || (event.outcome === 'unknown' && event.execution !== undefined);
+}
+/**
+ * Whether every line of a process's output may name what it reached: the process completed with exit 0. Otherwise its
+ * output may hold diagnostics that name paths it could not open, so only lines that carry a file name in a search hit's
+ * position are read as reached.
+ */
+export function outputIsClean(execution) {
+    return execution === undefined || (execution.status === 'completed' && execution.exitCode === 0);
+}

package/dist/core/access/returns.js

@@ -0,0 +1,173 @@
+import { isOrdinaryShape } from '../redaction/value-shapes.js';
+import { protectedValues } from './protected-values.js';
+export function traceValues(model, accesses, traceOf) {
+    // Spec §5.2: an ordinary value - a port, a boolean - would make every report that mentions one carry a value back.
+    const values = protectedValues(model, accesses).filter((value) => !isOrdinaryShape(value.value));
+    return { values, trace: traceOf(values.map((value) => value.value)) };
+}
+/** Which protected files a traced value in this text was read from. Empty when it carries none. */
+export function filesTracedIn(texts, traced) {
+    const files = new Set();
+    for (const text of texts) {
+        for (const index of traced.trace.foundIn(text)) {
+            const value = traced.values[index];
+            if (value !== undefined)
+                for (const path of value.paths)
+                    files.add(path);
+        }
+    }
+    return [...files].sort();
+}
+export function returnsOf(model, accesses, traced) {
+    const { values, trace } = traced;
+    const events = new Map(model.events.map((event) => [event.id, event]));
+    return model.delegations.flatMap((delegation) => {
+        const child = delegation.childAgentId;
+        if (child === undefined)
+            return [];
+        const below = agentsFrom(model, child);
+        // Only a confirmed reach could have given the agent something to return: a refusal did not, and an attempt whose
+        // effect the record does not establish is no reach (`2026-09-27-what-codex-wrote.md` X11).
+        const reached = accesses.filter((access) => below.has(access.agentId) && access.outcome === 'succeeded');
+        // Nothing protected was reached at or below it, so nothing protected could have come back.
+        if (reached.length === 0)
+            return [];
+        const event = events.get(delegation.id);
+        const result = event?.result;
+        const readable = event !== undefined && event.outcome !== 'unknown' && result?.content !== undefined;
+        // `2026-09-15-where-the-value-went.md` R3: what came back is what the delegating agent received - the result, and
+        // every report delivered for it. A launch notice says only that the agent started, so it is not one of them.
+        const received = [
+            ...(readable && result?.content !== undefined && result.launchNotice !== true
+                ? [{ text: result.content, evidence: result.evidence }]
+                : []),
+            ...delegation.reports.map((report) => ({ text: report.content, evidence: report.evidence })),
+        ];
+        const messages = model.messages.filter((message) => message.agentId === child).map((message) => message.text);
+        const reportLength = delegation.reports.length > 0
+            ? delegation.reports.reduce((length, report) => length + report.content.length, 0)
+            : result?.content?.length;
+        const base = {
+            delegationId: delegation.id,
+            agentId: child,
+            parentAgentId: delegation.parentAgentId,
+            filesReached: new Set(reached.map((access) => access.path)).size,
+            ...(reportLength === undefined ? {} : { reportLength }),
+            evidence: event?.result?.evidence ?? event?.evidence ?? delegation.evidence,
+        };
+        // A value read by a call that printed several protected files at once came from one of them, so the files it
+        // was found under are carried with whether they are the one or the several.
+        const filesOf = (texts) => {
+            const files = new Set();
+            let uncertain = false;
+            for (const text of texts) {
+                for (const index of trace.foundIn(text)) {
+                    const value = values[index];
+                    if (value === undefined || !below.has(value.agentId))
+                        continue;
+                    for (const path of value.paths)
+                        files.add(path);
+                    if (value.paths.length > 1)
+                        uncertain = true;
+                }
+            }
+            return { paths: [...files].sort(), uncertain };
+        };
+        const written = filesOf(messages);
+        const writtenFrom = written.paths;
+        const shown = (files) => files.uncertain ? { fileUncertain: true } : {};
+        // What was received decides what came back (R2, amended). A statement of a value shows where the value came from,
+        // says nothing of what the agent wrote (R4b), and carries the record of the first text that held it. It is made
+        // before anything unreadable is weighed: a value that came back is never downgraded (R7).
+        const fromReceived = filesOf(received.map((entry) => entry.text));
+        if (fromReceived.paths.length > 0) {
+            const carrying = received.find((entry) => filesOf([entry.text]).paths.length > 0);
+            return [{
+                    ...base,
+                    ...(carrying === undefined ? {} : { evidence: carrying.evidence }),
+                    strength: 'value',
+                    paths: fromReceived.paths,
+                    writtenFrom,
+                    ...shown(fromReceived),
+                }];
+        }
+        // R9: a return that cannot be read is not a clean one, whatever the agent wrote.
+        if (!readable)
+            return [{ ...base, strength: 'unknown', paths: [], writtenFrom, ...shown(written) }];
+        // where-the-value-went R5: started in the background, and no report delivered - what came back is not in the record.
+        if (received.length === 0)
+            return [{ ...base, strength: 'unknown', awaited: true, paths: [], writtenFrom, ...shown(written) }];
+        // R5: only a file that was reached below counts. A protected path a report merely mentions is prose.
+        const named = [...new Set(reached.map((access) => access.path))].filter((path) => received.some((entry) => namesPath(entry.text, path)));
+        if (named.length > 0) {
+            const naming = received.find((entry) => named.some((path) => namesPath(entry.text, path)));
+            return [{
+                    ...base,
+                    ...(naming === undefined ? {} : { evidence: naming.evidence }),
+                    strength: 'path',
+                    paths: named.sort(),
+                    writtenFrom,
+                    ...shown(written),
+                }];
+        }
+        // Nothing of the file was in what this record holds of the reply. Before that is said as a clean return, the
+        // one thing that can contradict it: a value only an agent below this delegation ever read, in the hands of the
+        // agent that delegated. A child's one channel to its parent is its reply, so the value crossed here - whatever
+        // carried it, and whether or not this version can read that carrier (`when-an-agent-finishes` D9). Saying
+        // "nothing came back" over that is the one answer the record rules out.
+        const crossed = filesOf(textsOf(model, delegation.parentAgentId, delegation.evidence.record));
+        if (crossed.paths.length > 0) {
+            return [{ ...base, strength: 'value', inferred: true, paths: crossed.paths, writtenFrom, ...shown(crossed) }];
+        }
+        const last = received.at(-1);
+        return [{ ...base, ...(last === undefined ? {} : { evidence: last.evidence }), strength: 'report', paths: [], writtenFrom, ...shown(written) }];
+    });
+}
+/**
+ * Every string an agent wrote after a given record: its own messages, what it put into the calls it made, the later words
+ * it gave its helpers, and code or instructions of its own that are no call of the model (X14, X17).
+ */
+function textsOf(model, agentId, after) {
+    const strings = (value) => {
+        if (typeof value === 'string')
+            return [value];
+        if (Array.isArray(value))
+            return value.flatMap(strings);
+        if (value !== null && typeof value === 'object')
+            return Object.values(value).flatMap(strings);
+        return [];
+    };
+    return [
+        ...model.messages.filter((message) => message.agentId === agentId && message.evidence.record > after).map((message) => message.text),
+        ...model.events.filter((event) => event.agentId === agentId && event.evidence.record > after).flatMap((event) => strings(event.input)),
+        ...model.delegations.flatMap((delegation) => delegation.followUps)
+            .filter((followUp) => followUp.senderAgentId === agentId && followUp.evidence.record > after)
+            .map((followUp) => followUp.text),
+        ...model.contexts.filter((context) => context.author === 'agent' && context.agentId === agentId && context.evidence.record > after)
+            .map((context) => context.text),
+    ];
+}
+/** The agent and every agent a chain of delegations below it started. */
+function agentsFrom(model, agentId) {
+    const below = new Set([agentId]);
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const delegation of model.delegations) {
+            const child = delegation.childAgentId;
+            if (child !== undefined && below.has(delegation.parentAgentId) && !below.has(child)) {
+                below.add(child);
+                grew = true;
+            }
+        }
+    }
+    return below;
+}
+/** Whether the text names this path as a whole: `.env` inside `.env.local` is not it, `/abs/apps/web/.env` is. */
+export function namesPath(text, path) {
+    for (let at = text.indexOf(path); at !== -1; at = text.indexOf(path, at + 1)) {
+        if (!/[\w.-]/.test(text.charAt(at - 1)) && !/[\w./-]/.test(text.charAt(at + path.length)))
+            return true;
+    }
+    return false;
+}