@relayflows/sdk 2.0.39 → 2.0.41

package/src/step-fields.ts

@@ -25,6 +25,7 @@ export const STEP_COMMON_FIELDS = [
   'input',
   'verification',
   'maxIterations',
+  'transportRetries',
   'memory',
   'requirements',
 ] as const;
@@ -37,5 +38,5 @@ export const STEP_COMMON_FIELDS = [
 export const STEP_FIELDS_BY_TYPE = {
   deterministic: ['command', 'timeoutMs', 'lease_ms', 'onNonZero'],
   llm: ['prompt', 'model', 'cli', 'output'],
-  agent: ['instruction', 'agent', 'cli', 'model', 'cwd', 'transport', 'surfaces', 'recoveryMode', 'permissions', 'output'],
+  agent: ['timeoutMs', 'instruction', 'agent', 'cli', 'model', 'cwd', 'transport', 'surfaces', 'recoveryMode', 'permissions', 'output'],
 } as const satisfies Record<StepType, readonly string[]>;

package/src/validate.ts

@@ -403,6 +403,9 @@ class Validator {
     if (st['maxIterations'] !== undefined && !isPosInt(st['maxIterations'])) {
       this.fail(`${at}.maxIterations: expected a positive integer`);
     }
+    if (st['transportRetries'] !== undefined && !isTransportRetries(st['transportRetries'])) {
+      this.fail(`${at}.transportRetries: expected a non-negative integer no greater than ${KERNEL_U32_MAX}`);
+    }
 
     if (type === 'deterministic') {
       this.validateDeterministic(st as unknown as DeterministicStepSpec, at);
@@ -487,6 +490,13 @@ class Validator {
   }
 
   private validateAgent(st: AgentStepSpec, at: string): void {
+    if (st.timeoutMs !== undefined) {
+      if (!isPosInt(st.timeoutMs) || st.timeoutMs > 60 * 60_000) {
+        this.fail(`${at}.timeoutMs: expected a positive integer at most 3600000 (60 minutes)`);
+      }
+      if (st.transport === 'relay') this.fail(`${at}.timeoutMs: unsupported with relay transport`);
+      if ((st.maxIterations ?? 1) > 1) this.fail(`${at}.timeoutMs: requires maxIterations 1`);
+    }
     if (!isNonEmptyString(st.instruction)) {
       this.fail(`${at}.instruction: expected a non-empty string`);
     }
@@ -605,6 +615,14 @@ export function validateSpec(spec: unknown): ValidationResult {
 
 // --- predicates -------------------------------------------------------------
 
+/** spec.rs `max_transport_retries: u32`. */
+const KERNEL_U32_MAX = 4_294_967_295;
+
+/** A transport retry budget the kernel can deserialize. */
+export function isTransportRetries(v: unknown): v is number {
+  return isNonNegInt(v) && v <= KERNEL_U32_MAX;
+}
+
 function isObject(v: unknown): v is Record<string, unknown> {
   return typeof v === 'object' && v !== null && !Array.isArray(v);
 }

package/src/worker-cli.ts

@@ -3,8 +3,16 @@ import { basename, dirname, join, resolve, sep } from 'node:path';
 import { diffWorkspaceFiles, snapshotWorkspaceFiles } from './agent-artifacts.js';
 import { claudeResultOutcome, decodeProviderResult, decodeWrapperResult, requirePricedUsage } from './worker-usage.js';
 import { openSidechannel, type SidechannelContext } from './pty-sidechannel.js';
-import { openTranscriptWriter, transcriptPath, type TranscriptDigest, type TranscriptFile, type TranscriptWriter } from './agent-transcript.js';
-import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import {
+  openTranscriptWriter,
+  redactText,
+  transcriptPath,
+  type TranscriptDigest,
+  type TranscriptFile,
+  type TranscriptWriter,
+} from './agent-transcript.js';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { redactRelayError } from './redact.js';
 import { StringDecoder } from 'node:string_decoder';
 import { childStop } from './child-stop.js';
 import { reapOnExit } from './agent-reaper.js';
@@ -21,9 +29,14 @@ import {
   type WrapperSessionLimits,
 } from './wrapper-session.js';
 import { wrapperEnvironment } from './wrapper-runtime.js';
-import { redactRelayError } from './redact.js';
 import { applyStepEnvironment } from './step-env.js';
 import { TAIL_CLOSE_TIMEOUT_MS, openTranscriptTail, type TranscriptTailWriter } from './transcript-tail.js';
+import {
+  isRetryableSpawnError,
+  transportEvidence,
+  type CliTransportCause,
+  type CliTransportEvidence,
+} from './cli-transport-evidence.js';
 import {
   runAgentRelayTask,
   AgentRelayTransportError,
@@ -31,6 +44,9 @@ import {
 } from './agent-relay-transport.js';
 import { pinCliAlias } from './cli/pinned-cli-alias.js';
 
+export type { CliTransportCause, CliTransportEvidence, CliTransportPhase } from './cli-transport-evidence.js';
+export { agentCompletionReason } from './cli-transport-evidence.js';
+
 /** Present only when a dispatched agent step carries a journaled wake context. */
 export const WAKE_CONTEXT_ENV = 'RELAYFLOW_WAKE_CONTEXT';
 
@@ -53,6 +69,12 @@ export interface WorkerCliResult {
   exit_code: number | null;
   stdout_tail: string;
   stderr_tail: string;
+  /**
+   * Bounded, redacted process-lifecycle evidence for a direct CLI spawn.
+   * This is journaled in `trajectory_tail`, including when parsed JSON output
+   * would otherwise discard the process wrapper.
+   */
+  transport?: CliTransportEvidence;
   /**
    * Files the agent created or changed under its working directory,
    * cwd-relative POSIX paths, sorted. Measured by the worker that spawned the
@@ -99,6 +121,8 @@ export async function runAgentCli(
   relayContext?: AgentRelayContext,
   processEnvironment: NodeJS.ProcessEnv = process.env,
   cliIdentity?: string,
+  // Trailing parameter preserves existing positional callers.
+  stepTimeoutMs?: number,
 ): Promise<WorkerCliResult> {
   signal?.throwIfAborted();
   if (signal !== undefined && process.platform === 'win32') {
@@ -145,17 +169,21 @@ export async function runAgentCli(
     // discovery names are set from this dispatch, exactly as for a direct spawn.
     const wrapperEnv = wrapperEnvironment(processEnvironment);
     applyStepEnvironment(wrapperEnv, sidechannel);
-    return requirePricedUsage(decodeWrapperResult(await runWrapperSession(
+    const session = await runWrapperSession(
       cli,
       instruction,
       wakeContext,
       effectiveModel,
       wrapperEnv,
-      wrapperLimits,
+      stepTimeoutMs === undefined ? wrapperLimits : { ...wrapperLimits, executionTimeoutMs: stepTimeoutMs },
       signal,
       cwd,
       argv0,
-    )), effectiveModel);
+    );
+    const decoded = decodeWrapperResult(session);
+    // A wrapper that hit its deadline after reporting usage is still charged
+    // for it; what it wrote is not the step's output.
+    return requirePricedUsage(session.transport?.cause === 'timeout' ? { ...decoded, stdout_tail: '' } : decoded, effectiveModel);
   }
 
   const env: NodeJS.ProcessEnv = { ...processEnvironment };
@@ -166,6 +194,8 @@ export async function runAgentCli(
   applyStepEnvironment(env, sidechannel);
   const invocation = mode === 'llm' ? llmExecution(kind, instruction, effectiveModel) : agentExecution(kind, instruction, effectiveModel);
 
+  if (stepTimeoutMs !== undefined) invocation.timeoutMs = stepTimeoutMs;
+
   if (wakeContext !== undefined) {
     try {
       env[WAKE_CONTEXT_ENV] = JSON.stringify(wakeContext);
@@ -185,7 +215,9 @@ export async function runAgentCli(
   const args = [...invocation.args];
   args.splice(args.length - 1, 0, ...(kind === 'claude' ? ['--output-format', 'stream-json', '--verbose'] : ['--json']));
   const completion = kind === 'claude' ? claudeResultOutcome : undefined;
-  return requirePricedUsage(decodeProviderResult(await spawnInvocation(cli, { ...invocation, args }, env, signal, sidechannel, cwd, completion, argv0), kind, env), effectiveModel);
+  return requirePricedUsage(decodeProviderResult(await spawnInvocation(
+    cli, { ...invocation, args }, env, signal, sidechannel, cwd, completion, argv0, kind,
+  ), kind, env), effectiveModel);
   }
 }
 
@@ -325,9 +357,15 @@ async function spawnInvocation(
   cwd?: string,
   completion?: (line: string) => { failed: boolean } | undefined,
   argv0?: string,
+  kind?: CliAdapterKind,
 ): Promise<WorkerCliResult> {
-  let writeInput: (bytes: Buffer) => Promise<boolean> = async () => false;
-  let canDrive = () => false;
+  const pendingInput: Buffer[] = [];
+  let acceptingDrive = true;
+  let writeInput: (bytes: Buffer) => Promise<boolean> = async bytes => {
+    pendingInput.push(Buffer.from(bytes));
+    return true;
+  };
+  let canDrive = () => acceptingDrive;
   let driven = false;
   // Prove and pin the authored identity before opening any per-attempt
   // resources. If pinning fails there is then nothing else to unwind.
@@ -362,6 +400,12 @@ async function spawnInvocation(
       ...sidechannel,
       onDrive() { driven = true; sidechannel.onDrive(); },
     }, bytes => writeInput(bytes), () => canDrive());
+    // Decide the child's stdin shape before spawn. An unattended Codex process
+    // gets `/dev/null` from `ignore`, so it never enters the "additional input
+    // from stdin" path. Only an already-enrolled drive peer gets a writable
+    // pipe. View/passthrough retain live output without changing stdin.
+    driven = channel === undefined ? false : await channel.waitForDrive(100);
+    acceptingDrive = false;
     // Tee the transcript into bounded tail files beside the socket. Evidence
     // for `flows status --tail`, never the record; a failure here is a warning.
     tails = sidechannel === undefined ? undefined : openTails(sidechannel);
@@ -376,10 +420,10 @@ async function spawnInvocation(
   // Always a group of its own off Windows, so every stop — and
   // `reapOnExit` — reaches the whole agent tree, lease-bound or not.
   const ownsGroup = process.platform !== 'win32';
-  let child: ChildProcessWithoutNullStreams;
+  let child: ChildProcess;
   try {
     child = spawn(pinned.executable, invocation.args, {
-      stdio: ['pipe', 'pipe', 'pipe'], env,
+      stdio: [driven ? 'pipe' : 'ignore', 'pipe', 'pipe'], env,
       detached: ownsGroup,
       ...(argv0 === undefined ? {} : { argv0 }),
       ...(cwd === undefined ? {} : { cwd }),
@@ -389,20 +433,32 @@ async function spawnInvocation(
     throw error;
   }
   return new Promise((resolve) => {
-    child.stdin.on('error', () => {});
-    if (channel === undefined) child.stdin.end();
-    canDrive = () => !child.stdin.destroyed && !child.stdin.writableEnded;
-    // A pipe cannot be reopened after EOF. Give startup subscribers a bounded
-    // chance to opt into drive, then let unattended/view-only CLIs read EOF.
-    const inputTimer = channel === undefined ? undefined : setTimeout(() => {
-      if (!driven) child.stdin.end();
-    }, 100);
-    writeInput = bytes => new Promise(resolve => {
-      if (!canDrive()) { resolve(false); return; }
-      // write(false) still accepts the bytes. The completion callback waits
-      // until they flush; the sidechannel pauses its reader in the meantime.
-      child.stdin.write(bytes, error => resolve(!error));
-    });
+    const stdin = child.stdin;
+    stdin?.on('error', () => {});
+    canDrive = () => stdin !== null && !stdin.destroyed && !stdin.writableEnded;
+    let inputQueue = Promise.resolve(true);
+    writeInput = bytes => {
+      inputQueue = inputQueue.then(previousAccepted => {
+        if (!previousAccepted || !canDrive()) return false;
+        return new Promise<boolean>(resolve => {
+          // write(false) still accepts the bytes. The completion callback
+          // waits until they flush; the sidechannel pauses its reader.
+          stdin!.write(bytes, error => resolve(!error));
+        });
+      });
+      return inputQueue;
+    };
+    for (const bytes of pendingInput.splice(0)) void writeInput(bytes);
+    // The last driver leaving is the end of input: flush what it sent, then
+    // EOF. Without it a driven Codex waits on its stdin lifecycle forever.
+    if (driven) {
+      channel?.whenDriveIdle(() => {
+        inputQueue = inputQueue.then(() => {
+          if (canDrive()) stdin!.end();
+          return false;
+        });
+      });
+    }
     let release = () => {};
     const stdout: Buffer[] = [];
     const stderr: Buffer[] = [];
@@ -414,7 +470,6 @@ async function spawnInvocation(
     const finish = (result: WorkerCliResult, discardTranscript = false): void => {
       if (settled) return;
       settled = true;
-      if (inputTimer !== undefined) clearTimeout(inputTimer);
       channel?.close();
       if (timer !== undefined) clearTimeout(timer);
       if (graceTimer !== undefined) clearTimeout(graceTimer);
@@ -498,8 +553,12 @@ async function spawnInvocation(
       timer = undefined;
       if (graceTimer !== undefined) clearTimeout(graceTimer);
       graceTimer = undefined;
+      const transport = transportEvidence({
+        phase: 'abort', cause: 'lease_lost', exitCode: null, signal: null,
+        stderr: 'Agent execution aborted: lease ownership lost.', retryable: false,
+      }, env);
       finishAfterStop(
-        { exit_code: null, stdout_tail: '', stderr_tail: 'Agent execution aborted: lease ownership lost.' },
+        { exit_code: null, stdout_tail: '', stderr_tail: 'Agent execution aborted: lease ownership lost.', transport },
         'kill',
         true,
         'abort',
@@ -529,14 +588,22 @@ async function spawnInvocation(
     const onResult = (outcome: { failed: boolean }): void => {
       if (graceTimer !== undefined || settled) return;
       graceTimer = setTimeout(() => {
+        const exitCode = outcome.failed ? 1 : 0;
+        const stderrText = `${Buffer.concat(stderr).toString('utf8')}\nCLI reported its final result but had not exited ${RESULT_EXIT_GRACE_MS}ms later; its process tree was stopped.`.trim();
+        const transport = transportEvidence({
+          phase: 'result_exit_grace', cause: 'result_exit_timeout', exitCode, signal: null,
+          stderr: stderrText,
+          retryable: false,
+        }, env);
         finishAfterStop({
-          exit_code: outcome.failed ? 1 : 0,
+          exit_code: exitCode,
           stdout_tail: Buffer.concat(stdout).toString('utf8'),
-          stderr_tail: `${Buffer.concat(stderr).toString('utf8')}\nCLI reported its final result but had not exited ${RESULT_EXIT_GRACE_MS}ms later; its process tree was stopped.`.trim(),
+          stderr_tail: redactText(stderrText, env),
+          transport,
         }, 'terminate');
       }, RESULT_EXIT_GRACE_MS);
     };
-    child.stdout.on('data', (chunk: Buffer) => {
+    child.stdout!.on('data', (chunk: Buffer) => {
       stdout.push(chunk);
       channel?.publish(chunk);
       // The tails take raw bytes, so they are fed before any line splitting
@@ -555,28 +622,59 @@ async function spawnInvocation(
         if (outcome !== undefined) onResult(outcome);
       }
     });
-    child.stderr.on('data', (chunk: Buffer) => { stderr.push(chunk); channel?.publish(chunk); tails?.stderr.append(chunk); });
-    child.once('error', (error) => finishOnChildExit({
-      exit_code: null,
-      stdout_tail: Buffer.concat(stdout).toString('utf8'),
-      stderr_tail: error.message,
-    }));
+    child.stderr!.on('data', (chunk: Buffer) => { stderr.push(chunk); channel?.publish(chunk); tails?.stderr.append(chunk); });
+    child.once('error', (error) => {
+      const code = typeof (error as NodeJS.ErrnoException).code === 'string'
+        ? (error as NodeJS.ErrnoException).code : undefined;
+      const retryable = isRetryableSpawnError(code);
+      const transport = transportEvidence({
+        phase: 'spawn', cause: child.pid === undefined ? 'spawn_error' : 'process_error',
+        exitCode: null, signal: null, stderr: error.message, errorCode: code, retryable,
+      }, env);
+      finishOnChildExit({
+        exit_code: null,
+        stdout_tail: Buffer.concat(stdout).toString('utf8'),
+        stderr_tail: redactText(error.message, env),
+        transport,
+      });
+    });
     child.once('error', () => { if (child.pid === undefined) release(); });
     child.once('close', release);
-    child.once('close', (code) => finishOnChildExit({
-      exit_code: code,
-      stdout_tail: Buffer.concat(stdout).toString('utf8'),
-      stderr_tail: Buffer.concat(stderr).toString('utf8'),
-    }));
+    child.once('close', (code, signalName) => {
+      const stderrText = Buffer.concat(stderr).toString('utf8');
+      const codexStdinLifecycle = kind === 'codex' && code === 1
+        && stderrText.trim() === 'Reading additional input from stdin...';
+      const cause: CliTransportCause = codexStdinLifecycle ? 'codex_stdin_lifecycle'
+        : signalName !== null ? 'signal'
+          : code === null ? 'close_without_status'
+            : code === 0 ? 'exited' : 'nonzero_exit';
+      const retryable = codexStdinLifecycle || signalName !== null || code === null;
+      const transport = transportEvidence({
+        phase: 'close', cause, exitCode: code, signal: signalName, stderr: stderrText, retryable,
+      }, env);
+      finishOnChildExit({
+        exit_code: code,
+        stdout_tail: Buffer.concat(stdout).toString('utf8'),
+        stderr_tail: redactText(stderrText, env),
+        transport,
+      });
+    });
     if (invocation.timeoutMs > 0) {
       timer = setTimeout(() => {
         // The stop owns this settle: a direct-child event is not proof that its
         // group is gone, and an unprovable forced stop must fail the step rather
         // than arriving after a successful result has already won the race.
+        const timeoutMessage = `CLI invocation timed out after ${invocation.timeoutMs}ms.`;
+        const transport = transportEvidence({
+          phase: 'timeout', cause: 'timeout', exitCode: null, signal: null,
+          stderr: `${Buffer.concat(stderr).toString('utf8')}\n${timeoutMessage}`,
+          retryable: false,
+        }, env);
         finishAfterStop({
           exit_code: null,
           stdout_tail: Buffer.concat(stdout).toString('utf8'),
-          stderr_tail: `CLI invocation timed out after ${invocation.timeoutMs}ms.`,
+          stderr_tail: timeoutMessage,
+          transport,
         }, 'terminate');
       }, invocation.timeoutMs);
     }

package/src/worker-spend.ts

@@ -35,7 +35,10 @@ function unmeteredUsage(input: number | undefined, output: number | undefined):
  */
 export function workerSpend(result: WorkerCliResult, model?: string): { result: WorkerCliResult; usage: StepUsage | undefined } {
   try {
-    const usage = pricedUsage(model, result.tokens_input, result.tokens_output)
+    // Usage that was never reported is unknown, not a measured $0, even for a
+    // priced model (a step stopped before its CLI reported, for one).
+    const reported = result.tokens_input !== undefined && result.tokens_output !== undefined;
+    const usage = (reported ? pricedUsage(model, result.tokens_input, result.tokens_output) : undefined)
       ?? unmeteredUsage(result.tokens_input, result.tokens_output);
     return { result, usage };
   }

package/src/worker.ts

@@ -7,13 +7,20 @@ import type { JournalClient } from './journal-client.js';
 import type { Pins, StepDispatchEvent } from './protocol.js';
 import type { ResolvedKernelAgentStep } from './resolved-cli-identity.js';
 import { runAgentCli } from './worker-cli.js';
+import { agentCompletionReason } from './cli-transport-evidence.js';
 import { agentStepCwd } from './agent-cwd.js';
 import { resolveCliModel } from './cli-adapter.js';
 import { withWorkerLease } from './worker-lease.js';
 import { workerInstruction } from './worker-input.js';
 import { helperCall } from './yaml-helpers.js';
 import { completeHelperDispatch } from './yaml-helper-effect.js';
-import { ARTIFACT_PATHS_MAX, boundTranscriptDigest, type TranscriptDigest } from './agent-transcript.js';
+import {
+  ARTIFACT_PATHS_MAX,
+  boundTranscriptDigest,
+  boundedTail,
+  redactText,
+  type TranscriptDigest,
+} from './agent-transcript.js';
 
 export { MODEL_ENV, WAKE_CONTEXT_ENV } from './worker-cli.js';
 
@@ -149,11 +156,11 @@ export class AgentWorker extends EventEmitter {
             spec.transport === 'relay' ? 'relay' : 'direct',
             { runId: dispatch.run_id, stepId: dispatch.step_id, idempotencyKey: dispatch.idempotency_key,
               dataDir: this.options.dataDir, resultSchema: spec.verification?.json_schema },
-            this.options.environment, spec.cli_identity)
+            this.options.environment, spec.cli_identity, spec.timeout_ms)
           : Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: 'agent step has no declared CLI' }));
     const { result, usage } = workerSpend(completed, effectiveModel);
     const cost = reportedCost(completed, effectiveModel);
-    const completionReason = result.exit_code === 0 ? 'success' : 'worker_error';
+    const completionReason = agentCompletionReason(result);
 
     // Output shape: if the CLI's stdout parses as JSON, promote THAT
     // as the step's `output` value so `json_schema` verification
@@ -181,7 +188,16 @@ export class AgentWorker extends EventEmitter {
     // `transcript` is not part of the wrapper either: it is evidence about the
     // attempt, journaled in `trajectory_tail` below on success and failure
     // alike, where the kernel already accepts and bounds it (16 KiB).
-    const { transcript, ...wrapper } = result;
+    const { transcript, transport, ...rawWrapper } = result;
+    // `stderr_tail` is evidence, not authored output. Redact and bound it
+    // before it reaches either the worker-failure render or the journal --
+    // against the environment the CLI ran with as well as this host's, since a
+    // secret supplied only to the CLI is the one most likely to be echoed.
+    const redacted = redactText(redactText(rawWrapper.stderr_tail), this.options.environment ?? process.env);
+    const wrapper = {
+      ...rawWrapper,
+      stderr_tail: boundedTail(redacted, 2 * 1024, 'worker stderr: ').text,
+    };
     const output = result.relay_task?.status === 'completed' && result.exit_code === 0
       ? result.relay_task.output : parseJsonOutput(result.stdout_tail) ?? wrapper;
     const trajectoryTail = {
@@ -190,6 +206,7 @@ export class AgentWorker extends EventEmitter {
         task_execution: result.relay_task.task_execution, error: result.relay_task.error,
       } }),
       ...(transcript === undefined ? {} : { transcript: transcriptDigest(transcript, dispatch.attempt, result) }),
+      ...(transport === undefined ? {} : { transport }),
     };
 
     await this.client.stepComplete(

package/src/wrapper-session.ts

@@ -1,3 +1,4 @@
+import { transportEvidence, type CliTransportEvidence } from './cli-transport-evidence.js';
 import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { childStop, ownsProcessGroup } from './child-stop.js';
 import { reapOnExit } from './agent-reaper.js';
@@ -29,6 +30,7 @@ export interface WrapperSessionLimits {
 }
 
 export interface WrapperSessionResult {
+  transport?: CliTransportEvidence;
   exit_code: number | null;
   stdout_tail: string;
   stderr_tail: string;
@@ -157,7 +159,7 @@ async function executePinnedWrapper(
     let exitCode: number | null = null;
     /** The handshake deadline, then the execution deadline if there is one. */
     let lifecycleTimer: NodeJS.Timeout | undefined;
-    /** The post-exit drain grace, armed only when execution is unlimited. */
+    /** The post-exit drain grace, armed once the wrapper has exited and acknowledged. */
     let drainTimer: NodeJS.Timeout | undefined;
 
     const finish = (result: WrapperSessionResult): void => {
@@ -231,7 +233,7 @@ async function executePinnedWrapper(
     };
     signal?.addEventListener('abort', onAbort, { once: true });
     if (signal?.aborted) { onAbort(); return; }
-    const terminate = (message: string): void => {
+    const terminate = (message: string, transport?: WrapperSessionResult['transport'], captured = ''): void => {
       if (protocolError !== undefined) return;
       protocolError = message;
       if (lifecycleTimer !== undefined) clearTimeout(lifecycleTimer);
@@ -247,7 +249,7 @@ async function executePinnedWrapper(
       // The shared stop owns both the liveness bound and settlement. Its
       // callback preserves this refusal once group death is proved, or
       // replaces it with a fail-closed confirmation error when it is not.
-      finishAfterStop(failure(message), 'terminate');
+      finishAfterStop({ ...failure(message), stdout_tail: captured, ...(transport === undefined ? {} : { transport }) }, 'terminate');
     };
     const startExecutionTimer = (): void => {
       if (lifecycleTimer !== undefined) clearTimeout(lifecycleTimer);
@@ -258,9 +260,29 @@ async function executePinnedWrapper(
       // and what bounds the work from here is the lease abort — the same thing
       // that bounds a `claude` or `codex` step.
       if (limits.executionTimeoutMs <= 0) return;
-      lifecycleTimer = setTimeout(() => terminate(
+      lifecycleTimer = setTimeout(() => {
+        lifecycleTimer = undefined;
+        // The deadline bounds a wrapper that is still running. One that has
+        // already exited did not time out, whatever it left holding stdio:
+        // its settle belongs to the post-exit drain, which reports the
+        // wrapper's own exit. Re-arming here is idempotent.
+        if (childExited) {
+          startDrainGrace();
+          return;
+        }
+        onExecutionDeadline();
+      }, limits.executionTimeoutMs);
+    };
+    const onExecutionDeadline = (): void => {
+      terminate(
         `CLI ${JSON.stringify(cli)} execution timed out after ${limits.executionTimeoutMs}ms.`,
-      ), limits.executionTimeoutMs);
+        transportEvidence({ phase: 'timeout', cause: 'timeout', retryable: false, exitCode: null, signal: null,
+          stderr: `CLI execution timed out after ${limits.executionTimeoutMs}ms.` }, env),
+        // What the wrapper wrote before its deadline, so a result envelope it
+        // already emitted still reports its usage. Only the caller decides
+        // what of it, if anything, is output.
+        stdout.join('') + executionPending,
+      );
     };
     const exceedsOutputLimit = (additionalBytes: number): boolean => {
       const pendingBytes = Buffer.byteLength(executionPending);
@@ -382,13 +404,13 @@ async function executePinnedWrapper(
       finishOnChildExit(result);
     };
     /**
-     * Arm the post-exit drain, for an unlimited session that has both seen the
-     * wrapper exit and consumed its acknowledgement. A session with an explicit
-     * execution deadline keeps its existing behaviour: that deadline is what
-     * bounds a withheld `'close'` there, and nothing about it changes.
+     * Arm the post-exit drain, for a session that has both seen the wrapper
+     * exit and consumed its acknowledgement. This holds with or without an
+     * execution deadline: the deadline bounds a wrapper still running, and a
+     * wrapper that exited — even with a descendant holding stdio — settles as
+     * its own exit here rather than waiting out the deadline as a timeout.
      */
     const startDrainGrace = (): void => {
-      if (limits.executionTimeoutMs > 0) return;
       if (!childExited || phase !== 'execute') return;
       if (settled || drainTimer !== undefined || protocolError !== undefined) return;
       drainTimer = setTimeout(drainExpired, DRAIN_AFTER_EXIT_MS);

package/src/yaml-helpers.ts

@@ -63,7 +63,7 @@ export type HelperCall = { [P in keyof YamlHelperParams]: { [V in keyof YamlHelp
 }[keyof YamlHelperParams[P]] }[keyof YamlHelperParams];
 
 const prefix = HELPER_INSTRUCTION_PREFIX;
-const commonFields = ['id', 'dependsOn', 'maxIterations', 'verification', 'output'] as const;
+const commonFields = ['id', 'dependsOn', 'maxIterations', 'transportRetries', 'verification', 'output'] as const;
 const isObject = (value: unknown): value is Record<string, unknown> =>
   value !== null && typeof value === 'object' && !Array.isArray(value);