@agentwhy/cli 0.0.0-dev

package/dist/core/access/command-line.js

@@ -0,0 +1,454 @@
+/**
+ * The paths a command line could be addressing.
+ *
+ * A command has structure, which spec §6.5 names as the reason an earlier hook could be fixed: separators, and
+ * quoting. Both are used here instead of a list of "commands that read", because such a list is never complete
+ * and the first program missing from it passes unseen.
+ *
+ * Quoting does most of the work. `grep -rn "SECRET" apps` names `apps`; `echo "see .env for the value"` names
+ * nothing, and splitting that sentence into words - which is what a plain tokeniser does - is where most of the
+ * noise came from. A quoted string stays **one** token, so a sentence mentioning a file no longer matches a
+ * path pattern, while a genuinely quoted path (`cat "my file.env"`) still does.
+ *
+ * **A command is read once, a character at a time, as a shell reads it** (`CommandReader`). It used to be read in
+ * passes - lines, then operators, then words - and each pass had to guess what the next one knew: a heredoc body
+ * looked like commands, a quoted script was cut at its own semicolons, and a quote spanning lines hid the command
+ * after it. Each of those was measured on a real session (`specs/2026-09-15-findings-worth-reading.md` §2).
+ *
+ * **Code an interpreter is handed on the command line is code** (`specs/2026-09-15-paths-not-fragments.md` R1, added
+ * 2026-09-15). `node -e "log('check apps/web/.env')"` names no file, and the string literal inside it was being
+ * reported as one. From such a word only a candidate shaped like a whole path is kept.
+ *
+ * **Known limits.** A path built at runtime (`$DIR/.env`) is not recognised. A quoted string that is exactly a
+ * path is counted, which is correct, and a quoted sentence that is exactly a path-shaped word would be too. A
+ * string handed to `sh -c` is one word, not a command; none was found on the sessions measured. A heredoc inside
+ * `$(...)` can end the substitution early at a `)` in its body. An interpreter's option that takes a value of its
+ * own before the code flag (`node -r x -e "…"`) ends the search for its code, and that code then reads as any other
+ * argument does - noise, never silence - as does an interpreter started through another program (`npx tsx -e`).
+ */
+var _a;
+import { shapedLikePath } from './path-shape.js';
+/**
+ * Programs whose output is the **content** of what they were pointed at, rather than a list of what they
+ * reached. `cat .env` prints a file; the paths inside that file are the file's text, not places the command
+ * went. Anything not on this list keeps the conservative reading - its output is treated as a listing - so a
+ * program missing from here costs noise, never silence.
+ */
+const PRINTS_CONTENT = new Set([
+    'cat',
+    'head',
+    'tail',
+    'bat',
+    'less',
+    'more',
+    'echo',
+    'printf',
+    'jq',
+    'base64',
+    'strings',
+    'xxd',
+    'od',
+]);
+/** `NAME=value` before a program sets a variable; it runs nothing. */
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+/** Unquoted, each of these ends a simple command. `&` directly before `>` redirects instead (`&>file`). */
+const ENDS_A_COMMAND = new Set([';', '|', '&', '(', ')']);
+/** Unquoted, each of these ends a word and nothing more. A newline ends the command too, and is read apart. */
+const BLANK = new Set([' ', '\t', '\r', '\f', '\v']);
+/** What may follow the first character of a redirection and still belong to it: `>>`, `>|`, `2>&1`. */
+const REDIRECTION = new Set(['<', '>', '&', '|']);
+/** Inside double quotes a backslash escapes only these; before anything else it is itself. */
+const ESCAPED_IN_DOUBLE_QUOTES = new Set(['"', '\\', '$', '`', '\n']);
+/**
+ * A command line read the way a shell reads it, as far as the questions asked of it need.
+ *
+ * **Added 2026-09-14** (`specs/2026-09-15-findings-worth-reading.md` R1-R4b), in three measured steps. A heredoc body is
+ * **data** - a script, a JSON document, prose on standard input - and splitting the command on newlines had made
+ * each of its lines a command: `import`, `const` and `x` were reported as programs, the largest single source of
+ * findings that named no file. Operators were then cut before quoting was known, so a quoted `node -e` script fell
+ * apart at its own semicolons. And a reading that fixed that line by line still lost the command after a quote
+ * spanning lines, and every program inside a quoted `$(...)`.
+ *
+ * A heredoc body with no terminator runs to the end of the command, as a quote left open does.
+ */
+function readCommand(command) {
+    return new CommandReader(command).read();
+}
+class CommandReader {
+    #text;
+    #at = 0;
+    #simples = [];
+    /** Heredocs opened on the current line. Their bodies begin after its newline, in the order they were opened. */
+    #pending = [];
+    #words = [];
+    #word = '';
+    #next = 'argument';
+    constructor(text) {
+        this.#text = text;
+    }
+    read() {
+        const text = this.#text;
+        while (this.#at < text.length) {
+            const character = text.charAt(this.#at);
+            const following = text.charAt(this.#at + 1);
+            if (this.#readSubstitution())
+                continue;
+            if (character === '\\') {
+                // Before a newline it joins two lines; before anything else it makes that character plain.
+                if (following !== '\n')
+                    this.#word += following;
+                this.#at += 2;
+            }
+            else if (character === "'") {
+                this.#singleQuoted();
+            }
+            else if (character === '"') {
+                this.#doubleQuoted();
+            }
+            else if (character === '#' && this.#word === '') {
+                this.#skipComment();
+            }
+            else if (character === '\n') {
+                this.#at += 1;
+                this.#endCommand();
+                this.#skipHeredocBodies();
+            }
+            else if (BLANK.has(character)) {
+                this.#at += 1;
+                this.#endWord();
+            }
+            else if (character === '<' && following === '<') {
+                this.#openHeredoc();
+            }
+            else if (character === '<' || character === '>' || (character === '&' && following === '>')) {
+                this.#skipRedirection();
+            }
+            else if (ENDS_A_COMMAND.has(character)) {
+                this.#at += 1;
+                this.#endCommand();
+            }
+            else {
+                this.#word += character;
+                this.#at += 1;
+            }
+        }
+        this.#endCommand();
+        return this.#simples;
+    }
+    /**
+     * `$(...)` or a backtick at the current position, read as a command in its own right (R4b). It adds no word to
+     * the command around it: its text is not what the shell passes on, and offered as a candidate, `$(cat x/.env)`
+     * would become a finding named `cat x/.env`. False when no substitution starts here.
+     */
+    #readSubstitution() {
+        const text = this.#text;
+        if (text.charAt(this.#at) === '`') {
+            this.#at += 1;
+            this.#simples.push(...new _a(this.#backticked()).read());
+            return true;
+        }
+        if (text.charAt(this.#at) === '$' && text.charAt(this.#at + 1) === '(') {
+            this.#at += 2;
+            const inner = this.#parenthesised();
+            // `$((...))` is arithmetic: nothing in it runs.
+            if (!inner.startsWith('('))
+                this.#simples.push(...new _a(inner).read());
+            return true;
+        }
+        return false;
+    }
+    /** The text of a backtick substitution, its closing backtick consumed. Inside, an escaped backtick is one. */
+    #backticked() {
+        const text = this.#text;
+        let inner = '';
+        while (this.#at < text.length && text.charAt(this.#at) !== '`') {
+            if (text.charAt(this.#at) === '\\' && text.charAt(this.#at + 1) === '`') {
+                inner += '`';
+                this.#at += 2;
+                continue;
+            }
+            inner += text.charAt(this.#at);
+            this.#at += 1;
+        }
+        this.#at += 1;
+        return inner;
+    }
+    /** The text of `$(...)`, its closing parenthesis consumed. A parenthesis inside quotes does not count. */
+    #parenthesised() {
+        const text = this.#text;
+        const start = this.#at;
+        let depth = 1;
+        let quote = '';
+        while (this.#at < text.length) {
+            const character = text.charAt(this.#at);
+            this.#at += 1;
+            if (quote !== '') {
+                if (character === '\\' && quote === '"')
+                    this.#at += 1;
+                else if (character === quote)
+                    quote = '';
+            }
+            else if (character === '\\') {
+                this.#at += 1;
+            }
+            else if (character === "'" || character === '"') {
+                quote = character;
+            }
+            else if (character === '(') {
+                depth += 1;
+            }
+            else if (character === ')') {
+                depth -= 1;
+                if (depth === 0)
+                    return text.slice(start, this.#at - 1);
+            }
+        }
+        return text.slice(start);
+    }
+    /** Nothing is special inside single quotes, a newline included. Left open, the quote runs to the end. */
+    #singleQuoted() {
+        const close = this.#text.indexOf("'", this.#at + 1);
+        const end = close === -1 ? this.#text.length : close;
+        this.#word += this.#text.slice(this.#at + 1, end);
+        this.#at = end + 1;
+    }
+    /** Inside double quotes a backslash escapes a few characters, and `$(...)` and backticks still run. */
+    #doubleQuoted() {
+        const text = this.#text;
+        this.#at += 1;
+        while (this.#at < text.length) {
+            const character = text.charAt(this.#at);
+            const following = text.charAt(this.#at + 1);
+            if (character === '"') {
+                this.#at += 1;
+                return;
+            }
+            if (this.#readSubstitution())
+                continue;
+            if (character === '\\' && ESCAPED_IN_DOUBLE_QUOTES.has(following)) {
+                if (following !== '\n')
+                    this.#word += following;
+                this.#at += 2;
+                continue;
+            }
+            this.#word += character;
+            this.#at += 1;
+        }
+    }
+    /** A comment runs to the end of its line. The newline is left to end the command. */
+    #skipComment() {
+        const end = this.#text.indexOf('\n', this.#at);
+        this.#at = end === -1 ? this.#text.length : end;
+    }
+    /** `<<WORD` and `<<-WORD` open a body after this line; `<<<` hands the next word to the program as input. */
+    #openHeredoc() {
+        this.#endWord();
+        const third = this.#text.charAt(this.#at + 2);
+        if (third === '<') {
+            this.#at += 3;
+            this.#next = 'data';
+            return;
+        }
+        this.#at += third === '-' ? 3 : 2;
+        this.#next = { stripTabs: third === '-' };
+    }
+    /** `<`, `>`, `>>`, `2>&1`, `&>`: a redirection ends a word and ends no command. Its target is still a word. */
+    #skipRedirection() {
+        this.#endWord();
+        this.#at += 1;
+        while (REDIRECTION.has(this.#text.charAt(this.#at)))
+            this.#at += 1;
+    }
+    /** Called just past a newline: the bodies of the heredocs opened on the line before, skipped as data. */
+    #skipHeredocBodies() {
+        const text = this.#text;
+        while (this.#pending.length > 0 && this.#at < text.length) {
+            const end = text.indexOf('\n', this.#at);
+            const raw = text.slice(this.#at, end === -1 ? text.length : end);
+            this.#at = end === -1 ? text.length : end + 1;
+            const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+            const open = this.#pending[0];
+            if (open !== undefined && (open.stripTabs ? line.replace(/^\t+/, '') : line) === open.marker) {
+                this.#pending.shift();
+            }
+        }
+    }
+    #endWord() {
+        const word = this.#word;
+        this.#word = '';
+        if (word === '')
+            return;
+        const next = this.#next;
+        this.#next = 'argument';
+        if (next === 'argument')
+            this.#words.push(word);
+        else if (next !== 'data')
+            this.#pending.push({ marker: word, stripTabs: next.stripTabs });
+    }
+    #endCommand() {
+        this.#endWord();
+        // A `<<` with no marker before the command ended opens nothing.
+        this.#next = 'argument';
+        const words = this.#words;
+        this.#words = [];
+        if (words.length === 0)
+            return;
+        const program = words.find((word) => !ASSIGNMENT.test(word));
+        this.#simples.push(program === undefined ? { words } : { words, program });
+    }
+}
+_a = CommandReader;
+/**
+ * The programs a command line runs, by name. A program name is structure, not content: it is what makes
+ * "ran a search" sayable in a report without quoting the command, which §7.3 does not allow.
+ */
+export function programsIn(command) {
+    return readCommand(command)
+        .flatMap((simple) => (simple.program === undefined ? [] : [basename(simple.program)]))
+        // A program is named like one: letters, and no dot. Reading heredocs as data removed most of what used to
+        // slip through here; this stays for what that cannot know, and it costs `python3.11`, worth less than noise.
+        .filter((program) => /^[A-Za-z][A-Za-z0-9_-]*$/.test(program));
+}
+/**
+ * Each simple command a line runs: the program by its base name, and the words after it, quoting removed. For a
+ * reader that needs one program's arguments in order - which ones are options, which one is a pattern - rather than
+ * every word as a possible path.
+ */
+export function simpleCommandsIn(command) {
+    return readCommand(command).flatMap((simple) => simple.program === undefined
+        ? []
+        : [{ program: basename(simple.program), args: simple.words.slice(simple.words.indexOf(simple.program) + 1) }]);
+}
+/** Options git takes before its subcommand that consume the word after them. */
+const GIT_OPTIONS_WITH_A_VALUE = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path']);
+/**
+ * Whether the line runs `git commit` (`specs/2026-09-15-where-the-value-went.md` R7): the first word past git's own
+ * options is the subcommand. A message that says "commit", or `git log --grep commit`, does not commit anything.
+ */
+export function commitsIn(command) {
+    return readCommand(command).some((simple) => {
+        if (simple.program === undefined || basename(simple.program) !== 'git')
+            return false;
+        const words = simple.words.slice(simple.words.indexOf(simple.program) + 1);
+        for (let at = 0; at < words.length; at += 1) {
+            const word = words[at] ?? '';
+            if (GIT_OPTIONS_WITH_A_VALUE.has(word))
+                at += 1;
+            else if (!word.startsWith('-'))
+                return word === 'commit';
+        }
+        return false;
+    });
+}
+/** True when every command in the line only prints what it was given, so its output enumerates nothing. */
+export function printsContentOnly(commands) {
+    const programs = commands.flatMap((command) => readCommand(command).flatMap((simple) => (simple.program === undefined ? [] : [simple.program])));
+    return programs.length > 0 && programs.every((program) => PRINTS_CONTENT.has(basename(program)));
+}
+function basename(program) {
+    const parts = program.split('/');
+    return parts[parts.length - 1] ?? program;
+}
+/**
+ * Programs whose arguments are text and never a file they open. `echo "check apps/web/.env"` addresses
+ * nothing, and reading its argument as a path is how a sentence about a file became a file that was read.
+ * Unknown programs keep the conservative reading, so absence from this list costs noise, never silence.
+ */
+const ADDRESSES_NOTHING = new Set(['echo', 'printf', 'true', 'false', ':', 'sleep']);
+/** Whether a program, by its base name, takes only text and never opens a file its arguments name. */
+export function addressesNothing(program) {
+    return ADDRESSES_NOTHING.has(basename(program));
+}
+/**
+ * Interpreters, and the words that hand them code rather than a file to open. `deno` takes a subcommand where the
+ * others take a flag, and the search is the same either way.
+ */
+const HANDS_OVER_CODE = new Map([
+    ['python', new Set(['-c'])],
+    ['python3', new Set(['-c'])],
+    ['node', new Set(['-e', '-p', '--eval', '--print'])],
+    ['bun', new Set(['-e', '-p', '--eval', '--print'])],
+    ['deno', new Set(['eval'])],
+    ['ruby', new Set(['-e'])],
+    ['perl', new Set(['-e', '-E'])],
+    ['php', new Set(['-r'])],
+]);
+/**
+ * The word a simple command hands its program as code, if it does. The search passes over the interpreter's own
+ * options and stops at the first word that is neither an option nor the code flag: that word is a script to run,
+ * and everything after it belongs to the script, not to the interpreter - `node script.js -e x` opens `x` as the
+ * script's own argument.
+ */
+function inlineCodeOf(simple) {
+    const program = simple.program;
+    if (program === undefined)
+        return [];
+    const flags = HANDS_OVER_CODE.get(basename(program));
+    if (flags === undefined)
+        return [];
+    const words = simple.words.slice(simple.words.indexOf(program) + 1);
+    for (let at = 0; at < words.length; at += 1) {
+        const word = words[at] ?? '';
+        // The whole word is returned for `--eval=…`, because that is what the caller matches its words against.
+        const separator = word.indexOf('=');
+        if (flags.has(word))
+            return words[at + 1] === undefined ? [] : [words[at + 1] ?? ''];
+        if (separator > 0 && flags.has(word.slice(0, separator)))
+            return [word];
+        if (!word.startsWith('-'))
+            return [];
+    }
+    return [];
+}
+/**
+ * Whether every program the line runs is an interpreter handed code, or prints only what it was given, and the code
+ * names `path` - `python3 -c "print(open('.env').read())"`, alone or piped to `head`. Such output is read for values
+ * as a `cat`'s is (`docs/detection.md`, `python-open`). An interpreter can print anything, so this holds only where its
+ * own code names the file: a script that is a file of its own, or a path built while it runs, stays out, and an
+ * ordinary line it printed is dropped by the same shape rules as any other value.
+ */
+export function codeReadsNamedFile(commands, path) {
+    const simples = commands.flatMap((command) => readCommand(command)).filter((simple) => simple.program !== undefined);
+    const code = simples.flatMap(inlineCodeOf);
+    return (code.some((words) => words.includes(path)) &&
+        simples.every((simple) => inlineCodeOf(simple).length > 0 || PRINTS_CONTENT.has(basename(simple.program ?? ''))));
+}
+/** The code a command line hands to an interpreter, as words. For the measurement, which counts where a path sat. */
+export function inlineCode(command) {
+    return readCommand(command).flatMap(inlineCodeOf);
+}
+/**
+ * The paths a command line could be addressing: the words of every simple command it runs, unless the program
+ * addresses nothing. Read through `readCommand`, so a heredoc body contributes no word at all (R4). From a word
+ * that is code an interpreter was handed, only a candidate shaped like a whole path is kept (R1).
+ */
+export function commandPathCandidates(command) {
+    return readCommand(command)
+        .flatMap((simple) => {
+        if (simple.program !== undefined && ADDRESSES_NOTHING.has(basename(simple.program)))
+            return [];
+        const code = new Set(inlineCodeOf(simple));
+        return simple.words.flatMap((word) => code.has(word) ? candidatesOf(word).filter((candidate) => shapedLikePath(candidate)) : candidatesOf(word));
+    })
+        .filter((candidate) => candidate !== '');
+}
+/**
+ * Brackets and quotes hold a path inside an expression. `python3 -c "print(open('apps/web/.env').read())"` reads
+ * a file, and the token that survives quoting is the whole expression - which was being reported, verbatim, as
+ * the name of a file. Splitting on them keeps the finding and loses the noise around it.
+ *
+ * Only brackets and quotes: splitting on commas and semicolons as well would cut a quoted sentence into
+ * fragments and hand each one to the policy, which is the noise this module exists to avoid.
+ */
+const HOLDS_A_PATH = /[()'"`]+/;
+/**
+ * A flag is not a path, but `--file=.env` carries one. An assignment before the program - `FOO=bar cmd` - is
+ * not a path either, and its value is treated the same way: what follows the first `=` is the candidate.
+ */
+function candidatesOf(token) {
+    const separator = token.indexOf('=');
+    if (separator === -1 && token.startsWith('-'))
+        return [];
+    const value = separator === -1 ? token : token.slice(separator + 1);
+    return value.split(HOLDS_A_PATH).filter((candidate) => candidate !== '');
+}

package/dist/core/access/listing.js

@@ -0,0 +1,58 @@
+/**
+ * The paths a listing could be naming.
+ *
+ * A listing has structure too. `grep` writes `path:line:matched text`, `find` and `ls -1` write one path per
+ * line, `ls -l` writes the name last after a permission string. So a path counts by **where it sits**, not by
+ * being somewhere in the line.
+ *
+ * The difference is not cosmetic: a matched line is arbitrary file content, and taking every word of it made a
+ * document that mentions a file read as a file that was reached. **Measured across seven sessions
+ * (2026-09-15):** of 125 findings that came from a result, 71 had the path inside a line of prose - a table, a
+ * numbered list, an arrow in someone's notes - against 52 where the line was the path and 2 search hits. Taking
+ * the last field of any line, and the whole of any line, is where those 71 came from, and both are gone.
+ *
+ * **And a line taken whole is a path only when the whole of it is one**
+ * (`specs/2026-09-15-paths-not-fragments.md` R2, added 2026-09-15). Position says where a path would sit; it does not
+ * say that a program wrote one there. `…/id_rsa -> outside the project` and `…/id_rsa in a result · succeeded · 2×`
+ * sit where a path sits and are sentences about a file; `[apps/web/.env,` is one line of a printed array. Measured
+ * on nine sessions: six such findings, and no line with words before its path, which is why a field keeps its words.
+ */
+import { holdsCodePunctuation, shapedLikePath } from './path-shape.js';
+/** Where a path written out in full starts: the root, the home directory, or the directory the command ran in. */
+const PATH_START = /^(?:\/|~\/|\.\.?\/)/;
+/** How `ls -l` opens a line, and nothing else does: a file type and nine permission characters. */
+const LONG_LISTING = /^[-dlbcps][rwxSsTt-]{9}[ @+]/;
+/** A field of a line is where a path sits; punctuation of code in it says a program printed an expression (R2). */
+const asField = (text) => (text !== '' && !holdsCodePunctuation(text) ? text : '');
+/** A line taken whole, and a line of one word, name a file only when the whole of the line is a path (R2). */
+const asWholeLine = (text) => (shapedLikePath(text) ? text : '');
+export function listingPathCandidates(text) {
+    return text
+        .split('\n')
+        .map((line) => {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            return [];
+        // `grep -n` without a file name writes `49:matched text`, and that leading number is not part of a path.
+        // Dropping it is what stops `49:packages/app/.env` from being reported as a file.
+        const withoutLineNumber = trimmed.replace(/^\d+:/, '');
+        const colon = withoutLineNumber.indexOf(':');
+        const fields = withoutLineNumber.split(/\s+/);
+        // In order of preference. A whole grep line matches a pattern as readily as the path that starts it, so
+        // the narrower candidate is offered first and only the first match of a line is taken: one line of a
+        // listing names one file.
+        const candidates = [
+            { text: asField(colon === -1 ? '' : withoutLineNumber.slice(0, colon)), positional: true },
+            // `find` prints whole paths, one per line. A line with no search hit's colon that starts where a path starts
+            // is that path because of where it sits, space in a directory name and all. Offered before the final field,
+            // which cut `…/Web Portal/app/.env` into `Portal/app/.env`: a second finding, for a file that exists nowhere.
+            { text: colon === -1 && PATH_START.test(withoutLineNumber) ? asWholeLine(withoutLineNumber) : '', positional: true },
+            // A line that is one word is that word: `ls -1` and `git status --porcelain` write listings like that.
+            { text: fields.length === 1 ? asWholeLine(withoutLineNumber) : '', positional: true },
+            // `ls -l` writes the name last, after a permission string that nothing else begins with.
+            { text: LONG_LISTING.test(withoutLineNumber) ? asField(fields[fields.length - 1] ?? '') : '', positional: false },
+        ];
+        return candidates.filter((candidate) => candidate.text !== '');
+    })
+        .filter((candidates) => candidates.length > 0);
+}

package/dist/core/access/path-shape.js

@@ -0,0 +1,59 @@
+/** Punctuation that belongs to an expression and to no file name on the systems this reads. */
+const CODE_PUNCTUATION = /[{}<>,;]|->|=>/;
+/** A shell operator standing between words: what a command line holds and a path does not. */
+const OPERATOR = /(?:^|\s)(?:&&|\|\||\|)(?:\s|$)/;
+/** A word of a path holds a separator, or starts where a path starts. */
+function partOfAPath(word) {
+    return word.includes('/') || word.startsWith('.') || word.startsWith('~');
+}
+/**
+ * A square bracket belongs to a path only inside one segment of it. A framework names directories
+ * `app/[locale]/page.tsx` and files `[...slug].env`; a program printing an array writes `[apps/web/.env,`. So a
+ * bracket that does not open and close within its own segment is code, and one that does is a name someone chose.
+ */
+function bracketsPairWithinSegments(text) {
+    for (const segment of text.split('/')) {
+        let depth = 0;
+        for (const character of segment) {
+            if (character === '[')
+                depth += 1;
+            else if (character === ']')
+                depth -= 1;
+            if (depth < 0)
+                return false;
+        }
+        if (depth !== 0)
+            return false;
+    }
+    return true;
+}
+/** Whether the string carries punctuation of code. A line of output that does names no file (R2). */
+export function holdsCodePunctuation(text) {
+    return CODE_PUNCTUATION.test(text) || !bracketsPairWithinSegments(text);
+}
+/**
+ * The shape, by the first rule that matches: an operator makes it command text, punctuation makes it code, and
+ * what is left is read by its words. One word is a path; more are a path only when the first and the last are both
+ * part of one - `/Users/someone/Client Name/app/.env` is a path, `check apps/web/.env` is a sentence.
+ */
+export function pathShape(text) {
+    if (OPERATOR.test(text))
+        return 'command-text';
+    if (holdsCodePunctuation(text))
+        return 'code-punctuation';
+    const words = text.trim().split(/\s+/);
+    if (words.length === 1)
+        return 'path';
+    if (!partOfAPath(words[0] ?? ''))
+        return 'words-before';
+    if (!partOfAPath(words[words.length - 1] ?? ''))
+        return 'words-after';
+    return 'path-with-space';
+}
+/** Whether the whole string is a path, space in a directory name and all. */
+export function shapedLikePath(text) {
+    if (text.trim() === '')
+        return false;
+    const shape = pathShape(text);
+    return shape === 'path' || shape === 'path-with-space';
+}

package/dist/core/access/path-tokens.js

@@ -0,0 +1,37 @@
+/**
+ * Pulls path-like tokens out of a piece of text, so they can be held against the policy.
+ *
+ * The separators are the reason this file exists. A path rarely sits alone: it arrives inside a command
+ * (`grep -rn SECRET apps/web`), inside a quoted argument, or inside a line of output that reads
+ * `apps/web/.env.development:12:SECRET=…`. Splitting on whitespace alone would leave that whole line as one
+ * token and no pattern would ever match it - which is exactly the shape the motivating case took.
+ *
+ * **Known limits, deliberately not guessed around:** a path assembled at runtime (`$HOME/.ssh/id_rsa`,
+ * `"$dir"/.env`) is not recognised as the file it names, and a token that merely looks like a path is offered
+ * to the policy like any other. The error runs toward reporting rather than passing over, and every fact says
+ * where it was found so a reader can judge it.
+ */
+const SEPARATORS = /[\s"'`,;:=()<>|{}[\]]+/;
+export function pathTokens(text) {
+    return text
+        .split(SEPARATORS)
+        .filter((token) => token !== '')
+        .map(stripTrailingPunctuation)
+        .filter((token) => token !== '');
+}
+// Prose puts a full stop after a path. A trailing slash is kept: a directory pattern such as the one for
+// `secrets` matches the form with the separator and not the bare name, so stripping it lost every call that
+// addressed a protected directory as a whole.
+function stripTrailingPunctuation(token) {
+    return token.replace(/[.]+$/, '');
+}
+/** Every string inside a value, however deeply it sits. Tool inputs are shaped by the tool, not by us. */
+export function stringsIn(value) {
+    if (typeof value === 'string')
+        return [value];
+    if (Array.isArray(value))
+        return value.flatMap(stringsIn);
+    if (value !== null && typeof value === 'object')
+        return Object.values(value).flatMap(stringsIn);
+    return [];
+}