@relayflows/sdk 2.0.11 → 2.0.13

package/src/preflight.ts

@@ -8,6 +8,7 @@ import type { TriggerSource } from '@relayflows/surface';
 import { acceptsAnyOutput, inspectStepGate, type StepGateInspection } from './gate-contract.js';
 import { compileSpec, CompileError } from './compile.js';
 import { helperCall } from './yaml-helpers.js';
+import { resolveCliModelSelection, type CliModelSource } from './cli-adapter.js';
 import { isNamedGate, NAMED_GATE_FAILURE_KINDS, type NamedGateFailureKind } from './named-gates.js';
 import { compileScopes, type ScopeInput, type MountRegistry } from './scope-compiler.js';
 import { readMountRegistry } from './mount-registry.js';
@@ -22,8 +23,10 @@ export interface CliResolution {
   stepId: string;
   cli: string;
   source: CliResolutionSource;
-  /** Model the step or selected named agent declared, probed with the CLI. */
+  /** Effective model probed with the CLI. */
   model?: string;
+  /** Exact source selected by step > named agent > adapter default priority. */
+  modelSource?: CliModelSource;
 }
 
 export interface CliProbeResult {
@@ -114,6 +117,11 @@ export type PreflightDiagnostic = PreflightRefusal | PreflightWarning;
 export interface PreflightResult {
   plugins?: readonly LoadedPlugin[];
   mcpTools?: Readonly<Record<string, readonly string[]>>;
+  /**
+   * True when no diagnostic is a refusal. `ok: true` may still carry warnings
+   * (e.g. `budget_unmetered`); callers that report to a person must surface
+   * `diagnostics`, not just branch on `ok`.
+   */
   ok: boolean;
   gates: StepGateInspection[];
   resolutions: CliResolution[];
@@ -208,18 +216,17 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
     };
   }
   const diagnostics: PreflightDiagnostic[] = [];
+  const cliResolutionDiagnostics: PreflightDiagnostic[] = [];
   const resolutions: CliResolution[] = [];
   const resolutionByStep = new Map<string, CliResolution>();
   const cliProbeResults = new Map<string, CliProbeOutcome>();
 
-  diagnostics.push(...unknownModelDiagnostics(compiled, options));
   diagnostics.push(...scopeDiagnostics(compiled, options));
   for (const server of new Set(options.mcpServers ?? [])) {
     if (options.mcp !== undefined && Object.hasOwn(options.mcp, server)) continue;
     diagnostics.push({ severity: 'refusal', kind: 'mcp_undeclared_server', server,
       message: `MCP server "${server}" is not declared in the nearest flows.json mcp map.` });
   }
-  diagnostics.push(...budgetDiagnostics(compiled));
   // Resolve the complete flow before touching any environment fact. A later
   // statically unresolved CLI makes the whole submission impossible, so no
   // earlier command, provider/model, or trigger probe may run first.
@@ -228,7 +235,7 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
     if (step.type === 'agent' && helperCall(step) !== undefined) continue;
     const resolution = resolveCli(step, compiled, options.projectCli);
     if (resolution === undefined) {
-      diagnostics.push({
+      cliResolutionDiagnostics.push({
         severity: 'refusal',
         kind: 'cli_unresolved',
         stepId: step.id,
@@ -239,7 +246,19 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
       resolutionByStep.set(step.id, resolution);
     }
   }
-  if (diagnostics.length > 0) {
+  diagnostics.push(...cliResolutionDiagnostics);
+  if (cliResolutionDiagnostics.length > 0) {
+    return { ok: false, gates: compiled.steps.map(inspectStepGate), resolutions, diagnostics };
+  }
+  diagnostics.push(...unknownModelDiagnostics(compiled, options, resolutionByStep));
+  diagnostics.push(...budgetDiagnostics(
+    compiled,
+    new Map(resolutions.map(resolution => [resolution.stepId, {
+      cli: resolution.cli,
+      ...(resolution.model === undefined ? {} : { model: resolution.model }),
+    }])),
+  ));
+  if (diagnostics.some((diagnostic) => diagnostic.severity === 'refusal')) {
     return { ok: false, gates: compiled.steps.map(inspectStepGate), resolutions, diagnostics };
   }
 
@@ -311,6 +330,7 @@ function scopeDiagnostics(flow: FlowSpec, options: PreflightOptions): PreflightR
 function unknownModelDiagnostics(
   flow: FlowSpec,
   options: PreflightOptions,
+  resolutionByStep: ReadonlyMap<string, CliResolution> = new Map(),
 ): PreflightRefusal[] {
   const diagnostics: PreflightRefusal[] = [];
   // model_unknown is a governance check: it exists to enforce a project's
@@ -340,16 +360,21 @@ function unknownModelDiagnostics(
   }
 
   for (const step of flow.steps) {
-    if (step.type === 'deterministic' || step.model === undefined) continue;
-    if (isKnownModel(step.model, options.models)) continue;
-    const resolution = resolveCli(step, flow, options.projectCli);
+    if (step.type === 'deterministic') continue;
+    const resolution = resolutionByStep.get(step.id);
+    // Selected named declarations were checked once above, including unused
+    // declarations. Other sources are step declarations or adapter defaults.
+    if (resolution?.modelSource === 'named') continue;
+    const model = resolution?.model ?? step.model;
+    if (model === undefined || isKnownModel(model, options.models)) continue;
+    if (!enforceRegistry) continue;
     diagnostics.push({
       severity: 'refusal',
       kind: 'model_unknown',
       stepId: step.id,
       ...(resolution === undefined ? {} : { cli: resolution.cli }),
-      model: step.model,
-      message: unknownModelMessage(step.id, step.model, resolution?.cli, options.modelRegistryPath),
+      model,
+      message: unknownModelMessage(step.id, model, resolution?.cli, options.modelRegistryPath),
     });
   }
 
@@ -402,14 +427,16 @@ function resolveCli(
   const named = step.type === 'agent' && step.agent !== undefined
     ? flow.agents?.[step.agent]
     : undefined;
-  // Model comes only from the step or its explicitly selected declaration.
-  // There is deliberately no flow/project or host default.
-  const effectiveModel = step.model ?? named?.model;
-  const model = effectiveModel !== undefined ? { model: effectiveModel } : {};
-  if (step.cli !== undefined) return { stepId: step.id, cli: step.cli, source: 'step', ...model };
-  if (named !== undefined) return { stepId: step.id, cli: named.cli, source: 'named', ...model };
-  if (flow.cli !== undefined) return { stepId: step.id, cli: flow.cli, source: 'flow', ...model };
-  if (projectCli !== undefined) return { stepId: step.id, cli: projectCli, source: 'project', ...model };
+  const resolved = (cli: string, source: CliResolutionSource): CliResolution => {
+    const effectiveModel = resolveCliModelSelection(cli, { step: step.model, named: named?.model });
+    return { stepId: step.id, cli, source,
+      ...(effectiveModel.model === undefined ? {} : { model: effectiveModel.model }),
+      ...(effectiveModel.source === undefined ? {} : { modelSource: effectiveModel.source }) };
+  };
+  if (step.cli !== undefined) return resolved(step.cli, 'step');
+  if (named !== undefined) return resolved(named.cli, 'named');
+  if (flow.cli !== undefined) return resolved(flow.cli, 'flow');
+  if (projectCli !== undefined) return resolved(projectCli, 'project');
   return undefined;
 }
 

package/src/protocol.ts

@@ -72,11 +72,26 @@ export interface HelloResult {
 export interface StepSpend {
   tokens_input: number;
   tokens_output: number;
+  /** Metered dollars; a lower bound when `dollars_unmetered` is set. */
   dollars: number;
+  /** Present (true) only when the step spent tokens of unknown dollar cost. */
+  dollars_unmetered?: true;
   wallclock_ms: number;
 }
 
+/**
+ * Worker-reported `step.complete` usage. A priced step reports exact
+ * `dollars`; a step whose model has no frozen price reports its tokens with
+ * `dollars_unmetered: true` and no dollar amount, so unknown cost is never
+ * journaled as a measured $0. See `workerSpend` for the full contract.
+ */
+export type StepUsage =
+  | { tokens_in: number; tokens_out: number; dollars: string; dollars_unmetered?: never }
+  | { tokens_in: number; tokens_out: number; dollars_unmetered: true; dollars?: never };
+
 export interface RunStartParams {
+  /** Caller-owned retry identity. Reuse with a different spec is refused. */
+  admission_key?: string;
   reuse_from_run_id?: string;
   /**
    * The kernel spec dialect — the ONE boundary shape `RunSpec::parse`
@@ -128,7 +143,7 @@ export interface RunGetResult {
   run_id: string;
   status: RunStatus;
   steps: Record<string, StepSnapshot>;
-  budget: { tokens_in: number; tokens_out: number; dollars: string };
+  budget: { tokens_in: number; tokens_out: number; dollars: string; dollars_unmetered?: true };
 }
 
 export interface RunWatchParams {
@@ -305,7 +320,7 @@ export interface StepCompleteParams {
   idempotency_key: string;
   completionReason: CompletionReason;
   output?: unknown;
-  usage?: { tokens_in: number; tokens_out: number; dollars: string };
+  usage?: StepUsage;
   started_pins?: Pins;
   end_pins?: Pins;
   effects?: EffectRef[];

package/src/spec.ts

@@ -238,10 +238,11 @@ export interface AgentStepSpec extends BaseStepSpec {
   /** Inert preflight declaration; overrides the flow/project CLI default. */
   cli?: string;
   /**
-   * Model the declared CLI must use. Raw Claude/Codex adapters receive their
-   * real model flag; an identified Relayflows wrapper receives it in its
-   * same-process execution request. Declared here so the choice is journaled with the step
-   * instead of being ambient host state.
+   * Model the declared CLI must use. A step declaration wins over its selected
+   * named agent and any registered adapter default. Raw Claude/Codex adapters
+   * receive the effective model as a real flag; an identified Relayflows
+   * wrapper receives an explicitly declared model in its same-process request.
+   * The effective choice is journaled instead of being ambient host state.
    */
   model?: string;
   surfaces?: AgentSurfaces;
@@ -451,9 +452,31 @@ export interface KernelAgentStep extends KernelStepCommon {
 
 export type KernelStepSpec = KernelDeterministicStep | KernelLlmStep | KernelAgentStep;
 
+/**
+ * Accounting carried into a run that continues an earlier one. The authored
+ * executor lowers each step to its own kernel run and sends the previous run's
+ * totals here. It mirrors the kernel's `PriorSpend` field for field, so the
+ * handoff cannot quietly narrow what a carried budget can express.
+ */
+export interface KernelPriorSpend {
+  tokens_in: number;
+  tokens_out: number;
+  /** Metered dollars only; a lower bound when `dollars_unmetered` is set. */
+  dollars: string;
+  wallclock_ms: number;
+  day?: number;
+  /**
+   * At least one carried charge spent tokens of unknown dollar cost, so
+   * `dollars` is a lower bound rather than a measured total. Omitted when
+   * false, so a fully metered flow's payload keeps its exact bytes and a
+   * kernel that predates the key never receives it.
+   */
+  dollars_unmetered?: boolean;
+}
+
 export interface KernelBudgetSpec {
   pricing?: 'frozen';
-  prior_spend?: { tokens_in: number; tokens_out: number; dollars: string; wallclock_ms: number; day?: number };
+  prior_spend?: KernelPriorSpend;
   max_tokens?: number;
   max_wallclock_ms?: number;
   window?: 'day';

package/src/worker-cli.ts

@@ -6,6 +6,7 @@ import {
   agentExecution,
   llmExecution,
   cliAdapterKind,
+  resolveCliModel,
   type CliInvocation,
   type CliAdapterKind,
 } from './cli-adapter.js';
@@ -68,9 +69,10 @@ export async function runAgentCli(
     throw new Error('Lease-bound agent execution requires macOS or Linux process-group cancellation; Windows is unsupported.');
   }
   const kind = cliAdapterKind(cli);
+  const effectiveModel = resolveCliModel(cli, model);
 
   if (mode === 'agent' && transport === 'relay') {
-    return runViaAgentRelay(kind, instruction, wakeContext, model, relayContext, cwd, signal);
+    return runViaAgentRelay(kind, instruction, wakeContext, effectiveModel, relayContext, cwd, signal);
   }
 
   if (kind === 'relayflows-wrapper-v1') {
@@ -78,17 +80,17 @@ export async function runAgentCli(
       cli,
       instruction,
       wakeContext,
-      model,
+      effectiveModel,
       wrapperEnvironment(process.env),
       wrapperLimits,
       signal,
-    )), model);
+    )), effectiveModel);
   }
 
   const env: NodeJS.ProcessEnv = { ...process.env };
   delete env[WAKE_CONTEXT_ENV];
   delete env[MODEL_ENV];
-  const invocation = mode === 'llm' ? llmExecution(kind, instruction, model) : agentExecution(kind, instruction, model);
+  const invocation = mode === 'llm' ? llmExecution(kind, instruction, effectiveModel) : agentExecution(kind, instruction, effectiveModel);
 
   if (wakeContext !== undefined) {
     try {
@@ -106,7 +108,7 @@ export async function runAgentCli(
   // Structured provider output carries the authoritative token counts.
   const args = [...invocation.args];
   args.splice(args.length - 1, 0, ...(kind === 'claude' ? ['--output-format', 'json'] : ['--json']));
-  return requirePricedUsage(decodeProviderResult(await spawnInvocation(cli, { ...invocation, args }, env, signal, sidechannel, cwd), kind), model);
+  return requirePricedUsage(decodeProviderResult(await spawnInvocation(cli, { ...invocation, args }, env, signal, sidechannel, cwd), kind), effectiveModel);
 }
 
 /** Wait under the same worker lease for an authoritative task receipt. */

package/src/worker-spend.ts

@@ -1,17 +1,44 @@
 import { pricedUsage } from './model-pricing.js';
+import type { StepUsage } from './protocol.js';
 import type { WorkerCliResult } from './worker-cli.js';
 
+/**
+ * Usage for a step whose dollar cost is unknown (unpriced or undeclared model).
+ *
+ * It carries the reported tokens and `dollars_unmetered: true`, and never a
+ * `dollars` amount: unknown cost is not journaled as a measured $0. The kernel
+ * records the flag on the step's `budget`/`spend` and on the run total, counts
+ * the tokens toward token ceilings, and compares only metered dollars against
+ * `maxDollars`. A CLI that reported no tokens still marks the step unmetered,
+ * with zero tokens — the same token accounting any unreported step gets.
+ */
+function unmeteredUsage(input: number | undefined, output: number | undefined): StepUsage {
+  return { tokens_in: input ?? 0, tokens_out: output ?? 0, dollars_unmetered: true };
+}
+
 /**
  * Attach token/dollar usage to a worker's CLI result. Invalid token counts
  * (non-integer or negative) are the one remaining failure mode — those are
  * journaled as `worker_error` with the usage projected from clamped counts.
  *
- * Unpriced models are NOT a failure here: `pricedUsage` returns
- * `dollars: null` and preflight (see `budgetDiagnostics`) has already refused
- * declared dollar budgets against unpriced models before the CLI dispatched.
+ * Contract across preflight → worker → kernel (keep all three aligned):
+ * - preflight (`budgetDiagnostics`) warns `budget_unmetered` for a
+ *   dollar-budgeted step with no frozen price and lets it run;
+ * - this function returns priced usage (`dollars`) for a priced model, and
+ *   unmetered usage (`dollars_unmetered: true`, no `dollars`) otherwise —
+ *   never `undefined` for a successful decode, so token ceilings always see the
+ *   step and the journal always says whether its dollars are known;
+ * - the kernel (`machine/budget.rs`) enforces tokens on every charge and
+ *   dollars on metered charges only, and rejects unmetered usage that also
+ *   claims non-zero dollars.
+ * `tests/budget-unmetered-live.test.ts` pins the chain end to end.
  */
-export function workerSpend(result: WorkerCliResult, model?: string) {
-  try { return { result, usage: pricedUsage(model, result.tokens_input, result.tokens_output) }; }
+export function workerSpend(result: WorkerCliResult, model?: string): { result: WorkerCliResult; usage: StepUsage | undefined } {
+  try {
+    const usage = pricedUsage(model, result.tokens_input, result.tokens_output)
+      ?? unmeteredUsage(result.tokens_input, result.tokens_output);
+    return { result, usage };
+  }
   catch (error) {
     return {
       result: { ...result, exit_code: null, stderr_tail: error instanceof Error ? error.message : 'Invalid model usage' },

package/src/worker.ts

@@ -5,6 +5,7 @@ import type { JournalClient } from './journal-client.js';
 import type { Pins, StepDispatchEvent } from './protocol.js';
 import type { KernelAgentStep } from './spec.js';
 import { runAgentCli } from './worker-cli.js';
+import { resolveCliModel } from './cli-adapter.js';
 import { withWorkerLease } from './worker-lease.js';
 import { workerInstruction } from './worker-input.js';
 import { helperCall } from './yaml-helpers.js';
@@ -105,9 +106,10 @@ export class AgentWorker extends EventEmitter {
       return;
     }
     let humanIntervention = false;
+    const effectiveModel = typeof spec.cli === 'string' ? resolveCliModel(spec.cli, spec.model) : spec.model;
     const completed: WorkerCliResult = await withWorkerLease(this.client, dispatch, signal =>
       typeof spec.cli === 'string' && typeof spec.instruction === 'string'
-        ? runAgentCli(spec.cli, workerInstruction(spec.instruction, dispatch), dispatch.wake_context, spec.model, undefined, signal, 'agent', this.options.dataDir === undefined ? undefined : {
+        ? runAgentCli(spec.cli, workerInstruction(spec.instruction, dispatch), dispatch.wake_context, effectiveModel, undefined, signal, 'agent', this.options.dataDir === undefined ? undefined : {
           dataDir: this.options.dataDir, runId: dispatch.run_id, stepId: dispatch.step_id,
           onReady: this.options.onPtyReady, onDrive: () => { humanIntervention = true; },
         }, typeof spec.cwd === 'string' ? spec.cwd : undefined,
@@ -115,7 +117,7 @@ export class AgentWorker extends EventEmitter {
           { runId: dispatch.run_id, stepId: dispatch.step_id, idempotencyKey: dispatch.idempotency_key,
             dataDir: this.options.dataDir, resultSchema: spec.verification?.json_schema })
         : Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: 'agent step has no declared CLI' }));
-    const { result, usage } = workerSpend(completed, spec.model);
+    const { result, usage } = workerSpend(completed, effectiveModel);
     const completionReason = result.exit_code === 0 ? 'success' : 'worker_error';
 
     // Output shape: if the CLI's stdout parses as JSON, promote THAT

package/dist/cli/deterministic-failure.d.ts

@@ -1,5 +0,0 @@
-import type { StepFailedDetails } from '../failure-kinds.js';
-import type { JournalClient } from '../journal-client.js';
-/** Read completion evidence through the existing protocol, including later pages. */
-export declare function deterministicFailureDetails(client: JournalClient, runId: string): Promise<StepFailedDetails | undefined>;
-//# sourceMappingURL=deterministic-failure.d.ts.map

package/dist/cli/deterministic-failure.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"deterministic-failure.d.ts","sourceRoot":"","sources":["../../src/cli/deterministic-failure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,qFAAqF;AACrF,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAqCxC"}

package/dist/cli/deterministic-failure.js

@@ -1,66 +0,0 @@
-const STDERR_TAIL_BYTES = 1_024;
-/** Read completion evidence through the existing protocol, including later pages. */
-export async function deterministicFailureDetails(client, runId) {
-    const snapshot = await client.runGet(runId);
-    if (!Object.values(snapshot.steps).some(step => step.type === 'deterministic'))
-        return undefined;
-    let fromSeq = 1;
-    const failures = new Map();
-    while (true) {
-        const { entries } = await client.journalRead(runId, fromSeq, 100);
-        if (entries.length === 0)
-            break;
-        for (const raw of entries) {
-            const entry = record(raw);
-            const seq = entry?.['seq'];
-            if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < fromSeq) {
-                throw new Error('invalid journal sequence in command failure inspection');
-            }
-            fromSeq = seq + 1;
-            const stepId = entry?.['step_id'];
-            if (entry?.['entry_type'] !== 'step.completed' || typeof stepId !== 'string'
-                || snapshot.steps[stepId]?.type !== 'deterministic')
-                continue;
-            // A later completion supersedes an earlier failed attempt.
-            failures.delete(stepId);
-            const payload = record(entry['payload']);
-            // Post-#292 the kernel preserves the captured `{exit_code, stdout_tail,
-            // stderr_tail}` in `output` on failed completions; prefer it. Fall back
-            // to `trajectory_tail` for journal records emitted before that fix.
-            const output = record(payload?.['output']) ?? record(payload?.['trajectory_tail']);
-            const exitCode = output?.['exit_code'];
-            if (payload?.['disposition'] !== 'step_done' || payload['completionReason'] === 'success'
-                || typeof exitCode !== 'number' || !Number.isSafeInteger(exitCode) || exitCode === 0)
-                continue;
-            failures.set(stepId, {
-                stepId,
-                exitCode,
-                stderrTail: stderrTail(output?.['stderr_tail']),
-                hint: `flows replay ${shellQuote(runId)} --at ${shellQuote(stepId)}`,
-            });
-        }
-    }
-    return [...failures.values()].at(-1);
-}
-function record(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value)
-        ? value : undefined;
-}
-function stderrTail(value) {
-    if (typeof value !== 'string')
-        return '';
-    const bytes = Buffer.from(value, 'utf8');
-    let start = Math.max(0, bytes.length - STDERR_TAIL_BYTES);
-    // Drop a partial leading code point, avoiding replacement-byte expansion.
-    while (start < bytes.length && (bytes[start] & 0xc0) === 0x80)
-        start += 1;
-    // Preserve tabs/newlines; replace binary controls (including ESC and CR),
-    // C1 controls and Unicode formatting controls without growing the excerpt.
-    return bytes.subarray(start).toString('utf8')
-        .replace(/[\p{Cc}\p{Cf}]/gu, character => character === '\n' || character === '\t' ? character : '?');
-}
-function shellQuote(value) {
-    return /^[A-Za-z0-9_-]+$/.test(value) && !value.startsWith('-')
-        ? value : `'${value.replace(/'/g, "'\\''")}'`;
-}
-//# sourceMappingURL=deterministic-failure.js.map

package/dist/cli/deterministic-failure.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"deterministic-failure.js","sourceRoot":"","sources":["../../src/cli/deterministic-failure.ts"],"names":[],"mappings":"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"}

package/src/cli/deterministic-failure.ts

@@ -1,69 +0,0 @@
-import type { StepFailedDetails } from '../failure-kinds.js';
-import type { JournalClient } from '../journal-client.js';
-
-const STDERR_TAIL_BYTES = 1_024;
-
-/** Read completion evidence through the existing protocol, including later pages. */
-export async function deterministicFailureDetails(
-  client: JournalClient,
-  runId: string,
-): Promise<StepFailedDetails | undefined> {
-  const snapshot = await client.runGet(runId);
-  if (!Object.values(snapshot.steps).some(step => step.type === 'deterministic')) return undefined;
-  let fromSeq = 1;
-  const failures = new Map<string, StepFailedDetails>();
-  while (true) {
-    const { entries } = await client.journalRead(runId, fromSeq, 100);
-    if (entries.length === 0) break;
-    for (const raw of entries) {
-      const entry = record(raw);
-      const seq = entry?.['seq'];
-      if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < fromSeq) {
-        throw new Error('invalid journal sequence in command failure inspection');
-      }
-      fromSeq = seq + 1;
-      const stepId = entry?.['step_id'];
-      if (entry?.['entry_type'] !== 'step.completed' || typeof stepId !== 'string'
-        || snapshot.steps[stepId]?.type !== 'deterministic') continue;
-      // A later completion supersedes an earlier failed attempt.
-      failures.delete(stepId);
-      const payload = record(entry['payload']);
-      // Post-#292 the kernel preserves the captured `{exit_code, stdout_tail,
-      // stderr_tail}` in `output` on failed completions; prefer it. Fall back
-      // to `trajectory_tail` for journal records emitted before that fix.
-      const output = record(payload?.['output']) ?? record(payload?.['trajectory_tail']);
-      const exitCode = output?.['exit_code'];
-      if (payload?.['disposition'] !== 'step_done' || payload['completionReason'] === 'success'
-        || typeof exitCode !== 'number' || !Number.isSafeInteger(exitCode) || exitCode === 0) continue;
-      failures.set(stepId, {
-        stepId,
-        exitCode,
-        stderrTail: stderrTail(output?.['stderr_tail']),
-        hint: `flows replay ${shellQuote(runId)} --at ${shellQuote(stepId)}`,
-      });
-    }
-  }
-  return [...failures.values()].at(-1);
-}
-
-function record(value: unknown): Record<string, unknown> | undefined {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-    ? value as Record<string, unknown> : undefined;
-}
-
-function stderrTail(value: unknown): string {
-  if (typeof value !== 'string') return '';
-  const bytes = Buffer.from(value, 'utf8');
-  let start = Math.max(0, bytes.length - STDERR_TAIL_BYTES);
-  // Drop a partial leading code point, avoiding replacement-byte expansion.
-  while (start < bytes.length && (bytes[start]! & 0xc0) === 0x80) start += 1;
-  // Preserve tabs/newlines; replace binary controls (including ESC and CR),
-  // C1 controls and Unicode formatting controls without growing the excerpt.
-  return bytes.subarray(start).toString('utf8')
-    .replace(/[\p{Cc}\p{Cf}]/gu, character => character === '\n' || character === '\t' ? character : '?');
-}
-
-function shellQuote(value: string): string {
-  return /^[A-Za-z0-9_-]+$/.test(value) && !value.startsWith('-')
-    ? value : `'${value.replace(/'/g, "'\\''")}'`;
-}