@relayflows/sdk 2.0.39 → 2.0.41

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-commands.ts

@@ -156,7 +156,7 @@ export const CLI_VERBS = [
     args: [{ name: 'flow', description: 'flow.ts for a hosted listener, or <flow>@sha256:<digest> for a bundle', required: true }],
     options: [
       { flags: '--to <file-bucket-uri>', description: 'Destination file bucket for a sealed bundle' },
-      { flags: '--repo <owner/name>', description: 'Repository the hosted listener watches' },
+      { flags: '--repo <owner/name|gitlab:group/project>', description: 'Target repository: owner/name or github:owner/name for GitHub; gitlab:group/project (subgroups allowed) or a github.com/gitlab.com HTTP(S) URL' },
       { flags: '--on <provider>', description: 'Trigger source, as <provider>[:key=value,...]; repeatable' },
       { flags: '--approver <handle>', description: 'Handle delivered to every launched run as input.approver' },
       { flags: '--agents <list>', description: 'Agent harnesses to allow, as claude[,codex]' },

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/cli.ts

@@ -125,7 +125,7 @@ const USAGE = [
   'flows plugin update [--json] [--yes] [--to <ref>] [<name>]',
   'flows build [--out <dir>] <flow.yaml|flow.ts>',
   'flows build --verify <bundle-dir>',
-  'flows deploy <flow.ts> --repo <owner/name> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--plugin <ref>] [--no-connect] [--json]',
+  'flows deploy <flow.ts> --repo <owner/name|gitlab:group/project> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--plugin <ref>] [--no-connect] [--json]',
   'flows deploy <flow.ts> --flow <name|listener-id> [--plugin <ref>] [--no-connect] [--json]',
   'flows deployments [--json]',
   'flows versions [--json] <name|listener-id>',

package/src/cloud-deploy.ts

@@ -18,10 +18,11 @@ import { parseVersionChange, type CloudFlowVersionChange } from './cloud-version
  * deploy wizard. `POST /api/v1/flows/deploy` stores one self-contained
  * authored source and creates a proactive listener whose watch rules match
  * the chosen ticket sources on the workspace's relayfile projections. There
- * is no webhook to register: the GitHub App installation (or Slack/Linear/
- * Jira/Shortcut connection) is the ingress, and each matching ticket launches
- * a run of the stored source with `{ approver, issue, event }` as its input,
- * inside a fresh branch of the deployment's repository.
+ * is no webhook to register: the GitHub App installation (or the GitLab,
+ * Slack, Linear, Jira or Shortcut connection) is the ingress, and each
+ * matching ticket launches a run of the stored source with
+ * `{ approver, issue, event }` as its input, inside a fresh branch of the
+ * deployment's repository.
  */
 
 export const FLOW_TRIGGER_PROVIDERS = ['github', 'gitlab', 'linear', 'jira', 'shortcut', 'slack'] as const;
@@ -45,6 +46,25 @@ const MAX_SOURCE_BYTES = 256_000;
 const MAX_SETTING_LENGTH = 500;
 const REPO_OWNER = /^[A-Za-z0-9-]{1,39}$/u;
 const REPO_NAME = /^[A-Za-z0-9_.-]{1,100}$/u;
+// GitLab coordinates mirror Cloud's isValidFlowRepositoryCoordinates
+// (AgentWorkforce/cloud packages/web/lib/flows/flow-repository.ts): the owner
+// is the namespace path, at most 255 characters and 20 segments (the root
+// group counts; the project name does not), and every owner segment and the
+// project name match GITLAB_SEGMENT without a trailing ., .git or .atom.
+const GITLAB_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/u;
+const GITLAB_OWNER_SEGMENTS = 20;
+const GITLAB_OWNER_LENGTH = 255;
+
+function validGitlabSegment(segment: string): boolean {
+  return GITLAB_SEGMENT.test(segment)
+    && !segment.endsWith('.') && !segment.endsWith('.git') && !segment.endsWith('.atom');
+}
+
+export interface DeployRepository {
+  owner: string;
+  name: string;
+  host?: 'gitlab';
+}
 
 export interface FlowTriggerSource {
   provider: FlowTriggerProvider;
@@ -53,7 +73,7 @@ export interface FlowTriggerSource {
 
 export interface DeployToCloudInput {
   path: string;
-  repository: { owner: string; name: string };
+  repository: DeployRepository;
   sources: FlowTriggerSource[];
   /** The `f.human` approver handle every launched run receives as `input.approver`. */
   approver: string;
@@ -98,7 +118,7 @@ export interface CloudDeployment {
   agentId: string;
   name: string;
   status: string;
-  repository: { owner: string; name: string };
+  repository: DeployRepository;
   sources: FlowTriggerSource[];
   sourceSha256: string;
   /** What the source declared it needs; the harnesses became `inputs.agents` unless `agents` was given. */
@@ -109,12 +129,24 @@ export interface CloudDeployment {
   version?: CloudFlowVersionChange;
 }
 
-export function parseRepository(value: string): { owner: string; name: string } {
-  const [owner, name, extra] = value.replace(/^https?:\/\/github\.com\//iu, '').replace(/\.git$/iu, '').split('/');
-  if (!owner || !name || extra !== undefined || !REPO_OWNER.test(owner) || !REPO_NAME.test(name)) {
-    throw new CloudFlowError('invalid_input', `Expected --repo <owner>/<name>, got "${value}".`);
+export function parseRepository(value: string): DeployRepository {
+  const prefix = /^(github|gitlab):/iu.exec(value);
+  const path = prefix ? value.slice(prefix[0].length) : value;
+  const url = /^https?:\/\/(github|gitlab)\.com\//iu.exec(path);
+  const host = (prefix?.[1] ?? url?.[1] ?? 'github').toLowerCase();
+  const parts = (url ? path.slice(url[0].length) : path).replace(/\.git$/iu, '').split('/');
+  const name = parts.at(-1)!;
+  const owner = parts.slice(0, -1).join('/');
+  const valid = host === 'gitlab'
+    ? parts.length >= 2 && parts.length - 1 <= GITLAB_OWNER_SEGMENTS
+      && owner.length <= GITLAB_OWNER_LENGTH && parts.every(validGitlabSegment)
+    : parts.length === 2 && REPO_OWNER.test(owner) && REPO_NAME.test(name);
+  if (!valid || (url && url[1]!.toLowerCase() !== host)) {
+    throw new CloudFlowError('invalid_input',
+      `Expected --repo <owner/name> (GitHub) or gitlab:<group/project> (up to ${GITLAB_OWNER_SEGMENTS} namespace segments), `
+      + `or a github.com/gitlab.com HTTP(S) project URL, got "${value}".`);
   }
-  return { owner, name };
+  return { owner, name, ...(host === 'gitlab' ? { host: 'gitlab' as const } : {}) };
 }
 
 /** `github`, `github:labels=agent,contains=urgent`, `slack:channel=#eng`. */
@@ -233,11 +265,21 @@ export async function deployToCloud(
   if (!approver) throw new CloudFlowError('invalid_input', '--approver must name who approves f.human questions.');
   const name = (input.name ?? definition.name).trim();
   if (!name || name.length > 100) throw new CloudFlowError('invalid_input', 'Deployment name must be 1-100 characters.');
-  // A GitHub source scoped to nothing would wake on every repository the
-  // installation covers; default it to the deployment's own repository.
-  const sources = input.sources.map(s => s.provider === 'github' && s.settings['repository'] === undefined
-    ? { ...s, settings: { ...s.settings, repository: `${input.repository.owner}/${input.repository.name}` } }
-    : s);
+  // Scope same-host sources to the target rather than waking on every project.
+  const target = `${input.repository.owner}/${input.repository.name}`;
+  const sources = input.sources.map(s => {
+    if (s.provider === 'github' && s.settings['repository'] === undefined) {
+      if (input.repository.host === 'gitlab') {
+        throw new CloudFlowError('invalid_input',
+          'A GitLab target needs an explicit --on github:repository=owner/name for a GitHub source.');
+      }
+      return { ...s, settings: { ...s.settings, repository: target } };
+    }
+    if (s.provider === 'gitlab' && s.settings['project'] === undefined && input.repository.host === 'gitlab') {
+      return { ...s, settings: { ...s.settings, project: target } };
+    }
+    return s;
+  });
   options.signal?.throwIfAborted();
 
   const whoami = await cloudRequest('/api/v1/auth/whoami', options);
@@ -245,8 +287,7 @@ export async function deployToCloud(
   if (workspace === undefined || typeof workspace.id !== 'string' || !workspace.id) {
     throw new CloudFlowError('invalid_response', 'Cloud did not report a current workspace for this credential.');
   }
-  // Every launched run lands in the deployment's repository, so GitHub is
-  // required even when no GitHub source wakes it.
+  // Every launched run needs the target's host, even when another provider wakes it.
   const requirements = mergeFlowExtensionRequirements(
     flowRequirements(definition, {
       sources, repository: input.repository, ...(projectCli === undefined ? {} : { projectCli }),
@@ -307,7 +348,7 @@ export interface CloudDeploymentSummary {
   agentId: string;
   name: string;
   status: string;
-  repository?: { owner: string; name: string };
+  repository?: DeployRepository;
   sources: FlowTriggerSource[];
   createdAt?: string;
   updatedAt?: string;
@@ -323,7 +364,8 @@ export async function listCloudDeployments(options: CloudConnectionOptions = {})
       throw new CloudFlowError('invalid_response', 'Cloud returned a malformed deployment row.');
     }
     const repository = isCloudRecord(row.repository) && typeof row.repository.owner === 'string'
-      && typeof row.repository.name === 'string' ? { owner: row.repository.owner, name: row.repository.name } : undefined;
+      && typeof row.repository.name === 'string' ? { owner: row.repository.owner, name: row.repository.name,
+          ...(row.repository.host === 'gitlab' ? { host: 'gitlab' as const } : {}) } : undefined;
     const sources = Array.isArray(row.sources) ? row.sources.flatMap((s): FlowTriggerSource[] =>
       isCloudRecord(s) && typeof s.provider === 'string' && (FLOW_TRIGGER_PROVIDERS as readonly string[]).includes(s.provider)
         ? [{ provider: s.provider as FlowTriggerProvider,

package/src/cloud-versions.ts

@@ -4,7 +4,7 @@ import {
   CloudFlowError, cloudFetch, cloudRequest, isCloudRecord, type CloudConnectionOptions,
 } from './cloud-http.js';
 import {
-  FLOW_AGENT_HARNESSES, listCloudDeployments, loadDeploySource, type FlowTriggerSource,
+  FLOW_AGENT_HARNESSES, listCloudDeployments, loadDeploySource, type DeployRepository, type FlowTriggerSource,
 } from './cloud-deploy.js';
 import {
   parseVersion, parseVersionChange, type CloudFlowVersion, type CloudFlowVersionChange,
@@ -25,7 +25,7 @@ export interface CloudListener {
   agentId: string;
   name: string;
   status: string;
-  repository: { owner: string; name: string; host?: 'gitlab' };
+  repository: DeployRepository;
   sources: FlowTriggerSource[];
   activeVersion: CloudFlowVersion | null;
   versions: CloudFlowVersion[];

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/flow-requirements.ts

@@ -51,8 +51,8 @@ export interface FlowRequirements {
 export interface FlowRequirementsContext {
   /** Trigger sources the deployment listens on (`--on`, or the wizard's chosen sources). */
   sources?: readonly { provider: string }[];
-  /** Set when the deployment targets a repository: every launched run needs GitHub. */
-  repository?: boolean | { owner: string; name: string };
+  /** Set when the deployment targets a repository: every launched run needs its host (true means GitHub). */
+  repository?: boolean | { owner: string; name: string; host?: 'gitlab' };
   /** The nearest `flows.json` `cli`, when one applies. */
   projectCli?: string;
 }
@@ -180,7 +180,10 @@ export function flowRequirements(
   for (const source of context.sources ?? []) {
     declare({ provider: source.provider, from: 'source', detail: `--on ${source.provider}` });
   }
-  if (context.repository) declare({ provider: 'github', from: 'source', detail: 'deploy target' });
+  if (context.repository) {
+    const provider = typeof context.repository === 'object' && context.repository.host === 'gitlab' ? 'gitlab' : 'github';
+    declare({ provider, from: 'source', detail: 'deploy target' });
+  }
 
   const uses = [...harnessUses.values()];
   return {

package/src/index.ts

@@ -107,7 +107,7 @@ export {
 export { prepareCloudSubmission, cloudSubmissionBody, type CloudSubmission } from './cloud-run.js';
 export {
   deployToCloud, listCloudDeployments, undeployFromCloud, parseRepository, parseTriggerSource, FLOW_TRIGGER_PROVIDERS,
-  type DeployToCloudInput, type CloudDeployment, type CloudDeploymentSummary, type FlowTriggerSource, type FlowTriggerProvider,
+  type DeployRepository, type DeployToCloudInput, type CloudDeployment, type CloudDeploymentSummary, type FlowTriggerSource, type FlowTriggerProvider,
 } from './cloud-deploy.js';
 export {
   ensureIntegrationsConnected, integrationConnected, providerLabel,

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;