@relayflows/sdk 2.0.39 → 2.0.40

package/src/cli/step-evidence.ts

@@ -17,6 +17,13 @@ export const ATTEMPT_TAIL_BYTES = 256;
  */
 const PRODUCER_TRUNCATED = /…\s*\((?:render bounded|[\d,]+ bytes truncated)\)$/u;
 
+/**
+ * What the worker puts in front of a stderr it cut to its tail (`boundedTail`
+ * in worker.ts and cli-transport-evidence.ts). The same rule applies: equal
+ * surviving tails cannot establish equal failures.
+ */
+const STDERR_TRUNCATED = /^\[(?:worker|transport) stderr: [\d,]+ bytes truncated\]…/u;
+
 /**
  * The evidence fields a step failure reports, as the journal held them.
  *
@@ -29,6 +36,11 @@ const PRODUCER_TRUNCATED = /…\s*\((?:render bounded|[\d,]+ bytes truncated)\)$
  */
 export interface SelectedEvidence {
   exitCode?: number;
+  transportPhase?: string;
+  transportCause?: string;
+  signal?: string;
+  errorCode?: string;
+  retryableTransport?: boolean;
   /** Present only when nonempty. */
   stdoutTail?: string;
   /** Present whenever the journal carried one, including the empty string. */
@@ -57,16 +69,18 @@ export interface SelectedEvidence {
 export function selectEvidence(payload: Record<string, unknown>): SelectedEvidence {
   const detail = record(payload['verification'])?.['detail'];
   const rendered = typeof detail === 'string' ? parsed(detail) : undefined;
+  const trajectory = record(payload['trajectory_tail']);
+  const transport = record(trajectory?.['transport']);
   const candidates = [
     record(payload['output']),
-    record(payload['trajectory_tail']),
+    trajectory,
     rendered,
   ].filter((candidate): candidate is Record<string, unknown> => candidate !== undefined);
   const structured = candidates.find(processShaped) ?? candidates[0];
-  const exitCode = structured?.['exit_code'];
+  const exitCode = structured?.['exit_code'] ?? transport?.['exit_code'];
   const stdout = structured?.['stdout_tail'];
-  const stderr = structured?.['stderr_tail'];
-  const transcript = record(record(payload['trajectory_tail'])?.['transcript']);
+  const stderr = structured?.['stderr_tail'] ?? transport?.['stderr_tail'];
+  const transcript = record(trajectory?.['transcript']);
   const failure = record(transcript?.['failure']);
   const excerpt = failure?.['excerpt'];
   const transcriptPath = record(transcript?.['file'])?.['path'];
@@ -77,6 +91,11 @@ export function selectEvidence(payload: Record<string, unknown>): SelectedEviden
     ? excerpt : undefined;
   return {
     ...(typeof exitCode === 'number' && Number.isSafeInteger(exitCode) ? { exitCode } : {}),
+    ...(typeof transport?.['phase'] === 'string' ? { transportPhase: transport['phase'] } : {}),
+    ...(typeof transport?.['cause'] === 'string' ? { transportCause: transport['cause'] } : {}),
+    ...(typeof transport?.['signal'] === 'string' ? { signal: transport['signal'] } : {}),
+    ...(typeof transport?.['error_code'] === 'string' ? { errorCode: transport['error_code'] } : {}),
+    ...(typeof transport?.['retryable'] === 'boolean' ? { retryableTransport: transport['retryable'] } : {}),
     ...(typeof stdout === 'string' && stdout.length > 0 ? { stdoutTail: stdout } : {}),
     ...(typeof stderr === 'string' ? { stderrTail: stderr } : {}),
     ...(excerptDetail !== undefined ? { detail: excerptDetail }
@@ -117,6 +136,11 @@ export function terminalEvidence(payload: Record<string, unknown>): Partial<Step
   const selected = selectEvidence(payload);
   return {
     ...(selected.exitCode === undefined ? {} : { exitCode: selected.exitCode }),
+    ...(selected.transportPhase === undefined ? {} : { transportPhase: formatStepExcerpt(selected.transportPhase) }),
+    ...(selected.transportCause === undefined ? {} : { transportCause: formatStepExcerpt(selected.transportCause) }),
+    ...(selected.signal === undefined ? {} : { signal: formatStepExcerpt(selected.signal) }),
+    ...(selected.errorCode === undefined ? {} : { errorCode: formatStepExcerpt(selected.errorCode) }),
+    ...(selected.retryableTransport === undefined ? {} : { retryableTransport: selected.retryableTransport }),
     ...(selected.stdoutTail === undefined ? {} : { stdoutTail: formatStepExcerpt(selected.stdoutTail) }),
     ...(selected.stderrTail === undefined ? {} : { stderrTail: formatStepExcerpt(selected.stderrTail) }),
     ...(selected.detail === undefined ? {} : { detail: formatStepExcerpt(selected.detail) }),
@@ -151,6 +175,13 @@ export function attemptFailure(
     completionReason,
     ...(typeof disposition === 'string' && disposition.length > 0 ? { disposition } : {}),
     ...(selected.exitCode === undefined ? {} : { exitCode: selected.exitCode }),
+    // Closed-vocabulary scalars, so a crash that left no stderr still says how
+    // it died (`signal=SIGKILL`) rather than reading as no evidence at all.
+    ...(selected.signal === undefined ? {} : { signal: bound(selected.signal) }),
+    ...(selected.transportCause === undefined ? {} : { transportCause: bound(selected.transportCause) }),
+    ...(selected.transportPhase === undefined ? {} : { transportPhase: bound(selected.transportPhase) }),
+    ...(selected.errorCode === undefined ? {} : { errorCode: bound(selected.errorCode) }),
+    ...(selected.retryableTransport === undefined ? {} : { retryableTransport: selected.retryableTransport }),
     ...(selected.stdoutTail === undefined ? {} : { stdoutTail: bound(selected.stdoutTail) }),
     ...(selected.stderrTail === undefined ? {} : { stderrTail: bound(selected.stderrTail) }),
     ...(selected.detail === undefined ? {} : { detail: bound(selected.detail) }),
@@ -177,15 +208,18 @@ export function failureCause(
   const verification = record(payload['verification']);
   const output = record(payload['output']);
   const trajectory = record(payload['trajectory_tail']);
+  const transport = record(trajectory?.['transport']);
   const failure = record(record(trajectory?.['transcript'])?.['failure']);
   const verificationDetail = text(verification?.['detail']);
   const accounts = [
     verificationDetail,
     text(output?.['stdout_tail']), text(output?.['stderr_tail']),
     text(trajectory?.['stdout_tail']), text(trajectory?.['stderr_tail']),
+    text(transport?.['phase']), text(transport?.['cause']), text(transport?.['signal']),
+    text(transport?.['error_code']), text(transport?.['stderr_tail']),
     text(failure?.['excerpt']),
   ];
-  const exitCodes = [output?.['exit_code'], trajectory?.['exit_code']]
+  const exitCodes = [output?.['exit_code'], trajectory?.['exit_code'], transport?.['exit_code']]
     .filter(value => typeof value === 'number');
   return {
     key: JSON.stringify([
@@ -197,13 +231,15 @@ export function failureCause(
       completionReason === 'verification_failed' || completionReason === 'retries_exhausted'
         ? 'kernel_rejected' : completionReason,
       text(verification?.['gate']), text(verification?.['verdict']), verificationDetail,
-      ...exitCodes, ...accounts, text(failure?.['kind']),
+      ...exitCodes, ...accounts, transport?.['retryable'], text(failure?.['kind']),
     ]),
     // An attempt that journaled nothing about itself cannot agree with
     // another one; it can only fail to disagree.
     recorded: exitCodes.length > 0 || accounts.some(account => account !== undefined),
     producerTruncated: (verificationDetail !== undefined
       && PRODUCER_TRUNCATED.test(verificationDetail))
+      || [output?.['stderr_tail'], trajectory?.['stderr_tail'], transport?.['stderr_tail']]
+        .some(stderr => typeof stderr === 'string' && STDERR_TRUNCATED.test(stderr))
       // The transcript digest's own flag (`boundTranscriptDigest`,
       // agent-transcript.ts): the worker already cut this excerpt, so equal
       // survivors cannot establish identical failures either.
@@ -255,8 +291,16 @@ export function renderAttemptHistory(details: StepFailedDetails): string {
 }
 
 function renderAttempt(attempt: StepAttemptFailure): string {
+  const transport = [
+    attempt.signal === undefined ? '' : ` signal=${attempt.signal}`,
+    attempt.transportCause === undefined ? '' : ` transport=${attempt.transportCause}`,
+    attempt.transportPhase === undefined ? '' : ` phase=${attempt.transportPhase}`,
+    attempt.errorCode === undefined ? '' : ` error_code=${attempt.errorCode}`,
+    attempt.retryableTransport === undefined ? '' : ` retryable=${attempt.retryableTransport}`,
+  ].join('');
   const head = `  attempt ${attempt.attempt ?? '?'}: ${attempt.completionReason ?? 'unknown'}`
     + (attempt.exitCode === undefined ? '' : ` exit=${attempt.exitCode}`)
+    + transport
     + (attempt.truncated ? ' (excerpt truncated)' : '');
   // An empty `stderrTail` is a journaled fact but not an account of anything,
   // so it never displaces useful stdout the way `detail ?? stderr ?? stdout`
@@ -264,7 +308,7 @@ function renderAttempt(attempt: StepAttemptFailure): string {
   const accounts: Array<[string, string]> = [
     ['detail', attempt.detail], ['stderr', attempt.stderrTail], ['stdout', attempt.stdoutTail],
   ].filter((pair): pair is [string, string] => typeof pair[1] === 'string' && pair[1].length > 0);
-  if (accounts.length === 0) return `${head} — no failure evidence recorded`;
+  if (accounts.length === 0) return transport === '' ? `${head} — no failure evidence recorded` : head;
   const [only] = accounts;
   if (accounts.length === 1 && !only![1].includes('\n')) return `${head} — ${only![0]}: ${only![1]}`;
   return [head, ...accounts.map(([label, value]) => indent(`${label}: ${value}`))].join('\n');

package/src/cli/step-failure.ts

@@ -60,6 +60,7 @@ export async function stepFailureDetails(
   // enforcing (relayflowd-core/src/entry.rs `AttemptStartedPayload`). They are
   // collected on the same walk and reported only when the journal held them.
   const budgets = new Map<string, number>();
+  const transportBudgets = new Map<string, number>();
   // 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>();
@@ -82,6 +83,10 @@ export async function stepFailureDetails(
         if (typeof maxIterations === 'number' && Number.isSafeInteger(maxIterations) && maxIterations > 0) {
           budgets.set(stepId, maxIterations);
         }
+        const transportRetries = record(entry['payload'])?.['max_transport_retries'];
+        if (typeof transportRetries === 'number' && Number.isSafeInteger(transportRetries) && transportRetries >= 0) {
+          transportBudgets.set(stepId, transportRetries);
+        }
         continue;
       }
       if (entry['entry_type'] !== 'step.completed') continue;
@@ -117,12 +122,14 @@ export async function stepFailureDetails(
       const stepType = snapshot.steps[stepId]?.type;
       const attempt = entry['attempt'];
       const maxIterations = budgets.get(stepId);
+      const transportRetries = transportBudgets.get(stepId);
       failures.set(stepId, {
         stepId,
         completionReason,
         ...(stepType === undefined ? {} : { stepType }),
         ...(typeof attempt === 'number' && Number.isSafeInteger(attempt) && attempt > 0 ? { attempt } : {}),
         ...(maxIterations === undefined ? {} : { maxIterations }),
+        ...(transportRetries === undefined ? {} : { transportRetries }),
         ...((uncharged.get(stepId) ?? 0) > 0 ? { unchargedAttempts: uncharged.get(stepId) } : {}),
         ...terminalEvidence(payload),
         // A single failed attempt is already fully described by the scalars
@@ -166,7 +173,13 @@ export function renderStepEvidence(details: StepFailedDetails): string {
     + (details.stepType === undefined ? '' : ` (${details.stepType})`)
     + ` completionReason: ${details.completionReason}`
     + renderAttempt(details)
+    + (details.transportRetries === undefined ? '' : ` transportRetries=${details.transportRetries}`)
     + (details.exitCode === undefined ? '' : ` exit=${details.exitCode}`)
+    + (details.signal === undefined ? '' : ` signal=${details.signal}`)
+    + (details.transportCause === undefined ? '' : ` transport=${details.transportCause}`)
+    + (details.transportPhase === undefined ? '' : ` phase=${details.transportPhase}`)
+    + (details.errorCode === undefined ? '' : ` error_code=${details.errorCode}`)
+    + (details.retryableTransport === undefined ? '' : ` retryable=${details.retryableTransport}`)
     + '.'
     + renderAttemptHistory(details)
     + (details.detail === undefined ? '' : `\nDetail: ${details.detail}`)

package/src/cli-transport-evidence.ts

@@ -0,0 +1,70 @@
+import { boundedTail, redactText } from './agent-transcript.js';
+
+export type CliTransportPhase = 'spawn' | 'close' | 'abort' | 'timeout' | 'result_exit_grace';
+export type CliTransportCause =
+  | 'exited'
+  | 'nonzero_exit'
+  | 'signal'
+  | 'close_without_status'
+  | 'spawn_error'
+  | 'process_error'
+  | 'lease_lost'
+  | 'timeout'
+  | 'result_exit_timeout'
+  | 'codex_stdin_lifecycle';
+
+export interface CliTransportEvidence {
+  phase: CliTransportPhase;
+  cause: CliTransportCause;
+  exit_code: number | null;
+  signal: NodeJS.Signals | null;
+  /** OS/libuv error code, never an unbounded error message. */
+  error_code?: string;
+  /** True only for a closed set of infrastructure failures. */
+  retryable: boolean;
+  /** Redacted UTF-8 tail with its truncation made explicit. */
+  stderr_tail: string;
+}
+
+/** Infrastructure classification is deliberately narrower than "nonzero". */
+export function agentCompletionReason(
+  result: { exit_code: number | null; transport?: CliTransportEvidence },
+): 'success' | 'crashed' | 'timeout' | 'worker_error' {
+  if (result.exit_code === 0) return 'success';
+  if (result.transport?.retryable === true) return 'crashed';
+  if (result.transport?.cause === 'timeout') return 'timeout';
+  return 'worker_error';
+}
+
+const TRANSPORT_STDERR_MAX_BYTES = 2 * 1024;
+const RETRYABLE_SPAWN_ERROR_CODES = new Set(['EAGAIN', 'EMFILE', 'ENFILE', 'ENOMEM', 'ETXTBSY']);
+
+export function isRetryableSpawnError(code: string | undefined): boolean {
+  return code !== undefined && RETRYABLE_SPAWN_ERROR_CODES.has(code);
+}
+
+export function transportEvidence(
+  value: {
+    phase: CliTransportPhase;
+    cause: CliTransportCause;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stderr: string;
+    errorCode?: string;
+    retryable: boolean;
+  },
+  env: NodeJS.ProcessEnv,
+): CliTransportEvidence {
+  const bounded = boundedTail(redactText(value.stderr, env), TRANSPORT_STDERR_MAX_BYTES, 'transport stderr: ');
+  const errorCode = value.errorCode !== undefined && /^[A-Z0-9_-]{1,64}$/.test(value.errorCode)
+    ? value.errorCode : undefined;
+  return {
+    phase: value.phase,
+    cause: value.cause,
+    exit_code: value.exitCode,
+    signal: value.signal,
+    ...(errorCode === undefined ? {} : { error_code: errorCode }),
+    retryable: value.retryable,
+    stderr_tail: bounded.text,
+  };
+}

package/src/compile.ts

@@ -38,7 +38,7 @@ import type {
 import { SPEC_SCHEMA_VERSION } from './spec.js';
 import { canonicalize, specHash } from './canonical.js';
 import { validateOutputDeclaration } from './output-schema.js';
-import { validateSpec, type ValidationResult } from './validate.js';
+import { isTransportRetries, 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';
@@ -74,7 +74,12 @@ export class CompileError extends Error {
  * survives float-precision (`1.1 * 1000 = 1100.0000000000002`) rather than
  * being rejected by `isSafeInteger`.
  */
-export function parseStepTimeout(timeout: unknown): number {
+export const AGENT_STEP_TIMEOUT_MAX_MS = 60 * 60_000;
+export function parseAgentStepTimeout(timeout: unknown): number {
+  return parseStepTimeout(timeout, true);
+}
+
+export function parseStepTimeout(timeout: unknown, agent = false): number {
   const unitToMs: Record<'ms' | 's' | 'm', number> = { ms: 1, s: 1000, m: 60_000 };
   let milliseconds: number;
   if (typeof timeout === 'number') {
@@ -96,10 +101,10 @@ export function parseStepTimeout(timeout: unknown): number {
     milliseconds = NaN;
   }
   if (!Number.isSafeInteger(milliseconds) || milliseconds <= 0) {
-    throw new CompileError(['f.run timeout must be a positive whole number of milliseconds or a duration such as "10s" or "5m".'], 'timeout_invalid');
+    throw new CompileError([`${agent ? 'f.agent' : 'f.run'} timeout must be a positive whole number of milliseconds or a duration such as "10s" or "5m".`], 'timeout_invalid');
   }
-  if (milliseconds > 15 * 60_000) {
-    throw new CompileError(['f.run timeout exceeds the maximum of 15 minutes declared in SURFACE.md.'], 'lease_exceeded');
+  if (milliseconds > (agent ? AGENT_STEP_TIMEOUT_MAX_MS : 15 * 60_000)) {
+    throw new CompileError([`${agent ? 'f.agent' : 'f.run'} timeout exceeds the maximum of ${agent ? 60 : 15} minutes declared in SURFACE.md.`], 'lease_exceeded');
   }
   return milliseconds;
 }
@@ -190,6 +195,8 @@ function compileStep(step: StepSpec): StepSpec {
       ? { dependsOn: step.input === undefined ? step.dependsOn : [...new Set([...(step.dependsOn ?? []), ...bindingDependencies(step.input)])] } : {}),
     ...(step.input !== undefined ? { input: step.input } : {}),
     maxIterations,
+    ...(step.transportRetries !== undefined && step.transportRetries !== DEFAULT_TRANSPORT_RETRIES
+      ? { transportRetries: step.transportRetries } : {}),
     ...(step.memory !== undefined ? { memory: step.memory } : {}),
     ...(step.requirements !== undefined ? { requirements: step.requirements } : {}),
   };
@@ -209,7 +216,7 @@ function compileStep(step: StepSpec): StepSpec {
         type: 'deterministic',
         command: s.command,
         verification: verification ?? { type: 'exit_code' as const },
-        // #138: `timeoutMs` is deterministic-only — worker-backed verbs own
+        // Timeout fields stay per-verb — worker-backed verbs own
         // their dispatch timeout. It must be spread HERE and nowhere in `base`.
         ...(s.timeoutMs !== undefined ? { timeoutMs: s.timeoutMs } : {}),
         ...(s.lease_ms !== undefined ? { lease_ms: parseStepTimeout(s.lease_ms) } : {}),
@@ -240,6 +247,7 @@ function compileStep(step: StepSpec): StepSpec {
         ...base,
         type: 'agent',
         instruction: s.instruction,
+        ...(s.timeoutMs === undefined ? {} : { timeoutMs: s.timeoutMs }),
         ...(verification !== undefined ? { verification: outputGate(verification, s.id) } : {}),
         ...(s.agent !== undefined ? { agent: s.agent } : {}),
         ...(s.cli !== undefined ? { cli: s.cli } : {}),
@@ -320,6 +328,10 @@ const KERNEL_RETRY_DEFAULTS = {
   jitter_percent: 20,
 } as const;
 
+// spec.rs `default_max_transport_retries`. The kernel serializes this value as
+// absent, so the SDK must too, or an explicit default changes the spec hash.
+const DEFAULT_TRANSPORT_RETRIES = 1;
+
 /**
  * Map an authoring `FlowSpec` to the kernel spec dialect — the single shape at
  * the SDK↔kernel boundary (`kernel/relayflowd-core/src/spec.rs`). Authoring
@@ -452,7 +464,7 @@ 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', 'cli_identity',
+    'cwd', 'recovery_mode', 'surfaces', 'permissions', 'transport', 'cli_identity',
   ] as const;
   const step = requireKernelObject(value, unionKeys, at);
   if (step['cli_identity'] !== undefined) {
@@ -467,10 +479,11 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
     : type === 'llm'
       ? ['prompt', 'model', 'cli', 'cli_identity'] as const
       : type === 'agent'
-        ? ['instruction', 'cli', 'model', 'cwd', 'recovery_mode', 'surfaces', 'permissions', 'cli_identity'] as const
+        ? ['timeout_ms', 'instruction', 'cli', 'model', 'recovery_mode', 'surfaces', 'permissions', 'cwd', 'transport', 'cli_identity'] as const
         : [];
   assertKernelKeys(step, [...commonKeys, ...typeKeys], at);
-  if (step['retry'] !== undefined) validateAuthoringRetryDefaults(step['retry'], `${at}.retry`);
+  const transportRetries = step['retry'] === undefined
+    ? undefined : validateAuthoringRetryDefaults(step['retry'], `${at}.retry`);
   const dependsOn = step['depends_on'];
   const common = {
     id: step['id'],
@@ -481,6 +494,7 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
       ? { dependsOn }
       : {}),
     ...(step['max_iterations'] !== undefined ? { maxIterations: step['max_iterations'] } : {}),
+    ...(transportRetries === undefined ? {} : { transportRetries }),
     ...kernelVerificationToAuthoring(type, step['verification'], `${at}.verification`),
     ...(step['memory'] !== undefined ? { memory: kernelMemoryToAuthoring(step['memory'], `${at}.memory`) } : {}),
   };
@@ -500,8 +514,9 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
     return {
       ...common,
       instruction: step['instruction'],
+      ...(step['timeout_ms'] === undefined ? {} : { timeoutMs: step['timeout_ms'] }),
       ...(step['recovery_mode'] !== undefined ? { recoveryMode: step['recovery_mode'] } : {}),
-      ...copyDefined(step, ['cli', 'model', 'cwd', 'surfaces']),
+      ...copyDefined(step, ['cli', 'model', 'surfaces', 'cwd', 'transport']),
       ...(step['permissions'] !== undefined
         ? { permissions: kernelPermissionsToAuthoring(step['permissions'], `${at}.permissions`) }
         : {}),
@@ -510,9 +525,9 @@ function kernelStepToAuthoring(value: unknown, at: string): unknown {
   return common;
 }
 
-function validateAuthoringRetryDefaults(value: unknown, at: string): void {
+function validateAuthoringRetryDefaults(value: unknown, at: string): number | undefined {
   const retry = requireKernelObject(value, [
-    'initial_backoff_ms', 'max_backoff_ms', 'multiplier', 'jitter_percent',
+    'initial_backoff_ms', 'max_backoff_ms', 'multiplier', 'jitter_percent', 'max_transport_retries',
   ], at);
   for (const [field, expected] of Object.entries(KERNEL_RETRY_DEFAULTS)) {
     if (retry[field] !== expected) {
@@ -521,6 +536,12 @@ function validateAuthoringRetryDefaults(value: unknown, at: string): void {
       ]);
     }
   }
+  const transportRetries = retry['max_transport_retries'];
+  if (transportRetries === undefined) return undefined;
+  if (!isTransportRetries(transportRetries)) {
+    throw new CompileError([`${at}.max_transport_retries must be a non-negative u32 integer`]);
+  }
+  return transportRetries === DEFAULT_TRANSPORT_RETRIES ? undefined : transportRetries;
 }
 
 function kernelVerificationToAuthoring(
@@ -617,7 +638,11 @@ function toKernelStep(step: StepSpec, cliIdentity?: string): ResolvedKernelStepS
       : [...new Set([...(step.dependsOn ?? []), ...bindingDependencies(step.input)])],
     ...(step.input !== undefined ? { input: step.input } : {}),
     max_iterations: step.maxIterations ?? 1,
-    retry: { ...KERNEL_RETRY_DEFAULTS },
+    retry: {
+      ...KERNEL_RETRY_DEFAULTS,
+      ...(step.transportRetries !== undefined && step.transportRetries !== DEFAULT_TRANSPORT_RETRIES
+        ? { max_transport_retries: step.transportRetries } : {}),
+    },
     verification: toKernelVerification(step),
     ...(cliIdentity !== undefined ? { cli_identity: cliIdentity } : {}),
     ...(step.requirements !== undefined ? { requirements: {
@@ -662,6 +687,7 @@ function toKernelStep(step: StepSpec, cliIdentity?: string): ResolvedKernelStepS
         ...common,
         type: 'agent',
         instruction: step.instruction,
+        ...(step.timeoutMs === undefined ? {} : { timeout_ms: step.timeoutMs }),
         ...(step.cli !== undefined ? { cli: step.cli } : {}),
         ...(step.model !== undefined ? { model: step.model } : {}),
         ...(step.cwd !== undefined ? { cwd: step.cwd } : {}),

package/src/failure-kinds.ts

@@ -207,6 +207,12 @@ export interface StepAttemptFailure {
   /** `retry`, `step_done` or `park`: what the kernel did next, not why it failed. */
   disposition?: string;
   exitCode?: number;
+  /** This attempt's own transport evidence; see `StepFailedDetails`. */
+  transportPhase?: string;
+  transportCause?: string;
+  signal?: string;
+  errorCode?: string;
+  retryableTransport?: boolean;
   /** Redacted, terminal-safe UTF-8 excerpt, at most 256 bytes. */
   stdoutTail?: string;
   /** Redacted, terminal-safe UTF-8 excerpt, at most 256 bytes. */
@@ -277,6 +283,8 @@ export interface StepFailedDetails {
    * `retries_exhausted`.
    */
   maxIterations?: number;
+  /** Additional classified infrastructure retries declared for the step. */
+  transportRetries?: number;
   /**
    * Attempts before this one that died without a result -- the kernel
    * journaled them `crashed` or `lease_expired` itself -- and so, by design,
@@ -286,6 +294,11 @@ export interface StepFailedDetails {
    */
   unchargedAttempts?: number;
   exitCode?: number;
+  transportPhase?: string;
+  transportCause?: string;
+  signal?: string;
+  errorCode?: string;
+  retryableTransport?: boolean;
   /**
    * Terminal-safe UTF-8 excerpt of the captured stdout, at most
    * `EXCERPT_BYTES` (cli/step-excerpt.ts). The field name is kept for

package/src/pty-sidechannel.ts

@@ -31,6 +31,8 @@ export async function openSidechannel(
   canDrive: () => boolean = () => true,
 ) {
   const peers = new Map<Socket, boolean>();
+  const drivePeers = new Set<Socket>();
+  const driveIdle: Array<() => void> = [];
   let closed = false;
   const server = createServer(socket => {
     if (peers.size >= 16) { socket.destroy(); return; }
@@ -39,7 +41,12 @@ export async function openSidechannel(
     let mode: string | undefined;
     socket.setTimeout(2_000, () => socket.destroy());
     socket.on('error', () => socket.destroy());
-    socket.on('close', () => peers.delete(socket));
+    socket.on('close', () => {
+      peers.delete(socket);
+      if (drivePeers.delete(socket) && drivePeers.size === 0) {
+        for (const listener of driveIdle.splice(0)) listener();
+      }
+    });
     socket.on('data', (bytes: Buffer) => {
       if (mode === undefined) {
         hello = Buffer.concat([hello, bytes]);
@@ -52,7 +59,10 @@ export async function openSidechannel(
         socket.setTimeout(0);
         peers.set(socket, true);
         // Passthrough is a passive raw-byte view in this initial slice.
-        if (mode === 'drive') context.onDrive();
+        if (mode === 'drive') {
+          drivePeers.add(socket);
+          context.onDrive();
+        }
         bytes = hello.subarray(end + 1);
         hello = Buffer.alloc(0);
       }
@@ -89,6 +99,32 @@ export async function openSidechannel(
         if (ready && !peer.write(bytes)) peer.destroy();
       }
     },
+    /**
+     * Wait for a drive peer before the CLI is spawned.
+     *
+     * A direct headless CLI must not be handed a pipe merely because a
+     * sidechannel exists: Codex treats any non-TTY stdin as an additional
+     * prompt source and waits for its lifecycle. The caller uses this bounded
+     * enrollment window to choose `pipe` only when a driver actually joined;
+     * view and passthrough peers never change the child's stdin contract.
+     */
+    async waitForDrive(timeoutMs: number): Promise<boolean> {
+      // Enrollment is a live state, not a sticky historical event. Hold the
+      // whole bounded window so a peer that greets and then disconnects before
+      // spawn cannot leave the child with piped stdin and nobody to close it.
+      if (timeoutMs > 0) await new Promise<void>(resolve => setTimeout(resolve, timeoutMs));
+      return drivePeers.size > 0;
+    },
+    /**
+     * Run `listener` once no drive peer is live: now, or when the last one
+     * disconnects. `waitForDrive` is a snapshot, and a peer can leave the
+     * moment after it is taken; the caller that chose `pipe` on it closes the
+     * child's stdin here, so the child never waits on a pipe nobody holds.
+     */
+    whenDriveIdle(listener: () => void): void {
+      if (drivePeers.size === 0) listener();
+      else driveIdle.push(listener);
+    },
     close() {
       if (closed) return;
       closed = true;

package/src/spec.ts

@@ -228,6 +228,8 @@ export interface BaseStepSpec {
   dependsOn?: string[];
   /** Semantic retry bound (kernel DESIGN.md §1.2 `max_iterations`). Default 1. */
   maxIterations?: number;
+  /** Additional attempts after classified infrastructure loss. Default 1. */
+  transportRetries?: number;
 }
 
 export interface OutputBinding {
@@ -288,6 +290,7 @@ export interface LlmStepSpec extends BaseStepSpec {
  */
 export interface AgentStepSpec extends BaseStepSpec {
   type: 'agent';
+  timeoutMs?: number;
   instruction: string;
   verification?: OutputVerificationSpec;
   /** Named authoring declaration selected from `FlowSpec.agents`. Compiled away. */
@@ -352,7 +355,7 @@ export interface YamlHelperParams {
 type OneKey<T> = { [K in keyof T]: Pick<T, K> & Partial<Record<Exclude<keyof T, K>, never>> }[keyof T];
 
 /** Helper sugar is removed before validation of the three kernel step types. */
-export type YamlHelperStepSpec = Pick<BaseStepSpec, 'id' | 'dependsOn' | 'maxIterations'> & {
+export type YamlHelperStepSpec = Pick<BaseStepSpec, 'id' | 'dependsOn' | 'maxIterations' | 'transportRetries'> & {
   verification?: OutputVerificationSpec;
   output?: JsonOutputSchema;
 } & OneKey<{ [P in keyof YamlHelperParams]: OneKey<YamlHelperParams[P]> }>;
@@ -453,6 +456,7 @@ export interface KernelRetryPolicy {
   max_backoff_ms: number;
   multiplier: number;
   jitter_percent: number;
+  max_transport_retries?: number;
 }
 
 /**
@@ -510,6 +514,7 @@ export interface KernelPermissionsSpec {
 
 export interface KernelAgentStep extends KernelStepCommon {
   type: 'agent';
+  timeout_ms?: number;
   instruction: string;
   cli?: string;
   model?: string;

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);
 }