@relayflows/sdk 2.0.36 → 2.0.38

package/src/cli/run.ts

@@ -39,6 +39,7 @@ import {
   type LoweredCompletionReason,
 } from '../authored-completion.js';
 import { DEFAULT_LOCAL_AGENT_CAPACITY } from '../worker-slots.js';
+import { localAgentEnvironment } from '../local-agent-environment.js';
 import {
   checkFlow,
   type CheckReport,
@@ -176,20 +177,22 @@ export async function runFlow(
   dataDir: string,
   options: RunLifecycleOptions = {},
 ): Promise<RunExecution> {
+  const agentEnvironment = localAgentEnvironment();
   const prepared = parseDigestReference(path) ? await prepareDigestRun(path, options.bucket) : undefined;
   if (prepared && 'exitCode' in prepared) return prepared;
-  const checked = prepared ?? checkFlow(path);
+  const checked = prepared ?? checkFlow(path, { environment: agentEnvironment });
   if (!checked.report.ok || checked.flow === undefined) {
     return { exitCode: 2, report: fromCheckReport('run', checked.report) };
   }
 
-  return executeCheckedFlow(checked, dataDir, options);
+  return executeCheckedFlow(checked, dataDir, options, agentEnvironment);
 }
 
 async function executeCheckedFlow(
   checked: ReturnType<typeof checkFlow>,
   dataDir: string,
   options: RunLifecycleOptions,
+  agentEnvironment?: NodeJS.ProcessEnv,
 ): Promise<RunExecution> {
   const socketPath = socketFor(dataDir);
   // Carry the preflight's diagnostics as a RunReport from here on, so the
@@ -213,12 +216,12 @@ async function executeCheckedFlow(
     if (options.localAgent) {
       localAgent = await attachLocalAgent(
         client, dataDir, options.onPtyReady, undefined, options.agentCapacity,
-        undefined, declaredLocalAgentStreams(spec),
+        undefined, declaredLocalAgentStreams(spec), agentEnvironment,
       );
     }
     if (options.localAgent && spec.steps.some(step => step.type === 'agent' && communicationInstruction(step.instruction))) {
       const { attachCommunicationWorkers } = await import('../communication/local.js');
-      communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir);
+      communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir, agentEnvironment);
     }
     if (options.onJournalEntry !== undefined) client.on('entry', options.onJournalEntry);
     const outcome = await startWatched(client, spec, options);
@@ -281,6 +284,9 @@ export async function resumeFlow(
   dataDir: string,
   options: RunLifecycleOptions = {},
 ): Promise<RunExecution> {
+  // Resume can load authored source; consume the descriptor before reading the
+  // journal so no source evaluation can race credential pickup.
+  const agentEnvironment = localAgentEnvironment();
   const socketPath = socketFor(dataDir);
   const base = emptyReport('resume');
   const client = new JournalClient(socketPath);
@@ -323,11 +329,12 @@ export async function resumeFlow(
       if (options.localAgent) {
         authoredAgent = await attachLocalAgent(
           client, dataDir, options.onPtyReady, authoredRoot.localAgentStream, workerCapacity,
+          undefined, [], agentEnvironment,
         );
         authoredLlmClient = new JournalClient(socketPath);
         await authoredLlmClient.connect();
         await authoredLlmClient.hello('flows-authored-resume-llm');
-        authoredLlm = new LlmWorker(authoredLlmClient, `${authoredAgent.stream}-llm`, workerCapacity);
+        authoredLlm = new LlmWorker(authoredLlmClient, `${authoredAgent.stream}-llm`, workerCapacity, agentEnvironment);
         authoredLlm.on('error', onWorkerFailure('resume-llm', error => {
           llmFailure = error;
           client.close();
@@ -338,6 +345,7 @@ export async function resumeFlow(
         dataDir,
         localAgentStream: authoredAgent?.stream,
         ...(authoredAgent === undefined ? {} : { workerCapacity }),
+        ...(agentEnvironment === undefined ? {} : { agentEnvironment }),
         lifecycle: options,
       });
       if (result === undefined) throw new Error('authored root disappeared during resume');
@@ -356,11 +364,11 @@ export async function resumeFlow(
       if (!spec) throw new Error('Cannot attach a local worker: the journaled run spec is missing');
       authoredAgent = await attachLocalAgent(
         client, dataDir, options.onPtyReady, undefined, options.agentCapacity,
-        undefined, declaredLocalAgentStreams(spec),
+        undefined, declaredLocalAgentStreams(spec), agentEnvironment,
       );
       if (spec?.steps.some(step => step.type === 'agent' && communicationInstruction(step.instruction))) {
         const { attachCommunicationWorkers } = await import('../communication/local.js');
-        communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir);
+        communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir, agentEnvironment);
       }
     }
     const onEntry = options.onJournalEntry;
@@ -400,6 +408,9 @@ export async function resumeFlow(
     if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
       return authoredStepFailure('resume', base, socketPath, error, runId);
     }
+    if (error instanceof AuthoredFlowExecutionError && error.code === 'root_lease_lost') {
+      return rootLeaseLostReport('resume', base, socketPath, error, runId);
+    }
     // An authored resume that parks for want of a worker is a park, reported
     // like the run path's — and with the same remedy, because an authored root
     // admits its worker at run start: resuming again cannot attach one, so the
@@ -514,6 +525,38 @@ function authoredInputArgument(metadata: AuthoredRootMetadata | undefined): Auth
  * drove correctly, and it produces a report with no `status`, which is the
  * whole of what `RUN <id> unknown` ever meant.
  */
+/**
+ * The authored root's lease was lost and not re-dispatched to this process
+ * (authored-root.ts driveRootFollowingRetries). Exit 1 because this CLI did
+ * not finish the run, but the report says what is true of it: still
+ * `running` in the journal, and resumable -- never `protocol_error` with the
+ * generic "worker wait canceled" and no run id, which is what it was.
+ */
+export function rootLeaseLostReport(
+  command: RunCommand,
+  base: CheckReport | RunReport,
+  socketPath: string,
+  error: AuthoredFlowExecutionError,
+  fallbackRunId?: string,
+): RunExecution {
+  const rootRunId = error.rootRunId ?? fallbackRunId;
+  return {
+    exitCode: 1,
+    report: {
+      ...fromBase(command, base),
+      ok: false,
+      ...(rootRunId === undefined ? {} : { runId: rootRunId, rootRunId }),
+      socketPath,
+      status: 'running',
+      diagnostics: [...base.diagnostics, {
+        severity: 'failure',
+        kind: 'root_lease_lost',
+        message: error.message.replace(/^root_lease_lost: /, ''),
+      }],
+    },
+  };
+}
+
 export function authoredStepFailure(
   command: RunCommand,
   base: CheckReport | RunReport,
@@ -790,13 +833,27 @@ export async function classifyOutcome(
   let parkedStep: ParkedStep | undefined;
   let needsHuman = false;
   let unclassifiedPolls = 0;
-  while (current.status === 'parked') {
+  // `running` too: an authored body re-driven after a lost root lease re-admits
+  // its child by admission key and gets the EXISTING run back, mid-attempt.
+  // Only `parked` was followed, so that child -- on the attempt 2 the kernel
+  // retried it to -- fell straight through to "status running without a
+  // classifiable completion" and failed the flow (customer rw_3a0fcb71).
+  while (current.status === 'parked' || current.status === 'running') {
     const inspection = await inspectOutOfBandStep(client, current.run_id);
     // A runnable sibling may only be waiting for capacity held by a live
-    // attempt. Keep driving until that lease releases before declaring a park.
-    if (inspection?.parkedStep !== undefined && (inspection.needsHuman || inspection.runningStep === undefined)) {
+    // attempt or by a retry in backoff. Keep driving until that active work
+    // settles before declaring a park.
+    if (inspection?.parkedStep !== undefined && (inspection.needsHuman
+      || (inspection.runningStep === undefined && inspection.backoffStep === undefined))) {
       parkedStep = inspection.parkedStep;
       needsHuman = inspection.needsHuman;
+      // `run.get` reports the live snapshot as `running` for an ordinary
+      // runnable worker wait, even when `run.start`/`run.resume` already
+      // classified the outcome as parked. Conversely, a re-admitted run can
+      // arrive here with a stale `running` outcome after its worker vanished.
+      // The step-level inspection is authoritative that this is a park; do
+      // not copy its broader run status and lose that classification.
+      current = { ...current, status: 'parked' };
       break;
     }
     if (inspection?.runningStep !== undefined) {
@@ -804,6 +861,20 @@ export async function classifyOutcome(
       current = await client.runResume(current.run_id, command === 'run' || options.allowHumanInfluenced);
       continue;
     }
+    // A step in `backoff` is between attempts: the kernel has scheduled the
+    // next one (a dead worker's retry is due at once, but waits for the
+    // worker slot the dead attempt held; a failed attempt waits out the
+    // retry policy's delay, bounded by its max_backoff_ms). That is progress,
+    // not an unclassifiable state -- treating it as one gave up after 2s on a
+    // child whose attempt 2 then succeeded (customer rw_3a0fcb71). Once due,
+    // the step is dispatched (`running`, followed above) or, with no worker,
+    // left `runnable` and reported as a park.
+    if (inspection?.backoffStep !== undefined && inspection.runningStep === undefined) {
+      throwIfCanceled(options.signal, inspection.backoffStep.id);
+      await delay(EXPIRED_LEASE_POLL_MS, options.signal);
+      current = await client.runResume(current.run_id, command === 'run' || options.allowHumanInfluenced);
+      continue;
+    }
     if (inspection?.status === 'completed' || inspection?.status === 'failed') {
       current = await client.runResume(current.run_id, command === 'run' || options.allowHumanInfluenced);
       continue;
@@ -946,6 +1017,8 @@ interface OutOfBandInspection {
   parkedStep?: ParkedStep;
   needsHuman: boolean;
   runningStep?: RunningStep;
+  /** A step waiting out a retry backoff: its next attempt is scheduled. */
+  backoffStep?: ParkedStep;
 }
 
 interface RunningStep extends ParkedStep {
@@ -973,6 +1046,9 @@ async function inspectOutOfBandStep(
   const runningEntry = entries.find(([, step]) =>
     step.type !== 'deterministic' && step.state === 'running',
   );
+  const backoffEntry = entries.find(([, step]) =>
+    step.type !== 'deterministic' && step.state === 'backoff',
+  );
   const parkedEntry = humanEntry ?? runnableEntry;
   const parkedStep = parkedEntry === undefined ? undefined : {
     id: parkedEntry[0],
@@ -988,11 +1064,21 @@ async function inspectOutOfBandStep(
     needsHuman: humanEntry !== undefined,
     ...(parkedStep !== undefined ? { parkedStep } : {}),
     ...(runningStep !== undefined ? { runningStep } : {}),
+    ...(backoffEntry !== undefined ? { backoffStep: {
+      id: backoffEntry[0],
+      type: backoffEntry[1].type as Extract<StepType, 'llm' | 'agent'>,
+    } } : {}),
   };
 }
 
 // Match kernel/relayflowd/src/server/client.rs: allow the lease sweep to dispatch a retry.
 export const LEASE_SWEEP_GRACE_MS = 5_000;
+// How often to re-ask the daemon about a step whose lease looks expired here.
+const EXPIRED_LEASE_POLL_MS = 250;
+// A deadline unchanged for a whole lease (relayflowd LEASE_RENEWAL_MS, 30s)
+// plus the sweep grace was renewed by nobody: the attempt is dead and the
+// daemon never swept it. Fail rather than hang.
+const STALE_LEASE_MS = 30_000 + LEASE_SWEEP_GRACE_MS;
 
 async function waitForRunningStep(
   client: JournalClient,
@@ -1010,20 +1096,29 @@ async function waitForRunningStep(
     stepType: runningStep.type,
     leaseDeadlineMs,
   });
+  // When the lease deadline last changed, on this process's monotonic clock.
+  // A live worker renews every ~10s, moving the deadline; a dead lease the
+  // daemon has not swept keeps it. That -- not a comparison of the daemon's
+  // deadline with our wall clock -- is what separates the two under skew.
+  let deadlineSeenAt = performance.now();
   while (true) {
     throwIfCanceled(options.signal, runningStep.id);
     const remainingMs = leaseDeadlineMs + LEASE_SWEEP_GRACE_MS - Date.now();
-    if (remainingMs <= 0) {
+    if (performance.now() - deadlineSeenAt > STALE_LEASE_MS) {
       throw new Error(
         `worker lease for step "${runningStep.id}" expired at ${leaseDeadlineMs} without completion`,
       );
     }
-    await delay(Math.min(50, remainingMs), options.signal);
+    // Past the deadline by THIS clock alone is not an expiry: the daemon may
+    // still hold the lease (skew) or be sweeping it into a retry. Keep
+    // following the step, at a slower poll, until the daemon says otherwise.
+    await delay(remainingMs <= 0 ? EXPIRED_LEASE_POLL_MS : Math.min(50, remainingMs), options.signal);
     const snapshot = await client.runGet(runId);
     const step = snapshot.steps[runningStep.id];
     if (step?.state !== 'running') return;
     if (step.lease_deadline_ms !== undefined && step.lease_deadline_ms !== leaseDeadlineMs) {
       leaseDeadlineMs = step.lease_deadline_ms;
+      deadlineSeenAt = performance.now();
       options.onWait?.({
         runId,
         stepId: runningStep.id,
@@ -1090,7 +1185,14 @@ function errorMessage(error: unknown): string {
 }
 
 function throwIfCanceled(signal: AbortSignal | undefined, stepId: string): void {
-  if (signal?.aborted === true) throw new Error(`waiting for running step "${stepId}" was canceled`);
+  if (signal?.aborted === true) {
+    throw new Error(`waiting for running step "${stepId}" was canceled${cancelCause(signal)}`, { cause: signal.reason });
+  }
+}
+
+/** Why a wait was canceled, when whoever aborted it said (a lost lease does). */
+function cancelCause(signal: AbortSignal): string {
+  return signal.reason instanceof Error && signal.reason.name !== 'AbortError' ? `: ${signal.reason.message}` : '';
 }
 
 export function delay(ms: number, signal?: AbortSignal): Promise<void> {
@@ -1104,7 +1206,9 @@ export function delay(ms: number, signal?: AbortSignal): Promise<void> {
     const cancel = (): void => {
       clearTimeout(timer);
       signal.removeEventListener('abort', cancel);
-      rejectDelay(new Error('worker wait canceled'));
+      // Carries the abort reason: a bare "worker wait canceled" was all a
+      // lost root lease ever reported (customer rw_3a0fcb71).
+      rejectDelay(new Error(`worker wait canceled${cancelCause(signal)}`, { cause: signal.reason }));
     };
     if (signal.aborted) cancel();
     else signal.addEventListener('abort', cancel, { once: true });

package/src/cli/step-failure.ts

@@ -63,6 +63,8 @@ export async function stepFailureDetails(
   // Keyed by step, so interleaved steps never pool their attempts and a page
   // boundary never splits one step's history.
   const histories = new Map<string, AttemptHistory>();
+  // Attempts the kernel itself declared dead (see `unchargedAttempts`).
+  const uncharged = new Map<string, number>();
   while (true) {
     const { entries } = await client.journalRead(runId, fromSeq, 100);
     if (entries.length === 0) break;
@@ -93,6 +95,7 @@ export async function stepFailureDetails(
       // holds every entry; only this diagnostic's candidate is cleared.
       if (payload === undefined || typeof completionReason !== 'string' || completionReason === 'success') {
         histories.delete(stepId);
+        uncharged.delete(stepId);
         continue;
       }
       const history = histories.get(stepId) ?? { records: [], causes: [] };
@@ -101,6 +104,10 @@ export async function stepFailureDetails(
       history.records.push(attemptFailure(entry['attempt'], completionReason, payload['disposition'], payload));
       history.causes.push(failureCause(completionReason, payload));
       histories.set(stepId, history);
+      if (payload['disposition'] !== 'step_done' && payload['completed_by'] === 'kernel'
+        && (completionReason === 'crashed' || completionReason === 'lease_expired')) {
+        uncharged.set(stepId, (uncharged.get(stepId) ?? 0) + 1);
+      }
       // 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
@@ -116,6 +123,7 @@ export async function stepFailureDetails(
         ...(stepType === undefined ? {} : { stepType }),
         ...(typeof attempt === 'number' && Number.isSafeInteger(attempt) && attempt > 0 ? { attempt } : {}),
         ...(maxIterations === undefined ? {} : { maxIterations }),
+        ...((uncharged.get(stepId) ?? 0) > 0 ? { unchargedAttempts: uncharged.get(stepId) } : {}),
         ...terminalEvidence(payload),
         // A single failed attempt is already fully described by the scalars
         // above; repeating it as a one-element history would add a clause to
@@ -169,6 +177,16 @@ export function renderStepEvidence(details: StepFailedDetails): string {
 
 function renderAttempt(details: StepFailedDetails): string {
   if (details.attempt === undefined) return '';
+  const uncharged = details.unchargedAttempts ?? 0;
+  // `attempt=N/M` compares like with like only when every attempt was charged.
+  // A worker that died (crashed / lease_expired) costs no iteration, so a
+  // one-iteration step can legitimately run attempt 2 -- printed as
+  // `attempt=2/1` it read as the budget being overrun. Say which is which.
+  if (uncharged > 0 && uncharged < details.attempt) {
+    return ` attempt=${details.attempt}`
+      + ` (iteration ${details.attempt - uncharged}${details.maxIterations === undefined ? '' : `/${details.maxIterations}`};`
+      + ` ${uncharged} earlier attempt${uncharged === 1 ? '' : 's'} lost to a dead worker, not charged)`;
+  }
   return ` attempt=${details.attempt}`
     + (details.maxIterations === undefined ? '' : `/${details.maxIterations}`);
 }

package/src/cloud-run.ts

@@ -98,6 +98,7 @@ export async function prepareCloudSubmission(
   options: { input?: JsonValue; signal?: AbortSignal } = {},
 ): Promise<CloudSubmission> {
   let spec: FlowSpec | undefined;
+  let compiledKernelInput = false;
   let authored: { source: string; authority: CloudAuthoredAuthority; name: string; schedules: ScheduleTriggerSource[]; extensions: readonly FlowExtensionSubmission[] } | undefined;
   const inputPresent = Object.prototype.hasOwnProperty.call(options, 'input');
   let authoredInput: JsonValue | undefined;
@@ -150,7 +151,11 @@ export async function prepareCloudSubmission(
           // compatibility. If both fail, retain the original authoring diagnostic.
           try {
             spec = compileSpec(kernelToAuthoring(parsed));
-          } catch {
+            compiledKernelInput = true;
+          } catch (kernelError) {
+            if (kernelError instanceof CompileError && kernelError.kind === 'untrusted_cli_identity') {
+              throw new CloudFlowError('invalid_input', kernelError.message);
+            }
             throw error;
           }
         }
@@ -176,7 +181,9 @@ export async function prepareCloudSubmission(
     const kernel = toKernelSpec(spec!);
     // JSON is a YAML subset. Sending canonical data preserves the exact spec
     // while using the server's existing YAML-to-config admission path.
-    return { workflow: canonicalize(spec), fileType: 'yaml', inputPresent: false, specHash: specHash(kernel),
+    // A compiled input stays in the kernel dialect. kernelToAuthoring refuses
+    // serialized cli_identity: only local preflight may mint that proof.
+    return { workflow: canonicalize(compiledKernelInput ? kernel : spec), fileType: 'yaml', inputPresent: false, specHash: specHash(kernel),
       name: spec!.name ?? "flow", schedules: [] };
   }
   return {

package/src/communication/local.ts

@@ -8,7 +8,8 @@ import { loadRelayModules } from './relay.js';
 import { checkCommunicationEnvironment, CommunicationEnvironmentError } from './preflight.js';
 import { requireCommunicationCli } from './worker.js';
 
-export async function attachCommunicationWorkers(spec: KernelRunSpec, socketPath: string, dataDir: string) {
+export async function attachCommunicationWorkers(spec: KernelRunSpec, socketPath: string, dataDir: string,
+  environment?: NodeJS.ProcessEnv) {
   const steps = spec.steps.filter(step => step.type === 'agent' && communicationInstruction(step.instruction));
   checkCommunicationEnvironment(spec);
   try { await loadRelayModules(); }
@@ -28,7 +29,7 @@ export async function attachCommunicationWorkers(spec: KernelRunSpec, socketPath
       requireCommunicationCli(step.cli ?? spec.cli);
       if (step.surfaces?.workspace?.length) throw new Error('Local communication workers support stream surfaces only');
       const client = new JournalClient(socketPath);
-      const worker = new AgentWorker(client, { workerId: `communication-${randomUUID()}`, dataDir,
+      const worker = new AgentWorker(client, { workerId: `communication-${randomUUID()}`, dataDir, environment,
         requiredStreams: [channelName(step.id, '$receipts')],
         pins: { workspace: [], streams: step.surfaces?.streams?.map(({ stream }) => ({ stream, read_offset: 0 })) ?? [] } });
       workers.push({ client, worker });

package/src/communication/worker.ts

@@ -1,9 +1,10 @@
 import { communicationHistory } from './history.js';
-import { basename } from 'node:path';
+import { mkdir, mkdtemp, rm, symlink } from 'node:fs/promises';
+import { basename, join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import type { JournalClient } from '../journal-client.js';
 import type { StepDispatchEvent } from '../protocol.js';
-import type { KernelAgentStep } from '../spec.js';
+import type { ResolvedKernelAgentStep } from '../resolved-cli-identity.js';
 import { withWorkerLease } from '../worker-lease.js';
 import { workerInstruction } from '../worker-input.js';
 import { resolveCliModel } from '../cli-adapter.js';
@@ -18,13 +19,15 @@ export function requireCommunicationCli(cli: string | undefined): void {
   if (!cli?.trim()) throw new Error('Agent communication requires a declared CLI executable');
 }
 export async function completeCommunicationDispatch(client: JournalClient, dispatch: StepDispatchEvent,
-  instruction: CommunicationInstruction, dataDir: string, runRoot?: string): Promise<void> {
-  const spec = dispatch.spec as KernelAgentStep;
+  instruction: CommunicationInstruction, dataDir: string, runRoot?: string,
+  environment?: NodeJS.ProcessEnv): Promise<void> {
+  const spec = dispatch.spec as ResolvedKernelAgentStep;
   requireCommunicationCli(spec.cli);
   let output: unknown;
   let completionReason: 'success' | 'worker_error' = 'success';
   try {
-    output = await withWorkerLease(client, dispatch, signal => run(client, dispatch, instruction, spec, dataDir, signal, runRoot));
+    output = await withWorkerLease(client, dispatch, signal =>
+      run(client, dispatch, instruction, spec, dataDir, signal, runRoot, environment));
   } catch (error) {
     completionReason = 'worker_error';
     output = { error: error instanceof Error ? error.message : String(error) };
@@ -34,7 +37,8 @@ export async function completeCommunicationDispatch(client: JournalClient, dispa
       started_pins: dispatch.pins, end_pins: dispatch.pins });
 }
 async function run(client: JournalClient, dispatch: StepDispatchEvent, instruction: CommunicationInstruction,
-  spec: KernelAgentStep, dataDir: string, lease: AbortSignal, runRoot?: string): Promise<unknown> {
+  spec: ResolvedKernelAgentStep, dataDir: string, lease: AbortSignal, runRoot?: string,
+  environment?: NodeJS.ProcessEnv): Promise<unknown> {
   // Same contract as the CLI worker: a declared directory is resolved and held
   // inside the same run root the CLI worker measures against, before anything
   // is spawned. Thrown, not reported, because `completeCommunicationDispatch`
@@ -50,6 +54,7 @@ async function run(client: JournalClient, dispatch: StepDispatchEvent, instructi
   let pumping: Promise<void> | undefined;
   let receipts = Promise.resolve();
   let unsubscribe: (() => void) | undefined;
+  let cliLinkDirectory: string | undefined;
   try {
     let resolve!: (value: unknown) => void;
     let reject!: (reason: unknown) => void;
@@ -77,10 +82,20 @@ async function run(client: JournalClient, dispatch: StepDispatchEvent, instructi
       void receipts.catch(reject);
     });
     // Relay supplies each CLI's launch flags and injection behavior.
-    handle = await relay.broker.spawnPty({ name, cli: basename(spec.cli!).replace(/\.exe$/i, ''), task: prompt, channels: [], skipRelayPrompt: true,
-      model: resolveCliModel(spec.cli!, spec.model), cwd: directory,
-      harnessConfig: { runtime: 'pty', command: quote(spec.cli!), args: [],
-        cwd: directory, env: { ...agentEnvironment(spec.cli!),
+    const cliIdentity = spec.cli_identity ?? spec.cli!;
+    const argv0 = basename(cliIdentity);
+    let command = spec.cli!;
+    if (basename(command) !== argv0) {
+      const linkRoot = join(dataDir, 'communication');
+      await mkdir(linkRoot, { recursive: true, mode: 0o700 });
+      cliLinkDirectory = await mkdtemp(join(linkRoot, 'cli-'));
+      command = join(cliLinkDirectory, argv0);
+      await symlink(spec.cli!, command, 'file');
+    }
+    handle = await relay.broker.spawnPty({ name, cli: basename(cliIdentity).replace(/\.exe$/i, ''), task: prompt, channels: [], skipRelayPrompt: true,
+      model: resolveCliModel(cliIdentity, spec.model), cwd: directory,
+      harnessConfig: { runtime: 'pty', command: quote(command), args: [],
+        cwd: directory, env: { ...agentEnvironment(cliIdentity, environment ?? process.env),
           RELAYFLOW_COMMUNICATION_SOCKET: tools.path, RELAYFLOW_COMMUNICATION_TOKEN: tools.token },
         delivery: { mode: 'pty-injection', format: 'relay-block' } } });
     const ready = await handle.waitForReady(Math.min(instruction.timeoutMs, 90_000));
@@ -97,7 +112,10 @@ async function run(client: JournalClient, dispatch: StepDispatchEvent, instructi
     finally {
       try { await receipts; }
       finally { try { await handle?.release('Flow communication attempt ended', { deleteIdentity: true }); }
-        finally { try { await tools?.close(); } finally { await relay.close(); } } }
+        finally { try { await tools?.close(); } finally {
+          try { await relay.close(); }
+          finally { if (cliLinkDirectory) await rm(cliLinkDirectory, { recursive: true, force: true }); }
+        } } }
     }
   }
 }

package/src/compile.ts

@@ -24,10 +24,7 @@ import type {
   AgentStepSpec,
   DeterministicStepSpec,
   FlowSpec,
-  KernelAgentStep,
   KernelRunSpec,
-  KernelStepCommon,
-  KernelStepSpec,
   KernelTriggerSpec,
   KernelVerificationSpec,
   LlmStepSpec,
@@ -45,6 +42,13 @@ import { validateSpec, type ValidationResult } from './validate.js';
 import { snapshotJsonValue } from './json-value.js';
 import { expandYamlHelpers } from './yaml-helpers.js';
 import { expandCommunication, validateCommunicationTopology } from './communication/spec.js';
+import {
+  inheritResolvedCliIdentities,
+  resolvedCliIdentities,
+  type ResolvedKernelAgentStep,
+  type ResolvedKernelStepCommon,
+  type ResolvedKernelStepSpec,
+} from './resolved-cli-identity.js';
 
 export class CompileError extends Error {
   readonly errors: string[];
@@ -173,7 +177,7 @@ export function compileSpec(spec: unknown): CompiledFlowSpec {
     ...(input.workspace !== undefined ? { workspace: input.workspace } : {}),
     ...(input.tools !== undefined ? { tools: input.tools } : {}),
   };
-  return flow;
+  return inheritResolvedCliIdentities(spec, flow);
 }
 
 function compileStep(step: StepSpec): StepSpec {
@@ -325,6 +329,7 @@ export function toKernelSpec(flow: FlowSpec): KernelRunSpec {
   // This public boundary is callable without compileSpec. Compile again so
   // runtime casts are validated and all returned schema data is snapshotted.
   const compiled = compileSpec(flow);
+  const cliIdentities = resolvedCliIdentities(compiled);
 
   return {
     version: compiled.version,
@@ -347,7 +352,10 @@ export function toKernelSpec(flow: FlowSpec): KernelRunSpec {
     // reverse order would hand the green gate a source whose barrier it does
     // not wait for.
     steps: lowerNamedGates(lowerStepsGreenGates(compiled.steps))
-      .map((step) => toKernelStep(resolveNamedAgent(step, compiled.agents))),
+      .map((step) => toKernelStep(
+        resolveNamedAgent(step, compiled.agents),
+        cliIdentities?.get(step.id),
+      )),
     ...(compiled.budget !== undefined ? { budget: toKernelBudget(compiled.budget) } : {}),
   };
 }
@@ -374,7 +382,7 @@ export function kernelToAuthoring(value: unknown): unknown {
   const steps = requireKernelArray(root['steps'], 'spec.steps')
     .map((step, index) => kernelStepToAuthoring(step, `spec.steps[${index}]`));
   const triggers = root['triggers'];
-  return {
+  const authoring: FlowSpec = {
     ...copyDefined(root, ['version', 'name', 'description', 'cli']),
     ...(triggers !== undefined
       ? {
@@ -386,7 +394,8 @@ export function kernelToAuthoring(value: unknown): unknown {
     ...(root['budget'] !== undefined
       ? { budget: kernelBudgetToAuthoring(root['budget'], 'spec.budget') }
       : {}),
-  };
+  } as FlowSpec;
+  return authoring;
 }
 
 /**
@@ -443,17 +452,22 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
   const unionKeys = [
     'id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification', 'memory', 'requirements', 'input',
     'command', 'timeout_ms', 'lease_ms', 'on_non_zero', 'prompt', 'model', 'cli', 'instruction',
-    'cwd', 'recovery_mode', 'surfaces', 'permissions',
+    'cwd', 'recovery_mode', 'surfaces', 'permissions', 'cli_identity',
   ] as const;
   const step = requireKernelObject(value, unionKeys, at);
+  if (step['cli_identity'] !== undefined) {
+    throw new CompileError([
+      `${at}.cli_identity: host-proved adapter identity is not accepted from serialized input`,
+    ], 'untrusted_cli_identity');
+  }
   const type = step['type'];
   const commonKeys = ['id', 'type', 'depends_on', 'max_iterations', 'retry', 'verification', 'memory', 'requirements', 'input'] as const;
   const typeKeys = type === 'deterministic'
     ? ['command', 'timeout_ms', 'lease_ms', 'on_non_zero'] as const
     : type === 'llm'
-      ? ['prompt', 'model', 'cli'] as const
+      ? ['prompt', 'model', 'cli', 'cli_identity'] as const
       : type === 'agent'
-        ? ['instruction', 'cli', 'model', 'cwd', 'recovery_mode', 'surfaces', 'permissions'] as const
+        ? ['instruction', 'cli', 'model', 'cwd', 'recovery_mode', 'surfaces', 'permissions', 'cli_identity'] as const
         : [];
   assertKernelKeys(step, [...commonKeys, ...typeKeys], at);
   if (step['retry'] !== undefined) validateAuthoringRetryDefaults(step['retry'], `${at}.retry`);
@@ -596,8 +610,8 @@ function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-function toKernelStep(step: StepSpec): KernelStepSpec {
-  const common: KernelStepCommon = {
+function toKernelStep(step: StepSpec, cliIdentity?: string): ResolvedKernelStepSpec {
+  const common: ResolvedKernelStepCommon = {
     id: step.id,
     depends_on: step.input === undefined ? step.dependsOn ?? []
       : [...new Set([...(step.dependsOn ?? []), ...bindingDependencies(step.input)])],
@@ -605,6 +619,7 @@ function toKernelStep(step: StepSpec): KernelStepSpec {
     max_iterations: step.maxIterations ?? 1,
     retry: { ...KERNEL_RETRY_DEFAULTS },
     verification: toKernelVerification(step),
+    ...(cliIdentity !== undefined ? { cli_identity: cliIdentity } : {}),
     ...(step.requirements !== undefined ? { requirements: {
       ...Object.fromEntries(Object.entries(step.requirements).filter(([key]) => key !== 'expectedDurationMs')),
       ...(step.requirements.expectedDurationMs !== undefined ? { expected_duration_ms: step.requirements.expectedDurationMs } : {}),
@@ -643,7 +658,7 @@ function toKernelStep(step: StepSpec): KernelStepSpec {
       };
     }
     case 'agent': {
-      const out: KernelAgentStep = {
+      const out: ResolvedKernelAgentStep = {
         ...common,
         type: 'agent',
         instruction: step.instruction,

package/src/decimal-dollars.ts

@@ -0,0 +1,38 @@
+// Exact decimal-dollar arithmetic shared by the journal folds.
+
+/**
+ * Sum two decimal dollar strings exactly, at whatever scale they carry — the
+ * kernel's budget fold (`relayflowd-core/src/state/budget.rs`) aligns every
+ * fractional digit before adding, and it accepts arbitrary precision. Scaling
+ * to a fixed six fractional digits dropped a charge of `0.0000001` to zero, so
+ * `flows status` underreported spend the kernel had totalled exactly.
+ *
+ * A value that is not a decimal number is left out of the sum rather than
+ * counted as zero, and the caller is told by `malformed`.
+ */
+export function addDollars(left: string, right: string): string {
+  const parsed = [left, right].map((value) => /^\d+(?:\.\d+)?$/.test(value) ? value : null);
+  const usable = parsed.filter((value): value is string => value !== null);
+  if (usable.length === 0) return '0';
+  if (usable.length === 1) return normalizeDollars(usable[0]!);
+  const scale = Math.max(...usable.map((value) => (value.split('.')[1] ?? '').length));
+  const scaled = usable.map((value) => {
+    const [whole, fraction = ''] = value.split('.');
+    return BigInt(`${whole}${fraction.padEnd(scale, '0')}`);
+  });
+  return fromScaled(scaled[0]! + scaled[1]!, scale);
+}
+
+/** `12.3400` -> `12.34`, `0.000` -> `0`; the journal's own spelling otherwise. */
+function normalizeDollars(value: string): string {
+  const [whole, fraction = ''] = value.split('.');
+  return fromScaled(BigInt(`${whole}${fraction}`), fraction.length);
+}
+
+function fromScaled(total: bigint, scale: number): string {
+  if (scale === 0) return String(total);
+  const digits = String(total).padStart(scale + 1, '0');
+  const whole = digits.slice(0, digits.length - scale);
+  const fraction = digits.slice(digits.length - scale).replace(/0+$/, '');
+  return fraction.length === 0 ? whole : `${whole}.${fraction}`;
+}