@event4u/agent-config 14.22.0 → 15.0.0

package/src/scripts/ci_settle.ts

@@ -18,10 +18,20 @@
  * every agent's head: `not settled` and `settled` are different from `could not
  * read`, and only the first two may end a wait.
  *
- * Exit codes: 0 = settled, every check succeeded (or was skipped) ·
+ * A verdict also has to be ABOUT SOMETHING, which is the second half of the
+ * same rule and was missing until 2026-09-08: the rollup answers about the head
+ * the PR *record* carries, and that head stops tracking the branch when the PR
+ * is merged or when the record lags a push. Both then look like a healthy
+ * green. {@link classifyTarget} refuses those, before the wait and again at
+ * verdict time. Measured cost of not having it: a `SETTLED GREEN — 40 check(s)`
+ * for a head with literally zero check runs.
+ *
+ * Exit codes: 0 = settled green, and the head it is about is named ·
  *             1 = settled, at least one check failed ·
- *             2 = did not settle within the budget, or the API could not be
- *                 read — NEVER a verdict, and the reason is printed.
+ *             2 = did not settle within the budget, the API could not be read,
+ *                 or the target is not a PR a verdict can be about (merged,
+ *                 closed, or head-diverged) — NEVER a verdict, and the reason
+ *                 is printed.
  *
  * Usage: ./scripts-run src/scripts/ci_settle <pr> [--timeout-min N] [--interval-sec N]
  *
@@ -57,6 +67,121 @@ export type PollState =
     | { kind: 'pending'; total: number; done: number }
     | { kind: 'settled'; failing: string[]; total: number };
 
+/**
+ * What `git ls-remote` said about the PR branch's tip.
+ *
+ * `absent` and `unreadable` are different answers and must not collapse: a
+ * cross-repo fork PR legitimately has no ref under this `origin`, while a
+ * transport failure means nobody knows. Collapsing them either disables the
+ * divergence check for forks silently, or blocks every fork PR forever.
+ */
+export type RemoteTip =
+    | { kind: 'found'; sha: string }
+    | { kind: 'absent' }
+    | { kind: 'unreadable'; reason: string };
+
+/**
+ * Whether the PR this wait is about still decides anything.
+ *
+ * `refuse` is NOT a verdict — it exits 2 like every other non-verdict, because
+ * the wait produced no readable statement about the head that matters.
+ */
+export type TargetState =
+    | { kind: 'open'; head: string; ref: string; divergenceChecked: boolean }
+    | { kind: 'unreadable'; reason: string }
+    | { kind: 'refuse'; reason: string };
+
+/**
+ * Decide whether a green from {@link classifyPoll} may be reported at all.
+ *
+ * WHY THIS EXISTS, measured 2026-09-08 on PR #1949 and paid for twice in one
+ * session. `gh pr view --json statusCheckRollup` answers about the head the PR
+ * *record* carries, and that head stops tracking the branch in two situations
+ * this script previously could not tell apart from a healthy wait:
+ *
+ * 1. **The PR is already merged or closed.** A push to its branch fires no
+ *    `pull_request` event, so no checks are created for the new commits and the
+ *    rollup keeps returning the merge-time head's checks. The script reported
+ *    `SETTLED GREEN — 40 check(s)` for a head that had stopped mattering, and
+ *    the only thing that exposed it was a hand-written
+ *    `/commits/<sha>/check-runs` query answering `0`. Reported at face value
+ *    that green authorises a merge of content nobody checked.
+ * 2. **The PR record lags the branch ref.** Same shape, different cause
+ *    (recorded on PR #710): `git ls-remote` shows the new SHA while the record
+ *    keeps the old one, and merging then lands the PR WITHOUT the newer
+ *    commits — silently, which is what makes it worse than a red.
+ *
+ * Both are answered by the same two facts, which is why one function decides
+ * them: the PR's `state`, and whether its head equals the branch tip. Pure, so
+ * the failure is testable without a network — feed it a merged PR and it must
+ * answer `refuse`, never `open`.
+ */
+export function classifyTarget(
+    stdout: string,
+    stderr: string,
+    status: number | null,
+    tip: RemoteTip,
+): TargetState {
+    const combined = `${stdout}\n${stderr}`.toLowerCase();
+    for (const marker of _UNREADABLE_MARKERS) {
+        if (combined.includes(marker.toLowerCase())) {
+            return { kind: 'unreadable', reason: marker };
+        }
+    }
+    if (status !== 0) {
+        return { kind: 'unreadable', reason: `gh exited ${String(status)}` };
+    }
+    let state: string;
+    let head: string;
+    let ref: string;
+    try {
+        const parsed = JSON.parse(stdout) as {
+            state?: unknown;
+            headRefOid?: unknown;
+            headRefName?: unknown;
+        };
+        if (
+            typeof parsed.state !== 'string' ||
+            typeof parsed.headRefOid !== 'string' ||
+            typeof parsed.headRefName !== 'string'
+        ) {
+            return { kind: 'unreadable', reason: 'no state / headRefOid / headRefName in response' };
+        }
+        state = parsed.state.toUpperCase();
+        head = parsed.headRefOid;
+        ref = parsed.headRefName;
+    } catch {
+        return { kind: 'unreadable', reason: 'unparseable JSON' };
+    }
+    if (state !== 'OPEN') {
+        return {
+            kind: 'refuse',
+            reason:
+                `the PR is ${state}, not OPEN. Its rollup describes head ${head.slice(0, 9)} as of ` +
+                'that transition; pushes after it create no checks, so a green here would be about ' +
+                'a head that no longer decides anything',
+        };
+    }
+    if (tip.kind === 'unreadable') {
+        return { kind: 'unreadable', reason: `branch tip: ${tip.reason}` };
+    }
+    if (tip.kind === 'absent') {
+        // A fork PR's ref is not under this origin. Say the check did not apply
+        // rather than pretending it passed.
+        return { kind: 'open', head, ref, divergenceChecked: false };
+    }
+    if (tip.sha !== head) {
+        return {
+            kind: 'refuse',
+            reason:
+                `the PR record is at head ${head.slice(0, 9)} but origin/${ref} is at ` +
+                `${tip.sha.slice(0, 9)}. Merging in this state lands the PR WITHOUT the newer ` +
+                'commits (recorded on PR #710), and any verdict here is about the wrong head',
+        };
+    }
+    return { kind: 'open', head, ref, divergenceChecked: true };
+}
+
 /** Markers that mean the API did not answer — not that nothing is pending. */
 const _UNREADABLE_MARKERS = [
     'error connecting to',
@@ -126,6 +251,41 @@ function poll(pr: string): PollState {
     return classifyPoll(r.stdout ?? '', r.stderr ?? '', r.status);
 }
 
+/**
+ * Read the branch tip from the remote, not from a local ref.
+ *
+ * A local `origin/<ref>` is only as fresh as the last fetch, and the divergence
+ * this guards against is created by somebody else's push — so a stale local ref
+ * would report agreement exactly when it matters most.
+ */
+function readTip(ref: string): RemoteTip {
+    const r = spawnSync('git', ['ls-remote', 'origin', `refs/heads/${ref}`], {
+        encoding: 'utf-8',
+        timeout: 60_000,
+    });
+    if (r.status !== 0) {
+        const why = (r.stderr ?? '').trim().split('\n')[0] ?? `git exited ${String(r.status)}`;
+        return { kind: 'unreadable', reason: why };
+    }
+    const line = (r.stdout ?? '').trim();
+    if (line === '') return { kind: 'absent' };
+    const sha = line.split(/\s+/)[0] ?? '';
+    return sha === '' ? { kind: 'unreadable', reason: 'empty sha in ls-remote output' } : { kind: 'found', sha };
+}
+
+function readTarget(pr: string): TargetState {
+    const r = spawnSync('gh', ['pr', 'view', pr, '--json', 'state,headRefOid,headRefName'], {
+        encoding: 'utf-8',
+        timeout: 60_000,
+    });
+    // The ref name comes from the same read, so the tip lookup needs it first;
+    // classifyTarget is called twice rather than plumbing a callback through a
+    // pure function.
+    const shape = classifyTarget(r.stdout ?? '', r.stderr ?? '', r.status, { kind: 'absent' });
+    if (shape.kind !== 'open') return shape;
+    return classifyTarget(r.stdout ?? '', r.stderr ?? '', r.status, readTip(shape.ref));
+}
+
 function sleepSync(seconds: number): void {
     // Deliberately synchronous: this is a CLI whose whole job is to block.
     spawnSync(process.execPath, ['-e', `setTimeout(()=>{}, ${String(seconds * 1000)})`], {
@@ -164,18 +324,58 @@ export function main(argv: readonly string[]): number {
     }
     const intervalSec = num('--interval-sec', 60);
 
+    // Up front, because waiting nine minutes to learn the PR was merged before
+    // the wait began is the expensive way to find out.
+    const before = readTarget(pr);
+    if (before.kind === 'refuse') {
+        process.stdout.write(`ci_settle: REFUSING TO WAIT — ${before.reason}. No verdict is claimed.\n`);
+        return 2;
+    }
+    if (before.kind === 'unreadable') {
+        process.stdout.write(
+            `ci_settle: could not read the PR's target state (${before.reason}) — NOT a verdict, waiting anyway; ` +
+                'the pre-verdict re-check below still applies.\n',
+        );
+    } else if (!before.divergenceChecked) {
+        process.stdout.write(
+            `ci_settle: origin carries no refs/heads/${before.ref} (a fork PR) — the head-divergence check does not apply here.\n`,
+        );
+    }
+
     const deadline = Date.now() + timeoutMin * 60_000;
     let unreadableStreak = 0;
 
     for (;;) {
         const state = poll(pr);
         if (state.kind === 'settled') {
+            // The rollup is about the record's head. Re-read that head at
+            // VERDICT time, not only at start: a push or a merge during the
+            // wait makes the rollup describe something the caller is not about
+            // to act on, and this is the last moment a wrong verdict is still
+            // preventable.
+            const at = readTarget(pr);
+            if (at.kind === 'refuse') {
+                process.stdout.write(
+                    `ci_settle: WITHHOLDING A VERDICT — ${at.reason}. The checks that settled are not about ` +
+                        'the head that matters now.\n',
+                );
+                return 2;
+            }
+            if (at.kind === 'unreadable') {
+                process.stdout.write(
+                    `ci_settle: WITHHOLDING A VERDICT — could not confirm the target head (${at.reason}). ` +
+                        'A verdict needs to name the head it is about.\n',
+                );
+                return 2;
+            }
             if (state.failing.length === 0) {
-                process.stdout.write(`ci_settle: SETTLED GREEN — ${String(state.total)} check(s)\n`);
+                process.stdout.write(
+                    `ci_settle: SETTLED GREEN — ${String(state.total)} check(s) on ${at.head.slice(0, 9)}\n`,
+                );
                 return 0;
             }
             process.stdout.write(
-                `ci_settle: SETTLED RED — ${String(state.failing.length)} of ${String(state.total)} failing:\n` +
+                `ci_settle: SETTLED RED — ${String(state.failing.length)} of ${String(state.total)} failing on ${at.head.slice(0, 9)}:\n` +
                     state.failing.map((f) => `  ${f}\n`).join(''),
             );
             return 1;

package/src/scripts/code_graph/build.ts

@@ -34,6 +34,7 @@ import {
     type EdgeConfidence,
     EXPECTED_GRAMMAR_ABI,
     EXT_LANG,
+    isStatedResolution,
     type Lang,
     type ResolvedVia,
     SCHEMA_VERSION,
@@ -612,6 +613,52 @@ export function buildGraph(
         });
     }
 
+    // DERIVED `tests` edges (3.2).
+    //
+    // A test file that imports an in-repo symbol from a NON-test file is
+    // asserted to test it. Derived here rather than extracted because the
+    // predicate is a property of the two PATHS, which no grammar can see, and
+    // because `buildGraph` already holds every `imports` edge plus the node
+    // table needed to reject cross-test and out-of-repo targets.
+    //
+    // Three exclusions, each of which would otherwise manufacture a false
+    // `tests` edge:
+    //   · target outside the repository (`external:*` / `symbol:*`) — there is
+    //     no subject to test;
+    //   · target in another TEST file — a shared test helper is not a subject;
+    //   · target is the subject FILE node rather than a symbol in it, which is
+    //     kept: a test that imports a module tests that module, and the file
+    //     node is the only handle a caller has for a module with no exported
+    //     symbol the extractor named;
+    //   · THE SOURCE IMPORT IS ITSELF A GUESS. Added after an independent review
+    //     demonstrated the laundering: a PHP `use Two\Mailer` with no
+    //     `composer.json` binds by BASE NAME, so the `imports` edge is
+    //     `name-lookup` and can point at `One\Mailer` — and a `tests` edge
+    //     derived from it, stamped `test-import`, made that wrong target
+    //     TRUSTWORTHY to every consumer of the accepted-edge filter. Measured
+    //     consequences on a two-namespace fixture: `tests-for One\Mailer`
+    //     named a test that does not test it, `tests-for Two\Mailer` reported
+    //     none, `untested` inverted the pair, and `dead` called the tested class
+    //     dead. A derived edge may never be more trustworthy than the edge it
+    //     was derived from.
+    const nodeSourceFile = new Map(nodes.map((n) => [n.id, n.source_file]));
+    for (const e of [...edges]) {
+        if (e.relation !== 'imports') continue;
+        if (!isStatedResolution(e.resolved_via)) continue;
+        const from = nodeSourceFile.get(e.source);
+        if (from === undefined || !isTestFile(from)) continue;
+        const to = nodeSourceFile.get(e.target);
+        if (to === undefined || isTestFile(to)) continue;
+        emit({
+            source: e.source,
+            target: e.target,
+            relation: 'tests',
+            confidence: 'INFERRED',
+            resolved_via: 'test-import',
+            provider: 'native',
+        });
+    }
+
     // deterministic ordering
     nodes.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
     edges.sort((a, b) => {
@@ -677,6 +724,38 @@ function ambiguousTarget(candidates: readonly string[], targetName: string): str
     return `symbol:${targetName}`;
 }
 
+/**
+ * Is `relPath` a test file?
+ *
+ * A deterministic PATH predicate — no content read, no heuristic on the file's
+ * body. It is the input to the derived `tests` relation (3.2), so it has to be
+ * conservative in one direction only: a subject wrongly classified as a test
+ * silently loses its `tests` edges, while a test wrongly classified as a
+ * subject would make a test file look like a tested surface. Both are wrong;
+ * the second is worse, because `untested` would then report a real subject as
+ * covered.
+ *
+ * The four conventions are the ones this launch set actually uses, and each is
+ * anchored rather than substring-matched so a directory called
+ * `src/latest/thing.ts` is not a test:
+ *
+ *   · a `tests/` or `test/` path segment (this repository's own layout);
+ *   · a `__tests__/` segment (the JS convention);
+ *   · a `.test.` / `.spec.` filename infix (Vitest / Jest / Pest-JS);
+ *   · a `Test.php` / `test.php` filename suffix, or a `_test.php` infix
+ *     (PHPUnit's `*Test.php` and Go-style `_test` both appear in PHP trees).
+ */
+export function isTestFile(relPath: string): boolean {
+    const p = relPath.split(path.sep).join('/');
+    const segments = p.split('/');
+    if (segments.some((seg) => seg === 'tests' || seg === 'test' || seg === '__tests__')) return true;
+    const base = segments[segments.length - 1] ?? '';
+    if (/\.(test|spec)\./i.test(base)) return true;
+    if (/(^|[._-])test\.php$/i.test(base)) return true;
+    if (/Test\.php$/.test(base)) return true;
+    return false;
+}
+
 export function serializeGraph(g: CodeGraph): string {
     const key_order: (keyof CodeGraph)[] = [
         'schema_version',

package/src/scripts/code_graph/cli.ts

@@ -28,6 +28,20 @@
  * `agents/runtime/state/code-graph-v1.json`) is local-only and disposable —
  * gitignored, rebuildable from source at any time; never a source of truth.
  *
+ *   impact    --diff <rev> [--depth N]      callers/dependents/test files
+ *                                             reachable from the changed
+ *                                             symbols over ACCEPTED edges
+ *   tests-for <symbol>                        test files importing the symbol
+ *   untested  --diff <rev>                    changed symbols no test imports
+ *   dead      [--entry-points F]              zero accepted in-edges, minus
+ *             [--accept-missing-exports]      declared entry points; REFUSES
+ *                                             when a source is unavailable
+ *
+ * The four gate verbs (3.1–3.3) each print the `resolved_via` histogram of the
+ * edges they accepted AND of the edges they refused to walk, plus the graph's
+ * three-state staleness — so a caller can tell "no callers" from "no callers I
+ * would trust", and "dead" from "dead as of a graph 40 commits behind".
+ *
  * Query subcommands (query/path/explain/affected) are added by the Phase-3
  * query tier. Deterministic, LLM-free, no network. Exit codes:
  * 0 ok · 1 not-found / validation-failed / refresh-budget-exceeded ·
@@ -49,8 +63,8 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
-import { buildFromRepo, sidecarPath } from './build.js';
-import { computeVerdict, detectSources, pickSource } from './detect.js';
+import { buildFromRepo, isTestFile, sidecarPath } from './build.js';
+import { computeVerdict, detectSources, type GraphState, graphState, pickSource } from './detect.js';
 import { suggestVerb } from './intent.js';
 import {
     affected,
@@ -65,6 +79,18 @@ import {
 import { openGraphIndex, sqliteTwinPath } from './sqlite_store.js';
 import type { CodeGraph } from './types.js';
 import { validateGraph } from './validate.js';
+import {
+    dead,
+    type DeadResult,
+    entryPointsFromFile,
+    impact,
+    type ImpactResult,
+    repoEntryPoints,
+    testsFor,
+    type TestsForResult,
+    untested,
+    type UntestedResult,
+} from './verbs.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
@@ -258,10 +284,24 @@ function budgetOf(argv: string[]): number {
     return Number.isFinite(b) && b > 0 ? b : 1500;
 }
 
-function changedNodeSeeds(g: LoadedGraph, root: string, ref: string): string[] {
-    let files: string[];
+/**
+ * Files changed between `ref` and `HEAD`, repo-relative.
+ *
+ * Extracted from `changedNodeSeeds` so the Phase-3 verbs seed from the same
+ * diff reading as `affected --since`. `null` distinguishes "git refused" (a bad
+ * rev, not a repository) from "nothing changed" — a verb that reports an empty
+ * impact set for a rev git could not resolve is asserting something it never
+ * measured.
+ */
+export function changedFiles(root: string, ref: string): string[] | null {
+    // `execFileSync` takes an argv array, so there is no shell and `$(...)` in a
+    // rev is inert. What the `${ref}..HEAD` concatenation does NOT stop is
+    // OPTION injection: `--output=/tmp/x` becomes `--output=/tmp/x..HEAD`, a
+    // well-formed option whose value is a filename, and the file is written with
+    // exit 0 (probed 2026-09-09). A rev never begins with `-`.
+    if (ref.startsWith('-')) return null;
     try {
-        files = execFileSync('git', ['-C', root, 'diff', '--name-only', `${ref}..HEAD`], {
+        return execFileSync('git', ['-C', root, 'diff', '--name-only', `${ref}..HEAD`], {
             env: hardenedSpawnEnv(),
             encoding: 'utf-8',
             stdio: ['ignore', 'pipe', 'ignore'],
@@ -270,8 +310,13 @@ function changedNodeSeeds(g: LoadedGraph, root: string, ref: string): string[] {
             .map((s) => s.trim())
             .filter(Boolean);
     } catch {
-        return [];
+        return null;
     }
+}
+
+function changedNodeSeeds(g: LoadedGraph, root: string, ref: string): string[] {
+    const files = changedFiles(root, ref);
+    if (files === null) return [];
     // Served by the `nodes_source_file` index on the SQLite path, so a wide
     // diff does not force the whole node table into memory to answer it.
     return g.idsInFiles(files);
@@ -322,6 +367,213 @@ function isFlagValue(argv: string[], token: string): boolean {
     return i > 0 && (argv[i - 1] as string).startsWith('--');
 }
 
+// Phase-3 gate verbs (3.1-3.3).
+
+/** The staleness token every gate verb prints, per step 3.1–3.3's shared
+ * verify: "each prints `resolved_via` counts and the staleness state". */
+/**
+ * The staleness of the graph the verb is ACTUALLY reading.
+ *
+ * `answeredBy` is `resolveGraph`'s own picked path when it has one. Without it
+ * the two disagreed on the case `resolveRoot`'s docstring exists for: with
+ * `--root <other repo>` the verb answers from `DEFAULT_CACHE` (anchored to the
+ * package tree) while `graphState` looked under the OTHER root, so the printed
+ * staleness described a cache the answer never came from. An independent review
+ * found the `--graph` half fixed and this half open.
+ */
+function stateOf(argv: string[], answeredBy?: string): GraphState {
+    const explicit = flag(argv, '--graph');
+    return graphState(resolveRoot(argv), explicit ?? answeredBy);
+}
+
+/** The two histogram lines + the staleness line, in one place so the four
+ * verbs cannot drift apart in how they report their own filtering. */
+function renderEnvelope(r: { source: string; state: GraphState; accepted_via: string; rejected_via: string }): void {
+    process.stdout.write(`source: ${r.source}\nstaleness: ${r.state}\n`);
+    process.stdout.write(`accepted resolved_via: ${r.accepted_via}\n`);
+    process.stdout.write(`rejected resolved_via: ${r.rejected_via}\n`);
+}
+
+function renderReads(reads: readonly { path: string; lines: [number, number] | null }[]): void {
+    if (!reads.length) return;
+    process.stdout.write('minimal read set:\n');
+    for (const r of reads) process.stdout.write(`  ${r.path}${r.lines ? `:${r.lines[0]}-${r.lines[1]}` : ''}\n`);
+}
+
+/**
+ * `impact --diff <rev>` (3.1) — callers, dependents and test files reachable
+ * from the changed symbols over ACCEPTED edges, plus the producing edges and a
+ * minimal read set.
+ */
+function cmdImpact(argv: string[]): number {
+    const ref = flag(argv, '--diff');
+    if (ref === null) {
+        process.stderr.write('usage: code_graph/cli.ts impact --diff <rev> [--graph P] [--depth N]\n');
+        return 2;
+    }
+    const root = resolveRoot(argv);
+    const files = changedFiles(root, ref);
+    if (files === null) {
+        process.stderr.write(`code-graph: cannot resolve rev '${ref}' in ${root}\n`);
+        return 1;
+    }
+    const r = resolveGraph(argv);
+    if ('err' in r) {
+        process.stderr.write(`code-graph: ${r.err}\n`);
+        return 1;
+    }
+    try {
+        const depth = Number(flag(argv, '--depth'));
+        const res: ImpactResult = impact(
+            r.g,
+            files,
+            stateOf(argv, r.g.answeredBy),
+            Number.isFinite(depth) && depth > 0 ? depth : 2,
+            isTestFile,
+        );
+        renderEnvelope(res);
+        process.stdout.write(`changed files: ${files.length} · seeds: ${res.seeds.length}\n`);
+        if (res.unresolved_files.length)
+            process.stdout.write(`unresolved changed files (no node in the graph): ${res.unresolved_files.join(', ')}\n`);
+        process.stdout.write(`dependents (${res.dependents.length}):\n`);
+        for (const d of res.dependents) process.stdout.write(`  ${d}\n`);
+        process.stdout.write(`test files (${res.test_files.length}):\n`);
+        for (const t of res.test_files) process.stdout.write(`  ${t}\n`);
+        process.stdout.write(`producing edges (${res.producing_edges.length}):\n`);
+        for (const e of res.producing_edges) process.stdout.write(`  ${e}\n`);
+        renderReads(res.recommended_reads);
+        return 0;
+    } finally {
+        r.g.close();
+    }
+}
+
+/** `tests-for <symbol>` (3.2) — the test files that import the symbol. */
+function cmdTestsFor(argv: string[]): number {
+    const positional = argv.filter((a) => !a.startsWith('--') && !isFlagValue(argv, a));
+    const symbol = positional[0];
+    if (!symbol) {
+        process.stderr.write('usage: code_graph/cli.ts tests-for <symbol> [--graph P]\n');
+        return 2;
+    }
+    const r = resolveGraph(argv);
+    if ('err' in r) {
+        process.stderr.write(`code-graph: ${r.err}\n`);
+        return 1;
+    }
+    try {
+        const res: TestsForResult = testsFor(r.g, symbol, stateOf(argv, r.g.answeredBy));
+        renderEnvelope(res);
+        process.stdout.write(`seeds: ${res.seeds.join(', ') || '(none)'}\n`);
+        process.stdout.write(`tests (${res.tests.length}):\n`);
+        for (const t of res.tests) process.stdout.write(`  ${t}\n`);
+        renderReads(res.recommended_reads);
+        return 0;
+    } finally {
+        r.g.close();
+    }
+}
+
+/** `untested --diff <rev>` (3.2) — changed symbols no test file imports. */
+function cmdUntested(argv: string[]): number {
+    const ref = flag(argv, '--diff');
+    if (ref === null) {
+        process.stderr.write('usage: code_graph/cli.ts untested --diff <rev> [--graph P]\n');
+        return 2;
+    }
+    const root = resolveRoot(argv);
+    const files = changedFiles(root, ref);
+    if (files === null) {
+        process.stderr.write(`code-graph: cannot resolve rev '${ref}' in ${root}\n`);
+        return 1;
+    }
+    const r = resolveGraph(argv);
+    if ('err' in r) {
+        process.stderr.write(`code-graph: ${r.err}\n`);
+        return 1;
+    }
+    try {
+        const res: UntestedResult = untested(r.g, files, stateOf(argv, r.g.answeredBy));
+        renderEnvelope(res);
+        process.stdout.write(`changed files: ${files.length} · changed symbols: ${res.tested.length + res.untested.length}\n`);
+        if (res.unresolved_files.length)
+            process.stdout.write(`unresolved changed files (no node in the graph): ${res.unresolved_files.join(', ')}\n`);
+        process.stdout.write(`tested (${res.tested.length}) · untested (${res.untested.length}):\n`);
+        for (const u of res.untested) process.stdout.write(`  ${u}\n`);
+        renderReads(res.recommended_reads);
+        return 0;
+    } finally {
+        r.g.close();
+    }
+}
+
+/**
+ * `dead` (3.3) — symbols with zero accepted in-edges that no declared entry
+ * point names. REFUSES by default when an entry-point source is unavailable;
+ * see `verbs.ts::dead` for why that refusal is not relaxable by an options bag.
+ */
+function cmdDead(argv: string[]): number {
+    const r = resolveGraph(argv);
+    if ('err' in r) {
+        process.stderr.write(`code-graph: ${r.err}\n`);
+        return 1;
+    }
+    try {
+        const root = resolveRoot(argv);
+        const sources = repoEntryPoints(root);
+        const listFile = flag(argv, '--entry-points');
+        if (listFile !== null) {
+            if (!fs.existsSync(listFile)) {
+                process.stderr.write(`code-graph: entry-point list not found: ${listFile}\n`);
+                return 1;
+            }
+            // An operator-supplied list SUPPLIES the missing source, so the
+            // `exports` row stops being a gap rather than being ignored: the
+            // caller has stated the entry points the graph could not.
+            const supplied = entryPointsFromFile(listFile);
+            const patched = sources.map((srcRow) =>
+                srcRow.name === 'exports'
+                    ? { ...srcRow, status: 'read' as const, detail: `supplied by ${listFile}`, entries: [] }
+                    : srcRow,
+            );
+            patched.push(supplied);
+            const res: DeadResult = dead(r.g, patched, stateOf(argv, r.g.answeredBy));
+            return renderDead(res);
+        }
+        const res: DeadResult = dead(r.g, sources, stateOf(argv, r.g.answeredBy), {
+            acceptMissingExports: argv.includes('--accept-missing-exports'),
+        });
+        return renderDead(res);
+    } finally {
+        r.g.close();
+    }
+}
+
+function renderDead(res: DeadResult): number {
+    // The envelope FIRST, on both branches. It used to print only after the
+    // refusal check, so the default invocation in this repository — where
+    // `exports` is always unavailable — printed neither histogram nor the
+    // staleness line, and 3.1-3.3's shared verify ("each prints `resolved_via`
+    // counts and the staleness state") held only on the branch that answers.
+    // A reader of a refusal wants the staleness most of all: it says whether
+    // re-running after a rebuild could change anything.
+    renderEnvelope(res);
+    process.stdout.write('entry-point sources consulted:\n');
+    for (const srcRow of res.sources)
+        process.stdout.write(
+            `  ${srcRow.name.padEnd(13)} ${srcRow.status}${srcRow.detail ? ` — ${srcRow.detail}` : ''} · ${srcRow.entries.length} entr${srcRow.entries.length === 1 ? 'y' : 'ies'}\n`,
+        );
+    if (res.refusal !== null) {
+        process.stderr.write(`❌  dead refused: ${res.refusal}\n`);
+        return 1;
+    }
+    process.stdout.write(`excluded as declared entry points: ${res.excluded.length}\n`);
+    process.stdout.write(`dead (${res.dead.length}):\n`);
+    for (const d of res.dead) process.stdout.write(`  ${d}\n`);
+    renderReads(res.recommended_reads);
+    return 0;
+}
+
 function cmdDetect(argv: string[]): number {
     const root = resolveRoot(argv);
     if (flag(argv, '--format') === 'json') {
@@ -462,9 +714,14 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
         if (sub === 'refresh') return cmdRefresh(argv.slice(1));
         if (sub === 'query' || sub === 'explain' || sub === 'affected' || sub === 'path')
             return cmdQuery(sub, argv.slice(1));
+        if (sub === 'impact') return cmdImpact(argv.slice(1));
+        if (sub === 'tests-for') return cmdTestsFor(argv.slice(1));
+        if (sub === 'untested') return cmdUntested(argv.slice(1));
+        if (sub === 'dead') return cmdDead(argv.slice(1));
         if (sub === 'suggest-verb') return cmdSuggestVerb(argv.slice(1));
         process.stderr.write(
-            'usage: code_graph/cli.ts <build|validate|detect|refresh|query|explain|affected|path|suggest-verb> [options]\n',
+            'usage: code_graph/cli.ts <build|validate|detect|refresh|query|explain|affected|path|' +
+                'impact|tests-for|untested|dead|suggest-verb> [options]\n',
         );
         return 2;
     } catch (e) {