@relayflows/sdk 2.0.37 → 2.0.39

package/src/cloud-deploy.ts

@@ -11,6 +11,7 @@ import {
 } from './flow-requirements.js';
 import { readProjectConfig } from './cli/check.js';
 import { assertNoUseDependencies, collectExtensionSubmissions } from './flow-extension-submit.js';
+import { parseVersionChange, type CloudFlowVersionChange } from './cloud-versions-wire.js';
 
 /**
  * Hosted listener deployment: the CLI form of the agentrelay.com onboarding's
@@ -104,6 +105,8 @@ export interface CloudDeployment {
   requirements: FlowRequirements;
   /** Integrations connected through the prompt during this deploy. */
   connected: string[];
+  /** The listener's active version after this deploy; absent from a Cloud without versions. */
+  version?: CloudFlowVersionChange;
 }
 
 export function parseRepository(value: string): { owner: string; name: string } {
@@ -165,9 +168,18 @@ export function parseTriggerSource(value: string): FlowTriggerSource {
   return { provider: provider as FlowTriggerProvider, settings };
 }
 
-export async function deployToCloud(
-  input: DeployToCloudInput, options: CloudConnectionOptions = {},
-): Promise<CloudDeployment> {
+/** One authored source, read and loaded the way every hosted deploy sends it. */
+export interface DeploySource {
+  bytes: Buffer;
+  source: string;
+  definition: ReturnType<Awaited<ReturnType<typeof loadAuthoredFlow>>['getDefinition']>;
+  extensions: Awaited<ReturnType<typeof collectExtensionSubmissions>>;
+  projectCli: string | undefined;
+}
+
+export async function loadDeploySource(
+  input: { path: string; plugins?: readonly string[] },
+): Promise<DeploySource> {
   if (!/\.flow\.ts$/iu.test(input.path)) {
     throw new CloudFlowError('unsupported_source', 'flows deploy takes one authored .flow.ts source.');
   }
@@ -204,6 +216,13 @@ export async function deployToCloud(
   } catch {
     projectCli = undefined;
   }
+  return { bytes, source, definition, extensions, projectCli };
+}
+
+export async function deployToCloud(
+  input: DeployToCloudInput, options: CloudConnectionOptions = {},
+): Promise<CloudDeployment> {
+  const { bytes, source, definition, extensions, projectCli } = await loadDeploySource(input);
   if (input.sources.length === 0 || input.sources.length > 10) {
     throw new CloudFlowError('invalid_input', 'Give between one and ten --on trigger sources.');
   }
@@ -274,11 +293,13 @@ export async function deployToCloud(
   if (!isCloudRecord(result) || typeof result.agentId !== 'string' || typeof result.status !== 'string') {
     throw new CloudFlowError('invalid_response', 'Cloud did not return a deployment.');
   }
+  const version = parseVersionChange(result.version);
   return {
     agentId: result.agentId, name, status: result.status,
     repository: input.repository, sources,
     sourceSha256: createHash('sha256').update(bytes).digest('hex'),
     requirements, connected,
+    ...(version === undefined ? {} : { version }),
   };
 }
 

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/cloud-versions-wire.ts

@@ -0,0 +1,58 @@
+import { isCloudRecord } from './cloud-http.js';
+
+/**
+ * What a Cloud write did to a listener's active version (cloud#4115).
+ * `reactivated`: the bytes match an earlier version, so the pointer moved to
+ * it without a new row, and `version` can be LOWER than `previousVersion`.
+ */
+export interface CloudFlowVersionChange {
+  version: number;
+  previousVersion: number | null;
+  change: 'created' | 'reactivated' | 'unchanged';
+}
+
+export interface CloudFlowVersion {
+  version: number;
+  sourceSha256: string;
+  origin: string;
+  createdAt: string;
+}
+
+const CHANGES = ['created', 'reactivated', 'unchanged'] as const;
+
+function isVersionNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 1;
+}
+
+/** Undefined for a Cloud that predates versions or a malformed field. */
+export function parseVersionChange(value: unknown): CloudFlowVersionChange | undefined {
+  if (!isCloudRecord(value) || !isVersionNumber(value.version)
+    || !(value.previousVersion === null || isVersionNumber(value.previousVersion))
+    || !(CHANGES as readonly unknown[]).includes(value.change)) return undefined;
+  return {
+    version: value.version,
+    previousVersion: value.previousVersion as number | null,
+    change: value.change as CloudFlowVersionChange['change'],
+  };
+}
+
+export function parseVersion(value: unknown): CloudFlowVersion | undefined {
+  if (!isCloudRecord(value) || !isVersionNumber(value.version) || typeof value.sourceSha256 !== 'string'
+    || typeof value.origin !== 'string' || typeof value.createdAt !== 'string') return undefined;
+  return { version: value.version, sourceSha256: value.sourceSha256, origin: value.origin, createdAt: value.createdAt };
+}
+
+/**
+ * `version 4 (was 3)`; a rollback by content says the number went down, so
+ * nobody reads v2-after-v3 as a failed deploy.
+ */
+export function describeVersionChange(change: CloudFlowVersionChange): string {
+  if (change.change === 'unchanged') return `version ${change.version} (unchanged)`;
+  const was = change.previousVersion === null ? '' : ` (was ${change.previousVersion}`;
+  if (change.change === 'reactivated') {
+    const down = change.previousVersion !== null && change.version < change.previousVersion
+      ? '; active version went down' : '';
+    return `re-activated version ${change.version}${was}${down}${was ? ')' : ''}`;
+  }
+  return `version ${change.version}${was}${was ? ')' : ''}`;
+}

package/src/cloud-versions.ts

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto';
+import { ensureIntegrationsConnected, type ConnectPrompt } from './cloud-connect.js';
+import {
+  CloudFlowError, cloudFetch, cloudRequest, isCloudRecord, type CloudConnectionOptions,
+} from './cloud-http.js';
+import {
+  FLOW_AGENT_HARNESSES, listCloudDeployments, loadDeploySource, type FlowTriggerSource,
+} from './cloud-deploy.js';
+import {
+  parseVersion, parseVersionChange, type CloudFlowVersion, type CloudFlowVersionChange,
+} from './cloud-versions-wire.js';
+import { flowRequirements, mergeFlowExtensionRequirements, type FlowRequirements } from './flow-requirements.js';
+
+/**
+ * Versions of a hosted listener (AgentWorkforce/cloud#4115). A deployed
+ * flow's source is immutable: `flows deploy <file> --flow <name-or-id>` makes
+ * the next version and moves the listener's pointer to it, leaving the
+ * listener's repository, triggers, approver, agents and run budget untouched;
+ * `flows rollback` moves the pointer to any recorded version.
+ */
+
+const LISTENER_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+
+export interface CloudListener {
+  agentId: string;
+  name: string;
+  status: string;
+  repository: { owner: string; name: string; host?: 'gitlab' };
+  sources: FlowTriggerSource[];
+  activeVersion: CloudFlowVersion | null;
+  versions: CloudFlowVersion[];
+}
+
+/** A listener id as given, else the one deployment in the workspace with that name. */
+export async function resolveCloudFlow(flow: string, options: CloudConnectionOptions = {}): Promise<string> {
+  const wanted = flow.trim();
+  if (!wanted) throw new CloudFlowError('invalid_input', '--flow needs a flow name or listener id.');
+  if (LISTENER_UUID.test(wanted)) return wanted.toLowerCase();
+  const deployments = await listCloudDeployments(options);
+  // Any listener id the workspace lists, before names: ids are not all uuids.
+  const byId = deployments.find(deployment => deployment.agentId === wanted);
+  if (byId) return byId.agentId;
+  const matches = deployments.filter(deployment => deployment.name.toLowerCase() === wanted.toLowerCase());
+  if (matches.length === 1) return matches[0]!.agentId;
+  if (matches.length === 0) {
+    throw new CloudFlowError('invalid_input', `No flow named "${wanted}" in this workspace; list them with: flows deployments`);
+  }
+  throw new CloudFlowError('invalid_input',
+    `More than one flow is named "${wanted}" (${matches.map(match => match.agentId).join(', ')}); pass the listener id.`);
+}
+
+export async function getCloudListener(agentId: string, options: CloudConnectionOptions = {}): Promise<CloudListener> {
+  const payload = await cloudRequest(`/api/v1/flows/listeners/${encodeURIComponent(agentId)}`, options);
+  const listener = isCloudRecord(payload) && isCloudRecord(payload.listener) ? payload.listener : undefined;
+  if (!listener || typeof listener.name !== 'string' || typeof listener.status !== 'string'
+    || !isCloudRecord(listener.repository) || typeof listener.repository.owner !== 'string'
+    || typeof listener.repository.name !== 'string' || !Array.isArray(listener.sources)) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not return the flow listener.');
+  }
+  const versions = isCloudRecord(payload) && Array.isArray(payload.versions)
+    ? payload.versions.flatMap(entry => parseVersion(entry) ?? []) : [];
+  return {
+    agentId,
+    name: listener.name,
+    status: listener.status,
+    repository: {
+      owner: listener.repository.owner, name: listener.repository.name,
+      ...(listener.repository.host === 'gitlab' ? { host: 'gitlab' as const } : {}),
+    },
+    sources: listener.sources.flatMap((entry): FlowTriggerSource[] => isCloudRecord(entry) && typeof entry.provider === 'string'
+      ? [{ provider: entry.provider as FlowTriggerSource['provider'],
+          settings: Object.fromEntries(Object.entries(isCloudRecord(entry.settings) ? entry.settings : {})
+            .flatMap(([key, value]) => typeof value === 'string' ? [[key, value]] : typeof value === 'boolean' ? [[key, String(value)]] : [])) }]
+      : []),
+    activeVersion: isCloudRecord(payload) ? parseVersion(payload.activeVersion) ?? null : null,
+    versions,
+  };
+}
+
+export interface DeployVersionInput {
+  path: string;
+  /** The flow's deployed name or its listener id. */
+  flow: string;
+  plugins?: readonly string[];
+  connect?: ConnectPrompt;
+  checkConnections?: boolean;
+}
+
+export interface CloudVersionDeployment {
+  agentId: string;
+  name: string;
+  status: string;
+  sourceSha256: string;
+  requirements: FlowRequirements;
+  connected: string[];
+  version: CloudFlowVersionChange;
+}
+
+/** `POST /api/v1/flows/listeners/<id>/versions`: the source alone becomes the next version. */
+export async function deployVersionToCloud(
+  input: DeployVersionInput, options: CloudConnectionOptions = {},
+): Promise<CloudVersionDeployment> {
+  const { bytes, source, definition, extensions, projectCli } = await loadDeploySource(input);
+  const agentId = await resolveCloudFlow(input.flow, options);
+  const listener = await getCloudListener(agentId, options);
+  options.signal?.throwIfAborted();
+  // Requirements derive from the source, read against the listener's own
+  // repository and triggers, exactly as the create form reads its flags.
+  const requirements = mergeFlowExtensionRequirements(
+    flowRequirements(definition, {
+      sources: listener.sources,
+      // A GitHub repository means every run needs GitHub; a GitLab project does not.
+      ...(listener.repository.host === 'gitlab' ? {} : { repository: listener.repository }),
+      ...(projectCli === undefined ? {} : { projectCli }),
+    }),
+    extensions.map(extension => ({ name: extension.name, permissions: extension.manifest.permissions })),
+  );
+  // As on create: a harness Cloud cannot run is refused here, not deployed.
+  // There is no --agents override beside --flow; the listener's agents stay.
+  const unsupported = requirements.harnessUses
+    .filter(use => !(FLOW_AGENT_HARNESSES as readonly string[]).includes(use.harness));
+  if (unsupported.length > 0) {
+    throw new CloudFlowError('unsupported_source',
+      `This flow declares ${unsupported.map(use => `${use.harness} (${use.detail})`).join(', ')}, which Cloud deployments cannot run yet; `
+      + `Cloud runs ${FLOW_AGENT_HARNESSES.join(' and ')}. Change the declaration before deploying a new version.`);
+  }
+  const whoami = await cloudRequest('/api/v1/auth/whoami', options);
+  const workspace = isCloudRecord(whoami) && isCloudRecord(whoami.currentWorkspace) ? whoami.currentWorkspace : undefined;
+  if (workspace === undefined || typeof workspace.id !== 'string' || !workspace.id) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not report a current workspace for this credential.');
+  }
+  // A draft activates nothing, so Cloud checks nothing; match it here.
+  const connected = listener.status !== 'listening' || input.checkConnections === false
+    ? []
+    : (await ensureIntegrationsConnected(requirements, {
+        ...options, workspaceId: workspace.id, ...(input.connect === undefined ? {} : { prompt: input.connect }),
+      })).connected;
+  options.signal?.throwIfAborted();
+  const result = await cloudFetch(`/api/v1/flows/listeners/${encodeURIComponent(agentId)}/versions`, options, {
+    method: 'POST', detail: true, body: JSON.stringify({
+      workspaceId: workspace.id,
+      source,
+      requirements: {
+        integrations: requirements.integrations.map(integration => integration.provider),
+        harnesses: requirements.harnesses,
+        mcp: requirements.mcp,
+      },
+      ...(extensions.length === 0 ? {} : { extensions }),
+    }),
+  });
+  const version = isCloudRecord(result) ? parseVersionChange(result.version) : undefined;
+  if (!isCloudRecord(result) || typeof result.status !== 'string' || version === undefined) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not return the new flow version.');
+  }
+  return {
+    agentId, name: listener.name, status: result.status,
+    sourceSha256: createHash('sha256').update(bytes).digest('hex'),
+    requirements, connected, version,
+  };
+}
+
+/** `POST /api/v1/flows/listeners/<id>/versions/<n>/activate`: history is kept; only the pointer moves. */
+export async function activateCloudFlowVersion(
+  flow: string, version: number, options: CloudConnectionOptions = {},
+): Promise<{ agentId: string; status: string; version: CloudFlowVersionChange }> {
+  if (!Number.isSafeInteger(version) || version < 1) {
+    throw new CloudFlowError('invalid_input', `A version is a positive whole number, got "${version}".`);
+  }
+  const agentId = await resolveCloudFlow(flow, options);
+  const result = await cloudFetch(
+    `/api/v1/flows/listeners/${encodeURIComponent(agentId)}/versions/${version}/activate`,
+    options, { method: 'POST', detail: true },
+  );
+  const change = isCloudRecord(result) ? parseVersionChange(result.version) : undefined;
+  if (!isCloudRecord(result) || typeof result.status !== 'string' || change === undefined) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not confirm the active version.');
+  }
+  return { agentId, status: result.status, version: change };
+}

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