@akagilnc/pi-workflow-roles 0.1.3837 → 0.1.3873

package/src/headless-host/role-turn-host.ts

@@ -1,20 +1,23 @@
-/**
- * Generic headless CLI RoleTurnHost (#645 / #752).
- * One process per turn: spawn → read result envelope/exit → structured_output / MCP → envelope.
- * No reads of the host's private home; session id is package-owned binding only.
- * No permanent stdout/stderr/init probe copies — sitian + binding are the dossier.
- */
+/** Headless CLI last hop (#645/#820): spawn/parse/bind. Shared loop = external-host-turn-loop. */
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
-import type { RoleTurnHost, RoleTurnKnownFailure, RoleTurnRequest, RoleTurnResult } from "../host-contracts.ts";
+import type { RoleTurnHost, RoleTurnRequest, RoleTurnResult } from "../host-contracts.ts";
+import {
+  createSerializedRoleTurnHost,
+  driveExternalRoleTurnRounds,
+  hostAbortedError,
+  isHostAbortedError,
+} from "../external-host-turn-loop.ts";
 import {
-  renderAcpSystemPromptOverride,
-  type AcpPreparedTurn,
-  type AcpSessionIdentityAuthority,
-} from "../acp-host/role-turn-host.ts";
+  renderSystemPromptOverride,
+  type PreparedRoleTurn,
+  type SessionIdentityAuthority,
+} from "../prepared-role-turn.ts";
+import { retainDiagnosticTail } from "../diagnostic-tail.ts";
+import { reportHostSessionEvent } from "../host-session-record.ts";
 import {
   headlessMcpConfigDocument,
   headlessTurnArgs,
@@ -23,9 +26,11 @@ import {
 
 export type HeadlessRoleTurnHostConfig = Readonly<{
   description: HeadlessHostDescription;
-  sessionIdentity: AcpSessionIdentityAuthority;
+  sessionIdentity: SessionIdentityAuthority;
+  /** Seat-table host key (e.g. claude) for sitian host field. */
+  hostName: string;
   binary: string;
-  prepare(request: RoleTurnRequest): Promise<AcpPreparedTurn>;
+  prepare(request: RoleTurnRequest): Promise<PreparedRoleTurn>;
   env?: NodeJS.ProcessEnv;
 }>;
 
@@ -49,7 +54,7 @@ function failure(
   };
 }
 
-/** One headless CLI result envelope (`--output-format json`). */
+/** One headless CLI result envelope (stream-json last line, or single json doc). */
 export type HeadlessCliResult = Readonly<{
   session_id?: string;
   is_error?: boolean;
@@ -61,27 +66,35 @@ export type HeadlessCliResult = Readonly<{
   [key: string]: unknown;
 }>;
 
+/**
+ * True when a parsed stdout object is the typed result receipt (or a single-doc
+ * envelope without stream-json `type`). Intermediate stream-json events are not.
+ */
+function isHeadlessResultCandidate(value: unknown): value is HeadlessCliResult {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const record = value as HeadlessCliResult & { type?: unknown };
+  return record.type === undefined
+    || record.type === "result"
+    || record.structured_output !== undefined;
+}
+
 /**
  * Parse host stdout into the result envelope.
- * Production uses `--output-format json` (one document). stream-json last-result
- * parsing remains so a misconfigured description still yields a typed miss rather
- * than a silent empty parse — not a permanent probe path.
+ * Production uses `--output-format stream-json` (#811 live records); last-result
+ * line is the typed receipt. A single-document `json` body still parses so a
+ * misconfigured description yields a typed miss rather than a silent empty parse.
+ * Callers must not retain the full stream — only the rolling result candidate.
  */
 export function parseHeadlessCliStdout(stdout: string): HeadlessCliResult | undefined {
   const trimmed = stdout.trim();
   if (trimmed === "") return undefined;
   try {
     const single = JSON.parse(trimmed) as unknown;
-    if (typeof single === "object" && single !== null && !Array.isArray(single)) {
-      const record = single as HeadlessCliResult & { type?: unknown };
-      if (record.type === undefined || record.type === "result" || record.structured_output !== undefined) {
-        return record;
-      }
-    }
+    if (isHeadlessResultCandidate(single)) return single;
   } catch {
     // fall through
   }
-  // Defensive: if a description still requests stream-json, keep only the result line.
+  // stream-json: keep the last result line (structured_output / is_error live here).
   let last: HeadlessCliResult | undefined;
   for (const line of trimmed.split("\n")) {
     const text = line.trim();
@@ -90,6 +103,7 @@ export function parseHeadlessCliStdout(stdout: string): HeadlessCliResult | unde
       const value = JSON.parse(text) as unknown;
       if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
       const record = value as HeadlessCliResult & { type?: unknown };
+      // Multi-line stream: only explicit result / structured_output lines (not bare objects).
       if (record.type === "result" || record.structured_output !== undefined) {
         last = record;
       }
@@ -100,12 +114,19 @@ export function parseHeadlessCliStdout(stdout: string): HeadlessCliResult | unde
   return last;
 }
 
-/** Bound stderr retained only for failure diagnostics (not a dossier copy). */
-const STDERR_DIAGNOSTIC_CAP = 16 * 1024;
-
-function clipDiagnostic(text: string): string {
-  if (text.length <= STDERR_DIAGNOSTIC_CAP) return text;
-  return `${text.slice(0, STDERR_DIAGNOSTIC_CAP)}\n…[stderr clipped]`;
+/**
+ * If `line` is a result-candidate JSON object, return its trimmed text; else undefined.
+ * Used to roll the sole stdout retained for final parse (no full-stream copy).
+ */
+function resultCandidateText(line: string): string | undefined {
+  const text = line.trim();
+  if (text === "") return undefined;
+  try {
+    const value = JSON.parse(text) as unknown;
+    return isHeadlessResultCandidate(value) ? text : undefined;
+  } catch {
+    return undefined;
+  }
 }
 
 function spawnHeadlessTurn(options: {
@@ -115,10 +136,12 @@ function spawnHeadlessTurn(options: {
   readonly env: NodeJS.ProcessEnv;
   readonly signal?: AbortSignal;
   readonly timeoutMs?: number;
+  /** Called for each complete stdout line as it arrives (live stream-json). */
+  readonly onStdoutLine?: (line: string) => void;
 }): Promise<{ code: number | null; stdout: string; stderr: string; timedOut: boolean }> {
   return new Promise((resolve, reject) => {
     if (options.signal?.aborted) {
-      reject(Object.assign(new Error("headless host aborted"), { code: "host-aborted" }));
+      reject(hostAbortedError("headless host aborted"));
       return;
     }
     const child = spawn(options.binary, [...options.args], {
@@ -126,31 +149,68 @@ function spawnHeadlessTurn(options: {
       env: options.env,
       stdio: ["ignore", "pipe", "pipe"],
     });
-    let stdout = "";
+    // Rolling retention only: last result-candidate line for final parse.
+    // Live events go to sitian via onStdoutLine — never accumulate the full stream.
+    let resultStdout = "";
     let stderr = "";
+    let lineBuffer = "";
     let settled = false;
     let timedOut = false;
     let timer: NodeJS.Timeout | undefined;
+    const failLine = (error: unknown): void => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+      try { child.kill("SIGTERM"); } catch { /* already exiting */ }
+      reject(error instanceof Error ? error : new Error(String(error)));
+    };
+    const emitStdoutLine = (line: string): void => {
+      const candidate = resultCandidateText(line);
+      if (candidate !== undefined) resultStdout = candidate;
+      if (options.onStdoutLine === undefined) return;
+      try {
+        options.onStdoutLine(line);
+      } catch (error) {
+        failLine(error);
+      }
+    };
+    const flushStdoutLines = (chunk: string, final: boolean): void => {
+      lineBuffer += chunk;
+      for (;;) {
+        const end = lineBuffer.indexOf("\n");
+        if (end < 0) break;
+        const line = lineBuffer.slice(0, end);
+        lineBuffer = lineBuffer.slice(end + 1);
+        emitStdoutLine(line);
+        if (settled) return;
+      }
+      if (final && lineBuffer.length > 0) {
+        emitStdoutLine(lineBuffer);
+        lineBuffer = "";
+      }
+    };
     const settle = (code: number | null): void => {
+      if (settled) return;
+      // Final flush first: onStdoutLine may failLine (reject + settled=true).
+      flushStdoutLines("", true);
       if (settled) return;
       settled = true;
       if (timer !== undefined) clearTimeout(timer);
       options.signal?.removeEventListener("abort", onAbort);
-      resolve({ code, stdout, stderr, timedOut });
+      resolve({ code, stdout: resultStdout, stderr, timedOut });
     };
     const onAbort = (): void => {
       child.kill("SIGTERM");
       if (settled) return;
       settled = true;
       if (timer !== undefined) clearTimeout(timer);
-      reject(Object.assign(new Error("headless host aborted"), { code: "host-aborted" }));
+      reject(hostAbortedError("headless host aborted"));
     };
-    child.stdout.setEncoding("utf8").on("data", (chunk: string) => { stdout += chunk; });
+    child.stdout.setEncoding("utf8").on("data", (chunk: string) => { flushStdoutLines(chunk, false); });
     child.stderr.setEncoding("utf8").on("data", (chunk: string) => {
-      // Cap retained stderr: diagnostics only, not an unbounded transcript face.
-      if (stderr.length < STDERR_DIAGNOSTIC_CAP) {
-        stderr = clipDiagnostic(stderr + chunk);
-      }
+      // Rolling diagnostic tail only — not an unbounded transcript face.
+      stderr = retainDiagnosticTail(stderr + chunk);
     });
     child.on("error", (error) => {
       if (settled) return;
@@ -170,255 +230,203 @@ function spawnHeadlessTurn(options: {
   });
 }
 
-function cleanupErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-/**
- * If dispose/cleanup failed: success becomes typed failure; existing failure keeps
- * its primary cause and records the cleanup error in details (failure-honesty).
- */
+/** Success→dispose failure; existing failure keeps primary cause + cleanup detail. */
 function withCleanupFailure(outcome: RoleTurnResult, cleanupError: unknown): RoleTurnResult {
-  const message = cleanupErrorMessage(cleanupError);
+  const message = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
   if (outcome.knownFailure === undefined) {
-    return failure(
-      "session",
-      "HeadlessDisposeFailure",
-      "dispose-failed",
-      { cleanupError: message },
-      message,
-    );
+    return failure("session", "HeadlessDisposeFailure", "dispose-failed", { cleanupError: message }, message);
   }
   return {
     ...outcome,
     knownFailure: {
       ...outcome.knownFailure,
-      details: {
-        ...(outcome.knownFailure.details ?? {}),
-        cleanupError: message,
-      },
+      details: { ...(outcome.knownFailure.details ?? {}), cleanupError: message },
     },
   };
 }
 
-/**
- * Main-session headless adapter. prepare() is the shared envelope boundary;
- * this module owns only CLI spawn / parse / session-id bind / resume loop.
- */
-export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig): RoleTurnHost {
-  let serial = Promise.resolve();
+function terminalFromSpawned(
+  spawned: { code: number | null; stderr: string; timedOut: boolean },
+  knownFailure: NonNullable<RoleTurnResult["knownFailure"]>,
+): { readonly status: "terminal"; readonly result: RoleTurnResult } {
   return {
-    executeTurn(request) {
-      const execution = serial.then(async (): Promise<RoleTurnResult> => {
-        const prepared = await config.prepare(request);
-        const systemPrompt = renderAcpSystemPromptOverride(prepared.systemPrompt);
-        let outcome: RoleTurnResult = failure("session", "HeadlessNoOutcome", "no-outcome");
-        try {
-          // Same-host resume reuses the bound native session id via --resume.
-          let sessionId = await config.sessionIdentity.load(request.principal);
-          let sessionKind: "new" | "resume" =
-            request.continuation.kind === "resume" && sessionId !== undefined && sessionId !== ""
-              ? "resume"
-              : "new";
-          if (sessionKind === "new") {
-            sessionId = randomUUID();
-            await config.sessionIdentity.bind(request.principal, sessionId);
-          }
-
-          // Cross-host handoff: prior-native paths ride the user prompt (DK-7).
-          const priorNativePaths =
-            request.continuation.kind === "resume"
-              ? request.hostTransition?.priorNativePaths
-              : undefined;
-          let prompt =
-            priorNativePaths !== undefined && priorNativePaths.length > 0
-              ? `${prepared.prompt}\n${priorNativePaths.join("\n")}`
-              : prepared.prompt;
+    status: "terminal",
+    result: {
+      code: spawned.code,
+      stderr: spawned.stderr,
+      timedOut: spawned.timedOut,
+      knownFailure,
+    },
+  };
+}
 
-          const abortSignal =
-            request.signal === undefined
-              ? prepared.abortSignal
-              : prepared.abortSignal === undefined
-                ? request.signal
-                : AbortSignal.any([prepared.abortSignal, request.signal]);
+/** Headless last hop (#820): session bind/resume, CLI spawn turn, MCP/json-schema mount. */
+export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig): RoleTurnHost {
+  return createSerializedRoleTurnHost(async (request): Promise<RoleTurnResult> => {
+    const prepared = await config.prepare(request);
+    const systemPrompt = renderSystemPromptOverride(prepared.systemPrompt);
+    let outcome: RoleTurnResult = failure("session", "HeadlessNoOutcome", "no-outcome");
+    try {
+      let sessionId = await config.sessionIdentity.load(request.principal);
+      let sessionKind: "new" | "resume" =
+        request.continuation.kind === "resume" && sessionId !== undefined && sessionId !== ""
+          ? "resume"
+          : "new";
+      if (sessionKind === "new") {
+        sessionId = randomUUID();
+        await config.sessionIdentity.bind(request.principal, sessionId);
+      }
 
-          // config.env is the production authority for package-root / host child env
-          // (see createProductionHeadlessRoleTurnHost). Do not re-override keys from
-          // process.env after the spread — that erased AK_PACKAGE_ROOT.
-          const env: NodeJS.ProcessEnv = {
-            ...process.env,
-            ...(config.env ?? {}),
-          };
+      // config.env owns package-root/child env; do not re-spread process.env over it.
+      const env: NodeJS.ProcessEnv = { ...process.env, ...(config.env ?? {}) };
+      const systemPromptPath = join(request.runDirectory, "headless-system-prompt.txt");
+      await writeFile(systemPromptPath, systemPrompt, "utf8");
+      const mcpConfigPath = join(request.runDirectory, "headless-mcp-config.json");
+      await writeFile(
+        mcpConfigPath,
+        `${JSON.stringify(headlessMcpConfigDocument(prepared.mcpServers), null, 2)}\n`,
+        "utf8",
+      );
 
-          // Materialize system prompt + MCP config once per prepare (stable across
-          // correctable retries). Paths live under the run directory we already own.
-          // Envelope always projects the AK MCP relay row; no empty-server branch.
-          const systemPromptPath = join(request.runDirectory, "headless-system-prompt.txt");
-          await writeFile(systemPromptPath, systemPrompt, "utf8");
-          const mcpConfigPath = join(request.runDirectory, "headless-mcp-config.json");
-          await writeFile(
+      const sessionParent = config.sessionIdentity.resolveSessionFile(request.principal);
+      outcome = await driveExternalRoleTurnRounds(prepared, request, {
+        roundLimitName: "HeadlessRoundLimit",
+        currentSessionId: () => sessionId,
+        afterRetry() { sessionKind = "resume"; },
+        async runRound({ prompt, abortSignal }) {
+          const args = headlessTurnArgs({
+            description: config.description,
+            prompt,
+            systemPromptPath,
+            jsonSchema: prepared.jsonSchema,
             mcpConfigPath,
-            `${JSON.stringify(headlessMcpConfigDocument(prepared.mcpServers), null, 2)}\n`,
-            "utf8",
-          );
-
-          // No round cap on content review (#750); this bound is only for
-          // correctable mechanical resubmit (non-sole etc.), matching ACP's 8.
-          for (let attempt = 0; attempt < 8; attempt += 1) {
-            if (abortSignal?.aborted) {
-              const closure = await prepared.closeRound();
-              if ("failure" in closure) {
-                outcome = { code: null, stderr: "", timedOut: false, knownFailure: closure.failure };
-                break;
-              }
-              outcome = failure("session", "HostAborted", "host-aborted", { sessionId });
-              break;
-            }
+            ...(request.model?.model !== undefined ? { model: request.model.model } : {}),
+            ...(request.model?.thinking !== undefined ? { effort: request.model.thinking } : {}),
+            session: sessionKind === "new"
+              ? { kind: "new", id: sessionId! }
+              : { kind: "resume", id: sessionId! },
+          });
 
-            const args = headlessTurnArgs({
-              description: config.description,
-              prompt,
-              systemPromptPath,
-              jsonSchema: prepared.jsonSchema,
-              mcpConfigPath,
-              ...(request.model?.model !== undefined ? { model: request.model.model } : {}),
-              ...(request.model?.thinking !== undefined ? { effort: request.model.thinking } : {}),
-              session: sessionKind === "new"
-                ? { kind: "new", id: sessionId! }
-                : { kind: "resume", id: sessionId! },
-            });
-
-            let spawned: { code: number | null; stdout: string; stderr: string; timedOut: boolean };
-            try {
-              spawned = await spawnHeadlessTurn({
-                binary: config.binary,
-                args,
-                cwd: request.cwd,
-                env,
-                ...(abortSignal === undefined ? {} : { signal: abortSignal }),
-                ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
-              });
-            } catch (error) {
-              if (
-                typeof error === "object"
-                && error !== null
-                && (error as { code?: unknown }).code === "host-aborted"
-              ) {
-                const closure = await prepared.closeRound();
-                if ("failure" in closure) {
-                  outcome = { code: null, stderr: "", timedOut: false, knownFailure: closure.failure };
-                  break;
+          let spawned: { code: number | null; stdout: string; stderr: string; timedOut: boolean };
+          try {
+            spawned = await spawnHeadlessTurn({
+              binary: config.binary,
+              args,
+              cwd: request.cwd,
+              env,
+              ...(abortSignal === undefined ? {} : { signal: abortSignal }),
+              ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
+              onStdoutLine(line) {
+                const trimmed = line.trim();
+                if (trimmed === "") return;
+                let event: unknown;
+                try {
+                  event = JSON.parse(trimmed) as unknown;
+                } catch {
+                  // Non-JSON noise on stdout is not a host structured event.
+                  return;
                 }
-                outcome = failure("session", "HostAborted", "host-aborted", { sessionId });
-                break;
-              }
-              const message = error instanceof Error ? error.message : String(error);
-              outcome = failure("activation", "HeadlessSpawnFailure", "spawn-failed", {
-                diagnostic: message,
-                binary: config.binary,
-              }, message);
-              break;
-            }
-
-            if (spawned.timedOut) {
-              outcome = {
-                code: spawned.code,
-                stderr: spawned.stderr,
-                timedOut: true,
-                knownFailure: {
-                  cause: "timeout",
-                  identity: { name: "HeadlessTimeout", code: "timeout" },
-                  details: { sessionId },
-                },
+                // Sitian write failures propagate → spawn rejects → session failure.
+                reportHostSessionEvent({
+                  host: config.hostName,
+                  cwd: request.cwd,
+                  sessionParent,
+                  source: "headless-host",
+                  event,
+                });
+              },
+            });
+          } catch (error) {
+            if (isHostAbortedError(error)) throw error;
+            const message = error instanceof Error ? error.message : String(error);
+            // SitianInfrastructureError.knownCause is session; spawn errno stays activation.
+            const isRecordFailure =
+              typeof error === "object"
+              && error !== null
+              && ((error as { knownCause?: unknown }).knownCause === "session"
+                || (error as { name?: unknown }).name === "SitianInfrastructureError");
+            if (isRecordFailure) {
+              return {
+                status: "terminal",
+                result: failure(
+                  "session",
+                  "HostSessionRecordFailure",
+                  "host-session-record-failed",
+                  { diagnostic: message, sessionId },
+                  message,
+                ),
               };
-              break;
             }
+            return {
+              status: "terminal",
+              result: failure("activation", "HeadlessSpawnFailure", "spawn-failed", {
+                diagnostic: message,
+                binary: config.binary,
+              }, message),
+            };
+          }
 
-            const envelope = parseHeadlessCliStdout(spawned.stdout);
-            if (envelope === undefined) {
-              outcome = {
-                code: spawned.code,
-                stderr: spawned.stderr,
-                timedOut: false,
-                knownFailure: {
-                  cause: "output",
-                  identity: { name: "HeadlessEmptyOutput", code: "empty-stdout" },
-                  diagnostic: clipDiagnostic(spawned.stderr.trim() || "headless CLI produced no parseable result"),
-                  details: { sessionId, exitCode: spawned.code },
-                },
-              };
-              break;
-            }
+          if (spawned.timedOut) {
+            return terminalFromSpawned(spawned, {
+              cause: "timeout",
+              identity: { name: "HeadlessTimeout", code: "timeout" },
+              details: { sessionId },
+            });
+          }
 
-            // Bind the host-reported session id (authoritative for --resume).
-            if (typeof envelope.session_id === "string" && envelope.session_id !== "") {
-              sessionId = envelope.session_id;
-              await config.sessionIdentity.bind(request.principal, sessionId);
-            }
+          const envelope = parseHeadlessCliStdout(spawned.stdout);
+          if (envelope === undefined) {
+            return terminalFromSpawned(spawned, {
+              cause: "output",
+              identity: { name: "HeadlessEmptyOutput", code: "empty-stdout" },
+              diagnostic: retainDiagnosticTail(spawned.stderr.trim() || "headless CLI produced no parseable result"),
+              details: { sessionId, exitCode: spawned.code },
+            });
+          }
 
-            if (envelope.is_error === true || (typeof envelope.subtype === "string" && envelope.subtype.startsWith("error_"))) {
-              const errorCode =
-                typeof envelope.subtype === "string" && envelope.subtype.startsWith("error_")
-                  ? envelope.subtype
-                  : envelope.is_error === true
-                    ? "is_error"
-                    : "cli-error";
-              const diagnostic = typeof envelope.result === "string"
-                ? envelope.result
-                : Array.isArray(envelope.errors)
-                  ? envelope.errors.map(String).join("\n")
-                  : clipDiagnostic(spawned.stderr.trim() || "headless CLI reported is_error");
-              outcome = {
-                code: spawned.code,
-                stderr: spawned.stderr,
-                timedOut: false,
-                knownFailure: {
-                  cause: "output",
-                  identity: { name: "HeadlessCliError", code: errorCode },
-                  diagnostic,
-                  details: {
-                    sessionId,
-                    subtype: envelope.subtype,
-                    errors: envelope.errors,
-                    exitCode: spawned.code,
-                  },
-                },
-              };
-              break;
-            }
+          if (typeof envelope.session_id === "string" && envelope.session_id !== "") {
+            sessionId = envelope.session_id;
+            await config.sessionIdentity.bind(request.principal, sessionId);
+          }
 
-            // Schema channel: host-native structured_output is the terminating receipt
-            // (#750). Intermediate tools may have already run via MCP during the process.
-            if (envelope.structured_output !== undefined) {
-              await prepared.ingestStructuredOutput(envelope.structured_output);
-            }
-            const closure = await prepared.closeRound();
-            if (closure.accepted) {
-              outcome = { code: 0, stderr: "", timedOut: false };
-              break;
-            }
-            if ("failure" in closure) {
-              outcome = { code: null, stderr: spawned.stderr, timedOut: false, knownFailure: closure.failure };
-              break;
-            }
-            // Shared envelope already owns the officer/correctable text (#813).
-            prompt = closure.retry.message;
-            sessionKind = "resume";
-            if (attempt === 7) {
-              outcome = failure("output", "HeadlessRoundLimit", "round-retry-limit", { sessionId });
-            }
+          if (envelope.is_error === true || (typeof envelope.subtype === "string" && envelope.subtype.startsWith("error_"))) {
+            const errorCode =
+              typeof envelope.subtype === "string" && envelope.subtype.startsWith("error_")
+                ? envelope.subtype
+                : envelope.is_error === true
+                  ? "is_error"
+                  : "cli-error";
+            const diagnostic = typeof envelope.result === "string"
+              ? envelope.result
+              : Array.isArray(envelope.errors)
+                ? envelope.errors.map(String).join("\n")
+                : retainDiagnosticTail(spawned.stderr.trim() || "headless CLI reported is_error");
+            return terminalFromSpawned(spawned, {
+              cause: "output",
+              identity: { name: "HeadlessCliError", code: errorCode },
+              diagnostic,
+              details: {
+                sessionId,
+                subtype: envelope.subtype,
+                errors: envelope.errors,
+                exitCode: spawned.code,
+              },
+            });
           }
-        } finally {
-          try {
-            await prepared.dispose?.();
-          } catch (cleanupError) {
-            outcome = withCleanupFailure(outcome, cleanupError);
+
+          if (envelope.structured_output !== undefined) {
+            await prepared.ingestStructuredOutput(envelope.structured_output);
           }
-        }
-        return outcome;
+          return { status: "delivered", stderr: spawned.stderr };
+        },
       });
-      serial = execution.then(() => undefined, () => undefined);
-      return execution;
-    },
-  };
+    } finally {
+      try {
+        await prepared.dispose?.();
+      } catch (cleanupError) {
+        outcome = withCleanupFailure(outcome, cleanupError);
+      }
+    }
+    return outcome;
+  });
 }