@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/ci_settle.ts

@@ -237,9 +237,30 @@ export function classifyPoll(stdout: string, stderr: string, status: number | nu
         return { kind: 'pending', total: rows.length, done };
     }
     const bad = new Set(['FAILURE', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED', 'STARTUP_FAILURE']);
-    const failing = rows
-        .filter((r) => bad.has(String(r.conclusion).toUpperCase()))
-        .map((r) => String(r.name ?? '?'));
+    // A concurrency group that supersedes its own earlier run leaves TWO rows
+    // under one name: the superseded one CANCELLED, the one that counts
+    // SUCCESS. The forge reports that check green; this classifier reported the
+    // whole PR red, because CANCELLED sat in `bad` and nothing looked at the
+    // twin. Measured 2026-10-01 on PR #2135 (`lint commit subjects`), where the
+    // false red cost a run a diagnosis it did not owe.
+    //
+    // The reprieve is deliberately the narrowest one that fixes it: CANCELLED
+    // only, and only when a row of the SAME NAME concluded SUCCESS. A genuine
+    // cancellation — a human stopping a run, a timeout killing one — has no
+    // successful twin and stays failing. Widening this to every bad conclusion,
+    // or to CANCELLED unconditionally, would trade a false red for a false
+    // green, which is the worse error in a tool whose output is acted on.
+    const nameOf = (r: (typeof rows)[number]): string => String(r.name ?? '?');
+    const concl = (r: (typeof rows)[number]): string => String(r.conclusion).toUpperCase();
+    const succeeded = new Set(rows.filter((r) => concl(r) === 'SUCCESS').map(nameOf));
+    const failing = [
+        ...new Set(
+            rows
+                .filter((r) => bad.has(concl(r)))
+                .filter((r) => !(concl(r) === 'CANCELLED' && succeeded.has(nameOf(r))))
+                .map(nameOf),
+        ),
+    ];
     return { kind: 'settled', failing, total: rows.length };
 }
 
@@ -293,25 +314,131 @@ function sleepSync(seconds: number): void {
     });
 }
 
-export function main(argv: readonly string[]): number {
-    const positional = argv.filter((a) => !a.startsWith('--'));
-    const pr = positional[0];
-    if (pr === undefined) {
-        process.stderr.write(
-            'usage: ci_settle <pr> [--timeout-min N] [--interval-sec N]\n' +
-                `  default --timeout-min is ${String(FOREGROUND_CEILING_MIN)}, which fits inside one foreground Bash call (600 s cap).\n` +
-                '  a longer wait is a BACKGROUND job, not a bigger number — a foreground call past the cap is killed and reports nothing.\n',
+/** The only flags this waiter honours. Anything else is a caller mistake. */
+const KNOWN_FLAGS = ['--timeout-min', '--interval-sec'] as const;
+
+const USAGE =
+    'usage: ci_settle <pr> [--timeout-min N] [--interval-sec N]\n' +
+    `  default --timeout-min is ${String(FOREGROUND_CEILING_MIN)}, which fits inside one foreground Bash call (600 s cap).\n` +
+    '  a longer wait is a BACKGROUND job, not a bigger number — a foreground call past the cap is killed and reports nothing.\n';
+
+export type ParsedArgs =
+    | { kind: 'ok'; pr: string; timeoutMin: number; intervalSec: number }
+    | { kind: 'usage'; message: string };
+
+/**
+ * Parse argv, REFUSING anything this waiter would not honour.
+ *
+ * Refusal rather than a default is the whole point. The previous parser read
+ * its two knobs with `argv.indexOf(flag)` and filtered positionals on a leading
+ * `--`, so a caller who wrote the near-universal `--timeout 1700` got two
+ * silent substitutions at once: the unknown flag was ignored, and its value —
+ * carrying no dashes — survived as a second positional and was dropped. The
+ * wait then ran for the 9-minute default while the caller believed they had
+ * asked for 28, and the resulting `DID NOT SETTLE` read as a slow CI rather
+ * than as their own typo.
+ *
+ * That is the one failure a waiter must not have. Its entire product is a
+ * verdict somebody will act on, and a verdict produced under arguments the
+ * caller did not actually give is worse than no verdict, because it looks like
+ * one. So every unrecognised flag, every unusable value and every extra
+ * positional is a usage refusal, exit 2 — the code this tool already reserves
+ * for "no verdict is claimed".
+ *
+ * `--flag=value` is accepted beside `--flag value` because it is the other
+ * spelling a caller reaches for, and refusing it would trade one silent
+ * surprise for a noisy one with no safety gained.
+ */
+export function parseArgs(argv: readonly string[]): ParsedArgs {
+    const refuse = (why: string): ParsedArgs => ({ kind: 'usage', message: `ci_settle: ${why}\n${USAGE}` });
+
+    const positional: string[] = [];
+    const given = new Map<string, string>();
+
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (!a.startsWith('--')) {
+            positional.push(a);
+            continue;
+        }
+        const eq = a.indexOf('=');
+        const name = eq === -1 ? a : a.slice(0, eq);
+        if (!(KNOWN_FLAGS as readonly string[]).includes(name)) {
+            return refuse(
+                `unknown flag ${name}. This waiter spells its deadline --timeout-min (in MINUTES), not --timeout`,
+            );
+        }
+        if (given.has(name)) return refuse(`${name} given twice`);
+        if (eq !== -1) {
+            given.set(name, a.slice(eq + 1));
+            continue;
+        }
+        const v = argv[i + 1];
+        if (v === undefined || v.startsWith('--')) return refuse(`${name} needs a value`);
+        given.set(name, v);
+        i++;
+    }
+
+    const raw = positional[0];
+    if (raw === undefined) return refuse('no PR number given');
+    if (positional.length > 1) {
+        return refuse(
+            `unexpected argument ${JSON.stringify(positional[1])} — this tool takes exactly one positional, the PR number; ` +
+                'a flag value must follow its own flag',
         );
-        return 2;
     }
-    const num = (flag: string, dflt: number): number => {
-        const i = argv.indexOf(flag);
-        if (i === -1) return dflt;
-        const v = argv[i + 1];
-        const n = v === undefined ? NaN : parseInt(v, 10);
-        return Number.isFinite(n) && n > 0 ? n : dflt;
+
+    // Finding 1 of the 2026-10-01 R2 review: the first version of this guard
+    // validated every OPTIONAL argument and waved the mandatory one through, so
+    // the failure it exists to remove stayed reachable through the front door.
+    // `ci_settle PR-2130` parsed as ok; `gh pr view PR-2130` then exits non-zero
+    // on every poll, each one classifies as unreadable, no streak caps the loop,
+    // and the run spends its entire budget to arrive at `DID NOT SETTLE` — which
+    // is read as a slow CI rather than as the typo it is. A guard that refuses
+    // the arguments a caller may omit and accepts the one they cannot is not a
+    // guard. `#123` and a PR URL are admitted because both are what a caller
+    // copies out of the forge; a branch name is NOT, because this tool's whole
+    // verdict is bound to one head and a branch makes that binding ambiguous.
+    const pr = /^#?[0-9]+$/.test(raw)
+        ? raw.replace(/^#/, '')
+        : (/^https?:\/\/[^\s]*\/pull\/([0-9]+)(?:[/?#].*)?$/.exec(raw)?.[1] ?? null);
+    if (pr === null || pr === '0' || /^0+$/.test(pr)) {
+        return refuse(
+            `${JSON.stringify(raw)} is not a PR number — give the number itself (2130), #2130, or the pull-request URL`,
+        );
+    }
+
+    const num = (flag: string, dflt: number): number | string => {
+        const v = given.get(flag);
+        if (v === undefined) return dflt;
+        const unit = flag === '--timeout-min' ? 'minutes' : 'seconds';
+        if (!/^[0-9]+$/.test(v)) return `${flag} wants a whole number of ${unit}, got ${JSON.stringify(v)}`;
+        const n = parseInt(v, 10);
+        // Finding 2: the parser this replaced guarded with `Number.isFinite`, and
+        // the digits-only test that replaced it does not. A long enough run of
+        // digits parses to Infinity, clears `n > 0`, and makes `deadline`
+        // unreachable — an unbounded wait in a tool whose contract is that it
+        // always returns a stated verdict or a stated non-verdict.
+        if (!Number.isFinite(n)) return `${flag} is too large to be a number of ${unit}`;
+        if (n <= 0) return `${flag} wants a positive number, got ${v}`;
+        return n;
     };
+
     const timeoutMin = num('--timeout-min', FOREGROUND_CEILING_MIN);
+    if (typeof timeoutMin === 'string') return refuse(timeoutMin);
+    const intervalSec = num('--interval-sec', 60);
+    if (typeof intervalSec === 'string') return refuse(intervalSec);
+
+    return { kind: 'ok', pr, timeoutMin, intervalSec };
+}
+
+export function main(argv: readonly string[]): number {
+    const parsed = parseArgs(argv);
+    if (parsed.kind === 'usage') {
+        process.stderr.write(parsed.message);
+        return 2;
+    }
+    const { pr, timeoutMin, intervalSec } = parsed;
     if (timeoutMin > FOREGROUND_CEILING_MIN) {
         // Said once, up front, rather than discovered when the call is killed:
         // a truncated wait produces no line at all, so the warning has to come
@@ -322,7 +449,6 @@ export function main(argv: readonly string[]): number {
                 'the deadline and will report nothing — run it as a background job for a wait this long.\n',
         );
     }
-    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.

package/src/scripts/closure_scan.ts

@@ -19,6 +19,8 @@
  *   `unpicked-alternative`     "either X or Y", "option A … option B"
  *   `unchecked-assumption`     "assuming", "presumably", "probably fine"
  *   `missing-verify`           an open step with no `verify:` line
+ *   `unfalsifiable-verify`     a step WITH a `verify:` line whose oracle
+ *                              cannot say no
  *   `ambiguous-acceptance`     a vague acceptance criterion (improve / clean up
  *                              / best practices / handle errors properly)
  *   `contradictory`            "contradicts", "conflicts with", "but also"
@@ -35,6 +37,24 @@
  * Exit codes: 0 no open decisions · 1 open decisions found · 2 bad argv.
  * Finding open decisions is the POINT, so `--strict` is what makes exit 1 a
  * failure for a caller that wants one; the default is a report.
+ *
+ * ONE FAMILY IS A LISTING AND NEVER A GATE. `unfalsifiable-verify` exits 0
+ * unconditionally — under `--strict` too — and that is a property of the
+ * family, not a flag a caller can flip. The reason is the one this script's
+ * own header already records about a detector that fires on ordinary prose,
+ * sharpened by a measurement: on 2026-09-29 the active roadmap tree carried
+ * 230 clauses and 6 machine-decidable expectations — 97.4% of them state no
+ * oracle — so a family promoted to a gate would red all but a handful of
+ * roadmaps at once, and the cheapest repair for a gate that reds on
+ * everything is to weaken it until it finds nothing. The exemption is
+ * narrow: a `tbd` in the same corpus still goes red under `--strict`.
+ *
+ * The figure is the MEASURED one, not the commissioning roadmap's. That
+ * roadmap asserted zero expectations tree-wide; a reading refuted it — six
+ * exist, all six written before the grammar was legal, and three of them are
+ * that roadmap's own verify lines. The producing
+ * command is `./scripts-run src/scripts/roadmap_verify_share`, so the number
+ * above is re-derivable rather than remembered.
  */
 
 import * as fs from 'node:fs';
@@ -42,6 +62,8 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+import { parseVerifyClause, type VerifyClause } from './_lib/verify_clause.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const _PROG = 'closure_scan';
 
@@ -50,6 +72,7 @@ export type Kind =
     | 'unpicked-alternative'
     | 'unchecked-assumption'
     | 'missing-verify'
+    | 'unfalsifiable-verify'
     | 'ambiguous-acceptance'
     | 'contradictory'
     | 'product-semantics'
@@ -74,6 +97,7 @@ export const OWNERSHIP_BY_KIND: Readonly<Record<Kind, string>> = {
     'unpicked-alternative': 'contested-technical',
     'unchecked-assumption': 'reversible-technical',
     'missing-verify': 'deterministic',
+    'unfalsifiable-verify': 'deterministic',
     'ambiguous-acceptance': 'reversible-technical',
     contradictory: 'contested-technical',
     'product-semantics': 'product-owned',
@@ -88,6 +112,73 @@ export const OWNER_ROUTED: ReadonlySet<string> = new Set([
     'destructive-owned',
 ]);
 
+/**
+ * Families that report and never gate — `--strict` cannot make these exit 1.
+ *
+ * A set rather than a flag, so the exemption is a property of the family that a
+ * caller cannot accidentally promote. See the header for the measurement that
+ * makes promotion a bad trade today.
+ */
+export const NON_BLOCKING_KINDS: ReadonlySet<Kind> = new Set<Kind>(['unfalsifiable-verify']);
+
+/**
+ * Command heads whose exit status is decided by something other than the
+ * property a step is claiming.
+ *
+ * Deliberately short. `echo`, `true` and `printf` cannot fail at all; `cat`,
+ * `ls`, `pwd` and `date` fail only on a missing path or a broken clock, never
+ * on the CONTENT a step asserts. Anything whose exit code already tracks the
+ * claim — `grep` (1 on no match), a linter, a test runner — is absent on
+ * purpose: including it would turn this listing into a census of every verify
+ * line in the tree, which is step 2.2's instrument, not this one.
+ */
+const FIXED_OUTPUT_HEADS: ReadonlySet<string> = new Set(['echo', 'true', 'printf', 'cat', 'ls', 'pwd', 'date']);
+
+/**
+ * Why this clause's oracle cannot say no — or `null` when it can.
+ *
+ * Three shapes, each one a way of carrying a `verify:` line that reads as
+ * verification and decides nothing.
+ *
+ * THE COUNT IS A LOWER BOUND, and saying so is the point. `scan()` assigns at
+ * most one kind per unit and the line patterns run first, so a step that also
+ * says "assuming", "merge" or "deploy" is claimed by the broader family and
+ * never reaches this one. Measured on 2026-09-29: 12 of 50 candidates were
+ * shadowed that way, so the published listing under-reports by roughly a
+ * quarter. A reader told a number and not told it is a floor would read the
+ * remainder as clean, which is the same mistake as reporting a share off a
+ * corpus nobody scanned.
+ */
+export function unfalsifiableReason(clause: VerifyClause): string | null {
+    if (clause.command === null) {
+        // A MANUAL clause asserting a QUANTITY nothing produced. Narrowed to a
+        // multi-digit number or an explicit `N of`/`N%` shape: a lone digit is
+        // usually a step id or an exit code being discussed, and firing on
+        // those would bury the real ones.
+        const quantity = /\b\d{2,}\b/.test(clause.raw) || /\b\d+\s*(?:%|of\b)/.test(clause.raw);
+        return quantity ? 'a manual clause asserts a quantity nothing here produces' : null;
+    }
+
+    const head = (clause.command.trim().split(/\s+/)[0] ?? '').split('/').pop() ?? '';
+    if (FIXED_OUTPUT_HEADS.has(head) && clause.expect?.kind !== 'regex') {
+        // A regex expectation rescues a fixed-output head: `cat f -> /x/` does
+        // decide something. An exit expectation does not — naming exit 0 on a
+        // command that cannot exit anything else adds a symbol, not an oracle.
+        return `the command head \`${head}\` produces a fixed result, so the clause cannot fail`;
+    }
+
+    if (clause.expect?.kind === 'regex') {
+        try {
+            if (new RegExp(clause.expect.source).test(clause.command)) {
+                return 'the expectation matches the command text, so an echo of the command satisfies it';
+            }
+        } catch {
+            // An expectation that cannot compile never became one upstream.
+        }
+    }
+    return null;
+}
+
 interface Pattern {
     readonly kind: Kind;
     readonly re: RegExp;
@@ -145,6 +236,17 @@ export interface Unit {
     /** 1-based line of the unit's first line. */
     readonly line: number;
     readonly text: string;
+    /**
+     * The same block with its NEWLINES intact.
+     *
+     * `text` is joined with spaces so a wrapped pattern still matches across
+     * the wrap, and that is right for the line patterns. It is wrong for the
+     * `verify:` clause: with no newline left, "to end of line" means "to end of
+     * the step", so a manual clause inherited every digit in the evidence block
+     * written under it. Measured before this field existed: 46 of 50
+     * `unfalsifiable-verify` hits fired on a quantity the clause never wrote.
+     */
+    readonly blockText: string;
     readonly inAcceptance: boolean;
     readonly isOpenStep: boolean;
     readonly hasVerify: boolean;
@@ -188,6 +290,7 @@ export function units(lines: readonly string[]): Unit[] {
                 // written with single spaces stops matching across the wrap —
                 // which is the case this unit exists to catch.
                 text: block.join(' ').replace(/\s+/g, ' '),
+                blockText: block.join('\n'),
                 inAcceptance,
                 isOpenStep: OPEN_STEP_RE.test(line),
                 hasVerify: /(?:^|\s)verify:/m.test(block.join('\n')),
@@ -198,6 +301,7 @@ export function units(lines: readonly string[]): Unit[] {
         out.push({
             line: i + 1,
             text: line,
+            blockText: line,
             inAcceptance,
             isOpenStep: false,
             hasVerify: false,
@@ -227,6 +331,14 @@ export function scan(text: string): Finding[] {
         if (matched === null && u.isOpenStep && !u.hasVerify && !u.inAcceptance) {
             matched = 'missing-verify';
         }
+        // A step that HAS a verify line, whose oracle still cannot say no.
+        // Checked on closed steps too — a `[x]` flipped on a command that
+        // could not fail is the defect in its completed form, and restricting
+        // this to open steps would hide every instance that already landed.
+        if (matched === null && u.hasVerify && !u.inAcceptance) {
+            const clause = parseVerifyClause(u.blockText);
+            if (clause !== null && unfalsifiableReason(clause) !== null) matched = 'unfalsifiable-verify';
+        }
         if (matched === null) continue;
         findings.push({
             id: '',
@@ -316,7 +428,9 @@ export function main(argv?: readonly string[]): number {
         }
     }
     if (!findings.length) return 0;
-    return strict ? 1 : 0;
+    // `--strict` goes red on the families that gate, never on the listing.
+    const blocking = findings.filter((f) => !NON_BLOCKING_KINDS.has(f.kind));
+    return strict && blocking.length > 0 ? 1 : 0;
 }
 
 function _isCliEntry(): boolean {

package/src/scripts/code_graph/detect.ts

@@ -17,7 +17,9 @@ import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { load_agent_settings } from '../_lib/agent_settings.js';
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
+import { EXT_LANG } from './types.js';
 import { validateGraph } from './validate.js';
 
 export type SourceKind = 'consumer' | 'scip' | 'native';
@@ -33,6 +35,44 @@ export interface SourceVerdict {
 
 const CONSUMER_CANDIDATES = ['graph.json', 'code-graph.json', '.code-graph/graph.json'];
 
+/**
+ * Extra graph paths the CONSUMER declares, from `code_graph.consumer_index_paths`.
+ *
+ * The default list above stays generic on purpose — three filenames, none of
+ * them any particular tool's. A tool that writes its index somewhere else is
+ * reachable by the consumer naming the path, never by this package shipping a
+ * table of vendor locations: such a table is wrong the day a tool moves its
+ * file and wrong forever about one nobody thought of, and
+ * `check_no_external_sources` would fail the build for carrying it.
+ *
+ * Absolute paths and anything escaping the project root are dropped. A setting
+ * that could point the walk at `/etc` would be a path-traversal surface in a
+ * read a consumer did not ask for.
+ */
+export function consumerCandidates(root: string): string[] {
+    let declared: unknown;
+    try {
+        const settings = load_agent_settings({ cwd: root }) ?? {};
+        const section = (settings as Record<string, unknown>)['code_graph'];
+        declared =
+            section !== null && typeof section === 'object' && !Array.isArray(section)
+                ? (section as Record<string, unknown>)['consumer_index_paths']
+                : undefined;
+    } catch {
+        declared = undefined;
+    }
+    const extra = Array.isArray(declared)
+        ? declared.filter(
+              (p): p is string =>
+                  typeof p === 'string' &&
+                  p !== '' &&
+                  !path.isAbsolute(p) &&
+                  !path.normalize(p).startsWith('..'),
+          )
+        : [];
+    return [...CONSUMER_CANDIDATES, ...extra.filter((p) => !CONSUMER_CANDIDATES.includes(p))];
+}
+
 function gitLastCommitEpoch(root: string): number | null {
     try {
         const out = execFileSync('git', ['-C', root, 'log', '-1', '--format=%ct'], {
@@ -100,7 +140,7 @@ export function detectSources(root: string, nativeCache: string): SourceVerdict[
     const abs = path.resolve(root);
     const out: SourceVerdict[] = [];
 
-    for (const rel of CONSUMER_CANDIDATES) {
+    for (const rel of consumerCandidates(abs)) {
         const p = path.join(abs, rel);
         if (fs.existsSync(p)) {
             const { ok, sha } = looksLikeGraph(p);
@@ -189,7 +229,12 @@ export function computeVerdict(root: string, nativeCache: string): VerdictJSON {
 export const NATIVE_CACHE_REL = path.join('agents', 'runtime', 'state', 'code-graph-v1.json');
 
 /**
- * The three-state staleness token every consumer of the graph reports.
+ * The four-state staleness token every consumer of the graph reports.
+ *
+ * `edited` is the fourth and newest (`road-to-a-graph-that-feeds-the-gate` 2.3).
+ * Without it an uncommitted change to an indexed file read as `fresh` — the one
+ * state that says "nothing stands between this answer and the tree" — which is
+ * the reading most likely to be wrong while someone is editing.
  *
  * Lives HERE rather than in the PreToolUse hook that first needed it
  * (`hooks/code_graph_context_hook.ts`, step 1.2). Phase 3's verbs must each
@@ -198,7 +243,73 @@ export const NATIVE_CACHE_REL = path.join('agents', 'runtime', 'state', 'code-gr
  * the engine, never the other way round. The hook re-exports this so its own
  * consumers are unaffected.
  */
-export type GraphState = 'absent' | 'fresh' | `behind:${number}`;
+export type GraphState = 'absent' | 'fresh' | 'edited' | `behind:${number}`;
+
+/**
+ * The working tree carries an uncommitted change to a file the extractor would
+ * index.
+ *
+ * WHY POINT-IN-TIME PORCELAIN AND NOT THE ARTIFACT'S MTIME. An mtime comparison
+ * looks cheaper and is wrong in the one direction that matters: restoring a
+ * stashed or checked-out file rewrites its mtime, so a tree put back exactly as
+ * the graph saw it would read stale forever and never return to `fresh`. The
+ * porcelain result describes a CONTENT difference, so a revert is visible as a
+ * revert.
+ *
+ * "Indexed paths" is read as *paths of the kind the extractor indexes* —
+ * `EXT_LANG`'s extensions — not as the node set of a loaded graph. Loading the
+ * graph to answer a freshness question would mean opening the index on every
+ * PreToolUse call this now runs on, which is the latency the Risk Register
+ * names; the extension filter answers the same question with no read. It can
+ * over-report (a `.ts` file the build excluded) and cannot under-report, and
+ * over-reporting `edited` only ever makes an answer look worth less than it is.
+ *
+ * Untracked files count. A source file that exists only in the working tree is
+ * precisely something the index cannot know about.
+ *
+ * `--untracked-files=all` IS LOAD-BEARING, and the default was wrong. Plain
+ * porcelain COLLAPSES an untracked directory to one entry — `?? src/` — which
+ * carries no extension, so the filter below skipped it and an entire new source
+ * tree read as `fresh`. A completion review reproduced exactly that, and it is
+ * the one direction the paragraph above promises cannot happen. The cost is
+ * enumerating untracked files rather than untracked directories; `.gitignore`
+ * still applies, so a vendored tree stays out of it.
+ */
+function hasUncommittedIndexedEdit(root: string): boolean {
+    let out: string;
+    try {
+        out = execFileSync('git', ['-C', root, 'status', '--porcelain', '--untracked-files=all'], {
+            env: hardenedSpawnEnv(),
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            // Both bounds are the review's: Node's 1 MB default would throw
+            // ENOBUFS on a large working tree, the catch below would return
+            // false, and the state would read `fresh` — a second silent
+            // under-report on a probe that runs at PreToolUse and at every stop.
+            // The timeout bounds the other failure: this probe sits in front of
+            // a tool call, so a hung git must not hold one up.
+            maxBuffer: 32 * 1024 * 1024,
+            timeout: 5_000,
+        });
+    } catch {
+        // Not a repository, or the probe failed: nothing is known, and an
+        // unknown is reported as the state the caller already had.
+        return false;
+    }
+    for (const raw of out.split('\n')) {
+        if (raw.length < 4) continue;
+        // `XY <path>`; a rename or copy is `XY <old> -> <new>`, and the NEW path
+        // is the one on disk. Quotes appear under core.quotepath for non-ASCII.
+        let p = raw.slice(3);
+        const arrow = p.indexOf(' -> ');
+        if (arrow !== -1) p = p.slice(arrow + 4);
+        p = p.trim().replace(/^"|"$/g, '');
+        const dot = p.lastIndexOf('.');
+        if (dot === -1) continue;
+        if (p.slice(dot).toLowerCase() in EXT_LANG) return true;
+    }
+    return false;
+}
 
 /**
  * Resolve the graph's state for `root`.
@@ -206,7 +317,10 @@ export type GraphState = 'absent' | 'fresh' | `behind:${number}`;
  * `absent` means no source at all — the silent case. A picked source whose
  * staleness is UNKNOWN reads as `fresh`, mirroring {@link computeVerdict}'s own
  * `picked.stale ? STALE : FRESH`: unknown is not treated as stale, because
- * inventing a commit count would be worse than reporting none.
+ * inventing a commit count would be worse than reporting none. A source level
+ * with HEAD then reads `edited` instead of `fresh` while the working tree
+ * carries an uncommitted change to an indexable file — see
+ * {@link hasUncommittedIndexedEdit} for why that probe is porcelain, not mtime.
  *
  * `nativeCache` overrides where the native graph is looked for. It exists
  * because a verb invoked with an explicit `--graph <path>` would otherwise
@@ -218,7 +332,13 @@ export type GraphState = 'absent' | 'fresh' | `behind:${number}`;
 export function graphState(root: string, nativeCache?: string): GraphState {
     const picked = pickSource(detectSources(root, nativeCache ?? path.join(root, NATIVE_CACHE_REL)));
     if (!picked) return 'absent';
-    if (picked.stale !== true) return 'fresh';
-    const behind = picked.commits_behind;
-    return `behind:${typeof behind === 'number' ? behind : 0}`;
+    if (picked.stale === true) {
+        const behind = picked.commits_behind;
+        return `behind:${typeof behind === 'number' ? behind : 0}`;
+    }
+    // The commit count comes FIRST and wins: `behind:N` already says the index
+    // predates committed work, and reporting `edited` instead would hide the
+    // larger gap behind the smaller one. Only a graph level with HEAD has an
+    // uncommitted edit as its whole remaining distance.
+    return hasUncommittedIndexedEdit(root) ? 'edited' : 'fresh';
 }