@dzhechkov/harness-core 0.8.46 → 0.8.48

package/src/workflow-run-dispatch.ts

@@ -60,7 +60,18 @@ export interface DispatchResult {
   /** null when the runtime did not report a count — NEVER 0, never estimated (ADR-004 C4). */
   tokensIn: number | null;
   tokensOut: number | null;
-  tokensSource: 'claude-envelope' | 'codex-stderr' | null;
+  tokensSource: 'claude-envelope' | 'codex-stderr' | 'codex-json' | null;
+  tokensTotal?: number | null;
+  tokensCacheRead?: number | null;
+  tokensCacheWrite?: number | null;
+  tokensReasoning?: number | null;
+  reportedTotalBasis?: 'raw-inclusive' | 'uncached-display' | 'reported-unknown' | 'output-only' | 'unknown';
+  inputCacheSemantics?: 'includes-cache-read-write' | 'excludes-cache-read-write' | 'uncached-display' | 'unknown';
+  reportedCostUsd?: number | null;
+  usageDiagnostics?: string[];
+  totalDerivation?: string;
+  modelProvenance?: string;
+  usageSource?: { schema: string; scope: string; threadId: string | null; turnId: string | null; receiptId: string | null };
   failure?: DispatchFailure;
 }
 
@@ -69,6 +80,13 @@ export interface ProbeOutcome {
   id: string | null;
   wallMs: number;
   detail: string;
+  provenance?: {
+    schema: 'wf-probe-attempts-1'; complete: boolean; totalConsidered: number;
+    attempts: Array<{ ordinal: number; model: string | null; family: BridgeFamily; wrapperInvoked: boolean;
+      outcome: 'answered' | 'failed' | 'rejected'; selected: boolean;
+      reason: 'answered' | 'timeout' | 'spawn-error' | 'no-exit-code' | 'exit-nonzero' | 'unexpected-response' | 'invalid-candidate' }>;
+  } | null;
+  provenanceReason?: 'candidate-model-invalid' | 'wrapper-result-invalid' | null;
 }
 
 export interface Dispatcher {
@@ -181,7 +199,7 @@ export { CODEX_EXEC_PROMPT_CEILING_CHARS };
 export function codexExecArgv(modelId: string, prompt: string, deliverable: Deliverable): string[] {
   const returnValue = (deliverable ?? 'return-value') !== 'file';
   const text = returnValue ? CODEX_SCOPING_PREFIX + '\n\n' + prompt : prompt;
-  return ['exec', '-m', modelId, ...(returnValue ? ['--sandbox', 'read-only'] : []), text];
+  return ['exec', '-m', modelId, ...(returnValue ? ['--sandbox', 'read-only'] : []), '--json', text];
 }
 
 /** The liveness probe: an allowlist says an id is SPELLABLE, only a probe says it ANSWERS. */
@@ -205,55 +223,160 @@ export function interpretCodexProbe(out: { stdout: string; exitCode: number | nu
  * builds/configs do print one; it is tested, not assumed. (Named consequence: codex runs report no
  * token counts today. That is the honest state, not a bug to paper over — see the manifest.)
  */
-export function extractCodexTokens(stderr: string): { tokensIn: number | null; tokensOut: number | null } {
-  const text = String(stderr ?? '');
-  const num = (raw: string | undefined): number | null => {
-    if (raw === undefined) return null;
-    const n = Number(raw.replace(/[,_\s]/g, ''));
-    return Number.isFinite(n) && n >= 0 ? n : null;
+type ObservedUsage = Pick<DispatchResult, 'tokensIn' | 'tokensOut' | 'tokensSource' | 'tokensTotal' | 'tokensCacheRead' | 'tokensCacheWrite' | 'tokensReasoning' | 'reportedTotalBasis' | 'inputCacheSemantics' | 'reportedCostUsd' | 'usageDiagnostics' | 'usageSource' | 'totalDerivation'>;
+const count = (value: unknown): number | null => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : null;
+const emptyUsage = (): ObservedUsage => ({ tokensIn: null, tokensOut: null, tokensTotal: null, tokensCacheRead: null,
+  tokensCacheWrite: null, tokensReasoning: null, tokensSource: null, reportedTotalBasis: 'unknown', inputCacheSemantics: 'unknown',
+  reportedCostUsd: null, usageDiagnostics: [] });
+
+export function extractCodexTokens(stderr: string): ObservedUsage {
+  const text = String(stderr ?? ''); const usage = emptyUsage();
+  const numeric = (raw: string | undefined): number | null => raw === undefined ? null : count(Number(raw.replace(/[,_\s]/g, '')));
+  const input = /\binput\b[^\n\d+.-]{0,20}([+-]?\d[\d,_]*(?:\.\d+)?)|\btokens?\s+in\b[^\n\d+.-]{0,10}([+-]?\d[\d,_]*(?:\.\d+)?)/i.exec(text);
+  const output = /\boutput\b[^\n\d+.-]{0,20}([+-]?\d[\d,_]*(?:\.\d+)?)|\btokens?\s+out\b[^\n\d+.-]{0,10}([+-]?\d[\d,_]*(?:\.\d+)?)/i.exec(text);
+  const total = /tokens used\s*\n\s*([+-]?\d[\d,_]*(?:\.\d+)?)|Token usage:\s*total=([+-]?\d[\d,_]*(?:\.\d+)?)/i.exec(text);
+  usage.tokensIn = numeric(input?.[1] ?? input?.[2]); usage.tokensOut = numeric(output?.[1] ?? output?.[2]);
+  usage.tokensTotal = numeric(total?.[1] ?? total?.[2]);
+  if (input && usage.tokensIn === null) usage.usageDiagnostics!.push('invalid-counter:input');
+  if (output && usage.tokensOut === null) usage.usageDiagnostics!.push('invalid-counter:output');
+  if (total && usage.tokensTotal === null) usage.usageDiagnostics!.push('invalid-counter:total');
+  const cached = /\(\+([\d,_]+) cached\)/i.exec(text);
+  if (total?.[2] && cached) usage.tokensCacheRead = numeric(cached[1]);
+  usage.reportedTotalBasis = total?.[2] ? 'uncached-display' : 'reported-unknown';
+  usage.inputCacheSemantics = total?.[2] ? 'uncached-display' : 'unknown';
+  usage.tokensSource = usage.tokensTotal != null || usage.tokensIn != null || usage.tokensOut != null ? 'codex-stderr' : null;
+  usage.totalDerivation = usage.tokensTotal === null ? 'not-recorded' : 'reported';
+  return usage;
+}
+
+export function extractClaudeUsage(stdout: string): ObservedUsage {
+  let chosen: Record<string, unknown> | null = null;
+  for (const line of [String(stdout).trim(), ...String(stdout).split(/\r?\n/)]) {
+    try { const obj = JSON.parse(line) as Record<string, unknown>; if (obj && obj['type'] === 'result') chosen = obj; } catch { /* non-envelope line */ }
+  }
+  const result = emptyUsage(); if (!chosen) return result;
+  const usage = chosen['usage']; if (!usage || typeof usage !== 'object' || Array.isArray(usage)) return result;
+  const raw = usage as Record<string, unknown>;
+  const invalid = (obj: Record<string, unknown>, key: string) => obj[key] != null && count(obj[key]) === null;
+  const field = (obj: Record<string, unknown>, key: string): number | null => {
+    if (invalid(obj, key)) result.usageDiagnostics!.push('invalid-count:' + key);
+    return count(obj[key]);
   };
-  // Two accepted spellings per half: `input tokens: N` / `input: N tokens` and `tokens in: N`.
-  const inMatch = /\binput\b[^\n\d]{0,20}([\d,_]+)|\btokens?\s+in\b[^\n\d]{0,10}([\d,_]+)/i.exec(text);
-  const outMatch = /\boutput\b[^\n\d]{0,20}([\d,_]+)|\btokens?\s+out\b[^\n\d]{0,10}([\d,_]+)/i.exec(text);
-  const tokensIn = inMatch === null ? null : num(inMatch[1] ?? inMatch[2]);
-  const tokensOut = outMatch === null ? null : num(outMatch[1] ?? outMatch[2]);
-  return { tokensIn, tokensOut };
+  result.tokensIn = field(raw, 'input_tokens'); result.tokensOut = field(raw, 'output_tokens');
+  result.tokensCacheRead = field(raw, 'cache_read_input_tokens'); result.tokensCacheWrite = field(raw, 'cache_creation_input_tokens');
+  const creation = raw['cache_creation'];
+  if (creation != null) {
+    if (typeof creation !== 'object' || Array.isArray(creation)) {
+      result.usageDiagnostics!.push('invalid-cache-creation-shape'); result.tokensCacheWrite = null;
+    } else {
+      const nested = creation as Record<string, unknown>;
+      const a = field(nested, 'ephemeral_5m_input_tokens'); const b = field(nested, 'ephemeral_1h_input_tokens');
+      const nestedInvalid = invalid(nested, 'ephemeral_5m_input_tokens') || invalid(nested, 'ephemeral_1h_input_tokens');
+      const total = a !== null && b !== null ? count(a + b) : null;
+      if (a !== null && b !== null && total === null) result.usageDiagnostics!.push('cache-creation-overflow');
+      if (nestedInvalid || (a !== null && b !== null && total === null)) result.tokensCacheWrite = null;
+      else if (raw['cache_creation_input_tokens'] == null) result.tokensCacheWrite = total;
+      else if (result.tokensCacheWrite !== null && total !== null && total !== result.tokensCacheWrite) {
+        result.usageDiagnostics!.push('cache-creation-mismatch'); result.tokensCacheWrite = null;
+      }
+    }
+  }
+  result.tokensReasoning = field(raw, 'reasoning_output_tokens');
+  if (result.tokensReasoning !== null && result.tokensOut !== null && result.tokensReasoning > result.tokensOut) {
+    result.usageDiagnostics!.push('reasoning-exceeds-output'); result.tokensReasoning = null;
+  }
+  result.tokensTotal = field(raw, 'total_tokens');
+  const components = [result.tokensIn, result.tokensCacheRead, result.tokensCacheWrite, result.tokensOut];
+  const partitionKnown = components.every((n) => n !== null);
+  const derived = partitionKnown ? count(components.reduce<number>((n, v) => n + (v ?? 0), 0)) : null;
+  if (partitionKnown && derived === null) result.usageDiagnostics!.push('total-overflow');
+  if (invalid(raw, 'total_tokens')) result.totalDerivation = 'invalid-reported-total';
+  else if (raw['total_tokens'] == null) {
+    result.tokensTotal = derived; result.totalDerivation = derived === null ? 'not-recorded' : 'disjoint-dimensions';
+  } else result.totalDerivation = 'reported';
+  if (derived !== null && result.tokensTotal !== null && result.tokensTotal !== derived) result.usageDiagnostics!.push('total-split-mismatch');
+  result.reportedCostUsd = typeof chosen['total_cost_usd'] === 'number' && Number.isFinite(chosen['total_cost_usd']) && chosen['total_cost_usd'] >= 0 ? chosen['total_cost_usd'] : null;
+  result.reportedTotalBasis = 'raw-inclusive'; result.inputCacheSemantics = 'excludes-cache-read-write'; result.tokensSource = 'claude-envelope';
+  return result;
 }
 
-/**
- * The claude `--output-format json` USAGE fields, pinned to the LIVE envelope shape.
- *
- * MEASURED this session (`claude -p --output-format json`, sonnet):
- * `usage.input_tokens = 2`, `usage.output_tokens = 4`, alongside `cache_read_input_tokens` and
- * `cache_creation_input_tokens`. Only the two plain counters are reported — cache tokens are a
- * SEPARATE dimension `wf-budget-1` has no field for, and silently folding them into `tokensIn`
- * would inflate every cached run's cost picture. Added to the architecture's export list; see the
- * manifest.
- */
-export function extractClaudeUsage(stdout: string): { tokensIn: number | null; tokensOut: number | null } {
-  const env = extractClaudeResult(String(stdout ?? ''));
-  if (!env.ok) return { tokensIn: null, tokensOut: null };
-  // re-scan for the envelope object itself: extractClaudeResult hands back only the text
-  const lines = String(stdout ?? '').split(/\r?\n/);
-  const candidates = [String(stdout ?? '').trim(), ...lines.map((l) => l.trim())].filter((c) => c.startsWith('{') && c.endsWith('}'));
-  let usage: Record<string, unknown> | null = null;
-  for (const c of candidates) {
-    let obj: unknown;
-    try {
-      obj = JSON.parse(c);
-    } catch {
-      continue;
+function codexStructuredOutput(stdout: string): { structured: boolean; valid: boolean; text: string; usage: ObservedUsage; reportedModel?: string | null } {
+  const lines = stdout.split(/\r?\n/).filter((line) => line.trim());
+  const events: Record<string, unknown>[] = []; let malformed = false; let recognized = false;
+  const types = new Set(['thread.started', 'turn.started', 'turn.completed', 'turn.failed', 'item.started', 'item.updated', 'item.completed', 'error']);
+  for (const line of lines) {
+    if (/"type"\s*:\s*"(?:thread\.|turn\.|item\.|error")/.test(line)) recognized = true;
+    try { const event = JSON.parse(line) as Record<string, unknown>;
+      if (event && typeof event === 'object' && typeof event['type'] === 'string' && (types.has(event['type']) || /^(thread|turn|item)\./.test(event['type']))) recognized = true;
+      events.push(event);
+    } catch { malformed = true; }
+  }
+  if (!recognized) return { structured: false, valid: true, text: stdout.trim(), usage: emptyUsage() };
+  const result = emptyUsage(); let failedTerminal = false; let text = ''; let threadId: string | null = null; const terminals: Record<string, unknown>[] = []; const reportedModels = new Set<string>();
+  for (const event of events) {
+    if (!event || typeof event !== 'object' || !types.has(String(event['type']))) { malformed = true; continue; }
+    if (typeof event['model'] === 'string' && event['model'].trim()) reportedModels.add(event['model']);
+    if (event['type'] === 'thread.started' && typeof event['thread_id'] === 'string') { if (threadId !== null && threadId !== event['thread_id']) malformed = true; threadId = event['thread_id']; }
+    if (event['type'] === 'item.completed' && event['item'] && typeof event['item'] === 'object') {
+      const item = event['item'] as Record<string, unknown>; if (item['type'] === 'agent_message' && typeof item['text'] === 'string') text = item['text'];
     }
-    if (obj === null || typeof obj !== 'object') continue;
-    const u = (obj as Record<string, unknown>)['usage'];
-    if (u !== null && typeof u === 'object' && !Array.isArray(u)) usage = u as Record<string, unknown>;
+    if (event['type'] === 'turn.completed' || (event['type'] === 'turn.failed' && event['usage'] != null)) terminals.push(event);
+    if (event['type'] === 'turn.failed' || event['type'] === 'error') failedTerminal = true;
+  }
+  const distinct = new Set(terminals.map((v) => { const u = v['usage'] && typeof v['usage'] === 'object' ? v['usage'] as Record<string,unknown> : {}; return JSON.stringify([v['turn_id'] ?? null, ...['input_tokens','cached_input_tokens','cache_write_input_tokens','output_tokens','reasoning_output_tokens','total_tokens'].map((key) => u[key] ?? null)]); }));
+  if (distinct.size !== 1) { malformed = true; result.usageDiagnostics!.push(distinct.size === 0 ? 'terminal-usage-unavailable' : 'conflicting-terminal-usage'); }
+  if (distinct.size === 1) {
+    const terminal = terminals[0]!; const raw = terminal['usage'];
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+      const usage = raw as Record<string, unknown>;
+      result.tokensIn = count(usage['input_tokens']); result.tokensOut = count(usage['output_tokens']);
+      result.tokensCacheRead = count(usage['cached_input_tokens']); result.tokensCacheWrite = count(usage['cache_write_input_tokens']);
+      result.tokensReasoning = count(usage['reasoning_output_tokens']);
+      const derived = result.tokensIn !== null && result.tokensOut !== null ? count(result.tokensIn + result.tokensOut) : null;
+      result.tokensTotal = count(usage['total_tokens']) ?? derived;
+      result.totalDerivation = count(usage['total_tokens']) !== null ? 'reported' : derived === null ? 'not-recorded' : 'input-plus-output';
+      if (derived !== null && result.tokensTotal !== derived) result.usageDiagnostics!.push('total-split-mismatch');
+      if (result.tokensCacheRead != null && result.tokensIn != null && result.tokensCacheRead > result.tokensIn) result.usageDiagnostics!.push('cache-exceeds-input');
+      if (result.tokensReasoning != null && result.tokensOut != null && result.tokensReasoning > result.tokensOut) result.usageDiagnostics!.push('reasoning-exceeds-output');
+      for (const [key, value] of Object.entries(usage)) if (key.endsWith('_tokens') && count(value) === null) result.usageDiagnostics!.push('invalid-counter:' + key);
+      result.tokensSource = 'codex-json'; result.reportedTotalBasis = 'raw-inclusive'; result.inputCacheSemantics = 'includes-cache-read-write';
+      result.usageSource = { schema: 'codex-exec-json', scope: 'terminal-turn', threadId, turnId: typeof terminal['turn_id'] === 'string' ? terminal['turn_id'] : null, receiptId: null };
+    } else malformed = true;
   }
-  if (usage === null) return { tokensIn: null, tokensOut: null };
-  const pick = (k: string): number | null => {
-    const v = usage?.[k];
-    return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : null;
+  if (malformed) result.usageDiagnostics!.push('malformed-event-stream');
+  if (failedTerminal) result.usageDiagnostics!.push('runtime-turn-failed');
+  if (reportedModels.size > 1) result.usageDiagnostics!.push('provider-model-mismatch');
+  return { structured: true, valid: !malformed && !failedTerminal, text, usage: result, reportedModel: reportedModels.size === 1 ? [...reportedModels][0]! : null };
+}
+
+/** Observe the existing wrapper seam; this does not attest OS child start. */
+function collectProbeMetadata(family: BridgeFamily) {
+  const attempts: NonNullable<ProbeOutcome['provenance']>['attempts'] = [];
+  let totalConsidered = 0;
+  let invalid: Exclude<ProbeOutcome['provenanceReason'], undefined> = null;
+  return {
+    record(id: string, wrapperInvoked: boolean, r: ChildRun | null, selected: boolean) {
+      const ordinal = ++totalConsidered;
+      if (wrapperInvoked && (typeof id !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(id))) invalid = 'candidate-model-invalid';
+      let reason: NonNullable<ProbeOutcome['provenance']>['attempts'][number]['reason'] = 'invalid-candidate';
+      if (r !== null) {
+        const typed = typeof r.stdout === 'string' && typeof r.stderr === 'string' && typeof r.timedOut === 'boolean'
+          && (r.exitCode === null || (Number.isSafeInteger(r.exitCode) && r.exitCode >= 0))
+          && (r.spawnError === null || (typeof r.spawnError === 'string' && r.spawnError.length > 0));
+        const consistent = typed && !(r.timedOut && (r.spawnError !== null || r.exitCode === 0))
+          && !(r.spawnError !== null && r.exitCode !== null) && !(selected && (r.timedOut || r.spawnError !== null || r.exitCode !== 0));
+        if (!consistent && invalid !== 'candidate-model-invalid') invalid = 'wrapper-result-invalid';
+        reason = r.timedOut ? 'timeout' : r.spawnError !== null ? 'spawn-error' : r.exitCode === null ? 'no-exit-code'
+          : r.exitCode !== 0 ? 'exit-nonzero' : selected ? 'answered' : 'unexpected-response';
+      }
+      if (ordinal <= 32) attempts.push({ ordinal, model: wrapperInvoked ? id : null, family, wrapperInvoked,
+        outcome: !wrapperInvoked ? 'rejected' : selected ? 'answered' : 'failed', reason, selected });
+    },
+    finish(): Pick<ProbeOutcome, 'provenance' | 'provenanceReason'> {
+      return { provenance: invalid === null ? { schema: 'wf-probe-attempts-1', complete: totalConsidered <= 32, totalConsidered, attempts } : null,
+        provenanceReason: invalid };
+    },
   };
-  return { tokensIn: pick('input_tokens'), tokensOut: pick('output_tokens') };
 }
 
 // ── the adapter factories (pure over the injected ChildRunner) ───────────────────────────────────
@@ -264,6 +387,7 @@ function failed(family: BridgeFamily, model: string | null, wallMs: number, reas
     text: null,
     family,
     modelUsed: model,
+    modelProvenance: 'probed-request',
     wallMs,
     tokensIn: null,
     tokensOut: null,
@@ -294,12 +418,16 @@ export function makeCodexExecDispatcher(run: ChildRunner, opts?: { bin?: string;
       const t0 = clock();
       const list = candidates.length > 0 ? candidates : ['gpt-5.5'];
       const started: string[] = [];
+      const observation = collectProbeMetadata('openai');
       for (const id of list) {
+        const wrapperInvoked = true;
         const r = await run(bin, codexProbeArgv(id), { stdinText: null, timeoutMs: 120_000, cwd: isolatedCwd(), detached: true });
         started.push(id);
-        if (interpretCodexProbe(r)) return { id, wallMs: clock() - t0, detail: `codex answered on ${id}` };
+        const selected = interpretCodexProbe(r);
+        observation.record(id, wrapperInvoked, r, selected);
+        if (selected) return { id, wallMs: clock() - t0, detail: `codex answered on ${id}`, ...observation.finish() };
       }
-      return { id: null, wallMs: clock() - t0, detail: `no codex candidate answered a probe (tried: ${started.join(', ')}) — an allowlist says an id is spellable, only a probe says it answers` };
+      return { id: null, wallMs: clock() - t0, detail: `no codex candidate answered a probe (tried: ${started.join(', ')}) — an allowlist says an id is spellable, only a probe says it answers`, ...observation.finish() };
     },
     dispatch: async (req) => {
       const t0 = clock();
@@ -314,25 +442,15 @@ export function makeCodexExecDispatcher(run: ChildRunner, opts?: { bin?: string;
         cwd: req.cwd,
         detached: true,
       });
+      const parsed = codexStructuredOutput(String(r.stdout ?? ''));
+      const usage = parsed.structured ? parsed.usage : extractCodexTokens(r.stderr);
       const cls = classifyChildRun(r);
-      if (cls.kind === 'timeout') return failed('openai', req.resolvedModelId, req.timeoutMs, 'dispatch-timeout', `the ${req.timeoutMs}ms deadline fired on step ${req.stepId}`);
-      if (cls.kind === 'dead') return failed('openai', req.resolvedModelId, clock() - t0, 'dispatch-dead', cls.detail);
-      const text = String(r.stdout ?? '').trim();
-      if (cls.exitCode !== 0 || text === '') {
-        return failed('openai', req.resolvedModelId, clock() - t0, 'dispatch-dead',
-          `codex exited ${cls.exitCode} with ${text === '' ? 'NO stdout' : String(text.length) + ' chars of stdout'} — a clean exit with nothing to read is the spawned-but-mute case, not an empty success`);
-      }
-      const tokens = extractCodexTokens(r.stderr);
-      return {
-        outcome: 'ok',
-        text,
-        family: 'openai',
-        modelUsed: req.resolvedModelId,
-        wallMs: clock() - t0,
-        tokensIn: tokens.tokensIn,
-        tokensOut: tokens.tokensOut,
-        tokensSource: tokens.tokensIn === null && tokens.tokensOut === null ? null : 'codex-stderr',
-      };
+      if (cls.kind === 'timeout') return { ...failed('openai', req.resolvedModelId, req.timeoutMs, 'dispatch-timeout', `the ${req.timeoutMs}ms deadline fired on step ${req.stepId}`), ...usage };
+      if (cls.kind === 'dead') return { ...failed('openai', req.resolvedModelId, clock() - t0, 'dispatch-dead', cls.detail), ...usage };
+      if (cls.exitCode !== 0 || !parsed.valid || parsed.text === '') return { ...failed('openai', req.resolvedModelId, clock() - t0, 'dispatch-dead', 'Codex exited nonzero, had an invalid structured event stream, or was spawned-but-mute with no final text'), ...usage };
+      return { outcome: 'ok', text: parsed.text, family: 'openai', modelUsed: parsed.reportedModel ?? req.resolvedModelId,
+        modelProvenance: parsed.reportedModel ? 'provider-reported' : 'probed-request', wallMs: clock() - t0, ...usage };
+
     },
   };
 }
@@ -358,14 +476,18 @@ export function makeClaudePDispatcher(run: ChildRunner, opts?: { bin?: string; i
       const t0 = clock();
       const list = candidates.length > 0 ? candidates : ['sonnet'];
       const tried: string[] = [];
+      const observation = collectProbeMetadata('claude');
       for (const id of list) {
         const argv = claudeProbeArgs(id);
         tried.push(id);
-        if (argv === null) continue; // an unsafe id is not spellable, let alone answerable
+        if (argv === null) { observation.record(id, false, null, false); continue; } // existing unsafe rejection
+        const wrapperInvoked = true;
         const r = await run(bin, argv, { stdinText: null, timeoutMs: 120_000, cwd: isolatedCwd(), detached: true });
-        if (interpretClaudeProbe({ stdout: r.stdout, exitCode: r.exitCode ?? 1 })) return { id, wallMs: clock() - t0, detail: `claude answered on ${id}` };
+        const selected = interpretClaudeProbe({ stdout: r.stdout, exitCode: r.exitCode ?? 1 });
+        observation.record(id, wrapperInvoked, r, selected);
+        if (selected) return { id, wallMs: clock() - t0, detail: `claude answered on ${id}`, ...observation.finish() };
       }
-      return { id: null, wallMs: clock() - t0, detail: `no claude candidate answered a probe (tried: ${tried.join(', ')})` };
+      return { id: null, wallMs: clock() - t0, detail: `no claude candidate answered a probe (tried: ${tried.join(', ')})`, ...observation.finish() };
     },
     dispatch: async (req) => {
       const t0 = clock();
@@ -380,33 +502,15 @@ export function makeClaudePDispatcher(run: ChildRunner, opts?: { bin?: string; i
         cwd: fileMode ? req.cwd : isolatedCwd(),
         detached: true,
       });
+      const usage = extractClaudeUsage(r.stdout);
       const cls = classifyChildRun(r);
-      if (cls.kind === 'timeout') return failed('claude', req.resolvedModelId, req.timeoutMs, 'dispatch-timeout', `the ${req.timeoutMs}ms deadline fired on step ${req.stepId}`);
-      if (cls.kind === 'dead') return failed('claude', req.resolvedModelId, clock() - t0, 'dispatch-dead', cls.detail);
-      // The EXIT CODE and the ENVELOPE must agree (Step-8 HIGH-10). A parseable success envelope
-      // from a process that exited nonzero is a CONTRADICTION, not a success: the runtime told us
-      // twice and the two answers differ, so believing the friendlier one is how a failed dispatch
-      // becomes a green step. The codex adapter already required exit 0; this one did not.
-      if (cls.exitCode !== 0) {
-        return failed('claude', req.resolvedModelId, clock() - t0, 'dispatch-dead',
-          `claude exited ${cls.exitCode} — a nonzero exit is a failed dispatch even when stdout carries a parseable success envelope; the two disagree and the exit code is the runtime's own verdict`);
-      }
+      if (cls.kind === 'timeout') return { ...failed('claude', req.resolvedModelId, req.timeoutMs, 'dispatch-timeout', `the ${req.timeoutMs}ms deadline fired on step ${req.stepId}`), ...usage };
+      if (cls.kind === 'dead') return { ...failed('claude', req.resolvedModelId, clock() - t0, 'dispatch-dead', cls.detail), ...usage };
+      if (cls.exitCode !== 0) return { ...failed('claude', req.resolvedModelId, clock() - t0, 'dispatch-dead', `claude exited ${cls.exitCode} — a nonzero exit is a failed dispatch even with a success envelope`), ...usage };
       const env = extractClaudeResult(r.stdout);
-      if (!env.ok) {
-        return failed('claude', req.resolvedModelId, clock() - t0, 'dispatch-dead',
-          `claude exited ${cls.exitCode} but the reply is not readable as a result envelope: ${env.detail}`);
-      }
-      const usage = extractClaudeUsage(r.stdout);
-      return {
-        outcome: 'ok',
-        text: env.text,
-        family: 'claude',
-        modelUsed: req.resolvedModelId,
-        wallMs: clock() - t0,
-        tokensIn: usage.tokensIn,
-        tokensOut: usage.tokensOut,
-        tokensSource: usage.tokensIn === null && usage.tokensOut === null ? null : 'claude-envelope',
-      };
+      if (!env.ok) return { ...failed('claude', req.resolvedModelId, clock() - t0, 'dispatch-dead', `reply is not readable as a result envelope: ${env.detail}`), ...usage };
+      return { outcome: 'ok', text: env.text, family: 'claude', modelUsed: req.resolvedModelId, modelProvenance: 'probed-request', wallMs: clock() - t0, ...usage };
+
     },
   };
 }

package/src/workflow-run.ts

@@ -43,7 +43,7 @@ import { classifyFailure, errSnap, gateVerdict, joinRegion, stepContractLines, t
 import { checkpointInputHash, decideCheckpointResume, parseCheckpointRead, serializeCheckpoint } from './feature-adr-checkpoints.js';
 import { modelFamily, type BridgeFamily } from './qe-bridge.js';
 import { buildReqeDebt } from './reqe.js';
-import { CODEX_EXEC_XHIGH_TIMEOUT_MS, defangGateEchoes, type DispatchResult, type Dispatcher } from './workflow-run-dispatch.js';
+import { CODEX_EXEC_XHIGH_TIMEOUT_MS, defangGateEchoes, type DispatchResult, type Dispatcher, type ProbeOutcome } from './workflow-run-dispatch.js';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Schemas / constants
@@ -164,7 +164,8 @@ export interface WfRunState {
   dispatcherOverride?: boolean;
 }
 
-export interface WfBudgetRow {
+export interface WfBudgetRow extends Pick<DispatchResult, 'tokensTotal' | 'tokensCacheRead' | 'tokensCacheWrite' | 'tokensReasoning' | 'reportedTotalBasis' | 'inputCacheSemantics' | 'reportedCostUsd' | 'usageDiagnostics' | 'usageSource' | 'totalDerivation'> {
+  projectRoot?: string;
   schema: typeof WF_BUDGET_ROW_SCHEMA;
   kind: 'stage' | 'probe';
   runId: string;
@@ -175,10 +176,23 @@ export interface WfBudgetRow {
   attempt: number | null;
   family: BridgeFamily;
   model: string | null;
+  modelProvenance?: string;
+  requestedModel?: string | null;
+  plannedModel?: string | null;
+  plannedModelSource?: 'plan-declared' | 'plan-omitted' | 'unavailable';
+  probeId?: string | null;
+  probeProvenance?: Exclude<ProbeOutcome['provenance'], undefined>;
+  probeSource?: 'dispatcher-child-seam' | 'scripted-dispatcher';
+  probeObservationReason?: 'producer-not-recorded' | 'id-factory-missing' | 'id-factory-invalid' | 'provenance-invalid' | 'candidate-model-invalid' | 'wrapper-result-invalid' | 'selected-model-invalid' | null;
   wallMs: number;
   tokensIn: number | null;
   tokensOut: number | null;
-  tokensSource: 'claude-envelope' | 'codex-stderr' | null;
+  tokensSource: DispatchResult['tokensSource'];
+  phase?: string | null;
+  role?: string | null;
+  tier?: string | null;
+  mode?: string | null;
+  estimate?: unknown;
   outcome: 'ok' | 'null' | 'error' | null;
   timeoutMs: number | null;
 }
@@ -239,6 +253,7 @@ export interface RunnerInputs {
   wallClockExtraMs: number | null;
   runnerVersion: string;
   cwdRoot: string;
+  projectRoot?: string;
 }
 
 /** Small, dependency-free 64-bit FNV — the same shape the checkpoint plane uses, kept local so this
@@ -927,6 +942,35 @@ export interface RunStore {
   writeReqeDebt(record: object): void;
 }
 
+const safeRoutingModel = (value: unknown): value is string => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(value);
+function probeRecordReason(probe: ProbeOutcome, family: BridgeFamily): Exclude<WfBudgetRow['probeObservationReason'], undefined> {
+  const exact = (value: unknown, keys: string[]): value is Record<string, unknown> => value !== null && typeof value === 'object'
+    && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+    && Reflect.ownKeys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+  if (probe.id !== null && !safeRoutingModel(probe.id)) return 'selected-model-invalid';
+  const present = [Object.hasOwn(probe, 'provenance'), Object.hasOwn(probe, 'provenanceReason')];
+  if (present.every(value => !value)) return 'producer-not-recorded';
+  if (!present.every(Boolean)) return 'provenance-invalid';
+  if (probe.provenance === null && (probe.provenanceReason === 'candidate-model-invalid' || probe.provenanceReason === 'wrapper-result-invalid')) return probe.provenanceReason;
+  const p = probe.provenance;
+  if (probe.provenanceReason !== null || !exact(p, ['schema', 'complete', 'totalConsidered', 'attempts']) || p.schema !== 'wf-probe-attempts-1'
+    || typeof p.complete !== 'boolean' || !Number.isSafeInteger(p.totalConsidered) || p.totalConsidered <= 0 || !Array.isArray(p.attempts)
+    || p.attempts.length !== Math.min(p.totalConsidered, 32) || p.complete !== (p.totalConsidered <= 32)) return 'provenance-invalid';
+  for (const [index, a] of p.attempts.entries()) {
+    if (!exact(a, ['ordinal', 'model', 'family', 'wrapperInvoked', 'outcome', 'reason', 'selected']) || a.ordinal !== index + 1
+      || a.family !== family || typeof a.wrapperInvoked !== 'boolean' || typeof a.selected !== 'boolean') return 'provenance-invalid';
+    const rejected = family === 'claude' && !a.wrapperInvoked && !a.selected && a.model === null && a.outcome === 'rejected' && a.reason === 'invalid-candidate';
+    const answered = a.wrapperInvoked && a.selected && safeRoutingModel(a.model) && a.outcome === 'answered' && a.reason === 'answered';
+    const failed = a.wrapperInvoked && !a.selected && safeRoutingModel(a.model) && a.outcome === 'failed'
+      && ['timeout', 'spawn-error', 'no-exit-code', 'exit-nonzero', 'unexpected-response'].includes(a.reason);
+    if (!(rejected || answered || failed)) return 'provenance-invalid';
+  }
+  const selected = p.attempts.filter(a => a.selected);
+  if (!p.complete ? selected.length !== 0 : probe.id === null ? selected.length !== 0
+    : selected.length !== 1 || selected[0]?.ordinal !== p.totalConsidered || selected[0]?.model !== probe.id) return 'provenance-invalid';
+  return null;
+}
+
 export interface SchedulerDeps {
   store: RunStore;
   dispatchers: Record<BridgeFamily, Dispatcher>;
@@ -935,6 +979,7 @@ export interface SchedulerDeps {
   /** Injected ISO clock (determinism, NFR-2). */
   now(): string;
   monotonicMs(): number;
+  newProbeId?: () => string;
   /**
    * TEST SEAM (named, never a casual flag): disables the landed barrier so the F5 mutant can show
    * the lying file-step passing. Default false; a run that sets it records `dispatcherOverride`.
@@ -978,6 +1023,7 @@ function failureClassOf(res: DispatchResult): FailureClass | null {
 }
 
 interface RunCtx {
+  probeIds: Partial<Record<BridgeFamily, string | null>>;
   inputs: RunnerInputs;
   pre: PreflightOk;
   deps: SchedulerDeps;
@@ -1053,16 +1099,36 @@ export async function runWorkflow(inputs: RunnerInputs, pre: PreflightOk, deps:
 
   const usedFamilies = [...new Set(Object.values(pre.families))];
   const probedIds: Partial<Record<BridgeFamily, string | null>> = {};
+  const probeIds: Partial<Record<BridgeFamily, string | null>> = {};
   let probeAgentCalls = 0;
   const probeDetail: Partial<Record<BridgeFamily, string>> = {};
   for (const family of usedFamilies) {
     const candidates = [...new Set(allSpecs(pre.projection).filter((s) => pre.families[s.stepId] === family).map((s) => s.model).filter((m): m is string => typeof m === 'string'))];
     const probe = await deps.dispatchers[family].probe(candidates);
     probeAgentCalls++;
+    let probeId: string | null = null;
+    let idReason: Exclude<WfBudgetRow['probeObservationReason'], undefined> = 'id-factory-missing';
+    if (deps.newProbeId) {
+      try {
+        const id = deps.newProbeId();
+        if (typeof id === 'string' && /^[0-9a-f]{32}$/.test(id)) {
+          probeId = id;
+          idReason = null;
+        } else idReason = 'id-factory-invalid';
+      } catch { idReason = 'id-factory-invalid'; }
+    }
+    const producerReason = probeRecordReason(probe, family);
+    const probeObservationReason = producerReason && producerReason !== 'producer-not-recorded' ? producerReason : idReason ?? producerReason;
+    probeIds[family] = probeId;
     store.appendBudgetRow({
       schema: WF_BUDGET_ROW_SCHEMA,
       kind: 'probe',
+      probeId,
+      probeProvenance: probeObservationReason === null ? probe.provenance! : null,
+      probeSource: deps.dispatcherOverride ? 'scripted-dispatcher' : 'dispatcher-child-seam',
+      probeObservationReason,
       runId: inputs.runId,
+      projectRoot: inputs.projectRoot ?? inputs.cwdRoot,
       dispatchSeq: null,
       stepId: null,
       itemKey: null,
@@ -1073,6 +1139,14 @@ export async function runWorkflow(inputs: RunnerInputs, pre: PreflightOk, deps:
       tokensIn: null,
       tokensOut: null,
       tokensSource: null,
+      tokensTotal: null,
+      tokensCacheRead: null,
+      tokensCacheWrite: null,
+      tokensReasoning: null,
+      reportedTotalBasis: 'unknown',
+      inputCacheSemantics: 'unknown',
+      reportedCostUsd: null,
+      usageDiagnostics: ['probe-usage-not-recorded'],
       outcome: null,
       timeoutMs: null,
     });
@@ -1189,6 +1263,7 @@ export async function runWorkflow(inputs: RunnerInputs, pre: PreflightOk, deps:
 
   const opened = openTrace(inputs, pre, store, inputs.resume !== null);
   const ctx: RunCtx = {
+    probeIds,
     inputs,
     pre,
     deps,
@@ -1500,16 +1575,37 @@ async function dispatchOnce(
       schema: WF_BUDGET_ROW_SCHEMA,
       kind: 'stage',
       runId: ctx.inputs.runId,
+      projectRoot: ctx.inputs.projectRoot ?? ctx.inputs.cwdRoot,
       dispatchSeq,
       stepId: spec.stepId,
       itemKey,
       attempt,
       family,
-      model: res.modelUsed ?? model,
+      model: res.modelUsed,
+      requestedModel: model,
+      plannedModel: safeRoutingModel(spec.model) ? spec.model : null,
+      plannedModelSource: safeRoutingModel(spec.model) ? 'plan-declared' : spec.model == null ? 'plan-omitted' : 'unavailable',
+      probeId: ctx.probeIds[family] ?? null,
+      modelProvenance: res.modelProvenance ?? (res.modelUsed === null ? 'not-recorded' : 'dispatcher-reported'),
       wallMs,
       tokensIn: res.tokensIn,
       tokensOut: res.tokensOut,
       tokensSource: res.tokensSource,
+      tokensTotal: res.tokensTotal ?? null,
+      totalDerivation: res.totalDerivation ?? 'not-recorded',
+      tokensCacheRead: res.tokensCacheRead ?? null,
+      tokensCacheWrite: res.tokensCacheWrite ?? null,
+      tokensReasoning: res.tokensReasoning ?? null,
+      reportedTotalBasis: res.reportedTotalBasis ?? 'unknown',
+      inputCacheSemantics: res.inputCacheSemantics ?? 'unknown',
+      reportedCostUsd: res.reportedCostUsd ?? null,
+      usageDiagnostics: res.usageDiagnostics ?? [],
+      ...(res.usageSource !== undefined ? { usageSource: res.usageSource } : {}),
+      phase: spec.phase,
+      role: spec.role ?? null,
+      tier: spec.tier ?? null,
+      mode: spec.mode ?? null,
+      estimate: spec.estimate ?? null,
       outcome,
       timeoutMs,
     });
@@ -1699,7 +1795,7 @@ function appendLedger(ctx: RunCtx, outcome: string): void {
     outcome,
     date: null,
   });
-  if (line !== null) ctx.deps.store.appendLedgerLine(line);
+  if (line !== null) ctx.deps.store.appendLedgerLine(JSON.stringify({ ...JSON.parse(line), summary: true, sourceProjection: 'workflow-budget', workflowRunId: ctx.inputs.runId }));
 }
 
 /** PAUSE — flush WITHOUT `run.closed` (parity with the render's top-level terminal return, which