@relayflows/sdk 2.0.22 → 2.0.23

package/src/preflight.ts

@@ -1,3 +1,4 @@
+import { communicationInstruction } from './communication/spec.js';
 import { loadPlugins, type LoadedPlugin } from './plugin-loader.js';
 import { PluginError } from './plugin-manifest.js';
 import type { FlowSpec, StepSpec, TriggerSpec, McpServerConfig } from './spec.js';
@@ -32,13 +33,24 @@ export interface CliResolution {
 
 export interface CliProbeResult {
   exists: boolean;
-  authenticated: boolean;
+  authenticated: boolean | 'unverified';
   /** False when a custom executable did not identify as a wrapper adapter. */
   supported?: boolean;
   /** Exact declared model passed the CLI's model-scoped readiness probe. */
   modelAvailable?: boolean;
   authCommand?: string;
   modelCommand?: string;
+  /** Exit code of the authentication probe, when it failed. */
+  authExitCode?: number | null;
+  /**
+   * Redacted output of a FAILED authentication probe.
+   *
+   * Present only on failure. Without it a `cli_unauthenticated` refusal can
+   * state that a probe exited non-zero and never what it said, which makes an
+   * intermittent probe failure impossible to tell apart from a genuinely
+   * unauthenticated CLI.
+   */
+  authFailureDetail?: string;
 }
 
 export type CliProbeFailureDetail =
@@ -70,7 +82,7 @@ export interface PreflightProbes {
    * model in scope, so readiness answers "can this CLI use THIS model" rather
    * than the weaker "is this CLI authenticated at all".
    */
-  cli(cli: string, source: CliResolutionSource, model?: string): CliProbeResult;
+  cli(cli: string, source: CliResolutionSource, model?: string, execution?: 'managed'): CliProbeResult;
   executor(trigger: TriggerSpec): boolean;
   command(binary: string): boolean;
 }
@@ -292,7 +304,8 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
       continue;
     }
     const resolution = resolutionByStep.get(step.id)!;
-    probeResolvedCli(resolution, options.probes, cliProbeResults, diagnostics);
+    probeResolvedCli(resolution, options.probes, cliProbeResults, diagnostics,
+      step.type === 'agent' && communicationInstruction(step.instruction) !== undefined);
   }
 
   for (const trigger of compiled.triggers ?? []) {
@@ -453,6 +466,7 @@ function probeResolvedCli(
   probes: PreflightProbes,
   cache: Map<string, CliProbeOutcome>,
   diagnostics: PreflightDiagnostic[],
+  managed = false,
 ): void {
   // Source is load-bearing: the same relative CLI string resolves from the
   // flow directory for step/named/flow declarations and the config directory for
@@ -460,11 +474,13 @@ function probeResolvedCli(
   // Model is part of the key: the same CLI probed with two different models
   // is two different questions, and caching on the CLI alone would let a
   // model that the CLI cannot resolve inherit an earlier model's pass.
-  const cacheKey = JSON.stringify([resolution.cli, resolution.source, resolution.model ?? null]);
+  const cacheKey = JSON.stringify([resolution.cli, resolution.source, resolution.model ?? null, managed]);
   let outcome = cache.get(cacheKey);
   if (outcome === undefined) {
     try {
-      outcome = { result: probes.cli(resolution.cli, resolution.source, resolution.model) };
+      outcome = { result: managed
+        ? probes.cli(resolution.cli, resolution.source, resolution.model, 'managed')
+        : probes.cli(resolution.cli, resolution.source, resolution.model) };
     } catch (error) {
       const detail = error instanceof CliProbeError ? error.detail : undefined;
       outcome = { failure: detail ?? null };
@@ -500,14 +516,27 @@ function probeResolvedCli(
       cli: resolution.cli,
       message: `Step "${resolution.stepId}" declares CLI "${resolution.cli}", but it is neither a supported raw Claude/Codex executable nor a conforming Relayflows wrapper; custom wrappers must identify with the relayflows-agent-cli-v1 contract.`,
     });
-  } else if (!result.authenticated) {
+  } else if (managed && result.authenticated === 'unverified') {
+    diagnostics.push({ severity: 'warning', kind: 'managed_cli_unverified', stepId: resolution.stepId,
+      message: `Step "${resolution.stepId}" uses Relay's interactive CLI transport. The executable exists, but authentication${resolution.model ? ' and access to model "' + resolution.model + '"' : ''} could not be verified before startup. The managed session must execute its task and report completion; startup or task failure fails the step.` });
+  } else if (result.authenticated !== true) {
     const command = result.authCommand ?? `${resolution.cli} auth status`;
+    // Say what the probe reported. A refusal that names only the command turns
+    // a transient provider rejection and a genuinely unauthenticated CLI into
+    // the same message, and the difference decides whether retrying is
+    // correct.
+    const exitCode = result.authExitCode === undefined || result.authExitCode === null
+      ? ''
+      : ` (exit ${result.authExitCode})`;
+    const detail = result.authFailureDetail !== undefined && result.authFailureDetail.length > 0
+      ? ` It reported: ${result.authFailureDetail}`
+      : ' It produced no output, so the reason is unavailable.';
     diagnostics.push({
       severity: 'refusal',
       kind: 'cli_unauthenticated',
       stepId: resolution.stepId,
       cli: resolution.cli,
-      message: `Step "${resolution.stepId}" declares CLI "${resolution.cli}", but "${command}" exited non-zero; authenticate it or repair that adapter's authentication probe.`,
+      message: `Step "${resolution.stepId}" declares CLI "${resolution.cli}", but "${command}" exited non-zero${exitCode}; authenticate it or repair that adapter's authentication probe.${detail}`,
     });
   } else if (resolution.model !== undefined && result.modelAvailable !== true) {
     diagnostics.push({

package/src/protocol.ts

@@ -55,6 +55,9 @@ export type Verb =
   | 'step.wait'
   | 'event.emit'
   | 'event.submit'
+  | 'channel.append'
+  | 'channel.receive'
+  | 'channel.ack'
   | 'stream.append'
   | 'stream.read'
   | 'journal.read';
@@ -160,6 +163,8 @@ export interface WorkerAttachParams {
   step_types: StepType[];
   /** Maximum concurrent assignments. Omitted means the conservative default 1. */
   capacity?: number;
+  /** Accept only agent steps declaring every named stream (must also be pinned). */
+  required_streams?: string[];
   /**
    * The surfaces this worker holds, as opaque revisions/offsets. Required when
    * `step_types` includes `agent` — an agent attempt's start pins come from
@@ -411,7 +416,17 @@ export interface JournalReadResult {
 }
 
 /** Typed map of verb -> { params, result }. Used by the client for type-safety. */
+export interface ChannelIdentity {
+  run_id: string; step_id: string; attempt: number; idempotency_key: string; channel: string;
+}
+export interface ChannelEntry {
+  seq: number;
+  payload: { channel: string; offset: number; message?: unknown; producer?: string; consumer?: string; message_id?: string; delivery_seq?: number };
+}
 export interface VerbContract {
+  'channel.append': { params: ChannelIdentity & { message_id: string; message: unknown }; result: ChannelEntry };
+  'channel.receive': { params: ChannelIdentity; result: ChannelEntry | null };
+  'channel.ack': { params: ChannelIdentity & { delivery_seq: number }; result: ChannelEntry };
   hello: { params: HelloParams; result: HelloResult };
   'run.start': { params: RunStartParams; result: RunStartResult };
   'run.resume': { params: RunResumeParams; result: RunResumeResult };

package/src/spec.ts

@@ -374,6 +374,8 @@ export interface TriggerSpec {
  * is this spec mapped to the kernel dialect (`toKernelSpec`).
  */
 export interface FlowSpec {
+  /** Opt-in live messaging between independent agent steps; compiled into journal channels. */
+  communication?: { links: Array<{ from: string; to: string }>; timeoutMs?: number };
   /** Spec schema semver (RFC §7). Compilers always emit latest. */
   version: string;
   name?: string;

package/src/worker-cli.ts

@@ -1,5 +1,5 @@
 import { realpathSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { 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';
@@ -23,7 +23,7 @@ import {
 import { wrapperEnvironment } from './wrapper-runtime.js';
 import { redactRelayError } from './redact.js';
 import { applyStepEnvironment } from './step-env.js';
-import { TAIL_CLOSE_TIMEOUT_MS, openTranscriptTail, transcriptTailPath, type TranscriptTailWriter } from './transcript-tail.js';
+import { TAIL_CLOSE_TIMEOUT_MS, openTranscriptTail, type TranscriptTailWriter } from './transcript-tail.js';
 import {
   runAgentRelayTask,
   AgentRelayTransportError,
@@ -110,28 +110,23 @@ export async function runAgentCli(
   // serialized around their snapshot-spawn-snapshot interval, so one agent's
   // writes are never attributed to a concurrent one in the same directory.
   //
-  // This process writes its own evidence during that interval — the attempt's
-  // transcript file and the two `flows status --tail` tails — and when the data
-  // dir sits under the cwd (a local `--data-dir` inside the project) they all
-  // land inside the scanned tree. None of them is agent-authored content, so
-  // every one is dropped from the diff by path. Missing any of them reports
-  // our own bookkeeping back to the kernel as the step's artifacts.
+  // Bookkeeping written during that interval is not agent-authored content,
+  // and when the data dir sits under the cwd (a local `--data-dir` inside the
+  // project) all of it lands inside the scanned tree: this process's own
+  // transcript file and two `flows status --tail` tails, and the run journals
+  // the daemon appends to while the agent runs. So the whole data dir is
+  // dropped from the diff. Anything left in reports the kernel's own state
+  // back to the kernel as the step's artifacts, where an `artifact_exists`
+  // gate then reads it.
   const artifactRoot = mode === 'agent' ? resolve(cwd ?? process.cwd()) : undefined;
   return artifactRoot === undefined
     ? execute()
     : serializedByDirectory(artifactRoot, async () => {
       const before = await snapshotWorkspaceFiles(artifactRoot);
       const result = await execute();
-      const ours = new Set<string>();
-      for (const path of ownEvidencePaths(sidechannel)) {
-        const real = realPath(path);
-        if (real !== undefined) ours.add(real);
-      }
+      const kernelData = sidechannel === undefined ? undefined : realPath(resolve(sidechannel.dataDir));
       const artifacts = diffWorkspaceFiles(before, await snapshotWorkspaceFiles(artifactRoot))
-        .filter(path => {
-          const real = realPath(resolve(artifactRoot, path));
-          return real === undefined || !ours.has(real);
-        });
+        .filter(path => !under(realPath(resolve(artifactRoot, path)), kernelData));
       return { ...result, artifacts };
     });
 
@@ -198,39 +193,25 @@ function openTails(context: SidechannelContext): { stdout: TranscriptTailWriter;
 }
 
 /**
- * Every path this process may write under the workspace during an attempt, so
- * the artifact diff can drop all of them.
+ * Whether `path` is `directory` or anything beneath it, both symlink-free.
  *
- * Derived from the attempt identity — the same input `openTranscriptWriter` and
- * `openTails` use to decide where to write — and never from the result. The
- * transcript pointer on the result is optional: `finish` drops it when the
- * close outruns `TAIL_CLOSE_TIMEOUT_MS` and `discardTranscript` drops it on
- * abort, and on both paths the file is already on disk. An exclusion built from
- * that pointer therefore lost the transcript exactly when the close was slow,
- * which is the moment the file is most likely to still be there.
+ * The artifact exclusion is a subtree, not a list of names, because the files
+ * to exclude are not all knowable in advance. The attempt's own transcript and
+ * tails are (they derive from the attempt identity), but the daemon decides on
+ * its own when to write which run journal, and a journal appended to inside
+ * the snapshot interval is indistinguishable in a diff from a file the agent
+ * wrote. Excluding the directory covers both, and covers them without reading
+ * the result: the transcript pointer there is optional — `finish` drops it
+ * when the close outruns `TAIL_CLOSE_TIMEOUT_MS` and `discardTranscript` drops
+ * it on abort, while the file stays on disk — so an exclusion built from it
+ * lost the transcript exactly when the close was slow (flows#495).
  *
- * Empty when there is no sidechannel or no attempt to name, which is exactly
- * when nothing is written.
+ * `false` when there is no data dir to exclude, which is exactly when this
+ * process has nowhere to write.
  */
-function ownEvidencePaths(context: SidechannelContext | undefined): string[] {
-  const attempt = context?.attempt;
-  if (context === undefined || attempt === undefined) return [];
-  const identity = { dataDir: context.dataDir, runId: context.runId, stepId: context.stepId, attempt };
-  try {
-    // For each tail, both the finished file and the `.tmp` the writer stages
-    // and renames over (`transcript-tail.ts`): a close that timed out or a
-    // flush that failed can leave the staging file behind, and it is no more
-    // agent-authored than the file it was going to become.
-    const paths = [transcriptPath(identity, attempt)];
-    for (const stream of ['stdout', 'stderr'] as const) {
-      const tail = transcriptTailPath(identity, stream);
-      paths.push(tail, `${tail}.tmp`);
-    }
-    return paths;
-  } catch {
-    // An id the path cannot carry; nothing was written under it either.
-    return [];
-  }
+function under(path: string | undefined, directory: string | undefined): boolean {
+  if (path === undefined || directory === undefined) return false;
+  return path === directory || path.startsWith(directory.endsWith(sep) ? directory : directory + sep);
 }
 
 /** Symlink-free form of a path, or the path itself when it cannot be resolved. */

package/src/worker.ts

@@ -1,3 +1,4 @@
+import { communicationInstruction } from './communication/spec.js';
 import { workerSpend } from './worker-spend.js';
 import type { WorkerCliResult } from './worker-cli.js';
 import { EventEmitter } from 'node:events';
@@ -18,6 +19,7 @@ export interface AgentWorkerOptions {
   workerId: string;
   pins: Pins;
   capacity?: number;
+  requiredStreams?: string[];
   dataDir?: string;
   onPtyReady?: (path: string) => void;
 }
@@ -60,6 +62,7 @@ export class AgentWorker extends EventEmitter {
         ['agent'],
         this.options.pins,
         this.options.capacity,
+        this.options.requiredStreams,
       );
       this.attached = true;
     } catch (error) {
@@ -106,6 +109,13 @@ export class AgentWorker extends EventEmitter {
       await completeHelperDispatch(this.client, dispatch, helper, this.options.dataDir);
       return;
     }
+    const communication = communicationInstruction(spec.instruction);
+    if (communication) {
+      if (!this.options.dataDir) throw new Error('Agent communication requires a worker data directory');
+      const { completeCommunicationDispatch } = await import('./communication/worker.js');
+      await completeCommunicationDispatch(this.client, dispatch, communication, this.options.dataDir);
+      return;
+    }
     let humanIntervention = false;
     const effectiveModel = typeof spec.cli === 'string' ? resolveCliModel(spec.cli, spec.model) : spec.model;
     const completed: WorkerCliResult = await withWorkerLease(this.client, dispatch, signal =>

package/src/wrapper-session.ts

@@ -13,6 +13,14 @@ import {
 
 export interface WrapperSessionLimits {
   handshakeTimeoutMs: number;
+  /**
+   * How long the wrapper may work after acknowledging the request, or `0` for
+   * no deadline at all — the same convention `CliInvocation.timeoutMs` already
+   * uses for a native CLI spawn, where `worker-cli.ts` arms its timer only
+   * `if (invocation.timeoutMs > 0)`. `0` is the default, so a wrapper-backed
+   * step is bounded by the lease abort exactly as a `claude` or `codex` step
+   * is, and not by a constant neither of those pays.
+   */
   executionTimeoutMs: number;
   maxOutputBytes: number;
 }
@@ -25,7 +33,7 @@ export interface WrapperSessionResult {
 
 const DEFAULT_LIMITS: WrapperSessionLimits = {
   handshakeTimeoutMs: 10_000,
-  executionTimeoutMs: 300_000,
+  executionTimeoutMs: 0,
   maxOutputBytes: 1_048_576,
 };
 const HANDSHAKE_OUTPUT_LIMIT = 8_192;
@@ -36,6 +44,19 @@ const HANDSHAKE_OUTPUT_LIMIT = 8_192;
  * not depend on `'close'`: past this point the reader settles regardless.
  */
 const SETTLE_AFTER_KILL_MS = 250;
+/**
+ * How long a session with NO execution deadline waits, after the wrapper
+ * process itself is gone, for its stdio to finish draining.
+ *
+ * The execution deadline used to be what settled a wrapper that exited while a
+ * descendant still held an inherited pipe, because `'close'` waits on every
+ * one of them. That job is real; keying it on elapsed time was not. It is
+ * keyed on the wrapper's own exit instead, which is the fact that actually
+ * matters. Reaching the end of this grace is not proof that a pipe was leaked
+ * — buffered output may simply still be in flight — so the grace is a policy
+ * and the stop that follows it is bounded, not a diagnosis.
+ */
+const DRAIN_AFTER_EXIT_MS = 250;
 
 /**
  * Identify and execute a custom wrapper in one pinned process. No private
@@ -108,14 +129,29 @@ function executePinnedWrapper(
     let phase: 'identity' | 'ack' | 'execute' = 'identity';
     let protocolError: string | undefined;
     let settled = false;
+    let outputFinalized = false;
+    let childExited = false;
+    let exitCode: number | null = null;
+    /** The handshake deadline, then the execution deadline if there is one. */
     let lifecycleTimer: NodeJS.Timeout | undefined;
+    /** `terminate`'s own settle deadline. */
     let settleTimer: NodeJS.Timeout | undefined;
+    /** The post-exit drain grace, armed only when execution is unlimited. */
+    let drainTimer: NodeJS.Timeout | undefined;
+    /** The settle deadline the drain's own stop owes, after its escalation. */
+    let drainSettleTimer: NodeJS.Timeout | undefined;
+    // Each deadline owns its own handle. They can be armed at the same time —
+    // a drain grace can be running when an over-limit final line terminates
+    // the session — and a shared variable would drop the only reference to
+    // one of them and leave it pending past the settle.
 
     const finish = (result: WrapperSessionResult): void => {
       if (settled) return;
       settled = true;
       if (lifecycleTimer !== undefined) clearTimeout(lifecycleTimer);
       if (settleTimer !== undefined) clearTimeout(settleTimer);
+      if (drainTimer !== undefined) clearTimeout(drainTimer);
+      if (drainSettleTimer !== undefined) clearTimeout(drainSettleTimer);
       signal?.removeEventListener('abort', onAbort);
       resolve(result);
     };
@@ -152,6 +188,12 @@ function executePinnedWrapper(
       if (protocolError !== undefined) return;
       protocolError = message;
       if (lifecycleTimer !== undefined) clearTimeout(lifecycleTimer);
+      lifecycleTimer = undefined;
+      // A refusal wins over a drain that was going to report the wrapper's own
+      // exit as a success: from here this settle belongs to the deadline armed
+      // below, and a drain that still fired would stop the tree a second time.
+      if (drainTimer !== undefined) clearTimeout(drainTimer);
+      drainTimer = undefined;
       // Same reach as an abort, only gentler first: this stop must find the
       // whole group, or a descendant outlives the session still holding the
       // stdio it inherited.
@@ -171,6 +213,13 @@ function executePinnedWrapper(
     };
     const startExecutionTimer = (): void => {
       if (lifecycleTimer !== undefined) clearTimeout(lifecycleTimer);
+      lifecycleTimer = undefined;
+      // `0` is no deadline, exactly as `worker-cli.ts` reads
+      // `invocation.timeoutMs` for a native CLI. The handshake deadline it
+      // just replaced was a liveness check and is over; nothing else is armed,
+      // 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(
         `CLI ${JSON.stringify(cli)} execution timed out after ${limits.executionTimeoutMs}ms.`,
       ), limits.executionTimeoutMs);
@@ -210,6 +259,12 @@ function executePinnedWrapper(
         }
         phase = 'execute';
         startExecutionTimer();
+        // The wrapper may already be gone: `'exit'` is delivered as soon as the
+        // process dies, while the bytes it wrote are still being read out of
+        // the pipe. The exit is remembered rather than acted on, and the drain
+        // grace starts here, once the acknowledgement it waits behind has
+        // actually been consumed.
+        startDrainGrace();
       }
     };
     const acceptExecutionData = (chunk: string): void => {
@@ -228,6 +283,83 @@ function executePinnedWrapper(
       }
     };
     const handshakeComplete = (): boolean => phase === 'execute';
+    /**
+     * Fold the last un-terminated line into the captured output, exactly once.
+     *
+     * Two settles can now reach this — `'close'` and the drain grace — and the
+     * pending buffer may only be spent by one of them. A second finalization
+     * that appended it again would duplicate the wrapper's own result, and a
+     * buffer left in place would go on being counted against `maxOutputBytes`
+     * by any later chunk.
+     */
+    const finalizeOutput = (): void => {
+      if (outputFinalized) return;
+      outputFinalized = true;
+      if (protocolError === undefined && phase === 'execute' && executionPending.length > 0) {
+        if (normalizeLine(executionPending) === WRAPPER_EXECUTE_TOKEN) {
+          protocolError = `CLI ${JSON.stringify(cli)} emitted a duplicate execute protocol frame.`;
+        } else if (!exceedsOutputLimit(0)) {
+          appendStdout(executionPending);
+        }
+      }
+      executionPending = '';
+    };
+    /**
+     * The one result builder. A recorded protocol or output failure outranks
+     * the exit status: a wrapper that violated the contract is refused even
+     * when the process it ran in went on to exit 0.
+     */
+    const executionResult = (code: number | null): WrapperSessionResult => {
+      finalizeOutput();
+      if (protocolError !== undefined || phase !== 'execute') {
+        return failure(
+          protocolError
+            ?? `CLI ${JSON.stringify(cli)} exited before completing the ${WRAPPER_IDENTIFY_TOKEN} same-process handshake.`,
+        );
+      }
+      return {
+        exit_code: code,
+        stdout_tail: stdout.join(''),
+        stderr_tail: Buffer.concat(stderr).toString('utf8'),
+      };
+    };
+    const drainExpired = (): void => {
+      drainTimer = undefined;
+      if (settled) return;
+      const result = executionResult(exitCode);
+      // Finalizing can itself refuse the session — an over-limit final line —
+      // and `terminate` has then already stopped the tree and armed its own
+      // settle deadline. Stopping or arming a second time here would leave two
+      // deadlines racing for one settle.
+      if (settleTimer !== undefined) return;
+      // The wrapper is gone and `'close'` has still not arrived, so something
+      // it left behind is holding stdio it inherited. Stop what is reachable —
+      // a settle that releases no pipes lets the step complete while
+      // `flows run` never exits — and then own the settle regardless: the
+      // force kill has no callback, and a descendant that escaped into its own
+      // group before the wrapper died is not traceable to this spawn at all.
+      stop.terminate();
+      drainSettleTimer = setTimeout(
+        () => finish(executionResult(exitCode)),
+        FORCE_KILL_DELAY_MS + SETTLE_AFTER_KILL_MS,
+      );
+      // Settle now if the stop turned out to have nothing to reach; otherwise
+      // the deadline above owns it, and a `'close'` that arrives once the
+      // group is empty may still settle earlier.
+      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.
+     */
+    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);
+    };
 
     lifecycleTimer = setTimeout(() => terminate(
       `CLI ${JSON.stringify(cli)} did not identify as ${WRAPPER_IDENTIFY_TOKEN} within ${limits.handshakeTimeoutMs}ms.`,
@@ -235,7 +367,11 @@ function executePinnedWrapper(
 
     child.stdout.setEncoding('utf8');
     child.stdout.on('data', (chunk: string) => {
-      if (protocolError !== undefined) return;
+      // Once the output has been finalized the result is built and the
+      // captured bytes are spent. A late chunk — the drain grace has expired
+      // and a descendant still owns the pipe — may neither be appended to a
+      // result already reported nor re-judged against a limit already applied.
+      if (protocolError !== undefined || outputFinalized) return;
       if (phase === 'execute') {
         acceptExecutionData(chunk);
         return;
@@ -273,7 +409,7 @@ function executePinnedWrapper(
       }
     });
     child.stderr.on('data', (chunk: Buffer) => {
-      if (protocolError !== undefined || exceedsOutputLimit(chunk.byteLength)) return;
+      if (protocolError !== undefined || outputFinalized || exceedsOutputLimit(chunk.byteLength)) return;
       capturedBytes += chunk.byteLength;
       stderr.push(chunk);
     });
@@ -281,42 +417,41 @@ function executePinnedWrapper(
       // A child that closes stdin before acknowledgement is classified on close.
     });
     child.once('error', (error) => finishOnChildExit(failure(error.message)));
-    child.once('close', (code) => {
-      if (protocolError === undefined && phase === 'execute' && executionPending.length > 0) {
-        if (normalizeLine(executionPending) === WRAPPER_EXECUTE_TOKEN) {
-          protocolError = `CLI ${JSON.stringify(cli)} emitted a duplicate execute protocol frame.`;
-        } else if (!exceedsOutputLimit(0)) {
-          appendStdout(executionPending);
-        }
-      }
-      if (protocolError !== undefined || phase !== 'execute') {
-        finishOnChildExit(failure(
-          protocolError
-            ?? `CLI ${JSON.stringify(cli)} exited before completing the ${WRAPPER_IDENTIFY_TOKEN} same-process handshake.`,
-        ));
-        return;
-      }
-      finishOnChildExit({
-        exit_code: code,
-        stdout_tail: stdout.join(''),
-        stderr_tail: Buffer.concat(stderr).toString('utf8'),
-      });
+    // `'exit'` is evidence about the DIRECT CHILD only: the wrapper process is
+    // gone, whether or not anything it spawned still holds the stdio it
+    // inherited. That is exactly the fact the drain grace waits on, and it is
+    // not evidence of a dead group — nothing here settles or stops.
+    child.once('exit', (code) => {
+      childExited = true;
+      exitCode = code;
+      startDrainGrace();
     });
+    child.once('close', (code) => finishOnChildExit(executionResult(code)));
   });
 }
 
 function sessionLimits(overrides: Partial<WrapperSessionLimits>): WrapperSessionLimits {
   return {
     handshakeTimeoutMs: positiveLimit(overrides.handshakeTimeoutMs, DEFAULT_LIMITS.handshakeTimeoutMs),
-    executionTimeoutMs: positiveLimit(overrides.executionTimeoutMs, DEFAULT_LIMITS.executionTimeoutMs),
+    executionTimeoutMs: durationLimit(overrides.executionTimeoutMs, DEFAULT_LIMITS.executionTimeoutMs),
     maxOutputBytes: positiveLimit(overrides.maxOutputBytes, DEFAULT_LIMITS.maxOutputBytes),
   };
 }
 
+/** A bound a wrapper may not switch off: `0` and below fall back. */
 function positiveLimit(value: number | undefined, fallback: number): number {
   return value !== undefined && Number.isSafeInteger(value) && value > 0 ? value : fallback;
 }
 
+/**
+ * A duration that may be switched off, so `0` is a value and not a missing
+ * one. Reusing {@link positiveLimit} here would coerce an explicit "no
+ * deadline" back to the fallback, which is how the default became unreachable.
+ */
+function durationLimit(value: number | undefined, fallback: number): number {
+  return value !== undefined && Number.isSafeInteger(value) && value >= 0 ? value : fallback;
+}
+
 function normalizeLine(line: string): string {
   return line.endsWith('\r') ? line.slice(0, -1) : line;
 }