@relayflows/sdk 2.0.12 → 2.0.13

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

@@ -190,6 +190,34 @@ export async function runDirectFlow(
         },
       };
     }
+    // A step that ran and failed is a run failure, not a protocol failure.
+    // Routing it through `protocolFailure` reported `relayflowd could not
+    // complete the run request` — which says the daemon broke — and left the
+    // report with no `status`, so the summary line printed `RUN <id> unknown`
+    // about a run whose outcome was known exactly. 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. Mirrors
+    // the `McpStepError` branch above, which had this shape all along.
+    if (error instanceof AuthoredFlowExecutionError && error.code === 'step_failed') {
+      return {
+        exitCode: 1,
+        report: {
+          ...base,
+          ok: false,
+          runId: error.runId,
+          socketPath,
+          status: 'failed',
+          completionReason: 'step_failed',
+          diagnostics: [...base.diagnostics, {
+            severity: 'failure',
+            kind: 'step_failed',
+            // The `code: ` prefix `AuthoredFlowExecutionError` adds is
+            // redundant once the diagnostic is labelled `[step_failed]`.
+            message: error.message.replace(/^step_failed: /, ''),
+          }],
+        },
+      };
+    }
     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,
@@ -409,18 +417,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 +623,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, "'\\''")}'`;
+}

package/src/cli.ts

@@ -30,6 +30,7 @@ import { parseDigestReference } from './bundle-transport.js';
 import { parseBuildArgs, runBuild, type BuildArgs } from './cli/build.js';
 import { runHnMonitor } from './cli/hn-monitor.js';
 import { runTickRunner } from './cli/tick-runner.js';
+import { DEFAULT_DATA_DIR } from './daemon-connection.js';
 import {
   mintObserverUrl,
   resolveObserverLinkEnv,
@@ -60,7 +61,6 @@ type ParsedArgs =
       intervalMs: number; epochMs: number | undefined; maxCatchUp: number | undefined;
       pollIntervalMs: number | undefined };
 
-const DEFAULT_DATA_DIR = '.relayflowd';
 const USAGE = [
   'Usage:',
   'flows add <helper-name|@flows/helper-name>',
@@ -299,7 +299,7 @@ async function observerUrlFrom(
   if (mint === undefined) return undefined;
   const outcome = await mint;
   if (outcome.warning !== undefined) {
-    io.stderr(`[observer] token mint failed: ${outcome.warning}; skipping observer link`);
+    io.stderr(`[observer] token mint failed: ${outcome.warning}; continuing without an observer link (the run is unaffected)`);
   }
   return outcome.observerUrl;
 }
@@ -394,11 +394,11 @@ export async function finalizeObserverLine(
   const outcome = await Promise.race([mint, timeout]);
   if (timer !== undefined) clearTimeout(timer);
   if (outcome === TIMED_OUT) {
-    io.stderr('[observer] mint did not complete in time; skipping observer link');
+    io.stderr('[observer] mint did not complete in time; continuing without an observer link (the run is unaffected)');
     return;
   }
   if (outcome.warning !== undefined) {
-    io.stderr(`[observer] token mint failed: ${outcome.warning}; skipping observer link`);
+    io.stderr(`[observer] token mint failed: ${outcome.warning}; continuing without an observer link (the run is unaffected)`);
     return;
   }
   if (outcome.observerUrl !== undefined) io.stdout(`Observer: ${outcome.observerUrl}`);

package/src/daemon-connection.ts

@@ -41,6 +41,14 @@ export const CONNECTION_FILE = 'connection.json';
 export const SOCKET_FILE = 'relayflowd.sock';
 export const DAEMON_LOG_FILE = 'relayflowd.log';
 
+/**
+ * The data dir every verb defaults to. It lives here, next to the other paths
+ * derived from it, so the CLI's `--data-dir` default and the failure
+ * diagnostic that decides whether to echo `--data-dir` back at an operator
+ * cannot drift apart.
+ */
+export const DEFAULT_DATA_DIR = '.relayflowd';
+
 /** `<data-dir>/connection.json`, exactly the shape in §1. */
 export interface DaemonConnection {
   socket_path: string;

package/src/failure-kinds.ts

@@ -62,8 +62,11 @@ export const CHECK_FAILURE_KINDS = [
  * accepting every output must not be reported as if it constrained one.
  *
  * `budget_unmetered` names an LLM/agent step under a dollar budget whose model
- * has no frozen price (including Codex, which selects its own model). Pricing
- * is light enforcement: the step runs and simply contributes no dollars.
+ * has no frozen price (including Codex, which selects its own model). A
+ * missing price never refuses: the step runs, journals its tokens with
+ * `dollars_unmetered: true`, and cannot cross `maxDollars`; token limits still
+ * apply. It replaced the `budget_missing_price` refusal (#421), which older
+ * `flows check` reports may still show.
  */
 export const PREFLIGHT_WARNING_KINDS = [
   'unprovable_effects',
@@ -122,13 +125,32 @@ export type PreflightWarningKind = (typeof PREFLIGHT_WARNING_KINDS)[number];
 export type RunFailureKind = (typeof RUN_FAILURE_KINDS)[number];
 export type RunWarningKind = (typeof RUN_WARNING_KINDS)[number];
 
-/** Optional evidence on the existing step_failed diagnostic, not a new kind. */
+/**
+ * Optional evidence on the existing step_failed diagnostic, not a new kind.
+ *
+ * Every field is optional because a failure must be reportable on whatever it
+ * left behind. A deterministic step leaves `exitCode` plus output tails; an
+ * agent or llm step leaves `completionReason` and whatever the daemon captured
+ * into `detail` (see cli/step-failure.ts). Absent means "not journaled", never
+ * "zero" — an exit code is only ever reported when one was actually recorded.
+ */
 export interface StepFailedDetails {
   stepId?: string;
+  /** `deterministic` | `llm` | `agent`, when the run snapshot named one. */
+  stepType?: string;
+  /** The kernel's per-step reason, e.g. `worker_error`, `retries_exhausted`. */
+  completionReason?: string;
   exitCode?: number;
   /** Terminal-safe UTF-8 excerpt, at most 1,024 bytes. */
+  stdoutTail?: string;
+  /** Terminal-safe UTF-8 excerpt, at most 1,024 bytes. */
   stderrTail?: string;
+  /** The daemon's own account, when it was not a render of the fields above. */
+  detail?: string;
+  /** A runnable `flows replay` invocation for this run. */
   hint?: string;
+  /** The on-disk journal for this run, when the data dir is known. */
+  journalPath?: string;
 }
 
 const CHECK_FAILURE_KIND_SET: ReadonlySet<string> = new Set(CHECK_FAILURE_KINDS);

package/src/journal-client.ts

@@ -22,6 +22,7 @@ import {
   type Request,
   type Response,
   type ServerEvent,
+  type StepUsage,
 } from './protocol.js';
 import type { KernelRunSpec, StepType } from './spec.js';
 
@@ -366,7 +367,7 @@ export class JournalClient extends EventEmitter {
     completionReason: CompletionReason,
     extra: {
       output?: unknown;
-      usage?: { tokens_in: number; tokens_out: number; dollars: string };
+      usage?: StepUsage;
       started_pins?: Pins;
       end_pins?: Pins;
       effects?: EffectRef[];

package/src/model-pricing.ts

@@ -14,11 +14,13 @@ export function hasPricing(model: string | undefined): boolean {
 /**
  * Cost accounting for a step's declared model.
  *
- * Returns `undefined` for unpriced models — callers should omit `usage`
- * from the journal payload rather than sending nulls that break the kernel
- * wire schema. An unpriced step is unmetered, not refused: it contributes no
- * dollars to a budget, and `budgetDiagnostics` warns about it at preflight.
- * Codex model ids need no entry here; Codex selects its own model.
+ * Returns `undefined` for unpriced models, meaning "no known dollar cost" —
+ * never a zero price. Workers do not omit usage on that signal: `workerSpend`
+ * falls back to unmetered usage (reported tokens plus `dollars_unmetered: true`,
+ * no `dollars`), so token ceilings still count the step and the journal records
+ * its dollars as unknown. An unpriced step is unmetered, not refused:
+ * `budgetDiagnostics` warns about it at preflight and it cannot cross
+ * `maxDollars`. Codex model ids need no entry here; Codex selects its own model.
  */
 export function pricedUsage(model: string | undefined, input = 0, output = 0):
   | { tokens_in: number; tokens_out: number; dollars: string }

package/src/preflight.ts

@@ -117,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[];

package/src/protocol.ts

@@ -72,10 +72,23 @@ 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;
@@ -130,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 {
@@ -307,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[];