@event4u/agent-config 16.5.0 → 17.1.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,26 @@
  * 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.
+ * While it does, a `--content-class public-artifact` typed ask is also shadowed
+ * on the first admissible free route (free-hands 6.2): both calls run at once,
+ * the paid answer is returned unchanged, and the free one only becomes a row in
+ * the shadow ledger (`ai_council/free_hand_shadow.ts`, capped at 2,000 rows).
+ * `--no-record` turns the shadow off with the rest of the state writes.
+ *
+ * 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 +64,28 @@ 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, HandPayloadError, 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 { readShadowLedger, shadowAsk, SHADOW_CALL_CAP, type HeadVerify } from './ai_council/free_hand_shadow.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 +106,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 +127,52 @@ 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 verify recorded for both sides of a shadow call (free-hands 6.2).
+     * Default: `skipped` — the head has not checked either return at call time.
+     */
+    shadowVerify?: HeadVerify;
+    /** How long the paid answer waits for its shadow call; default `SHADOW_WAIT_MS`. */
+    shadowWaitMs?: number;
+    /** The slice the prompt was built from; the shadow rebuilds the same payload from it. */
+    handSlice?: { slice: HandSlice; egress: CouncilEgress };
+}
+
+/**
+ * The longest a shadow call may hold the paid answer. Past it the paid answer
+ * returns; the free call keeps running and its row lands only if it finishes,
+ * so a call that never returns is not ledgered.
+ */
+export const SHADOW_WAIT_MS = 30_000;
+
+/** 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>;
+    if (!isUnpaid(routeCandidateFromMember(member).billing)) return null;
+    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 +182,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 +215,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 +243,179 @@ 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);
+    const shadowFree = _shadowCandidate(opts, stateRoot, pool, chain);
+    // 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 shadow = failures === 0 && shadowFree !== null && !isUnpaid(route.billing) ? shadowFree : null;
+        const served = shadow === null ? pick : _teeMember(pick);
+        const shadowRun = shadow === null ? null : _runShadow(trimmed, served, shadow, opts, stateRoot as string);
+        const outcome = await _callRoute(served, route.name, system, trimmed, opts, stateRoot);
+        if (shadowRun !== null) await _bounded(shadowRun, opts.shadowWaitMs ?? SHADOW_WAIT_MS);
+        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);
+}
+
+/** Fewer than `SHADOW_CALL_CAP` rows; past it nothing but the paid route is called. */
+function _belowShadowCap(stateRoot: string): boolean {
+    return readShadowLedger(stateRoot).length < SHADOW_CALL_CAP;
+}
+
+/**
+ * The free route a typed `public-artifact` ask is shadowed on (free-hands 6.2):
+ * the first unpaid route the chooser admits once the flip gate is set aside,
+ * and only while the ask itself is served by a paid route. Null for anything
+ * else — untyped, project content, no state root, a flipped kind, the cap.
+ */
+function _shadowCandidate(
+    opts: AskOptions,
+    stateRoot: string | null,
+    pool: readonly { member: ExternalAIClient; route: ReturnType<typeof routeCandidateFromMember> }[],
+    chain: readonly ReturnType<typeof routeCandidateFromMember>[],
+): ExternalAIClient | null {
+    if (opts.kind === undefined || stateRoot === null) return null;
+    if ((opts.contentClass ?? DEFAULT_CONTENT_CLASS) !== 'public-artifact') return null;
+    const first = chain[0];
+    if (first === undefined || isUnpaid(first.billing)) return null;
+    const { chain: open } = chooseRouteChain({
+        kind: opts.kind,
+        contentClass: 'public-artifact',
+        unpaidAllowed: true,
+        candidates: pool.map((r) => r.route),
+        ...(opts.exposure !== undefined
+            ? { exposureShare: exposureShareFn(opts.exposure.ledger, opts.exposure.exposes, opts.exposure.trackedFiles) }
+            : {}),
+    });
+    const free = open.find((c) => isUnpaid(c.billing));
+    if (free === undefined || !_belowShadowCap(stateRoot)) return null;
+    return pool.find((r) => r.route === free)?.member ?? null;
+}
+
+/** Resolves when `run` settles or after `ms`, whichever comes first. */
+async function _bounded(run: Promise<void>, ms: number): Promise<void> {
+    let timer: NodeJS.Timeout | undefined;
+    const wait = new Promise<void>((resolve) => {
+        timer = setTimeout(resolve, ms);
+        timer.unref();
+    });
+    try {
+        await Promise.race([run, wait]);
+    } finally {
+        clearTimeout(timer);
+    }
+}
+
+/**
+ * The member with its first completion memoised, so the paid route is called once
+ * for both the caller and the ledger. Sound only because both consumers send the
+ * same `(handSystemPrompt(kind), prompt)` and neither retries on one member.
+ */
+function _teeMember(member: ExternalAIClient): ExternalAIClient {
+    let first: ReturnType<ExternalAIClient['ask']> | undefined;
+    const tee = Object.create(member) as ExternalAIClient;
+    tee.ask = (...args: Parameters<ExternalAIClient['ask']>) => (first ??= member.ask(...args));
+    return tee;
+}
+
+/** The shadow call; its result is the ledger row only, and nothing it raises reaches the caller. */
+async function _runShadow(
+    prompt: string,
+    paid: ExternalAIClient,
+    free: ExternalAIClient,
+    opts: AskOptions,
+    stateRoot: string,
+): Promise<void> {
+    if (opts.kind === undefined) return;
+    try {
+        const hand = opts.handSlice ?? { slice: { kind: opts.kind, spec: prompt }, egress: councilEgress() };
+        await shadowAsk(hand.slice, {
+            contentClass: 'public-artifact',
+            paid,
+            free,
+            egress: hand.egress,
+            ...(opts.exposure !== undefined ? { exposure: { ledger: opts.exposure.ledger, exposes: opts.exposure.exposes } } : {}),
+            verify: opts.shadowVerify ?? ((): { verdict: VerifyVerdict; tokens: number } => ({ verdict: 'skipped', tokens: 0 })),
+            stateRoot,
+            ...(opts.now !== undefined ? { now: opts.now } : {}),
+        });
+    } catch {
+        /* the shadow never fails the ask */
+    }
+}
 
+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 +423,86 @@ 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 interface AskHandOptions extends Omit<AskOptions, 'kind' | 'systemPrompt' | 'handSlice'> {
+    /** 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 scope = egress ?? councilEgress();
+    const payload = buildHandPayload(slice, scope);
+    return askOnce(payload.user, { ...rest, kind: slice.kind, handSlice: { slice, egress: scope } });
 }
 
-export async function main(argv: readonly string[]): Promise<number> {
+/** 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 +510,87 @@ 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)),
+        };
+        try {
+            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),
+                    },
+                },
+            );
+        } catch (e) {
+            if (!(e instanceof HandPayloadError)) throw e;
+            process.stderr.write(`ask_transport: ${e.message}\n`);
+            return 2;
+        }
+    } 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;
 }