@akagilnc/pi-workflow-roles 0.1.3771 → 0.1.3783

package/dist/public-role-summons.js

@@ -99,9 +99,9 @@ async function createSummonEnv(options) {
   const hostName = options.seat.host ?? "pi";
   let roleTurnHost = piHost;
   if (hostName !== "pi") {
-    const { lookupHostDescription } = await import("./host-descriptions.js");
-    const { loadProductionAcpHostFactory } = await import("./public-cli/load-production-acp-host.js");
-    if (lookupHostDescription(hostName) === void 0) {
+    const { lookupHostFamily } = await import("./host-descriptions.js");
+    const { loadProductionExternalHostFactory } = await import("./public-cli/load-production-external-host.js");
+    if (lookupHostFamily(hostName) === void 0) {
       throw new Error(
         `public role summons host unregistered: host=${hostName} seat=${options.role}`
       );
@@ -109,7 +109,7 @@ async function createSummonEnv(options) {
     let hostPromise;
     roleTurnHost = {
       executeTurn: async (request) => {
-        hostPromise ??= loadProductionAcpHostFactory(options.packageRoot, hostName).then(
+        hostPromise ??= loadProductionExternalHostFactory(options.packageRoot, hostName).then(
           (create) => create({
             packageRoot: options.packageRoot,
             principalAuthority
@@ -151,7 +151,8 @@ async function summonPublicRole(options) {
   } = await import("./public-cli/config.js");
   const credentials = options.credentials ?? await loadCredentialProviders(agentDir);
   const config = await loadPublicCliConfig(home);
-  const seat = resolveEffectiveSeat(config, options.role, credentials);
+  const invocation = options.host === void 0 ? void 0 : { host: options.host };
+  const seat = resolveEffectiveSeat(config, options.role, credentials, invocation);
   const env = {
     ...await createSummonEnv({
       role: options.role,
@@ -263,6 +264,38 @@ async function summonPublicRole(options) {
     ...stderr === void 0 || stderr === "" ? {} : { stderr }
   };
 }
+async function parentInvocationHost(sourceRunDirectory) {
+  const { readFile } = await import("node:fs/promises");
+  const path = join(sourceRunDirectory, "invocation.json");
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    const code = error instanceof Error && "code" in error ? error.code : void 0;
+    throw new Error(
+      `parent invocation.json required for gate source run at ${path}: ${code ?? (error instanceof Error ? error.message : String(error))}`,
+      { cause: error }
+    );
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    throw new Error(
+      `parent invocation.json unreadable at ${path}: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
+    );
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`parent invocation.json has non-object shape at ${path}`);
+  }
+  const host = raw.host;
+  if (host === void 0) return void 0;
+  if (typeof host !== "string" || host.trim() === "") {
+    throw new Error(`parent invocation.json host must be a non-empty string at ${path}`);
+  }
+  return host;
+}
 async function summonGateOfficer(options) {
   let home = options.home;
   if (home === void 0) {
@@ -276,6 +309,7 @@ async function summonGateOfficer(options) {
       submission: options.submission
     });
   }
+  const parentHost = await parentInvocationHost(options.sourceRunDirectory);
   const common = {
     cwd: options.cwd,
     ...home === void 0 ? {} : { home },
@@ -284,6 +318,7 @@ async function summonGateOfficer(options) {
     ...options.signal === void 0 ? {} : { signal: options.signal },
     ...options.reask === void 0 ? {} : { reviewReask: options.reask },
     ...gateReviewInstruction === void 0 ? {} : { gateReviewInstruction },
+    ...parentHost === void 0 ? {} : { host: parentHost },
     ...options.roleTurnHost === void 0 ? {} : { roleTurnHost: options.roleTurnHost },
     ...options.createRunId === void 0 ? {} : { createRunId: options.createRunId }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.3771",
+  "version": "0.1.3783",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/scripts/build-package.mjs

@@ -114,6 +114,33 @@ export async function buildAcpProductionHost(
   );
 }
 
+/**
+ * Deferred generic headless production host artifact (#645). Same peer-free
+ * selection face as ACP: loaded only when a headless description-table row is
+ * selected.
+ */
+export async function buildHeadlessProductionHost(
+  outfile = "dist/headless-host/production-host.js",
+) {
+  await mkdir(dirname(outfile), { recursive: true });
+  await build({
+    entryPoints: ["src/headless-host/production-host.ts"],
+    outfile,
+    format: "esm",
+    platform: "node",
+    target: "node20",
+    bundle: true,
+    packages: "external",
+    logLevel: "silent",
+  });
+  // Shared envelope resolves ./mcp-relay.mjs from import.meta.url of the bundle
+  // (#645 headless reuses the ACP relay for AK tools under --mcp-config).
+  await copyFile(
+    resolve("src/acp-host/mcp-relay.mjs"),
+    join(dirname(outfile), "mcp-relay.mjs"),
+  );
+}
+
 export async function buildPackageArtifacts() {
   await build({
     entryPoints: entries.map((name) => `src/${name}.ts`),
@@ -139,6 +166,7 @@ export async function buildPackageArtifacts() {
   }
   await buildPublicAkRoleBin();
   await buildAcpProductionHost();
+  await buildHeadlessProductionHost();
 }
 
 const isMain =

package/src/acp-host/role-envelope.ts

@@ -15,7 +15,7 @@ import type {
   RoleTurnKnownFailure,
   RoleTurnRequest,
 } from "../host-contracts.ts";
-import { packagedRoleInputFlag, packagedRolePhaseFlag } from "../packaged-role-registry.ts";
+import { packagedRoleInputFlag, packagedRoleOutputTool, packagedRolePhaseFlag } from "../packaged-role-registry.ts";
 import { stripSkillFrontmatter } from "../package-resources/method-skill.ts";
 import {
   createRoleRuntimeExtension,
@@ -131,10 +131,33 @@ export function createComposedAcpRoleTurnHost(
   });
 }
 
+/** JSON Schema draft-07 document for host-native `--json-schema` (headless). */
+export function terminatingToolJsonSchema(parameters: unknown): Readonly<Record<string, unknown>> {
+  const cloned = JSON.parse(JSON.stringify(parameters)) as Record<string, unknown>;
+  // $schema last so a newer declaration on the tool parameters cannot override draft-07.
+  return Object.freeze({
+    ...cloned,
+    $schema: "http://json-schema.org/draft-07/schema#",
+  });
+}
+
 export async function prepareAcpRoleEnvelope(options: {
   readonly request: RoleTurnRequest;
   readonly dependencies: RoleRuntimeDependencies;
+  /**
+   * MCP unix socket path for the protocol-relay child. Always required — AK tools
+   * ride this single MCP path; headless structured_output reuses the same
+   * terminating-tool ledger path without listing the terminating tool on MCP.
+   */
   readonly socketPath: string;
+  /**
+   * Whether MCP `tools/list` advertises the role terminating tool.
+   * ACP keeps it listed (session-tool receipt). Headless hides it so the host
+   * native `--json-schema` / structured_output is the sole schema channel
+   * (#750 submission-tool-is-schema-channel) and empty MCP probes cannot
+   * pre-empt a later structured_output.
+   */
+  readonly listTerminatingToolOnMcp?: boolean;
   /**
    * Durable principal session path (header layout only).
    * Production passes DurablePrincipalAuthority.decode(principal).sessionFile so
@@ -143,6 +166,14 @@ export async function prepareAcpRoleEnvelope(options: {
   readonly sessionFile?: string;
 }): Promise<AcpPreparedTurn> {
   const { request } = options;
+  if (options.socketPath === "") {
+    throw new Error("prepareAcpRoleEnvelope requires socketPath");
+  }
+  const listTerminatingToolOnMcp = options.listTerminatingToolOnMcp !== false;
+  const earlyTerminatingTool = packagedRoleOutputTool(request.activation.role);
+  if (earlyTerminatingTool === undefined) {
+    throw new Error(`role has no terminating tool: ${request.activation.role}`);
+  }
   const flags = projectAcpActivationFlags(request);
   const tools = new Map<string, HostToolDefinition>();
   const handlers = new Map<string, Handler[]>();
@@ -403,6 +434,87 @@ export async function prepareAcpRoleEnvelope(options: {
     await emit("tool_execution_end", { toolCallId, toolName, isError: projected.isError });
     return projected;
   }
+  /**
+   * Shared terminating/support tool path for MCP relay and headless structured_output.
+   * Books the call, runs execute, projects tool_result; does not emit turn_end (closeRound).
+   */
+  async function invokeAkTool(name: string, args: unknown): Promise<{
+    content: ContentPart[];
+    isError: boolean;
+    blocked?: true;
+  }> {
+    const tool = tools.get(name);
+    if (tool === undefined) throw new Error(`Unknown AK tool: ${name}`);
+    const toolCallId = randomUUID();
+    calls.push({ toolCallId, toolName: name });
+    // First-record-then-audit: book the tool-call leaf in memory before execute so
+    // judge/doctor subject gates see the candidate on parent session books.
+    sessionEntries.push({
+      type: "message",
+      message: {
+        role: "assistant" as const,
+        content: [{
+          type: "toolCall",
+          id: toolCallId,
+          name,
+          arguments: args ?? {},
+        }],
+      },
+    });
+    try {
+      await emit("tool_execution_start", { toolCallId, toolName: name });
+      const blocked = (await emit("tool_call", { toolCallId, toolName: name, input: (args ?? {}) as Record<string, unknown> }))
+        .some((value) => typeof value === "object" && value !== null && "block" in value && value.block === true);
+      if (blocked) {
+        // Lawful seatbelt/block stays bare rejection — not infrastructure (#593 r3).
+        return { content: [{ type: "text", text: `AK tool blocked: ${name}` }], isError: true, blocked: true };
+      }
+    } catch (error) {
+      // Pre-execution emit failure shares the non-correctable infra pathway (#593 r3).
+      const declared = declareRoundInfrastructureFailure(error);
+      try {
+        const projected = await projectToolResult(toolCallId, name, {
+          content: declared.content,
+          details: declared.details,
+          isError: true,
+        });
+        return { content: projected.content, isError: true };
+      } catch {
+        return { content: declared.content, isError: true };
+      }
+    }
+    try {
+      const result = await tool.execute(toolCallId, (args ?? {}) as never, undefined, undefined, context);
+      const projected = await projectToolResult(toolCallId, name, {
+        content: result.content,
+        details: result.details,
+        isError: false,
+      });
+      // Candidate only: seal waits for closeRound after the host round boundary.
+      return { content: projected.content, isError: projected.isError };
+    } catch (error) {
+      let content: ContentPart[];
+      let details: Record<string, unknown>;
+      if (isCorrectableExecuteError(error)) {
+        const projected = projectCorrectableExecuteRejection(error);
+        content = [{ type: "text", text: projected.diagnostic }];
+        details = projected.details;
+      } else {
+        // Slot-before-abort; projectToolResult may still project durable details.
+        ({ content, details } = declareRoundInfrastructureFailure(error));
+      }
+      // The shared envelope's tool_result handler is the sole classifier:
+      // it projects either the structured submission non-pass (correctable
+      // rejection) or the typed infrastructure fact onto the reply.
+      const projected = await projectToolResult(toolCallId, name, {
+        content,
+        details,
+        isError: true,
+      });
+      return { content: projected.content, isError: projected.isError };
+    }
+  }
+
   function reply(socket: Socket, id: number, result?: unknown, error?: unknown): void {
     const rpcError = error instanceof Error
       ? { code: "ak-relay-failure", name: error.name, message: error.message }
@@ -424,7 +536,9 @@ export async function prepareAcpRoleEnvelope(options: {
           if (rpc.token !== token) { reply(socket, rpc.id, undefined, "unauthorized relay"); return; }
           try {
             if (rpc.method === "tools/list") {
-              reply(socket, rpc.id, { tools: [...tools.values()].map((tool) => {
+              const listed = [...tools.values()].filter((tool) =>
+                listTerminatingToolOnMcp || tool.name !== earlyTerminatingTool);
+              reply(socket, rpc.id, { tools: listed.map((tool) => {
                 return { name: tool.name, description: tool.description, inputSchema: tool.parameters };
               }) });
               return;
@@ -433,95 +547,24 @@ export async function prepareAcpRoleEnvelope(options: {
             const params = rpc.params as ToolCallParams | undefined;
             const name = params?.name;
             if (typeof name !== "string") throw new Error("MCP tool name is missing");
-            const tool = tools.get(name);
-            if (tool === undefined) throw new Error(`Unknown AK tool: ${name}`);
-            const toolCallId = randomUUID();
-            calls.push({ toolCallId, toolName: name });
-            // First-record-then-audit: book the tool-call leaf in memory before execute so
-            // judge/doctor subject gates see the candidate on parent session books.
-            {
-              const message = {
-                role: "assistant" as const,
-                content: [{
-                  type: "toolCall",
-                  id: toolCallId,
-                  name,
-                  arguments: params?.arguments ?? {},
-                }],
-              };
-              sessionEntries.push({ type: "message", message });
+            // Headless schema channel owns the terminating receipt — refuse MCP
+            // terminating calls so an empty probe cannot book a non-sealable candidate.
+            if (!listTerminatingToolOnMcp && name === earlyTerminatingTool) {
+              throw new Error(`terminating tool ${name} is schema-channel only on this host`);
             }
-            try {
-              await emit("tool_execution_start", { toolCallId, toolName: name });
-              const blocked = (await emit("tool_call", { toolCallId, toolName: name, input: params?.arguments ?? {} }))
-                .some((value) => typeof value === "object" && value !== null && "block" in value && value.block === true);
-              if (blocked) {
-                // Lawful seatbelt/block stays bare RPC rejection — not infrastructure (#593 r3).
-                reply(socket, rpc.id, undefined, new Error(`AK tool blocked: ${name}`));
-                return;
-              }
-            } catch (error) {
-              // Pre-execution emit failure (e.g. observation writer) shares the same
-              // non-correctable infra pathway as execute throws (#593 r3).
-              const declared = declareRoundInfrastructureFailure(error);
-              try {
-                const projected = await projectToolResult(toolCallId, name, {
-                  content: declared.content,
-                  details: declared.details,
-                  isError: true,
-                });
-                reply(socket, rpc.id, {
-                  content: projected.content,
-                  isError: true,
-                });
-              } catch {
-                // Slot already filled; durable projection may have partially failed.
-                reply(socket, rpc.id, {
-                  content: declared.content,
-                  isError: true,
-                });
-              }
+            const outcome = await invokeAkTool(name, params?.arguments ?? {});
+            if (outcome.blocked === true) {
+              reply(socket, rpc.id, undefined, new Error(outcome.content.map((p) => p.type === "text" ? p.text : "").join("")));
               return;
             }
-            try {
-              const result = await tool.execute(toolCallId, (params?.arguments ?? {}) as never, undefined, undefined, context);
-              const projected = await projectToolResult(toolCallId, name, {
-                content: result.content,
-                details: result.details,
-                isError: false,
-              });
-              // Candidate only: do not emit turn_end here. Seal waits for the typed ACP
-              // round boundary (closeRound after session/prompt), so delayed siblings stay
-              // in the same round instead of becoming silent post-seal anomalies.
-              reply(socket, rpc.id, { content: projected.content, ...(projected.isError ? { isError: true } : {}) });
-            } catch (error) {
-              let content: ContentPart[];
-              let details: Record<string, unknown>;
-              if (isCorrectableExecuteError(error)) {
-                const projected = projectCorrectableExecuteRejection(error);
-                content = [{ type: "text", text: projected.diagnostic }];
-                details = projected.details;
-              } else {
-                // Slot-before-abort; projectToolResult may still project durable details.
-                ({ content, details } = declareRoundInfrastructureFailure(error));
-              }
-              // The shared envelope's tool_result handler is the sole classifier:
-              // it projects either the structured submission non-pass (correctable
-              // rejection) or the typed infrastructure fact onto the reply.
-              const projected = await projectToolResult(toolCallId, name, {
-                content,
-                details,
-                isError: true,
-              });
-              reply(socket, rpc.id, { content: projected.content, ...(projected.isError ? { isError: true } : {}) });
-            }
+            reply(socket, rpc.id, { content: outcome.content, ...(outcome.isError ? { isError: true } : {}) });
           } catch (error) { reply(socket, rpc.id, undefined, error); }
         })();
       }
     });
   }
-  await listen(server, options.socketPath);
   const relay = fileURLToPath(new URL("./mcp-relay.mjs", import.meta.url));
+  await listen(server, options.socketPath);
   let disposed = false;
   // Tools execute in this process (relay is protocol-only). Mirror Pi's child-env
   // AK_ROLE_RUN_DIR / AK_ROLE_COURT_ATTEMPT injection onto the parent so ledger
@@ -552,8 +595,6 @@ export async function prepareAcpRoleEnvelope(options: {
     } catch (error) {
       cleanupFailures.push(error);
     }
-    // Server closure is unconditional: a shutdown-handler failure must not leave
-    // the listening MCP server keeping the completed invocation alive.
     try {
       const closeAll = (server as unknown as { closeAllConnections?: () => void }).closeAllConnections;
       if (typeof closeAll === "function") closeAll.call(server);
@@ -571,6 +612,14 @@ export async function prepareAcpRoleEnvelope(options: {
     }
   };
 
+  const terminatingToolName: string = earlyTerminatingTool;
+  async function ingestStructuredOutput(params: unknown): Promise<void> {
+    // MCP path may already have invoked the terminating tool this round; skip the
+    // duplicate so structured_output + tool-call does not arm non-sole.
+    if (calls.some((call) => call.toolName === terminatingToolName)) return;
+    await invokeAkTool(terminatingToolName, params ?? {});
+  }
+
   const closeRound: AcpPreparedTurn["closeRound"] = async () => {
     // Typed round boundary: hand the complete call list to the shared ledger once.
     if (calls.length > 0) {
@@ -654,6 +703,11 @@ export async function prepareAcpRoleEnvelope(options: {
     else process.env.AK_ROLE_COURT_ATTEMPT = request.courtAttemptId;
     runDirInjected = true;
 
+    const terminating = tools.get(terminatingToolName);
+    if (terminating === undefined) {
+      throw new Error(`terminating tool not registered after activation: ${terminatingToolName}`);
+    }
+    const jsonSchema = terminatingToolJsonSchema(terminating.parameters);
     return {
       mcpServers: [{
         name: `ak-${request.activation.role}`,
@@ -669,6 +723,9 @@ export async function prepareAcpRoleEnvelope(options: {
       abortSignal: hostAbort.signal,
       closeRound,
       dispose,
+      jsonSchema,
+      terminatingToolName,
+      ingestStructuredOutput,
     };
   } catch (error) {
     // listen already succeeded; dispose is not yet caller-owned. Release the

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

@@ -43,6 +43,18 @@ export type AcpPreparedTurn = Readonly<{
     | { readonly accepted: false; readonly failure: RoleTurnKnownFailure }
   >;
   dispose?(): Promise<void>;
+  /**
+   * Headless CLI family (#645): role terminating-tool schema for host-native
+   * `--json-schema`. Present for every prepared turn; ACP ignores it.
+   */
+  jsonSchema: Readonly<Record<string, unknown>>;
+  /** Terminating tool name whose schema is `jsonSchema`. */
+  terminatingToolName: string;
+  /**
+   * Headless CLI family: feed host-native `structured_output` through the same
+   * terminating-tool path the MCP relay uses (ledger + gates). ACP ignores it.
+   */
+  ingestStructuredOutput(params: unknown): Promise<void>;
 }>;
 
 /** Fold structured system-prompt authority into the provider-visible ACP override. */

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);
+    },
+  };
+}