@relayflows/sdk 2.0.11 → 2.0.13

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-adapter.ts

@@ -28,6 +28,33 @@ export function cliAdapterKind(executable: string): CliAdapterKind {
   return resolveAdapterKind(executable);
 }
 
+export type CliModelSource = 'step' | 'named' | 'adapter';
+
+export interface ResolvedCliModel {
+  readonly model?: string;
+  readonly source?: CliModelSource;
+}
+
+/**
+ * Resolve the model once, in authoring priority order: step, selected named
+ * agent, then the registered CLI adapter's default. Unregistered executables
+ * resolve through the wrapper adapter, whose absent default remains undefined.
+ */
+export function resolveCliModelSelection(
+  executable: string,
+  declarations: Readonly<{ step?: string; named?: string }> = {},
+): ResolvedCliModel {
+  if (declarations.step !== undefined) return { model: declarations.step, source: 'step' };
+  if (declarations.named !== undefined) return { model: declarations.named, source: 'named' };
+  const model = registeredAdapters()[resolveAdapterKind(executable)].defaultModel;
+  return model === undefined ? {} : { model, source: 'adapter' };
+}
+
+/** Resolve a runtime model, where any materialized value is step-owned. */
+export function resolveCliModel(executable: string, model?: string): string | undefined {
+  return resolveCliModelSelection(executable, { step: model }).model;
+}
+
 /** Prove the adapter command shape before classifying an auth failure. */
 export function adapterIdentification(kind: CliAdapterKind): CliAdapterIdentification {
   return registeredAdapters()[kind].buildIdentification();

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,
@@ -53,14 +54,13 @@ type ParsedArgs =
   | { command: 'cloud-run'; value: string; json: boolean; wait: boolean }
   | { command: 'check'; json: boolean; watch: boolean; value: string }
   | { command: 'run'; bucket: string | undefined; reuseFromRunId: string | undefined; localAgent: boolean; dataDir: string; input: string | undefined; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
-  | { command: 'resume'; dataDir: string; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
+  | { command: 'resume'; localAgent: boolean; dataDir: string; json: boolean; spawn: boolean; noObserverLink: boolean; allowHumanInfluenced: boolean; value: string }
   | { command: 'observer'; dataDir: string }
   | { command: 'hn-monitor'; sub: 'start'; dataDir: string; specPath: string; pollIntervalMs: number | undefined }
   | { command: 'tick'; sub: 'start'; dataDir: string; specPath: string; scheduleId: string;
       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>',
@@ -74,7 +74,7 @@ const USAGE = [
   'flows run --cloud [--json] [--wait] <flow.yaml|spec.json>',
   'flows run [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] <flow.ts> --input <inline-json-or-file>',
   'flows tick start --schedule-id <id> --interval-ms <ms> [--epoch-ms <ms>] [--max-catch-up <n>] [--poll-interval-ms <ms>] [--data-dir <dir>] <spec.json>',
-  'flows resume [--allow-human-influenced] [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] <run-id>',
+  'flows resume [--allow-human-influenced] [--json] [--no-spawn] [--no-observer-link] [--data-dir <dir>] [--local-agent] <run-id>',
   'flows replay [--allow-human-influenced] [--json] [--data-dir <dir>] <run-id> [--at <step-id>]',
   'flows observer [--data-dir <dir>]',
   'flows hn-monitor start [--data-dir <dir>] [--poll-interval-ms <n>] <spec.json>',
@@ -191,7 +191,7 @@ export async function runCli(
     allowHumanInfluenced: parsed.allowHumanInfluenced,
     onPtyReady: (path: string) => io.stderr(`PTY ${path}`),
     ...(parsed.command === 'run' && parsed.reuseFromRunId !== undefined ? { reuseFromRunId: parsed.reuseFromRunId } : {}),
-    localAgent: parsed.command === 'run' && parsed.localAgent,
+    localAgent: parsed.localAgent,
     onProgress: showProgress,
     onWait: (progress: RunProgress) => {
       emitWait(progress, io);
@@ -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}`);
@@ -455,7 +455,7 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
       continue;
     }
     if (argument === '--local-agent') {
-      if (command !== 'run' || localAgent) return undefined;
+      if (command === 'check' || localAgent) return undefined;
       localAgent = true;
       continue;
     }
@@ -534,7 +534,7 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
     ? { command, json, watch, value: positionals[0]! }
     : command === 'run'
       ? { command, bucket, reuseFromRunId, localAgent, dataDir, input, json, spawn, noObserverLink, allowHumanInfluenced, value: positionals[0]! }
-      : { command, dataDir, json, spawn, noObserverLink, allowHumanInfluenced, value: positionals[0]! };
+      : { command, localAgent, dataDir, json, spawn, noObserverLink, allowHumanInfluenced, value: positionals[0]! };
 }
 
 function parseHnMonitorArgs(rest: readonly string[]): ParsedArgs | undefined {

package/src/cloud-run.ts

@@ -1,11 +1,14 @@
 import { RUN_COMPLETION_REASONS } from '@relayflows/surface';
 import type { RunCompletionReason } from './protocol.js';
 import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { setTimeout } from 'node:timers/promises';
 import { parse as parseYaml } from 'yaml';
 import { canonicalize, specHash } from './canonical.js';
 import { CompileError, compileSpec, kernelToAuthoring, toKernelSpec } from './compile.js';
 import type { FlowSpec } from './spec.js';
+import { snapshotJsonValue, type JsonValue } from './json-value.js';
+import { loadAuthoredFlow, type SurfaceModuleAuthority } from './authored-flow-loader.js';
 import {
   CloudFlowError, cloudConnection, cloudRequest, cloudRunId, isCloudRecord,
   type CloudConnectionOptions,
@@ -15,6 +18,8 @@ export type CloudFlowSource = FlowSpec | { path: string };
 export interface RunInCloudOptions extends CloudConnectionOptions {
   /** Existing Cloud workspace to run in; provisioning/authorization remains server-side. */
   workspaceId?: string;
+  /** Exact JSON input. Required at runtime for authored .flow.ts; refused for declarative source. */
+  input?: JsonValue;
 }
 export interface CloudRunReceipt {
   runId: string;
@@ -24,8 +29,14 @@ export interface CloudRunReceipt {
   /** Authenticated run API resource; this is not a public sharing URL. */
   apiUrl: string;
 }
+export interface CloudAuthoredAuthority {
+  readonly schemaVersion: 1;
+  readonly sourceSha256: string;
+  readonly byteLength: number;
+  readonly surface: SurfaceModuleAuthority;
+}
 export type CloudRunState =
-  | { runId: string; status: 'pending' | 'running' }
+  | { runId: string; status: 'pending' | 'launching' | 'running' }
   | { runId: string; status: 'completed' | 'failed' | 'cancelled'; completionReason: RunCompletionReason };
 
 /**
@@ -38,43 +49,83 @@ export async function runInCloud(
   options: RunInCloudOptions = {},
 ): Promise<CloudRunReceipt> {
   const { baseUrl } = cloudConnection(options);
-  let spec: FlowSpec;
+  let spec: FlowSpec | undefined;
+  let authored: { source: string; authority: CloudAuthoredAuthority } | undefined;
+  const inputPresent = Object.prototype.hasOwnProperty.call(options, 'input');
+  let authoredInput: JsonValue | undefined;
   try {
     options.signal?.throwIfAborted();
     if ('path' in flow) {
-      if (!/\.(?:ya?ml|json)$/iu.test(flow.path)) {
+      if (/\.flow\.ts$/iu.test(flow.path)) {
+        const bytes = await readFile(flow.path);
+        const source = bytes.toString('utf8');
+        if (!bytes.length || Buffer.from(source, 'utf8').compare(bytes) !== 0) {
+          throw new CloudFlowError('invalid_input', 'Authored source must be nonempty, lossless UTF-8.');
+        }
+        const loaded = await loadAuthoredFlow(flow.path);
+        loaded.getDefinition(loaded.handle);
+        if (loaded.graph.length !== 1) {
+          throw new CloudFlowError('unsupported_source',
+            'Cloud authored submission currently accepts one self-contained .flow.ts source without use dependencies.');
+        }
+        authored = {
+          source,
+          authority: Object.freeze({
+            schemaVersion: 1,
+            sourceSha256: createHash('sha256').update(bytes).digest('hex'),
+            byteLength: bytes.length,
+            surface: loaded.surfaceAuthority,
+          }),
+        };
+      } else if (!/\.(?:ya?ml|json)$/iu.test(flow.path)) {
         throw new CloudFlowError('unsupported_source',
-          'Cloud v2 currently accepts declarative YAML or JSON specs; authored TypeScript flows are not supported by the hosted runtime.');
-      }
-      const parsed: unknown = parseYaml(await readFile(flow.path, 'utf8'));
-      try {
-        spec = compileSpec(parsed);
-      } catch (error) {
-        if (!(error instanceof CompileError)) throw error;
-        // Prefer the authoring dialect; accept compiled kernel JSON for local-CLI
-        // compatibility. If both fail, retain the original authoring diagnostic.
+          'Cloud v2 accepts declarative YAML/JSON specs or authored .flow.ts source.');
+      } else {
+        const parsed: unknown = parseYaml(await readFile(flow.path, 'utf8'));
         try {
-          spec = compileSpec(kernelToAuthoring(parsed));
-        } catch {
-          throw error;
+          spec = compileSpec(parsed);
+        } catch (error) {
+          if (!(error instanceof CompileError)) throw error;
+          // Prefer the authoring dialect; accept compiled kernel JSON for local-CLI
+          // compatibility. If both fail, retain the original authoring diagnostic.
+          try {
+            spec = compileSpec(kernelToAuthoring(parsed));
+          } catch {
+            throw error;
+          }
         }
       }
     } else {
       spec = compileSpec(flow);
     }
+    if (authored !== undefined) {
+      if (!inputPresent) {
+        throw new CloudFlowError('invalid_input', 'Cloud authored .flow.ts requires an explicit JSON input. Pass {} when the flow needs no fields.');
+      }
+      authoredInput = snapshotJsonValue(options.input, 'Cloud authored input');
+    } else if (inputPresent) {
+      throw new CloudFlowError('invalid_input', 'Cloud input is supported only for authored .flow.ts source.');
+    }
   } catch (error) {
     options.signal?.throwIfAborted();
     if (error instanceof CloudFlowError) throw error;
     throw new CloudFlowError('invalid_input', 'Cannot read or compile the declarative flow. Check the file path and YAML/JSON spec.');
   }
   options.signal?.throwIfAborted();
-  const hash = specHash(toKernelSpec(spec));
+  const hash = authored === undefined
+    ? specHash(toKernelSpec(spec!))
+    : createHash('sha256').update(canonicalize({
+        authority: authored.authority,
+        input: authoredInput,
+      })).digest('hex');
   const result = await cloudRequest('/api/v1/workflows/run', options, {
     // JSON is a YAML subset. Sending canonical data preserves the exact spec
     // while using the server's existing YAML-to-config admission path.
-    workflow: canonicalize(spec),
-    fileType: 'yaml',
+    workflow: authored?.source ?? canonicalize(spec),
+    fileType: authored === undefined ? 'yaml' : 'ts',
     relayflowVersion: 'v2',
+    ...(authored === undefined ? {} : { authoredAuthority: authored.authority }),
+    ...(authored === undefined ? {} : { inputs: authoredInput }),
     ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
   });
   if (!isCloudRecord(result) || (result.status !== 'pending' && result.status !== 'running')) {
@@ -92,10 +143,12 @@ export async function getCloudFlowRun(
   const result = await cloudRequest(`/api/v1/workflows/runs/${runId}`, options);
   if (!isCloudRecord(result) || result.runId !== runId || result.relayflowVersion !== 'v2'
     || typeof result.status !== 'string'
-    || !['pending', 'running', 'completed', 'failed', 'cancelled'].includes(result.status)) {
+    || !['pending', 'launching', 'running', 'completed', 'failed', 'cancelled'].includes(result.status)) {
     throw new CloudFlowError('invalid_response', 'Cloud returned an invalid v2 run record.');
   }
-  if (result.status === 'pending' || result.status === 'running') return { runId, status: result.status };
+  if (result.status === 'pending' || result.status === 'launching' || result.status === 'running') {
+    return { runId, status: result.status };
+  }
   const report = result.result;
   const reason = isCloudRecord(report) ? report.completionReason : undefined;
   if (typeof reason !== 'string' || !(RUN_COMPLETION_REASONS as readonly string[]).includes(reason)
@@ -122,7 +175,7 @@ export async function waitForCloudFlowRun(
     try {
       const run = await getCloudFlowRun(runId, options);
       failures = 0;
-      if (run.status !== 'pending' && run.status !== 'running') return run;
+      if (run.status !== 'pending' && run.status !== 'launching' && run.status !== 'running') return run;
     } catch (error) {
       options.signal?.throwIfAborted();
       const transient = error instanceof CloudFlowError && (error.code === 'transient_error'

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

@@ -14,7 +14,6 @@ const PREFLIGHT_ENVIRONMENT_FAILURE_KINDS = [
   'mcp_undeclared_server',
   'mcp_unreachable',
   'budget_syntax_invalid',
-  'budget_missing_price',
   'cli_missing',
   'cli_unauthenticated',
   'cli_unresolved',
@@ -61,12 +60,20 @@ export const CHECK_FAILURE_KINDS = [
  * `vacuous_gate` is the same principle applied to a declared gate that judges
  * nothing: `schema: {}` and `schema: true` are legal and accepted, but a gate
  * 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). 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',
   'command_unresolved',
   'command_unprovable',
   'vacuous_gate',
+  'budget_unmetered',
 ] as const;
 
 /**
@@ -118,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';
 
@@ -204,8 +205,12 @@ export class JournalClient extends EventEmitter {
    * the run file, and append `run.spawned`. Authoring specs must be compiled
    * with `toKernelSpec` before crossing this journal-protocol boundary.
    */
-  runStart(spec: KernelRunSpec, reuseFromRunId?: string): Promise<VerbContract['run.start']['result']> {
-    return this.request('run.start', { spec, ...(reuseFromRunId === undefined ? {} : { reuse_from_run_id: reuseFromRunId }) }, null);
+  runStart(spec: KernelRunSpec, reuseFromRunId?: string, admissionKey?: string): Promise<VerbContract['run.start']['result']> {
+    return this.request('run.start', {
+      spec,
+      ...(reuseFromRunId === undefined ? {} : { reuse_from_run_id: reuseFromRunId }),
+      ...(admissionKey === undefined ? {} : { admission_key: admissionKey }),
+    }, null);
   }
 
   /** §3 memoized resume. */
@@ -362,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/llm-worker.ts

@@ -5,6 +5,7 @@ import type { JournalClient } from './journal-client.js';
 import type { CompletionReason, StepDispatchEvent } from './protocol.js';
 import type { KernelLlmStep } 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 { jsonSchemaOutputError } from './json-schema.js';
@@ -49,11 +50,12 @@ export class LlmWorker extends EventEmitter {
     const schema = spec.verification?.json_schema;
     const prompt = schema === undefined ? spec.prompt
       : `${spec.prompt}\n\nReturn only a JSON value matching this JSON Schema (no Markdown fences):\n${JSON.stringify(schema)}`;
+    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.prompt === 'string'
-        ? runAgentCli(spec.cli, workerInstruction(prompt, dispatch), dispatch.wake_context, spec.model, undefined, signal, 'llm')
+        ? runAgentCli(spec.cli, workerInstruction(prompt, dispatch), dispatch.wake_context, effectiveModel, undefined, signal, 'llm')
         : Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: 'llm step has no declared CLI' }));
-    const { result, usage } = workerSpend(completed, spec.model);
+    const { result, usage } = workerSpend(completed, effectiveModel);
     let reason: CompletionReason = result.exit_code === 0 ? 'success' : 'worker_error';
     let output: unknown = result.stdout_tail;
     let detail = result.stderr_tail;

package/src/local-agent.ts

@@ -3,14 +3,19 @@ import type { JournalClient } from './journal-client.js';
 import { AgentWorker } from './worker.js';
 
 /** A local worker for stream-only steps; no workspace recovery is claimed. */
-export async function attachLocalAgent(client: JournalClient, dataDir?: string, onPtyReady?: (path: string) => void): Promise<{
+export async function attachLocalAgent(
+  client: JournalClient,
+  dataDir?: string,
+  onPtyReady?: (path: string) => void,
+  requestedStream?: string,
+): Promise<{
   stream: string;
   readonly failure: unknown;
   close(): Promise<void>;
 }> {
   // A fresh, unconsumed stream has offset zero. The executor declares exactly
   // this stream on its agent steps. No worktree revision is invented.
-  const stream = `local-agent-${randomUUID()}`;
+  const stream = requestedStream ?? `local-agent-${randomUUID()}`;
   const worker = new AgentWorker(client, {
     workerId: stream,
     capacity: 1,

package/src/model-pricing.ts

@@ -2,6 +2,7 @@
 export const MODEL_PRICING: Readonly<Record<string, Readonly<{ input: number; output: number }>>> = Object.freeze({
   'claude-sonnet-4-6': Object.freeze({ input: 3, output: 15 }),
   'claude-opus-4-7': Object.freeze({ input: 15, output: 75 }),
+  'claude-opus-5': Object.freeze({ input: 5, output: 25 }),
   'codex-medium': Object.freeze({ input: 2, output: 8 }),
   'codex-large': Object.freeze({ input: 5, output: 20 }),
 });
@@ -13,12 +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. The refusal for a declared dollar budget against an unpriced
- * model is `budgetDiagnostics` at preflight (before any CLI dispatches).
- * Throwing here after usage decode would waste the CLI invocation that
- * preflight was meant to prevent.
+ * 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 }