@event4u/agent-config 14.21.0 → 14.23.0

package/src/scripts/hooks/code_graph_context_hook.ts

@@ -0,0 +1,201 @@
+#!/usr/bin/env tsx
+/**
+ * PreToolUse code-graph context line (road-to-a-graph-that-is-shipped 1.2).
+ *
+ * Replaces `code_graph_nudge_hook.ts`, which shipped default-OFF behind
+ * `hooks.code_graph.enabled` — a flag the settings table itself described as
+ * "deprecated — honest null 2026-07-28", requiring a manual install of the
+ * ABI-locked parser pair. Phase 0.1 made that manual install unnecessary, so
+ * the flag's premise is gone and the flag with it.
+ *
+ * Two behavioural changes, and both are the reason the replacement exists
+ * rather than a rename:
+ *
+ * 1. It speaks ONLY when a graph actually exists — `fresh` or `behind:N`.
+ *    The nudge also fired on ABSENT, i.e. it advertised a capability the
+ *    consumer had not built and, before 0.1, could not build. A hook whose
+ *    common case is "you do not have this" is an advertisement, not context.
+ *    Absent → silent, which is what makes default-on defensible: a consumer
+ *    who never builds a graph never hears from this hook at all.
+ * 2. It carries STATE, not an instruction. `fresh` and `behind:N` are facts
+ *    the model cannot otherwise see, and `behind:N` is the one that changes a
+ *    decision — an answer from a graph N commits stale is worth less than the
+ *    same answer from a fresh one, and only the hook knows N.
+ *
+ * Delivery is the dispatcher's, not this hook's: returning `warn` + a reason
+ * makes `emitFor` lower it to the host's structured envelope — on Claude Code
+ * `hookSpecificOutput.additionalContext` at exit 0 (`claudeAdditionalContext`
+ * in host_semantics.ts). It is never a plain echo. On a host with no verified
+ * PreToolUse contract the dispatcher swallows concern stdout, so the same line
+ * is carried as a rule instead (`external-code-graph-interop`), which is what
+ * "per-host `enforced_by` resolved from the table, not from a host name" means
+ * in practice.
+ *
+ * Once per session (a latch keyed by session id), so it cannot nag.
+ * fail_closed: false — every error path returns allow; a context line must
+ * never break a tool call.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { type GraphState, graphState } from '../code_graph/detect.js';
+import { readHookStdin } from './hook_stdin.js';
+
+const EXIT_ALLOW = 0;
+const EXIT_WARN = 2;
+const CODE_EXT = /\.(php|ts|tsx|mts|cts|js|jsx|mjs|cjs)$/i;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+interface ToolIntent {
+    isSearch: boolean;
+    isCodeRead: boolean;
+}
+
+/**
+ * Best-effort read of the intercepted tool + its target from the envelope.
+ *
+ * Carried over from the nudge unchanged, and the manifest's `tools:` filter is
+ * pinned against exactly this branch surface — Grep, Glob, Read.
+ */
+export function classifyTool(envelope: JsonObject): ToolIntent {
+    const payload = isObject(envelope['payload']) ? envelope['payload'] : envelope;
+    const nameVal =
+        payload['tool_name'] ?? payload['toolName'] ?? payload['tool'] ?? envelope['tool_name'] ?? envelope['tool'];
+    const name = typeof nameVal === 'string' ? nameVal : '';
+    const ti = (isObject(payload['tool_input']) ? payload['tool_input'] : envelope['tool_input']) as
+        | JsonObject
+        | undefined;
+    const isSearch = name === 'Grep' || name === 'Glob';
+    let isCodeRead = false;
+    if (name === 'Read' && isObject(ti)) {
+        const fp = ti['file_path'] ?? ti['path'];
+        if (typeof fp === 'string') isCodeRead = CODE_EXT.test(fp);
+    }
+    return { isSearch, isCodeRead };
+}
+
+function sessionId(envelope: JsonObject): string {
+    const s = envelope['session_id'] ?? envelope['sessionId'];
+    return typeof s === 'string' && s ? s : 'default';
+}
+
+function latchFile(root: string): string {
+    return path.join(root, 'agents', 'runtime', 'state', 'code-graph-context.json');
+}
+function alreadySpoke(root: string, session: string): boolean {
+    try {
+        const state = JSON.parse(fs.readFileSync(latchFile(root), 'utf-8')) as Record<string, boolean>;
+        return state[session] === true;
+    } catch {
+        return false;
+    }
+}
+function latch(root: string, session: string): void {
+    try {
+        const p = latchFile(root);
+        let state: Record<string, boolean> = {};
+        try {
+            state = JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, boolean>;
+        } catch {
+            /* fresh */
+        }
+        state[session] = true;
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify(state));
+    } catch {
+        /* fail-open: a persistence failure must not break the tool call */
+    }
+}
+
+/**
+ * The three-state staleness token this hook reports.
+ *
+ * Re-exported, not defined here: Phase 3's verbs must print the same token, and
+ * an engine module importing this hook to learn it would invert the dependency
+ * direction D9 measures. The definition lives in `code_graph/detect.ts`; this
+ * re-export keeps every existing importer of the hook working unchanged.
+ */
+export { type GraphState, graphState };
+
+/**
+ * The one line, ≤ ~45 tokens.
+ *
+ * It names the state and the verbs, and — on the stale branch — what the state
+ * costs. It does NOT claim the graph beats grep: that ordering question is
+ * `later/road-to-a-graph-that-wins.md`'s, and Kill register K5 forbids
+ * "graph-first" wording here.
+ */
+export function contextLine(state: GraphState): string {
+    if (state === 'fresh') {
+        return (
+            'code-graph: fresh. For structure questions (who calls / where used / impact) ' +
+            '`agent-config code-graph query|affected <symbol>` answers from the index; ' +
+            'grep is the other path — say which one answered.'
+        );
+    }
+    const n = state.slice('behind:'.length);
+    return (
+        `code-graph: ${n} commit(s) behind. Relationship answers may miss anything newer — ` +
+        '`agent-config code-graph refresh` rebuilds it, or use grep and say so.'
+    );
+}
+
+export function main(): number {
+    let envelope: JsonValue;
+    try {
+        const raw = readHookStdin();
+        envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+    } catch {
+        return EXIT_ALLOW;
+    }
+    if (!isObject(envelope)) return EXIT_ALLOW;
+
+    const cwd = envelope['cwd'];
+    const pr = envelope['workspace_root'] ?? envelope['project_root'];
+    const root = typeof cwd === 'string' && cwd ? cwd : typeof pr === 'string' && pr ? pr : '.';
+
+    const { isSearch, isCodeRead } = classifyTool(envelope);
+    if (!isSearch && !isCodeRead) return EXIT_ALLOW;
+
+    const session = sessionId(envelope);
+    if (alreadySpoke(root, session)) return EXIT_ALLOW; // once per session
+
+    let state: GraphState;
+    try {
+        state = graphState(root);
+    } catch {
+        return EXIT_ALLOW;
+    }
+    // No graph is the silent case — see the header. Nothing is latched either,
+    // so a session that builds a graph mid-flight still gets the line once.
+    if (state === 'absent') return EXIT_ALLOW;
+
+    latch(root, session);
+    process.stdout.write(`${JSON.stringify({ decision: 'warn', reason: contextLine(state) })}\n`);
+    return EXIT_WARN;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (isCliEntry()) process.exit(main());

package/src/scripts/hooks/concern_registry.ts

@@ -58,7 +58,8 @@ import { main as oneQuestionPerAskMain } from './one_question_per_ask_hook.js';
 import { main as rtkWrapMain } from './rtk_wrap_hook.js';
 import { _main as designPassMain } from './design_pass_hook.js';
 import { main as designSlopMain } from './design_slop_hook.js';
-import { main as codeGraphNudgeMain } from './code_graph_nudge_hook.js';
+import { main as codeGraphContextMain } from './code_graph_context_hook.js';
+import { main as chainNudgeMain } from './chain_nudge_hook.js';
 import { main as suggestionCaptureMain } from './suggestion_capture_hook.js';
 import { main as uiRouteNudgeMain } from './ui_route_nudge_hook.js';
 import { main as orchestrationRecordMain } from './orchestration_record_hook.js';
@@ -120,7 +121,8 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/rtk_wrap_hook.ts': rtkWrapMain as ConcernMain,
     'src/scripts/hooks/design_pass_hook.ts': designPassMain as ConcernMain,
     'src/scripts/hooks/design_slop_hook.ts': designSlopMain as ConcernMain,
-    'src/scripts/hooks/code_graph_nudge_hook.ts': codeGraphNudgeMain as ConcernMain,
+    'src/scripts/hooks/code_graph_context_hook.ts': codeGraphContextMain as ConcernMain,
+    'src/scripts/hooks/chain_nudge_hook.ts': chainNudgeMain as ConcernMain,
     'src/scripts/hooks/suggestion_capture_hook.ts': suggestionCaptureMain as ConcernMain,
     'src/scripts/hooks/ui_route_nudge_hook.ts': uiRouteNudgeMain as ConcernMain,
     'src/scripts/hooks/orchestration_record_hook.ts': orchestrationRecordMain as ConcernMain,

package/src/scripts/hooks/host_semantics.ts

@@ -95,7 +95,7 @@ function _joinReasons(reasons: readonly string[]): string {
  *
  * Exit 0 + this JSON is the documented way to surface advisory feedback
  * WITHOUT blocking — the mapping the four advisory PreToolUse concerns
- * (design-slop, code-graph-nudge, rtk-wrap, block-config-weakening's
+ * (design-slop, code-graph-context, rtk-wrap, block-config-weakening's
  * advisory path) always intended.
  */
 export function claudeAdditionalContext(event: string, text: string): string {

package/src/scripts/hooks/orchestration_record_hook.ts

@@ -16,7 +16,7 @@
  * Fires only on an `Agent` / `Task` tool-use completion (the two names this
  * repo has observed for the subagent-dispatch tool across hosts/versions).
  * Every other tool call is a silent no-op — same tool-filter discipline as
- * `code-graph-nudge` (`tools: [Agent, Task]` in the manifest entry keeps the
+ * `code-graph-context` (`tools: [Agent, Task]` in the manifest entry keeps the
  * dispatcher from paying this concern's cost on unrelated calls).
  *
  * Sync vs async (road-to-orchestrator-first-execution measured: 326 of 370
@@ -89,7 +89,7 @@ export const DISPATCH_TOOL_NAMES: ReadonlySet<string> = new Set(['Agent', 'Task'
  * Unwrap the dispatcher envelope (`{schema_version, platform, event,
  * payload}`) down to the platform-native payload. Falls back to the
  * top-level object for direct/legacy invocation (same shape both
- * `pr_url_reminder_hook.ts` and `code_graph_nudge_hook.ts` handle).
+ * `pr_url_reminder_hook.ts` and `code_graph_context_hook.ts` handle).
  */
 export function unwrapPayload(envelope: JsonObject): JsonObject {
     const inner = envelope['payload'];

package/src/scripts/hooks/push_settle_hook.ts

@@ -191,8 +191,9 @@ export function buildReminder(branch: string, pr: number | null): { reason: stri
     `own exit code.\n\n` +
     `Before this turn ends:\n` +
     `  1. Settle it:\n     ${settle}\n` +
-    `     Exit 0 = settled green · 1 = settled, something failed · 2 = NOT a verdict ` +
-    `(timed out or unreadable — never report 2 as green).\n` +
+    `     Exit 0 = settled green, and the line names the head it is about · 1 = settled, ` +
+    `something failed · 2 = NOT a verdict (timed out, unreadable, or the PR is merged / ` +
+    `closed / head-diverged — never report 2 as green).\n` +
     `  2. Red? Read only the failing part:\n` +
     `     gh run view --job <id> --log-failed | grep -E '×|FAIL|Error'\n` +
     `     then fix it and push again (fix-what-you-see: the author is irrelevant).\n` +

package/src/scripts/hooks/rule_inject_hook.ts

@@ -11,12 +11,23 @@
  * the 36.2 %-against-48 % run at `docs/CLAIMS.md:188-189`. Whatever that
  * instrument's flaws — and ADR-202 closed it — it points one way.
  *
- * DEFAULT OFF, AND OFF MEANS ZERO BYTES. The concern registers on two slots but
- * returns before reading the router unless `lean_projection.mode: delivery` is
- * set. Under every shipped default it emits nothing, costs no injection budget,
- * and leaves the standing corpus exactly as it is today. That is why its
- * `hook-token-budget.json` row is registered against the per-prompt cap rather
- * than a measured emission: there is no measured emission to register yet.
+ * SHIPPED ON FOR CLAUDE CODE SINCE ADR-265 — corrected 2026-09-08 (R2 finding
+ * 4), because this paragraph read "DEFAULT OFF, AND OFF MEANS ZERO BYTES …
+ * under every shipped default it emits nothing … there is no measured emission
+ * to register yet" and all four clauses became false in the same change that
+ * edited the paragraph below it. The shipped template carries
+ * `lean_projection.mode: delivery` with `hosts: [claude-code]`
+ * (`src/config/agent-settings.template.yml`), `gateOpen` returns true on that
+ * pair, and the emission IS measured: p50 6,674 B, p90 16,188 B, max 20,406 B
+ * over 318 gate-open fires on the frozen corpus, which is the distribution the
+ * `user_prompt_submit` slot raise in `src/config/hook-token-budget.json` is
+ * derived from.
+ *
+ * OFF STILL MEANS ZERO BYTES, and that half is unchanged: the concern returns
+ * before reading the router unless the resolved (mode, hosts) pair actually
+ * thins THIS host — see `gateOpen`, which checks both, because the projector
+ * does. On any other host, and on a `lean_projection.mode: eager-all` rollback,
+ * it emits nothing.
  *
  * ONE MATCHER, SHARED WITH THE OFFLINE MODEL. Everything about selection,
  * ordering, capping and body loading comes from `_lib/rule_injection.ts`, which
@@ -31,10 +42,33 @@
  * uses. State lives under `agents/runtime/state/`, the class
  * `context-hygiene.json` already occupies; no new state convention is created.
  *
+ * WHAT IS RE-DELIVERED AFTER A COMPACTION, EXACTLY
+ * (road-to-delivery-for-every-host 2.4 — stated because a rule lost at a
+ * compaction boundary is lost for the rest of the session, and "re-armed" alone
+ * does not say what a reader may rely on):
+ *
+ *   · `pre_compact` clears the WHOLE seen-set for that session, not the rules
+ *     matched on the compacted turn. There is no per-rule bookkeeping to be
+ *     partially wrong about.
+ *   · Nothing is delivered BY the compaction itself. The slot emits zero bytes
+ *     and exits allow; re-arming is silent.
+ *   · A rule's body returns on the NEXT turn whose trigger matches it — which
+ *     means a rule whose trigger does not fire again is NOT restored. Delivery
+ *     is trigger-driven on both sides of the boundary; compaction resets the
+ *     de-duplication, it does not replay a transcript.
+ *   · The seen-set is per session, so a compaction in one session re-arms only
+ *     that session.
+ *
+ * Held by three fixtures in `tests/scripts/rule_inject_hook.test.ts` under
+ * "once per session per rule, re-armed on compaction": the dedup case, the
+ * matched-rule → compaction → matching-turn → body-present case, and the
+ * per-session case. All three predate this roadmap; 2.4 adds the contract
+ * above, not the coverage, and says so rather than claiming new tests.
+ *
  * NEVER BLOCKS. Every failure path returns 0: unreadable stdin, malformed JSON,
  * missing router, unreadable body, unwritable state. The one non-zero exit is
  * the host's advisory context channel (exit 2 + `decision: "warn"`), the same
- * channel `ui-route-nudge` and `code-graph-nudge` already use on `pre_tool_use`
+ * channel `ui-route-nudge` and `code-graph-context` already use on `pre_tool_use`
  * with `severity: advisory` — a warn there is an injection, not a deny.
  *
  * HOST BOUNDARY, STATED RATHER THAN IMPLIED. `user_prompt_submit` and
@@ -54,8 +88,12 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { hookSectionEnabled, leanProjectionModeRaw } from '../_lib/hook_settings.js';
-import { deliversBodies, normalizeLeanProjectionMode } from '../_lib/lean_projection_mode.js';
+import { hookSectionEnabled, leanProjectionHostsRaw, leanProjectionModeRaw } from '../_lib/hook_settings.js';
+import {
+    deliversBodies,
+    normalizeLeanProjectionMode,
+    resolveLeanProjectionHosts,
+} from '../_lib/lean_projection_mode.js';
 import {
     loadRuleBody,
     loadRouter,
@@ -81,15 +119,38 @@ const EXIT_WARN = 2;
  * slot, for a concern that is default-OFF and emits nothing. Measured: 202 ms
  * -> 196 ms on the `pre_tool_use` p95 when the concern is unbound entirely, and
  * the CI latency gate went red on the branch that introduced it while passing
- * on main. So the runtime cap is the same bound in the unit
+ * on main. So the runtime cap is stated in the unit
  * `hook-token-budget.json` already enforces — 5,000 tok at the ~4 bytes/token
- * this corpus measures is 20,480 B, which is exactly this concern's registered
- * row. Cap and budget row are now one number instead of two units.
+ * this corpus measures was 20,480 B, and that WAS this concern's registered
+ * row until 2026-09-08. It matched the concern row and not the slot row; see
+ * the correction below.
+ *
+ * LOWERED 20480 -> 16384 on 2026-09-08 (R2 finding 3), and the paragraphs above
+ * are kept because they record how the retired number was derived. The defect
+ * was that the derivation above and the one behind the
+ * `user_prompt_submit` slot row were TWO STATISTICS IN TWO UNITS: this cap was
+ * the p90 of the matched-body TOKEN distribution, converted at ~4 B/tok; the
+ * slot row is the p90 gate-open FIRE SIZE in bytes, which is the activation
+ * charge owner ruling E2 specifies. They disagreed by 25 %, in the direction
+ * that licensed ONE concern to emit more than the whole slot — carrying 12
+ * other concerns — is registered for. Reconciled downward onto the slot row,
+ * because that is the owner-specified charge; the cost is measured and recorded
+ * in `hook-token-budget.json`'s own `rule-inject_reason` (33 -> 45 fires
+ * truncated, 63 -> 88 bodies withheld over 330 corpus fires).
+ *
+ * WHAT THIS CAP DOES, precisely: `selectForInjection` drops whole bodies to
+ * stay under it, so a fire is TRUNCATED and never over-emitted. It is the only
+ * number that acts on a single fire — the per-slot sums are an authoring-time
+ * control read by `bench_hook_injection`, and the runtime dispatcher enforces
+ * only `per_turn_aggregate_bytes.ceiling_bytes`.
  *
  * Re-run that command if the corpus or the bodies move; a cap copied from a
- * stale measurement is worse than no cap, because it looks derived.
+ * stale measurement is worse than no cap, because it looks derived. The
+ * tripwire in `tests/scripts/rule_inject_hook.test.ts` holds this equal to the
+ * registered concern row and at or below the slot sum, so the two units cannot
+ * drift apart again unnoticed.
  */
-export const CAP_BYTES = 20480;
+export const CAP_BYTES = 16384;
 
 /** Tools whose input names a file this concern can match path triggers against. */
 export const FILE_TOOLS = new Set(['Write', 'Edit', 'NotebookEdit', 'Read', 'MultiEdit']);
@@ -216,18 +277,44 @@ export function buildInjection(
 
 // ── main ─────────────────────────────────────────────────────────────────
 
+/**
+ * The one host this concern is bound on.
+ *
+ * The manifest binds `rule-inject` under `claude` alone, so the host axis
+ * `gateOpen` has to consult is a constant here rather than something read off
+ * the envelope — the envelope carries no host id, and inventing one from the
+ * process environment would be a guess where the manifest is a fact.
+ */
+export const DELIVERY_HOST = 'claude-code';
+
 /**
  * Whether the settings gate applies.
  *
- * Through the dispatcher the gate is absolute: no `lean_projection.mode:
- * delivery`, no bytes. A DIRECT CLI invocation is a probe by definition — an
- * operator piping an envelope into this file is asking to see what it would
- * deliver — so there the mode defaults to on. `AGENT_CONFIG_REPLAY` re-imposes
- * the gate, which is what keeps `bench_hook_injection` measuring the shipped
- * default (zero bytes) rather than the probe.
+ * BOTH AXES, because the projector reads both. Until 2026-09-08 this keyed on
+ * `lean_projection.mode` alone while `condense` gates stub-writing on
+ * `thinsHost(mode, hosts, host)` (R2 finding 5). The two disagreed in exactly
+ * the states the host axis exists for: `mode: delivery` with a `hosts:` list
+ * that does not resolve to `claude-code` — the documented "thin no host"
+ * state, which a fully typo'd list also produces — left this host with a
+ * FULL-BODIED tree while the hook kept injecting on a match, so every matched
+ * rule was delivered twice. `hosts: [cursor]` was the same defect with a
+ * second half: cursor received stubs with no bound slot to deliver them back.
+ *
+ * `deliversBodies` is checked separately from the host list rather than via
+ * `thinsHost`, which is true for `thin` as well: `thin` writes the same stubs
+ * and binds NO delivery concern, so it must never open this gate.
+ *
+ * An explicit `hooks.rule_inject` opt-in still opens it — that is an operator
+ * asking for the concern by name, independent of the projection mode. A DIRECT
+ * CLI invocation is a probe by definition — an operator piping an envelope into
+ * this file is asking to see what it would deliver — so there the gate defaults
+ * to open. `AGENT_CONFIG_REPLAY` re-imposes it, which is what keeps
+ * `bench_hook_injection` measuring the configured tree rather than the probe.
  */
 export function gateOpen(root: string, cliEntry: boolean): boolean {
-    if (deliversBodies(normalizeLeanProjectionMode(leanProjectionModeRaw(root)))) return true;
+    const mode = normalizeLeanProjectionMode(leanProjectionModeRaw(root));
+    const hosts = resolveLeanProjectionHosts(leanProjectionHostsRaw(root)).hosts;
+    if (deliversBodies(mode) && hosts.includes(DELIVERY_HOST)) return true;
     if (hookSectionEnabled(root, 'rule_inject')) return true;
     return cliEntry && process.env['AGENT_CONFIG_REPLAY'] !== '1';
 }

package/src/scripts/hooks/session_eol_hook.ts

@@ -45,7 +45,11 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import recycleThresholdConfig from '../../config/recycle-threshold-budget.json';
 
-import { recycle_envelope_rel } from '../_lib/recycle_envelope_paths.js';
+import {
+    listContinuityRecords,
+    RECYCLE_MAX_AGE_HOURS,
+    recycle_envelope_rel,
+} from '../_lib/recycle_envelope_paths.js';
 import {
     emptyCounters,
     eolSessionKey,
@@ -56,6 +60,12 @@ import {
 } from '../_lib/session_eol.js';
 import { readContextObservation } from '../_lib/context_observation.js';
 import { buildCheckpoint, writeCheckpoint } from '../_lib/run_checkpoint.js';
+import {
+    auto_record_enabled,
+    buildContinuityRecord,
+    run_checkpoints_enabled,
+} from '../_lib/continuity_writer.js';
+import { publishContinuityRecord } from '../_lib/continuity_slot.js';
 import { read_claimed_slug } from '../session_register_hook.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
@@ -210,6 +220,62 @@ export function envelopeExists(
     }
 }
 
+/**
+ * Records that were written and never read — the detection layer this defect
+ * did not have.
+ *
+ * `road-to-a-recycle-envelope-that-is-consumed` step 1.2. Twelve unconsumed
+ * envelopes accumulated across the estate over roughly a month, and the only
+ * reason anyone found them was a stray-copy check during an unrelated task. The
+ * producer reported success, the consumer reported `absent`, and nothing
+ * compared the two — so the mechanism was inert for weeks with no signal.
+ *
+ * Advisory ONLY. A hook that blocks a session end over a stale runtime file is
+ * worse than the file, and that is Kill-register K3 of the roadmap rather than
+ * a preference here.
+ *
+ * Silent in the normal case, which is what keeps it worth reading: a record
+ * younger than {@link RECYCLE_MAX_AGE_HOURS} is a pending resume, not a defect,
+ * and past that age the consumer discards it loudly on its own. What this
+ * reports is the third state — old enough to be dead, still sitting there,
+ * which means no successor ever came for it.
+ */
+export function unconsumedRecordLines(
+    workspaceRoot: string,
+    now: Date = new Date(),
+    maxAgeHours: number = RECYCLE_MAX_AGE_HOURS,
+): string[] {
+    const out: string[] = [];
+    for (const file of listContinuityRecords(workspaceRoot)) {
+        let raw: string;
+        try {
+            raw = fs.readFileSync(file, 'utf-8');
+        } catch {
+            continue; // an unreadable record proves nothing in either direction
+        }
+        let written: unknown;
+        let nextTask: unknown;
+        try {
+            const parsed = JSON.parse(raw) as { written_at?: unknown; next_task?: unknown };
+            written = parsed.written_at;
+            nextTask = parsed.next_task;
+        } catch {
+            continue;
+        }
+        if (typeof written !== 'string') continue;
+        const stamp = Date.parse(written);
+        if (Number.isNaN(stamp)) continue;
+        const ageHours = (now.getTime() - stamp) / 3_600_000;
+        if (ageHours <= maxAgeHours) continue;
+        const task = typeof nextTask === 'string' && nextTask.trim() !== '' ? nextTask.trim() : '(no next_task)';
+        out.push(
+            `unconsumed continuity record: ${path.relative(workspaceRoot, file)} is ` +
+                `${ageHours.toFixed(0)}h old and was never read — next_task was "${task.slice(0, 120)}"`,
+        );
+    }
+    return out;
+}
+
 /**
  * The follow-up line: the advisory already fired, and no envelope arrived.
  *
@@ -389,7 +455,7 @@ export function main(): number {
     // Best-effort throughout. A checkpoint is a recovery aid, and a
     // recovery aid that can fail a Stop is a liability.
     const checkpointRunId = payloadSessionId(payload, envelope);
-    if (shouldAdvise && checkpointRunId !== '') {
+    if (shouldAdvise && checkpointRunId !== '' && run_checkpoints_enabled(workspaceRoot)) {
         try {
             const slug = read_claimed_slug(workspaceRoot, checkpointRunId);
             if (slug !== null) {
@@ -411,6 +477,8 @@ export function main(): number {
         }
     }
 
+    writeContinuityRecord(workspaceRoot, rawSessionId, counters, threshold, tokens);
+
     if (shouldAdvise && threshold !== null && tokens !== null) {
         process.stdout.write(
             `${JSON.stringify({
@@ -434,6 +502,56 @@ export function main(): number {
     return 0;
 }
 
+/**
+ * The continuity-record handler — one of the three lifecycle handlers this
+ * concern carries, and independently switchable from the other two.
+ *
+ * `road-to-continuity-writer-activation` step 1.2, and it lands INSIDE this
+ * concern rather than as a fourth concern id on purpose: `check_estate_count`
+ * ratchets `concern_count` with allowance 0, and the 2026-09-08 AI council
+ * refused a temporary allowance 2/2. The substance the 2026-09-07 council's D2
+ * asked for is independent switching and failure isolation, and a handler
+ * behind its own settings key inside a `try` gives both without a manifest
+ * split. The split itself is step 2.1 and stays blocked until a concern is
+ * retired to pay for it.
+ *
+ * Fires from the recycle THRESHOLD, not from the once-per-session advisory
+ * stamp: the stamp fires once, so a record written from it would be frozen at
+ * the moment the session crossed the threshold and would go stale as the
+ * session continued. Driving it from the raw threshold condition instead means
+ * every later Stop supersedes the record under the slot's own policy, so what a
+ * successor reads is always the newest state, and the write rate is still
+ * bounded to the end phase of a session rather than every turn of it.
+ *
+ * Best-effort throughout, like the checkpoint above it: a continuity record is
+ * a recovery aid, and a recovery aid that can fail a Stop is a liability.
+ */
+function writeContinuityRecord(
+    workspaceRoot: string,
+    rawSessionId: string | null,
+    counters: EolCounters,
+    threshold: number | null,
+    tokens: number | null,
+): void {
+    if (threshold === null || tokens === null || tokens < threshold) return;
+    const sessionId = String(rawSessionId ?? '').trim();
+    if (sessionId === '') return;
+    try {
+        if (!auto_record_enabled(workspaceRoot)) return;
+        const slug = read_claimed_slug(workspaceRoot, sessionId);
+        const decision = buildContinuityRecord({
+            root: workspaceRoot,
+            sessionId,
+            slug,
+            counters,
+        });
+        if (decision.record === null) return;
+        publishContinuityRecord(workspaceRoot, sessionId, decision.record);
+    } catch {
+        // never block the Stop path, and never suppress a sibling handler
+    }
+}
+
 // Bundle-safety: never auto-run when inlined into an esbuild bundle, where
 // every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
 declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;

package/src/scripts/hooks/skill_route_hook.ts

@@ -140,7 +140,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { readHookStdin } from "./hook_stdin.js";
 import { isSyntheticPrompt } from "../_lib/prompt_shape.js";
-import { OBSERVATION_LOG, readObservationLog, resolveSkillsRoot } from "../_lib/skill_catalogue.js";
+import { OBSERVATION_LOG, readObservationLog, resolveSkillCatalogueRoots } from "../_lib/skill_catalogue.js";
 import { knownBareNames } from "../_lib/skill_catalogue_series.js";
 import { _tokenize, rank, type RankRow } from "../skill_tools/score_skill_relevance.js";
 
@@ -252,13 +252,20 @@ export interface RouteDecision {
  */
 export function routeDecision(
   prompt: string,
-  skillsDir: string | null,
+  // One root, or every readable root. `null` and `[]` are the same answer — no
+  // catalogue was read — and both must stay silent rather than rank nothing and
+  // call that a result.
+  skillsDir: string | readonly string[] | null,
   bareProvider?: () => Set<string> | null,
 ): RouteDecision {
   const silent: RouteDecision = { rows: [], suppressed: 0 };
   if (skillsDir === null) return silent;
+  if (Array.isArray(skillsDir) && skillsDir.length === 0) return silent;
   // Denominator floor BEFORE the catalogue read: a prompt too short to score
-  // meaningfully cannot produce a pointer worth 337 file reads either.
+  // meaningfully cannot produce a pointer worth the read either. The count is
+  // deliberately not stated — it used to say "337 file reads", which was one
+  // root; the union reads every readable root and the figure depends on the
+  // machine's install.
   try {
     if (_tokenize(prompt).size < MIN_TASK_TERMS) return silent;
   } catch {
@@ -346,7 +353,7 @@ export function main(): number {
   const root = _workspaceRoot(env);
   const platform = env["platform"];
   const host = typeof platform === "string" && platform ? platform : null;
-  const { rows, suppressed } = routeDecision(prompt, resolveSkillsRoot(root), () =>
+  const { rows, suppressed } = routeDecision(prompt, resolveSkillCatalogueRoots(root), () =>
     knownBareForHost(root, host),
   );
   if (rows.length === 0) return EXIT_ALLOW; // silence is the default