@relayflows/sdk 2.0.37 → 2.0.38

package/src/cli/run.ts

@@ -408,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
@@ -522,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,
@@ -798,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) {
@@ -812,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;
@@ -954,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 {
@@ -981,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],
@@ -996,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,
@@ -1018,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,
@@ -1098,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> {
@@ -1112,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/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';
@@ -20,7 +21,7 @@ export function requireCommunicationCli(cli: string | undefined): void {
 export async function completeCommunicationDispatch(client: JournalClient, dispatch: StepDispatchEvent,
   instruction: CommunicationInstruction, dataDir: string, runRoot?: string,
   environment?: NodeJS.ProcessEnv): Promise<void> {
-  const spec = dispatch.spec as KernelAgentStep;
+  const spec = dispatch.spec as ResolvedKernelAgentStep;
   requireCommunicationCli(spec.cli);
   let output: unknown;
   let completionReason: 'success' | 'worker_error' = 'success';
@@ -36,7 +37,7 @@ 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,
+  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
@@ -53,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;
@@ -80,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!, environment ?? process.env),
+    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));
@@ -100,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/failure-kinds.ts

@@ -144,6 +144,12 @@ export const RUN_FAILURE_KINDS = [
    * attaches and before the resume touches the journal.
    */
   'local_agent_unavailable',
+  /**
+   * The authored root's worker lease was lost and the kernel's retry did not
+   * reach this process. The run is NOT failed (`status: running`): its
+   * completed steps are journaled and `flows resume <rootRunId>` continues it.
+   */
+  'root_lease_lost',
 ] as const;
 
 /**
@@ -271,6 +277,14 @@ export interface StepFailedDetails {
    * `retries_exhausted`.
    */
   maxIterations?: number;
+  /**
+   * Attempts before this one that died without a result -- the kernel
+   * journaled them `crashed` or `lease_expired` itself -- and so, by design,
+   * consumed none of `maxIterations` (relayflowd-core recovery.rs). Present
+   * only when non-zero. Without it `attempt` can exceed `maxIterations`
+   * (`attempt=2/1`) and read as the kernel overrunning its own budget.
+   */
+  unchargedAttempts?: number;
   exitCode?: number;
   /**
    * Terminal-safe UTF-8 excerpt of the captured stdout, at most