@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/probe_turnaround.ts

@@ -0,0 +1,384 @@
+#!/usr/bin/env tsx
+/**
+ * Turnaround instrument — round-trips, batch size, blocking waits, context floor.
+ *
+ * WHY IT EXISTS. `agents/evidence/analysis/agent-turnaround-2026-08-30.md`
+ * measured that a user request in this package costs 42.6 API round-trips and a
+ * file change costs 58 tool calls, and its fifth finding is that NONE of it was
+ * measurable before: no instrument in the tree reported round-trips per request,
+ * tool-call batch size, or the blocking-wait tail, so no gate could have caught
+ * any of them growing. That analysis was a throwaway script. This is the
+ * committed form of it — `road-to-agent-turnaround` Phase 1.1.
+ *
+ * THE UNIT IS `requestId`, NOT THE ROW. The host writes `thinking`, `text` and
+ * `tool_use` as SEPARATE JSONL rows that share one `requestId`, so counting rows
+ * inflates every per-call figure. That was the first wrong answer the original
+ * measurement produced, and it is why this file groups before it counts.
+ *
+ * WHAT IT REPORTS, per corpus:
+ *   - API calls per real user request      (F1)
+ *   - mean tool-call batch size            (F1 — measured 1.00, i.e. fully serial)
+ *   - the >60 s blocking tail and its share of tool time  (F2)
+ *   - the first-call context floor         (F3 cross-check)
+ *
+ * A MEASUREMENT, NOT A GATE — by default. `--against-baseline` compares against
+ * `src/config/turnaround-budget.json` and is the only mode that can exit
+ * non-zero. Whether that mode may run in CI is answered in the config's own
+ * `_comment`, because a transcript store is machine-local and a fresh clone has
+ * none: a CI gate over it would be green-because-empty, the exact
+ * gate-that-scans-nothing-exits-green failure this repository names elsewhere.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/probe_turnaround [--store PATH] [--limit N]
+ *   ./scripts-run src/scripts/probe_turnaround --json
+ *   ./scripts-run src/scripts/probe_turnaround --against-baseline
+ *
+ * The MEASURING session is excluded by default — see `recentSessions`.
+ *
+ * Exit codes: 0 = reported (or within baseline) · 1 = baseline regression, or an
+ * empty corpus under `--against-baseline` · 2 = usage error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { defaultStore, isInjectedBody, userText } from './conformance_scan.js';
+
+const _FILE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_FILE), '..', '..');
+export const BUDGET_REL = 'src/config/turnaround-budget.json';
+
+/** The blocking-tail threshold, in seconds. Fixed by the source measurement. */
+export const BLOCKING_SECONDS = 60;
+
+type Entry = Record<string, unknown>;
+
+function isObj(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+export interface Turnaround {
+    sessions: number;
+    userRequests: number;
+    apiCalls: number;
+    callsPerRequest: number;
+    toolCalls: number;
+    /** Requests that carried at least one tool_use block. */
+    toolUsingRequests: number;
+    meanBatchSize: number;
+    toolSeconds: number;
+    blockingCalls: number;
+    blockingSeconds: number;
+    blockingShare: number;
+    contextFloorMin: number;
+    contextFloorMax: number;
+}
+
+const ZERO: Turnaround = {
+    sessions: 0,
+    userRequests: 0,
+    apiCalls: 0,
+    callsPerRequest: 0,
+    toolCalls: 0,
+    toolUsingRequests: 0,
+    meanBatchSize: 0,
+    toolSeconds: 0,
+    blockingCalls: 0,
+    blockingSeconds: 0,
+    blockingShare: 0,
+    contextFloorMin: 0,
+    contextFloorMax: 0,
+};
+
+function ms(iso: unknown): number | null {
+    if (typeof iso !== 'string') return null;
+    const t = Date.parse(iso);
+    return Number.isNaN(t) ? null : t;
+}
+
+/**
+ * The N most recently modified transcript files under `store`, excluding the
+ * MEASURING session.
+ *
+ * The exclusion is not hygiene, it is correctness, and it was found by the
+ * instrument failing its own baseline. Two consecutive runs minutes apart
+ * reported `calls_per_request` 81.42 then 81.61: the measuring session was
+ * adding API calls to the newest transcript while its user-request denominator
+ * stayed at one, so the probe was reading its own execution as a regression.
+ * The source analysis excluded the measuring session for the same reason and
+ * said so; this reproduces that rather than rediscovering it a third time.
+ *
+ * Identified by `CLAUDE_CODE_SESSION_ID` where the host exports it — the file
+ * is `<sessionId>.jsonl` — and otherwise by dropping the single
+ * most-recently-modified file, which is the same session by construction on any
+ * machine actually running this. `--include-current` opts back in for an
+ * offline corpus where nothing is being written.
+ */
+export function recentSessions(store: string, limit: number, includeCurrent = false): string[] {
+    if (!fs.existsSync(store)) return [];
+    const all = fs
+        .readdirSync(store)
+        .filter((f) => f.endsWith('.jsonl'))
+        .map((f) => ({ f, m: fs.statSync(path.join(store, f)).mtimeMs }))
+        .sort((a, b) => b.m - a.m);
+    if (!includeCurrent && all.length > 0) {
+        const sid = process.env['CLAUDE_CODE_SESSION_ID'];
+        const idx =
+            sid !== undefined && sid !== ''
+                ? all.findIndex((x) => x.f === `${sid}.jsonl`)
+                : 0;
+        if (idx >= 0) all.splice(idx, 1);
+    }
+    return all.slice(0, limit).map(({ f }) => path.join(store, f));
+}
+
+export function measure(files: readonly string[]): Turnaround {
+    const requestIds = new Set<string>();
+    /** requestId → tool_use blocks in it. */
+    const batch = new Map<string, number>();
+    /** tool_use id → the timestamp the assistant emitted it. */
+    const emittedAt = new Map<string, number>();
+    const durations: number[] = [];
+    const contextFloors: number[] = [];
+    let userRequests = 0;
+    let sessions = 0;
+
+    for (const file of files) {
+        let sawFloor = false;
+        let sawAny = false;
+        for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+            if (!line.trim()) continue;
+            let e: Entry;
+            try {
+                e = JSON.parse(line) as Entry;
+            } catch {
+                continue;
+            }
+            if (e['isSidechain'] === true) continue;
+            sawAny = true;
+            const msg = e['message'];
+
+            if (e['type'] === 'user') {
+                // The SAME predicate the conformance scan uses, imported rather
+                // than re-typed: a skill body and a slash-command header arrive
+                // in the user role and are not requests. Counting them would
+                // deflate calls-per-request by inventing a denominator.
+                const text = userText(e);
+                if (text !== null && !isInjectedBody(text)) userRequests += 1;
+                if (isObj(msg) && Array.isArray(msg['content'])) {
+                    const at = ms(e['timestamp']);
+                    for (const b of msg['content']) {
+                        if (!isObj(b) || b['type'] !== 'tool_result') continue;
+                        const id = String(b['tool_use_id'] ?? '');
+                        const started = emittedAt.get(id);
+                        if (started === undefined || at === null) continue;
+                        durations.push((at - started) / 1000);
+                        emittedAt.delete(id);
+                    }
+                }
+                continue;
+            }
+
+            if (e['type'] !== 'assistant') continue;
+            const rid = e['requestId'];
+            if (typeof rid === 'string' && rid !== '') requestIds.add(rid);
+
+            if (!sawFloor && isObj(msg) && isObj(msg['usage'])) {
+                const u = msg['usage'] as Record<string, unknown>;
+                const floor =
+                    Number(u['input_tokens'] ?? 0) +
+                    Number(u['cache_read_input_tokens'] ?? 0) +
+                    Number(u['cache_creation_input_tokens'] ?? 0);
+                if (floor > 0) {
+                    contextFloors.push(floor);
+                    sawFloor = true;
+                }
+            }
+
+            if (!isObj(msg) || !Array.isArray(msg['content'])) continue;
+            const at = ms(e['timestamp']);
+            let n = 0;
+            for (const b of msg['content']) {
+                if (!isObj(b) || b['type'] !== 'tool_use') continue;
+                n += 1;
+                const id = String(b['id'] ?? '');
+                if (id !== '' && at !== null) emittedAt.set(id, at);
+            }
+            if (n > 0 && typeof rid === 'string' && rid !== '') {
+                batch.set(rid, (batch.get(rid) ?? 0) + n);
+            }
+        }
+        if (sawAny) sessions += 1;
+    }
+
+    const toolCalls = [...batch.values()].reduce((a, b) => a + b, 0);
+    const toolSeconds = durations.reduce((a, b) => a + b, 0);
+    const blocking = durations.filter((d) => d > BLOCKING_SECONDS);
+    const blockingSeconds = blocking.reduce((a, b) => a + b, 0);
+    const round = (x: number, p = 2): number => Math.round(x * 10 ** p) / 10 ** p;
+
+    return {
+        sessions,
+        userRequests,
+        apiCalls: requestIds.size,
+        callsPerRequest: userRequests === 0 ? 0 : round(requestIds.size / userRequests),
+        toolCalls,
+        toolUsingRequests: batch.size,
+        meanBatchSize: batch.size === 0 ? 0 : round(toolCalls / batch.size),
+        toolSeconds: round(toolSeconds, 1),
+        blockingCalls: blocking.length,
+        blockingSeconds: round(blockingSeconds, 1),
+        blockingShare: toolSeconds === 0 ? 0 : round(blockingSeconds / toolSeconds, 4),
+        contextFloorMin: contextFloors.length === 0 ? 0 : Math.min(...contextFloors),
+        contextFloorMax: contextFloors.length === 0 ? 0 : Math.max(...contextFloors),
+    };
+}
+
+export interface Budget {
+    baseline: {
+        calls_per_request: number;
+        mean_batch_size: number;
+        blocking_share: number;
+        context_floor_max: number;
+    };
+    empty_corpus: 'fail' | 'report';
+}
+
+export function readBudget(root = REPO_ROOT): Budget | null {
+    const p = path.join(root, BUDGET_REL);
+    if (!fs.existsSync(p)) return null;
+    return JSON.parse(fs.readFileSync(p, 'utf8')) as Budget;
+}
+
+/**
+ * Baseline comparison.
+ *
+ * `calls_per_request` is deliberately ABSENT — see the comment in the body.
+ * Direction is DOWN for `blocking_share`, and UP for
+ * `mean_batch_size` — a batch of 1.00 is the floor being fixed, so a higher
+ * number is the improvement and the ratchet must not read it as a regression.
+ * `context_floor_max` is DOWN. Getting one of these directions backwards would
+ * make the gate reward the defect, which is why they are listed rather than
+ * inferred from a shared helper.
+ */
+export function compare(t: Turnaround, b: Budget): string[] {
+    const out: string[] = [];
+    // `calls_per_request` is REPORTED, never compared. Twice measured unstable
+    // for reasons that are not regressions: it fell 81.42 -> 72.67 when the
+    // measuring session was excluded, then drifted 72.67 -> 73.73 within the
+    // same afternoon because the corpus is an MTIME WINDOW and other sessions
+    // in the same project store keep sliding into it. A ratchet on a number
+    // that moves when nothing changed teaches the reader to ignore the gate,
+    // which is the failure this repository records for gates that can only
+    // block. The three metrics below are stable across the same runs.
+    if (t.meanBatchSize < b.baseline.mean_batch_size) {
+        out.push(
+            `mean batch size ${String(t.meanBatchSize)} < baseline ${String(b.baseline.mean_batch_size)} (direction: UP — 1.00 is fully serial)`,
+        );
+    }
+    if (t.blockingShare > b.baseline.blocking_share) {
+        out.push(
+            `blocking share ${String(t.blockingShare)} > baseline ${String(b.baseline.blocking_share)} (direction: DOWN)`,
+        );
+    }
+    if (t.contextFloorMax > b.baseline.context_floor_max) {
+        out.push(
+            `context floor max ${String(t.contextFloorMax)} > baseline ${String(b.baseline.context_floor_max)} (direction: DOWN)`,
+        );
+    }
+    return out;
+}
+
+function render(t: Turnaround, store: string): string {
+    const pct = (x: number): string => `${String(Math.round(x * 1000) / 10)} %`;
+    return [
+        `probe:turnaround · ${String(t.sessions)} session(s) · ${store}`,
+        `  API calls per user request   ${String(t.callsPerRequest)}  (${String(t.apiCalls)} calls / ${String(t.userRequests)} requests)`,
+        `  mean tool-call batch size    ${String(t.meanBatchSize)}  (${String(t.toolCalls)} tool calls / ${String(t.toolUsingRequests)} tool-using requests)`,
+        `  blocking tail (>${String(BLOCKING_SECONDS)}s)        ${String(t.blockingCalls)} call(s), ${String(Math.round(t.blockingSeconds / 60))} min = ${pct(t.blockingShare)} of ${String(Math.round(t.toolSeconds / 60))} min tool time`,
+        `  first-call context floor     ${String(t.contextFloorMin)}–${String(t.contextFloorMax)} tokens`,
+        '',
+    ].join('\n');
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const arg = (flag: string, dflt: string): string => {
+        const i = argv.indexOf(flag);
+        return i >= 0 && argv[i + 1] !== undefined ? (argv[i + 1] as string) : dflt;
+    };
+    for (const a of argv) {
+        if (a.startsWith('-') && !['--store', '--limit', '--json', '--against-baseline', '--include-current', '-h', '--help'].includes(a)) {
+            if (!argv.includes('--store') && !argv.includes('--limit')) {
+                process.stderr.write(`probe_turnaround: unrecognized argument: ${a}\n`);
+                return 2;
+            }
+        }
+    }
+    if (argv.includes('-h') || argv.includes('--help')) {
+        process.stdout.write(
+            'usage: probe_turnaround [--store PATH] [--limit N] [--json] [--against-baseline] [--include-current]\n',
+        );
+        return 0;
+    }
+    const store = arg('--store', defaultStore(process.cwd()));
+    const limit = Number(arg('--limit', '10'));
+    if (!Number.isFinite(limit) || limit < 1) {
+        process.stderr.write('probe_turnaround: --limit needs a positive integer\n');
+        return 2;
+    }
+    const files = recentSessions(store, limit, argv.includes('--include-current'));
+    const t = files.length === 0 ? ZERO : measure(files);
+    const gating = argv.includes('--against-baseline');
+
+    if (argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify({ store, ...t }, null, 2)}\n`);
+    } else {
+        process.stdout.write(render(t, store));
+    }
+
+    if (!gating) {
+        if (files.length === 0) {
+            // A REPORT over an empty store is honest and exits 0; only the
+            // gating mode treats emptiness as a failure. The distinction is the
+            // whole of step 1.3.
+            process.stdout.write(
+                `probe:turnaround · no transcript store at ${store} — nothing measured (report mode; ` +
+                    'use --against-baseline for the fail-closed form)\n',
+            );
+        }
+        return 0;
+    }
+
+    const budget = readBudget();
+    if (budget === null) {
+        process.stderr.write(`❌  probe_turnaround: ${BUDGET_REL} is missing — nothing to compare against.\n`);
+        return 1;
+    }
+    if (files.length === 0) {
+        if (budget.empty_corpus === 'fail') {
+            process.stderr.write(
+                `❌  probe_turnaround: empty corpus at ${store}. A baseline comparison over zero ` +
+                    'sessions certifies nothing, and the config records `empty_corpus: "fail"` so it ' +
+                    'refuses rather than reporting green.\n',
+            );
+            return 1;
+        }
+        process.stdout.write('probe:turnaround · empty corpus, `empty_corpus: "report"` — no verdict.\n');
+        return 0;
+    }
+    const regressions = compare(t, budget);
+    if (regressions.length > 0) {
+        process.stderr.write('❌  probe_turnaround: regression against the recorded baseline:\n');
+        for (const r of regressions) process.stderr.write(`    ${r}\n`);
+        process.stderr.write(
+            `    → raising a baseline in ${BUDGET_REL} needs the reason as a sentence in the same commit.\n`,
+        );
+        return 1;
+    }
+    process.stdout.write('✅  probe_turnaround: within the recorded baseline on all four metrics.\n');
+    return 0;
+}
+
+if (process.argv[1] !== undefined && process.argv[1].includes('probe_turnaround')) {
+    process.exit(main());
+}

package/src/scripts/probe_unblocked_ask.ts

@@ -0,0 +1,279 @@
+#!/usr/bin/env tsx
+/**
+ * The unblocked-ask rate — the class `user-interaction` measured and then had
+ * no instrument for.
+ *
+ * ## Why this one, and not one of the other 55
+ *
+ * `road-to-undeclared-obligation-disposition` Phase 2.1 ranks the
+ * `cheaply-probeable` bucket by MEASURED failure rather than by feel, and the
+ * ranking is lopsided: of 56 rules in that bucket, exactly **one** carries a
+ * cited measurement of its own failure. `user-interaction.md:75` records a
+ * 30-session conformance audit in which **every** malformed ask was a one-line
+ * parenthetical or a trailing free-text offer, and states that **no gate ships**
+ * for that class because `check_reply_consistency` inspects numbered-option
+ * blocks — "exactly the surface that did not fail".
+ *
+ * That is the whole case for building this and not a fourth probe. Phase 2.3
+ * caps the roadmap at one.
+ *
+ * ## What is counted
+ *
+ * A **hand-back** assistant turn — one immediately followed by a genuine user
+ * turn, i.e. where the agent actually stopped — that HANDS A DECISION and
+ * carries **no** numbered-options block. The rule's own § "The trigger is a
+ * decision, not a format" says the obligation fires on handing a decision in any
+ * form, so a trailing offer is an ask and owes a recommendation line.
+ *
+ * Of those, an ask is **malformed** when no recommendation line follows it.
+ *
+ * ## Honest bounds, and they are wide
+ *
+ * 1. **"Hands a decision" is a heuristic.** It matches offer shapes — *"soll ich
+ *    …?"*, *"shall I …?"*, *"sag Bescheid, wenn …"*, *"willst du …?"* — anchored
+ *    in the closing lines. A genuine clarifying question is deliberately NOT
+ *    excluded, because `user-interaction` treats a bare yes/no as an ask too.
+ *    Some rhetorical questions will be counted. The rate is therefore a
+ *    CEILING for malformed asks of this class, not a point estimate.
+ * 2. **Turns WITH a numbered block are excluded**, not judged. That surface
+ *    already has `check_reply_consistency`; measuring it here would double-count
+ *    a covered class and hide the uncovered one.
+ * 3. **A recommendation line is matched on the label**, `Recommendation:` or
+ *    `Empfehlung:` (with or without emphasis). A recommendation phrased without
+ *    the label reads as malformed here. The rule requires the label — a
+ *    wrong-language label is explicitly "no recommendation" — so this is the
+ *    rule's own bar, but it is a bar on FORM.
+ *
+ * Both edges are printed. A reader who cannot see the bracket cannot judge the
+ * number.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/probe_unblocked_ask [--limit N] [--store PATH] [--json]
+ *   ./scripts-run src/scripts/probe_unblocked_ask --self-test
+ *
+ * Exit codes: 0 always — a measurement, not a gate. `--self-test` exits 1 when
+ * the detector fails to fire on its fixtures.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { defaultStore, HARNESS_TEXT, isInjectedBody } from './conformance_scan.js';
+import { isSyntheticPrompt } from './_lib/prompt_shape.js';
+
+/** A numbered-options block — the surface `check_reply_consistency` already reads. */
+export const NUMBERED_BLOCK = /^\s{0,3}(\d+)[.)]\s+\S/m;
+
+/** The recommendation line, matched on its label. Either language. */
+export const RECOMMENDATION = /^\s{0,3}\**\s*(Recommendation|Empfehlung)\s*:?\**/im;
+
+/**
+ * Offer shapes that hand a decision without a block. Every one of these is a
+ * shape the 2026-08-06 audit found in a REAL malformed ask.
+ */
+export const OFFER_SHAPES: readonly RegExp[] = [
+    /\bsoll(en)? ich\b[^.!?]{0,120}\?/i,
+    /\bwillst du\b[^.!?]{0,120}\?/i,
+    /\bm(ö|oe)chtest du\b[^.!?]{0,120}\?/i,
+    /\bsag (mir )?bescheid,? (wenn|ob|falls)\b/i,
+    /\bwenn du (willst|m(ö|oe)chtest),? (dann )?(mache|kann|nehme|ziehe)\b/i,
+    /\bshall i\b[^.!?]{0,120}\?/i,
+    /\bshould i\b[^.!?]{0,120}\?/i,
+    /\bdo you want me to\b[^.!?]{0,120}\?/i,
+    /\bwould you like me to\b[^.!?]{0,120}\?/i,
+    /\blet me know (if|whether)\b/i,
+];
+
+interface Turn {
+    role: 'user' | 'assistant';
+    text: string;
+    at: string;
+}
+
+function turns(lines: string[]): Turn[] {
+    const out: Turn[] = [];
+    for (const line of lines) {
+        if (!line.trim()) continue;
+        let e: Record<string, unknown>;
+        try {
+            e = JSON.parse(line) as Record<string, unknown>;
+        } catch {
+            continue;
+        }
+        if (e['isSidechain'] === true) continue;
+        if (e['type'] === 'user' && e['toolUseResult'] !== undefined) continue;
+        if (e['isCompactSummary'] === true) continue;
+        const msg = e['message'] as { role?: string; content?: unknown } | undefined;
+        const role = msg?.role;
+        if (role !== 'user' && role !== 'assistant') continue;
+        const c = msg?.content;
+        const text =
+            typeof c === 'string'
+                ? c
+                : Array.isArray(c)
+                  ? c
+                        .filter((b: { type?: string }) => b?.type === 'text')
+                        .map((b: { text?: string }) => b.text ?? '')
+                        .join('\n')
+                  : '';
+        if (!text.trim()) continue;
+        if (role === 'assistant' && HARNESS_TEXT.test(text.trim())) continue;
+        if (role === 'user' && (isSyntheticPrompt(text) || isInjectedBody(text))) continue;
+        out.push({ role, text, at: String(e['timestamp'] ?? '') });
+    }
+    return out;
+}
+
+export interface AskVerdict {
+    /** The turn hands a decision with no numbered block. */
+    unblockedAsk: boolean;
+    /** …and carries no recommendation label. */
+    malformed: boolean;
+}
+
+/** Classify one assistant hand-back's closing lines. */
+export function classifyTail(tail: string): AskVerdict {
+    if (NUMBERED_BLOCK.test(tail)) return { unblockedAsk: false, malformed: false };
+    const offers = OFFER_SHAPES.some((re) => re.test(tail));
+    if (!offers) return { unblockedAsk: false, malformed: false };
+    return { unblockedAsk: true, malformed: !RECOMMENDATION.test(tail) };
+}
+
+export interface Result {
+    handbacks: number;
+    withBlock: number;
+    unblockedAsks: number;
+    malformed: number;
+    samples: { session: string; at: string; span: string }[];
+}
+
+export function measure(store: string, limit: number): Result {
+    const r: Result = { handbacks: 0, withBlock: 0, unblockedAsks: 0, malformed: 0, samples: [] };
+    let files: string[];
+    try {
+        files = fs.readdirSync(store).filter((f) => f.endsWith('.jsonl'));
+    } catch {
+        return r;
+    }
+    const ordered = files
+        .map((f) => ({ f, m: fs.statSync(path.join(store, f)).mtimeMs }))
+        .sort((a, b) => b.m - a.m)
+        .slice(0, limit)
+        .map((x) => x.f);
+
+    for (const f of ordered) {
+        const session = f.replace(/\.jsonl$/, '').slice(0, 8);
+        const ts = turns(fs.readFileSync(path.join(store, f), 'utf8').split('\n'));
+        for (let i = 0; i < ts.length; i += 1) {
+            const t = ts[i] as Turn;
+            if (t.role !== 'assistant') continue;
+            const next = ts[i + 1];
+            if (next !== undefined && next.role !== 'user') continue;
+            r.handbacks += 1;
+            // Closing lines only: an offer buried mid-reply is not the hand-back.
+            const tail = t.text.trimEnd().split('\n').slice(-8).join('\n');
+            if (NUMBERED_BLOCK.test(tail)) {
+                r.withBlock += 1;
+                continue;
+            }
+            const v = classifyTail(tail);
+            if (!v.unblockedAsk) continue;
+            r.unblockedAsks += 1;
+            if (v.malformed) {
+                r.malformed += 1;
+                if (r.samples.length < 5) {
+                    const hit = OFFER_SHAPES.find((re) => re.test(tail));
+                    r.samples.push({
+                        session,
+                        at: t.at,
+                        span: (tail.match(hit as RegExp)?.[0] ?? '').slice(0, 110),
+                    });
+                }
+            }
+        }
+    }
+    return r;
+}
+
+/**
+ * Prove the detector fires, and prove it stays silent where it must.
+ *
+ * An instrument never seen fire has unknown sensitivity — and one that fires on
+ * everything measures nothing, which is why the negative cases are here too.
+ */
+export function selfTest(): number {
+    const cases: Array<[string, string, boolean, boolean]> = [
+        ['a trailing German offer with no recommendation', 'Fertig.\n\nSag Bescheid, wenn ich die drei Zeilen mitnehmen soll.', true, true],
+        ['a bare yes/no offer', 'Der Branch ist grün.\n\nSoll ich das so umsetzen?', true, true],
+        ['an English trailing offer', 'Done.\n\nLet me know if you want the second half too.', true, true],
+        ['an offer WITH a recommendation label', 'Soll ich das so umsetzen?\n\n**Empfehlung:** ja, es ist reversibel.', true, false],
+        ['a numbered block is excluded — another gate reads it', '1. do it\n2. skip it\n\nRecommendation: 1', false, false],
+        ['an ordinary statement hands nothing', 'Fixed the schema lint; force-pushed b17c4ef8.', false, false],
+        ['a question about the code is not an offer to act', 'Why does this function take a callback?', false, false],
+    ];
+    let failed = 0;
+    for (const [name, tail, wantAsk, wantMalformed] of cases) {
+        const v = classifyTail(tail);
+        const ok = v.unblockedAsk === wantAsk && v.malformed === wantMalformed;
+        process.stdout.write(
+            `${ok ? '✅' : '❌'}  ${name} — ask=${String(v.unblockedAsk)} malformed=${String(v.malformed)}` +
+                (ok ? '\n' : ` (wanted ask=${String(wantAsk)} malformed=${String(wantMalformed)})\n`),
+        );
+        if (!ok) failed += 1;
+    }
+    const positives = cases.filter((c) => c[3]).length;
+    if (positives < 3) {
+        process.stderr.write('❌  probe_unblocked_ask --self-test: fewer than 3 positive cases — a truncated suite must fail.\n');
+        return 1;
+    }
+    process.stdout.write(
+        `\nprobe_unblocked_ask --self-test: ${String(cases.length - failed)}/${String(cases.length)} case(s) behaved ` +
+            `(${String(positives)} positive, ${String(cases.length - positives)} negative)\n`,
+    );
+    return failed > 0 ? 1 : 0;
+}
+
+export function main(argv: string[]): number {
+    let limit = 60;
+    let storeArg: string | null = null;
+    let json = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i] as string;
+        if (a === '--limit') limit = Number(argv[++i]);
+        else if (a === '--store') storeArg = String(argv[++i]);
+        else if (a === '--json') json = true;
+        // --self-test runs BEFORE the store is resolved: the fixtures are
+        // in-process, and resolving a transcript store that may not exist here
+        // would make the sensitivity proof depend on the host having one.
+        else if (a === '--self-test') return selfTest();
+        else {
+            process.stderr.write(`probe_unblocked_ask: unrecognized argument: ${a}\n`);
+            return 0;
+        }
+    }
+    const store = storeArg ?? defaultStore(process.cwd());
+    const r = measure(store, limit);
+    if (json) {
+        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+        return 0;
+    }
+    const pct = (n: number, d: number): string => (d === 0 ? 'n/a' : `${((100 * n) / d).toFixed(1)}%`);
+    process.stdout.write(
+        `probe_unblocked_ask · ${String(limit)} most recent session(s) under ${store}\n` +
+            `  hand-back turns          ${String(r.handbacks)}\n` +
+            `  …with a numbered block   ${String(r.withBlock)}  (excluded — check_reply_consistency reads that surface)\n` +
+            `  …unblocked asks          ${String(r.unblockedAsks)}  ${pct(r.unblockedAsks, r.handbacks)} of hand-backs\n` +
+            `  …of those, malformed     ${String(r.malformed)}  ${pct(r.malformed, r.unblockedAsks)} of unblocked asks\n` +
+            '\n  CEILING, not a point estimate: "hands a decision" is a heuristic and a\n' +
+            '  rhetorical question can match it. A recommendation is matched on its LABEL,\n' +
+            '  which is the rule\'s own bar but a bar on form.\n',
+    );
+    for (const s of r.samples) {
+        process.stdout.write(`    · ${s.session} ${s.at}: ${s.span}\n`);
+    }
+    return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exit(main(process.argv.slice(2)));
+}