@event4u/agent-config 14.7.0 → 14.9.0

package/src/scripts/check_secret_leak.ts

@@ -38,6 +38,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { runSelfTest } from './_lib/gate_self_test.js';
 import { scanText, type SecretFinding } from './_lib/secret_detector.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -107,8 +108,34 @@ function isAllowed(rel: string, lineno: number, allow: readonly AllowEntry[]): b
     return allow.some((a) => a.file === rel && (a.line === null || a.line === lineno));
 }
 
-function isExcluded(rel: string): boolean {
-    return DEFAULT_EXCLUDE.some((rx) => rx.test(rel));
+/** `dist/` — excluded everywhere EXCEPT the pack scope. See `isExcluded`. */
+const DIST_EXCLUDE: RegExp = /(^|\/)dist(\/|$)/;
+
+function isExcluded(rel: string, mode: Mode = 'diff'): boolean {
+    return DEFAULT_EXCLUDE.some((rx) => {
+        // The `dist/` exclusion is the SECOND reason this gate could not see
+        // what ships, and it fires regardless of mode. Mode enumeration was the
+        // first: every git-backed mode walks the git tree, and `dist/cli/**` is
+        // gitignored while `dist/` is a `files[]` root. Adding the pack scope
+        // alone fixed nothing measurable — the payload resolved and then this
+        // filter threw away exactly the paths the scope exists to reach.
+        // Verified: a key-shaped string planted at `dist/zzcanary/leak.txt`
+        // (`git check-ignore -v` names `.gitignore:206`, and `npm pack` ships
+        // it) was missed by the new mode until this branch existed.
+        //
+        // Kept for every OTHER mode, because there the exclusion is right:
+        // `dist/` is a byte-for-byte projection of `src/`, which is scanned at
+        // its own path, so scanning the copy adds no coverage. In the pack scope
+        // the question is different — not "is this content somewhere else in the
+        // repo" but "does this content SHIP" — and for an untracked shipped path
+        // there is no other path to have scanned it at.
+        //
+        // The cost is a duplicate finding for a TRACKED dist file. That is not a
+        // false positive: a projection is byte-identical to its source, so a
+        // finding there is a finding in `src/` too.
+        if (mode === 'pack' && rx.source === DIST_EXCLUDE.source) return false;
+        return rx.test(rel);
+    });
 }
 
 /** Fast binary sniff — a NUL byte in the first 8 KiB means "not text". */
@@ -132,7 +159,48 @@ function gitLines(root: string, args: readonly string[]): string[] {
     return res.stdout.split('\n').filter((l) => l.trim() !== '');
 }
 
-export type Mode = 'diff' | 'all' | 'explicit';
+export type Mode = 'diff' | 'all' | 'explicit' | 'pack';
+
+/**
+ * `pack` exists because the other three cannot see a large part of what ships.
+ *
+ * Every one of them enumerates the GIT tree — `git diff`, `git ls-files`, or an
+ * explicit path list a caller derived from one. `dist/` is a `files[]` root and
+ * `dist/cli/**` is gitignored (`.gitignore:206` is `/dist/*`, and
+ * `git check-ignore -v dist/cli/agent-config.js` names that line), so those
+ * paths are shipped and untracked at the same time and this gate could not
+ * reach them **by construction** — not by misconfiguration.
+ *
+ * Additive on purpose: no existing caller changes behaviour, and the three
+ * git-backed modes are untouched.
+ */
+export function packPayloadFiles(root: string): string[] {
+    const out = spawnSync('npm', ['pack', '--dry-run', '--ignore-scripts', '--json'], {
+        cwd: root,
+        encoding: 'utf-8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (out.status !== 0 || typeof out.stdout !== 'string') {
+        // Returning [] would hand the scope assertion an empty set, which it
+        // already treats as a gate that could not run — the right verdict, and
+        // reached without inventing a second failure path.
+        return [];
+    }
+    const i = out.stdout.indexOf('[');
+    if (i < 0) return [];
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(out.stdout.slice(i));
+    } catch {
+        return [];
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0) return [];
+    const first = parsed[0] as { files?: { path?: unknown }[] };
+    const files = Array.isArray(first.files) ? first.files : [];
+    return files
+        .map((f) => (typeof f.path === 'string' ? f.path : ''))
+        .filter((pth) => pth !== '');
+}
 
 /**
  * Resolve the file set.
@@ -155,6 +223,9 @@ export function resolveFiles(
     if (mode === 'all') {
         return gitLines(root, ['ls-files']);
     }
+    if (mode === 'pack') {
+        return packPayloadFiles(root);
+    }
     const base = opts.base ?? 'origin/main';
     // An unresolvable base is a scan of NOTHING, not a clean scan.
     //
@@ -191,7 +262,7 @@ export function scanRepo(
     const applyExcludes = mode !== 'explicit';
     const hits: LeakHit[] = [];
     for (const rel of resolveFiles(root, mode, opts)) {
-        if (applyExcludes && isExcluded(rel)) {
+        if (applyExcludes && isExcluded(rel, mode)) {
             continue;
         }
         const abs = path.join(root, rel);
@@ -220,6 +291,7 @@ export function scanRepo(
 interface Args {
     json: boolean;
     all: boolean;
+    pack: boolean;
     base: string | undefined;
     paths: string[];
 }
@@ -228,6 +300,7 @@ function parseArgs(argv: readonly string[]): Args {
     const paths: string[] = [];
     let json = false;
     let all = false;
+    let pack = false;
     let base: string | undefined;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i] as string;
@@ -235,13 +308,17 @@ function parseArgs(argv: readonly string[]): Args {
             json = true;
         } else if (a === '--all') {
             all = true;
+        } else if (a === '--pack') {
+            pack = true;
         } else if (a === '--base') {
             base = argv[++i];
         } else if (a === '-h' || a === '--help') {
             _stdout(
-                'usage: check_secret_leak [paths...] [--all] [--base <ref>] [--json]\n' +
+                'usage: check_secret_leak [paths...] [--all] [--pack] [--base <ref>] [--json]\n' +
                     '  default → scans files changed vs origin/main + untracked (shift-left).\n' +
                     '  --all   → scans the whole tracked tree.\n' +
+                    '  --pack  → scans the npm pack payload, INCLUDING shipped-but-gitignored\n' +
+                    '            paths the three git-backed modes cannot reach.\n' +
                     '  paths   → scans exactly those paths (excludes skipped).\n' +
                     '  Exit 1 on a high-confidence leak.\n',
             );
@@ -253,7 +330,7 @@ function parseArgs(argv: readonly string[]): Args {
             paths.push(a);
         }
     }
-    return { json, all, base, paths };
+    return { json, all, pack, base, paths };
 }
 
 function _stdout(s: string): void {
@@ -263,9 +340,73 @@ function _stderr(s: string): void {
     process.stderr.write(s);
 }
 
+/**
+ * Discrimination, over the one property this branch added.
+ *
+ * The pack scope's whole value is that it reaches paths the git-backed modes
+ * cannot, and it was measurably INERT when first written: the mode resolved the
+ * payload and `DEFAULT_EXCLUDE`'s `dist/` rule then filtered away exactly those
+ * paths. A self-test over `isExcluded` is therefore not a formality here — it
+ * pins the difference between the mode working and the mode existing.
+ *
+ * Deliberately over the pure predicate rather than over a spawned `npm pack`:
+ * the canary in `gate-coverage.yml` already drives the real binary end to end
+ * with a real plant, and duplicating that here would add a pack run per case
+ * for no additional evidence.
+ */
+function selfTest(): number {
+    return runSelfTest({
+        gate: 'check_secret_leak',
+        minCases: 7,
+        minRejectCases: 3,
+        cases: [
+            {
+                name: 'pack scope does NOT exclude dist/ — the blind spot it exists for',
+                expect: 'reject',
+                run: () => (isExcluded('dist/cli/agent-config.js', 'pack') ? 0 : 1),
+            },
+            {
+                name: 'diff scope DOES exclude dist/ — a projection scanned at its source',
+                expect: 'accept',
+                run: () => (isExcluded('dist/cli/agent-config.js', 'diff') ? 0 : 1),
+            },
+            {
+                name: 'all scope also still excludes dist/ — untouched by this change',
+                expect: 'accept',
+                run: () => (isExcluded('dist/agent-src/rules/x.md', 'all') ? 0 : 1),
+            },
+            {
+                // The exclusion carve-out is `dist/` ONLY. If it leaked into the
+                // other rules the pack scope would start reading test fixtures,
+                // which legitimately hold secret-shaped strings.
+                name: 'pack scope still excludes tests/ — the carve-out is dist-only',
+                expect: 'accept',
+                run: () => (isExcluded('tests/fixtures/x.txt', 'pack') ? 0 : 1),
+            },
+            {
+                name: 'pack scope still excludes node_modules/',
+                expect: 'accept',
+                run: () => (isExcluded('node_modules/x/index.js', 'pack') ? 0 : 1),
+            },
+            {
+                name: 'pack scope reaches a second dist subtree, not just dist/cli',
+                expect: 'reject',
+                run: () => (isExcluded('dist/hooks/dispatch.js', 'pack') ? 0 : 1),
+            },
+            {
+                name: 'a shipped non-dist path is scanned in every mode',
+                expect: 'reject',
+                run: () => (isExcluded('src/scripts/x.ts', 'pack') || isExcluded('src/scripts/x.ts', 'diff') ? 0 : 1),
+            },
+        ],
+    });
+}
+
 export function main(argv?: readonly string[]): number {
-    const args = parseArgs(argv ?? process.argv.slice(2));
-    const mode: Mode = args.paths.length > 0 ? 'explicit' : args.all ? 'all' : 'diff';
+    const rawArgv = argv ?? process.argv.slice(2);
+    if (rawArgv.includes('--self-test')) return selfTest();
+    const args = parseArgs(rawArgv);
+    const mode: Mode = args.pack ? 'pack' : args.paths.length > 0 ? 'explicit' : args.all ? 'all' : 'diff';
 
     // Scope assertion, deliberately here and not inside `scanRepo`: that export
     // is called directly by tests and other callers against arbitrary roots, and
@@ -280,6 +421,11 @@ export function main(argv?: readonly string[]): number {
     // re-thrown untouched to preserve it.
     try {
         const targets = resolveFiles(REPO_ROOT, mode, { explicit: args.paths, base: args.base });
+        // The coverage register requires an enforced gate to report what it
+        // inspected. Printed before the assertion so a dead scope still tells
+        // the reader the number it died on, which is the one number that
+        // distinguishes "resolved nothing" from "resolved and filtered".
+        _stdout(`scanned: ${String(targets.length)}\n`);
         assertScanned({
             gate: 'check_secret_leak',
             scanned: targets.length,
@@ -289,9 +435,15 @@ export function main(argv?: readonly string[]): number {
                     ? ['git ls-files']
                     : mode === 'explicit'
                       ? ['<explicit path arguments>']
-                      : [`git diff --name-only --diff-filter=ACMR ${args.base ?? 'origin/main'}`, 'git ls-files --others --exclude-standard'],
-            // `all` and `explicit` carry no reason: zero tracked files, or zero
-            // named paths, is blindness in a repo that has content.
+                      : mode === 'pack'
+                        ? ['npm pack --dry-run --ignore-scripts payload (package.json files[])']
+                        : [`git diff --name-only --diff-filter=ACMR ${args.base ?? 'origin/main'}`, 'git ls-files --others --exclude-standard'],
+            // `all`, `explicit` and `pack` carry no reason: zero tracked files,
+            // zero named paths, or an empty pack payload is blindness in a repo
+            // that has content. `pack` inherits the strict path by omission
+            // rather than by a new branch — an empty payload means a botched
+            // `files[]` or a pack that resolved nothing, which is the loudest
+            // possible signal and the opposite of a clean bill.
             ...(mode === 'diff'
                 ? {
                       allowEmpty:
@@ -317,7 +469,9 @@ export function main(argv?: readonly string[]): number {
     if (args.json) {
         _stdout(JSON.stringify({ check: 'secret-leak', count: hits.length, hits }, null, 2) + '\n');
     } else if (hits.length === 0) {
-        _stdout('✅  check_secret_leak: no high-confidence secret found in the tracked tree.\n');
+        _stdout(
+            `✅  check_secret_leak: no high-confidence secret found in ${mode === 'pack' ? 'the npm pack payload' : 'the tracked tree'}.\n`,
+        );
     } else {
         _stderr(`❌  check_secret_leak: ${hits.length} high-confidence secret finding(s):\n`);
         for (const h of hits) {

package/src/scripts/check_single_delivery.ts

@@ -76,9 +76,9 @@ import { reportScanned } from './_lib/scan_scope.js';
 
 // ledger-exempt: this gate has no skip semantics to account for. `_lib/gate_ledger`
 // exists so a gate that PASSES OVER targets says which and why; here the target set
-// is four fixed artefact types, every one of them appears in the output, and a type
+// is six fixed artefact types, every one of them appears in the output, and a type
 // whose layer is missing is printed as `absent` rather than quietly dropped — see
-// the `absent` field and the `types_compared=N of 4` ledger line, which together
+// the `absent` field and the `types_compared=N of 6` ledger line, which together
 // already carry what a per-target ledger would. Adding one would restate the render
 // in a second format, and the gate's own docstring warns that the degenerate pass
 // here is a marker with no argument behind it. If a future version gains a real skip
@@ -88,10 +88,51 @@ import { reportScanned } from './_lib/scan_scope.js';
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
-/** Artefact types the host loads from both layers. */
-const TYPES = ['rules', 'skills', 'commands', 'agents'] as const;
+/**
+ * Artefact types the host loads from both layers.
+ *
+ * ## The identity key, named because it is not the same for every row
+ *
+ * Every row below compares BASENAMES within one family directory. For `rules`,
+ * `personas`, `user-types` and `agents` that IS the host's unit, so basename
+ * equality is the right key. For `commands` it is not: the host-visible unit is
+ * the invocation name `/cluster:sub`, which the colon form encodes in the PATH
+ * (`commands/<cluster>/<sub>.md`), so this gate's `commands` row compares cluster
+ * DIRECTORY names — a coarser key than the thing the host registers.
+ *
+ * That gap is recorded rather than closed, and the reason is a measurement: since
+ * `commandsWithheld` gates the colon-form generator, a machine with a verified
+ * host layer projects ZERO commands, so there is no project-side name for the
+ * coarse key to be wrong about. On a machine WITHOUT one, the project layer is
+ * the only layer and there is nothing to compare. The key is therefore imprecise
+ * exactly where it has no work to do. Closing it would mean reading each command
+ * file's own slug — real work for a row whose overlap is 0 in both topologies.
+ *
+ * `personas` and `user-types` were added 2026-08-21 (closure correction). See
+ * `unknownProjectFamilies` for what now prevents the next omission.
+ */
+const TYPES = ['rules', 'skills', 'commands', 'personas', 'user-types', 'agents'] as const;
 type ArtefactType = (typeof TYPES)[number];
 
+/**
+ * Directory names under `<repo>/.claude/` that the HOST writes, not a generator.
+ *
+ * `unknownProjectFamilies` used to rest on the premise that `<repo>/.claude/` is
+ * "written by `condense.ts` generators and nothing else". That premise is false
+ * and the gate proved it on 2026-08-22, refusing a release push over
+ * `.claude/worktrees/` — the maintainer's git-worktree root, gitignored at
+ * `.gitignore:246`, named as a conventional worktree location by
+ * `worktree_cleanup_check.STANDARD_WORKTREE_DIRS`, and excluded from
+ * `inventory_abstraction_budget`. Nothing about it is an artefact family, so
+ * "add it to TYPES" was advice that could not be taken.
+ *
+ * The set is hand-written and stays independent of any producer registry, for
+ * the same reason `TYPES` is: a verifier that derives its scope from a producer
+ * inherits that producer's omissions. It grows only on tree evidence that a name
+ * is host state — never to silence a family a generator actually emits.
+ */
+const HOST_OWNED = new Set(['worktrees']);
+
 /**
  * What a layer's entries physically ARE — symlinks, directories, or regular files.
  *
@@ -273,6 +314,54 @@ export interface Verdict {
     namesRead: number;
     /** True when no type had BOTH layers present — nothing was actually compared. */
     readNothing: boolean;
+    /**
+     * Family directories present in the PROJECT layer that `TYPES` does not name.
+     *
+     * The forcing function that makes this gate's own 2026-08-21 omission
+     * non-recurring: `personas` was written by a generator, shipped by the
+     * installer, and named by neither measurer, so it was invisible rather than
+     * reported — a gate cannot report a family it was never told exists.
+     *
+     * Only the PROJECT layer is scanned, and that is the whole reason this can be
+     * a hard refusal rather than a warning. Every entry in `<repo>/.claude/` is a
+     * family this repository chose to emit, EXCEPT the host-written names in
+     * `HOST_OWNED` — see that constant for why the unqualified version of this
+     * sentence was wrong. `~/.claude/` is the host's own directory —
+     * `plugins`, `projects`, `sessions`, `shell-snapshots`, `telemetry` and a
+     * dozen more live there — and treating an unrecognised name in it as a defect
+     * would be a false-positive generator, not a check.
+     */
+    unknownFamilies: string[];
+}
+
+/**
+ * Family directories the project layer holds that `TYPES` does not name.
+ *
+ * Deliberately NOT derived from the installer's `_CLAUDE_SKILL_BUNDLE` or from
+ * `check_generator_output_coverage`'s registry: a verifier whose scope comes from
+ * a producer inherits that producer's omissions, which is the exact defect this
+ * function exists to catch. `TYPES` stays hand-written and independent; this
+ * compares it against the filesystem the generators actually produced and refuses
+ * on disagreement.
+ */
+function unknownProjectFamilies(projectRoot: string): string[] {
+    const known = new Set<string>(TYPES);
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(projectRoot, { withFileTypes: true });
+    } catch {
+        return []; // no project layer at all — nothing emitted, nothing to miss
+    }
+    return entries
+        .filter(
+            (e) =>
+                e.isDirectory() &&
+                !e.name.startsWith('.') &&
+                !known.has(e.name) &&
+                !HOST_OWNED.has(e.name),
+        )
+        .map((e) => e.name)
+        .sort();
 }
 
 export function evaluate(globalRoot: string, projectRoot: string): Verdict {
@@ -299,6 +388,7 @@ export function evaluate(globalRoot: string, projectRoot: string): Verdict {
             0,
         ),
         readNothing: compared === 0,
+        unknownFamilies: unknownProjectFamilies(projectRoot),
     };
 }
 
@@ -354,12 +444,24 @@ export function render(v: Verdict, globalRoot: string, projectRoot: string): str
         out.push('');
         out.push(`  layers not present (nothing to compare there): ${v.absent.join(', ')}`);
     }
+    if (v.unknownFamilies.length > 0) {
+        out.push('');
+        out.push(
+            `  ❌  unknown family in the project layer: ${v.unknownFamilies.join(', ')}` +
+                ' — add it to TYPES in this gate AND in _lib/layer_overlap_notice.ts,',
+        );
+        out.push(
+            '      or the next family shipped from two layers is invisible the way `personas`' +
+                ' was until 2026-08-21.',
+        );
+    }
     out.push('');
     out.push(
         `check_single_delivery ledger: duplicated=${v.duplicated}` +
             ` name_overlap_different_shape=${v.nameOverlapDifferentShape}` +
             ` scope_defeat=${v.defeated}` +
             ` types_compared=${v.typesCompared} of ${v.readings.length}` +
+            ` unknown_families=${v.unknownFamilies.length}` +
             ` names_read=${v.namesRead}`,
     );
     return out.join('\n');
@@ -459,6 +561,37 @@ export function main(argv?: readonly string[]): number {
             ' case (layers present but never paired) is refused separately.',
     });
 
+    // Refuses in both modes, unlike every other branch here — but ONLY over this
+    // repository's own generated tree, and that qualification was added by a
+    // neutral review (2026-08-21) rather than being there from the start.
+    //
+    // The asymmetry is the argument for the refusal: every other verdict here is
+    // a property of ONE MACHINE's two layers, which is why `--enforce` is opt-in.
+    // "this repository emits a family no measurer names" is true on every checkout
+    // and fixable in one line, so gating it behind `--enforce` would put the one
+    // topology-independent check behind the flag meant for topology-dependent
+    // ones.
+    //
+    // The qualification is the review's, and it is right: an unrecognised
+    // DIRECTORY does not by itself establish generator ownership. It does under
+    // `<repo>/.claude/`, which `condense.ts` writes and nothing else does. It does
+    // NOT under an arbitrary `--project` path, which may be a consumer tree with
+    // a host-native or project-only family that legitimately cannot overlap — and
+    // refusing there would make a nominal report exit 1 on a correct topology.
+    // So a repointed root REPORTS and does not refuse.
+    if (v.unknownFamilies.length > 0) {
+        const own = projectRoot === path.join(REPO_ROOT, '.claude');
+        process.stdout.write(
+            `${own ? '❌' : '⚠️ '}  check_single_delivery: unknown family in the project` +
+                ` layer: ${v.unknownFamilies.join(', ')}. Add measurement before it can ship` +
+                ' — TYPES in this gate and in _lib/layer_overlap_notice.ts.' +
+                (own ? '' : ' Reported, not enforced: --project is repointed, so generator' +
+                    ' ownership of this tree is not established.') +
+                '\n',
+        );
+        if (own) return 1;
+    }
+
     if (v.readNothing) {
         // Never a pass. A gate that compared nothing has not verified anything,
         // and saying "invariant holds" here is the false-green shape this repo

package/src/scripts/check_standing_rule_delivery.ts

@@ -326,8 +326,14 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     if (pct > 1) {
         process.stderr.write(
             `❌  ${PROG}: ${total} tok of standing rule prose exceeds the ${budget.total_cap_tokens} cap. `
-                + 'If two layers overlap, `agent-config install --layer=<global|project>` suppresses one '
-                + 'without deleting a file; otherwise scope rules with `paths:` or move bodies into the digest.\n',
+                + 'If two layers overlap, that is the ADR-236 partition not yet armed on this '
+                + 'machine: run `agent-config install` so the host layer is fingerprinted in '
+                + 'installed.lock, and the next `task generate-tools` withholds the globally-owned '
+                + 'artefacts instead of writing a second copy. (Superseded advice: this line used to '
+                + 'name `install --layer=<global|project>`, the layer-suppression remedy ADR-226 '
+                + 'declined and ADR-236 replaced — a reader following it could not fix the '
+                + 'condition.) Otherwise the total is body length, not duplication: scope rules with '
+                + '`paths:` or move bodies into the digest.\n',
         );
         return 1;
     }

package/src/scripts/code_graph/cli.ts

@@ -77,8 +77,47 @@ function flag(argv: string[], name: string): string | null {
     return i >= 0 && i + 1 < argv.length ? (argv[i + 1] as string) : null;
 }
 
+/**
+ * Resolve the repository to operate on. `--root` > `AGENT_CONFIG_PROJECT_ROOT` >
+ * this module's own tree.
+ *
+ * The middle rung is the whole point, and its absence was a confused deputy:
+ * `_dispatch.bash` parses `--root` GLOBALLY, strips it from argv, and exports
+ * `AGENT_CONFIG_PROJECT_ROOT` (`:1655`) — then this engine read neither and fell
+ * back to its own module path. So `agent-config code-graph build --root <other
+ * repo>` silently indexed THIS package. The dispatcher made the decision and the
+ * engine substituted its own, which is why every consumer-facing invocation was
+ * wrong about which repository it had just read.
+ *
+ * `realpathSync` rather than `resolve` alone: a symlinked root must normalise to
+ * what will actually be walked, or the path a caller sees in the output is not
+ * the path that was indexed. Fail-loud on a root that does not exist — a silent
+ * fallback to the package tree is the defect this function exists to remove, and
+ * reintroducing it for a typo'd path would be the same bug wearing a smaller
+ * hat.
+ *
+ * Deliberately NOT touching `DEFAULT_CACHE`, which is anchored to `REPO_ROOT`
+ * for the same reason and is a separate decision: it is a WRITE path, with its
+ * own ownership, cleanup, concurrency and multi-repo namespacing questions.
+ * Council 2026-08-22, both seats, explicitly out of scope here.
+ */
+function resolveRoot(argv: string[]): string {
+    const explicit = flag(argv, '--root');
+    const fromDispatcher = process.env['AGENT_CONFIG_PROJECT_ROOT'];
+    const candidate =
+        explicit ?? (fromDispatcher !== undefined && fromDispatcher !== '' ? fromDispatcher : REPO_ROOT);
+    try {
+        return fs.realpathSync(path.resolve(candidate));
+    } catch {
+        // Returned unresolved on purpose: every caller checks existence and
+        // prints the path it was given, which is more useful in the error than
+        // a normalised form of a path that does not exist.
+        return path.resolve(candidate);
+    }
+}
+
 async function cmdBuild(argv: string[]): Promise<number> {
-    const root = flag(argv, '--root') ?? REPO_ROOT;
+    const root = resolveRoot(argv);
     const out = argv.includes('--out') ? flag(argv, '--out') : DEFAULT_CACHE;
     if (!fs.existsSync(root)) {
         process.stderr.write(`code-graph: root not found: ${root}\n`);
@@ -122,7 +161,7 @@ function cmdValidate(argv: string[]): number {
 
 function resolveGraph(argv: string[]): { g: LoadedGraph; note: string } | { err: string } {
     const explicit = flag(argv, '--graph');
-    const root = flag(argv, '--root') ?? REPO_ROOT;
+    const root = resolveRoot(argv);
     if (explicit) {
         if (!fs.existsSync(explicit)) return { err: `graph not found: ${explicit}` };
         return { g: loadGraph(explicit, path.relative(REPO_ROOT, explicit)), note: '' };
@@ -179,7 +218,7 @@ function cmdQuery(kind: 'query' | 'explain' | 'affected' | 'path', argv: string[
     const positional = argv.filter((a) => !a.startsWith('--') && !isFlagValue(argv, a));
     const budget = budgetOf(argv);
     if (kind === 'affected' && flag(argv, '--since')) {
-        const root = flag(argv, '--root') ?? REPO_ROOT;
+        const root = resolveRoot(argv);
         const seeds = changedNodeSeeds(r.g, root, flag(argv, '--since') as string);
         const merged: QueryResult = { source: r.g.source, seeds: [], lines: [], truncated: false, recommended_reads: [] };
         const perSeed: QueryResult[] = [];
@@ -216,7 +255,7 @@ function isFlagValue(argv: string[], token: string): boolean {
 }
 
 function cmdDetect(argv: string[]): number {
-    const root = flag(argv, '--root') ?? REPO_ROOT;
+    const root = resolveRoot(argv);
     if (flag(argv, '--format') === 'json') {
         // Machine-readable three-state verdict (Phase 2). Existing human-text
         // output below is unchanged for existing consumers.
@@ -316,7 +355,7 @@ function runBudgetedBuild(root: string, out: string, update: boolean, budgetSeco
 }
 
 function cmdRefresh(argv: string[]): number {
-    const root = flag(argv, '--root') ?? REPO_ROOT;
+    const root = resolveRoot(argv);
     const out = flag(argv, '--out') ?? DEFAULT_CACHE;
     const budgetSeconds = budgetSecondsOf(argv);
     if (!fs.existsSync(root)) {

package/src/scripts/code_graph/extract.ts

@@ -306,6 +306,93 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                 if (body) for (const c of namedChildren(body)) walk(c, classId, id);
                 return;
             }
+            // Modern TS declares most of its functions as bindings, not as
+            // `function` statements. Before this case the extractor produced
+            // NO node for `export const f = () => {}` or
+            // `const g = function () {}`, which is the measured cause of the
+            // 170-vs-13,428 TS/PHP symbol gap: the six handled kinds simply do
+            // not cover the dominant declaration form.
+            //
+            // Scoped deliberately to bindings whose value IS a function. A
+            // `const x = 3` is data, not a symbol this graph answers questions
+            // about, and emitting a node per constant would inflate the count
+            // without improving recall — which is the cosmetic-improvement
+            // failure the phase falsifier exists to catch.
+            case 'lexical_declaration':
+            case 'variable_declaration': {
+                for (const d of namedChildren(n)) {
+                    if (d.type !== 'variable_declarator') continue;
+                    const value = d.childForFieldName('value');
+                    if (!value || (value.type !== 'arrow_function' && value.type !== 'function_expression')) {
+                        continue;
+                    }
+                    const nm = nameField(d) ?? '<anon>';
+                    const id = classId ? `${classId}::${nm}` : `${file}#${nm}`;
+                    out.nodes.push({
+                        id,
+                        label: nm,
+                        kind: classId ? 'method' : 'function',
+                        source_file: file,
+                        source_location: loc(d),
+                    });
+                    out.rawEdges.push({
+                        sourceId: classId ?? fileId,
+                        relation: 'member',
+                        targetName: nm,
+                        confidenceHint: 'EXTRACTED',
+                    });
+                    // Walk the body under the BINDING's scope, so a call inside
+                    // an arrow function attributes to that function rather than
+                    // to the enclosing file — the same treatment
+                    // `function_declaration` gets.
+                    //
+                    // `walk(body)` and not `namedChildren(body)`: an
+                    // expression-bodied arrow (`() => helper()`) has the CALL
+                    // itself as its body, so descending one level first steps
+                    // straight past it and the edge is lost. The sibling cases
+                    // can iterate children because a `statement_block` is never
+                    // the interesting node; here it often is.
+                    const body = value.childForFieldName('body');
+                    if (body) walk(body, classId, id);
+                }
+                // Non-function declarators still need walking for their calls.
+                for (const d of namedChildren(n)) {
+                    if (d.type !== 'variable_declarator') continue;
+                    const value = d.childForFieldName('value');
+                    if (value && (value.type === 'arrow_function' || value.type === 'function_expression')) {
+                        continue;
+                    }
+                    walk(d, classId, scopeId);
+                }
+                return;
+            }
+            // `class C { m = () => 1 }` — a class property holding a function.
+            // Emitted as a `method`, the same kind `method_definition` emits,
+            // because it is one to every caller.
+            case 'public_field_definition': {
+                const value = n.childForFieldName('value');
+                const nm = nameField(n) ?? '<anon>';
+                if (value && (value.type === 'arrow_function' || value.type === 'function_expression')) {
+                    const id = classId ? `${classId}::${nm}` : `${file}#${nm}`;
+                    out.nodes.push({
+                        id,
+                        label: nm,
+                        kind: 'method',
+                        source_file: file,
+                        source_location: loc(n),
+                    });
+                    out.rawEdges.push({
+                        sourceId: classId ?? fileId,
+                        relation: 'member',
+                        targetName: nm,
+                        confidenceHint: 'EXTRACTED',
+                    });
+                    const body = value.childForFieldName('body');
+                    if (body) walk(body, classId, id);
+                    return;
+                }
+                break;
+            }
             case 'new_expression': {
                 const ctor = n.childForFieldName('constructor');
                 if (ctor && (ctor.type === 'identifier' || ctor.type === 'type_identifier' || ctor.type === 'member_expression'))