@relayflows/sdk 2.0.10 → 2.0.12

package/src/authored-root.ts

@@ -0,0 +1,396 @@
+import { loadPinnedAuthoredSource } from './authored-source-authority.js';
+import { assertAuthoredRuntimeAvailable, runAuthoredInNode } from './authored-node-runner.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { canonicalize } from './canonical.js';
+import { compileSpec, toKernelSpec } from './compile.js';
+import { executeAuthoredFlow, type AuthoredFlowExecutionResult } from './authored-flow-executor.js';
+import {
+  loadAuthoredFlow,
+  type LoadedAuthoredFlow,
+  type SurfaceModuleAuthority,
+} from './authored-flow-loader.js';
+import { JournalClient } from './journal-client.js';
+import type { RunOutcome, StepDispatchEvent } from './protocol.js';
+import { SPEC_SCHEMA_VERSION } from './spec.js';
+import type { RunLifecycleOptions } from './cli/run.js';
+import { withWorkerLease } from './worker-lease.js';
+import { isSurfaceCompletionReason } from './authored-step-output.js';
+
+const ROOT_KIND = 'relayflows.authored-root.v1';
+
+export interface AuthoredRootMetadata {
+  readonly kind: typeof ROOT_KIND;
+  readonly flowName: string;
+  readonly flowPath: string;
+  readonly sourceSha256: string;
+  readonly surface: SurfaceModuleAuthority;
+  readonly sources: readonly AuthoredRootSourceAuthority[];
+  readonly localAgentStream?: string;
+  readonly inputPresent: boolean;
+  readonly input?: unknown;
+}
+
+export interface AuthoredRootSourceAuthority {
+  readonly path: string;
+  readonly sourceSha256: string;
+  readonly surface: SurfaceModuleAuthority;
+}
+
+export interface DurableAuthoredOptions {
+  readonly dataDir: string;
+  readonly admissionKey?: string;
+  readonly localAgentStream?: string;
+  readonly lifecycle?: RunLifecycleOptions;
+}
+
+/** Admit and execute one authored body under a durable kernel root. */
+export async function executeDurableAuthoredFlow(
+  loaded: LoadedAuthoredFlow,
+  journal: JournalClient,
+  input: unknown,
+  options: DurableAuthoredOptions,
+): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+  assertAuthoredRuntimeAvailable();
+  const source = await readFile(loaded.sourcePath);
+  const sources = await Promise.all(loaded.graph.map(async node => Object.freeze({
+    path: node.path,
+    sourceSha256: sha256(await readFile(node.path)),
+    surface: node.surfaceAuthority,
+  })));
+  const definition = loaded.getDefinition(loaded.handle);
+  const metadata: AuthoredRootMetadata = Object.freeze({
+    kind: ROOT_KIND,
+    flowName: definition.name,
+    flowPath: loaded.sourcePath,
+    sourceSha256: sha256(source),
+    surface: loaded.surfaceAuthority,
+    sources: Object.freeze(sources),
+    ...(options.localAgentStream === undefined ? {} : { localAgentStream: options.localAgentStream }),
+    inputPresent: input !== undefined,
+    ...(input === undefined ? {} : { input: jsonSnapshot(input, 'authored root input') }),
+  });
+  const admissionKey = rootAdmissionKey(options.admissionKey ?? randomUUID());
+  const stream = `authored-root-${admissionKey.slice(-40)}`;
+  const spec = rootSpec(metadata, stream);
+  const peer = journal.createPeer();
+  await peer.connect();
+  await peer.hello('flows-authored-root');
+  let cancelDispatch = () => {};
+  try {
+    const dispatchWait = nextRootDispatch(peer);
+    cancelDispatch = dispatchWait.cancel;
+    await peer.workerAttach(`worker-${stream}`, ['agent'], {
+      workspace: [], streams: [{ stream, read_offset: 0 }],
+    });
+    const outcome = await journal.runStart(spec, undefined, admissionKey);
+    if (outcome.status === 'completed') {
+      dispatchWait.cancel();
+      return await completedRootResult(journal, outcome.run_id);
+    }
+    assertRootCanDispatch(outcome);
+    // `run.start` is an idempotent receipt. If the first caller died after
+    // the daemon dispatched this root, a same-daemon retry sees the existing
+    // active run but receives no second dispatch from start itself. Resume is
+    // safe for the first caller too: the daemon preserves a live lease and
+    // redelivers only when the former worker connection is gone.
+    await journal.runResume(outcome.run_id);
+    const dispatch = await dispatchWait.promise;
+    return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
+  } finally {
+    cancelDispatch();
+    peer.close();
+  }
+}
+
+/** Resume the exact source and Surface instance recorded by an authored root. */
+export async function resumeDurableAuthoredFlow(
+  rootRunId: string,
+  journal: JournalClient,
+  options: Omit<DurableAuthoredOptions, 'admissionKey'>,
+): Promise<(AuthoredFlowExecutionResult & { readonly rootRunId: string }) | undefined> {
+  const metadata = await readAuthoredRootMetadata(journal, rootRunId);
+  if (metadata === undefined) return undefined;
+  assertAuthoredRuntimeAvailable();
+  const loaded = await loadPinnedAuthoredSource(metadata);
+  if (metadata.localAgentStream !== options.localAgentStream) {
+    throw new Error('authored root local agent surface mismatch');
+  }
+  const stream = rootStreamFromMetadata(await rootKernelStep(journal, rootRunId));
+  const peer = journal.createPeer();
+  await peer.connect();
+  await peer.hello('flows-authored-root-resume');
+  let cancelDispatch = () => {};
+  try {
+    const dispatchWait = nextRootDispatch(peer);
+    cancelDispatch = dispatchWait.cancel;
+    await peer.workerAttach(`worker-${stream}-${randomUUID()}`, ['agent'], {
+      workspace: [], streams: [{ stream, read_offset: 0 }],
+    });
+    const outcome = await journal.runResume(rootRunId);
+    if (outcome.status === 'completed') {
+      dispatchWait.cancel();
+      return await completedRootResult(journal, rootRunId);
+    }
+    assertRootCanDispatch(outcome);
+    const dispatch = await dispatchWait.promise;
+    return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
+  } finally {
+    cancelDispatch();
+    peer.close();
+  }
+}
+
+export async function readAuthoredRootMetadata(
+  journal: JournalClient,
+  runId: string,
+): Promise<AuthoredRootMetadata | undefined> {
+  const step = await rootKernelStep(journal, runId).catch(() => undefined);
+  if (step === undefined || step.id !== 'authored-root' || !hasRootStream(step)) return undefined;
+  if (typeof step.instruction !== 'string') {
+    throw new Error('authored root journal has malformed authority metadata');
+  }
+  let value: unknown;
+  try { value = JSON.parse(step.instruction); } catch {
+    throw new Error('authored root journal has malformed authority metadata');
+  }
+  if (!isRootMetadata(value)) {
+    throw new Error('authored root journal has malformed authority metadata');
+  }
+  return value;
+}
+
+async function driveRoot(
+  loaded: LoadedAuthoredFlow,
+  metadata: AuthoredRootMetadata,
+  journal: JournalClient,
+  peer: JournalClient,
+  dispatch: StepDispatchEvent,
+  options: Omit<DurableAuthoredOptions, 'admissionKey'>,
+): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+  try {
+    const result = await withWorkerLease(peer, dispatch, async rootSignal => {
+      const callerSignal = options.lifecycle?.signal;
+      const signal = callerSignal === undefined ? rootSignal : AbortSignal.any([callerSignal, rootSignal]);
+      if (process.versions['bun'] !== undefined) {
+        return runAuthoredInNode(metadata, journal.socketPath, dispatch.run_id, {
+          dataDir: options.dataDir, localAgentStream: options.localAgentStream,
+          ...options.lifecycle, signal,
+        });
+      }
+      return await executeAuthoredFlow(
+        loaded.handle,
+        journal,
+        metadata.inputPresent ? metadata.input : undefined,
+        {
+          getDefinition: loaded.getDefinition,
+          dataDir: options.dataDir,
+          flowPath: metadata.flowPath,
+          localAgentStream: options.localAgentStream,
+          rootRunId: dispatch.run_id,
+          ...options.lifecycle,
+          signal: callerSignal === undefined
+            ? rootSignal
+            : AbortSignal.any([callerSignal, rootSignal]),
+        },
+      );
+    });
+    await peer.stepComplete(
+      dispatch.run_id, dispatch.step_id, dispatch.attempt,
+      dispatch.idempotency_key, 'success', {
+        output: { name: result.name, completionReason: result.completionReason,
+          journalSteps: result.journalSteps,
+          ...(result.executionRuntime === undefined ? {} : { executionRuntime: result.executionRuntime }) },
+        started_pins: dispatch.pins, end_pins: dispatch.pins,
+      },
+    );
+    return Object.freeze({ ...result, rootRunId: dispatch.run_id });
+  } catch (error) {
+    await terminalizeRootFailure(peer, dispatch, error);
+    throw error;
+  }
+}
+
+/**
+ * A returned body failure is deterministic for this root attempt. Complete
+ * every kernel retry with the same declared failure so the run reaches its
+ * durable `step_failed` terminal instead of being stranded waiting for a
+ * worker after the CLI has already returned. A process crash never enters
+ * this path: the running attempt remains recoverable by `run.resume`.
+ */
+async function terminalizeRootFailure(
+  peer: JournalClient,
+  firstDispatch: StepDispatchEvent,
+  error: unknown,
+): Promise<void> {
+  let dispatch = firstDispatch;
+  const output = { error: error instanceof Error ? error.message : 'authored root failed' };
+  for (;;) {
+    const next = nextRootDispatch(peer);
+    let outcome: RunOutcome;
+    try {
+      outcome = await peer.stepComplete(
+        dispatch.run_id, dispatch.step_id, dispatch.attempt,
+        dispatch.idempotency_key, 'worker_error', {
+          output, started_pins: dispatch.pins, end_pins: dispatch.pins,
+        },
+      );
+    } catch (completionError) {
+      next.cancel();
+      throw completionError;
+    }
+    if (outcome.status === 'failed') {
+      next.cancel();
+      return;
+    }
+    try { assertRootCanDispatch(outcome); } catch (outcomeError) {
+      next.cancel();
+      throw outcomeError;
+    }
+    dispatch = await next.promise;
+    if (dispatch.run_id !== firstDispatch.run_id) {
+      throw new Error('authored root retry was dispatched for a different run');
+    }
+  }
+}
+
+function rootSpec(metadata: AuthoredRootMetadata, stream: string) {
+  return toKernelSpec(compileSpec({
+    version: SPEC_SCHEMA_VERSION,
+    name: `authored-root/${metadata.flowName}`,
+    steps: [{
+      id: 'authored-root', type: 'agent',
+      instruction: canonicalize(metadata),
+      surfaces: { streams: [{ stream }] },
+      recoveryMode: 'reset', maxIterations: 8,
+    }],
+  }));
+}
+
+async function rootKernelStep(journal: JournalClient, runId: string): Promise<Record<string, unknown>> {
+  const entries = (await journal.journalRead(runId, 1)).entries as Array<Record<string, unknown>>;
+  const spawned = entries.find(entry => entry.entry_type === 'run.spawned');
+  const payload = spawned?.payload as { spec?: { steps?: unknown[] } } | undefined;
+  const step = payload?.spec?.steps?.[0];
+  if (typeof step !== 'object' || step === null || Array.isArray(step)) {
+    throw new Error('authored root journal has no root step');
+  }
+  return step as Record<string, unknown>;
+}
+
+function rootStreamFromMetadata(step: Record<string, unknown>): string {
+  const surfaces = step.surfaces as { streams?: Array<{ stream?: unknown }> } | undefined;
+  const stream = surfaces?.streams?.[0]?.stream;
+  if (typeof stream !== 'string' || !stream.startsWith('authored-root-')) {
+    throw new Error('authored root journal has no pinned stream');
+  }
+  return stream;
+}
+
+function hasRootStream(step: Record<string, unknown>): boolean {
+  try { rootStreamFromMetadata(step); return true; } catch { return false; }
+}
+
+function nextRootDispatch(peer: JournalClient): {
+  promise: Promise<StepDispatchEvent>;
+  cancel(): void;
+} {
+  let cancel = () => {};
+  const promise = new Promise<StepDispatchEvent>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      peer.off('step.dispatch', onDispatch);
+      reject(new Error('authored root was not dispatched'));
+    }, 30_000);
+    const onDispatch = (dispatch: StepDispatchEvent) => {
+      if (dispatch.step_id !== 'authored-root') return;
+      clearTimeout(timer);
+      peer.off('step.dispatch', onDispatch);
+      resolve(dispatch);
+    };
+    peer.on('step.dispatch', onDispatch);
+    cancel = () => {
+      clearTimeout(timer);
+      peer.off('step.dispatch', onDispatch);
+    };
+  });
+  return { promise, cancel };
+}
+
+async function completedRootResult(
+  journal: JournalClient,
+  rootRunId: string,
+): Promise<AuthoredFlowExecutionResult & { readonly rootRunId: string }> {
+  const entries = (await journal.journalRead(rootRunId, 1)).entries as Array<Record<string, unknown>>;
+  const completed = entries.slice().reverse().find(entry => entry.entry_type === 'step.completed'
+    && entry.step_id === 'authored-root'
+    && (entry.payload as { completionReason?: unknown } | undefined)?.completionReason === 'success');
+  const output = (completed?.payload as { output?: unknown } | undefined)?.output;
+  if (!isCompletedRootOutput(output)) {
+    throw new Error('completed authored root has no durable result');
+  }
+  return Object.freeze({
+    name: output.name,
+    completionReason: output.completionReason,
+    journalSteps: Object.freeze(output.journalSteps.map(step => Object.freeze({ ...step }))),
+    rootRunId,
+  });
+}
+
+function isCompletedRootOutput(value: unknown): value is Omit<AuthoredFlowExecutionResult, 'rootRunId'> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const output = value as Partial<AuthoredFlowExecutionResult>;
+  return typeof output.name === 'string'
+    && (output.completionReason === 'success' || output.completionReason === 'needs_human')
+    && Array.isArray(output.journalSteps)
+    && output.journalSteps.every(step => typeof step === 'object' && step !== null
+      && typeof step.id === 'string' && typeof step.runId === 'string'
+      && isSurfaceCompletionReason(step.completionReason));
+}
+
+function assertRootCanDispatch(outcome: RunOutcome): void {
+  // The kernel reports `parked` after handing an agent lease to its worker;
+  // the pushed dispatch is the authority that work is live. An idempotent
+  // start retry may instead observe the same active state as `running`.
+  if (outcome.status === 'running' || outcome.status === 'parked') return;
+  throw new Error(`authored root "${outcome.run_id}" is ${outcome.status}`
+    + (outcome.completion_reason === null ? '' : ` (${outcome.completion_reason})`));
+}
+
+function rootAdmissionKey(value: string): string {
+  return `authored-root:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+function sha256(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function jsonSnapshot(value: unknown, label: string): unknown {
+  const encoded = JSON.stringify(value);
+  if (encoded === undefined) throw new Error(`${label} is not JSON serializable`);
+  return JSON.parse(encoded) as unknown;
+}
+
+function isRootMetadata(value: unknown): value is AuthoredRootMetadata {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const root = value as Partial<AuthoredRootMetadata>;
+  const surface = root.surface as Partial<SurfaceModuleAuthority> | undefined;
+  const sources = root.sources;
+  return root.kind === ROOT_KIND && typeof root.flowName === 'string'
+    && typeof root.flowPath === 'string' && /^[a-f0-9]{64}$/.test(root.sourceSha256 ?? '')
+    && typeof root.inputPresent === 'boolean' && surface?.packageName === '@relayflows/surface'
+    && typeof surface.version === 'string' && /^[a-f0-9]{64}$/.test(surface.packageSha256 ?? '')
+    && /^[a-f0-9]{64}$/.test(surface.runtimeSha256 ?? '')
+    && Array.isArray(sources) && sources.length > 0 && sources.every(isRootSourceAuthority)
+    && (root.localAgentStream === undefined
+      || /^local-agent-[a-f0-9-]+$/.test(root.localAgentStream));
+}
+
+function isRootSourceAuthority(value: unknown): value is AuthoredRootSourceAuthority {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const source = value as Partial<AuthoredRootSourceAuthority>;
+  const surface = source.surface as Partial<SurfaceModuleAuthority> | undefined;
+  return typeof source.path === 'string' && /^[a-f0-9]{64}$/.test(source.sourceSha256 ?? '')
+    && surface?.packageName === '@relayflows/surface' && typeof surface.version === 'string'
+    && /^[a-f0-9]{64}$/.test(surface.packageSha256 ?? '')
+    && /^[a-f0-9]{64}$/.test(surface.runtimeSha256 ?? '');
+}

package/src/authored-runtime-capability.ts

@@ -0,0 +1,40 @@
+import { stripTypeScriptTypes, register } from 'node:module';
+import { createHook } from 'node:async_hooks';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+
+/** A runtime with no-op promise hooks cannot distinguish await from ignored then. */
+export function assertAuthoredPromiseHooks(): void {
+  let initialized = false;
+  let resolved = false;
+  const hook = createHook({
+    init(_id, type) { if (type === 'PROMISE') initialized = true; },
+    promiseResolve() { resolved = true; },
+  });
+  try {
+    hook.enable();
+    void new Promise<void>((resolve) => resolve());
+  } finally { hook.disable(); }
+  if (!initialized || !resolved) throw new AuthoredFlowExecutionError(
+    'unsupported_promise_lifecycle',
+    'authored execution requires working Node promise hooks; use the standalone Node-authored runner with Node >=22.14',
+  );
+}
+
+export function assertAuthoredNodeVersion(version = process.versions.node): void {
+  const [major, minor] = version.split('.').map(Number);
+  if (!Number.isInteger(major) || !Number.isInteger(minor)
+    || major! < 22 || (major === 22 && minor! < 14)
+    || process.versions['bun'] !== undefined
+    || typeof stripTypeScriptTypes !== 'function' || typeof register !== 'function') {
+    throw new AuthoredFlowExecutionError('unsupported_promise_lifecycle',
+      'the authored runner requires Node >=22.14; no workflow body was executed');
+  }
+  assertAuthoredPromiseHooks();
+}
+
+/** PID 1 is valid when the standalone CLI is a container's init process. */
+export function parseAuthoredParentPid(value: string | undefined): number {
+  const pid = Number(value);
+  if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error('invalid authored parent identity');
+  return pid;
+}

package/src/authored-source-authority.ts

@@ -0,0 +1,62 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { register } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { canonicalize } from './canonical.js';
+import { loadAuthoredFlow } from './authored-flow-loader.js';
+import type { AuthoredRootMetadata } from './authored-root.js';
+const sha256 = (bytes: Uint8Array): string => createHash('sha256').update(bytes).digest('hex');
+
+/** Re-open the exact source graph and Surface instance pinned by the durable root. */
+export async function loadPinnedAuthoredSource(metadata: AuthoredRootMetadata, immutableNodeImport = false) {
+  const source = await readFile(metadata.flowPath);
+  if (sha256(source) !== metadata.sourceSha256) {
+    throw new Error('authored root source authority mismatch');
+  }
+  const sources = new Map([[pathToFileURL(metadata.flowPath).href, source.toString('utf8')]]);
+  for (const pinned of metadata.sources) {
+    const bytes = await readFile(pinned.path);
+    if (sha256(bytes) !== pinned.sourceSha256) {
+      throw new Error(`authored root source authority mismatch for "${pinned.path}"`);
+    }
+    sources.set(pathToFileURL(pinned.path).href, bytes.toString('utf8'));
+  }
+  if (immutableNodeImport) installPinnedSourceLoader(sources);
+  const loaded = await loadAuthoredFlow(metadata.flowPath);
+  if (canonicalize(loaded.surfaceAuthority) !== canonicalize(metadata.surface)
+    || loaded.getDefinition(loaded.handle).name !== metadata.flowName) {
+    throw new Error('authored root Surface module authority mismatch');
+  }
+  const loadedSources = loaded.graph.map(node => ({
+    path: node.path,
+    sourceSha256: metadata.sources.find(source => source.path === node.path)?.sourceSha256 ?? '',
+    surface: node.surfaceAuthority,
+  }));
+  if (canonicalize(loadedSources) !== canonicalize(metadata.sources)) {
+    throw new Error('authored root declared source graph authority mismatch');
+  }
+  return loaded;
+}
+
+let pinnedSourceLoaderInstalled = false;
+
+/** Isolated Node child only: preserve original URLs/resolution, load verified bytes. */
+function installPinnedSourceLoader(sources: Map<string, string>): void {
+  if (pinnedSourceLoaderInstalled) throw new Error('authored Node process already owns a source graph');
+  pinnedSourceLoaderInstalled = true;
+  // Node >=22.14 supports register and stripTypeScriptTypes. A loader thread
+  // receives the captured bytes, never reopening mutable authored paths.
+  const loader = `
+    import {stripTypeScriptTypes} from 'node:module';
+    let sources;
+    export function initialize(data){sources=new Map(data);}
+    export async function load(url,context,next){
+      if(sources.has(url))return {format:'module',shortCircuit:true,
+        source:stripTypeScriptTypes(sources.get(url),{mode:'transform',sourceUrl:url})};
+      if(url.startsWith('file:') && new URL(url).pathname.endsWith('.flow.ts'))
+        throw new Error('authored root declared source graph authority mismatch');
+      return next(url,context);
+    }
+  `;
+  register('data:text/javascript,' + encodeURIComponent(loader), { data: [...sources] });
+}

package/src/authored-worker-step.ts

@@ -11,6 +11,7 @@ import { SPEC_SCHEMA_VERSION, type FlowSpec, type StepSpec } from './spec.js';
 import { isSurfaceCompletionReason, readCompletedStepOutput, readSuccessfulOutput } from './authored-step-output.js';
 import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
 import { snapshotJsonValue } from './json-value.js';
+import { authoredChildAdmissionKey } from './authored-admission.js';
 
 const WORKSPACE_PERMISSION_ANNOTATION = /:\s*(readonly|readwrite)\s*$/i;
 
@@ -19,6 +20,7 @@ export function authoredWorkerRunner(
   definition: { name: string }, journal: JournalClient, flowPath: string,
   journalSteps: AuthoredFlowJournalStep[], waitOptions: RunLifecycleOptions,
   localAgentStream?: string, budget?: AuthoredBudget, headerBudget?: unknown,
+  rootRunId?: string,
 ) {
   async function run(step: StepSpec): Promise<unknown> {
     const id = step.id;
@@ -35,7 +37,7 @@ export function authoredWorkerRunner(
           diagnostic.severity === 'refusal',
       );
       throw new AuthoredFlowExecutionError(
-        refusal?.kind === 'budget_missing_price' || refusal?.kind === 'budget_syntax_invalid' ? refusal.kind
+        refusal?.kind === 'budget_syntax_invalid' ? refusal.kind
           : step.type === 'llm' ? 'llm_cli_unresolved' : 'agent_cli_unresolved',
         refusal?.message
           ?? `flow "${definition.name}" step "${id}": no CLI could be resolved for f.${step.type} `
@@ -79,7 +81,10 @@ export function authoredWorkerRunner(
     }
     return readCompletedStepOutput(journal, outcome.run_id, id, journalSteps);
     };
-    return budget === undefined ? consume(await journal.runStart(spec)) : budget.execute(journal, spec, consume);
+    const admissionKey = authoredChildAdmissionKey(rootRunId, id);
+    return budget === undefined
+      ? consume(await journal.runStart(spec, undefined, admissionKey))
+      : budget.execute(journal, spec, consume, admissionKey);
   }
 
   return {
@@ -164,6 +169,7 @@ export function authoredWorkerRunner(
 /** Deterministic commands execute inline under their per-invocation lease. */
 export function authoredDeterministicRunner(
   name: string, journal: JournalClient, journalSteps: AuthoredFlowJournalStep[], budget: AuthoredBudget,
+  rootRunId?: string,
 ) {
   return async (id: string, command: string, terminal = false, leaseMs?: number, verification?: NamedGate): Promise<string> => {
     const spec = toKernelSpec(compileSpec({
@@ -175,7 +181,12 @@ export function authoredDeterministicRunner(
         ...(verification === undefined ? {} : { verification }),
       }],
     }));
-    if (terminal) return readSuccessfulOutput(journal, await journal.runStart(spec), id, journalSteps);
-    return budget.execute(journal, spec, outcome => readSuccessfulOutput(journal, outcome, id, journalSteps));
+    const admissionKey = authoredChildAdmissionKey(rootRunId, id);
+    if (terminal) return readSuccessfulOutput(
+      journal, await journal.runStart(spec, undefined, admissionKey), id, journalSteps,
+    );
+    return budget.execute(
+      journal, spec, outcome => readSuccessfulOutput(journal, outcome, id, journalSteps), admissionKey,
+    );
   };
 }

package/src/budget-preflight.ts

@@ -1,31 +1,47 @@
 import type { CompiledFlowSpec } from './compile.js';
-import type { PreflightRefusal } from './preflight.js';
-import { MODEL_PRICING } from './model-pricing.js';
+import type { PreflightWarning } from './preflight.js';
+import { hasPricing } from './model-pricing.js';
+import { resolveAdapterKind } from './adapters/index.js';
 
-/** Legacy explicit envelopes keep their worker-supplied pricing contract. */
-export function budgetDiagnostics(flow: CompiledFlowSpec): PreflightRefusal[] {
-  if (flow.budget?.pricing !== 'frozen') return [];
-  const diagnostics: PreflightRefusal[] = [];
-  const declared = [
-    ...Object.entries(flow.agents ?? {}).map(([agent, d]) => ({ agent, model: d.model })),
-    ...flow.steps.flatMap(s => s.type !== 'deterministic' && s.model !== undefined
-      ? [{ stepId: s.id, model: s.model }] : []),
-  ];
+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.
+ *
+ * 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.
+ */
+export function budgetDiagnostics(
+  flow: CompiledFlowSpec,
+  resolved: ReadonlyMap<string, BudgetStepResolution> = new Map(),
+): PreflightWarning[] {
+  if (flow.budget?.pricing !== 'frozen' || flow.budget.maxDollars === undefined) return [];
+  const warnings: PreflightWarning[] = [];
   for (const step of flow.steps) {
-    if (step.type === 'deterministic' || flow.budget.maxDollars === undefined) continue;
-    const model = step.model ?? (step.type === 'agent' && step.agent !== undefined
-      ? flow.agents?.[step.agent]?.model : undefined);
-    if (model === undefined) diagnostics.push({
-      severity: 'refusal', kind: 'budget_missing_price', stepId: step.id,
-      message: `Step "${step.id}" needs a declared, priced model for its dollar budget.`,
-    });
-  }
-  for (const declaration of declared) {
-    if (Object.hasOwn(MODEL_PRICING, declaration.model)) continue;
-    diagnostics.push({
-      severity: 'refusal', kind: 'budget_missing_price', ...declaration,
-      message: `Model "${declaration.model}" has no frozen price for budget accounting.`,
+    if (step.type === 'deterministic') continue;
+    const resolution = resolved.get(step.id);
+    const model = resolution?.model
+      ?? step.model ?? (step.type === 'agent' && step.agent !== undefined
+        ? flow.agents?.[step.agent]?.model : undefined);
+    if (hasPricing(model)) continue;
+    const cli = resolution?.cli ?? step.cli;
+    const reason = model !== undefined
+      ? `model "${model}" has no frozen price`
+      : cli !== undefined && resolveAdapterKind(cli) === 'codex'
+        ? 'Codex selects its own model'
+        : 'no model is declared';
+    warnings.push({
+      severity: 'warning', kind: 'budget_unmetered', stepId: step.id,
+      message: `Step "${step.id}" is unmetered (${reason}); it does not count toward the dollar budget.`,
     });
   }
-  return diagnostics;
+  return warnings;
 }

package/src/cli/check.ts

@@ -358,7 +358,9 @@ function bindResolvedCliPaths(
       const resolution = byStep.get(step.id);
       if (resolution === undefined) return step;
       const directory = resolution.source === 'project' ? configDirectory : flowDirectory;
-      return { ...step, cli: canonicalCli(resolution.cli, directory) };
+      return { ...step, cli: canonicalCli(resolution.cli, directory),
+        ...(resolution.modelSource === 'adapter' && resolution.model !== undefined
+          ? { model: resolution.model } : {}) };
     }),
   };
 }