@akagilnc/pi-workflow-roles 0.1.3771 → 0.1.3789

package/src/collector-tool-schemas.ts

@@ -4,9 +4,33 @@ import { openToolObject } from "./open-tool-schema.ts";
 import { withInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.ts";
 
 export const collectorObserveArgsSchema = Type.Object({}, { additionalProperties: false });
+/**
+ * Stable request identity: non-empty after trim, no leading/trailing whitespace.
+ * Host schema + ledger identity seam share this contract (#677 / D2 dedup).
+ */
+export const COLLECTOR_REQUEST_ID_PATTERN = /^\S(?:.*\S)?$/;
 export const collectorRequestArgsSchema = Type.Object({
-  requestId: Type.String({ minLength: 1, description: "配置请求身份" }),
+  requestId: Type.String({
+    minLength: 1,
+    pattern: COLLECTOR_REQUEST_ID_PATTERN.source,
+    description: "请求身份（配置 id 或角色判定的稳定 id；首尾无空白）",
+  }),
   snapshotId: Type.String({ minLength: 1, description: "最新留存观察快照" }),
+  body: Type.Optional(Type.String({
+    minLength: 1,
+    description: "角色判定的请求正文；request-manifest 未收录该 requestId 时必填",
+  })),
+}, { additionalProperties: false });
+/** UTF-8 byte ceiling per handbook body — keeps next activation materials inside context budget. */
+export const COLLECTOR_HANDBOOK_MAX_BYTES = 64 * 1024;
+export const collectorHandbookWriteArgsSchema = Type.Object({
+  scope: Type.Union([
+    Type.Literal("general"),
+    Type.Literal("repo"),
+  ], { description: "general＝通用手册；repo＝当前仓库差异" }),
+  body: Type.String({
+    description: `手册全文（opaque 工作记忆；整份替换；UTF-8 至多 ${COLLECTOR_HANDBOOK_MAX_BYTES} 字节）`,
+  }),
 }, { additionalProperties: false });
 export const collectorReadArgsSchema = Type.Object({
   evidenceId: Type.String({ minLength: 1, description: "observe 返回的材料证据 id（evidenceId）" }),

package/src/headless-host/description.ts

@@ -0,0 +1,123 @@
+/**
+ * One headless CLI host description (#645 / #752).
+ * Every host-specific value the generic headless adapter needs — binary, argv
+ * shape, session binding — is data here; lifecycle stays one copy so #646 codex
+ * is another row, not a fork.
+ */
+import { join } from "node:path";
+
+export type HeadlessHostDescription = Readonly<{
+  /** Binary path segments relative to the operator home. */
+  binaryFromHome: readonly string[];
+  /** Durable session-id binding filename beside the session principal. */
+  sessionBindingFile: string;
+  /**
+   * Host-native print-mode flags that never change per turn (no prompt).
+   * Model / effort / system-prompt / schema / session / resume / mcp-config
+   * are composed by the adapter from the turn request — not listed here.
+   */
+  fixedArgs: readonly string[];
+  /** Print-mode flag that takes the user prompt as its value (e.g. `-p`). */
+  promptFlag: string;
+  /** CLI flag for the seat model (e.g. `--model`). */
+  modelFlag: string;
+  /** CLI flag for the seat thinking level (e.g. `--effort`); value is opaque pass-through. */
+  effortFlag: string;
+  /**
+   * CLI flag whose value is a path to the system-prompt file
+   * (`--system-prompt-file`). File delivery keeps ARG_MAX off the critical path.
+   */
+  systemPromptFlag: string;
+  /** CLI flag whose value is a JSON Schema document string. */
+  jsonSchemaFlag: string;
+  /** CLI flag whose value is a path or JSON string for MCP servers. */
+  mcpConfigFlag: string;
+  /** CLI flag to mint a fresh session id (initial turn). */
+  sessionIdFlag: string;
+  /** CLI flag to resume a prior session id. */
+  resumeFlag: string;
+}>;
+
+/** Absolute agent binary for one operator home. */
+export function resolveHeadlessBinary(
+  description: HeadlessHostDescription,
+  operatorHome: string,
+): string {
+  return join(operatorHome, ...description.binaryFromHome);
+}
+
+/**
+ * Build one headless CLI argv for a single process turn.
+ * Shape: `<promptFlag> <prompt> <fixedArgs…> <system/schema/mcp/model/effort/session…>`.
+ */
+export function headlessTurnArgs(options: {
+  readonly description: HeadlessHostDescription;
+  readonly prompt: string;
+  /** Absolute path written by the adapter; paired with `systemPromptFlag`. */
+  readonly systemPromptPath: string;
+  readonly jsonSchema: Readonly<Record<string, unknown>>;
+  /** Absolute path to host-native MCP config JSON; omitted when no AK MCP servers. */
+  readonly mcpConfigPath?: string;
+  readonly model?: string;
+  readonly effort?: string;
+  /** Fresh session: pass as session id. Resume: pass as resume id. */
+  readonly session: { readonly kind: "new"; readonly id: string } | { readonly kind: "resume"; readonly id: string };
+}): string[] {
+  const { description } = options;
+  const args: string[] = [
+    description.promptFlag,
+    options.prompt,
+    ...description.fixedArgs,
+    description.systemPromptFlag,
+    options.systemPromptPath,
+    description.jsonSchemaFlag,
+    JSON.stringify(options.jsonSchema),
+  ];
+  if (options.mcpConfigPath !== undefined && options.mcpConfigPath !== "") {
+    args.push(description.mcpConfigFlag, options.mcpConfigPath);
+  }
+  if (options.model !== undefined && options.model !== "") {
+    args.push(description.modelFlag, options.model);
+  }
+  if (options.effort !== undefined && options.effort !== "") {
+    args.push(description.effortFlag, options.effort);
+  }
+  if (options.session.kind === "new") {
+    args.push(description.sessionIdFlag, options.session.id);
+  } else {
+    args.push(description.resumeFlag, options.session.id);
+  }
+  return args;
+}
+
+/**
+ * Project shared-envelope MCP server rows into Claude `--mcp-config` JSON.
+ * Env stays a plain object (Claude CLI shape); ACP rows use `{name,value}[]`.
+ */
+export function headlessMcpConfigDocument(
+  mcpServers: readonly Readonly<Record<string, unknown>>[],
+): Readonly<{ mcpServers: Readonly<Record<string, Readonly<Record<string, unknown>>>> }> {
+  const servers: Record<string, Record<string, unknown>> = {};
+  for (const row of mcpServers) {
+    const name = typeof row.name === "string" ? row.name : undefined;
+    const command = typeof row.command === "string" ? row.command : undefined;
+    if (name === undefined || name === "" || command === undefined || command === "") continue;
+    const entry: Record<string, unknown> = { command };
+    if (Array.isArray(row.args)) entry.args = row.args;
+    if (Array.isArray(row.env)) {
+      const env: Record<string, string> = {};
+      for (const item of row.env) {
+        if (typeof item !== "object" || item === null) continue;
+        const record = item as { name?: unknown; value?: unknown };
+        if (typeof record.name === "string" && typeof record.value === "string") {
+          env[record.name] = record.value;
+        }
+      }
+      if (Object.keys(env).length > 0) entry.env = env;
+    } else if (typeof row.env === "object" && row.env !== null && !Array.isArray(row.env)) {
+      entry.env = row.env;
+    }
+    servers[name] = entry;
+  }
+  return Object.freeze({ mcpServers: Object.freeze(servers) });
+}

package/src/headless-host/production-host.ts

@@ -0,0 +1,75 @@
+/**
+ * Production composition for the generic headless CLI RoleTurnHost (#645).
+ * Agent subprocesses inherit the operator home and credentials in place.
+ * No HOME rewrite, no isolated home, no credential parameters — CLI owns auth.
+ * Sitian records on the run are the dossier; host private sessions stay private.
+ *
+ * Intermediate AK tools ride the shared envelope MCP relay via host-native
+ * `--mcp-config` under `--strict-mcp-config`. The terminating receipt is the
+ * host-native `--json-schema` / structured_output schema channel only
+ * (#750 submission-tool-is-schema-channel) — terminating tool is not listed on MCP.
+ */
+import { randomUUID } from "node:crypto";
+
+import type { DurablePrincipalAuthority, RoleTurnHost } from "../host-contracts.ts";
+import { createAcpRoleRuntimeDependencies } from "../acp-host/production-host.ts";
+import { prepareAcpRoleEnvelope } from "../acp-host/role-envelope.ts";
+import { createAcpSessionIdentityAuthority } from "../acp-host/session-identity.ts";
+import { resolveHeadlessBinary, type HeadlessHostDescription } from "./description.ts";
+import { createHeadlessRoleTurnHost } from "./role-turn-host.ts";
+
+export type ProductionHeadlessHostOptions = Readonly<{
+  packageRoot: string;
+  principalAuthority: DurablePrincipalAuthority;
+  description: HeadlessHostDescription;
+}>;
+
+/**
+ * Assemble a production headless RoleTurnHost from the shared envelope prepare
+ * (MCP relay for AK tools) and one host description row. Binary is resolved
+ * from each turn's operator home (`request.home`).
+ */
+export function createProductionHeadlessRoleTurnHost(
+  options: ProductionHeadlessHostOptions,
+): RoleTurnHost {
+  const { packageRoot, principalAuthority, description } = options;
+  const sessionIdentity = createAcpSessionIdentityAuthority(
+    principalAuthority,
+    description.sessionBindingFile,
+  );
+  const roleRuntimeDependencies = createAcpRoleRuntimeDependencies(packageRoot);
+
+  const innerFor = (operatorHome: string): RoleTurnHost =>
+    createHeadlessRoleTurnHost({
+      description,
+      sessionIdentity,
+      binary: resolveHeadlessBinary(description, operatorHome),
+      env: {
+        ...process.env,
+        AK_PACKAGE_ROOT: packageRoot,
+      },
+      prepare: (request) =>
+        prepareAcpRoleEnvelope({
+          request,
+          dependencies: roleRuntimeDependencies,
+          sessionFile: sessionIdentity.resolveSessionFile(request.principal),
+          // Same MCP relay as ACP so intermediate AK tools stay reachable;
+          // headless adapter projects the row into --mcp-config.
+          socketPath: `/tmp/ak-headless-mcp-${randomUUID()}.sock`,
+          // Schema channel owns the terminating receipt; hide it from MCP list.
+          listTerminatingToolOnMcp: false,
+        }),
+    });
+
+  let cachedHome: string | undefined;
+  let cachedHost: RoleTurnHost | undefined;
+  return {
+    executeTurn(request) {
+      if (cachedHost === undefined || cachedHome !== request.home) {
+        cachedHome = request.home;
+        cachedHost = innerFor(request.home);
+      }
+      return cachedHost.executeTurn(request);
+    },
+  };
+}

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

@@ -0,0 +1,424 @@
+/**
+ * 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.
+ */
+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 {
+  renderAcpSystemPromptOverride,
+  type AcpPreparedTurn,
+  type AcpSessionIdentityAuthority,
+} from "../acp-host/role-turn-host.ts";
+import {
+  headlessMcpConfigDocument,
+  headlessTurnArgs,
+  type HeadlessHostDescription,
+} from "./description.ts";
+
+export type HeadlessRoleTurnHostConfig = Readonly<{
+  description: HeadlessHostDescription;
+  sessionIdentity: AcpSessionIdentityAuthority;
+  binary: string;
+  prepare(request: RoleTurnRequest): Promise<AcpPreparedTurn>;
+  env?: NodeJS.ProcessEnv;
+}>;
+
+function failure(
+  cause: "activation" | "session" | "output" | "provider",
+  name: string,
+  code: string,
+  details?: Readonly<Record<string, unknown>>,
+  diagnostic?: string,
+): RoleTurnResult {
+  return {
+    code: null,
+    stderr: "",
+    timedOut: false,
+    knownFailure: {
+      cause,
+      identity: { name, code },
+      ...(diagnostic === undefined ? {} : { diagnostic }),
+      ...(details === undefined ? {} : { details }),
+    },
+  };
+}
+
+/** One headless CLI result envelope (`--output-format json`). */
+export type HeadlessCliResult = Readonly<{
+  session_id?: string;
+  is_error?: boolean;
+  subtype?: string;
+  result?: unknown;
+  structured_output?: unknown;
+  errors?: unknown;
+  permission_denials?: unknown;
+  [key: string]: unknown;
+}>;
+
+/**
+ * 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.
+ */
+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;
+      }
+    }
+  } catch {
+    // fall through
+  }
+  // Defensive: if a description still requests stream-json, keep only the result line.
+  let last: HeadlessCliResult | undefined;
+  for (const line of trimmed.split("\n")) {
+    const text = line.trim();
+    if (text === "") continue;
+    try {
+      const value = JSON.parse(text) as unknown;
+      if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
+      const record = value as HeadlessCliResult & { type?: unknown };
+      if (record.type === "result" || record.structured_output !== undefined) {
+        last = record;
+      }
+    } catch {
+      // skip non-JSON noise lines
+    }
+  }
+  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]`;
+}
+
+function spawnHeadlessTurn(options: {
+  readonly binary: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly env: NodeJS.ProcessEnv;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}): 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" }));
+      return;
+    }
+    const child = spawn(options.binary, [...options.args], {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timedOut = false;
+    let timer: NodeJS.Timeout | undefined;
+    const settle = (code: number | null): void => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+      resolve({ code, stdout, 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" }));
+    };
+    child.stdout.setEncoding("utf8").on("data", (chunk: string) => { stdout += chunk; });
+    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);
+      }
+    });
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+      reject(error);
+    });
+    child.on("close", (code) => settle(code));
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    if (options.timeoutMs !== undefined && options.timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+      }, options.timeoutMs);
+    }
+  });
+}
+
+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).
+ */
+function withCleanupFailure(outcome: RoleTurnResult, cleanupError: unknown): RoleTurnResult {
+  const message = cleanupErrorMessage(cleanupError);
+  if (outcome.knownFailure === undefined) {
+    return failure(
+      "session",
+      "HeadlessDisposeFailure",
+      "dispose-failed",
+      { cleanupError: message },
+      message,
+    );
+  }
+  return {
+    ...outcome,
+    knownFailure: {
+      ...outcome.knownFailure,
+      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();
+  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;
+
+          const abortSignal =
+            request.signal === undefined
+              ? prepared.abortSignal
+              : prepared.abortSignal === undefined
+                ? request.signal
+                : AbortSignal.any([prepared.abortSignal, request.signal]);
+
+          // 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 ?? {}),
+          };
+
+          // 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(
+            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;
+            }
+
+            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;
+                }
+                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 },
+                },
+              };
+              break;
+            }
+
+            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;
+            }
+
+            // 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);
+            }
+
+            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;
+            }
+
+            // 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;
+            }
+            // Correctable rejection → resume same session with plain resubmit prompt.
+            prompt = `The prior terminal submission was rejected (${closure.retry.code}). Resubmit it as the sole terminal structured output (or the sole terminating tool call). Rejected call ids: ${closure.retry.toolCallIds.join(", ") || "none"}.`;
+            sessionKind = "resume";
+            if (attempt === 7) {
+              outcome = failure("output", "HeadlessRoundLimit", "round-retry-limit", { sessionId });
+            }
+          }
+        } finally {
+          try {
+            await prepared.dispose?.();
+          } catch (cleanupError) {
+            outcome = withCleanupFailure(outcome, cleanupError);
+          }
+        }
+        return outcome;
+      });
+      serial = execution.then(() => undefined, () => undefined);
+      return execution;
+    },
+  };
+}