@akagilnc/pi-workflow-roles 0.1.5483 → 0.1.5571

package/src/factory-board.ts

@@ -16,9 +16,7 @@
  * output path outside every ledger and declares the bound; one-shot write does
  * not advertise refresh. Snapshot bindings stay fixed; each tick re-reads ledgers.
  */
-import { randomUUID } from "node:crypto";
-import { lstat, mkdir, realpath, rename, rm, writeFile } from "node:fs/promises";
-import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { resolve } from "node:path";
 
 import { packagedBoardPlacement } from "./packaged-role-registry.ts";
 import {
@@ -29,6 +27,8 @@ import {
 } from "./human-format.ts";
 import {
   DEFAULT_REFRESH_BOUNDARY_SECONDS,
+  assertOutputOutsideLedgers,
+  writePageOutsideLedgers,
   buildTicketTrajectoryBookIndex,
   loadTicketTrajectoryRuns,
   loadUnboundTrajectoryRuns,
@@ -41,7 +41,7 @@ import {
 } from "./ticket-trajectory.ts";
 import type { BoardSnapshot, SnapshotTicket, TicketIssueState } from "./ticket-snapshot.ts";
 
-import { isRecord, isMissingPathError } from "./unknown-value.ts";
+import { isRecord } from "./unknown-value.ts";
 
 /** Unaccepted latest-run mtime bands (page-visible thresholds). */
 export const UNACCEPTED_FLYING_MS = 2 * 60 * 1000;
@@ -322,11 +322,6 @@ function attr(value: string): string {
   return escapeHtml(value);
 }
 
-function isPathInside(parent: string, child: string): boolean {
-  const rel = relative(parent, child);
-  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !rel.startsWith(".."));
-}
-
 function activeBlockedBy(ticket: SnapshotTicket): number[] {
   if (ticket.state === "closed") return [];
   return ticket.blockedBy
@@ -1654,76 +1649,7 @@ ${boardPageScript()}
 `;
 }
 
-async function assertOutputOutsideAllLedgers(
-  books: readonly FactoryBoardBook[],
-  outputPath: string,
-): Promise<{ ledgerRoots: string[]; outputAbsolute: string }> {
-  const outputAbsolute = resolve(outputPath);
-  const ledgerRoots: string[] = [];
-  for (const book of books) {
-    const ledgerResolved = resolve(book.ledgerDir);
-    let ledgerRoot: string;
-    try {
-      ledgerRoot = await realpath(ledgerResolved);
-    } catch (error) {
-      if (!isMissingPathError(error)) throw error;
-      ledgerRoot = ledgerResolved;
-    }
-    ledgerRoots.push(ledgerRoot);
-
-    const missingTail: string[] = [];
-    let cursor = outputAbsolute;
-    for (;;) {
-      try {
-        await lstat(cursor);
-        break;
-      } catch (error) {
-        if (!isMissingPathError(error)) throw error;
-        const parent = dirname(cursor);
-        if (parent === cursor) break;
-        missingTail.push(basename(cursor));
-        cursor = parent;
-      }
-    }
-    let realPrefix: string;
-    try {
-      realPrefix = await realpath(cursor);
-    } catch (error) {
-      if (!isMissingPathError(error)) throw error;
-      realPrefix = resolve(cursor);
-    }
-    const prospectiveReal =
-      missingTail.length === 0 ? realPrefix : resolve(realPrefix, ...missingTail.reverse());
-    if (
-      isPathInside(ledgerRoot, prospectiveReal) ||
-      isPathInside(ledgerRoot, realPrefix) ||
-      isPathInside(ledgerRoot, outputAbsolute)
-    ) {
-      throw new Error("factory board outputPath must be outside every ledger directory");
-    }
-  }
-  return { ledgerRoots, outputAbsolute };
-}
-
-async function writeHtmlAtomically(outputAbsolute: string, html: string, ledgerRoots: string[]): Promise<string> {
-  const parent = dirname(outputAbsolute);
-  await mkdir(parent, { recursive: true });
-  const parentReal = await realpath(parent);
-  for (const root of ledgerRoots) {
-    if (isPathInside(root, parentReal) || isPathInside(root, resolve(parentReal, basename(outputAbsolute)))) {
-      throw new Error("factory board outputPath must be outside every ledger directory");
-    }
-  }
-  const temporary = join(parent, `.factory-board-${randomUUID()}.html.tmp`);
-  try {
-    await writeFile(temporary, html, "utf8");
-    await rename(temporary, outputAbsolute);
-  } catch (error) {
-    await rm(temporary, { force: true }).catch(() => undefined);
-    throw error;
-  }
-  return realpath(outputAbsolute);
-}
+const BOARD_OUTPUT_REFUSAL = "factory board outputPath must be outside every ledger directory";
 
 export async function writeFactoryBoardPage(input: {
   books: readonly FactoryBoardBook[];
@@ -1732,7 +1658,11 @@ export async function writeFactoryBoardPage(input: {
   outputPath: string;
   refreshBoundarySeconds?: number;
 }): Promise<{ outputPath: string; html: string }> {
-  const gate = await assertOutputOutsideAllLedgers(input.books, input.outputPath);
+  const gate = await assertOutputOutsideLedgers(
+    input.books.map((book) => book.ledgerDir),
+    input.outputPath,
+    BOARD_OUTPUT_REFUSAL,
+  );
   const html = await renderFactoryBoardHtml(
     input.books,
     input.view,
@@ -1741,7 +1671,12 @@ export async function writeFactoryBoardPage(input: {
       ? { refreshBoundarySeconds: input.refreshBoundarySeconds }
       : undefined,
   );
-  const outputPath = await writeHtmlAtomically(gate.outputAbsolute, html, gate.ledgerRoots);
+  const outputPath = await writePageOutsideLedgers(
+    gate.ledgerRoots,
+    gate.outputAbsolute,
+    html,
+    BOARD_OUTPUT_REFUSAL,
+  );
   return { outputPath, html };
 }
 

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

@@ -36,10 +36,7 @@ export function createProductionHeadlessRoleTurnHost(
   options: ProductionHeadlessHostOptions,
 ): RoleTurnHost {
   const { packageRoot, principalAuthority, description, hostName } = options;
-  const sessionIdentity = createSessionIdentityAuthority(
-    principalAuthority,
-    description.sessionBindingFile,
-  );
+  const sessionIdentity = createSessionIdentityAuthority(principalAuthority, hostName);
   const roleRuntimeDependencies = createRoleRuntimeDependencies(packageRoot);
 
   const innerFor = (operatorHome: string): RoleTurnHost =>

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

@@ -6,10 +6,12 @@
 import { spawn, spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
-import { writeFile } from "node:fs/promises";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 
 import type { RoleTurnHost, RoleTurnRequest, RoleTurnResult } from "../host-contracts.ts";
+import { sessionDirectoryOf } from "../role-run-placement.ts";
 import {
   createSerializedRoleTurnHost,
   driveExternalRoleTurnRounds,
@@ -17,6 +19,7 @@ import {
   externalHostFailure as failure,
   hostAbortedError,
   isHostAbortedError,
+  recordTurnDelivery,
 } from "../external-host-turn-loop.ts";
 import { describeErrorIdentity } from "../public-cli/run-lifecycle.ts";
 import { projectThrownFailureLeaf, retainPackageFault } from "../public-cli/settlement.ts";
@@ -461,31 +464,51 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
 
       // 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");
+      // CLI start-up inputs (system prompt / schema / MCP config files) are not
+      // dossier: they live in a throwaway directory, and what was delivered is
+      // recorded once per actual start as a history.jsonl `turn-delivery` row.
+      const sessionParent = config.sessionIdentity.resolveSessionFile(request.principal);
+      const inputsDirectory = await mkdtemp(join(tmpdir(), "ak-role-headless-"));
+      const systemPromptPath = join(inputsDirectory, "system-prompt.txt");
       let mcpConfigPath: string | undefined;
       let outputSchemaPath: string | undefined;
-      if (codex) {
-        // #1148: Codex --output-schema requires a native strict transport schema.
-        // Project from the unique open declaration; do not alter package receipt rules.
-        if (prepared.terminatingToolName !== NAVIGATOR_OUTPUT_TOOL_NAME) {
-          outputSchemaPath = join(request.runDirectory, "headless-output-schema.json");
+      let startedWithSchema: unknown;
+      // A setup failure after mkdtemp must not leave the prompt material behind.
+      try {
+        await writeFile(systemPromptPath, systemPrompt, "utf8");
+        let deliveredSchema: unknown;
+        if (codex) {
+          // #1148: Codex --output-schema requires a native strict transport schema.
+          // Project from the unique open declaration; do not alter package receipt rules.
+          if (prepared.terminatingToolName !== NAVIGATOR_OUTPUT_TOOL_NAME) {
+            outputSchemaPath = join(inputsDirectory, "output-schema.json");
+            deliveredSchema = closeJsonSchemaForCodex(prepared.jsonSchema);
+            await writeFile(outputSchemaPath, `${JSON.stringify(deliveredSchema, null, 2)}\n`, "utf8");
+          }
+        } else {
+          mcpConfigPath = join(inputsDirectory, "mcp-config.json");
           await writeFile(
-            outputSchemaPath,
-            `${JSON.stringify(closeJsonSchemaForCodex(prepared.jsonSchema), null, 2)}\n`,
+            mcpConfigPath,
+            `${JSON.stringify(headlessMcpConfigDocument(prepared.mcpServers), null, 2)}\n`,
             "utf8",
           );
+          // #959: navigator prose exit — no closed JSON schema on claude either.
+          if (prepared.terminatingToolName !== NAVIGATOR_OUTPUT_TOOL_NAME) deliveredSchema = prepared.jsonSchema;
         }
-      } else {
-        mcpConfigPath = join(request.runDirectory, "headless-mcp-config.json");
-        await writeFile(
-          mcpConfigPath,
-          `${JSON.stringify(headlessMcpConfigDocument(prepared.mcpServers), null, 2)}\n`,
-          "utf8",
-        );
+        startedWithSchema = deliveredSchema;
+      } catch (setupError) {
+        try {
+          await rm(inputsDirectory, { recursive: true, force: true });
+        } catch (cleanupError) {
+          await retainPackageFault({
+            runDirectory: request.runDirectory,
+            diagnostic: `headless turn inputs cleanup failed beside setup failure: ${describeErrorIdentity(cleanupError)}`,
+            error: cleanupError,
+          });
+        }
+        throw setupError;
       }
 
-      const sessionParent = config.sessionIdentity.resolveSessionFile(request.principal);
       let exitedSessionId: string | undefined;
       try {
       outcome = await driveExternalRoleTurnRounds(prepared, request, {
@@ -534,6 +557,11 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
             }) !== undefined;
           }
 
+          // What this CLI start was given: one history record per start.
+          await recordTurnDelivery(request.runDirectory, {
+            systemPrompt,
+            ...(startedWithSchema === undefined ? {} : { outputSchema: startedWithSchema }),
+          }, "headless-host");
           let spawned: HeadlessSpawnResult;
           try {
             spawned = await spawnHeadlessTurn({
@@ -714,12 +742,19 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
         },
       });
       } finally {
+        try {
+          await rm(inputsDirectory, { recursive: true, force: true });
+        } catch (error) {
+          await retainPackageFault({
+            runDirectory: request.runDirectory,
+            diagnostic: `headless turn inputs cleanup failed beside host terminal: ${describeErrorIdentity(error)}`,
+            error,
+          });
+        }
         try {
           if (exitedSessionId !== undefined && exitedSessionId !== "") copyAndRecordHostDossier({
             host: config.hostName, sessionId: exitedSessionId, cwd: request.cwd,
-            sessionDirectory: join(request.runDirectory, "session"), sessionParent,
-            continuation: request.continuation,
-            ...(request.model !== undefined ? { model: request.model } : {}),
+            sessionDirectory: sessionDirectoryOf(request.runDirectory), sessionParent,
             ...(request.home !== undefined ? { home: request.home } : {}),
           });
         } catch (error) {

package/src/host-descriptions.ts

@@ -15,8 +15,6 @@ import type { HeadlessHostDescription } from "./headless-host/description.ts";
 export type HostIdentityDescription = Readonly<{
   /** Binary path segments relative to the operator home. */
   binaryFromHome: readonly string[];
-  /** Durable host session binding filename beside the session principal. */
-  sessionBindingFile: string;
 }>;
 
 /** Resolve a host description's agent binary under the operator home. */
@@ -45,7 +43,6 @@ export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = O
     }),
     modelPassing: "set_model",
     setModelId: "bare",
-    sessionBindingFile: "grok-acp-session.json",
   }),
   /**
    * Operator home `~/.hermes`, native session/load resume, `acp` subcommand.
@@ -63,7 +60,6 @@ export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = O
     }),
     modelPassing: "set_model",
     setModelId: "provider:model",
-    sessionBindingFile: "hermes-acp-session.json",
     seatProfileSoul: Object.freeze({
       flag: "-p",
       namePrefix: "ak-",
@@ -84,7 +80,6 @@ export const HEADLESS_HOST_DESCRIPTIONS: Readonly<Record<string, HeadlessHostDes
   "claude": Object.freeze({
     protocol: "claude-print",
     binaryFromHome: Object.freeze([".local", "bin", "claude"]),
-    sessionBindingFile: "claude-headless-session.json",
     fixedArgs: Object.freeze([
       // Live NDJSON events → sitian host-session records (#811); last line is the result receipt.
       "--output-format", "stream-json",
@@ -109,7 +104,6 @@ export const HEADLESS_HOST_DESCRIPTIONS: Readonly<Record<string, HeadlessHostDes
   "codex": Object.freeze({
     protocol: "codex-exec",
     binaryFromHome: Object.freeze([".local", "bin", "codex"]),
-    sessionBindingFile: "codex-headless-session.json",
   }),
 });