@relayflows/sdk 2.0.20 → 2.0.22

package/src/spec.ts

@@ -125,7 +125,22 @@ export interface AgentSurfaces {
   external?: string[];
 }
 
-/** Permission model for an agent step (gate 8). `readonly` provably cannot write. */
+/**
+ * Per-step permission declarations for an agent step.
+ *
+ * Validated by gate 1 and recorded in the compiled step spec (as `file_globs`,
+ * `network_allowlist` and `access_preset`), but **not currently enforced**:
+ * nothing reads these fields to gate a file or network access. Enforcement is
+ * gate 8 (#442). `accessPreset: 'readonly'` does not prevent writes today.
+ *
+ * `flows check` emits a `permissions_unenforced` warning for every agent step
+ * that declares this block in a declarative spec — YAML/JSON, or a `FlowSpec`
+ * handed to the check API. A declaration inside an authored `.flow.ts` body is
+ * **not** inspected: checking TypeScript preflights the flow header without
+ * executing the body, so those steps do not exist yet and the check passes
+ * silently. A clean check is not evidence that no unenforced declaration is
+ * present; the paragraph above is, for every dialect.
+ */
 export interface PermissionsSpec {
   fileGlobs?: string[];
   networkAllowlist?: string[];

package/src/step-env.ts

@@ -0,0 +1,47 @@
+// The four names a worker exports so an agent can find its own run on disk.
+//
+// Set on every direct claude/codex attempt that has a data directory
+// (worker-cli.ts), and read by `flows status` when it is invoked with no run
+// id. Identifiers and a path only: with these an agent can open its journal
+// and nothing else. Env rather than a file in cwd because a cwd file pollutes
+// the workspace, goes stale after a crash and breaks when `spec.cwd` is
+// shared; the environment dies with the attempt.
+
+import { resolve } from 'node:path';
+
+export const DATA_DIR_ENV = 'RELAYFLOW_DATA_DIR';
+export const RUN_ID_ENV = 'RELAYFLOW_RUN_ID';
+export const STEP_ID_ENV = 'RELAYFLOW_STEP_ID';
+export const ATTEMPT_ENV = 'RELAYFLOW_ATTEMPT';
+
+export const STEP_ENV_NAMES = [DATA_DIR_ENV, RUN_ID_ENV, STEP_ID_ENV, ATTEMPT_ENV] as const;
+
+export interface StepIdentity {
+  dataDir: string;
+  runId: string;
+  stepId: string;
+  /**
+   * Optional for the same reason it is optional on `SidechannelContext`: a
+   * spawn that names no attempt has none to export, and an absent
+   * `RELAYFLOW_ATTEMPT` is the honest form. `flows status` needs the run and
+   * the step to resolve itself; the attempt only picks a transcript tail.
+   */
+  attempt?: number;
+}
+
+/**
+ * Overwrite the four names in `env` from `identity`, or remove them when there
+ * is none. Removal matters: a worker that is itself running inside a step
+ * inherits its parent's values, and an agent must not mistake them for its own.
+ * The data dir is made absolute because the agent's cwd may be `spec.cwd`.
+ */
+export function applyStepEnvironment(env: NodeJS.ProcessEnv, identity: StepIdentity | undefined): void {
+  for (const name of STEP_ENV_NAMES) delete env[name];
+  if (identity === undefined) return;
+  env[DATA_DIR_ENV] = resolve(identity.dataDir);
+  env[RUN_ID_ENV] = identity.runId;
+  env[STEP_ID_ENV] = identity.stepId;
+  // Left unset rather than set to "undefined": the four names are deleted
+  // above, so an agent sees no attempt instead of a bogus one.
+  if (identity.attempt !== undefined) env[ATTEMPT_ENV] = String(identity.attempt);
+}

package/src/transcript-tail.ts

@@ -0,0 +1,193 @@
+// Bounded transcript tails: the last 64 KiB of an agent attempt's stdout and
+// stderr, on disk beside its `pty.sock`.
+//
+// Nothing else holds the transcript. The worker buffers it in memory and
+// publishes it live to the sidechannel; a failed agent attempt's output is
+// nulled in the journal (machine.rs), leaving at most 2,000 chars of gate
+// `detail`. So "why did my last attempt end" was unanswerable from disk.
+//
+// These files are evidence, not the record: best-effort, bounded, rewritten
+// in place, never a reason for a step to fail. The journal remains truth.
+// The file is raw; `flows status` redacts on read, which is the same trust
+// boundary as `pty.sock` today (same OS user, mode 0600).
+
+import { mkdir, open, readFile, rename } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { ptySocketPath } from './pty-sidechannel.js';
+import { redact } from './redact.js';
+import type { StepTails, TailSource, TranscriptTail } from './cli/status.js';
+import type { StepView } from './run-state.js';
+
+export const TAIL_CAPACITY_BYTES = 64 * 1024;
+/** At most four rewrites a second, however fast the agent talks. */
+export const TAIL_FLUSH_INTERVAL_MS = 250;
+/**
+ * How long a spawn's completion will wait for the final tail flush. Transcript
+ * evidence is best-effort, so a stalled filesystem must cost the step this
+ * much and no more — past it the invocation settles and the close runs on.
+ */
+export const TAIL_CLOSE_TIMEOUT_MS = 2_000;
+
+export type TailStream = 'stdout' | 'stderr';
+
+export interface TailIdentity {
+  dataDir: string;
+  runId: string;
+  stepId: string;
+  attempt: number;
+}
+
+/** The first line of every tail file, so a stale file is never mistaken for this attempt's. */
+export interface TailHeader {
+  v: 1;
+  run_id: string;
+  step_id: string;
+  attempt: number;
+  started_at_ms: number;
+}
+
+export function transcriptTailPath(identity: TailIdentity, stream: TailStream): string {
+  if (!Number.isSafeInteger(identity.attempt) || identity.attempt < 0) throw new Error('Invalid transcript tail attempt');
+  return join(dirname(ptySocketPath(identity)), `attempt-${identity.attempt}.${stream}.tail`);
+}
+
+export interface TranscriptTailWriter {
+  append(chunk: Buffer): void;
+  /** Flush what is pending and stop. Resolves once the last write has settled, success or not. */
+  close(): Promise<void>;
+}
+
+/**
+ * A ring of the last {@link TAIL_CAPACITY_BYTES} bytes, flushed to
+ * `attempt-<n>.<stream>.tail` at most every {@link TAIL_FLUSH_INTERVAL_MS}.
+ * A write failure is reported once as a process warning and then ignored:
+ * the attempt continues, and `flows status` will say no transcript is on disk.
+ */
+export function openTranscriptTail(
+  identity: TailIdentity,
+  stream: TailStream,
+  startedAtMs = Date.now(),
+  warn: (message: string) => void = (message) => process.emitWarning(message),
+): TranscriptTailWriter {
+  const path = transcriptTailPath(identity, stream);
+  const header = JSON.stringify({ v: 1, run_id: identity.runId, step_id: identity.stepId, attempt: identity.attempt, started_at_ms: startedAtMs } satisfies TailHeader);
+  const ring: Buffer[] = [];
+  let ringBytes = 0;
+  let dirty = false;
+  let closed = false;
+  let failed = false;
+  let timer: NodeJS.Timeout | undefined;
+  let inFlight: Promise<void> = Promise.resolve();
+
+  const flush = (): Promise<void> => {
+    if (!dirty || failed) return inFlight;
+    dirty = false;
+    const body = Buffer.concat([Buffer.from(`${header}\n`), ...ring]);
+    inFlight = inFlight.then(async () => {
+      // Write beside, then rename over: a reader never sees a torn file.
+      const staging = `${path}.tmp`;
+      await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+      const file = await open(staging, 'w', 0o600);
+      try { await file.writeFile(body); } finally { await file.close(); }
+      await rename(staging, path);
+    }).catch((error: unknown) => {
+      if (failed) return;
+      failed = true;
+      warn(`Transcript tail for ${identity.runId}/${identity.stepId} attempt ${identity.attempt} (${stream}) could not be written; the step continues without it: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    return inFlight;
+  };
+
+  return {
+    append(chunk) {
+      if (closed || failed || chunk.length === 0) return;
+      if (chunk.length >= TAIL_CAPACITY_BYTES) {
+        ring.splice(0, ring.length, Buffer.from(chunk.subarray(chunk.length - TAIL_CAPACITY_BYTES)));
+        ringBytes = TAIL_CAPACITY_BYTES;
+      } else {
+        ring.push(Buffer.from(chunk));
+        ringBytes += chunk.length;
+        while (ringBytes > TAIL_CAPACITY_BYTES) {
+          const excess = ringBytes - TAIL_CAPACITY_BYTES;
+          const head = ring[0]!;
+          if (head.length <= excess) { ring.shift(); ringBytes -= head.length; } else { ring[0] = head.subarray(excess); ringBytes -= excess; }
+        }
+      }
+      dirty = true;
+      if (timer === undefined) {
+        timer = setTimeout(() => { timer = undefined; void flush(); }, TAIL_FLUSH_INTERVAL_MS);
+        timer.unref();
+      }
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      if (timer !== undefined) { clearTimeout(timer); timer = undefined; }
+      await flush();
+    },
+  };
+}
+
+/** A tail file parsed and checked against the attempt it claims to be. */
+export interface ReadTail {
+  header: TailHeader;
+  /** Bytes of transcript on disk, after the header line. */
+  bytes: number;
+  text: string;
+}
+
+/**
+ * Read one tail file. `undefined` when absent, unparseable, or written for a
+ * different attempt — or for this attempt number but before the journal says
+ * the attempt began, which is a file left by an earlier life of this data dir.
+ */
+export async function readTranscriptTail(
+  identity: TailIdentity,
+  stream: TailStream,
+  attemptStartedAtMs: number | null,
+): Promise<ReadTail | undefined> {
+  let raw: Buffer;
+  try {
+    raw = await readFile(transcriptTailPath(identity, stream));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+  const newline = raw.indexOf(10);
+  if (newline < 0) return undefined;
+  let header: unknown;
+  try { header = JSON.parse(raw.subarray(0, newline).toString('utf8')); } catch { return undefined; }
+  if (header === null || typeof header !== 'object') return undefined;
+  const claimed = header as Partial<TailHeader>;
+  if (claimed.v !== 1 || claimed.run_id !== identity.runId || claimed.step_id !== identity.stepId
+    || claimed.attempt !== identity.attempt || typeof claimed.started_at_ms !== 'number') return undefined;
+  if (attemptStartedAtMs !== null && claimed.started_at_ms < attemptStartedAtMs) return undefined;
+  const body = raw.subarray(newline + 1);
+  return { header: claimed as TailHeader, bytes: body.length, text: body.toString('utf8') };
+}
+
+/**
+ * Redact the whole tail before splitting it. A direct agent inherits the
+ * worker's environment, so it can print a multiline secret; splitting first
+ * meant no line held the whole value and `replaceAll` matched none of them.
+ */
+function lastLines(text: string, count: number, env: NodeJS.ProcessEnv): string[] {
+  const lines = redact(text, env).split('\n');
+  if (lines.at(-1) === '') lines.pop();
+  return lines.slice(Math.max(0, lines.length - count));
+}
+
+/** The {@link TailSource} `flows status` uses: this step's latest attempt, redacted. */
+export function transcriptTailSource(env: NodeJS.ProcessEnv = process.env): TailSource {
+  return {
+    async read(dataDir: string, runId: string, step: StepView, lines: number): Promise<StepTails> {
+      if (step.type !== 'agent' || step.attempt === 0) return null;
+      const identity = { dataDir, runId, stepId: step.id, attempt: step.attempt };
+      const tail = async (stream: TailStream): Promise<TranscriptTail | null> => {
+        const read = await readTranscriptTail(identity, stream, step.started_at_ms);
+        return read === undefined ? null : { attempt: step.attempt, bytes: read.bytes, lines: lastLines(read.text, lines, env) };
+      };
+      return { stdout: await tail('stdout'), stderr: await tail('stderr') };
+    },
+  };
+}

package/src/worker-cli.ts

@@ -1,9 +1,13 @@
+import { realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { diffWorkspaceFiles, snapshotWorkspaceFiles } from './agent-artifacts.js';
-import { decodeProviderResult, decodeWrapperResult, requirePricedUsage } from './worker-usage.js';
+import { claudeResultOutcome, decodeProviderResult, decodeWrapperResult, requirePricedUsage } from './worker-usage.js';
 import { openSidechannel, type SidechannelContext } from './pty-sidechannel.js';
+import { openTranscriptWriter, transcriptPath, type TranscriptDigest, type TranscriptFile, type TranscriptWriter } from './agent-transcript.js';
 import { spawn } from 'node:child_process';
-import { childStop, ownsProcessGroup } from './child-stop.js';
+import { StringDecoder } from 'node:string_decoder';
+import { childStop } from './child-stop.js';
+import { reapOnExit } from './agent-reaper.js';
 import {
   agentExecution,
   llmExecution,
@@ -17,6 +21,9 @@ import {
   type WrapperSessionLimits,
 } from './wrapper-session.js';
 import { wrapperEnvironment } from './wrapper-runtime.js';
+import { redactRelayError } from './redact.js';
+import { applyStepEnvironment } from './step-env.js';
+import { TAIL_CLOSE_TIMEOUT_MS, openTranscriptTail, transcriptTailPath, type TranscriptTailWriter } from './transcript-tail.js';
 import {
   runAgentRelayTask,
   AgentRelayTransportError,
@@ -50,6 +57,15 @@ export interface WorkerCliResult {
    * agent runs on another host.
    */
   artifacts?: string[];
+  /**
+   * The attempt's transcript digest (`agent-transcript.ts`): provider result
+   * metadata, tool calls summarized, final text, failure excerpt, and — when
+   * the spawn had a sidechannel context with an attempt — the pointer to the
+   * redacted, capped `stream-json` file. Journaled in `trajectory_tail`, never
+   * in `output`. Present for Claude/Codex executions; absent for wrappers and
+   * the relay transport, which stream no provider frames through this process.
+   */
+  transcript?: TranscriptDigest;
 }
 
 /**
@@ -93,23 +109,44 @@ export async function runAgentCli(
   // workspace to change. Executions sharing a working directory are
   // 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.
   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();
-      return { ...result, artifacts: diffWorkspaceFiles(before, await snapshotWorkspaceFiles(artifactRoot)) };
+      const ours = new Set<string>();
+      for (const path of ownEvidencePaths(sidechannel)) {
+        const real = realPath(path);
+        if (real !== undefined) ours.add(real);
+      }
+      const artifacts = diffWorkspaceFiles(before, await snapshotWorkspaceFiles(artifactRoot))
+        .filter(path => {
+          const real = realPath(resolve(artifactRoot, path));
+          return real === undefined || !ours.has(real);
+        });
+      return { ...result, artifacts };
     });
 
   async function execute(): Promise<WorkerCliResult> {
   if (kind === 'relayflows-wrapper-v1') {
+    // The closed allowlist admits no ambient RELAYFLOW_* value; the four
+    // discovery names are set from this dispatch, exactly as for a direct spawn.
+    const wrapperEnv = wrapperEnvironment(process.env);
+    applyStepEnvironment(wrapperEnv, sidechannel);
     return requirePricedUsage(decodeWrapperResult(await runWrapperSession(
       cli,
       instruction,
       wakeContext,
       effectiveModel,
-      wrapperEnvironment(process.env),
+      wrapperEnv,
       wrapperLimits,
       signal,
       cwd,
@@ -119,6 +156,9 @@ export async function runAgentCli(
   const env: NodeJS.ProcessEnv = { ...process.env };
   delete env[WAKE_CONTEXT_ENV];
   delete env[MODEL_ENV];
+  // Where this attempt's journal is, so the agent can run `flows status` on
+  // itself. Only a worker with a data dir knows; an ad-hoc spawn exports nothing.
+  applyStepEnvironment(env, sidechannel);
   const invocation = mode === 'llm' ? llmExecution(kind, instruction, effectiveModel) : agentExecution(kind, instruction, effectiveModel);
 
   if (wakeContext !== undefined) {
@@ -134,13 +174,71 @@ export async function runAgentCli(
   }
 
   if (invocation.modelEnv !== undefined) env[MODEL_ENV] = invocation.modelEnv;
-  // Structured provider output carries the authoritative token counts.
+  // Structured provider output carries the authoritative token counts. Claude
+  // streams it, so its final result is seen when it is emitted rather than
+  // only once the process exits — which, after a background task, it may not.
   const args = [...invocation.args];
-  args.splice(args.length - 1, 0, ...(kind === 'claude' ? ['--output-format', 'json'] : ['--json']));
-  return requirePricedUsage(decodeProviderResult(await spawnInvocation(cli, { ...invocation, args }, env, signal, sidechannel, cwd), kind), effectiveModel);
+  args.splice(args.length - 1, 0, ...(kind === 'claude' ? ['--output-format', 'stream-json', '--verbose'] : ['--json']));
+  const completion = kind === 'claude' ? claudeResultOutcome : undefined;
+  return requirePricedUsage(decodeProviderResult(await spawnInvocation(cli, { ...invocation, args }, env, signal, sidechannel, cwd, completion), kind, env), effectiveModel);
+  }
+}
+
+function openTails(context: SidechannelContext): { stdout: TranscriptTailWriter; stderr: TranscriptTailWriter } | undefined {
+  // Same rule as the per-attempt transcript file: no attempt, no tails.
+  const attempt = context.attempt;
+  if (attempt === undefined) return undefined;
+  const identity = { dataDir: context.dataDir, runId: context.runId, stepId: context.stepId, attempt };
+  try {
+    return { stdout: openTranscriptTail(identity, 'stdout'), stderr: openTranscriptTail(identity, 'stderr') };
+  } catch {
+    // An id the path cannot carry; the sidechannel declined it the same way.
+    return undefined;
   }
 }
 
+/**
+ * Every path this process may write under the workspace during an attempt, so
+ * the artifact diff can drop all of them.
+ *
+ * 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.
+ *
+ * Empty when there is no sidechannel or no attempt to name, which is exactly
+ * when nothing is written.
+ */
+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 [];
+  }
+}
+
+/** Symlink-free form of a path, or the path itself when it cannot be resolved. */
+function realPath(path: string | undefined): string | undefined {
+  if (path === undefined) return undefined;
+  try { return realpathSync(path); } catch { return path; }
+}
+
 /** One agent at a time per canonical working directory, for the artifact interval. */
 const directoryQueues = new Map<string, Promise<unknown>>();
 function serializedByDirectory<T>(directory: string, task: () => Promise<T>): Promise<T> {
@@ -186,13 +284,14 @@ async function runViaAgentRelay(
   }
 }
 
-function redactRelayError(message: string): string {
-  for (const key of ['RELAY_AGENT_TOKEN', 'RELAY_API_KEY']) {
-    const secret = process.env[key];
-    if (secret) message = message.replaceAll(secret, '[redacted]');
-  }
-  return message.replace(/\b(?:at|rk|nt|ot|br|arr)_(?:live_)?[A-Za-z0-9_-]+/g, '[redacted]');
-}
+/**
+ * How long a CLI that has reported its final result may take to exit. Claude
+ * Code in print mode waits, after its result, for every background task it
+ * started to finish; one that never finishes kept a finished step running
+ * until the whole run's deadline. Past this grace the result stands and the
+ * tree is stopped.
+ */
+export const RESULT_EXIT_GRACE_MS = 30_000;
 
 async function spawnInvocation(
   cli: string,
@@ -201,17 +300,36 @@ async function spawnInvocation(
   signal?: AbortSignal,
   sidechannel?: SidechannelContext,
   cwd?: string,
+  completion?: (line: string) => { failed: boolean } | undefined,
 ): Promise<WorkerCliResult> {
   let writeInput: (bytes: Buffer) => Promise<boolean> = async () => false;
   let canDrive = () => false;
   let driven = false;
+  // The transcript file lives beside the PTY socket and is named by attempt.
+  // Its absence (no data dir, no attempt, unwritable dir) costs the step
+  // nothing: the digest is built from the buffered frames regardless. Opened
+  // BEFORE the sidechannel: once `onReady` has fired, a drive peer's HELLO may
+  // arrive at any time, and nothing may sit between that and the spawn that
+  // arms `canDrive`.
+  const writer: TranscriptWriter | undefined = sidechannel?.attempt === undefined ? undefined
+    : await openTranscriptWriter(transcriptPath(sidechannel, sidechannel.attempt), env);
   const channel = sidechannel === undefined ? undefined : await openSidechannel({
     ...sidechannel,
     onDrive() { driven = true; sidechannel.onDrive(); },
   }, bytes => writeInput(bytes), () => canDrive());
-  if (signal?.aborted) { channel?.close(); signal.throwIfAborted(); }
+  // Tee the transcript into bounded tail files beside the socket. Evidence
+  // for `flows status --tail`, never the record; a failure here is a warning.
+  const tails = sidechannel === undefined ? undefined : openTails(sidechannel);
+  if (signal?.aborted) {
+    channel?.close();
+    void writer?.close();
+    void tails?.stdout.close(); void tails?.stderr.close();
+    signal.throwIfAborted();
+  }
   return new Promise((resolve) => {
-    const ownsGroup = ownsProcessGroup(signal);
+    // Always a group of its own off Windows, so every stop — and
+    // `reapOnExit` — reaches the whole agent tree, lease-bound or not.
+    const ownsGroup = process.platform !== 'win32';
     const child = spawn(cli, invocation.args, {
       stdio: ['pipe', 'pipe', 'pipe'], env,
       detached: ownsGroup,
@@ -232,22 +350,58 @@ async function spawnInvocation(
       child.stdin.write(bytes, error => resolve(!error));
     });
     const stop = childStop(child, ownsGroup);
+    const release = ownsGroup ? reapOnExit(stop) : () => {};
     const stdout: Buffer[] = [];
     const stderr: Buffer[] = [];
     let settled = false;
     let timer: NodeJS.Timeout | undefined;
-    const finish = (result: WorkerCliResult): void => {
+    let graceTimer: NodeJS.Timeout | undefined;
+    const decoder = new StringDecoder('utf8');
+    let partialLine = '';
+    const finish = (result: WorkerCliResult, discardTranscript = false): void => {
       if (settled) return;
       settled = true;
       if (inputTimer !== undefined) clearTimeout(inputTimer);
       channel?.close();
       if (timer !== undefined) clearTimeout(timer);
+      if (graceTimer !== undefined) clearTimeout(graceTimer);
       signal?.removeEventListener('abort', onAbort);
-      resolve(result);
+      if (writer === undefined && tails === undefined) { resolve(result); return; }
+      if (writer !== undefined) {
+        const rest = partialLine + decoder.end();
+        if (rest.length > 0) writer.write(rest);
+      }
+      // Two independent pieces of evidence close here: the per-attempt
+      // transcript, whose descriptor rides back on the result as the digest's
+      // file pointer, and the `flows status --tail` tails, which nothing reads
+      // from the result.
+      //
+      // Neither may hold a step open. A stalled write would leave
+      // `runAgentCli` unresolved forever, and every later abort or timeout is
+      // already a no-op once `settled` is true — so the whole close is raced
+      // against a bounded deadline and the result stands either way. Past the
+      // deadline the transcript pointer is dropped rather than waited for: a
+      // completion without a pointer is recoverable, a step that never
+      // completes is not.
+      // The writer's result is recorded the moment it lands, not read out of
+      // the combined race: the two closes are independent, and a stalled tail
+      // must not throw away a transcript that finished and is on disk.
+      let transcriptFile: TranscriptFile | undefined;
+      const closedWriter = writer === undefined
+        ? Promise.resolve()
+        : writer.close().then((file) => { transcriptFile = file; }, () => {});
+      const closedTails = tails === undefined
+        ? Promise.resolve()
+        : Promise.all([tails.stdout.close(), tails.stderr.close()]).then(() => undefined, () => undefined);
+      const deadline = new Promise<void>((done) => setTimeout(done, TAIL_CLOSE_TIMEOUT_MS).unref?.());
+      void Promise.race([Promise.all([closedWriter, closedTails]), deadline]).then(() => {
+        resolve(discardTranscript || transcriptFile === undefined
+          ? result : { ...result, transcript: { file: transcriptFile } });
+      }, () => resolve(result));
     };
     const onAbort = (): void => {
       stop.kill();
-      finish({ exit_code: null, stdout_tail: '', stderr_tail: 'Agent execution aborted: lease ownership lost.' });
+      finish({ exit_code: null, stdout_tail: '', stderr_tail: 'Agent execution aborted: lease ownership lost.' }, true);
     };
     /**
      * Same invariant as `wrapper-session.ts`: `'close'` and `'error'` are
@@ -263,13 +417,51 @@ async function spawnInvocation(
     };
     signal?.addEventListener('abort', onAbort, { once: true });
     if (signal?.aborted) onAbort();
-    child.stdout.on('data', (chunk: Buffer) => { stdout.push(chunk); channel?.publish(chunk); });
-    child.stderr.on('data', (chunk: Buffer) => { stderr.push(chunk); channel?.publish(chunk); });
+    /**
+     * The CLI has reported its final result. A normal exit inside the grace
+     * settles through `'close'` exactly as before, with the real exit code.
+     * Past it, the result settles the step with the exit status that result
+     * would have carried, and the stop outlives the settle as the timeout's
+     * does.
+     */
+    const onResult = (outcome: { failed: boolean }): void => {
+      if (graceTimer !== undefined || settled) return;
+      graceTimer = setTimeout(() => {
+        stop.terminate();
+        finish({
+          exit_code: outcome.failed ? 1 : 0,
+          stdout_tail: Buffer.concat(stdout).toString('utf8'),
+          stderr_tail: `${Buffer.concat(stderr).toString('utf8')}\nCLI reported its final result but had not exited ${RESULT_EXIT_GRACE_MS}ms later; its process tree was stopped.`.trim(),
+        });
+      }, RESULT_EXIT_GRACE_MS);
+    };
+    child.stdout.on('data', (chunk: Buffer) => {
+      stdout.push(chunk);
+      channel?.publish(chunk);
+      // The tails take raw bytes, so they are fed before any line splitting
+      // and regardless of what the writer or the detector still wants.
+      tails?.stdout.append(chunk);
+      // Lines are split whenever a writer or a completion detector wants
+      // them; the detector stops looking once a result has been seen, the
+      // writer keeps every line to the end.
+      if (writer === undefined && (completion === undefined || graceTimer !== undefined)) return;
+      const lines = (partialLine + decoder.write(chunk)).split('\n');
+      partialLine = lines.pop() ?? '';
+      for (const line of lines) {
+        writer?.write(line);
+        if (completion === undefined || graceTimer !== undefined) continue;
+        const outcome = completion(line);
+        if (outcome !== undefined) onResult(outcome);
+      }
+    });
+    child.stderr.on('data', (chunk: Buffer) => { stderr.push(chunk); channel?.publish(chunk); tails?.stderr.append(chunk); });
     child.once('error', (error) => finishOnChildExit({
       exit_code: null,
       stdout_tail: Buffer.concat(stdout).toString('utf8'),
       stderr_tail: error.message,
     }));
+    child.once('error', () => { if (child.pid === undefined) release(); });
+    child.once('close', release);
     child.once('close', (code) => finishOnChildExit({
       exit_code: code,
       stdout_tail: Buffer.concat(stdout).toString('utf8'),