@event4u/agent-config 12.1.0 → 14.0.0

package/src/scripts/hook_manifest.yaml

@@ -74,6 +74,21 @@ concerns:
   # Phase 5 — Tier-1 hook for the minimal-safe-diff rule. Counts unique
   # files touched per turn into agents/runtime/state/minimal-safe-diff.json and
   # flips warning=true past hooks.minimal_safe_diff.threshold.
+  # road-to-metric-loop-and-review-integrity Phase 4 — shipping-intent gate on
+  # diff VOLUME, complementary to `minimal-safe-diff` rather than a duplicate:
+  # that concern counts unique files touched PER TURN, this one counts changed
+  # lines on the branch AT A SHIP VERB. Threshold 1695 is the corrected p90 of
+  # this repository's own last 40 merged PRs, and the exclusion set (review-input
+  # snapshots, generated indexes, projection trees) is part of the metric's
+  # definition, not a tuning knob — the replay measured the naive metric
+  # double-counting the diff it was measuring. Warn-level first; escalation waits
+  # for one release of recorded firings. Evidence:
+  # agents/evidence/eval-findings/metric-loop-s04.md
+  ship-diff-volume:
+    script: src/scripts/hooks/ship_diff_volume_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
   minimal-safe-diff:
     script: src/scripts/minimal_safe_diff_hook.ts
     args: []
@@ -434,6 +449,28 @@ concerns:
     args: []
     fail_closed: false
     severity: advisory
+  # road-to-inbox-harvest-2026-08-d-runtime-skill-routing Phase 2 — binds the
+  # deterministic task→skill ranker, which had shipped with ZERO production
+  # callers: `score_skill_relevance.rank` and its `suggest_skill_for_task`
+  # wrapper were reachable only from their CLIs and from `routing:doctor`.
+  # Ranks the SUBMITTED prompt over the installed skill catalogue and injects
+  # at most one line naming the top-3 skill ids and their scores — POINTERS,
+  # never bodies, never a load instruction. Same delivery as `delegation-nudge`
+  # above: `{decision:"warn", reason, additional_context}` at exit 2, reduced
+  # to a real exit of 0 by `host_semantics.emitFor`'s warn branch, so it never
+  # blocks a turn.
+  #
+  # Silence is the default and its floor is MEASURED, not chosen: `rank`
+  # returns something on nearly every real prompt, so the trigger is a top-1
+  # score at or above 30/100 — the p90 of the routing-matrix corpus (496 prompt
+  # lines; median 18, p75 28, max 70), firing on 13.9% of them. A median floor
+  # would speak on half of all turns, which is the per-turn-reminder shape this
+  # estate has already measured failing. fail_closed: false.
+  skill-route:
+    script: src/scripts/hooks/skill_route_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
   # road-to-orchestrator-discipline-carriers Phase 5 (F4-lite) — end-review
   # nudge. Fires ONLY when the session mutated tracked+untracked, non-doc
   # files beyond MUTATION_LINE_THRESHOLD (50 lines; untracked files added
@@ -452,6 +489,16 @@ concerns:
     args: []
     fail_closed: false
     severity: advisory
+    # road-to-stop-gate-honesty step 3.1 — skipped on a refusal RETRY.
+    # ARGUMENT, per concern as that step requires: the F2 fire gate is a
+    # once-per-session marker, and this concern's own header records that a
+    # second run "reads the marker and returns silently, without re-running the
+    # transcript scan". The retry therefore cannot change its artefact — the
+    # telemetry line was already written, or already suppressed, on the first
+    # Stop. Idempotence is the concern's own construction, not our assumption
+    # about it. The saving is the module load rather than a large read, which is
+    # the smaller of the two flags below it and is stated as such.
+    skip_on_refusal_retry: true
   # road-to-conformance-round5 Phase 3 — the FIRST concern that can refuse a
   # turn-END. Round 5 measured the reason: both blocking carriers reached zero
   # violations, neither advisory carrier did, and 19 language violations
@@ -535,6 +582,43 @@ concerns:
     args: []
     fail_closed: false
     severity: advisory
+  # road-to-user-out-of-the-loop Phase 0 Step 1 — the interruption ledger.
+  # Every Stop, classifies whether the turn that just ended put a synchronous
+  # contact to the user and appends one `{run_id, turn, kind, class, roadmap}`
+  # line to gitignored runtime state (agents/runtime/state/interruptions.jsonl,
+  # file shape after gate-metrics.jsonl). Three classes, not two: a hand-back
+  # ("das entscheidest Du", "your call") ends the turn and waits for the user
+  # exactly as a question does, so counting only `?` would report this
+  # package's own preferred shape as zero contacts.
+  #
+  # CAPTURE ONLY, and that is the point rather than caution: Phase 0's two
+  # pre-registered claims are baselines, and a baseline can only be read off a
+  # window no mechanism reacted to. It emits nothing, never warns, and always
+  # returns 0 — so it carries no src/config/hook-token-budget.json row, the
+  # same as subagent-ledger and orchestration-record.
+  #
+  # Reply-shape detection is IMPORTED from turn-end-gate (readTranscriptTail,
+  # finalParagraph, HANDBACK) rather than copied — a second copy would drift
+  # from the measured corpus's detector and the drift would land silently in
+  # the baseline. Dedupe on the turn ordinal, the same identity that hook
+  # derives, because a host may fire Stop twice for one turn. fail_closed: false.
+  interruption-ledger:
+    script: src/scripts/hooks/interruption_ledger_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
+    # road-to-stop-gate-honesty step 3.1 — skipped on a refusal RETRY, and this
+    # is the flag with the real saving.
+    # ARGUMENT, per concern: `alreadyRecorded(ledgerPath, run_id, turn)` dedupes
+    # on the TURN ORDINAL, and a refusal retry is the same turn by construction
+    # — the gate's layer-2 marker is keyed on that same ordinal. So the ledger
+    # already writes nothing on the retry and the artefact is provably identical.
+    # What it does NOT already avoid is the cost: `main()` calls
+    # `readTranscriptTail` (up to 8 MB, walking the whole file) BEFORE reaching
+    # `alreadyRecorded`, so today every refused Stop pays a full transcript walk
+    # and then discards the result. That is the "pure duplicate cost" § D-3
+    # names, measured in the source rather than assumed.
+    skip_on_refusal_retry: true
   # road-to-subagent-lifecycle-integrity Phase 1 (Steps 2+3) — the subagent
   # lifecycle ledger. Binds ONLY the two new events; on every other slot it is
   # not listed at all. Appends `subagent_start` / `subagent_stop` lines to
@@ -639,22 +723,31 @@ roles:
     # Orchestrator-only concerns (Phase 2.3): a worker never talks to the
     # user, never dispatches sub-workers, never runs the council, and its
     # complaints route via the orchestrator.
-    drop: [delegation-nudge, end-review-nudge, council-availability, team-review-gate, self-repair, session-eol]
+    # `skill-route` joins the drop list for the same reason `delegation-nudge`
+    # is on it: a worker was handed a bounded slice by an orchestrator that
+    # already chose the approach, so a routing pointer there advises nobody who
+    # can act on it and costs the dispatch anyway.
+    # `interruption-ledger` joins it on the first clause verbatim — "a worker
+    # never talks to the user". Its whole measurement is synchronous user
+    # contacts, so a worker turn that ends in a question to its orchestrator
+    # would be recorded as a contact that never reached a human, inflating the
+    # exact baseline Phase 0 pre-registers.
+    drop: [delegation-nudge, skill-route, end-review-nudge, council-availability, team-review-gate, self-repair, session-eol, interruption-ledger]
 
 platforms:
   augment:
     session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:      [chat-history, memory-learn, session-register]
     stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register]
-    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard]
+    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, ship-diff-volume, reread-guard]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
 
   claude:
     session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:      [chat-history, memory-learn, session-register]
-    stop:             [chat-history, hot-context, verify-before-complete, team-review-gate, end-review-nudge, turn-end-gate, self-repair, session-register, session-eol]
-    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, delegation-nudge, git-authorization, session-canary, self-repair, session-register]
-    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard, spawn-guard-shadow]
+    stop:             [chat-history, hot-context, verify-before-complete, team-review-gate, end-review-nudge, turn-end-gate, self-repair, session-register, session-eol, interruption-ledger]
+    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, delegation-nudge, skill-route, git-authorization, session-canary, self-repair, session-register]
+    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, ship-diff-volume, reread-guard, spawn-guard-shadow]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape, language-mirror]
     # `language-mirror` — round-5 § 6.1. `pre_compact` sets a pin-lost marker;
     # the `post_tool_use` entry above re-emits the pin exactly once while that
@@ -708,7 +801,7 @@ platforms:
     # still costs the dispatch, and its entire output is thrown away.
     stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
-    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard, spawn-guard-shadow]
+    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, ship-diff-volume, reread-guard, spawn-guard-shadow]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
     # subagent-ledger IS bound here, unlike the two nudges above, and the
     # difference is the delivery channel rather than the platform: the nudges

package/src/scripts/hooks/concern_registry.ts

@@ -32,6 +32,7 @@ import { main as onboardingGateMain } from '../onboarding_gate_hook.js';
 import { main as contextHygieneMain } from '../context_hygiene_hook.js';
 import { main as verifyBeforeCompleteMain } from '../before_complete_hook.js';
 import { main as minimalSafeDiffMain } from '../minimal_safe_diff_hook.js';
+import { main as shipDiffVolumeMain } from './ship_diff_volume_hook.js';
 import { main as injectionScanMain } from '../injection_scan_hook.js';
 import { main as memoryLearnMain } from '../memory_learn_hook.js';
 import { main as firstRunGateMain } from '../first_run_gate_hook.js';
@@ -57,6 +58,7 @@ import { main as codeGraphNudgeMain } from './code_graph_nudge_hook.js';
 import { main as uiRouteNudgeMain } from './ui_route_nudge_hook.js';
 import { main as orchestrationRecordMain } from './orchestration_record_hook.js';
 import { main as delegationNudgeMain } from './delegation_nudge_hook.js';
+import { main as skillRouteMain } from './skill_route_hook.js';
 import { main as endReviewNudgeMain } from './end_review_nudge_hook.js';
 import { main as turnEndGateMain } from './turn_end_gate_hook.js';
 import { main as editShapeMain } from './edit_shape_hook.js';
@@ -65,6 +67,7 @@ import { main as sessionEolMain } from './session_eol_hook.js';
 import { main as subagentLedgerMain } from './subagent_ledger_hook.js';
 import { main as toolResultBytesMain } from './tool_result_bytes_hook.js';
 import { main as spawnGuardShadowMain } from './spawn_guard_shadow_hook.js';
+import { main as interruptionLedgerMain } from './interruption_ledger_hook.js';
 
 /** A concern `main` — argv-taking or not; both shapes exist. */
 export type ConcernMain = (argv?: string[]) => number | undefined | void;
@@ -79,6 +82,7 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/context_hygiene_hook.ts': contextHygieneMain as ConcernMain,
     'src/scripts/before_complete_hook.ts': verifyBeforeCompleteMain as ConcernMain,
     'src/scripts/minimal_safe_diff_hook.ts': minimalSafeDiffMain as ConcernMain,
+    'src/scripts/hooks/ship_diff_volume_hook.ts': shipDiffVolumeMain as ConcernMain,
     'src/scripts/injection_scan_hook.ts': injectionScanMain as ConcernMain,
     'src/scripts/memory_learn_hook.ts': memoryLearnMain as ConcernMain,
     'src/scripts/first_run_gate_hook.ts': firstRunGateMain as ConcernMain,
@@ -104,6 +108,7 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/ui_route_nudge_hook.ts': uiRouteNudgeMain as ConcernMain,
     'src/scripts/hooks/orchestration_record_hook.ts': orchestrationRecordMain as ConcernMain,
     'src/scripts/hooks/delegation_nudge_hook.ts': delegationNudgeMain as ConcernMain,
+    'src/scripts/hooks/skill_route_hook.ts': skillRouteMain as ConcernMain,
     'src/scripts/hooks/end_review_nudge_hook.ts': endReviewNudgeMain as ConcernMain,
     'src/scripts/hooks/turn_end_gate_hook.ts': turnEndGateMain as ConcernMain,
     'src/scripts/hooks/edit_shape_hook.ts': editShapeMain as ConcernMain,
@@ -112,4 +117,5 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/subagent_ledger_hook.ts': subagentLedgerMain as ConcernMain,
     'src/scripts/hooks/tool_result_bytes_hook.ts': toolResultBytesMain as ConcernMain,
     'src/scripts/hooks/spawn_guard_shadow_hook.ts': spawnGuardShadowMain as ConcernMain,
+    'src/scripts/hooks/interruption_ledger_hook.ts': interruptionLedgerMain as ConcernMain,
 };

package/src/scripts/hooks/dispatch_hook.ts

@@ -342,16 +342,51 @@ export function _role_drop_set(
   return new Set(drop.filter((d): d is string => typeof d === "string"));
 }
 
+/**
+ * True when this `stop` is the RETRY of a turn a stop-hook already refused.
+ *
+ * The host sets `stop_hook_active` on exactly that Stop; `turn_end_gate_hook`
+ * reads the same field as its layer-1 re-entrancy guard, so this is the host's
+ * own answer rather than an inference of ours. Anything unparseable is `false`,
+ * which is the full chain — the safe direction, since the cost of running a
+ * concern twice is duplicate work and the cost of skipping one wrongly is a lost
+ * write.
+ */
+export function _is_refusal_retry(event: string, payload_text: string): boolean {
+  if (event !== "stop") return false;
+  try {
+    const parsed: unknown = JSON.parse(payload_text);
+    if (!_isObject(parsed)) return false;
+    const payload = parsed["payload"];
+    const source = _isObject(payload) ? payload : parsed;
+    return source["stop_hook_active"] === true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Return the ordered concern definitions for (platform, event) under the
  * given session role (default `orchestrator` — byte-identical to the
  * pre-role-axis behaviour).
+ *
+ * `opts.refusal_retry` drops concerns that opted in with
+ * `skip_on_refusal_retry: true` — `road-to-stop-gate-honesty` step 3.1. Stop is
+ * the heaviest slot on claude and **every refused Stop runs the whole slot again
+ * on the retry** (§ D-3), so the concerns whose second run provably produces the
+ * identical artefact are pure duplicate cost.
+ *
+ * Opt-in per concern, default off, never a blanket skip: Risk 3 of that roadmap
+ * is that a concern skipped on the retry might have been the one that needed the
+ * second pass, and the loss would be silent. The manifest carries the per-concern
+ * argument beside each flag.
  */
 export function _resolve_concerns(
   manifest: JsonObject,
   platform: string,
   event: string,
   role: SessionRole = "orchestrator",
+  opts: { refusal_retry?: boolean } = {},
 ): ConcernDef[] {
   const platformsRaw = manifest["platforms"];
   const platforms = _isObject(platformsRaw) ? platformsRaw : {};
@@ -381,6 +416,9 @@ export function _resolve_concerns(
       );
       continue;
     }
+    if (opts.refusal_retry && spec["skip_on_refusal_retry"] === true) {
+      continue;
+    }
     out.push({ name: String(name), ...spec });
   }
   return out;
@@ -1081,13 +1119,17 @@ export function main(argv?: string[]): number {
   const payload_text = process.stdin.isTTY ? "" : _readStdin();
   _maybe_capture_payload(args, payload_text);
   const session_role = resolveSessionRole(process.env);
-  const concerns = _resolve_concerns(manifest, args.platform, args.event, session_role);
+  const refusal_retry = _is_refusal_retry(args.event, payload_text);
+  const concerns = _resolve_concerns(manifest, args.platform, args.event, session_role, {
+    refusal_retry,
+  });
 
   if (args.dry_run) {
     const plan = {
       platform: args.platform,
       event: args.event,
       role: session_role,
+      refusal_retry,
       concerns: concerns.map((c) => c["name"]),
     };
     process.stdout.write(_py_json_dumps(plan, 2) + "\n");

package/src/scripts/hooks/interruption_ledger_hook.ts

@@ -0,0 +1,256 @@
+/**
+ * interruption_ledger — road-to-user-out-of-the-loop Phase 0 Step 1.
+ *
+ * CAPTURE ONLY. Every `stop`, classifies whether the turn that just ended put a
+ * synchronous contact to the user, and appends one line to
+ * `agents/runtime/state/interruptions.jsonl`. It never emits context, never
+ * warns, and always returns 0 — the whole point of Phase 0 is a window that no
+ * mechanism reacted to, so a ledger that could change a run would corrupt the
+ * baseline it exists to measure.
+ *
+ * WHY THIS EXISTS. The roadmap's Goal names two axes — synchronous contacts per
+ * delivered roadmap, and wall-clock to open PR — and pre-registers both as
+ * claims. Neither is derivable today: nothing in the tree records that a turn
+ * ended by asking the user something. `check_enforcement_coverage` counts
+ * carriers, `gate-metrics.jsonl` counts gate verdicts, and the conformance suite
+ * scores reply SHAPE without ever asking whether the reply stopped the run.
+ *
+ * REUSE, NOT REIMPLEMENTATION. Reply-shape detection is `turn_end_gate_hook`'s,
+ * imported rather than copied: `readTranscriptTail` for the last assistant text,
+ * `finalParagraph` for the closing paragraph, and its `HANDBACK` list for the
+ * yields-without-asking shape. That file is the measured corpus's detector and
+ * has an R2 history behind each regex; a second copy here would drift from it
+ * silently and the drift would land in the baseline, not in a test.
+ *
+ * WHAT COUNTS AS A CONTACT, and why it is three classes rather than two. A
+ * question mark is the obvious one. It is not the only one: `scope-control`
+ * requires a hand-back — "das entscheidest Du", "your call" — which ends the
+ * turn and waits for the user just as hard as a question does, with no `?`
+ * anywhere. Counting only questions would report the package's own preferred
+ * hand-back shape as zero contacts, which is precisely the metric-that-flatters-
+ * the-design failure the roadmap's Risk 6 names.
+ *
+ *   ask       — the closing paragraph ends in a question mark.
+ *   handback  — no question, but the closing paragraph yields the decision.
+ *   none      — the turn ended without putting anything to the user.
+ *
+ * `class` refines an `ask` by the shape the user has to answer in:
+ * `numbered-options` when the reply carries a numbered block (the
+ * `user-interaction` shape — one decision point, cheap to answer), or
+ * `open-question` when it does not (free text, the expensive shape). The split
+ * exists because the two are not equal contacts and the report separates them.
+ *
+ * DEDUPE is on the turn ordinal, the same identity `turn_end_gate_hook` derives
+ * and for the same reason: a host may fire `stop` more than once for one turn,
+ * and a per-turn ledger that double-counts inflates exactly the number the
+ * baseline is pre-registered on.
+ *
+ * The roadmap slug comes from this session's own claim file — the one
+ * `agent-config sessions:claim` writes — so a contact is attributable to a
+ * delivered roadmap without this hook knowing anything about roadmaps. No claim
+ * means `roadmap: null`, which is a real and common state (any session that is
+ * not a roadmap run) and never a reason to skip the line.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { derive_session_tag } from '../chat_history.js';
+import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
+import { readHookStdin } from './hook_stdin.js';
+import { HANDBACK, finalParagraph, readTranscriptTail } from './turn_end_gate_hook.js';
+
+const EXIT_OK = 0;
+
+/** Same cap the turn-end gate reads its tail under. */
+const TRANSCRIPT_READ_MAX_BYTES = 2 * 1024 * 1024;
+
+export const LEDGER_RELPATH = path.join('agents', 'runtime', 'state', 'interruptions.jsonl');
+
+export type ContactKind = 'ask' | 'handback' | 'none';
+export type ContactClass = 'numbered-options' | 'open-question' | 'handback' | 'none';
+
+export interface InterruptionRecord {
+    run_id: string;
+    turn: number;
+    kind: ContactKind;
+    class: ContactClass;
+    roadmap: string | null;
+    at: string;
+}
+
+/**
+ * A numbered-options block: two or more numbered lines. One numbered line is an
+ * ordinary enumeration inside prose and is not a decision surface — requiring
+ * two is what keeps "1. read the file" from reading as an ask.
+ */
+export function hasNumberedOptions(reply: string): boolean {
+    let count = 0;
+    for (const line of reply.split('\n')) {
+        if (/^[ \t]{0,3}\d+[.)]\s+\S/.test(line)) count += 1;
+        if (count >= 2) return true;
+    }
+    return false;
+}
+
+/**
+ * Classify the reply. The question test is `turn_end_gate_hook`'s exactly — a
+ * question that ENDS the paragraph, never `includes('?')`, because a rhetorical
+ * or quoted question mid-reply is not a contact and counting it would inflate
+ * the baseline in the direction that makes the roadmap look successful later.
+ */
+export function classifyReply(reply: string): { kind: ContactKind; class: ContactClass } {
+    const tail = finalParagraph(reply);
+    if (!tail) return { kind: 'none', class: 'none' };
+
+    if (/\?["'’)\]]*\s*$/.test(tail)) {
+        return {
+            kind: 'ask',
+            class: hasNumberedOptions(reply) ? 'numbered-options' : 'open-question',
+        };
+    }
+    if (HANDBACK.some((re) => re.test(tail))) return { kind: 'handback', class: 'handback' };
+    return { kind: 'none', class: 'none' };
+}
+
+/** The roadmap this session claimed, or null. Never throws. */
+export function readClaimedRoadmap(workspaceRoot: string, sessionId: string): string | null {
+    if (!sessionId) return null;
+    try {
+        const file = path.join(
+            workspaceRoot,
+            'agents',
+            'runtime',
+            'state',
+            `roadmap-claim-${sessionId}.json`,
+        );
+        const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (parsed === null || typeof parsed !== 'object') return null;
+        const slug = (parsed as Record<string, unknown>)['slug'];
+        return typeof slug === 'string' && slug.length > 0 ? slug : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * True when this run has already recorded this turn. Reads only the tail of the
+ * ledger: the duplicate a repeated `stop` produces is always the most recent
+ * line, so scanning the whole file would cost more on every turn to catch
+ * nothing extra.
+ */
+export function alreadyRecorded(ledgerPath: string, runId: string, turn: number): boolean {
+    let raw: string;
+    try {
+        raw = fs.readFileSync(ledgerPath, 'utf8');
+    } catch {
+        return false;
+    }
+    const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+    for (const line of lines.slice(-20)) {
+        try {
+            const rec: unknown = JSON.parse(line);
+            if (rec === null || typeof rec !== 'object') continue;
+            const r = rec as Record<string, unknown>;
+            if (r['run_id'] === runId && r['turn'] === turn) return true;
+        } catch {
+            // A corrupt line is not a reason to skip the write.
+        }
+    }
+    return false;
+}
+
+function str(v: JsonValue | undefined): string {
+    return typeof v === 'string' ? v : '';
+}
+
+export function main(): number {
+    let envelope: JsonObject;
+    let payload: JsonObject;
+    try {
+        [envelope, payload] = unwrap(readHookStdin(), 'claude');
+    } catch {
+        return EXIT_OK;
+    }
+
+    const workspaceRoot = str(envelope['workspace_root'] as JsonValue | undefined) || process.cwd();
+    const transcriptPath = str(
+        (payload['transcript_path'] ?? payload['transcriptPath']) as JsonValue | undefined,
+    );
+    if (!transcriptPath) return EXIT_OK;
+
+    let lastAssistant = '';
+    let turnOrdinal = 0;
+    try {
+        const tail = readTranscriptTail(transcriptPath, { maxBytes: TRANSCRIPT_READ_MAX_BYTES });
+        lastAssistant = tail.lastAssistant;
+        turnOrdinal = tail.turnOrdinal;
+    } catch {
+        return EXIT_OK;
+    }
+    if (!lastAssistant) return EXIT_OK;
+
+    const sessionId =
+        str(payload['session_id'] as JsonValue | undefined) ||
+        str(envelope['session_id'] as JsonValue | undefined);
+    // `derive_session_tag`, NOT the turn-end gate's `deriveSessionKey`. Both
+    // hash the session id, and only this one produces the tag `chat_history`
+    // already writes as `s`. The wall-clock axis is a join between this ledger
+    // and those timestamps, so a 32-char key from the other derivation would
+    // have made the roadmap's second pre-registered claim underivable — while
+    // looking correct in every test that never crossed the two files.
+    const runId = sessionId ? derive_session_tag(sessionId) : 'unknown';
+
+    const ledgerPath = path.join(workspaceRoot, LEDGER_RELPATH);
+    if (alreadyRecorded(ledgerPath, runId, turnOrdinal)) return EXIT_OK;
+
+    const verdict = classifyReply(lastAssistant);
+    const record: InterruptionRecord = {
+        run_id: runId,
+        turn: turnOrdinal,
+        kind: verdict.kind,
+        class: verdict.class,
+        roadmap: readClaimedRoadmap(workspaceRoot, sessionId),
+        at: new Date().toISOString(),
+    };
+
+    try {
+        fs.mkdirSync(path.dirname(ledgerPath), { recursive: true });
+        fs.appendFileSync(ledgerPath, `${JSON.stringify(record)}\n`, 'utf8');
+    } catch {
+        // A ledger that cannot be written is a lost measurement, never a
+        // reason to affect the turn. Phase 0 is advisory by construction.
+    }
+    return EXIT_OK;
+}
+
+/**
+ * The concern runs in-process via `CONCERN_REGISTRY`, but the manifest's
+ * `script:` path is also the SPAWN FALLBACK — and without this guard that path
+ * imports the module, calls nothing, and exits 0. A silent no-op on a
+ * capture-only concern is invisible by construction: the ledger simply stays
+ * empty and the baseline reads as "no contacts". Caught by running the hook
+ * against a real envelope rather than by any unit test, which is why the probe
+ * is worth the two minutes.
+ */
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}