@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/ask_transport.ts

@@ -14,8 +14,10 @@
  *
  * Hard caps, per the roadmap's anti-loop discipline (Risk 2 — "rung 0.5
  * becomes a hidden agent loop"):
- *   - ONE completion. No retry beyond the transport chain's own cli→api
- *     fallback semantics inside the client.
+ *   - ONE completion, plus at most ONE retry on the next route of the
+ *     chooser's chain, gated by `MidFlightFallback`: only a failure that
+ *     cannot have been generated and charged falls through (an empty free
+ *     quota or an unservable model does; a server fault never does).
  *   - NO tool use, NO session, NO follow-up turn.
  *   - Honest ∅: council disabled / no member / transport failure → null
  *     (CLI exit 3), never a fabricated answer and never an escalation this
@@ -35,9 +37,21 @@
  * Usage:
  *   ./scripts-run src/scripts/ask_transport "is X true in file Y?" \
  *     [--system "<system prompt>"] [--member <name>] [--format text|json] \
- *     [--no-record] [--dir <audit-dir>]
+ *     [--content-class public-artifact|project-content] \
+ *     [--kind classify|extract|summarise-given-text|draft-candidate|test-candidates|finding-proposal] \
+ *     [--callee-file <path>]... [--no-record] [--dir <audit-dir>]
  *
- * Exit codes: 0 answer produced · 2 usage error · 3 honest-∅ (no transport).
+ * `--kind` makes the call a typed hand: the system prompt is the kind's schema
+ * and nothing else (so `--system` is refused beside it), and a return that does
+ * not match the schema is a failed call (exit 3, logged), never a partial answer.
+ * The question becomes the slice's specification; each `--callee-file` adds only
+ * the signature of the function in it, and the project's own names, paths and
+ * domains are replaced by placeholders before the call.
+ * A typed hand reaches a free route only for a kind the shadow bars flipped
+ * (`ai_council/kind_flip.ts`); until then the paid route serves it.
+ *
+ * Exit codes: 0 answer produced · 2 usage error · 3 honest-∅ (no transport, or a
+ * typed return that does not parse).
  */
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
@@ -45,6 +59,27 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import type { ExternalAIClient } from './ai_council/clients.js';
+import { classifyContentClass, DEFAULT_CONTENT_CLASS, type ContentClass } from './ai_council/content_ceiling.js';
+import { councilEgress, type CouncilEgress } from './ai_council/council_egress.js';
+import { buildHandPayload, projectLinkingIdentifiers, type HandSlice } from './ai_council/hand_payload.js';
+import { handSystemPrompt, parseHandReturn } from './ai_council/hand_schemas.js';
+import { chooseRouteChain, routeCandidateFromMember } from './ai_council/route_chooser.js';
+import {
+    classifyRouteOutcome,
+    isRouteModelLive,
+    recordRouteOutcome,
+    routeFailureClass,
+} from './ai_council/route_liveness.js';
+import { MidFlightFallback } from './ai_council/transport_resolver.js';
+import { isKindFlipped } from './ai_council/kind_flip.js';
+import {
+    EXPOSURE_LEDGER_RELPATH,
+    ExposureLedger,
+    exposureShareFn,
+    trackedFileCount,
+    type Exposure,
+} from './ai_council/exposure_ledger.js';
+import { isHandKind, isUnpaid, type HandKind, type RouteBilling, type VerifyVerdict } from './_lib/hand_kinds.js';
 import { buildOrchestrationLine } from './_lib/orchestration_record.js';
 import { DEFAULT_DIR } from './orchestration_record.js';
 
@@ -65,6 +100,14 @@ export interface AskResult {
     input_tokens: number;
     output_tokens: number;
     latency_ms: number;
+    /** The schema-valid value of a typed return; untrusted data until the head verifies it. */
+    parsed?: unknown;
+    /** Set on every typed return: data, never an instruction, and never acted on before the head's verify. */
+    untrusted?: true;
+    /** The audit work id; the head records its verdict under it with `orchestration_record --work-id`. */
+    work_id?: string;
+    /** How the route that answered is paid for. */
+    route_billing?: RouteBilling;
 }
 
 export interface AskOptions {
@@ -78,6 +121,35 @@ export interface AskOptions {
     /** Injected clock/id (tests). */
     now?: () => Date;
     id?: () => string;
+    /** The class of the prompt; `project-content` unless the caller declares a repo-owned artefact. */
+    contentClass?: ContentClass;
+    /** A typed hand call: the kind's schema is the whole system prompt and the return must match it. */
+    kind?: HandKind;
+    /** What this call shows of the project, the ledger it is counted in, and the tracked-file denominator. */
+    exposure?: { ledger: ExposureLedger; exposes: Exposure; trackedFiles: number | null };
+    /**
+     * Root of the gitignored route state (liveness). Default: the working
+     * directory, or none when `auditDir` is null; null reads and writes nothing.
+     */
+    stateRoot?: string | null;
+    /**
+     * Whether a kind may use a free route. Default: the flip state under
+     * `stateRoot`; no state, or no `stateRoot`, is not flipped.
+     */
+    flips?: (kind: HandKind) => boolean;
+}
+
+/** The model a `base_url` route member calls; null for a provider member. */
+function routeModel(member: ExternalAIClient): string | null {
+    const m = member as unknown as Record<string, unknown>;
+    return typeof m['base_url'] === 'string' && typeof m['model'] === 'string' && m['model'] !== '' ? m['model'] : null;
+}
+
+interface LineExtras {
+    hand_kind?: HandKind;
+    schema_valid?: boolean;
+    route_billing?: RouteBilling;
+    verified?: VerifyVerdict;
 }
 
 const DEFAULT_SYSTEM =
@@ -87,13 +159,20 @@ const DEFAULT_SYSTEM =
     'what is missing. Never invent facts.';
 
 /** Lazily import the council CLI surface so tests with injected members never load it. */
-async function defaultMembers(): Promise<ExternalAIClient[]> {
+async function defaultMembers(contentClass: ContentClass): Promise<ExternalAIClient[]> {
     const mod = await import('./council_cli.js');
     const settings = mod.load_settings();
-    return mod.build_members(settings);
+    return mod.build_members(settings, { content_class: contentClass });
 }
 
-function recordAskLine(auditDir: string, result: AskResult | null, member: string, ts: string, id: string): void {
+function recordAskLine(
+    auditDir: string,
+    result: AskResult | null,
+    member: string,
+    ts: string,
+    id: string,
+    extras: LineExtras,
+): void {
     const { line, errors } = buildOrchestrationLine({
         spawn_count: 0,
         token_delta: 0,
@@ -113,6 +192,11 @@ function recordAskLine(auditDir: string, result: AskResult | null, member: strin
         model_requested: result === null || result.model === UNKNOWN_MODEL ? null : result.model,
         model_served: result === null ? null : result.model_served,
         origin: 'dispatch-economy-2026',
+        ...(extras.hand_kind !== undefined ? { hand_kind: extras.hand_kind } : {}),
+        ...(extras.schema_valid !== undefined ? { schema_valid: extras.schema_valid } : {}),
+        ...(extras.route_billing !== undefined ? { route_billing: extras.route_billing } : {}),
+        ...(extras.verified !== undefined ? { verified: extras.verified } : {}),
+        work_id: askWorkId(id),
         ts,
         id,
     });
@@ -136,31 +220,87 @@ export async function askOnce(prompt: string, opts: AskOptions = {}): Promise<As
 
     let members: ExternalAIClient[];
     try {
-        members = opts.members ?? (await defaultMembers());
+        members = opts.members ?? (await defaultMembers(opts.contentClass ?? DEFAULT_CONTENT_CLASS));
     } catch {
         return _finish(null, 'none', opts); // disabled / unreadable config → ∅
     }
-    const memberName = (m: ExternalAIClient): string => {
-        const c = m as { name?: string; provider?: string };
-        return c.name || c.provider || 'unknown';
-    };
-    const pick =
-        opts.member !== undefined ? members.find((m) => memberName(m) === opts.member) : members[0];
-    if (pick === undefined) {
-        return _finish(null, opts.member ?? 'none', opts);
+    const stateRoot = opts.stateRoot !== undefined ? opts.stateRoot : opts.auditDir === null ? null : process.cwd();
+    // `--member` narrows the candidates; it never bypasses the chooser's checks.
+    const routed = members.map((m) => {
+        const route = routeCandidateFromMember(m);
+        const model = routeModel(m);
+        const retired = stateRoot !== null && model !== null && !isRouteModelLive(stateRoot, route.name, model);
+        return { member: m, route: retired ? { ...route, live: false } : route };
+    });
+    const pool = opts.member !== undefined ? routed.filter((r) => r.route.name === opts.member) : routed;
+    const flipped = opts.flips ?? ((k: HandKind): boolean => stateRoot !== null && isKindFlipped(stateRoot, k));
+    const { chain } = chooseRouteChain({
+        kind: opts.kind ?? null,
+        contentClass: opts.contentClass ?? DEFAULT_CONTENT_CLASS,
+        ...(opts.kind !== undefined ? { unpaidAllowed: flipped(opts.kind) } : {}),
+        candidates: pool.map((r) => r.route),
+        ...(opts.exposure !== undefined
+            ? { exposureShare: exposureShareFn(opts.exposure.ledger, opts.exposure.exposes, opts.exposure.trackedFiles) }
+            : {}),
+    });
+    const system = opts.kind !== undefined ? handSystemPrompt(opts.kind) : (opts.systemPrompt ?? DEFAULT_SYSTEM);
+    // One retry down the chain, gated like the council's cli→api fallback: a
+    // failure that may have been generated and charged never falls through.
+    const ledger = new MidFlightFallback();
+    let last: { provider: string; billing: RouteBilling } | null = null;
+    let failures = 0;
+    for (const route of chain) {
+        const pick = pool.find((r) => r.route === route)?.member;
+        if (pick === undefined) continue;
+        const outcome = await _callRoute(pick, route.name, system, trimmed, opts, stateRoot);
+        if (outcome.done) return _finish(outcome.result, route.name, opts, outcome.schemaValid, route.billing);
+        last = { provider: route.name, billing: route.billing };
+        if (++failures > 1) break;
+        // An empty quota on a free route is that route's limit, not a cap the user set.
+        const failure = routeFailureClass(classifyRouteOutcome(outcome.error));
+        if (ledger.attempt(route.name, failure, { apiOnQuota: isUnpaid(route.billing) }) !== 'api') break;
     }
-    const provider = memberName(pick);
+    return last === null ? _finish(null, opts.member ?? 'none', opts) : _finish(null, last.provider, opts, undefined, last.billing);
+}
 
+type RouteCallOutcome =
+    | { readonly done: true; readonly result: AskResult | null; readonly schemaValid: boolean | undefined }
+    | { readonly done: false; readonly error: string };
+
+/**
+ * One completion on one route. `done: false` only for a transport failure the
+ * route reported; an empty or unparseable answer was generated, so it ends the
+ * ask rather than being paid for again elsewhere.
+ */
+async function _callRoute(
+    pick: ExternalAIClient,
+    provider: string,
+    system: string,
+    prompt: string,
+    opts: AskOptions,
+    stateRoot: string | null,
+): Promise<RouteCallOutcome> {
+    opts.exposure?.ledger.record(provider, opts.exposure.exposes);
+    const model = routeModel(pick);
     try {
-        const response = pick.ask(opts.systemPrompt ?? DEFAULT_SYSTEM, trimmed);
+        const response = pick.ask(system, prompt);
         const r = response instanceof Promise ? await response : response;
-        if (r === null || r === undefined || (r.error !== null && r.error !== undefined && r.error !== '')) {
-            return _finish(null, provider, opts);
-        }
+        const error = r === null || r === undefined ? 'no response' : r.error;
+        if (stateRoot !== null && model !== null) recordRouteOutcome(stateRoot, provider, model, classifyRouteOutcome(error));
+        if (r === null || r === undefined) return { done: true, result: null, schemaValid: undefined };
+        if (error !== null && error !== undefined && error !== '') return { done: false, error };
         const text = (r.text ?? '').trim();
-        if (!text) return _finish(null, provider, opts);
-        return _finish(
-            {
+        if (!text) return { done: true, result: null, schemaValid: undefined };
+        let parsed: unknown;
+        if (opts.kind !== undefined) {
+            const p = parseHandReturn(opts.kind, text);
+            if (!p.ok) return { done: true, result: null, schemaValid: false };
+            parsed = p.value;
+        }
+        return {
+            done: true,
+            schemaValid: opts.kind !== undefined ? true : undefined,
+            result: {
                 answer: text,
                 member: provider,
                 model: r.model ?? UNKNOWN_MODEL,
@@ -168,32 +308,85 @@ export async function askOnce(prompt: string, opts: AskOptions = {}): Promise<As
                 input_tokens: r.input_tokens ?? 0,
                 output_tokens: r.output_tokens ?? 0,
                 latency_ms: r.latency_ms ?? 0,
+                ...(opts.kind !== undefined ? { parsed, untrusted: true as const } : {}),
             },
-            provider,
-            opts,
-        );
+        };
     } catch {
-        return _finish(null, provider, opts); // ONE completion — no retry here
+        return { done: true, result: null, schemaValid: undefined }; // a thrown call is never retried
     }
 }
 
-function _finish(result: AskResult | null, member: string, opts: AskOptions): AskResult | null {
+function askWorkId(id: string): string {
+    return `ask-${id}`;
+}
+
+/**
+ * A typed return is recorded `skipped` until the head records its own verdict
+ * under the same work id; one that never parsed has already failed the check.
+ */
+function _finish(
+    result: AskResult | null,
+    member: string,
+    opts: AskOptions,
+    schemaValid?: boolean,
+    billing?: RouteBilling,
+): AskResult | null {
+    const id = opts.id ? opts.id() : crypto.randomUUID();
     const auditDir = opts.auditDir === undefined ? path.join(process.cwd(), DEFAULT_DIR) : opts.auditDir;
     if (auditDir !== null) {
         const ts = (opts.now ? opts.now() : new Date()).toISOString();
-        const id = opts.id ? opts.id() : crypto.randomUUID();
-        recordAskLine(auditDir, result, member, ts, id);
+        const verified: VerifyVerdict | undefined =
+            opts.kind === undefined || billing === undefined ? undefined : schemaValid === true ? 'skipped' : 'fail';
+        recordAskLine(auditDir, result, member, ts, id, {
+            ...(opts.kind !== undefined ? { hand_kind: opts.kind } : {}),
+            ...(schemaValid !== undefined ? { schema_valid: schemaValid } : {}),
+            ...(billing !== undefined ? { route_billing: billing } : {}),
+            ...(verified !== undefined ? { verified } : {}),
+        });
     }
-    return result;
+    return result === null
+        ? null
+        : { ...result, work_id: askWorkId(id), ...(billing !== undefined ? { route_billing: billing } : {}) };
 }
 
-export async function main(argv: readonly string[]): Promise<number> {
+export interface AskHandOptions extends Omit<AskOptions, 'kind' | 'systemPrompt'> {
+    /** The run's placeholder scope; default: the council egress state. */
+    egress?: CouncilEgress;
+}
+
+/**
+ * A typed hand call over a slice: the payload is built from the specification
+ * and callee signatures only, with linking identifiers replaced, and the system
+ * prompt is the kind's schema.
+ */
+export async function askHand(slice: HandSlice, opts: AskHandOptions = {}): Promise<AskResult | null> {
+    const { egress, ...rest } = opts;
+    const payload = buildHandPayload(slice, egress ?? councilEgress());
+    return askOnce(payload.user, { ...rest, kind: slice.kind });
+}
+
+/** The declared name of a callee, for the ledger's symbol count. */
+function calleeName(source: string): string[] {
+    const m = /\b(?:function|def|class)\s+([A-Za-z_$][\w$]*)|\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/.exec(source);
+    const name = m?.[1] ?? m?.[2];
+    return name === undefined ? [] : [name];
+}
+
+/** Test seam: inject members instead of reading the council configuration. */
+export interface MainDeps {
+    members?: ExternalAIClient[];
+}
+
+export async function main(argv: readonly string[], deps: MainDeps = {}): Promise<number> {
     let prompt = '';
     let system: string | undefined;
     let member: string | undefined;
     let format: 'text' | 'json' = 'text';
     let record = true;
     let dir: string | undefined;
+    let contentClass: ContentClass = DEFAULT_CONTENT_CLASS;
+    let kindRaw: string | undefined;
+    const calleeFiles: string[] = [];
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i] ?? '';
         if (a === '--system') system = argv[++i];
@@ -201,25 +394,81 @@ export async function main(argv: readonly string[]): Promise<number> {
         else if (a === '--format') format = argv[++i] === 'json' ? 'json' : 'text';
         else if (a === '--no-record') record = false;
         else if (a === '--dir') dir = argv[++i];
+        else if (a === '--content-class') contentClass = classifyContentClass(argv[++i]);
+        else if (a === '--kind') kindRaw = argv[++i] ?? '';
+        else if (a === '--callee-file') calleeFiles.push(argv[++i] ?? '');
         else if (!a.startsWith('--')) prompt = prompt ? `${prompt} ${a}` : a;
     }
     if (!prompt.trim()) {
         process.stderr.write('ask_transport: a question argument is required\n');
         return 2;
     }
+    if (kindRaw !== undefined && !isHandKind(kindRaw)) {
+        process.stderr.write(`ask_transport: --kind must be one of the hand kinds; '${kindRaw}' is not one (head-only work never reaches a hand)\n`);
+        return 2;
+    }
+    if (kindRaw !== undefined && system !== undefined) {
+        process.stderr.write('ask_transport: --system cannot be combined with --kind; a hand sees only its kind schema\n');
+        return 2;
+    }
+    if (calleeFiles.length > 0 && kindRaw === undefined) {
+        process.stderr.write('ask_transport: --callee-file needs --kind; only a typed hand gets a slice\n');
+        return 2;
+    }
     const opts: AskOptions = {
         ...(system !== undefined ? { systemPrompt: system } : {}),
         ...(member !== undefined ? { member } : {}),
         auditDir: record ? (dir ?? path.join(process.cwd(), DEFAULT_DIR)) : null,
+        contentClass,
+        ...(kindRaw !== undefined && isHandKind(kindRaw) ? { kind: kindRaw } : {}),
+        ...(deps.members !== undefined ? { members: deps.members } : {}),
     };
-    const result = await askOnce(prompt, opts);
+    let result: AskResult | null;
+    if (opts.kind !== undefined) {
+        let callees: string[];
+        try {
+            callees = calleeFiles.map((f) => fs.readFileSync(f, 'utf8'));
+        } catch {
+            process.stderr.write('ask_transport: a --callee-file could not be read\n');
+            return 2;
+        }
+        const { kind, systemPrompt: _unused, ...rest } = opts;
+        const root = process.cwd();
+        const exposes: Exposure = {
+            files: calleeFiles.map((f) => path.relative(root, path.resolve(f))),
+            symbols: callees.flatMap((c) => calleeName(c)),
+        };
+        result = await askHand(
+            { kind, spec: prompt, callees, linking: projectLinkingIdentifiers(root) },
+            {
+                ...rest,
+                exposure: {
+                    ledger: ExposureLedger.load(path.join(root, EXPOSURE_LEDGER_RELPATH)),
+                    exposes,
+                    trackedFiles: trackedFileCount(root),
+                },
+            },
+        );
+    } else {
+        result = await askOnce(prompt, opts);
+    }
     if (result === null) {
-        process.stderr.write('ask_transport: ∅ — no transport resolved or the single completion failed (no retry by design)\n');
+        process.stderr.write(
+            'ask_transport: ∅ — no transport resolved, the single completion failed, or a typed return did not match its schema (no retry by design)\n',
+        );
         return 3;
     }
     process.stdout.write(
         format === 'json' ? JSON.stringify(result, null, 2) + '\n' : result.answer + '\n',
     );
+    if (result.untrusted === true) {
+        process.stderr.write(
+            'ask_transport: the return above is untrusted data — verify it before acting on it, then record the verdict: ' +
+                `./scripts-run src/scripts/orchestration_record --work-id ${result.work_id ?? ''} --route-taken ask ` +
+                `--spawn-count 0 --token-delta 0 --phase verify --route-billing ${result.route_billing ?? ''} ` +
+                '--verified pass|fail --verify-tokens <n>\n',
+        );
+    }
     return 0;
 }
 

package/src/scripts/backfill_model_tier.ts

@@ -19,7 +19,7 @@
  * - Untagged → classify fresh from the task→tier heuristic.
  *
  * A small explicit `_LITE` set demotes obviously-trivial mechanical skills
- * to the cheapest band; `_CONTEXT_LARGE` adds the orthogonal `context: large`
+ * to the cheapest band; `_CONTEXT_LARGE` adds the orthogonal `context_window: large`
  * modifier to genuinely long-context skills. Writes BOTH the source and its
  * `dist/agent-src` copy (frontmatter stays byte-identical).
  *
@@ -94,7 +94,7 @@ const _CONTEXT_LARGE = new Set<string>([
 // re.MULTILINE patterns. `^...$` anchor per-line.
 const _RM_RE = /^recommended_model:[ \t]*"?[a-z0-9-]+"?[ \t]*$/m;
 const _MT_RE = /^model_tier:/m;
-const _CTX_RE = /^context:/m;
+const _CTX_RE = /^context_window:/m;
 
 type Fm = Record<string, unknown> | null;
 
@@ -152,8 +152,7 @@ function _apply(p: string, tier: string, want_context: boolean): boolean {
         changed = true;
     }
     if (want_context && !_CTX_RE.test(fm)) {
-        // re.sub(r'(^model_tier:.*$)', r'\1\ncontext: large', fm, count=1, MULTILINE)
-        fm = _subOnce(fm, /^model_tier:.*$/m, (match) => `${match}\ncontext: large`);
+        fm = _subOnce(fm, /^model_tier:.*$/m, (match) => `${match}\ncontext_window: large`);
         changed = true;
     }
     if (changed) {
@@ -221,7 +220,7 @@ export function run(apply: boolean): number {
         total += v;
     }
     process.stdout.write(
-        `  context:large on ${ctx} skills · ${verb} ${touched} newly · total ${total}\n`,
+        `  context_window:large on ${ctx} skills · ${verb} ${touched} newly · total ${total}\n`,
     );
     return 0;
 }

package/src/scripts/before_complete_hook.ts

@@ -67,6 +67,7 @@ import {
 import { readHookStdin } from "./hooks/hook_stdin.js";
 import { hookSectionValue } from "./_lib/hook_settings.js";
 import { isVerificationCommand, mightBeVerification } from "./_lib/verification_command.js";
+import { observeAssetRender, type AssetRenderGap, type AssetRenderRecord } from "./_lib/asset_render_record.js";
 import {
   advisoryLine,
   runTouchedFileQuality,
@@ -187,6 +188,7 @@ function _empty_state(): StateDict {
     // a reader must never have to distinguish "no runs yet" from "key absent".
     verification_runs: [],
     edits_this_turn: 0,
+    asset_renders: [],
     // NOTE — `quality_runs` and `quality_files_source` are deliberately ABSENT
     // here, against the convention `verification_runs` above follows.
     //
@@ -696,6 +698,9 @@ function _reset_turn(state: StateDict, session_id: string): StateDict {
   // turn's edits, which is the freshness argument `verify-before-complete` makes.
   state["verification_runs"] = [];
   state["edits_this_turn"] = 0;
+  // Turn-scoped like its neighbours: a render from an earlier turn is not one
+  // this turn's hook saw, and the SVG obligation asks for exactly that.
+  state["asset_renders"] = [];
   // TURN-scoped for the same reason as its neighbour: a quality verdict from
   // the previous turn describes files this turn may already have changed, and a
   // stale PASS is the direction that misleads. DELETED rather than emptied, so
@@ -709,6 +714,28 @@ function _reset_turn(state: StateDict, session_id: string): StateDict {
   return state;
 }
 
+function _observe_asset_render(
+  consumer_root: string,
+  envelope: StateDict,
+): AssetRenderRecord | AssetRenderGap | null {
+  const raw = envelope["payload"];
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  const pl = raw as StateDict;
+  const [, cmd] = _extract_command(pl);
+  if (!cmd) return null;
+  const cwd = pl["cwd"] ?? envelope["cwd"];
+  try {
+    return observeAssetRender(
+      consumer_root,
+      cmd,
+      _extract_exit_reading(pl, _is_failure_event(pl, envelope)).code,
+      typeof cwd === "string" && path.isAbsolute(cwd) ? cwd : consumer_root,
+    );
+  } catch {
+    return null;
+  }
+}
+
 function _asInt(v: unknown): number {
   if (!v) {
     return 0;
@@ -732,6 +759,7 @@ function _update(
   event: string,
   envelope: StateDict,
   quality: { runs: QualityRun[]; source: string } | null = null,
+  assetRender: AssetRenderRecord | AssetRenderGap | null = null,
 ): StateDict {
   const session_id = (envelope["session_id"] || state["session_id"] || "") as string;
   if (session_id && session_id !== state["session_id"]) {
@@ -900,6 +928,12 @@ function _update(
       // of its own red-then-green pair.
       state["verification_runs"] = _cap_runs(runs);
     }
+    // The finished asset render, observed rather than inferred — read by the
+    // turn-end gate's SVG obligation.
+    if (assetRender !== null) {
+      const renders = Array.isArray(state["asset_renders"]) ? (state["asset_renders"] as unknown[]) : [];
+      state["asset_renders"] = [...renders, assetRender].slice(-MAX_VERIFICATION_RUNS_PER_TURN);
+    }
   } else if (event === "stop") {
     state["last_stop_at"] = _now();
     if (quality !== null) {
@@ -975,6 +1009,9 @@ export function run(
   const quality_mode = event === "stop" ? readTouchedFileQualityMode(consumer_root) : "off";
   const quality =
     quality_mode === "off" ? null : collectTouchedFileQuality(consumer_root, session_id);
+  // Hashed BEFORE the lock for the same reason as the quality pass: file reads
+  // stay out of the critical section.
+  const assetRender = event === "post_tool_use" ? _observe_asset_render(consumer_root, envelope) : null;
 
   // LOAD → UPDATE → PUBLISH under ONE lock, not three separate steps.
   //
@@ -1006,7 +1043,7 @@ export function run(
     // treats a missing counter as 0 and the `=== true` guards treat a missing
     // flag as false, so every assertion would still pass while `schema_version`
     // and an explicit `ci_last: null` vanished from a freshly created file.
-    state = _update({ ..._empty_state(), ...loaded } as StateDict, event, envelope, quality);
+    state = _update({ ..._empty_state(), ...loaded } as StateDict, event, envelope, quality, assetRender);
     return state;
   });
   if (outcome === "failed") {
@@ -1115,6 +1152,8 @@ export function main(argv?: string[]): number {
 export interface TurnRunState {
   readonly runs: readonly unknown[];
   readonly edits_this_turn: number;
+  /** Absent when the recorder that wrote the file predates the field. */
+  readonly asset_renders?: readonly unknown[];
 }
 
 /**
@@ -1153,7 +1192,14 @@ export function readTurnRunState(
         const edits = state['edits_this_turn'];
         if (!Array.isArray(runs)) return null;
         if (typeof edits !== 'number' || !Number.isFinite(edits) || edits < 1) return null;
-        return { runs: runs as readonly unknown[], edits_this_turn: edits };
+        const renders = state['asset_renders'];
+        return {
+            runs: runs as readonly unknown[],
+            edits_this_turn: edits,
+            // Absent rather than empty when the writer predates the field, so
+            // the SVG obligation falls back instead of reading "no render".
+            ...(Array.isArray(renders) ? { asset_renders: renders as readonly unknown[] } : {}),
+        };
     } catch {
         // Absent, unreadable or malformed — the recorder said nothing, so the
         // transcript answers. Never a refusal of its own.

package/src/scripts/bench_hook_latency.ts

@@ -103,7 +103,7 @@ const MANIFEST_PATH = path.join(REPO_ROOT, 'src', 'scripts', 'hook_manifest.yaml
 const BUDGET_PATH = path.join(REPO_ROOT, 'src', 'config', 'hook-latency-budget.json');
 const RESULTS_PATH = path.join(REPO_ROOT, 'docs', 'hook-latency.json');
 
-const EVENTS: readonly string[] = [
+export const EVENTS: readonly string[] = [
     'pre_tool_use',
     'post_tool_use',
     'user_prompt_submit',
@@ -113,7 +113,7 @@ const EVENTS: readonly string[] = [
 ];
 
 /** snake_case hook event → the platform-native name hooks.json passes. */
-const NATIVE_EVENT: Readonly<Record<string, string>> = {
+export const NATIVE_EVENT: Readonly<Record<string, string>> = {
     pre_tool_use: 'PreToolUse',
     post_tool_use: 'PostToolUse',
     user_prompt_submit: 'UserPromptSubmit',
@@ -199,7 +199,7 @@ function syntheticPayload(event: string, workspace: string, tool?: ToolShape): s
  * pays and concern state stays out of the repo.
  */
 let _matrixCache: Record<string, string> | null = null;
-function hooksJsonCommand(event: string): string {
+export function hooksJsonCommand(event: string): string {
     _matrixCache ??= build_claude_hook_matrix(MANIFEST_PATH);
     const native = NATIVE_EVENT[event] ?? event;
     const cmd = _matrixCache[native];