@relayflows/sdk 2.0.11 → 2.0.13

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,58 @@
 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 }] : []),
-  ];
+/**
+ * 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;
+}
+
+/**
+ * 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.
+ */
+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/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/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 } : {}) };
     }),
   };
 }

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

@@ -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)),
@@ -182,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,9 +11,11 @@ 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';
+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;
@@ -76,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`:
@@ -119,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);
     }
@@ -151,7 +163,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
@@ -160,12 +215,16 @@ 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,
         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 +248,13 @@ export async function resumeFlow(
       },
     };
   } finally {
-    client.close();
+    try {
+      await authoredLlm?.close();
+      authoredLlmClient?.close();
+      await authoredAgent?.close();
+    } finally {
+      client.close();
+    }
   }
 }
 
@@ -352,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,
@@ -552,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`);
 }