@event4u/agent-config 7.2.0 → 7.4.0

package/src/scripts/_cli/cmd_analyze_session.ts

@@ -0,0 +1,347 @@
+#!/usr/bin/env tsx
+/**
+ * `agent-config analyze-session` — post-session report from on-disk runtime
+ * state.
+ *
+ * Read-only diagnostic. No daemon, no network, no model calls. It reads two
+ * real data sources the work-engine / context-hygiene hook leave behind and
+ * prints a deterministic Markdown report:
+ *
+ *   1. the work_engine state envelope `.work-state.json` (version 1) — loaded
+ *      via `load_state` from `explain_last/state_loader.ts`. Fields read:
+ *        - `changes`  — files touched (array of {kind, stack, file, summary}).
+ *        - `outcomes` — directive → "success" / "blocked" / … .
+ *        - `halts`    — array of recorded halts.
+ *   2. `agents/runtime/state/context-hygiene.json` — fields read:
+ *        - `tool_calls`           (int)
+ *        - `consecutive_same_tool`(int)
+ *        - `loop_detected`        (bool)
+ *
+ * There is NO general token/cost data source in this package (only
+ * video-specific telemetry), so the report deliberately does NOT report
+ * tokens or cost — it prints a single honest "not tracked" line instead.
+ *
+ * Exit codes (mirroring `cmd_explain`'s `last` subject):
+ *   0  report rendered (even when a source file is absent — graceful note).
+ *   1  the work-state file is missing or unreadable.
+ *   2  invocation error (bad project root, bad --state-file path).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { ProjectRootError, resolve_project_root } from '../_lib/agent_settings.js';
+import { StateLoadError, load_state } from './explain_last/state_loader.js';
+
+type Dict = Record<string, unknown>;
+
+const _HERE = fileURLToPath(import.meta.url);
+
+const CONTEXT_HYGIENE_RELATIVE = path.join(
+    'agents',
+    'runtime',
+    'state',
+    'context-hygiene.json',
+);
+
+/** Python `raise SystemExit(code)` analogue — propagates an explicit code. */
+class SystemExitError extends Error {
+    constructor(public readonly code: number) {
+        super(`system-exit-${code}`);
+    }
+}
+
+/** argparse-style usage / help exit (code 2 / 0). Caught at the CLI entry. */
+class ArgparseExit extends Error {
+    constructor(public readonly code: number) {
+        super(`argparse-exit-${code}`);
+    }
+}
+
+function eprint(line = ''): void {
+    process.stderr.write(line + '\n');
+}
+
+function isPlainObject(value: unknown): value is Dict {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function _resolve_root(arg: string | null): string {
+    try {
+        const [root] = resolve_project_root(arg, { cwd: process.cwd() });
+        return root;
+    } catch (exc) {
+        if (exc instanceof ProjectRootError) {
+            eprint(`❌  analyze-session: ${exc.message}`);
+            throw new SystemExitError(2);
+        }
+        throw exc;
+    }
+}
+
+/** `Path.relative_to(base)` — returns null when `p` is not under `base`. */
+function relativeToOrNull(p: string, base: string): string | null {
+    const rel = path.relative(base, p);
+    if (rel === '') return rel;
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        return null;
+    }
+    return rel;
+}
+
+/**
+ * Read the context-hygiene snapshot. Returns the parsed object, or `null`
+ * when the file is absent / unreadable / not an object — the caller renders
+ * a graceful "not available" note rather than failing the whole report.
+ */
+function _load_context_hygiene(project_root: string): Dict | null {
+    const p = path.join(project_root, CONTEXT_HYGIENE_RELATIVE);
+    if (!fs.existsSync(p)) {
+        return null;
+    }
+    let text: string;
+    try {
+        text = fs.readFileSync(p, 'utf-8');
+    } catch {
+        return null;
+    }
+    let payload: unknown;
+    try {
+        payload = JSON.parse(text);
+    } catch {
+        return null;
+    }
+    return isPlainObject(payload) ? payload : null;
+}
+
+/** Render `value` as an integer string, or `'?'` when not a finite number. */
+function intOrUnknown(value: unknown): string {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return String(Math.trunc(value));
+    }
+    return '?';
+}
+
+/**
+ * Build the deterministic Markdown report from already-loaded state.
+ *
+ * Pure function — no I/O, no clock, no environment. Both inputs come from the
+ * caller so the report is unit-testable in isolation.
+ *
+ * @param state    the parsed `.work-state.json` (version 1).
+ * @param hygiene  the parsed context-hygiene snapshot, or `null` when absent.
+ */
+export function render_report(state: Dict, hygiene: Dict | null): string {
+    const lines: string[] = [];
+    lines.push('# Session analysis');
+    lines.push('');
+
+    // --- Files touched (from state.changes) ---
+    const changes = Array.isArray(state['changes']) ? (state['changes'] as unknown[]) : [];
+    lines.push(`## Files touched (${changes.length})`);
+    lines.push('');
+    if (changes.length === 0) {
+        lines.push('_No files recorded as changed._');
+    } else {
+        for (const change of changes) {
+            if (!isPlainObject(change)) continue;
+            const file = typeof change['file'] === 'string' ? change['file'] : '(unknown file)';
+            const summary =
+                typeof change['summary'] === 'string' && change['summary'].length > 0
+                    ? ` — ${change['summary']}`
+                    : '';
+            lines.push(`- \`${file}\`${summary}`);
+        }
+    }
+    lines.push('');
+
+    // --- Per-directive outcomes (from state.outcomes) ---
+    const outcomes = isPlainObject(state['outcomes']) ? (state['outcomes'] as Dict) : {};
+    const directives = Object.keys(outcomes).sort(); // deterministic order
+    const blocked = directives.filter((d) => outcomes[d] === 'blocked');
+    lines.push(`## Outcomes (${directives.length})`);
+    lines.push('');
+    if (directives.length === 0) {
+        lines.push('_No directive outcomes recorded._');
+    } else {
+        for (const directive of directives) {
+            const result = outcomes[directive];
+            const marker = result === 'blocked' ? '⚠️ ' : '';
+            lines.push(`- ${marker}\`${directive}\`: ${String(result)}`);
+        }
+    }
+    lines.push('');
+    if (blocked.length > 0) {
+        lines.push(`**Blocked directives (${blocked.length}):** ${blocked.join(', ')}`);
+        lines.push('');
+    }
+
+    // --- Halts (from state.halts) ---
+    const halts = Array.isArray(state['halts']) ? (state['halts'] as unknown[]) : [];
+    lines.push(`## Halts (${halts.length})`);
+    lines.push('');
+    if (halts.length === 0) {
+        lines.push('_No halts recorded._');
+    } else {
+        lines.push(`This session recorded ${halts.length} halt(s).`);
+    }
+    lines.push('');
+
+    // --- Tool activity (from context-hygiene) ---
+    lines.push('## Tool activity');
+    lines.push('');
+    if (hygiene === null) {
+        lines.push('_Context-hygiene snapshot not available._');
+    } else {
+        const toolCalls = intOrUnknown(hygiene['tool_calls']);
+        const consecutive = intOrUnknown(hygiene['consecutive_same_tool']);
+        const loop = hygiene['loop_detected'] === true;
+        lines.push(`- Tool calls: ${toolCalls}`);
+        lines.push(`- Consecutive same-tool calls: ${consecutive}`);
+        lines.push(`- Loop detected: ${loop ? 'yes' : 'no'}`);
+    }
+    lines.push('');
+
+    // --- Honest token/cost note (no per-session source in this package) ---
+    lines.push('## Token / cost');
+    lines.push('');
+    lines.push('Token/cost: not tracked (no per-session source).');
+    lines.push('');
+
+    return lines.join('\n');
+}
+
+function _analyze_session(project_root: string, state_file: string | null): number {
+    const target_state = state_file || path.join(project_root, '.work-state.json');
+    let state: Dict;
+    try {
+        state = load_state(target_state) as Dict;
+    } catch (exc) {
+        if (exc instanceof StateLoadError) {
+            // Never print absolute paths in errors (username leakage).
+            const rel = relativeToOrNull(target_state, project_root);
+            const shown = rel !== null ? rel : path.basename(target_state);
+            const msg = exc.message.split(target_state).join(shown);
+            eprint(`❌  analyze-session: ${msg}`);
+            return exc.exitCode;
+        }
+        throw exc;
+    }
+    const hygiene = _load_context_hygiene(project_root);
+    process.stdout.write(render_report(state, hygiene));
+    return 0;
+}
+
+interface Opts {
+    project: string | null;
+    state_file: string | null;
+}
+
+const PROG = 'agent-config analyze-session';
+const USAGE = `usage: ${PROG} [-h] [--project PROJECT] [--state-file STATE_FILE]\n`;
+
+const _HELP = `\
+usage: ${PROG} [--project PATH] [--state-file PATH]
+
+Print a post-session report from on-disk runtime state. Read-only;
+no daemon, no network, no model calls.
+
+Sources read:
+  .work-state.json (version 1)
+    · changes  — files touched
+    · outcomes — per-directive success / blocked
+    · halts    — recorded halts
+  agents/runtime/state/context-hygiene.json
+    · tool_calls · consecutive_same_tool · loop_detected
+
+Token/cost is NOT reported — this package has no per-session token
+source (only video-specific telemetry).
+
+options:
+  --project PATH       project root (defaults to anchor walk from cwd)
+  --state-file PATH    .work-state.json path (default <root>/.work-state.json)
+  -h, --help           show this help and exit
+
+exit codes:
+  0  report rendered (a missing source file is noted, not fatal)
+  1  no recent run found (state file missing or unreadable)
+  2  invocation error (bad project root, bad --state-file path)
+`;
+
+function _argError(msg: string): never {
+    process.stderr.write(USAGE);
+    process.stderr.write(`${PROG}: error: ${msg}\n`);
+    throw new ArgparseExit(2);
+}
+
+function _parse(argv: string[]): Opts {
+    const opts: Opts = { project: null, state_file: null };
+    let i = 0;
+    while (i < argv.length) {
+        const a = argv[i] as string;
+        if (a === '-h' || a === '--help') {
+            process.stdout.write(_HELP);
+            throw new ArgparseExit(0);
+        }
+        const eq = a.startsWith('--') ? a.indexOf('=') : -1;
+        const flag = eq >= 0 ? a.slice(0, eq) : a;
+        const inlineVal = eq >= 0 ? a.slice(eq + 1) : null;
+        if (flag === '--project' || flag === '--state-file') {
+            const dest = flag === '--project' ? 'project' : 'state_file';
+            let value: string;
+            if (inlineVal !== null) {
+                value = inlineVal;
+            } else {
+                if (i + 1 >= argv.length) {
+                    _argError(`argument ${flag}: expected one argument`);
+                }
+                value = argv[i + 1] as string;
+                i += 1;
+            }
+            opts[dest] = value;
+            i += 1;
+            continue;
+        }
+        _argError(`unrecognized arguments: ${a}`);
+    }
+    return opts;
+}
+
+export function main(argv: string[] | null = null): number {
+    const argv_list = argv !== null ? Array.from(argv) : process.argv.slice(2);
+    const opts = _parse(argv_list);
+    let project_root: string;
+    try {
+        project_root = _resolve_root(opts.project);
+    } catch (exc) {
+        if (exc instanceof SystemExitError) {
+            return exc.code;
+        }
+        throw exc;
+    }
+    return _analyze_session(project_root, opts.state_file);
+}
+
+// --- CLI entry ---
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry || process.argv[1] === _HERE) {
+    try {
+        process.exitCode = main(process.argv.slice(2));
+    } catch (e) {
+        if (e instanceof ArgparseExit) {
+            process.exitCode = e.code;
+        } else if (e instanceof SystemExitError) {
+            process.exitCode = e.code;
+        } else {
+            throw e;
+        }
+    }
+}
+
+export { _parse, _resolve_root, _load_context_hygiene, _analyze_session, ArgparseExit, SystemExitError };
+export type { Opts };

package/src/scripts/_dispatch.bash

@@ -933,6 +933,13 @@ cmd_explain() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_explain.ts" "$@"
 }
 
+# `agent-config analyze-session` — read-only post-session report from on-disk
+# runtime state (.work-state.json + context-hygiene.json). No daemon, no
+# network, no model calls. See scripts/_cli/cmd_analyze_session.ts.
+cmd_analyze_session() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_analyze_session.ts" "$@"
+}
+
 main() {
   local cmd="${1-}"
   [[ $# -gt 0 ]] && shift || true
@@ -991,6 +998,7 @@ main() {
     doctor)                  cmd_doctor "$@" ;;
     versions)                cmd_versions "$@" ;;
     explain)                 cmd_explain "$@" ;;
+    analyze-session)         cmd_analyze_session "$@" ;;
     help|--help|-h|"")
       # Optional `--tier=0|1|all` filter (default 0).
       local tier_arg="0"

package/src/scripts/_lib/eval_discrimination.ts

@@ -0,0 +1,95 @@
+/**
+ * eval_discrimination — the "falsifier of the falsifier" for the cross-model
+ * parity smoke (roadmap `road-to-operator-runtime-harvest`, T-003).
+ *
+ * A green parity result is trustworthy only if the eval *can* go red — and not
+ * just on a gross violation, but on a subtle, just-over-threshold one. A gross
+ * negative control proves "the harness can fail"; the SUBTLE control proves it
+ * is sensitive enough that an "all hosts pass" reading (outcome (a) in T-006)
+ * is not the underpowered-null trap wearing a green check. `discrimination_ok`
+ * is therefore gated on the SUBTLE control being caught — a gross-only control
+ * set is explicitly insufficient.
+ *
+ * Pure, dependency-free, host-agnostic: the smoke computes each control's
+ * `caught` from its assertion results (via `controlCaughtFromAssertions`) and
+ * passes the set here. No vendor calls happen in this module.
+ */
+
+export type ControlSeverity = 'gross' | 'subtle';
+
+export interface NegativeControl {
+    /** Stable id of the planted-violation control scenario. */
+    id: string;
+    /** How blatant the planted RDP violation is. */
+    severity: ControlSeverity;
+    /**
+     * Did the harness flag this control (grade it RED)? A control is "caught"
+     * when NOT all of its assertions passed — i.e. the harness correctly
+     * detected the planted violation. Caught is the *desired* outcome.
+     */
+    caught: boolean;
+}
+
+export interface DiscriminationResult {
+    /**
+     * True only when the harness caught the SUBTLE control (and a gross one
+     * exists and was also caught). This is the strict gate the parity smoke
+     * checks before trusting an "all hosts pass" reading.
+     */
+    discrimination_ok: boolean;
+    gross_caught: boolean;
+    subtle_caught: boolean;
+    /** Human-readable reason, surfaced in the smoke's emitted summary. */
+    reason: string;
+}
+
+/**
+ * A control is "caught" iff at least one of its assertions explicitly failed.
+ * `pass: null` (e.g. an ungraded `rubric` assertion deferred to a sub-agent
+ * grader) is NOT a fail — an un-graded assertion cannot count as catching a
+ * violation, so only explicit `false` qualifies.
+ */
+export function controlCaughtFromAssertions(
+    assertionResults: ReadonlyArray<{ pass: boolean | null }>,
+): boolean {
+    return assertionResults.some((r) => r.pass === false);
+}
+
+/**
+ * Decide whether the eval discriminates well enough to trust a green reading.
+ * Requires at least one `gross` AND one `subtle` control; gates on the subtle.
+ */
+export function computeDiscrimination(
+    controls: ReadonlyArray<NegativeControl>,
+): DiscriminationResult {
+    const gross = controls.filter((c) => c.severity === 'gross');
+    const subtle = controls.filter((c) => c.severity === 'subtle');
+
+    const gross_caught = gross.length > 0 && gross.every((c) => c.caught);
+    const subtle_caught = subtle.length > 0 && subtle.every((c) => c.caught);
+
+    let discrimination_ok = false;
+    let reason: string;
+
+    if (gross.length === 0 || subtle.length === 0) {
+        reason =
+            'GRADED control set incomplete: need at least one `gross` and one `subtle` ' +
+            'negative control. A single severity cannot establish sensitivity — outcome (a) stays invalid.';
+    } else if (!gross_caught) {
+        reason =
+            'Harness is blind to a GROSS violation — it cannot fail at all. ' +
+            'Any "all hosts pass" reading is meaningless.';
+    } else if (!subtle_caught) {
+        reason =
+            'Underpowered: the gross control was caught but the SUBTLE one slipped through. ' +
+            'This is the uninformative-null trap with a green check in front — outcome (a) is ' +
+            'INVALID until the subtle control is caught.';
+    } else {
+        discrimination_ok = true;
+        reason =
+            'Both gross and subtle negative controls were caught — the eval discriminates; ' +
+            'an "all hosts pass" reading is trustworthy.';
+    }
+
+    return { discrimination_ok, gross_caught, subtle_caught, reason };
+}

package/src/scripts/_lib/token_count.ts

@@ -1,41 +1,80 @@
 /**
- * Real-tokenizer counting for the budget tooling (roadmap 0B.1).
+ * Real-tokenizer counting for the budget tooling
+ * (roadmap 0B.1 → token-saving Phase 0, "real tokenizer into the bench path").
  *
- * TypeScript twin of `src/scripts/_lib/token_count.py` (ADR-200 —
- * Python→TS migration, Phase 2 / Wave 1). Public API mirrors the
- * Python module exactly (snake_case kept deliberately).
+ * `char != token`. Every budget in this suite is historically in characters;
+ * this helper reports a token count *alongside* chars so chars stay the cheap
+ * proxy and tokens become the truth where a real tokenizer is available.
  *
- * `char != token`. Every budget in this suite is historically in
- * characters; this helper adds a token count *alongside* chars so chars
- * stay the cheap proxy and tokens become the truth where a real
- * tokenizer is available.
+ * Design — optional dependency, graceful proxy fallback, **synchronous** API:
  *
- * Design — no silent installs, no mandatory network:
+ * - **GPT** — uses `js-tiktoken` (encoding `cl100k_base`) when the dependency
+ *   is present, producing EXACT BPE counts flagged `exact: true`. `js-tiktoken`
+ *   is a build/measurement-time **devDependency** (consumed by the bench /
+ *   audit tooling, never shipped to a consumer runtime). When it is absent —
+ *   e.g. a consumer that installed without devDependencies — the module falls
+ *   back to the documented `chars / 4` proxy flagged `exact: false`. The
+ *   optional load is a synchronous `createRequire(...)` inside a try/catch so
+ *   the public `measure()` / `gpt_tokens()` API stays synchronous and never
+ *   hard-fails on a missing dependency (no mandatory install, no network).
+ * - **Claude** — no offline Claude tokenizer exists; documented `chars / 3.6`
+ *   proxy, always `exact: false`. (Anthropic's exact count is API-only.)
  *
- * - **GPT** — the Python original uses `tiktoken` when installed; no
- *   tokenizer dependency ships with the TS twin, so the documented
- *   `chars / 4` proxy applies, flagged `exact: false`
- *   (`TIKTOKEN_AVAILABLE` is always `false` here — matching the
- *   Python module's behaviour when tiktoken is absent).
- * - **Claude** — no offline tokenizer; documented `chars / 3.6` proxy
- *   flagged `exact: false`.
+ * Both proxies are intentionally conservative ratios drawn from English-prose +
+ * markdown samples; they are estimates, never gates.
  *
- * Both proxies are intentionally conservative ratios drawn from
- * English-prose + markdown samples; they are estimates, never gates.
+ * The `*_proxy` helpers (`gpt_tokens_proxy`, `measure_proxy`,
+ * `method_note_proxy`) expose the fallback math directly — they are used by the
+ * fallback regression guard in the test suite and by any report that wants to
+ * record both the exact and the proxy count to flag the delta.
  *
- * Parity notes: "chars" counts Unicode code points (Python `len(str)`),
- * not UTF-16 units; rounding is banker's rounding (Python `round()`).
+ * Parity notes: "chars" counts Unicode code points (`len(str)` parity), not
+ * UTF-16 units; proxy rounding is banker's rounding.
  */
 
+import { createRequire } from "node:module";
+
 // Proxy ratios (chars per token) for the no-tokenizer fallback. Tuned for
 // English markdown rule/skill prose; deliberately conservative.
 const _GPT_CHARS_PER_TOKEN = 4.0;
 const _CLAUDE_CHARS_PER_TOKEN = 3.6;
 
-const _TIKTOKEN_ENCODING = "o200k_base"; // GPT-4o / GPT-4.1 family.
+// Roadmap (token-saving Phase 0) mandates the `cl100k_base` encoding. The
+// dependency also bundles `o200k_base` (GPT-4o / GPT-4.1 family); switching the
+// GPT count basis is a one-line change to this constant. The exact-vs-proxy
+// delta is recorded in every report via `method_note()`.
+const _TIKTOKEN_ENCODING = "cl100k_base";
+
+/** Minimal structural type for the js-tiktoken encoder we rely on. */
+interface _Encoder {
+  encode(text: string): number[];
+}
+
+/**
+ * Load the optional `js-tiktoken` encoder synchronously, returning `null` when
+ * the dependency is absent or fails to initialise (graceful proxy fallback).
+ * `createRequire` resolves the CJS build so the call stays synchronous even
+ * though this module is ESM.
+ */
+function _loadEncoder(): _Encoder | null {
+  try {
+    const require = createRequire(import.meta.url);
+    const mod = require("js-tiktoken") as {
+      getEncoding(name: string): _Encoder;
+    };
+    return mod.getEncoding(_TIKTOKEN_ENCODING);
+  } catch {
+    return null;
+  }
+}
+
+// Resolved once at module load. js-tiktoken's `getEncoding` is synchronous with
+// bundled rank tables, so eager init is cheap and keeps `TIKTOKEN_AVAILABLE` a
+// plain const (the historical API shape).
+const _ENCODER: _Encoder | null = _loadEncoder();
 
-// No tiktoken port ships with the TS twin — always the proxy path.
-export const TIKTOKEN_AVAILABLE = false;
+/** True when the real tokenizer is available (exact GPT counts), else proxy. */
+export const TIKTOKEN_AVAILABLE = _ENCODER !== null;
 
 /** A single token measurement and whether it is exact or a proxy. */
 export class TokenCount {
@@ -49,7 +88,7 @@ export class TokenCount {
   }
 }
 
-/** Count Unicode code points — Python `len(str)` parity. */
+/** Count Unicode code points — `len(str)` parity. */
 function _len(text: string): number {
   let count = 0;
   // for..of iterates code points, so astral chars count once.
@@ -57,7 +96,7 @@ function _len(text: string): number {
   return count;
 }
 
-/** Python `round()` — round half to even (banker's rounding). */
+/** Banker's rounding (round half to even) — proxy-path parity. */
 function _python_round(x: number): number {
   const floor = Math.floor(x);
   const diff = x - floor;
@@ -66,17 +105,31 @@ function _python_round(x: number): number {
   return floor % 2 === 0 ? floor : floor + 1;
 }
 
-/** Render a float like Python's f-string (4.0 → "4.0", 3.6 → "3.6"). */
+/** Render a float like a Python f-string (4.0 → "4.0", 3.6 → "3.6"). */
 function _py_float_repr(x: number): string {
   return Number.isInteger(x) ? `${x}.0` : `${x}`;
 }
 
-/** GPT token count — char proxy (tiktoken unavailable in the TS twin). */
+/**
+ * GPT token count — EXACT via js-tiktoken (`cl100k_base`) when available,
+ * otherwise the documented `chars / 4` proxy.
+ */
 export function gpt_tokens(text: string): TokenCount {
+  if (_ENCODER !== null) {
+    return new TokenCount(_ENCODER.encode(text).length, true);
+  }
+  return gpt_tokens_proxy(text);
+}
+
+/**
+ * GPT proxy count (`chars / 4`, banker's rounding) — the fallback path,
+ * exposed directly for the fallback regression guard and delta reporting.
+ */
+export function gpt_tokens_proxy(text: string): TokenCount {
   return new TokenCount(_python_round(_len(text) / _GPT_CHARS_PER_TOKEN), false);
 }
 
-/** Claude token count — documented offline proxy (no local tokenizer). */
+/** Claude token count — documented offline proxy (no local Claude tokenizer). */
 export function claude_tokens(text: string): TokenCount {
   return new TokenCount(
     _python_round(_len(text) / _CLAUDE_CHARS_PER_TOKEN),
@@ -95,9 +148,9 @@ export interface Measure {
 /**
  * Return chars + per-model token counts for one text blob.
  *
- * Keys: chars, tokens_gpt, tokens_gpt_exact, tokens_claude,
- * tokens_claude_exact. The `*_exact` booleans tell a report consumer
- * whether the number is a real tokenizer count or a proxy estimate.
+ * `tokens_gpt` is exact (js-tiktoken) when available; `tokens_gpt_exact` tells
+ * the report consumer which path produced it. `tokens_claude` is always the
+ * proxy (no offline Claude tokenizer).
  */
 export function measure(text: string): Measure {
   const g = gpt_tokens(text);
@@ -111,6 +164,31 @@ export function measure(text: string): Measure {
   };
 }
 
+/**
+ * Proxy-only measure (forces the chars-based estimate for GPT regardless of
+ * tokenizer availability). Use to record both the exact and the proxy count
+ * and flag the delta, and as the fallback regression guard.
+ */
+export function measure_proxy(text: string): Measure {
+  const g = gpt_tokens_proxy(text);
+  const c = claude_tokens(text);
+  return {
+    chars: _len(text),
+    tokens_gpt: g.tokens,
+    tokens_gpt_exact: g.exact,
+    tokens_claude: c.tokens,
+    tokens_claude_exact: c.exact,
+  };
+}
+
+/** Proxy-path provenance string (the fallback note). */
+export function method_note_proxy(): string {
+  return (
+    `tokens_gpt: proxy (chars/${_py_float_repr(_GPT_CHARS_PER_TOKEN)}, tiktoken not installed); ` +
+    `tokens_claude: proxy (chars/${_py_float_repr(_CLAUDE_CHARS_PER_TOKEN)})`
+  );
+}
+
 /** One-line provenance of how token counts were produced (for reports). */
 export function method_note(): string {
   if (TIKTOKEN_AVAILABLE) {
@@ -119,8 +197,5 @@ export function method_note(): string {
       `tokens_claude: proxy (chars/${_py_float_repr(_CLAUDE_CHARS_PER_TOKEN)})`
     );
   }
-  return (
-    `tokens_gpt: proxy (chars/${_py_float_repr(_GPT_CHARS_PER_TOKEN)}, tiktoken not installed); ` +
-    `tokens_claude: proxy (chars/${_py_float_repr(_CLAUDE_CHARS_PER_TOKEN)})`
-  );
+  return method_note_proxy();
 }