@agentwhy/cli 0.0.0-dev

package/dist/core/correlation/correlate.js

@@ -0,0 +1,329 @@
+import { outcomeOfExecution } from '../access/recorded-effect.js';
+import { MAIN_AGENT_TYPE } from '../agent.js';
+import { capabilityGaps } from '../capability.js';
+import { completenessOf } from '../completeness.js';
+import { projectRootOf } from '../project-root.js';
+import { PLAIN_INVOCATION_SOURCE, WORD_BREAK } from '../../shared/plain-invocation.js';
+/**
+ * Joins what an adapter read into the model, following spec §4.3 exactly: a result belongs to a call by the
+ * call's own id, a delegation to the agent it started by the id of the call that started it, and **nothing is
+ * ever joined by time** - there is no timestamp in these records to be tempted by.
+ *
+ * What cannot be joined confidently becomes a gap and gets no outcome (§4.3 rule 6), never a best guess.
+ */
+export function correlate(records) {
+    const gaps = [...records.gaps];
+    const resultsByCall = groupResults(records.results);
+    const calls = new Set(records.calls.map((call) => call.id));
+    for (const result of records.results) {
+        if (!calls.has(result.callId))
+            gaps.push({ kind: 'relation-unresolved' });
+    }
+    const running = reportRunning(records, resultsByCall);
+    const events = records.calls.filter((call) => call !== running).map((call) => toEvent(call, resultsByCall.get(call.id) ?? [], gaps));
+    // §4.3 rule 2: a delegated agent joins to its delegation by the id of the call that started it.
+    const indexByCall = indexDelegations(records.delegationIndex, gaps);
+    const delegated = new Set(records.delegations.map((call) => call.callId));
+    for (const entry of records.delegationIndex) {
+        if (!delegated.has(entry.callId))
+            gaps.push({ kind: 'relation-unresolved', agentId: entry.agentId });
+    }
+    // R4 of `2026-09-15-where-the-value-went.md`: a delivered report joins the delegation its notification names, by that
+    // call's id and nothing else. One naming any other call is no report of a delegation, and joins nothing.
+    const joined = delegations(records, indexByCall);
+    const byAgents = joinAgentReports(records, joined, gaps);
+    const reportsByCall = groupReports([...records.deliveredReports, ...byAgents.reports]);
+    // X17: later words join the delegation that started the agent they reached, by the id of the call that carried them.
+    const { followUps, unjoined } = joinFollowUps(records.followUps, records.followUpIndex, records.delegations, joined, gaps);
+    const delegationsOut = records.delegations.map((call) => toDelegation(call, joined.get(call.callId), reportsByCall.get(call.callId) ?? [], followUps.get(call.callId) ?? [], gaps));
+    const turns = checkedTurns(records.turns, gaps);
+    const contexts = [...records.contexts, ...unjoined, ...byAgents.unjoined];
+    // A text that is not whole is a gap wherever it is (X10, X31): a result, a delivery, a message or a context.
+    for (const event of events) {
+        if (event.result !== undefined && event.result.completeness !== 'complete')
+            gaps.push({ kind: 'result-incomplete', agentId: event.agentId });
+    }
+    for (const text of [...records.deliveries.map((delivery) => ({ ...delivery, agentId: delivery.recipientAgentId })), ...records.messages, ...contexts]) {
+        if (text.completeness !== 'complete')
+            gaps.push({ kind: 'result-incomplete', ...(text.agentId === undefined ? {} : { agentId: text.agentId }) });
+    }
+    gaps.push(...capabilityGaps(records.capabilities));
+    return {
+        sessionId: records.sessionId,
+        provider: records.provider,
+        projectRoot: projectRootOf(records.workingDirectories),
+        agents: records.agents,
+        delegations: delegationsOut,
+        events,
+        messages: records.messages,
+        turns,
+        reviews: records.reviews.map((review) => checkedReview(review, turns, gaps)),
+        contexts,
+        deliveries: records.deliveries,
+        capabilities: records.capabilities,
+        gaps,
+        completeness: completenessOf(gaps),
+    };
+}
+/**
+ * The index entry each delegating call keeps, once its own record agrees (X16): an entry whose started agent names a
+ * different parent contradicts the call, so neither is trusted.
+ */
+function delegations(records, indexByCall) {
+    const joined = new Map();
+    for (const call of records.delegations) {
+        const entry = indexByCall.get(call.callId);
+        // The delegation keeps no agent; `toDelegation` names that as the gap it is, once.
+        const contradicts = entry?.recordedParentAgentId !== undefined && entry.recordedParentAgentId !== call.parentAgentId;
+        joined.set(call.callId, contradicts ? undefined : entry);
+    }
+    return joined;
+}
+/**
+ * A report named by its agents joins the one delegation between them: the delegation whose agent sent it, made by the
+ * agent that received it (X18). None, or more than one, and it joins nothing: its words stay with the recipient as
+ * context another agent wrote, with a relation gap - never handed to a delegation by a guess.
+ */
+function joinAgentReports(records, joined, gaps) {
+    const reports = [];
+    const unjoined = [];
+    for (const report of records.agentReports) {
+        const between = records.delegations.filter((delegation) => delegation.parentAgentId === report.recipientAgentId && joined.get(delegation.callId)?.agentId === report.fromAgentId);
+        const delegation = between.length === 1 ? between[0] : undefined;
+        if (delegation === undefined) {
+            gaps.push({ kind: 'relation-unresolved', agentId: report.recipientAgentId });
+            unjoined.push({
+                kind: 'conversation', author: 'another-agent', agentId: report.recipientAgentId, text: report.content, completeness: 'complete', evidence: report.evidence,
+            });
+            continue;
+        }
+        reports.push({ callId: delegation.callId, content: report.content, evidence: report.evidence });
+    }
+    return { reports, unjoined };
+}
+/**
+ * Each follow-up joined to the one delegation that started the agent it reached, by that agent and by who sent it
+ * (X17). A call whose agent is no child its sender started, or whose index entry is missing or doubled, is not a
+ * follow-up: its words stay as an unjoined instruction of the sender, scanned, with a relation gap - never dropped, and
+ * never handed to a helper by a guess.
+ */
+function joinFollowUps(calls, index, delegationCalls, joined, gaps) {
+    // The agent each follow-up call reached; `undefined` where two entries name the call, since neither can be trusted.
+    const reached = new Map();
+    for (const entry of index)
+        reached.set(entry.callId, reached.has(entry.callId) ? undefined : entry.agentId);
+    const followUps = new Map();
+    const unjoined = [];
+    for (const call of calls) {
+        const agentId = reached.get(call.callId);
+        const starting = agentId === undefined
+            ? []
+            : delegationCalls.filter((delegation) => delegation.parentAgentId === call.senderAgentId && joined.get(delegation.callId)?.agentId === agentId);
+        const delegation = starting.length === 1 ? starting[0] : undefined;
+        if (delegation === undefined) {
+            gaps.push({ kind: 'relation-unresolved', agentId: call.senderAgentId });
+            unjoined.push({
+                kind: 'unjoined-instruction', author: 'agent', agentId: call.senderAgentId, text: call.text, completeness: 'complete', evidence: call.evidence,
+            });
+            continue;
+        }
+        const followUp = { id: call.callId, senderAgentId: call.senderAgentId, text: call.text, evidence: call.evidence };
+        followUps.set(delegation.callId, [...(followUps.get(delegation.callId) ?? []), followUp]);
+    }
+    return { followUps, unjoined };
+}
+/**
+ * One turn per `(agentId, id)`: a second record of the same turn contradicts the first, so neither is kept and the
+ * relation is a gap - a turn is never picked by time or position.
+ */
+function checkedTurns(turns, gaps) {
+    const key = (turn) => JSON.stringify([turn.agentId, turn.id]);
+    const counts = new Map();
+    for (const turn of turns)
+        counts.set(key(turn), (counts.get(key(turn)) ?? 0) + 1);
+    const doubled = new Set();
+    for (const turn of turns) {
+        if ((counts.get(key(turn)) ?? 0) < 2 || doubled.has(key(turn)))
+            continue;
+        doubled.add(key(turn));
+        gaps.push({ kind: 'relation-unresolved', agentId: turn.agentId });
+    }
+    return turns.filter((turn) => !doubled.has(key(turn)));
+}
+/**
+ * A verdict keeps the turn it names only when that is a turn of the reviewed agent (X20). A missing one is a review of no
+ * known turn, which the report says; one naming a turn the agent does not have is unlinked, with a gap in the reviewer's
+ * own source.
+ */
+function checkedReview(review, turns, gaps) {
+    const known = new Set(turns.filter((turn) => turn.agentId === review.reviewedAgentId).map((turn) => turn.id));
+    return {
+        ...review,
+        verdicts: review.verdicts.map((verdict) => {
+            if (verdict.turnId === undefined || known.has(verdict.turnId))
+                return verdict;
+            gaps.push({ kind: 'relation-unresolved', source: verdict.evidence.source });
+            const { turnId: _unlinked, ...unlinked } = verdict;
+            return unlinked;
+        }),
+    };
+}
+/**
+ * The call that is running this very report, where the session's own agent ran it: the session's last call, with no
+ * result yet, and nothing in it but `agentwhy report` and its flags. Its result cannot be in the record while the report
+ * is being drawn - the result is this report - so it is no gap, and a report opened from the conversation reads the
+ * same as one opened from Conversations a moment later. Anything more on the line (a pipe, a second command, a
+ * redirect) is a call like any other, and one with no result stays unknown.
+ */
+function reportRunning(records, results) {
+    const main = records.agents.find((agent) => agent.type === MAIN_AGENT_TYPE);
+    if (main === undefined)
+        return undefined;
+    // A sequence counts one transcript's calls, so the last call is the main transcript's own.
+    const last = records.calls.filter((call) => call.agentId === main.id)
+        .reduce((latest, call) => (latest === undefined || call.sequence > latest.sequence ? call : latest), undefined);
+    if (last === undefined || results.has(last.id))
+        return undefined;
+    return last.commands.length === 1 && AGENTWHY_REPORT.test(last.commands[0] ?? '') ? last : undefined;
+}
+/**
+ * `agentwhy report` with flags and plain values only: no shell operator, quote, substitution or second line. agentwhy
+ * is named by the same pattern a hook's invocation is read with, because the agent is asked to run it the way the hook
+ * does (`the-agent-tells-you.md` R18): a copy of its own would drift, and a report opened from the chat would show a
+ * gap. Found by a review: any word holding agentwhy passed, so another script's missing result was dropped too. Words
+ * are split where a shell splits them, on a space or a tab: a line break passed for one, and so did a second command.
+ */
+const AGENTWHY_REPORT = new RegExp(`^[ \\t]*(?:${PLAIN_INVOCATION_SOURCE})${WORD_BREAK}report(?:${WORD_BREAK}[\\w@%+=:,./~-]+)*[ \\t]*$`);
+/**
+ * Retries are separate calls with separate ids (§4.3 rule 7), so two results for one id is not a retry - it is
+ * an ambiguity, and picking one of them would hand the event a confident outcome it has not earned. They are
+ * kept together and the event is left without one.
+ */
+function groupResults(results) {
+    const byCall = new Map();
+    for (const result of results) {
+        const existing = byCall.get(result.callId);
+        if (existing === undefined)
+            byCall.set(result.callId, [result]);
+        else
+            existing.push(result);
+    }
+    return byCall;
+}
+function groupReports(reports) {
+    const byCall = new Map();
+    for (const report of reports) {
+        const existing = byCall.get(report.callId);
+        if (existing === undefined)
+            byCall.set(report.callId, [report]);
+        else
+            existing.push(report);
+    }
+    return byCall;
+}
+/** A second index entry for one call is the same kind of ambiguity: neither entry can be trusted to be the one. */
+function indexDelegations(entries, gaps) {
+    const byCall = new Map();
+    for (const entry of entries) {
+        if (byCall.has(entry.callId)) {
+            gaps.push({ kind: 'relation-unresolved', agentId: entry.agentId });
+            byCall.set(entry.callId, undefined);
+            continue;
+        }
+        byCall.set(entry.callId, entry);
+    }
+    return byCall;
+}
+function toEvent(call, results, sessionGaps) {
+    const own = [];
+    const result = results.length === 1 ? results[0] : undefined;
+    const outcome = results.length > 1 ? unresolved(call.agentId, own) : outcomeOf(call, result, call.agentId, own);
+    sessionGaps.push(...own);
+    const event = {
+        id: call.id,
+        agentId: call.agentId,
+        sequence: call.sequence,
+        toolName: call.toolName,
+        input: call.input,
+        targets: call.targets,
+        commands: call.commands,
+        resultShape: call.resultShape,
+        toolKnown: call.toolKnown,
+        ...(call.printsMatches === true ? { printsMatches: true } : {}),
+        ...(call.written === undefined ? {} : { written: call.written }),
+        outcome,
+        ...(result?.execution === undefined ? {} : { execution: result.execution }),
+        ...(call.turnId === undefined ? {} : { turnId: call.turnId }),
+        evidence: call.evidence,
+        completeness: completenessOf(own),
+    };
+    return result === undefined ? event : { ...event, result: toResult(result) };
+}
+function unresolved(agentId, own) {
+    own.push({ kind: 'relation-unresolved', agentId });
+    return 'unknown';
+}
+function outcomeOf(call, result, agentId, own) {
+    if (result === undefined) {
+        own.push({ kind: 'result-missing', agentId });
+        return 'unknown';
+    }
+    if (result.attributionAmbiguous === true)
+        return unresolved(agentId, own);
+    if (result.spilledResultMissing === true) {
+        own.push({ kind: 'spilled-result-missing', agentId });
+        return 'unknown';
+    }
+    if (result.denial !== undefined) {
+        // An unrecognised marker is UNKNOWN, never BLOCKED: the field is typed, its vocabulary is not documented.
+        if (result.denial.recognised)
+            return 'blocked';
+        own.push({ kind: 'outcome-unrecognised', agentId });
+        return 'unknown';
+    }
+    // X11: where the runtime recorded running the call, the record establishes access only as far as a profile says.
+    if (result.execution !== undefined) {
+        if (result.execution.status === 'unrecognised') {
+            own.push({ kind: 'outcome-unrecognised', agentId });
+            return 'unknown';
+        }
+        const outcome = outcomeOfExecution(call, result.execution);
+        // An effect the record does not establish is a gap, so that no report built on it reads as whole (X11).
+        if (outcome === 'unknown')
+            own.push({ kind: 'capability-absent', question: 'access', agentId });
+        return outcome;
+    }
+    return 'succeeded';
+}
+function toResult(result) {
+    return {
+        ...(result.content === undefined ? {} : { content: result.content }),
+        ...(result.denial === undefined ? {} : { denialKind: result.denial.kind }),
+        ...(result.launchNotice === true ? { launchNotice: true } : {}),
+        stage: result.stage,
+        completeness: result.completeness,
+        evidence: result.evidence,
+    };
+}
+function toDelegation(call, entry, reports, followUps, sessionGaps) {
+    const own = [];
+    // No index entry means the agent it started cannot be named. The delegation still happened, and saying so is
+    // the point: a delegation that vanishes from the report because its index is missing is the worse failure.
+    if (entry === undefined)
+        own.push({ kind: 'relation-unresolved', agentId: call.parentAgentId });
+    sessionGaps.push(...own);
+    const completeness = completenessOf(own);
+    return {
+        id: call.callId,
+        parentAgentId: call.parentAgentId,
+        ...(entry === undefined ? {} : { childAgentId: entry.agentId }),
+        ...(entry?.requestedType === undefined ? {} : { requestedType: entry.requestedType }),
+        ...(entry?.depth === undefined ? {} : { depth: entry.depth }),
+        ...(call.prompt === undefined ? {} : { prompt: call.prompt }),
+        ...(call.description === undefined ? {} : { description: call.description }),
+        reports: reports.map(({ content, evidence }) => ({ content, evidence })),
+        followUps,
+        evidence: call.evidence,
+        completeness,
+    };
+}

package/dist/core/delegation.js

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

package/dist/core/detector/prompt-signals.js

@@ -0,0 +1,78 @@
+/**
+ * The signals of specification §6.2, read out of the text a delegation carried.
+ *
+ * §6.2 gives each signal a meaning and one example; how one is recognised is
+ * `specs/2026-09-16-what-a-signal-looks-like.md`, written on counts taken from 15 real delegations rather than from
+ * intuition - which is how this project has three times written a rule over free text and paid for it (L009, L011).
+ *
+ * Two results of that measurement shape this module:
+ *
+ * - **Words are read outside paths** (R3). A prompt naming `apps/web/.env` was counted as being about configuration
+ *   because the word `env` sits inside the path. The text a path covers is removed before a word rule runs.
+ * - **`S4` is an identifier, not a word** (R6). A word list for configuration fired on 12 of 15 delegations - four
+ *   fifths of ordinary work - while `NEXT_PUBLIC_SITE_URL` and its like fired on 3. The word list is not here.
+ *
+ * Nothing in this module decides anything: a signal fires, and what a delegation led to is a label a person and the
+ * actions agree on, joined to these only by the scoring of the D1 plan (R8).
+ */
+import { pathTokens } from '../access/path-tokens.js';
+import { protects } from '../policy/policy.js';
+/** R4: asks for a value or for contents. The list is the one that was counted; it was not tuned afterwards. */
+const ASKS_FOR_A_VALUE = /\b(?:value|values|content|contents|what is set|what value|print|show)\b/i;
+/** R5: asks for a comparison of two things. */
+const ASKS_FOR_A_COMPARISON = /\b(?:match|matches|matching|compare|compared|comparison|same as|identical|differs?|different|equal)\b/i;
+/** R6: a name that points at configuration while naming no file - §6.2's own example of `S4`. */
+const CONFIGURATION_IDENTIFIER = /\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+\b/;
+/** R7: `C1` covers disclosure - do not quote the value - and `C2` covers reading the file at all. */
+const NOT_TO_QUOTE = /\b(?:do not quote|don't quote|without quoting|do not print|don't print|never quote|do not paste|don't paste)\b/i;
+const NOT_TO_READ = /\b(?:do not read|don't read|without reading|do not open|don't open|only confirm|confirm only|presence of)\b/i;
+/**
+ * A glob asks about a family of paths. `.env*` is a pattern for a protected path; `x*` is a pattern for nothing.
+ * Two expressions, because one carrying `g` would keep its place between calls and answer every second question
+ * wrongly.
+ */
+const HOLDS_A_GLOB = /[*?]/;
+const EVERY_GLOB = /[*?]/g;
+function namesAProtectedPath(tokens, policy) {
+    return tokens.some((token) => protects(policy, token) || (HOLDS_A_GLOB.test(token) && protects(policy, token.replace(EVERY_GLOB, 'x'))));
+}
+/**
+ * The text with the paths blanked out, so that a word rule cannot read a word that is part of one (R3). Blanked
+ * rather than deleted, so two words either side of a path do not become one.
+ *
+ * Only the tokens that look like a path go: `pathTokens` splits text at every separator and returns **every** word,
+ * because the policy is what decides which of them is a path. Blanking all of them would leave no text for a word
+ * rule to read - which is what the first version did, and what its tests caught.
+ */
+function looksLikeAPath(token) {
+    return token.includes('/') || token.startsWith('.') || token.startsWith('~');
+}
+function outsidePaths(text, tokens) {
+    let left = text;
+    for (const token of tokens.filter(looksLikeAPath))
+        left = left.split(token).join(' ');
+    return left;
+}
+/**
+ * What a delegation's prompt and description carry, read as one text (R1). The policy decides what a protected
+ * path is, so a project that protects more is read as naming more - the signal follows the policy, not a list.
+ */
+export function readPrompt(text, policy) {
+    const tokens = pathTokens(text);
+    const outside = outsidePaths(text, tokens);
+    const signals = [];
+    if (namesAProtectedPath(tokens, policy))
+        signals.push('S1');
+    if (ASKS_FOR_A_VALUE.test(outside))
+        signals.push('S2');
+    if (ASKS_FOR_A_COMPARISON.test(outside))
+        signals.push('S3');
+    if (CONFIGURATION_IDENTIFIER.test(outside))
+        signals.push('S4');
+    const caveats = [];
+    if (NOT_TO_QUOTE.test(outside))
+        caveats.push('C1');
+    if (NOT_TO_READ.test(outside))
+        caveats.push('C2');
+    return { signals, caveats };
+}

package/dist/core/entry-point.js

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

package/dist/core/event.js

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

package/dist/core/evidence.js

@@ -0,0 +1,9 @@
+export function mainSource() {
+    return { kind: 'main' };
+}
+export function agentSource(agentId) {
+    return { kind: 'agent', agentId };
+}
+export function reviewSource(reviewId) {
+    return { kind: 'review', reviewId };
+}

package/dist/core/late-message.js

@@ -0,0 +1,32 @@
+/**
+ * An agent's last words, added to the model when the transcript on disk does not hold them yet
+ * (`specs/2026-09-16-when-an-agent-finishes.md` R9).
+ *
+ * **Measured 2026-09-16 (B4c):** on 4 of 4 finished agents - foreground, background and nested - the agent's only text
+ * block was written to its transcript after the `SubagentStop` hook had run. A reading of the file alone misses exactly
+ * the message the motivating case's value was in.
+ *
+ * The record it is given is the one after every record of that agent read from disk. That is not a line number: an
+ * attachment line may land between them. It is the one thing known about its place - it was written after all of
+ * them - and it is the order the rules that compare records need. When the words are already on disk, the model is
+ * returned unchanged, so a transcript that caught up is not read twice.
+ */
+export function withLateMessage(model, agentId, text) {
+    if (text === '')
+        return model;
+    const fromAgent = (evidence) => evidence.source.kind === 'agent' && evidence.source.agentId === agentId;
+    const own = model.messages.filter((message) => message.agentId === agentId);
+    if (own.some((message) => message.text === text))
+        return model;
+    const records = [
+        ...model.events.flatMap((event) => [event.evidence, ...(event.result === undefined ? [] : [event.result.evidence])]),
+        ...own.map((message) => message.evidence),
+    ]
+        .filter(fromAgent)
+        .map((evidence) => evidence.record);
+    const after = records.reduce((last, record) => Math.max(last, record), 0) + 1;
+    return {
+        ...model,
+        messages: [...model.messages, { agentId, kind: 'said', text, completeness: 'complete', evidence: { source: { kind: 'agent', agentId }, record: after } }],
+    };
+}

package/dist/core/message.js

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

package/dist/core/nearest-project.js

@@ -0,0 +1,28 @@
+import { isAbsolute, relative, sep } from 'node:path';
+/**
+ * A folder that is gone cannot be offered, so only projects whose folder exists are considered. Where the folder lies
+ * inside more than one project, the nearest - the deepest - is the one; the projects inside it keep the listing's order.
+ * Paths are compared through `relative`, which compares a Windows path without regard to case, as its file system does.
+ *
+ * Nor is a folder `noProject` names (V6): Claude Code keeps the conversations of whatever folder it was started in, the
+ * home directory too, and a new terminal starts there. Found by a review: every folder under the home directory was
+ * offered the home directory as the project above it, which setup then refuses.
+ */
+export function nearestProject(folder, listing, noProject) {
+    const present = listing.projects.filter((project) => project.exists && !noProject(project.path));
+    const itself = present.find((project) => relative(project.path, folder) === '');
+    if (itself !== undefined)
+        return { kind: 'itself', project: itself };
+    const above = present
+        .filter((project) => within(project.path, folder))
+        .sort((a, b) => b.path.length - a.path.length)[0];
+    if (above !== undefined)
+        return { kind: 'above', project: above };
+    const inside = present.filter((project) => within(folder, project.path));
+    return inside.length > 0 ? { kind: 'inside', projects: inside } : { kind: 'none' };
+}
+/** Whether `path` lies under `folder`, and is not `folder` itself. */
+function within(folder, path) {
+    const between = relative(folder, path);
+    return between !== '' && between !== '..' && !between.startsWith(`..${sep}`) && !isAbsolute(between);
+}

package/dist/core/policy/default-policy.js

@@ -0,0 +1,32 @@
+/**
+ * The fallback when no policy was configured anywhere.
+ *
+ * `allowed` is **empty on purpose**. The obvious entries would be `.env.example` and `.env.sample`, and adding
+ * them would have the tool decide, on its own, that a file is safe. Teams leave real values in those templates,
+ * and spec §8.2 makes the same point from the other side: if the policy covers a sample file, that file stays
+ * out of reach too. An exception is a decision someone takes and writes down, never a gift from the default.
+ */
+export const DEFAULT_POLICY = {
+    level: 'no-read',
+    protected: [
+        // The name starts with `.env`, or ends with it. Chosen on measurement against a measured session
+        // (2026-09-14), not on taste - the wider shapes cost far more than they found:
+        //
+        //   `.env*`                113 findings · 29 paths · 4 of 5 refused calls recognised
+        //   `.env*` + `*.env`      124 findings · 34 paths · 4 of 5      <- this
+        //   `*.env` + `*.env.*`    218 findings · 91 paths · 4 of 5
+        //   `*.env*`               240 findings · 97 paths · 5 of 5
+        //
+        // The last catches one more refused call at the price of 116 further findings, most of them a mention of
+        // `.environment` in a document. That one call names a file shape none of the narrower patterns knows; it is
+        // recorded as an open question in the M3 plan rather than paid for with noise.
+        { pattern: '**/.env*' },
+        { pattern: '**/*.env' },
+        { pattern: '**/.npmrc' },
+        { pattern: '**/secrets/**' },
+        { pattern: '**/.ssh/**' },
+        { pattern: '**/id_rsa*' },
+    ],
+    allowed: [],
+    origin: { kind: 'default' },
+};

package/dist/core/policy/glob.js

@@ -0,0 +1,56 @@
+/**
+ * Path-glob matching, written out rather than taken from a library or from an experimental Node API, because
+ * which paths count as protected is the security decision of this tool: it has to be small enough to read and
+ * pinned by its own tests.
+ *
+ * `**` crosses directory separators, `*` and `?` do not. A pattern is anchored at both ends.
+ */
+const SPECIAL = /[.+^${}()|[\]\\]/g;
+export function globToRegExp(pattern) {
+    let source = '';
+    for (let index = 0; index < pattern.length; index += 1) {
+        const character = pattern[index] ?? '';
+        const next = pattern[index + 1];
+        if (character === '*' && next === '*') {
+            // `**/` also matches nothing at all, so `**/.env` matches `.env` at the root.
+            if (pattern[index + 2] === '/') {
+                source += '(?:.*/)?';
+                index += 2;
+            }
+            else {
+                source += '.*';
+                index += 1;
+            }
+            continue;
+        }
+        // `*` stops at whitespace as well as at a separator. Without that, a sentence mentioning a path matches a
+        // path pattern: everything up to the last slash is eaten by `**/`, and `.env*` then happily covers
+        // `.env (only the names, no values) ---`. A directory with a space still works, because `**/` may hold one;
+        // the cost is a **file name** containing a space, which is the rarer of the two by far.
+        if (character === '*') {
+            source += '[^/\\s]*';
+            continue;
+        }
+        if (character === '?') {
+            source += '[^/\\s]';
+            continue;
+        }
+        source += character.replace(SPECIAL, '\\$&');
+    }
+    return new RegExp(`^${source}$`);
+}
+/**
+ * The compiled form of each pattern met so far. A policy holds a handful of patterns and they are asked about once
+ * per candidate path, so a busy session compiled the same few thousands of times: measured at 566 ms of one run on a
+ * record-heavy transcript, spent entirely on rebuilding regular expressions that never differ. The compiled
+ * expression carries no `g` flag and no state, so returning the same one twice cannot change an answer.
+ */
+const COMPILED = new Map();
+export function matchesGlob(path, pattern) {
+    let compiled = COMPILED.get(pattern);
+    if (compiled === undefined) {
+        compiled = globToRegExp(pattern);
+        COMPILED.set(pattern, compiled);
+    }
+    return compiled.test(path);
+}

package/dist/core/policy/parse-policy.js

@@ -0,0 +1,70 @@
+import { isJsonObject, parseJsonObject } from '../../shared/json.js';
+export const POLICY_VERSION = 1;
+const LEVELS = ['no-read', 'no-disclose'];
+const KEYS = new Set(['version', 'level', 'protected', 'allowed']);
+export function parsePolicy(text, path) {
+    const document = parseJsonObject(text);
+    if (document === undefined)
+        return { errors: [`${path} is not a JSON object`] };
+    const errors = [];
+    const unknown = Object.keys(document).filter((key) => !KEYS.has(key));
+    if (unknown.length > 0) {
+        errors.push(`unknown ${unknown.length === 1 ? 'key' : 'keys'} ${unknown.join(', ')} — remove them, or fix the spelling`);
+    }
+    if (document.version !== POLICY_VERSION) {
+        errors.push(`"version" must be ${POLICY_VERSION} — add it, so a later format change is detected rather than guessed`);
+    }
+    const level = document.level;
+    if (typeof level !== 'string' || !isLevel(level)) {
+        errors.push(`"level" must be one of ${LEVELS.join(', ')}`);
+    }
+    const protectedPaths = readProtected(document.protected, errors);
+    const allowed = readAllowed(document.allowed, errors);
+    if (errors.length > 0)
+        return { errors };
+    return {
+        policy: {
+            level: level,
+            protected: protectedPaths,
+            allowed,
+            origin: { kind: 'file', path },
+        },
+    };
+}
+function isLevel(value) {
+    return LEVELS.includes(value);
+}
+/** An entry is a pattern, or a pattern with its own level. Both shapes are read; nothing acts on the level yet. */
+function readProtected(value, errors) {
+    if (!Array.isArray(value) || value.length === 0) {
+        errors.push('"protected" must be a non-empty array of path patterns');
+        return [];
+    }
+    return value.flatMap((entry, index) => {
+        if (typeof entry === 'string')
+            return entry === '' ? refuse(errors, index, 'is empty') : [{ pattern: entry }];
+        if (!isJsonObject(entry))
+            return refuse(errors, index, 'must be a pattern or an object with "path"');
+        const pattern = entry.path;
+        const level = entry.level;
+        if (typeof pattern !== 'string' || pattern === '')
+            return refuse(errors, index, 'has no "path"');
+        if (level !== undefined && (typeof level !== 'string' || !isLevel(level))) {
+            return refuse(errors, index, `has a "level" that is not one of ${LEVELS.join(', ')}`);
+        }
+        return [{ pattern, ...(level === undefined ? {} : { level: level }) }];
+    });
+}
+function readAllowed(value, errors) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || entry === '')) {
+        errors.push('"allowed" must be an array of path patterns');
+        return [];
+    }
+    return value;
+}
+function refuse(errors, index, problem) {
+    errors.push(`"protected" entry ${index + 1} ${problem}`);
+    return [];
+}