@relayflows/sdk 2.0.37 → 2.0.38

package/src/authored-root.ts

@@ -12,13 +12,13 @@ import {
   type LoadedAuthoredFlow,
   type SurfaceModuleAuthority,
 } from './authored-flow-loader.js';
-import { JournalClient } from './journal-client.js';
+import { JournalClient, JournalProtocolError } from './journal-client.js';
 import type { RunOutcome, StepDispatchEvent } from './protocol.js';
 import { SPEC_SCHEMA_VERSION } from './spec.js';
 import type { RunLifecycleOptions } from './cli/run.js';
-import { withWorkerLease } from './worker-lease.js';
+import { isLeaseLost, withWorkerLease } from './worker-lease.js';
 import { AuthoredFlowExecutionError, AuthoredHumanParked } from './authored-flow-error.js';
-import { readOpenHumanWaits } from './authored-human.js';
+import { readOpenHumanWaits, resumeCommand } from './authored-human.js';
 import { isSurfaceCompletionReason } from './authored-step-output.js';
 import { readSubscriptionPark } from './authored-subscription-park.js';
 import { localAgentCredentialEnvironment } from './local-agent-environment.js';
@@ -134,7 +134,7 @@ export async function executeDurableAuthoredFlow(
     if (parked !== undefined) return { state: 'suspended', name: metadata.flowName,
       suspension: parked, journalSteps: [], rootRunId: outcome.run_id };
     const dispatch = await dispatchWait.promise;
-    return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
+    return await driveRootFollowingRetries(loaded, metadata, journal, peer, dispatch, options);
   } finally {
     cancelDispatch();
     peer.close();
@@ -177,7 +177,7 @@ export async function resumeDurableAuthoredFlow(
     if (parked !== undefined) return { state: 'suspended', name: metadata.flowName,
       suspension: parked, journalSteps: [], rootRunId };
     const dispatch = await dispatchWait.promise;
-    return await driveRoot(loaded, metadata, journal, peer, dispatch, options);
+    return await driveRootFollowingRetries(loaded, metadata, journal, peer, dispatch, options);
   } finally {
     cancelDispatch();
     peer.close();
@@ -214,6 +214,102 @@ export async function readAuthoredRootMetadata(
   return Object.freeze({ ...value, extensions: value.extensions ?? [] });
 }
 
+/**
+ * How many times one CLI re-drives a root whose lease it lost. Each re-drive
+ * replays completed steps from their journaled receipts, so the bound guards a
+ * lease that keeps being lost, not the cost of the work.
+ */
+const MAX_ROOT_REDRIVES = 3;
+/**
+ * How long to wait for the kernel to re-dispatch a root whose lease was lost:
+ * a full lease (30s, relayflowd LEASE_RENEWAL_MS) in case the daemon still
+ * held it, plus its sweep and grace.
+ */
+const ROOT_REDISPATCH_TIMEOUT_MS = 45_000;
+
+/**
+ * Drive the root, and FOLLOW the kernel when it retries the root attempt.
+ *
+ * A lost root lease is not a failed flow. The kernel journals the attempt
+ * `lease_expired` with `disposition: retry` without charging an iteration
+ * (relayflowd-core recovery.rs) and re-dispatches the root to the worker
+ * still attached on `peer` -- this process. Exiting there with
+ * "worker wait canceled" (customer rw_3a0fcb71) threw away a run the kernel
+ * was about to continue, including a child agent already on its second
+ * attempt: the re-driven body replays completed steps from their receipts and
+ * adopts that in-flight child (authored-step-output.ts). Only when no retry
+ * arrives does the error leave, as `root_lease_lost` naming the resume.
+ */
+async function driveRootFollowingRetries(
+  loaded: LoadedAuthoredFlow,
+  metadata: AuthoredRootMetadata,
+  journal: JournalClient,
+  peer: JournalClient,
+  firstDispatch: StepDispatchEvent,
+  options: Omit<DurableAuthoredOptions, 'admissionKey'>,
+): Promise<DurableAuthoredFlowResult> {
+  let dispatch = firstDispatch;
+  for (let redrives = 0; ; redrives += 1) {
+    // Listen before driving: the retry can be dispatched the moment the
+    // daemon sweeps the lease, before the aborted body has unwound. The
+    // timeout starts only once there is a lost lease to wait on.
+    const next = rootRedispatch(peer);
+    try {
+      const result = await driveRoot(loaded, metadata, journal, peer, dispatch, options);
+      next.cancel();
+      return result;
+    } catch (error) {
+      // `run_terminal` from a step verb means the run has already reached a
+      // terminal state. It is lease-shaped for worker cleanup, but the kernel
+      // cannot re-dispatch this root, so do not turn it into a 45s retry wait.
+      const terminal = error instanceof JournalProtocolError && error.code === 'run_terminal';
+      if (!isLeaseLost(error) || terminal || options.lifecycle?.signal?.aborted === true) {
+        next.cancel();
+        throw error;
+      }
+      const lost = sentence(error instanceof Error ? error.message : String(error));
+      const resume = resumeCommand(dispatch.run_id, options.dataDir, options.localAgentStream !== undefined);
+      if (redrives >= MAX_ROOT_REDRIVES) {
+        next.cancel();
+        throw rootLeaseLost(dispatch, `${lost} It was lost ${redrives + 1} times in this process; continue the run with: ${resume}`, error);
+      }
+      process.emitWarning(
+        `authored root run_id=${dispatch.run_id} attempt=${dispatch.attempt}: ${lost} Waiting for the kernel to retry it.`,
+        { code: 'FLOWS_ROOT_LEASE_LOST' },
+      );
+      try {
+        dispatch = await next.wait(ROOT_REDISPATCH_TIMEOUT_MS, options.lifecycle?.signal);
+      } catch (waitError) {
+        // A caller cancel while waiting is the caller's, not a lost lease.
+        if (aborted(options.lifecycle?.signal)) throw waitError;
+        throw rootLeaseLost(dispatch, `${lost} The kernel did not re-dispatch the root within ${ROOT_REDISPATCH_TIMEOUT_MS / 1000}s; continue the run with: ${resume}`, error);
+      }
+      if (dispatch.run_id !== firstDispatch.run_id) {
+        throw new Error('authored root retry was dispatched for a different run');
+      }
+    }
+  }
+}
+
+/** Read at call time: `signal.aborted` changes while this function awaits. */
+function aborted(signal: AbortSignal | undefined): boolean {
+  return signal?.aborted === true;
+}
+
+function sentence(text: string): string {
+  return /[.!?]$/.test(text) ? text : `${text}.`;
+}
+
+function rootLeaseLost(dispatch: StepDispatchEvent, message: string, cause: unknown): AuthoredFlowExecutionError {
+  const error = new AuthoredFlowExecutionError('root_lease_lost',
+    `authored root run ${dispatch.run_id} lost its worker lease on attempt ${dispatch.attempt}. ${message}`
+      + ' Completed steps are journaled and are not re-run.',
+    'lease_expired');
+  error.rootRunId = dispatch.run_id;
+  (error as { cause?: unknown }).cause = cause;
+  return error;
+}
+
 async function driveRoot(
   loaded: LoadedAuthoredFlow,
   metadata: AuthoredRootMetadata,
@@ -269,6 +365,9 @@ async function driveRoot(
     );
     return Object.freeze({ ...result, rootRunId: dispatch.run_id });
   } catch (error) {
+    // A lost lease is owned by the kernel's retry path, not by this attempt's
+    // terminalization or suspension handling.
+    if (isLeaseLost(error)) throw error;
     if (error instanceof AuthoredFlowExecutionError
       && error.code === 'subscription_suspended'
       && error.suspension !== undefined) {
@@ -376,7 +475,51 @@ function hasRootStream(step: Record<string, unknown>): boolean {
   try { rootStreamFromMetadata(step); return true; } catch { return false; }
 }
 
-function nextRootDispatch(peer: JournalClient): {
+/**
+ * Buffers the next root dispatch from the moment it is created; `wait`
+ * bounds only the time spent waiting for it. Unlike `nextRootDispatch`, no
+ * timer runs while the body is being driven -- a body longer than the
+ * timeout must not leave a rejected promise nobody awaits.
+ */
+function rootRedispatch(peer: JournalClient): {
+  wait(timeoutMs: number, signal?: AbortSignal): Promise<StepDispatchEvent>;
+  cancel(): void;
+} {
+  let received: StepDispatchEvent | undefined;
+  let deliver: ((dispatch: StepDispatchEvent) => void) | undefined;
+  const onDispatch = (dispatch: StepDispatchEvent): void => {
+    if (dispatch.step_id !== 'authored-root') return;
+    peer.off('step.dispatch', onDispatch);
+    if (deliver === undefined) received = dispatch;
+    else deliver(dispatch);
+  };
+  peer.on('step.dispatch', onDispatch);
+  const cancel = (): void => { peer.off('step.dispatch', onDispatch); };
+  return {
+    cancel,
+    wait: (timeoutMs, signal) => new Promise((resolve, reject) => {
+      if (received !== undefined) { resolve(received); return; }
+      const settle = (): void => {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+        cancel();
+      };
+      const onAbort = (): void => {
+        settle();
+        reject(new Error('waiting for the authored root to be re-dispatched was canceled', { cause: signal?.reason }));
+      };
+      const timer = setTimeout(() => {
+        settle();
+        reject(new Error('authored root was not re-dispatched'));
+      }, timeoutMs);
+      deliver = dispatch => { settle(); resolve(dispatch); };
+      if (signal?.aborted === true) onAbort();
+      else signal?.addEventListener('abort', onAbort, { once: true });
+    }),
+  };
+}
+
+function nextRootDispatch(peer: JournalClient, timeoutMs = 30_000): {
   promise: Promise<StepDispatchEvent>;
   cancel(): void;
 } {
@@ -385,7 +528,7 @@ function nextRootDispatch(peer: JournalClient): {
     const timer = setTimeout(() => {
       peer.off('step.dispatch', onDispatch);
       reject(new Error('authored root was not dispatched'));
-    }, 30_000);
+    }, timeoutMs);
     const onDispatch = (dispatch: StepDispatchEvent) => {
       if (dispatch.step_id !== 'authored-root') return;
       clearTimeout(timer);

package/src/authored-worker-step.ts

@@ -343,6 +343,7 @@ function stepDetails(
     ...(found.completionReason === undefined ? {} : { completionReason: found.completionReason }),
     ...(found.attempt === undefined ? {} : { attempt: found.attempt }),
     ...(found.maxIterations === undefined ? {} : { maxIterations: found.maxIterations }),
+    ...(found.unchargedAttempts === undefined ? {} : { unchargedAttempts: found.unchargedAttempts }),
     ...(found.exitCode === undefined ? {} : { exitCode: found.exitCode }),
     ...(found.stdoutTail === undefined ? {} : { stdoutTail: found.stdoutTail }),
     ...(found.stderrTail === undefined ? {} : { stderrTail: found.stderrTail }),

package/src/child-stop.ts

@@ -6,6 +6,8 @@ import { execFileSync, type ChildProcess } from 'node:child_process';
  * the `flows run` event loop alive long after the step itself has settled.
  */
 export const FORCE_KILL_DELAY_MS = 1_000;
+/** Bound for proving that a forced process group has actually disappeared. */
+export const GROUP_EXIT_CONFIRM_TIMEOUT_MS = 1_000;
 
 /**
  * The one stop path for a spawned agent process.
@@ -65,6 +67,7 @@ export function childStop(
   child: ChildProcess,
   ownsGroup: boolean,
   forceKillDelayMs: number = FORCE_KILL_DELAY_MS,
+  onStopped: (error?: Error) => void = () => {},
 ): ChildStop {
   // Pinned at the spawn rather than read per signal. Every interesting use of
   // this id happens AFTER the direct child has been reaped — the escalation
@@ -74,6 +77,17 @@ export function childStop(
   // which is exactly the window both of those need to address.
   const pid = child.pid;
   let forceTimer: NodeJS.Timeout | undefined;
+  let groupPoll: NodeJS.Timeout | undefined;
+  let forced = false;
+  let forcedAt: number | undefined;
+  let stopped = false;
+  const notifyStopped = (error?: Error): void => {
+    if (stopped) return;
+    stopped = true;
+    if (groupPoll !== undefined) clearTimeout(groupPoll);
+    groupPoll = undefined;
+    onStopped(error);
+  };
   const cancel = (): void => {
     if (forceTimer !== undefined) clearTimeout(forceTimer);
     forceTimer = undefined;
@@ -106,6 +120,21 @@ export function childStop(
       }
     });
   };
+  const awaitGroupExit = (): void => {
+    if (!groupAnswers()) {
+      notifyStopped();
+      return;
+    }
+    if (forcedAt !== undefined && Date.now() - forcedAt >= GROUP_EXIT_CONFIRM_TIMEOUT_MS) {
+      notifyStopped(new Error(`Process groups did not stop answering within ${GROUP_EXIT_CONFIRM_TIMEOUT_MS}ms after SIGKILL.`));
+      return;
+    }
+    if (groupPoll !== undefined) return;
+    groupPoll = setTimeout(() => {
+      groupPoll = undefined;
+      awaitGroupExit();
+    }, 10);
+  };
   const signalTree = (name: NodeJS.Signals): void => {
     if (ownsGroup && pid !== undefined) {
       escapedGroups ??= descendantGroups(pid);
@@ -127,6 +156,9 @@ export function childStop(
     kill: (): void => {
       cancel();
       signalTree('SIGKILL');
+      forced = true;
+      forcedAt ??= Date.now();
+      awaitGroupExit();
     },
     terminate: (): void => {
       cancel();
@@ -134,6 +166,9 @@ export function childStop(
       forceTimer = setTimeout(() => {
         forceTimer = undefined;
         signalTree('SIGKILL');
+        forced = true;
+        forcedAt ??= Date.now();
+        awaitGroupExit();
       }, forceKillDelayMs);
       // Deliberately REFERENCED, unlike every other timer we arm. The survivor
       // this escalation exists for is the one that ignored `SIGTERM` and holds
@@ -144,9 +179,13 @@ export function childStop(
       // `maySettleOnChildExit` confirms the group is empty.
     },
     maySettleOnChildExit: (): boolean => {
-      if (forceTimer === undefined) return true;
+      if (forceTimer === undefined && !forced) {
+        notifyStopped();
+        return true;
+      }
       if (groupAnswers()) return false;
       cancel();
+      notifyStopped();
       return true;
     },
   };

package/src/cli/add-extension.ts

@@ -36,7 +36,7 @@ function eventKeys(manifest: FlowExtensionManifest): readonly string[] {
 
 function formatBudget(budget: FlowExtensionManifest['permissions']['budget']): string {
   if (budget === undefined) return 'inherits base';
-  return [budget.dollars === undefined ? '' : `$${budget.dollars}`, budget.wallclock ?? ''].filter(Boolean).join(' / ') || 'inherits base';
+  return [budget.tokens === undefined ? '' : `${budget.tokens} tokens`, budget.dollars === undefined ? '' : `$${budget.dollars}`, budget.wallclock ?? ''].filter(Boolean).join(' / ') || 'inherits base';
 }
 
 export function describeExtension(manifest: FlowExtensionManifest): string[] {

package/src/cli/check.ts

@@ -1,4 +1,5 @@
 import { communicationInstruction } from '../communication/spec.js';
+import { rememberResolvedCliIdentities } from '../resolved-cli-identity.js';
 import { checkCommunicationEnvironment } from '../communication/preflight.js';
 import { accessSync, constants, readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, parse as parsePath, resolve } from 'node:path';
@@ -15,6 +16,7 @@ import { parseMcpConfig } from '../mcp-config.js';
 import type { StepGateInspection } from '../gate-contract.js';
 import type { CheckFailureKind, CheckWarningKind } from '../failure-kinds.js';
 import {
+  cliProbeKey,
   preflight,
   type CliResolution,
   type CliProbeResult,
@@ -202,11 +204,15 @@ export function checkAuthoredFlow(
     const projectConfig = options !== undefined
       ? options.projectConfig
       : projectConfigOrOptions as ProjectConfig | undefined;
-    const effectiveProbeCache = cliProbeCache ?? options?.probeCache;
+    // Keep the exact probe result so the executable identity selected during
+    // readiness is the one written onto the admitted step. Without an
+    // explicit map, preflight would allocate a private cache and a bare CLI
+    // name could be resolved again under the later worker cwd.
+    const effectiveProbeCache = cliProbeCache ?? options?.probeCache ?? new Map<string, CliProbeOutcome>();
     const config = projectConfig ?? readProjectConfig(dirname(absolutePath));
     const probes = systemProbes(dirname(absolutePath), config, invocation.environment);
     const result = preflight(authoring, {
-      ...(effectiveProbeCache === undefined ? {} : { cliProbeCache: effectiveProbeCache }),
+      cliProbeCache: effectiveProbeCache,
       projectCli: config.cli,
       projectConfigPath: config.path,
       projectSearchStart: dirname(absolutePath),
@@ -220,6 +226,7 @@ export function checkAuthoredFlow(
           result.resolutions,
           dirname(absolutePath),
           config.directory,
+          effectiveProbeCache,
         )
       : undefined;
     if (flow?.steps.some(step => step.type === 'agent' && communicationInstruction(step.instruction))) {
@@ -472,20 +479,34 @@ function bindResolvedCliPaths(
   resolutions: readonly CliResolution[],
   flowDirectory: string,
   configDirectory: string,
+  probeCache: ReadonlyMap<string, CliProbeOutcome>,
 ): FlowSpec {
   const byStep = new Map(resolutions.map((resolution) => [resolution.stepId, resolution]));
-  return {
+  const identities = new Map<string, string>();
+  const bound: FlowSpec = {
     ...flow,
     steps: flow.steps.map((step) => {
       if (step.type === 'deterministic') return step;
       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),
+      const managed = step.type === 'agent' && communicationInstruction(step.instruction) !== undefined;
+      const outcome = probeCache.get(cliProbeKey(resolution, managed));
+      const executable = outcome !== undefined && 'result' in outcome
+        ? outcome.result.executable
+        : undefined;
+      const boundCli = executable !== undefined && isAbsolute(executable)
+        ? executable
+        : canonicalCli(resolution.cli, directory);
+      if (executable !== undefined && isAbsolute(executable)) {
+        identities.set(step.id, resolution.cli);
+      }
+      return { ...step, cli: boundCli,
         ...(resolution.modelSource === 'adapter' && resolution.model !== undefined
           ? { model: resolution.model } : {}) };
     }),
   };
+  return rememberResolvedCliIdentities(bound, identities);
 }
 
 function canonicalCli(cli: string, directory: string): string {

package/src/cli/cli-probe.ts

@@ -1,13 +1,15 @@
-import { accessSync, constants } from 'node:fs';
-import { isAbsolute, resolve } from 'node:path';
+import { accessSync, constants, realpathSync } from 'node:fs';
+import { basename, isAbsolute, resolve } from 'node:path';
 import { execFile, spawnSync } from 'node:child_process';
 import { agentEnvironment, brokerEnvironment } from '../communication/environment.js';
 import { adapterIdentification, authenticationProbe, classifyModelProbeFailure, cliAdapterKind,
   displayInvocation, modelReadinessProbe, type CliInvocation } from '../cli-adapter.js';
 import { MODEL_ENV } from '../worker-cli.js';
 import { CliProbeError, type CliProbeResult } from '../preflight.js';
+import { pinCliAlias, pinCliAliasSync } from './pinned-cli-alias.js';
 
 interface ProbeRequest {
+  argv0?: string;
   executable: string;
   directory: string;
   invocation: CliInvocation;
@@ -35,12 +37,19 @@ function driveSync<T>(sequence: Generator<ProbeRequest, T, ProbeOutput>): T {
   let next = sequence.next();
   while (!next.done) {
     const request = next.value;
-    const result = spawnSync(request.executable, request.invocation.args, {
-      ...probeOptions(request),
-      // Preserve the old synchronous probe contract: provider CLIs must not
-      // inherit a readable stdin that can block auth/identify probes.
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    const pinned = pinCliAliasSync(request.executable, request.argv0 ?? basename(request.executable));
+    const result = (() => {
+      try {
+        return spawnSync(pinned.executable, request.invocation.args, {
+          ...probeOptions(request),
+          // Preserve the old synchronous probe contract: provider CLIs must not
+          // inherit a readable stdin that can block auth/identify probes.
+          stdio: ['ignore', 'pipe', 'pipe'],
+        });
+      } finally {
+        pinned.release();
+      }
+    })();
     const failure = classifySpawnFailure(result.error, result.signal, request.invocation.timeoutMs);
     if (failure !== undefined) throw failure;
     next = sequence.next({ status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' });
@@ -48,30 +57,35 @@ function driveSync<T>(sequence: Generator<ProbeRequest, T, ProbeOutput>): T {
   return next.value;
 }
 
-function probeOptions({ directory, invocation, environment }: ProbeRequest) {
+function probeOptions({ argv0, directory, invocation, environment }: ProbeRequest) {
   const env = { ...environment };
   delete env[MODEL_ENV];
   if (invocation.modelEnv !== undefined) env[MODEL_ENV] = invocation.modelEnv;
   return { cwd: directory, encoding: 'utf8' as const, timeout: invocation.timeoutMs,
-    maxBuffer: 1024 * 1024, env };
+    maxBuffer: 1024 * 1024, env, ...(argv0 === undefined ? {} : { argv0 }) };
 }
 
-function runProbeAsync(request: ProbeRequest): Promise<ProbeOutput> {
-  return new Promise((resolve, reject) => {
-    const child = execFile(request.executable, request.invocation.args, probeOptions(request),
-      (error, stdout, stderr) => {
-        // Numeric exit codes are probe results; launch, timeout, signal and buffer
-        // errors are failures to collect a fact, just as in the synchronous driver.
-        if (error?.killed && typeof error.code !== 'string') return reject(new CliProbeError(`timeout:${request.invocation.timeoutMs}ms`));
-        const failure = classifySpawnFailure(
-          error !== null && typeof error.code !== 'number' && error.signal == null ? error : undefined,
-          error?.signal ?? null, request.invocation.timeoutMs);
-        if (failure !== undefined) return reject(failure);
-        resolve({ status: error === null ? 0 : typeof error.code === 'number' ? error.code : null,
-          stdout, stderr });
-      });
-    child.stdin?.end();
-  });
+async function runProbeAsync(request: ProbeRequest): Promise<ProbeOutput> {
+  const pinned = await pinCliAlias(request.executable, request.argv0 ?? basename(request.executable));
+  try {
+    return await new Promise((resolve, reject) => {
+      const child = execFile(pinned.executable, request.invocation.args, probeOptions(request),
+        (error, stdout, stderr) => {
+          // Numeric exit codes are probe results; launch, timeout, signal and buffer
+          // errors are failures to collect a fact, just as in the synchronous driver.
+          if (error?.killed && typeof error.code !== 'string') return reject(new CliProbeError(`timeout:${request.invocation.timeoutMs}ms`));
+          const failure = classifySpawnFailure(
+            error !== null && typeof error.code !== 'number' && error.signal == null ? error : undefined,
+            error?.signal ?? null, request.invocation.timeoutMs);
+          if (failure !== undefined) return reject(failure);
+          resolve({ status: error === null ? 0 : typeof error.code === 'number' ? error.code : null,
+            stdout, stderr });
+        });
+      child.stdin?.end();
+    });
+  } finally {
+    await pinned.release();
+  }
 }
 
 function* probeSequence(
@@ -83,17 +97,27 @@ function* probeSequence(
 ): Generator<ProbeRequest, CliProbeResult, ProbeOutput> {
   const executable = yield* executableSequence(cli, directory, sourceEnvironment);
   if (executable === undefined) return { exists: false, authenticated: false };
-  const kind = cliAdapterKind(executable);
+  // The declaration selects the adapter; the canonical executable selects
+  // the bytes. Package-manager links commonly name `claude` or `codex` while
+  // targeting a generic `cli.js`, whose basename must not rewrite the adapter
+  // contract after resolution.
+  const kind = cliAdapterKind(cli);
   // Relay owns interactive CLI launch/injection. Its generic PTY path is not
   // the headless wrapper protocol; do not demand that protocol from Gemini,
   // Cursor, OpenCode, or other interactive tools. Never invent an auth pass.
   if (execution === 'managed' && kind === 'relayflows-wrapper-v1') {
-    return { exists: true, supported: true, authenticated: 'unverified' };
+    return { exists: true, supported: true, authenticated: 'unverified', executable };
   }
   const environment = execution === 'managed'
-    ? { ...brokerEnvironment(sourceEnvironment), ...agentEnvironment(executable, sourceEnvironment) }
+    ? { ...brokerEnvironment(sourceEnvironment), ...agentEnvironment(cli, sourceEnvironment) }
     : sourceEnvironment;
-  const probe = (invocation: CliInvocation): ProbeRequest => ({ executable, directory, invocation, environment });
+  const probe = (invocation: CliInvocation): ProbeRequest => ({
+    executable,
+    argv0: basename(cli),
+    directory,
+    invocation,
+    environment,
+  });
   const identification = adapterIdentification(kind);
   const identified = yield probe(identification.invocation);
   if (
@@ -110,6 +134,7 @@ function* probeSequence(
       exists: true,
       supported: true,
       authenticated: (yield probe(auth)).status === 0,
+      executable,
       authCommand,
     };
   }
@@ -126,6 +151,7 @@ function* probeSequence(
       supported: true,
       authenticated: true,
       modelAvailable: true,
+      executable,
       authCommand,
       modelCommand,
     };
@@ -145,6 +171,7 @@ function* probeSequence(
     supported: true,
     authenticated,
     modelAvailable: false,
+    executable,
     authCommand,
     modelCommand,
     modelExitCode: scopedProbe.status,
@@ -181,16 +208,25 @@ function redactProbeOutput(text: string): string {
 function* executableSequence(command: string, directory: string, environment: NodeJS.ProcessEnv): Generator<ProbeRequest, string | undefined, ProbeOutput> {
   if (command.includes('/') || isAbsolute(command)) {
     const path = isAbsolute(command) ? command : resolve(directory, command);
-    try {
-      accessSync(path, constants.X_OK);
-      return path;
-    } catch {
-      return undefined;
-    }
+    return canonicalExecutable(path);
   }
   const result = yield { executable: 'which', directory: process.cwd(),
     invocation: { args: [command], timeoutMs: 5_000 }, environment };
-  return result.status === 0 ? result.stdout.trim() : undefined;
+  return result.status === 0
+    ? canonicalExecutable(resolve(process.cwd(), result.stdout.trim()))
+    : undefined;
+}
+
+function canonicalExecutable(path: string): string | undefined {
+  try {
+    accessSync(path, constants.X_OK);
+    // Dispatch must retain the exact target that readiness probed. Keeping a
+    // symlink path would allow the link to be retargeted between admission and
+    // worker spawn even though the compiled step carries an absolute path.
+    return realpathSync(path);
+  } catch {
+    return undefined;
+  }
 }
 
 function classifySpawnFailure(

package/src/cli/direct-run.ts

@@ -21,7 +21,7 @@ import { authoredInput, authoredWorkerRemedy, localAgentRemedy } from './local-a
 import {
   authoredCompletion,
   authoredHumanParked,
-  authoredStepFailure,
+  authoredStepFailure, rootLeaseLostReport,
   connect,
   emptyReport,
   fromCheckReport,
@@ -212,6 +212,9 @@ export async function runDirectFlow(
     if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
       return authoredStepFailure('run', base, socketPath, error);
     }
+    if (error instanceof AuthoredFlowExecutionError && error.code === 'root_lease_lost') {
+      return rootLeaseLostReport('run', base, socketPath, error);
+    }
     if (error instanceof AuthoredHumanParked) {
       return authoredHumanParked('run', base, socketPath, error, { dataDir, localAgent: options.localAgent === true });
     }

package/src/cli/pinned-cli-alias.ts

@@ -0,0 +1,74 @@
+import {
+  mkdtempSync,
+  rmSync,
+  symlinkSync,
+} from 'node:fs';
+import {
+  mkdtemp,
+  rm,
+  symlink,
+} from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+
+export interface PinnedCliAlias {
+  executable: string;
+  release(): void;
+}
+
+export interface PinnedCliAliasSync {
+  executable: string;
+  release(): void;
+}
+
+function aliasName(identity: string): string {
+  const name = basename(identity);
+  if (name.length === 0 || name === '.' || name === '..') {
+    throw new Error(`Invalid CLI identity basename: ${JSON.stringify(identity)}`);
+  }
+  return name;
+}
+
+/** Execute pinned canonical bytes through the proved basename, including shebang scripts. */
+export async function pinCliAlias(executable: string, identity: string): Promise<PinnedCliAlias> {
+  const name = aliasName(identity);
+  if (basename(executable) === name) {
+    return { executable, release() {} };
+  }
+  const directory = await mkdtemp(join(tmpdir(), 'relayflow-cli-'));
+  const alias = join(directory, name);
+  try {
+    await symlink(executable, alias, 'file');
+  } catch (error) {
+    await rm(directory, { recursive: true, force: true });
+    throw error;
+  }
+  let released = false;
+  return { executable: alias, release: () => {
+    if (released) return;
+    rmSync(directory, { recursive: true, force: true });
+    released = true;
+  } };
+}
+
+/** Synchronous counterpart for the synchronous preflight contract. */
+export function pinCliAliasSync(executable: string, identity: string): PinnedCliAliasSync {
+  const name = aliasName(identity);
+  if (basename(executable) === name) {
+    return { executable, release() {} };
+  }
+  const directory = mkdtempSync(join(tmpdir(), 'relayflow-cli-'));
+  const alias = join(directory, name);
+  try {
+    symlinkSync(executable, alias, 'file');
+  } catch (error) {
+    rmSync(directory, { recursive: true, force: true });
+    throw error;
+  }
+  let released = false;
+  return { executable: alias, release: () => {
+    if (released) return;
+    rmSync(directory, { recursive: true, force: true });
+    released = true;
+  } };
+}