@event4u/agent-config 14.22.0 → 14.23.0

package/src/scripts/_lib/lean_projection_mode.ts

@@ -42,3 +42,130 @@ export function writesThinFiles(mode: LeanProjectionMode): boolean {
 export function deliversBodies(mode: LeanProjectionMode): boolean {
     return mode === 'delivery';
 }
+
+/**
+ * The hosts a thinning mode may actually thin.
+ *
+ * Deliberately NOT "every host id the package knows". `condense`'s `TOOL_DIRS`
+ * writes a per-rule tree for exactly three hosts, so those are the only ids for
+ * which `lean_projection.hosts` can mean anything: naming `windsurf` there would
+ * be a request to thin a single concatenated file that has no per-rule stub
+ * shape, and naming `codex` a request to thin a tree the installer writes and
+ * `condense` never touches. Accepting such an id silently would leave the
+ * operator believing a host was scoped when nothing reads the entry.
+ */
+export const THINNABLE_HOSTS: readonly string[] = ['claude-code', 'cursor', 'cline'];
+
+/**
+ * The shipped default host set for a thinning mode.
+ *
+ * One host, and it is the one host that both binds `pre_tool_use` and honours a
+ * deny (`docs/enforcement-by-host.md:18-28`) — i.e. the only host where the
+ * delivery concern's verdict is acted on. Widening this is a decision, never a
+ * default: see `resolveLeanProjectionHosts`, which never widens implicitly.
+ */
+export const DEFAULT_LEAN_PROJECTION_HOSTS: readonly string[] = ['claude-code'];
+
+/** Why an id in a configured `hosts:` list was not kept. */
+export type DroppedHostReason = 'unknown' | 'not-thinnable';
+
+export interface LeanProjectionHosts {
+    /** The ids that survived, sorted and de-duplicated. */
+    readonly hosts: readonly string[];
+    /** Ids that were dropped, with the reason — reported, never silently discarded. */
+    readonly dropped: ReadonlyArray<{ readonly id: string; readonly reason: DroppedHostReason }>;
+    /** True when nothing was configured and the default was applied. */
+    readonly usedDefault: boolean;
+}
+
+/**
+ * Resolve a configured `lean_projection.hosts` list.
+ *
+ * Three properties, each of which is a failure this repository has seen in a
+ * neighbouring config surface:
+ *
+ * 1. **Absent means the default, never "all".** An empty or missing list
+ *    resolves to `DEFAULT_LEAN_PROJECTION_HOSTS`. A key nobody set must not
+ *    thin every host — that is D1, the defect this axis exists to repair.
+ * 2. **The set never widens implicitly.** Every id is checked against
+ *    `THINNABLE_HOSTS`; anything else is dropped. A typo cannot enrol a host,
+ *    and neither can a real host id that has no per-rule tree.
+ * 3. **A drop is reported, not swallowed.** The caller gets the ids and the
+ *    reason so it can print them. Silently ignoring an entry an operator wrote
+ *    is how a setting comes to mean nothing while looking configured.
+ *
+ * A configured list that resolves to NOTHING keeps `usedDefault: false` and an
+ * empty `hosts` — that is "thin no host", which is a legitimate and safe answer
+ * and must not fall back to the default. Falling back there would turn a
+ * fully-typo'd list into a Claude Code flip the operator never asked for.
+ *
+ * WHICH FILES REACH THIS AT ALL, stated because R2 finding 6 read the drop path
+ * as unreachable: `agent-settings.schema.json` and the wizard's Zod schema both
+ * constrain the items to an `enum`, so an out-of-vocabulary id written through
+ * either surface is a hard validation FAILURE and never arrives here. What
+ * arrives here is a HAND-EDITED `.agent-settings.yml` — the file
+ * `condense._lean_projection_settings` and `hooks/rule_inject_hook.gateOpen`
+ * both read directly, with no validation step in between. The two layers are
+ * defence in depth, not one contract stated twice: the schema is the authoring
+ * gate, this function is the read-time gate, and the drop wording below exists
+ * for the file the schema never saw.
+ */
+export function resolveLeanProjectionHosts(raw: unknown): LeanProjectionHosts {
+    const known = new Set(THINNABLE_HOSTS);
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return { hosts: [...DEFAULT_LEAN_PROJECTION_HOSTS], dropped: [], usedDefault: true };
+    }
+    const hosts: string[] = [];
+    const dropped: Array<{ id: string; reason: DroppedHostReason }> = [];
+    for (const entry of raw) {
+        const id = typeof entry === 'string' ? entry.trim().toLowerCase() : '';
+        if (id === '') {
+            dropped.push({ id: String(entry), reason: 'unknown' });
+            continue;
+        }
+        if (!known.has(id)) {
+            // `not-thinnable` is reserved for an id this package genuinely knows
+            // as a host but which owns no per-rule tree. Everything else is a
+            // typo or an invention, and the two deserve different wording
+            // because the operator's next action differs: fix the spelling, or
+            // learn that the host cannot be thinned at all.
+            dropped.push({ id, reason: KNOWN_NON_THINNABLE_HOSTS.has(id) ? 'not-thinnable' : 'unknown' });
+            continue;
+        }
+        if (!hosts.includes(id)) hosts.push(id);
+    }
+    hosts.sort();
+    return { hosts, dropped, usedDefault: false };
+}
+
+/**
+ * Host ids the package ships surfaces for that own no per-rule rule tree.
+ *
+ * Only used to word a drop precisely; it grants nothing. Sourced from
+ * `condense._ALL_TOOLS` plus the two hosts outside it that the host table
+ * carries (`codex`, `cowork`).
+ */
+const KNOWN_NON_THINNABLE_HOSTS: ReadonlySet<string> = new Set([
+    'claude-desktop', 'augment', 'copilot', 'windsurf', 'gemini', 'codex', 'cowork',
+]);
+
+/** One line per dropped id, for a caller that prints warnings. Empty when nothing was dropped. */
+export function describeDroppedHosts(res: LeanProjectionHosts): string[] {
+    return res.dropped.map(({ id, reason }) =>
+        reason === 'not-thinnable'
+            ? `lean_projection.hosts: "${id}" is a known host but has no per-rule rule tree — dropped`
+            : `lean_projection.hosts: "${id}" is not a thinnable host id — dropped`,
+    );
+}
+
+/**
+ * Does the projector write stubs for this host, under this mode and host set?
+ *
+ * The single predicate `condense` calls. Mode is checked FIRST and on purpose:
+ * with `mode` unset the answer is `false` for every host regardless of what
+ * `hosts` says, so a `hosts:` list left behind after a rollback to `eager-all`
+ * thins nothing.
+ */
+export function thinsHost(mode: LeanProjectionMode, hosts: readonly string[], hostId: string): boolean {
+    return writesThinFiles(mode) && hosts.includes(hostId);
+}

package/src/scripts/_lib/packed_binary_predicate.ts

@@ -61,6 +61,43 @@
  * that passed every condition above — never `observed` minus something excused.
  * A file that fails one condition lowers `allowed`; it never disappears from
  * `observed`.
+ *
+ * THE THREAT BOUNDARY — WHO THIS REFUSES, AND WHO IT DOES NOT.
+ *
+ * Written down because the eleven conditions read as a security control and are
+ * only half of one, and a reader could not previously tell that boundary from
+ * an oversight. The `release/14.22.0` self-review finding `d1696732ac28` is
+ * exactly that misreading: it reached for a signature this repository has no
+ * infrastructure to provide (`grep -rniE 'cosign|sigstore|minisign|slsa'`
+ * returns nothing in this tree), because nothing here said where the line was.
+ *
+ * REFUSED. A byte that drifts from what the manifest says — a corrupted copy, a
+ * truncated checkout, a refresh that updated the file and forgot the row, a
+ * grammar whose ABI moved under a version bump, a second row quietly widening a
+ * path. Each of those is one side of the pair changing while the other does
+ * not, and every condition above is a re-derivation from the bytes rather than
+ * a restatement of the row.
+ *
+ * NOT REFUSED, DELIBERATELY. An attacker who edits the manifest and the bytes in
+ * the SAME COMMIT. Every condition here reads the manifest, so a same-commit
+ * pair is internally consistent and passes all eleven. That case is out of
+ * scope for this module and is held by review instead: the manifest is a small
+ * JSON file whose diff a human reads, and a hash changing next to a binary
+ * changing is the most visible shape a diff has.
+ *
+ * WHAT CLOSES IT, AND WHERE. `_lib/vendored_grammar_upstream.ts` compares the
+ * vendored bytes against the `tree-sitter-wasms` release pinned in
+ * `package-lock.json` and installed by `npm ci` — a source outside this
+ * repository's own diff — and refuses rather than passes when that comparison
+ * cannot be made. It is exercised by `tests/scripts/vendored_grammar_upstream.test.ts`,
+ * which is where a reader auditing "what enforces these bytes" should go next.
+ * Its own docblock states what it may not claim: it is not independent of all
+ * repository state, and it does not verify the grammars against the registry
+ * independent of local build state.
+ *
+ * STILL OPEN, AND OWNED BY REVIEW. A `package-lock.json` row that points at a
+ * hostile package. No check in this tree defends that; the lock is
+ * human-readable text declaring dependencies, and reviewing it is the control.
  */
 import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';

package/src/scripts/_lib/recycle_envelope_paths.ts

@@ -73,11 +73,49 @@ export function recycle_envelope_rel(session_id: string | null | undefined): str
     return _sessionKeyed(session_id, RECYCLE_ENVELOPE_REL, 'recycle-envelope', '.json');
 }
 
+/**
+ * THE KEYING CONTRACT, in one place because its absence is what allowed the
+ * 2026-09-09 defect: the record is keyed by the **producing session** — the one
+ * that ran `session:recycle` — and it is READ by the **consuming session**,
+ * which is a different session with a different id. Those two facts were each
+ * true in their own module and were never written down together, so the
+ * producer and the consumer agreed on a PATH and disagreed about whose id
+ * filled it. {@link resolveContinuityRecord} is where that is now reconciled:
+ * it admits the unique record that is NOT the reader's own.
+ */
+
 /** Consumed sibling of {@link recycle_envelope_rel}, same keying. */
 export function recycle_consumed_rel(session_id: string | null | undefined): string {
     return _sessionKeyed(session_id, RECYCLE_CONSUMED_REL, 'recycle-envelope', '.consumed.json');
 }
 
+/**
+ * Where an UNUSABLE resident record is moved aside so the slot can be
+ * published into — never deleted.
+ *
+ * `road-to-continuity-writer-activation` step 1.1. The reader already discards
+ * a malformed, schema-invalid or expired record loudly
+ * ({@link resolveContinuityRecord}'s callers), so nothing is lost by taking it
+ * out of the authoritative name. What WOULD be lost by `unlink` is the evidence
+ * of why a resume did not happen, and that is the only artefact anyone
+ * debugging a missed resume has. Quarantine is one file per session and is
+ * pruned by the same janitor as the rest of `agents/runtime/state/`.
+ *
+ * Deliberately NOT the consumed name: `.consumed.json` is a claim that a
+ * successor read the record, and `predecessorTracePresent` reads exactly that
+ * file to corroborate a lineage. Writing a never-consumed record there would
+ * manufacture a predecessor trace, which is the one thing that check exists to
+ * refuse.
+ */
+export function recycle_quarantine_rel(session_id: string | null | undefined): string {
+    return _sessionKeyed(
+        session_id,
+        path.join(_STATE_REL, 'recycle-envelope.quarantined.json'),
+        'recycle-envelope',
+        '.quarantined.json',
+    );
+}
+
 /**
  * Shared builder. Containment is asserted locally rather than trusted from
  * `safe_stem`: a guarantee living in another module's implementation is one
@@ -133,44 +171,94 @@ export interface ContinuityResolution {
 /**
  * Which record THIS session may read.
  *
- * Three cases, and the third is the one the per-session key exists for:
+ * **A resume reads the PREDECESSOR's record, and this function used to look for
+ * the reader's own.** Corrected 2026-09-09 after measuring it: the producer
+ * writes under the PRODUCING session's id and the consumer arrives with its
+ * OWN, so the two never coincided and every successor was told `absent`. The
+ * mechanism resolved only for a caller with no session id at all — the one
+ * shape no host produces, and the only shape the 19 pre-existing consumer tests
+ * exercised. `road-to-a-recycle-envelope-that-is-consumed` carries the
+ * five-fixture table; AI council 2026-09-09, 2/2, chose the rule below.
+ *
+ * Four cases, and the second is the resume:
+ *
+ * 1. **Own record.** NEVER read. A session re-reading its own state is a loop,
+ *    not a resume, and a second `session_start` for one session (resume, host
+ *    reconnect) made it reachable. Excluded by construction here rather than
+ *    guarded downstream.
+ * 2. **Exactly one record that is not the reader's own.** Read it. That is the
+ *    predecessor.
+ * 3. **Several such records.** START CLEAN and say so — the existing refusal,
+ *    unchanged and now reachable from both branches. Picking the newest is
+ *    precisely the recency resolution the no-index rule below forbids.
+ * 4. **None.** `absent`.
  *
- * 1. **Own id resolves.** Read the record keyed to it, and nothing else. A peer
- *    session's record is not a candidate at any point, so "neither observes the
- *    other's" holds by construction rather than by a comparison that could be
- *    skipped.
- * 2. **No id, one candidate.** Read it. A single record in a checkout with no
- *    resolvable identity is the pre-key situation and is unchanged.
- * 3. **No id, several candidates.** START CLEAN and say so. Picking the newest
- *    is precisely the recency resolution the no-index rule forbids: it would
- *    hand this session a stranger's state and look like a successful resume.
+ * **Why this is not recency, stated because the rule it must not become is one
+ * line away:** nothing is sorted and nothing is compared by time. Uniqueness
+ * admits; ambiguity refuses. The peer-isolation intent the per-session key was
+ * introduced for therefore moves from the KEY to the REFUSAL — a live peer's
+ * record is no longer excluded by its filename, so the branch gate in
+ * `consume_recycle_envelope` is what keeps an unrelated session from resuming
+ * it. That gate is part of this rule, not a decoration on it.
  */
 export function resolveContinuityRecord(
     workspace_root: string,
     session_id: string | null | undefined,
 ): ContinuityResolution {
     const id = String(session_id ?? '').trim();
-    if (id !== '') {
-        const own = path.join(workspace_root, recycle_envelope_rel(id));
-        return fs.existsSync(own)
-            ? { file: own, reason: `continuity record for this session (${safe_stem(id)})` }
-            : { file: null, reason: `no continuity record for this session (${safe_stem(id)})` };
-    }
-    const candidates = listContinuityRecords(workspace_root);
+    const own = id === '' ? null : path.join(workspace_root, recycle_envelope_rel(id));
+    const candidates = listContinuityRecords(workspace_root).filter((f) => f !== own);
     if (candidates.length === 0) {
-        return { file: null, reason: 'no continuity record present' };
+        return {
+            file: null,
+            reason:
+                id === ''
+                    ? 'no continuity record present'
+                    : `no predecessor record in this workspace (own: ${safe_stem(id)})`,
+        };
     }
     if (candidates.length === 1) {
-        return { file: candidates[0] as string, reason: 'one continuity record, no session id to key on' };
+        return {
+            file: candidates[0] as string,
+            reason:
+                id === ''
+                    ? 'one continuity record, no session id to key on'
+                    : `predecessor record, one candidate (own: ${safe_stem(id)})`,
+        };
     }
     return {
         file: null,
         reason:
-            `starting clean: ${candidates.length} continuity records in this workspace and no session id ` +
-            'to tell them apart — resuming from the newest would resume a peer session, not this one',
+            `starting clean: ${candidates.length} continuity records in this workspace and no way to tell ` +
+            'which is the predecessor — resuming from the newest would resume a peer session, not this one',
     };
 }
 
+/**
+ * Which session this one continues — read, never composed.
+ *
+ * The chain is derivable without any new artifact: when this session started,
+ * its reader consumed the predecessor's record and MOVED it to this session's
+ * consumed path (`recycle_consumed_rel`). So the file sitting there is, by
+ * construction, the record this session resumed from, and its `session_id` is
+ * the predecessor.
+ *
+ * Returns the explicit string `none` when there is nothing there. `none` is a
+ * CLAIM — "this session starts a chain" — and is deliberately not an empty
+ * value: a reader must be able to tell "no predecessor" from "nobody wrote the
+ * field", because only the second one is a reason to go looking.
+ */
+export function resolvePredecessor(projectRoot: string, sessionId: string | null): string {
+    try {
+        const consumed = path.join(projectRoot, recycle_consumed_rel(sessionId));
+        const raw = JSON.parse(fs.readFileSync(consumed, 'utf-8')) as { session_id?: unknown };
+        const prior = String(raw.session_id ?? '').trim();
+        return prior === '' ? 'none' : prior;
+    } catch {
+        return 'none';
+    }
+}
+
 /**
  * Is there any trace in this workspace of the session a record names as its
  * predecessor?

package/src/scripts/_lib/regression_neighbourhood.ts

@@ -12,30 +12,33 @@
  * > neighbourhood names, and a fixture proves a neighbour regression is
  * > caught.**
  *
- * ## Which graph, and why it is not the one the step names
+ * TWO GRAPHS, BOTH DELIBERATE — the substitution is retired.
  *
- * The step says "the code graph". This tree has two graph surfaces and only one
- * of them resolves here, so the substitution is STATED rather than hidden.
+ * The step says "the code graph". Until 2026-09-08 this module could not read
+ * it: `agent-config code-graph detect` answered `no code-graph source detected`
+ * in a fresh checkout, so it selected over the artefact graph instead and said
+ * so. `road-to-a-graph-that-is-shipped` removed that premise — Phase 0.1 ships
+ * the parsers, Phase 1 builds the graph on install, and 3.1 added
+ * `impact --diff`, which is the reverse-reachability query this selector needs.
  *
- *   · `agent-config code-graph` — the native code-graph engine (ADR-124). It
- *     shipped `hooks.code_graph.enabled: false` (a flag retired 2026-09-07)
- *     (`src/config/agent-settings.template.yml:1373-1374`), and
- *     `agent-config code-graph detect` in this checkout answers
- *     `no code-graph source detected`. There is no index to select against.
- *   · `src/scripts/discovery_graph.ts` — this suite's OWN artefact relation
- *     graph, five typed edges extracted from the discovery manifest's
- *     structured fields, with an `affected` BFS already implemented and
- *     answering. That is the surface this module builds on.
+ * So both surfaces are now first-class, and which one a candidate uses is a
+ * property OF THE CANDIDATE rather than of what happened to resolve:
  *
- * The substitution changes what a "neighbourhood" means, and the difference is
- * worth naming: the native engine would neighbour a candidate by SYMBOL
- * relations, while `discovery_graph` neighbours it by ARTEFACT relations
- * (`supersedes`, `routes_to`, `references_adr`, pack and workspace membership).
- * For this roadmap's candidates — rules, skills, guidelines — the artefact
- * graph is the one that carries the coupling a rewrite can break. For a
- * candidate that edits a `.ts` symbol, it is the weaker surface, and this
- * module says so through {@link selectionVerdict}: a touched surface absent
- * from the graph is REFUSED, never silently neighboured with the empty set.
+ *   · **Code candidates** — a diff that edits `.ts` / `.php` symbols. Use
+ *     {@link selectRegressionsFromCode}, which neighbours by SYMBOL relations
+ *     over the native graph, filtered to accepted mechanisms
+ *     (`resolved_via` not in `{name-lookup, dynamic}`) so a same-name guess
+ *     never selects a regression.
+ *   · **Artefact candidates** — a diff that edits rules, skills, guidelines.
+ *     Use {@link selectRegressions}, which neighbours by ARTEFACT relations
+ *     over `src/scripts/discovery_graph.ts` (`supersedes`, `routes_to`,
+ *     `references_adr`, pack and workspace membership). For a rule rewrite that
+ *     is the graph carrying the coupling a change can break; the code graph
+ *     does not model it at all.
+ *
+ * Neither is a fallback for the other, and neither is silent: both paths REFUSE
+ * through {@link selectionVerdict} when a touched surface is absent from the
+ * graph they read, because an unknown neighbourhood is not an empty one.
  *
  * ## Why an unresolved surface refuses instead of selecting nothing
  *
@@ -55,6 +58,9 @@
  * A test asserts that identity rather than an id match, because an id match
  * would also be satisfied by a synthesized spec carrying a copied id.
  */
+import type { GraphState } from '../code_graph/detect.js';
+import type { LoadedGraph } from '../code_graph/query.js';
+import { impact } from '../code_graph/verbs.js';
 import { affected, isSyntheticNode, type Graph } from '../discovery_graph.js';
 
 /**
@@ -106,6 +112,48 @@ export interface NeighbourhoodReport {
     selected: readonly Selection[];
     /** Registry entries whose guards intersect nothing in the neighbourhood. */
     skipped: readonly string[];
+    /**
+     * Which graph answered. Present so a verdict record can never be read as a
+     * claim about the other surface — the failure the retired substitution
+     * section describes, arriving through the report instead of through the
+     * docstring.
+     */
+    graph: 'artefact' | 'code';
+    /**
+     * The graph's freshness at selection time: `fresh` / `behind:N` / `absent`
+     * on the code path, `null` on the artefact path (which is derived from the
+     * committed manifest and has no staleness axis).
+     *
+     * Added after an independent review found the code path hardcoding
+     * `'absent'` and dropping the value: the verbs are required to report
+     * staleness, `verbs.ts` argues the whole point is telling "dead" from "dead
+     * as of a graph 40 commits behind" — and the one in-repo CONSUMER of those
+     * verbs discarded it, so no selection could refuse on a stale graph.
+     */
+    graph_state: GraphState | null;
+    /**
+     * Touched files in a language the code graph does not index. NOT a refusal
+     * reason: an unindexed `.md` is a file with no symbols, which is a fact
+     * about the language set rather than an unknown neighbourhood.
+     */
+    not_indexed: readonly string[];
+    /**
+     * The edges that produced the neighbourhood, rendered, sorted.
+     *
+     * Required by step 3.4: *"the selected regressions and the producing edges
+     * enter the verdict record"*. Empty on the artefact path, whose `affected`
+     * BFS returns a relation name per hop rather than an edge — stated rather
+     * than faked, because an empty list a reader can attribute is better than a
+     * synthesised one they cannot.
+     */
+    producing_edges: readonly string[];
+    /**
+     * The `resolved_via` histogram of the edges the walk REFUSED, on the code
+     * path. A selection that looks narrow because half the graph was a guess
+     * reads very differently from one that looks narrow because the code is
+     * decoupled, and this is the only field that distinguishes them.
+     */
+    rejected_via: string;
     /**
      * Literal 0. This module selects from a registry; a non-zero value here
      * would mean it authored a task, which is K9.
@@ -196,6 +244,80 @@ export function selectRegressions(
         unresolved: unresolvedSurfaces(graph, candidate),
         selected: selected.sort((a, b) => a.spec.id.localeCompare(b.spec.id)),
         skipped: skipped.sort((a, b) => a.localeCompare(b)),
+        graph: 'artefact',
+        graph_state: null,
+        not_indexed: [],
+        producing_edges: [],
+        rejected_via: '(not applicable — the artefact graph has no mechanism axis)',
+        authored: 0,
+    };
+}
+
+/**
+ * The code-graph path (step 3.4).
+ *
+ * Neighbours a candidate by the symbols its diff touched, over the native code
+ * graph, using the same `impact --diff` reverse walk the CLI verb exposes. The
+ * neighbourhood's nodes are the seeds at depth 0 (`touched`) plus every
+ * accepted reverse-reachable node at its shallowest depth (`neighbour`), which
+ * is the identical shape {@link neighbourhood} produces for the artefact graph
+ * — so `selectRegressions`' matching logic is reused rather than forked.
+ *
+ * `touches` is read as FILE paths here, not artefact ids: a code candidate is a
+ * diff, and a diff names files. A touched file with no node in the graph lands
+ * in `unresolved` and therefore refuses through {@link selectionVerdict}, on
+ * exactly the terms the artefact path already uses.
+ */
+export function selectRegressionsFromCode(
+    g: LoadedGraph,
+    candidate: Candidate,
+    registry: readonly RegressionSpec[],
+    depth: number = DEFAULT_NEIGHBOURHOOD_DEPTH,
+    isTest: (relPath: string) => boolean = () => false,
+    graphState: GraphState = 'absent',
+): NeighbourhoodReport {
+    const res = impact(g, candidate.touches, graphState, depth, isTest);
+    const best = new Map<string, NeighbourhoodNode>();
+    for (const seed of res.seeds) {
+        best.set(seed, { node: seed, reason: 'touched', depth: 0, via: '', synthetic: false });
+    }
+    for (const r of res.reached) {
+        if (best.has(r.node)) continue;
+        best.set(r.node, {
+            node: r.node,
+            reason: 'neighbour',
+            depth: r.depth,
+            via: `${r.via}/${r.resolved_via}`,
+            synthetic: false,
+        });
+    }
+    const hood = [...best.values()].sort((a, b) => a.depth - b.depth || a.node.localeCompare(b.node));
+    const reasonOf = new Map<string, NeighbourReason>(hood.map((n) => [n.node, n.reason]));
+    const selected: Selection[] = [];
+    const skipped: string[] = [];
+    for (const spec of registry) {
+        const matched = spec.guards.filter((x) => reasonOf.has(x)).sort((a, b) => a.localeCompare(b));
+        if (matched.length === 0) {
+            skipped.push(spec.id);
+            continue;
+        }
+        selected.push({
+            spec,
+            matched,
+            reason: matched.some((m) => reasonOf.get(m) === 'touched') ? 'touched' : 'neighbour',
+        });
+    }
+    return {
+        candidate_id: candidate.id,
+        neighbourhood: hood,
+        unresolved: [...res.unresolved_files].sort((a, b) => a.localeCompare(b)),
+        selected: selected.sort((a, b) => a.spec.id.localeCompare(b.spec.id)),
+        skipped: skipped.sort((a, b) => a.localeCompare(b)),
+        graph: 'code',
+        graph_state: graphState,
+        not_indexed: [...res.not_indexed_files].sort((a, b) => a.localeCompare(b)),
+        producing_edges: [...res.producing_edges].sort(),
+        rejected_via: res.rejected_via,
         authored: 0,
     };
 }
@@ -209,9 +331,24 @@ export function selectRegressions(
  */
 export function selectionVerdict(report: NeighbourhoodReport): readonly string[] | null {
     const reasons: string[] = [];
+    // An ABSENT graph is the case the artefact path's own docstring warns
+    // about in the other direction: a lookup that cannot resolve and then
+    // selects nothing reports a clean sheet. `behind:N` is deliberately NOT a
+    // refusal — a stale graph still answers, and blocking on staleness would
+    // be the blocking-gate-on-a-stale-graph that K7 forbids. It is surfaced
+    // through `graph_state` so a caller that wants to refuse can.
+    if (report.graph === 'code' && report.graph_state === 'absent') {
+        reasons.push(
+            'the code graph is absent — a neighbourhood computed over no graph is empty for a ' +
+                'reason that has nothing to do with the candidate. Run `agent-config code-graph build`.',
+        );
+    }
     if (report.unresolved.length > 0) {
+        // Named per graph: a code-path refusal that said "relation graph" would
+        // point a reader at the wrong surface to go fix.
+        const which = report.graph === 'code' ? 'code graph' : 'artefact relation graph';
         reasons.push(
-            `touched surfaces absent from the relation graph: ${report.unresolved.join(', ')} — ` +
+            `touched surfaces absent from the ${which}: ${report.unresolved.join(', ')} — ` +
                 'their neighbourhood is unknown, and an unknown neighbourhood is not an empty one',
         );
     }

package/src/scripts/_lib/session_eol.ts

@@ -269,6 +269,50 @@ export function readEolCounters(
     }
 }
 
+/**
+ * Committed substantive-content floor, in parsed transcript tokens (billable
+ * input of the last main-chain assistant record, per `cc_transcript.ts`) — the
+ * OR-arm for a session that produced real discussion without ever calling a
+ * tool.
+ *
+ * Derivation (`agents/evidence/analysis/handoff-substantive-threshold.md`,  code-comment-allow provenance-comment -- unchanged relocation of a docblock whose whole point is that this threshold may only move on cited evidence
+ * 217 sessions of the local Claude store, 2026-08-10): 206 of the 207 sessions
+ * carrying an assistant record also carry a `tool_use` block, so this arm
+ * serves the ~0.5 % tail and the hosts whose transcripts log no tool blocks at
+ * all. 10 000 sits **25× below** the p10 of real working sessions (254 939),
+ * so it cannot hide one, and above a single trivial exchange. Changing it is a
+ * PR citing evidence, never a drive-by edit.
+ */
+export const SUBSTANTIVE_TOKEN_FLOOR = 10_000;
+
+/**
+ * Does this session hold anything worth resuming?
+ *
+ * `≥ 1 assistant turn AND (≥ 1 tool call OR parsed tokens ≥ the committed
+ * floor)`, read from the counts-only session-eol state.
+ *
+ * **Fail-open, deliberately** (Phase 1.2): absent, unreadable or mis-shaped
+ * state LISTS the candidate rather than filtering it, and a `tool_calls` key
+ * missing from a state file written before that counter existed reads as
+ * *unknown*, never as zero. A wrongly listed candidate is noise the user
+ * scrolls past; a wrongly hidden one is data loss they cannot even see.
+ */
+export function is_substantive(counters: StoredEolCounters | null): boolean {
+    if (counters === null) return true;
+    // Every "unknown" below is a NUMBER test, not an `=== undefined` test.
+    // Absent, null and NaN are all unknown, and each one reaches this code by
+    // a real path: a state file written before the counter existed is absent,
+    // `JSON.stringify` turns NaN into null on the way to disk, and a
+    // half-written file yields a parseable object with missing keys. Reading
+    // any of them as "counted zero" hides a session that did real work.
+    if (!Number.isFinite(counters.assistant_records)) return true;
+    if ((counters.assistant_records as number) < 1) return false;
+    if (!Number.isFinite(counters.tool_calls)) return true;
+    if ((counters.tool_calls as number) >= 1) return true;
+    if (!Number.isFinite(counters.final_context_tokens)) return true;
+    return (counters.final_context_tokens as number) >= SUBSTANTIVE_TOKEN_FLOOR;
+}
+
 export interface NewLinesRead {
     /** The complete lines appended since `fromByte` (possibly empty). */
     text: string;