@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/classify_merge_risk.ts

@@ -0,0 +1,320 @@
+#!/usr/bin/env tsx
+/**
+ * classify_merge_risk — ADR-282's danger gate in front of an authorized
+ * auto-merge.
+ *
+ * Says `routine` or `needs-council` for a diff, plus the triggers that fired.
+ * `routine` merges on the owner's auto-merge instruction with no review;
+ * `needs-council` sends the diff to the AI council first. The classifier is
+ * advisory to that flow and grants nothing on its own.
+ *
+ * Every trigger is lifted from a rule that already exists, never invented here:
+ *
+ *   - `non-destructive-by-default` Hard-Floor rows: bulk deletion (a removed
+ *     directory, or DELETION_THRESHOLD deleted files), infrastructure config,
+ *     production data and migrations, deploy and release paths.
+ *   - `security-sensitive-stop` surfaces: auth, authz, tenancy, billing,
+ *     secrets, uploads, webhooks, route files (public endpoints).
+ *   - The ratification surfaces, read through `check_kernel_edit_ratified`'s own
+ *     `classifyPaths` — a second list would drift from the first.
+ *   - Any CI workflow: `process-full` makes a disabled required check the thing
+ *     delivery-ready must refuse, and a green rollup on a weakened workflow is
+ *     exactly what a no-review merge would trust.
+ *   - Its own surface — this file and the two commands that call it — for the
+ *     reason the ratification gate watches itself: a routine-class PR must not
+ *     be able to loosen the gate that classed it.
+ *
+ * Prose files (`.md`, `.mdx`, `.txt`, `.rst`) are exempt from the security,
+ * infra and migration token checks: a skill ABOUT secrets is not a secret
+ * surface. They stay subject to deletion, governance and self-surface checks.
+ *
+ * Fails closed: a diff that cannot be read is `needs-council`, never `routine`,
+ * and never an internal-error exit a caller might read as "nothing found".
+ *
+ * Inputs (one of):
+ *   <pr-number>           PR mode: base and head read via `gh`, head fetched
+ *   --range BASE..HEAD    range mode (`...` also accepted)
+ * Options:
+ *   --root DIR            repository to read (default: cwd)
+ *   --json                one JSON object instead of text
+ *
+ * Exit codes: 0 = routine · 1 = needs-council (including fail-closed).
+ * The LAST output line is the verdict.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { classifyPaths, requiresRatification } from './check_kernel_edit_ratified.js';
+
+export const DELETION_THRESHOLD = 5;
+
+export interface ChangeEntry {
+    status: string;
+    path: string;
+    oldPath?: string;
+}
+
+export interface Trigger {
+    id: string;
+    rule: string;
+    paths: string[];
+}
+
+export interface Classification {
+    verdict: 'routine' | 'needs-council';
+    triggers: Trigger[];
+}
+
+export interface ClassifyOptions {
+    /** Does `dir` still exist in the head tree? Decides a removed directory. */
+    dirExistsInHead: (dir: string) => boolean;
+}
+
+const PROSE_EXT = new Set(['.md', '.mdx', '.txt', '.rst']);
+
+const SECURITY_TOKENS = new Set([
+    'auth', 'authn', 'authz', 'authenticate', 'authentication', 'authorization', 'authorize',
+    'login', 'logout', 'oauth', 'sso', 'saml', 'mfa', '2fa', 'password', 'passwords', 'passwd', 'jwt',
+    'permission', 'permissions', 'rbac', 'acl', 'policy', 'policies',
+    'tenant', 'tenants', 'tenancy', 'multitenancy',
+    'billing', 'payment', 'payments', 'invoice', 'invoices', 'subscription', 'subscriptions',
+    'refund', 'refunds', 'charge', 'charges',
+    'secret', 'secrets', 'credential', 'credentials', 'vault', 'kms', 'env',
+    'upload', 'uploads', 'webhook', 'webhooks', 'routes',
+]);
+
+const INFRA_SEGMENTS = new Set([
+    'terraform', 'terragrunt', 'pulumi', 'k8s', 'kubernetes', 'helm', 'charts', 'ansible',
+    'cloudformation', 'cdk', 'infra', 'infrastructure',
+]);
+const INFRA_EXT = new Set(['.tf', '.tfvars', '.hcl']);
+const INFRA_BASENAME_RE = /^(?:Pulumi(?:\.[\w-]+)?\.ya?ml|Chart\.ya?ml|kustomization\.ya?ml|serverless\.ya?ml)$/;
+
+const PROD_TOKENS = new Set(['prod', 'production']);
+const MIGRATION_SEGMENTS = new Set(['migrations', 'migration', 'migrate']);
+const DEPLOY_TOKENS = new Set(['deploy', 'deployment', 'deployments', 'release', 'releases', 'publish']);
+
+const SELF_SURFACE_RE =
+    /(?:^|\/)(?:scripts\/classify_merge_risk\.ts|domains\/git\/pr\/merge\/command\.md|domains\/product-basic\/roadmap\/process-full\/command\.md)$|^docs\/decisions\/ADR-282-[^/]+\.md$/;
+
+/** Lower-cased word tokens of a path: split on separators and camelCase. */
+function tokens(p: string): string[] {
+    return p
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[\/._\-\s]+/)
+        .filter((t) => t !== '');
+}
+
+function segments(p: string): string[] {
+    return p.toLowerCase().split('/');
+}
+
+function isProse(p: string): boolean {
+    return PROSE_EXT.has(path.posix.extname(p).toLowerCase());
+}
+
+function isSecurity(p: string): boolean {
+    if (isProse(p)) {
+        return false;
+    }
+    const base = path.posix.basename(p);
+    if (base === '.env' || base.startsWith('.env.')) {
+        return true;
+    }
+    return tokens(p).some((t) => SECURITY_TOKENS.has(t));
+}
+
+function isInfra(p: string): boolean {
+    if (INFRA_EXT.has(path.posix.extname(p).toLowerCase()) || INFRA_BASENAME_RE.test(path.posix.basename(p))) {
+        return true;
+    }
+    return !isProse(p) && segments(p).slice(0, -1).some((s) => INFRA_SEGMENTS.has(s));
+}
+
+function isProdOrMigration(p: string): boolean {
+    if (path.posix.extname(p).toLowerCase() === '.sql') {
+        return true;
+    }
+    if (isProse(p)) {
+        return false;
+    }
+    return segments(p).some((s) => MIGRATION_SEGMENTS.has(s)) || tokens(p).some((t) => PROD_TOKENS.has(t));
+}
+
+function isDeployOrRelease(p: string): boolean {
+    return !isProse(p) && tokens(p).some((t) => DEPLOY_TOKENS.has(t));
+}
+
+function isWorkflow(p: string): boolean {
+    return p.startsWith('.github/workflows/');
+}
+
+/** Every path a change touches — both sides of a rename or copy. */
+function touched(entries: readonly ChangeEntry[]): string[] {
+    const out = new Set<string>();
+    for (const e of entries) {
+        out.add(e.path);
+        if (e.oldPath !== undefined) {
+            out.add(e.oldPath);
+        }
+    }
+    return [...out];
+}
+
+export function classifyChanges(entries: readonly ChangeEntry[], opts: ClassifyOptions): Classification {
+    const triggers: Trigger[] = [];
+    const add = (id: string, rule: string, paths: string[]): void => {
+        if (paths.length > 0) {
+            triggers.push({ id, rule, paths: [...paths].sort() });
+        }
+    };
+    const all = touched(entries);
+    const deleted = entries.filter((e) => e.status === 'D').map((e) => e.path);
+
+    if (deleted.length >= DELETION_THRESHOLD) {
+        add('bulk-deletion', `non-destructive-by-default — ${deleted.length} deleted files (≥ ${DELETION_THRESHOLD})`, deleted);
+    }
+    const goneDirs = [...new Set(deleted.map((p) => path.posix.dirname(p)).filter((d) => d !== '.'))].filter(
+        (d) => !opts.dirExistsInHead(d),
+    );
+    add(
+        'removed-directory',
+        'non-destructive-by-default — a directory no longer exists in the head',
+        deleted.filter((p) => goneDirs.includes(path.posix.dirname(p))),
+    );
+    add('infra-config', 'non-destructive-by-default — Terraform / Pulumi / k8s / Ansible / cloud config', all.filter(isInfra));
+    add('prod-data-or-migration', 'non-destructive-by-default — production data or a migration', all.filter(isProdOrMigration));
+    add('deploy-or-release', 'non-destructive-by-default — deploy or release path', all.filter(isDeployOrRelease));
+    add('ci-workflow', 'process-full — a disabled required check cannot reach delivery-ready', all.filter(isWorkflow));
+    add('security-surface', 'security-sensitive-stop — auth, authz, tenancy, billing, secrets, uploads, webhooks, routes', all.filter(isSecurity));
+
+    const gated = classifyPaths(all);
+    if (requiresRatification(gated)) {
+        const gatedPaths = [...gated.kernelRules, ...gated.governanceHooks, ...gated.plumbing];
+        add(
+            'governance-surface',
+            'check_kernel_edit_ratified — kernel rule, governance hook, hook plumbing or the ratification mechanism',
+            gatedPaths.length > 0 ? gatedPaths : all.filter((p) => classifyPaths([p]).self),
+        );
+    }
+    add('merge-authority-surface', 'ADR-282 — the danger gate and the commands that call it', all.filter((p) => SELF_SURFACE_RE.test(p)));
+
+    return { verdict: triggers.length > 0 ? 'needs-council' : 'routine', triggers };
+}
+
+/** Parse `git diff --name-status` output. Throws on a line it cannot read. */
+export function parseNameStatus(text: string): ChangeEntry[] {
+    const out: ChangeEntry[] = [];
+    for (const line of text.split('\n')) {
+        if (line.trim() === '') {
+            continue;
+        }
+        const parts = line.split('\t');
+        const status = (parts[0] ?? '').charAt(0);
+        if (parts.length < 2 || !/^[AMDRCTU]$/.test(status)) {
+            throw new Error(`unreadable name-status line: ${JSON.stringify(line)}`);
+        }
+        if ((status === 'R' || status === 'C') && parts.length >= 3) {
+            out.push({ status, oldPath: parts[1] ?? '', path: parts[2] ?? '' });
+        } else {
+            out.push({ status, path: parts[1] ?? '' });
+        }
+    }
+    return out;
+}
+
+function git(root: string, args: string[]): { ok: boolean; out: string } {
+    const r = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+    return { ok: r.status === 0, out: r.stdout ?? '' };
+}
+
+interface Resolved {
+    base: string;
+    head: string;
+}
+
+function resolvePr(root: string, pr: string): Resolved | null {
+    const v = spawnSync('gh', ['pr', 'view', pr, '--json', 'baseRefName,headRefOid'], { cwd: root, encoding: 'utf8' });
+    if (v.status !== 0) {
+        return null;
+    }
+    const meta = JSON.parse(v.stdout) as { baseRefName?: string; headRefOid?: string };
+    if (meta.baseRefName === undefined || meta.headRefOid === undefined) {
+        return null;
+    }
+    git(root, ['fetch', '-q', 'origin', meta.baseRefName, `pull/${pr}/head`]);
+    return { base: `origin/${meta.baseRefName}`, head: meta.headRefOid };
+}
+
+function resolveRange(range: string): Resolved | null {
+    const m = /^(.+?)\.\.\.?(.+)$/.exec(range);
+    return m === null ? null : { base: m[1] ?? '', head: m[2] ?? '' };
+}
+
+function failClosed(reason: string): Classification {
+    return { verdict: 'needs-council', triggers: [{ id: 'diff-unreadable', rule: 'fail closed — ADR-282', paths: [reason] }] };
+}
+
+export function classifyTarget(root: string, target: { pr?: string | undefined; range?: string | undefined }): Classification {
+    const resolved = target.pr !== undefined ? resolvePr(root, target.pr) : resolveRange(target.range ?? '');
+    if (resolved === null) {
+        return failClosed('could not resolve base and head');
+    }
+    const diff = git(root, ['diff', '--name-status', '-M', `${resolved.base}...${resolved.head}`]);
+    if (!diff.ok) {
+        return failClosed(`git diff ${resolved.base}...${resolved.head} failed`);
+    }
+    let entries: ChangeEntry[];
+    try {
+        entries = parseNameStatus(diff.out);
+    } catch (e) {
+        return failClosed((e as Error).message);
+    }
+    return classifyChanges(entries, {
+        dirExistsInHead: (dir) => git(root, ['cat-file', '-e', `${resolved.head}:${dir}`]).ok,
+    });
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2), write: (l: string) => void = (l) => process.stdout.write(`${l}\n`)): number {
+    let root = process.cwd();
+    let range: string | undefined;
+    let pr: string | undefined;
+    let json = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? '';
+        if (a === '--root') {
+            root = argv[++i] ?? root;
+        } else if (a === '--range') {
+            range = argv[++i];
+        } else if (a === '--json') {
+            json = true;
+        } else if (/^\d+$/.test(a)) {
+            pr = a;
+        }
+    }
+    const result =
+        pr === undefined && range === undefined ? failClosed('no PR number and no --range given') : classifyTarget(root, { pr, range });
+    if (json) {
+        write(JSON.stringify(result));
+    } else {
+        for (const t of result.triggers) {
+            write(`trigger ${t.id} — ${t.rule}`);
+            for (const p of t.paths) {
+                write(`  ${p}`);
+            }
+        }
+        write(
+            result.verdict === 'routine'
+                ? 'verdict: routine'
+                : `verdict: needs-council (${result.triggers.length} trigger(s): ${result.triggers.map((t) => t.id).join(', ')})`,
+        );
+    }
+    return result.verdict === 'routine' ? 0 : 1;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+    process.exit(main());
+}

package/src/scripts/closure_scan.ts

@@ -130,7 +130,12 @@ export const NON_BLOCKING_KINDS: ReadonlySet<Kind> = new Set<Kind>(['unfalsifiab
  * 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.
+ * line in the tree, which is step 2.2's instrument, not this one. One case
+ * reads titles and runs nothing: a name-filtered test run
+ * (`vitest run <target> -t <name>`) whose target exists carries its own
+ * failure mode a plain exit-code read cannot see — `-t` with no matching
+ * title skips every test and still exits 0 — so that one shape is read for
+ * content, never executed, in `_nameFilterHasNoMatch` below.
  */
 const FIXED_OUTPUT_HEADS: ReadonlySet<string> = new Set(['echo', 'true', 'printf', 'cat', 'ls', 'pwd', 'date']);
 
@@ -149,6 +154,87 @@ const FIXED_OUTPUT_HEADS: ReadonlySet<string> = new Set(['echo', 'true', 'printf
  * remainder as clean, which is the same mistake as reporting a share off a
  * corpus nobody scanned.
  */
+// `vitest run <target> -t <name>` (optionally `npx`-prefixed); `<name>` may
+// be bare, single-quoted or double-quoted. The target is captured
+// non-greedily up to the first whitespace or quote.
+const VITEST_NAME_FILTER_RE = /(?:^|\s)vitest\s+run\s+(\S+)\s+-t\s+(?:'([^']+)'|"([^"]+)"|(\S+))/;
+
+// `describe(`, `it(`, `test(`, and their `.only`/`.skip`/`.each`/`.todo`
+// modifiers, each with a quoted first argument — the title vitest matches
+// `-t` against (concatenated with its ancestor `describe` titles at
+// run time; this reads each title string standalone, which is sufficient to
+// prove a filter CAN match something — the question this function asks).
+const TEST_TITLE_RE = /\b(?:describe|it|test)(?:\.\w+)?\s*\(\s*(['"`])((?:(?!\1).)*)\1/g;
+
+function _collectTestFiles(target: string): string[] {
+    let stat: fs.Stats;
+    try {
+        stat = fs.statSync(target);
+    } catch {
+        return [];
+    }
+    if (stat.isFile()) return [target];
+    if (!stat.isDirectory()) return [];
+    const out: string[] = [];
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(target, { recursive: true }) as string[];
+    } catch {
+        return [];
+    }
+    for (const rel of entries) {
+        if (!/\.(?:test|spec)\.tsx?$/.test(rel)) continue;
+        out.push(path.join(target, rel));
+    }
+    return out;
+}
+
+function _extractTitles(file: string): string[] {
+    let text: string;
+    try {
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return [];
+    }
+    const titles: string[] = [];
+    const re = new RegExp(TEST_TITLE_RE.source, TEST_TITLE_RE.flags);
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(text)) !== null) {
+        titles.push(m[2] ?? '');
+    }
+    return titles;
+}
+
+/**
+ * A name-filtered vitest run whose target exists but carries no test title
+ * containing the filter — the oracle exits 0 on every test skipped, which a
+ * plain exit-code read cannot distinguish from every test passing.
+ *
+ * `null` whenever the shape does not match, the target cannot be resolved
+ * (nothing to read), or no title could be extracted at all (a parse miss,
+ * not evidence of absence) — in every one of those the finding would be a
+ * guess, and this function only reports what it read.
+ */
+function _nameFilterHasNoMatch(command: string): string | null {
+    const m = VITEST_NAME_FILTER_RE.exec(command);
+    if (m === null) return null;
+    const targetRaw = m[1] as string;
+    const name = (m[2] ?? m[3] ?? m[4] ?? '').trim();
+    if (name === '') return null;
+    const target = path.resolve(process.cwd(), targetRaw);
+    const files = _collectTestFiles(target);
+    if (files.length === 0) return null;
+    let sawAnyTitle = false;
+    for (const file of files) {
+        for (const title of _extractTitles(file)) {
+            sawAnyTitle = true;
+            if (title.includes(name)) return null;
+        }
+    }
+    if (!sawAnyTitle) return null;
+    return `\`-t ${name}\` matches no test title under ${targetRaw}: the run exits 0 with every test skipped`;
+}
+
 export function unfalsifiableReason(clause: VerifyClause): string | null {
     if (clause.command === null) {
         // A MANUAL clause asserting a QUANTITY nothing produced. Narrowed to a
@@ -176,6 +262,10 @@ export function unfalsifiableReason(clause: VerifyClause): string | null {
             // An expectation that cannot compile never became one upstream.
         }
     }
+
+    const nameFilterReason = _nameFilterHasNoMatch(clause.command);
+    if (nameFilterReason !== null) return nameFilterReason;
+
     return null;
 }
 

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';
 }