@relayflows/sdk 2.0.10 → 2.0.12

package/src/cli/direct-run.ts

@@ -1,11 +1,13 @@
 import { McpStepError } from '../authored-mcp.js';
+import { randomUUID } from 'node:crypto';
+import { authoredLocalAgentStream } from '../authored-admission.js';
 import { McpPreflightError } from './check-typescript.js';
 import { attachLocalAgent } from '../local-agent.js';
 import { LlmWorker } from '../llm-worker.js';
 import {
   AuthoredFlowExecutionError,
-  executeAuthoredFlow,
 } from '../authored-flow-executor.js';
+import { executeDurableAuthoredFlow } from '../authored-root.js';
 import { AuthoredFlowLoadError } from '../authored-flow-loader.js';
 import { DirectInputError, parseDirectInput } from '../direct-input.js';
 import { JournalClient } from '../journal-client.js';
@@ -61,10 +63,13 @@ export async function runDirectFlow(
   let localLlm: LlmWorker | undefined;
   let llmClient: JournalClient | undefined;
   let llmFailure: unknown;
+  const admissionIdentity = options.authoredAdmissionKey
+    ?? process.env['RELAYFLOW_AUTHORED_ADMISSION_KEY'] ?? randomUUID();
   try {
-    const { handle, getDefinition } = checked.loaded;
     if (options.localAgent) {
-      localAgent = await attachLocalAgent(client, dataDir, options.onPtyReady);
+      localAgent = await attachLocalAgent(
+        client, dataDir, options.onPtyReady, authoredLocalAgentStream(admissionIdentity),
+      );
       // A session owns one worker registration. Keep the workspace-free LLM
       // worker on its own connection so it cannot replace the agent worker.
       llmClient = new JournalClient(socketPath);
@@ -74,15 +79,19 @@ export async function runDirectFlow(
       localLlm.on('error', error => { llmFailure = error; client.close(); });
       await localLlm.attach();
     }
-    const result = await executeAuthoredFlow(handle, client, input, {
-      getDefinition,
-      dataDir,
-      flowPath: path,
-      onProgress: options.onProgress,
-      localAgentStream: localAgent?.stream,
-      ...(options.signal !== undefined ? { signal: options.signal } : {}),
-      ...(options.onWait !== undefined ? { onWait: options.onWait } : {}),
-    });
+    const result = await executeDurableAuthoredFlow(
+      checked.loaded, client, input,
+      {
+        dataDir,
+        admissionKey: admissionIdentity,
+        localAgentStream: localAgent?.stream,
+        lifecycle: {
+          onProgress: options.onProgress,
+          ...(options.signal !== undefined ? { signal: options.signal } : {}),
+          ...(options.onWait !== undefined ? { onWait: options.onWait } : {}),
+        },
+      },
+    );
     const terminal = result.journalSteps.at(-1);
     if (terminal === undefined) {
       return protocolFailure('run', base, socketPath, new Error(
@@ -93,7 +102,7 @@ export async function runDirectFlow(
       return {
         exitCode: 3,
         report: {
-          ...base, ok: false, runId: terminal.runId, socketPath, status: 'parked',
+          ...base, ok: false, runId: result.rootRunId, socketPath, status: 'parked',
           completedSteps: result.journalSteps.length,
           diagnostics: [...base.diagnostics, {
             severity: 'parked', kind: 'run_parked',
@@ -107,7 +116,7 @@ export async function runDirectFlow(
       report: {
         ...base,
         ok: true,
-        runId: terminal.runId,
+        runId: result.rootRunId,
         socketPath,
         status: 'completed',
         completionReason: result.completionReason,
@@ -144,7 +153,7 @@ export async function runDirectFlow(
         && (error.code === 'helper_slack.credential_missing'
           || error.code === 'helper_slack.mount_required'
           || error.code === 'budget_syntax_invalid'
-          || error.code === 'budget_missing_price'
+          || error.code === 'unsupported_promise_lifecycle'
           || error.code === 'unsupported_header'
           || error.code === 'agent_cli_unresolved'
           || error.code === 'llm_cli_unresolved'
@@ -157,7 +166,6 @@ export async function runDirectFlow(
               error.code === 'helper_slack.credential_missing'
               || error.code === 'helper_slack.mount_required'
               || error.code === 'budget_syntax_invalid'
-              || error.code === 'budget_missing_price'
             ) ? error.code : 'invalid_spec',
             message: error.message,
           }, path)),

package/src/cli/run.ts

@@ -14,6 +14,8 @@ import type { RunFailureKind, RunWarningKind, StepFailedDetails } from '../failu
 import { deterministicFailureDetails } from './deterministic-failure.js';
 import { JournalClient, JournalProtocolError } from '../journal-client.js';
 import { attachLocalAgent } from '../local-agent.js';
+import { LlmWorker } from '../llm-worker.js';
+import { readAuthoredRootMetadata, resumeDurableAuthoredFlow } from '../authored-root.js';
 import type {
   RunCompletionReason,
   RunOutcome,
@@ -68,6 +70,8 @@ export interface RunProgress {
 }
 
 export interface RunLifecycleOptions {
+  /** Caller-owned hosted invocation identity for authored-root start recovery. */
+  authoredAdmissionKey?: string;
   bucket?: string;
   allowHumanInfluenced?: boolean;
   onPtyReady?: (path: string) => void;
@@ -151,7 +155,50 @@ export async function resumeFlow(
   const connected = await connect(client, 'resume', dataDir, base, options);
   if (connected !== undefined) return connected;
 
+  let authoredAgent: Awaited<ReturnType<typeof attachLocalAgent>> | undefined;
+  let authoredLlm: LlmWorker | undefined;
+  let authoredLlmClient: JournalClient | undefined;
   try {
+    const authoredRoot = await readAuthoredRootMetadata(client, runId);
+    if (authoredRoot !== undefined) {
+      if (authoredRoot.localAgentStream !== undefined && !options.localAgent) {
+        throw new Error('authored root requires --local-agent to resume its pinned worker surface');
+      }
+      if (authoredRoot.localAgentStream === undefined && options.localAgent) {
+        throw new Error('authored root was started without a local agent worker surface');
+      }
+      if (options.localAgent) {
+        authoredAgent = await attachLocalAgent(
+          client, dataDir, options.onPtyReady, authoredRoot.localAgentStream,
+        );
+        authoredLlmClient = new JournalClient(socketPath);
+        await authoredLlmClient.connect();
+        await authoredLlmClient.hello('flows-authored-resume-llm');
+        authoredLlm = new LlmWorker(authoredLlmClient, `${authoredAgent.stream}-llm`);
+        await authoredLlm.attach();
+      }
+      const result = await resumeDurableAuthoredFlow(runId, client, {
+        dataDir,
+        localAgentStream: authoredAgent?.stream,
+        lifecycle: options,
+      });
+      if (result === undefined) throw new Error('authored root disappeared during resume');
+      return {
+        exitCode: result.completionReason === 'needs_human' ? 3 : 0,
+        report: {
+          ...base,
+          ok: result.completionReason === 'success',
+          runId,
+          socketPath,
+          status: result.completionReason === 'needs_human' ? 'parked' : 'completed',
+          ...(result.completionReason === 'success'
+            ? { completionReason: 'success' as const }
+            : { diagnostics: [{ severity: 'parked' as const, kind: 'run_parked' as const,
+              message: `Flow "${result.name}" needs_human; see the journal for accumulated blockers.` }] }),
+          completedSteps: result.journalSteps.length,
+        },
+      };
+    }
     // resumeHelperEffect subsumes the old resumeSlackEffect: it handles the
     // slack effect resume plus every other provider from N's codegen. The
     // second call the earlier rebase left is a stale reference from before
@@ -166,6 +213,10 @@ export async function resumeFlow(
       return { exitCode: 2, report: { ...base, runId, socketPath,
         diagnostics: [{ severity: 'refusal', kind: 'human_influenced_run', message: error.message.replace(/^human_influenced_run: /, '') }] } };
     }
+    if (error instanceof AuthoredFlowExecutionError && error.code === 'unsupported_promise_lifecycle') {
+      return { exitCode: 2, report: { ...base, runId, socketPath,
+        diagnostics: [{ severity: 'refusal', kind: 'invalid_spec', message: error.message }] } };
+    }
     if (error instanceof AuthoredFlowExecutionError
       && (error.code === 'helper_slack.credential_missing' || error.code === 'helper_slack.mount_required'
         || error.code === 'helper_provider.mount_required' || error.code === 'helper_provider.unsupported')) {
@@ -189,7 +240,13 @@ export async function resumeFlow(
       },
     };
   } finally {
-    client.close();
+    try {
+      await authoredLlm?.close();
+      authoredLlmClient?.close();
+      await authoredAgent?.close();
+    } finally {
+      client.close();
+    }
   }
 }
 

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

@@ -53,7 +53,7 @@ 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;
@@ -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);
@@ -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/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,17 @@ 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). Pricing
+ * is light enforcement: the step runs and simply contributes no dollars.
  */
 export const PREFLIGHT_WARNING_KINDS = [
   'unprovable_effects',
   'command_unresolved',
   'command_unprovable',
   'vacuous_gate',
+  'budget_unmetered',
 ] as const;
 
 /**

package/src/journal-client.ts

@@ -204,8 +204,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. */

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 }),
 });
@@ -15,10 +16,9 @@ export function hasPricing(model: string | undefined): boolean {
  *
  * 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.
+ * 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.
  */
 export function pricedUsage(model: string | undefined, input = 0, output = 0):
   | { tokens_in: number; tokens_out: number; dollars: string }