@relayflows/sdk 2.0.12 → 2.0.14

package/dist/worker-spend.d.ts

@@ -1,20 +1,24 @@
+import type { StepUsage } from './protocol.js';
 import type { WorkerCliResult } from './worker-cli.js';
 /**
  * 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: the step journals zero dollars, so it
- * never trips a dollar budget, but its reported tokens still count toward any
- * token budget. Preflight (see `budgetDiagnostics`) warns that such a step is
- * unmetered for dollars.
+ * 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 declare function workerSpend(result: WorkerCliResult, model?: string): {
     result: WorkerCliResult;
-    usage: {
-        tokens_in: number;
-        tokens_out: number;
-        dollars: string;
-    } | undefined;
+    usage: StepUsage | undefined;
 };
 //# sourceMappingURL=worker-spend.d.ts.map

package/dist/worker-spend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker-spend.d.ts","sourceRoot":"","sources":["../src/worker-spend.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAQvD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,CAAC,EAAE,MAAM;;;;;;;EAclE"}
+{"version":3,"file":"worker-spend.d.ts","sourceRoot":"","sources":["../src/worker-spend.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAgBvD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAA;CAAE,CAc9H"}

package/dist/worker-spend.js

@@ -1,19 +1,33 @@
 import { pricedUsage } from './model-pricing.js';
-/** Zero-dollar usage for an unpriced step, only when the CLI reported tokens. */
+/**
+ * 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, output) {
-    if (input === undefined || output === undefined)
-        return undefined;
-    return { tokens_in: input, tokens_out: output, dollars: '0.000000' };
+    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: the step journals zero dollars, so it
- * never trips a dollar budget, but its reported tokens still count toward any
- * token budget. Preflight (see `budgetDiagnostics`) warns that such a step is
- * unmetered for dollars.
+ * 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, model) {
     try {

package/dist/worker-spend.js.map

@@ -1 +1 @@
-{"version":3,"file":"worker-spend.js","sourceRoot":"","sources":["../src/worker-spend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGjD,iFAAiF;AACjF,SAAS,cAAc,CAAC,KAAyB,EAAE,MAA0B;IAC3E,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAClE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;AACvE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,MAAuB,EAAE,KAAc;IACjE,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,aAAa,CAAC;eACtE,cAAc,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;QAC/D,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC3B,CAAC;IACD,OAAO,KAAK,EAAE,CAAC;QACb,OAAO;YACL,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,qBAAqB,EAAE;YACnH,KAAK,EAAE,WAAW,CAAC,SAAS,EAC1B,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,MAAM,CAAC,YAAa,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAChG,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,MAAM,CAAC,aAAc,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;SACvG,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"worker-spend.js","sourceRoot":"","sources":["../src/worker-spend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAIjD;;;;;;;;;GASG;AACH,SAAS,cAAc,CAAC,KAAyB,EAAE,MAA0B;IAC3E,OAAO,EAAE,SAAS,EAAE,KAAK,IAAI,CAAC,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW,CAAC,MAAuB,EAAE,KAAc;IACjE,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,aAAa,CAAC;eACtE,cAAc,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;QAC/D,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC3B,CAAC;IACD,OAAO,KAAK,EAAE,CAAC;QACb,OAAO;YACL,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,qBAAqB,EAAE;YACnH,KAAK,EAAE,WAAW,CAAC,SAAS,EAC1B,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,MAAM,CAAC,YAAa,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAChG,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,MAAM,CAAC,aAAc,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;SACvG,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayflows/sdk",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "description": "TypeScript-first authoring SDK for Relayflows. Compiles specs; speaks the journal protocol.",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,7 +45,7 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@relayfile/adapter-core": "0.5.24",
     "@relayfile/relay-helpers": "0.4.11",
-    "@relayflows/surface": "2.0.12",
+    "@relayflows/surface": "2.0.14",
     "@types/js-yaml": "^4.0.9",
     "ai-hist": "0.4.1",
     "ajv": "^8.17.1",

package/src/authored-budget.ts

@@ -2,14 +2,31 @@ import { BudgetSyntaxError, parseBudget, toKernelBudget } from './budget.js';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import type { JournalClient } from './journal-client.js';
 import type { RunOutcome } from './protocol.js';
-import type { KernelBudgetSpec, KernelRunSpec } from './spec.js';
+import type { KernelBudgetSpec, KernelPriorSpend, KernelRunSpec } from './spec.js';
+
+/**
+ * One journaled charge, in the accumulator's exact integer form.
+ *
+ * `unmetered` mirrors the journal's `budget.dollars_unmetered`: the charge
+ * spent tokens whose dollar cost is unknown, so its `micro` is a lower bound
+ * and not a measured amount. It is carried, not derived from `micro`, because
+ * an unmetered charge and a genuinely free charge both report zero dollars.
+ */
+interface Charge {
+  input: bigint;
+  output: bigint;
+  micro: bigint;
+  ms: bigint;
+  day: number;
+  unmetered: boolean;
+}
 
 /** Serialized admission for the internal authored runner's separate step runs. */
 export class AuthoredBudget {
   private readonly limit: KernelBudgetSpec | undefined;
   private failed = false;
   private tail: Promise<unknown> = Promise.resolve();
-  private charges: { input: bigint; output: bigint; micro: bigint; ms: bigint; day: number }[] = [];
+  private charges: Charge[] = [];
 
   constructor(header: unknown) {
     try {
@@ -32,14 +49,22 @@ export class AuthoredBudget {
       // Window selection follows journal timestamps, never the SDK host clock.
       const day = this.charges.at(-1)?.day;
       const total = this.charges.filter(c => this.limit!.window !== 'day' || c.day === day)
-        .reduce((s, c) => ({ input: s.input + c.input, output: s.output + c.output, micro: s.micro + c.micro, ms: s.ms + c.ms }),
-          { input: 0n, output: 0n, micro: 0n, ms: 0n });
+        .reduce((s, c) => ({ input: s.input + c.input, output: s.output + c.output, micro: s.micro + c.micro, ms: s.ms + c.ms,
+          // Sticky, exactly as the kernel's running total is: once any charge
+          // in the window was unmetered, the carried dollars are a lower bound.
+          unmetered: s.unmetered || c.unmetered }),
+          { input: 0n, output: 0n, micro: 0n, ms: 0n, unmetered: false });
       const exactNumber = (n: bigint) => { if (n > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error('budget counter overflow'); return Number(n); };
-      const outcome = await journal.runStart({ ...spec, budget: { ...this.limit, prior_spend: {
+      // One explicit conversion to the shared carried-spend shape, so a new
+      // accounting field is added here rather than silently dropped inline.
+      const priorSpend: KernelPriorSpend = {
         tokens_in: exactNumber(total.input), tokens_out: exactNumber(total.output),
         dollars: `${total.micro / 1_000_000n}.${String(total.micro % 1_000_000n).padStart(6, '0')}`,
-        wallclock_ms: exactNumber(total.ms), ...(this.limit.window === 'day' && day !== undefined ? { day } : {}),
-      } } }, undefined, admissionKey);
+        wallclock_ms: exactNumber(total.ms),
+        ...(this.limit.window === 'day' && day !== undefined ? { day } : {}),
+        ...(total.unmetered ? { dollars_unmetered: true as const } : {}),
+      };
+      const outcome = await journal.runStart({ ...spec, budget: { ...this.limit, prior_spend: priorSpend } }, undefined, admissionKey);
       try {
         if (outcome.completion_reason === 'budget_exceeded') throw new AuthoredFlowExecutionError('step_failed', 'Flow budget exceeded before the next step.', 'budget_exceeded', outcome.run_id);
         return await consume(outcome);
@@ -49,7 +74,7 @@ export class AuthoredBudget {
           const { entries } = await journal.journalRead(outcome.run_id, seq);
           if (entries.length === 0) break;
           for (const raw of entries) {
-            const e = raw as {seq: number; entry_type: string; at_ms: number; payload: {budget?: {tokens_in: number; tokens_out: number; dollars: string}; spend?: {wallclock_ms: number}}};
+            const e = raw as {seq: number; entry_type: string; at_ms: number; payload: {budget?: {tokens_in: number; tokens_out: number; dollars: string; dollars_unmetered?: boolean}; spend?: {wallclock_ms: number}}};
             seq = e.seq + 1;
             if (!['step.completed', 'memory.injected'].includes(e.entry_type)) continue;
             const b = e.payload.budget;
@@ -58,7 +83,8 @@ export class AuthoredBudget {
             if (fraction.length > 6 && /[1-9]/.test(fraction.slice(6))) throw new Error('budget accounting requires microdollar precision');
             this.charges.push({input: BigInt(b.tokens_in), output: BigInt(b.tokens_out),
               micro: BigInt(whole!) * 1_000_000n + BigInt(fraction.slice(0, 6).padEnd(6, '0')),
-              ms: BigInt(e.payload.spend?.wallclock_ms ?? 0), day: Math.floor(e.at_ms / 86_400_000)});
+              ms: BigInt(e.payload.spend?.wallclock_ms ?? 0), day: Math.floor(e.at_ms / 86_400_000),
+              unmetered: b.dollars_unmetered === true});
           }
         }
       }

package/src/authored-flow-executor.ts

@@ -148,6 +148,11 @@ export async function executeAuthoredFlow<Input = undefined>(
   const onProgress = options.onProgress;
   const flowPath = options.flowPath ?? join(process.cwd(), 'flow.ts');
   const waitOptions: RunLifecycleOptions = {
+    // Carried so a failed `f.agent` can name the journal that holds its
+    // evidence. Each authored worker call runs as its own kernel run, and
+    // without the data dir the diagnostic can name the run id but not where
+    // on disk to read it.
+    ...(options.dataDir !== undefined ? { dataDir: options.dataDir } : {}),
     ...(options.signal !== undefined ? { signal: options.signal } : {}),
     ...(options.onWait !== undefined ? { onWait: options.onWait } : {}),
   };

package/src/budget-preflight.ts

@@ -3,18 +3,29 @@ import type { PreflightWarning } from './preflight.js';
 import { hasPricing } from './model-pricing.js';
 import { resolveAdapterKind } from './adapters/index.js';
 
+/**
+ * The resolved CLI/model pair budget pricing needs, deliberately narrower than
+ * `ResolvedCliModel`: pricing depends only on *which* model will run (priced or
+ * not) and on the CLI for the Codex wording — not on whether the model came
+ * from authoring or an adapter default, which `ResolvedCliModel.source` records
+ * for `flows check` reporting. Keeping `source` out means a future resolution
+ * rung cannot change pricing by provenance alone.
+ */
 export interface BudgetStepResolution {
   readonly cli?: string;
   readonly model?: string;
 }
 
 /**
- * Dollar budgets are light enforcement: pricing never refuses a run. A step
- * whose model has no frozen price journals zero dollars (see `workerSpend`),
- * so it cannot trip `maxDollars`, while its reported tokens still count toward
- * any token budget; priced steps still accrue and a crossed limit still stops
- * the run in the kernel. This warning names each dollar-unmetered step so the
- * gap is reported, not silent.
+ * A missing price never refuses a run. Under a frozen dollar budget:
+ * - a priced step journals exact dollars and a crossed `maxDollars` stops the
+ *   run in the kernel;
+ * - an unmetered step (no model, or no frozen price) runs and journals its
+ *   tokens with `dollars_unmetered: true` (see `workerSpend`), so its unknown
+ *   cost cannot cross `maxDollars` while its tokens still count toward token
+ *   ceilings.
+ * This warning names each unmetered step so the gap is reported, not silent.
+ * Preflight `ok` stays true: warnings never refuse.
  *
  * Codex selects its own model when none is declared, so a Codex step is
  * expected to be unmetered and says so rather than asking for a fake price.

package/src/cli/build.ts

@@ -62,6 +62,13 @@ export async function runBuild(args: BuildArgs, io: CliIo): Promise<0 | 2> {
       emitBuildCheckReport(gate.report, args.json, io);
       return 2;
     }
+    // `ok` means "no refusal", not "no diagnostics". Build defers environment
+    // probes, so probe-shaped warnings (`command_unprovable`, ...) are expected
+    // here and stay in preflight.json; `budget_unmetered` does not depend on a
+    // probe and changes what the dollar budget enforces, so it is printed.
+    for (const diagnostic of gate.report.diagnostics) {
+      if (diagnostic.kind === 'budget_unmetered') io.stderr(`WARNING [${diagnostic.kind}] ${diagnostic.message}`);
+    }
     io.stdout(await buildFlow(args.value, args.out ?? 'dist/flows', io.stderr));
     return 0;
   } catch (error) {

package/src/cli/deploy.ts

@@ -31,6 +31,10 @@ export async function runDeploy(args: DeployArgs, io: CliIo): Promise<0 | 1 | 2>
       for (const diagnostic of checked.report.diagnostics) io.stderr(`${diagnostic.severity.toUpperCase()} [${diagnostic.kind}] ${diagnostic.message}`);
       return 2;
     }
+    // `ok` may still carry warnings (e.g. `budget_unmetered`); report them.
+    for (const diagnostic of checked.report.diagnostics) {
+      if (diagnostic.severity === 'warning') io.stderr(`WARNING [${diagnostic.kind}] ${diagnostic.message}`);
+    }
     const target = bucketDirectory(args.to, ref);
     if (await exists(target)) {
       await verifyDigest(target, ref.digest);

package/src/cli/direct-run.ts

@@ -14,6 +14,7 @@ import { JournalClient } from '../journal-client.js';
 import { inputFailureReport } from './check.js';
 import { checkAuthoredTriggers } from './check-triggers.js';
 import {
+  authoredStepFailure,
   connect,
   emptyReport,
   fromCheckReport,
@@ -190,6 +191,13 @@ export async function runDirectFlow(
         },
       };
     }
+    // A step that ran and failed is a run failure, not a protocol failure. The
+    // diagnostic carried up from `classifyOutcome` already names the step, its
+    // exit code and its output tail; this branch is what lets it reach the
+    // terminal. `resumeFlow` takes the same branch, through the same helper.
+    if (error instanceof AuthoredFlowExecutionError && error.code === 'step_failed') {
+      return authoredStepFailure('run', base, socketPath, error);
+    }
     const runId = error instanceof AuthoredFlowExecutionError ? error.runId : undefined;
     return protocolFailure('run', base, socketPath, error, runId);
   } finally {

package/src/cli/run.ts

@@ -11,7 +11,7 @@ import { ensureDaemon, type EnsureDaemonOptions } from '../daemon-lifecycle.js';
 import { isAuthoredFlowPath } from '../direct-input.js';
 import { daemonRefusal } from './daemon-refusal.js';
 import type { RunFailureKind, RunWarningKind, StepFailedDetails } from '../failure-kinds.js';
-import { deterministicFailureDetails } from './deterministic-failure.js';
+import { inspectionHint, stepFailureDetails } from './step-failure.js';
 import { JournalClient, JournalProtocolError } from '../journal-client.js';
 import { attachLocalAgent } from '../local-agent.js';
 import { LlmWorker } from '../llm-worker.js';
@@ -80,6 +80,14 @@ export interface RunLifecycleOptions {
   localAgent?: boolean;
   signal?: AbortSignal;
   onWait?: (progress: RunProgress) => void;
+  /**
+   * The daemon data dir, carried so a failure diagnostic can name the journal
+   * holding the evidence (`<dataDir>/runs/<runId>.sqlite3`) and emit a
+   * `flows replay` invocation that will actually resolve. Each verb sets it
+   * from its own `--data-dir`; absent only where no data dir exists, and the
+   * diagnostic then omits the path rather than guessing one.
+   */
+  dataDir?: string;
   /**
    * Attach-or-spawn policy for the daemon this command needs
    * (kernel/DAEMON-LIFECYCLE.md §3). `{ spawn: false }` is `--no-spawn`:
@@ -123,7 +131,7 @@ async function executeCheckedFlow(
     // advertises its existing pins; the daemon still owns surface matching.
     if (options.localAgent) localAgent = await attachLocalAgent(client, dataDir, options.onPtyReady);
     const outcome = await client.runStart(spec, options.reuseFromRunId);
-    const execution = await classifyOutcome(client, 'run', outcome, base, socketPath, options);
+    const execution = await classifyOutcome(client, 'run', outcome, base, socketPath, { ...options, dataDir });
     if (options.reuseFromRunId !== undefined) {
       execution.report.reuse = await reuseSummary(client, outcome.run_id, options.reuseFromRunId);
     }
@@ -207,7 +215,7 @@ export async function resumeFlow(
     if (await resumeHelperEffect(client, runId, dataDir)) {
       outcome = await client.runResume(runId, options.allowHumanInfluenced);
     }
-    return await classifyOutcome(client, 'resume', outcome, base, socketPath, options);
+    return await classifyOutcome(client, 'resume', outcome, base, socketPath, { ...options, dataDir });
   } catch (error) {
     if (error instanceof JournalProtocolError && error.code === 'human_influenced_run') {
       return { exitCode: 2, report: { ...base, runId, socketPath,
@@ -223,6 +231,14 @@ export async function resumeFlow(
       return { exitCode: 2, report: { ...base, runId, socketPath,
         diagnostics: [{ severity: 'refusal', kind: error.code, message: error.message }] } };
     }
+    // Same classification the run path gets. Resuming an authored root whose
+    // `f.agent` step failed is a step failure, not a protocol failure, and
+    // leaving it on `protocolFailure` meant `flows run` printed the evidence
+    // while `flows resume` still printed `protocol_error` and
+    // `RUN <id> unknown` for the identical failure.
+    if (error instanceof AuthoredFlowExecutionError && error.code === 'step_failed') {
+      return authoredStepFailure('resume', base, socketPath, error, runId);
+    }
     if (!(error instanceof JournalProtocolError) || error.code !== 'run_not_found') {
       return protocolFailure('resume', base, socketPath, error, runId);
     }
@@ -250,6 +266,49 @@ export async function resumeFlow(
   }
 }
 
+/**
+ * A step that ran and failed, reported as the run failure it is.
+ *
+ * Shared by `runDirectFlow` and `resumeFlow` on purpose. The first cut of this
+ * fix classified the run path and left resume on `protocolFailure`, so `flows
+ * run` became diagnosable while `flows resume` still printed `protocol_error`
+ * and `RUN <id> unknown` for the same failed step — and the surface doc claimed
+ * both were fixed. One function is what stops the two paths drifting again.
+ *
+ * `protocolFailure` is wrong here twice over: it blames the daemon for a run it
+ * drove correctly, and it produces a report with no `status`, which is the
+ * whole of what `RUN <id> unknown` ever meant.
+ */
+export function authoredStepFailure(
+  command: RunCommand,
+  base: CheckReport | RunReport,
+  socketPath: string,
+  error: AuthoredFlowExecutionError,
+  fallbackRunId?: string,
+): RunExecution {
+  // The failing step runs as its own kernel run, so the error's run id is the
+  // one whose journal holds the evidence. The resume target is the fallback.
+  const runId = error.runId ?? fallbackRunId;
+  return {
+    exitCode: 1,
+    report: {
+      ...fromBase(command, base),
+      ok: false,
+      ...(runId === undefined ? {} : { runId }),
+      socketPath,
+      status: 'failed',
+      completionReason: 'step_failed',
+      diagnostics: [...base.diagnostics, {
+        severity: 'failure',
+        kind: 'step_failed',
+        // The `step_failed: ` prefix `AuthoredFlowExecutionError` adds is
+        // redundant once the diagnostic is labelled `[step_failed]`.
+        message: error.message.replace(/^step_failed: /, ''),
+      }],
+    },
+  };
+}
+
 /**
  * Get a live daemon, then open the socket to it.
  *
@@ -409,18 +468,24 @@ export async function classifyOutcome(
       message: `Run "${current.run_id}" failed with completionReason: ${current.completion_reason}.`,
     };
     if (current.completion_reason === 'step_failed') {
+      let details: StepFailedDetails | undefined;
       try {
-        const details = await deterministicFailureDetails(client, current.run_id);
-        if (details !== undefined) {
-          Object.assign(diagnostic, details);
-          diagnostic.message += ` Step ${JSON.stringify(details.stepId)} exit=${details.exitCode}.`
-            + (details.stderrTail ? `\nStderr (last 1,024 bytes):\n${details.stderrTail}` : '')
-            + `\nInspect: ${details.hint}`;
-        }
+        details = await stepFailureDetails(client, current.run_id);
       } catch (error) {
         // Inspection must not erase the already known run failure.
-        diagnostic.message += ` Could not inspect command failure: ${errorMessage(error)}`;
+        diagnostic.message += ` Could not inspect the failed step: ${errorMessage(error)}`;
       }
+      if (details !== undefined) {
+        Object.assign(diagnostic, details);
+        diagnostic.message += renderStepEvidence(details);
+      }
+      // Appended whatever the inspection found — including nothing. A failure
+      // shape this reader does not recognise, or a journal it could not read,
+      // must still end with somewhere to go rather than with a dead end.
+      const where = inspectionHint(current.run_id, details?.stepId, options.dataDir);
+      Object.assign(diagnostic, where);
+      diagnostic.message += `\nInspect: ${where.hint}`
+        + (where.journalPath === undefined ? '' : `\nJournal: ${where.journalPath}`);
     }
     return {
       exitCode: 1,
@@ -609,6 +674,24 @@ function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : 'unknown protocol error';
 }
 
+/**
+ * The evidence half of a `step_failed` diagnostic; `inspectionHint` adds the
+ * rest. Each field is printed only when the journal actually carried it — an
+ * agent step has no exit code to report, and inventing `exit=undefined` (which
+ * is what the deterministic-only version printed for one) is worse than
+ * silence on that field.
+ */
+function renderStepEvidence(details: StepFailedDetails): string {
+  return ` Step ${JSON.stringify(details.stepId)}`
+    + (details.stepType === undefined ? '' : ` (${details.stepType})`)
+    + ` completionReason: ${details.completionReason}`
+    + (details.exitCode === undefined ? '' : ` exit=${details.exitCode}`)
+    + '.'
+    + (details.detail === undefined ? '' : `\nDetail: ${details.detail}`)
+    + (details.stdoutTail ? `\nStdout (last 1,024 bytes):\n${details.stdoutTail}` : '')
+    + (details.stderrTail ? `\nStderr (last 1,024 bytes):\n${details.stderrTail}` : '');
+}
+
 function throwIfCanceled(signal: AbortSignal | undefined, stepId: string): void {
   if (signal?.aborted === true) throw new Error(`waiting for running step "${stepId}" was canceled`);
 }

package/src/cli/step-failure.ts

@@ -0,0 +1,160 @@
+import { join } from 'node:path';
+import { DEFAULT_DATA_DIR } from '../daemon-connection.js';
+import type { StepFailedDetails } from '../failure-kinds.js';
+import type { JournalClient } from '../journal-client.js';
+
+const TAIL_BYTES = 1_024;
+
+/**
+ * Read what a failed step left in the journal — for any step type.
+ *
+ * This was `deterministicFailureDetails`, and its first act was to return
+ * `undefined` for any run without a `deterministic` step. That is every
+ * `f.agent` and `f.llm` step, because each authored worker call runs as its
+ * own single-step kernel run (authored-worker-step.ts). So a failed agent
+ * reached the terminal carrying nothing but its taxonomy label — the run said
+ * `step_failed` and discarded every account of why, which is the whole reason
+ * a local agent failure was undiagnosable.
+ *
+ * The two step families leave their evidence in different fields, because the
+ * kernel preserves `output` on a failed completion only for deterministic
+ * steps (`preserve_failure_output`, relayflowd-core/src/machine.rs). For an
+ * agent or llm step the worker's `{exit_code, stdout_tail, stderr_tail}` is
+ * nulled out of `output` and survives only as the bounded render the daemon
+ * captured into `verification.detail` (`worker_failure_detail`,
+ * relayflowd/src/engine/remote.rs). Both are read, in that order, and the
+ * daemon's render is re-parsed when it carries that same shape: an exit code
+ * the daemon stringified on its way into the journal is still an exit code,
+ * and printing it as one is the difference between a diagnosis and a blob.
+ */
+export async function stepFailureDetails(
+  client: JournalClient,
+  runId: string,
+): Promise<StepFailedDetails | undefined> {
+  const snapshot = await client.runGet(runId);
+  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 step failure inspection');
+      }
+      fromSeq = seq + 1;
+      const stepId = entry?.['step_id'];
+      if (entry?.['entry_type'] !== 'step.completed' || typeof stepId !== 'string') continue;
+      // A later completion supersedes an earlier failed attempt.
+      failures.delete(stepId);
+      const payload = record(entry['payload']);
+      if (payload === undefined) continue;
+      const completionReason = payload['completionReason'];
+      // A terminal completion that is not a success is the failure, whatever
+      // its step type. The old predicate also demanded a non-zero `exit_code`,
+      // which no agent completion carries and which a deterministic step that
+      // exits 0 and then fails its gate does not carry either — both were
+      // silently skipped.
+      if (payload['disposition'] !== 'step_done'
+        || typeof completionReason !== 'string' || completionReason === 'success') continue;
+      const stepType = snapshot.steps[stepId]?.type;
+      failures.set(stepId, {
+        stepId,
+        completionReason,
+        ...(stepType === undefined ? {} : { stepType }),
+        ...evidence(payload),
+      });
+    }
+  }
+  return [...failures.values()].at(-1);
+}
+
+/**
+ * Where to look, derived from the run id and data dir ALONE.
+ *
+ * Deliberately independent of the journal read: a failure whose evidence could
+ * not be read, or a failure shape nothing here recognises, must still end with
+ * somewhere to go rather than with a dead end. `flows replay` is that command —
+ * it already exists and already prints the full journal; nothing ever named it
+ * at the moment of failure, which is why the surface looked like it had no way
+ * to inspect a finished run.
+ */
+export function inspectionHint(
+  runId: string,
+  stepId: string | undefined,
+  dataDir: string | undefined,
+): { hint: string; journalPath?: string } {
+  const at = stepId === undefined ? '' : ` --at ${shellQuote(stepId)}`;
+  // Only name a non-default data dir: repeating the default back at an
+  // operator who never typed it is noise, and `flows replay` defaults to the
+  // same value (cli.ts).
+  const dir = dataDir === undefined || dataDir === DEFAULT_DATA_DIR
+    ? '' : ` --data-dir ${shellQuote(dataDir)}`;
+  return {
+    hint: `flows replay ${shellQuote(runId)}${at}${dir}`,
+    // Left as the operator spelled it rather than resolved: `.relayflowd/...`
+    // is what they will recognise in their own working directory.
+    ...(dataDir === undefined ? {} : { journalPath: join(dataDir, 'runs', `${runId}.sqlite3`) }),
+  };
+}
+
+/**
+ * Pull the process-shaped fields out of whichever field carried them.
+ *
+ * `verification.detail` is last because it is the daemon's own render rather
+ * than the worker's structured report — but for an agent step it is the only
+ * thing that survives, so it is parsed when it parses and kept verbatim when
+ * it does not. A truncated render (the daemon caps at 2,000 chars and appends
+ * a truncation note) will not parse; that falls through to the raw string,
+ * which is still the account of what went wrong.
+ */
+function evidence(payload: Record<string, unknown>): Partial<StepFailedDetails> {
+  const detail = record(payload['verification'])?.['detail'];
+  const structured = record(payload['output'])
+    ?? record(payload['trajectory_tail'])
+    ?? (typeof detail === 'string' ? parsed(detail) : undefined);
+  const exitCode = structured?.['exit_code'];
+  const stdout = structured?.['stdout_tail'];
+  const stderr = structured?.['stderr_tail'];
+  const structuredShape = typeof exitCode === 'number'
+    || typeof stdout === 'string' || typeof stderr === 'string';
+  return {
+    ...(typeof exitCode === 'number' && Number.isSafeInteger(exitCode) ? { exitCode } : {}),
+    ...(typeof stdout === 'string' && stdout.length > 0 ? { stdoutTail: tail(stdout) } : {}),
+    ...(typeof stderr === 'string' ? { stderrTail: tail(stderr) } : {}),
+    // Keep the daemon's account only when it was NOT just a render of the
+    // fields above — otherwise the same bytes print twice.
+    ...(typeof detail === 'string' && detail.length > 0 && !structuredShape
+      ? { detail: tail(detail) } : {}),
+  };
+}
+
+function parsed(value: string): Record<string, unknown> | undefined {
+  try {
+    return record(JSON.parse(value));
+  } catch {
+    return undefined;
+  }
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown> : undefined;
+}
+
+function tail(value: string): string {
+  const bytes = Buffer.from(value, 'utf8');
+  let start = Math.max(0, bytes.length - 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, "'\\''")}'`;
+}