@akagilnc/pi-workflow-roles 0.1.4586 → 0.1.4631

package/src/activation-ledger.ts

@@ -1,25 +1,8 @@
-import {
-  constants,
-  closeSync,
-  fstatSync,
-  openSync,
-  writeSync,
-} from "node:fs";
-import { dirname, isAbsolute, resolve } from "node:path";
-
-import type { ActivationSessionPointer } from "./activation-ledger-session.ts";
-import {
-  ActivationLedgerError,
-  activationWaitingLedgerPath,
-  assertLedgerFileInsideHome,
-  ensureRealDirectoryTree,
-  errorText,
-} from "./activation-ledger-topology.ts";
-
-/** Private open flags: O_NOFOLLOW closes the lstat→open TOCTOU window. */
-const ACTIVATION_LEDGER_APPEND_OPEN_FLAGS =
-  constants.O_APPEND | constants.O_CREAT | constants.O_WRONLY | constants.O_NOFOLLOW;
-
+/**
+ * Activation ledger surface: durable session principal + book/home topology.
+ * #855: two-face waiting.jsonl reconciliation deleted — this module no longer
+ * appends accepted-activation facts or own a waiting path.
+ */
 export {
   ActivationGitRepositoryRequiredError,
   resolveBookKeyFromGit,
@@ -33,219 +16,5 @@ export {
 export {
   ActivationLedgerError,
   activationBookDirectory,
-  activationWaitingLedgerPath,
   resolveActivationLedgerHome,
 } from "./activation-ledger-topology.ts";
-
-/** Caller-preassigned correlation id, or an explicit absent identity (never empty string). */
-export type ActivationCorrelationIdentity =
-  | { readonly kind: "caller"; readonly id: string }
-  | { readonly kind: "absent" };
-
-export const ACCEPTED_ACTIVATION_EVENT = "accepted-activation" as const;
-
-/**
- * Package-owned index-only top-level keys for accepted-activation facts (ADR 0049).
- * Sole machine key contract: projection and tests consume this descriptor — not prose markers.
- */
-export const ACCEPTED_ACTIVATION_FACT_KEYS = Object.freeze([
-  "event",
-  "role",
-  "observedAt",
-  "bookKey",
-  "session",
-  "correlation",
-] as const);
-
-export type AcceptedActivationFactKey = (typeof ACCEPTED_ACTIVATION_FACT_KEYS)[number];
-
-/**
- * Closed activation fact: index fields only (ADR 0049).
- * No prompt, transcript, argv, excerpt, or other content.
- */
-export type AcceptedActivationFact = {
-  readonly event: typeof ACCEPTED_ACTIVATION_EVENT;
-  readonly role: string;
-  readonly observedAt: string;
-  readonly bookKey: string;
-  readonly session: ActivationSessionPointer;
-  readonly correlation: ActivationCorrelationIdentity;
-};
-
-// Keys tuple ↔ fact type must stay exact (compile fail on drift; no second field list).
-type ExactKeyMatch<T, K extends PropertyKey> =
-  Exclude<keyof T, K> | Exclude<K, keyof T> extends never ? true : never;
-const _acceptedActivationFactKeysMatch: ExactKeyMatch<
-  AcceptedActivationFact,
-  AcceptedActivationFactKey
-> = true;
-void _acceptedActivationFactKeysMatch;
-
-/** Trusted typed inputs for building the closed fact (canonical fact minus event discriminant). */
-export type AcceptedActivationFactInput = Omit<AcceptedActivationFact, "event">;
-
-/**
- * Host correlation channel (not a CLI flag): a non-blank AK_CORRELATION_ID carries
- * the caller id verbatim; missing/blank/whitespace-only yields the typed absent identity.
- */
-export function correlationIdentityFromEnv(
-  env: NodeJS.ProcessEnv = process.env,
-): ActivationCorrelationIdentity {
-  const raw = env.AK_CORRELATION_ID;
-  if (typeof raw === "string" && raw.trim().length > 0) {
-    return { kind: "caller", id: raw };
-  }
-  return { kind: "absent" };
-}
-
-/**
- * Descriptor-driven top-level pick: only ACCEPTED_ACTIVATION_FACT_KEYS leave this boundary.
- * Nested session/correlation are rebuilt closed before the pick (ADR 0049: first-phase ledger holds zero content bytes by construction).
- */
-function projectAcceptedActivationFact(
-  input: AcceptedActivationFactInput,
-): AcceptedActivationFact {
-  const closed: AcceptedActivationFact = {
-    event: ACCEPTED_ACTIVATION_EVENT,
-    role: input.role,
-    observedAt: input.observedAt,
-    bookKey: input.bookKey,
-    session: { kind: "session-file", path: input.session.path },
-    correlation: input.correlation.kind === "caller"
-      ? { kind: "caller", id: input.correlation.id }
-      : { kind: "absent" },
-  };
-  // Descriptor is the sole top-level emission contract (typed pick; no content keys).
-  return Object.fromEntries(
-    ACCEPTED_ACTIVATION_FACT_KEYS.map((key) => [key, closed[key]]),
-  ) as AcceptedActivationFact;
-}
-
-/** Construct the closed fact from trusted typed inputs only (descriptor projection — no content keys). */
-export function buildAcceptedActivationFact(input: AcceptedActivationFactInput): AcceptedActivationFact {
-  return projectAcceptedActivationFact(input);
-}
-
-/** Serialize only the closed index fields (descriptor projection — no content keys). */
-export function serializeAcceptedActivationFact(fact: AcceptedActivationFact): string {
-  return `${JSON.stringify(projectAcceptedActivationFact(fact))}\n`;
-}
-
-/**
- * Bare O_APPEND write of one complete line under an absolute ledger home.
- * Private helper: production-bound to writeSync; owns open/write/close honesty only.
- * Close failure cannot mask open/write; simultaneous close is nested evidence.
- */
-function appendActivationLedgerLine(
-  ledgerPath: string,
-  line: Uint8Array,
-  options: { ledgerHome: string },
-): void {
-  if (!isAbsolute(options.ledgerHome)) {
-    throw new ActivationLedgerError(
-      `activation ledger home must be absolute: ${options.ledgerHome}`,
-    );
-  }
-  const resolvedLedger = resolve(ledgerPath);
-  const resolvedHome = resolve(options.ledgerHome);
-  const parent = dirname(resolvedLedger);
-  ensureRealDirectoryTree(resolvedHome, parent);
-  assertLedgerFileInsideHome(resolvedLedger, resolvedHome);
-
-  // Fail-closed guard (same shape as PR #418's publication seam): on platforms
-  // without O_NOFOLLOW (e.g. Windows, nodejs/node#41590) the JS bitwise-or in
-  // ACTIVATION_LEDGER_APPEND_OPEN_FLAGS would silently drop the flag and the
-  // lstat→open TOCTOU anti-symlink protection would vanish while the comment
-  // above still claims it. Refuse loudly via the existing typed ledger failure
-  // channel instead of appending unprotected; never silently degrade.
-  if (typeof constants.O_NOFOLLOW !== "number") {
-    throw new ActivationLedgerError(
-      "activation ledger append requires O_NOFOLLOW open-flag support (anti-symlink TOCTOU protection must not be silently dropped); refusing to append",
-    );
-  }
-  const bytes = Buffer.isBuffer(line) ? line : Buffer.from(line);
-  let ledgerFd: number | undefined;
-  let primaryFailure: unknown;
-  try {
-    try {
-      ledgerFd = openSync(resolvedLedger, ACTIVATION_LEDGER_APPEND_OPEN_FLAGS, 0o644);
-    } catch (error) {
-      // Native ELOOP/filesystem cause retained; no errno dispatch.
-      throw new ActivationLedgerError(
-        `activation ledger failed to open ledger file (${resolvedLedger}): ${errorText(error)}`,
-        { cause: error },
-      );
-    }
-
-    let opened: ReturnType<typeof fstatSync>;
-    try {
-      opened = fstatSync(ledgerFd);
-    } catch (error) {
-      throw new ActivationLedgerError(
-        `activation ledger failed to fstat ledger file (${resolvedLedger}): ${errorText(error)}`,
-        { cause: error },
-      );
-    }
-    if (!opened.isFile()) {
-      throw new ActivationLedgerError(
-        `activation ledger is not a regular file: ${resolvedLedger}`,
-      );
-    }
-
-    const written = writeSync(ledgerFd, bytes, 0, bytes.length, null);
-    if (written !== bytes.length) {
-      throw new ActivationLedgerError(
-        `activation ledger short write: wrote ${written} of ${bytes.length} bytes to ${resolvedLedger}`,
-      );
-    }
-  } catch (error) {
-    primaryFailure = error;
-  }
-
-  if (ledgerFd !== undefined) {
-    try {
-      closeSync(ledgerFd);
-    } catch (closeFailure) {
-      if (primaryFailure !== undefined) {
-        throw new AggregateError(
-          [primaryFailure, closeFailure],
-          "activation ledger operation and close failed",
-          { cause: primaryFailure },
-        );
-      }
-      throw closeFailure;
-    }
-  }
-
-  if (primaryFailure !== undefined) throw primaryFailure;
-}
-
-/**
- * Append one complete JSONL record with one O_APPEND write of the full record.
- * Shared-ledger contract: concurrent successful append-only producers cannot
- * overwrite one another. A short write is an honest infrastructure failure
- * (ADR 0049) — no non-append rollback/truncate. Close failure cannot mask the
- * primary write cause; simultaneous close evidence is retained.
- */
-export function appendAcceptedActivationFact(
-  ledgerPath: string,
-  fact: AcceptedActivationFact,
-  options: { ledgerHome: string },
-): void {
-  appendActivationLedgerLine(
-    ledgerPath,
-    Buffer.from(serializeAcceptedActivationFact(fact), "utf8"),
-    { ledgerHome: options.ledgerHome },
-  );
-}
-
-export function appendAcceptedActivationToBook(options: {
-  ledgerHome: string;
-  fact: AcceptedActivationFact;
-}): void {
-  appendAcceptedActivationFact(
-    activationWaitingLedgerPath(options.ledgerHome, options.fact.bookKey),
-    options.fact,
-    { ledgerHome: options.ledgerHome },
-  );
-}

package/src/analyst-entry.ts

@@ -22,9 +22,12 @@ import {
 } from "./analyst-cohort.ts";
 import {
   scanAnalystIssueRuns,
+  type AnalystGhostLeg,
   type AnalystReadableRunFacts,
   type AnalystScopedRunScan,
 } from "./analyst-ledger.ts";
+
+export type { AnalystGhostLeg, AnalystGhostLeaseCheck } from "./analyst-ledger.ts";
 import {
   mergeAnalystLibraryIndexRows,
   rowFromIssueMetricsPage,
@@ -173,6 +176,11 @@ export type AnalystIssueModeResult = {
   readonly mode: "issue";
   readonly page: AnalystIssueMetricsPage;
   readonly pagePath: string;
+  /**
+   * #855 live observation: admitted|running runs whose writer lease cannot prove
+   * a live holder. Fresh each query — never cached on the metrics page.
+   */
+  readonly ghostLegs: readonly AnalystGhostLeg[];
 };
 
 export type AnalystSweepModeResult = {
@@ -264,7 +272,16 @@ export async function readOrComputeAnalystIssuePage(
     const raw = await readFile(pagePath, "utf8");
     const page = JSON.parse(raw) as AnalystIssueMetricsPage;
     if (cachedPageMatchesRequestedScope(page, { bookKey, ...input })) {
-      return { mode: "issue", page, pagePath };
+      // #855 ghost legs are live observations — always fresh, never from the page cache.
+      const ghostScan = await scanAnalystIssueRuns({
+        bookKey,
+        ...(issueNumber === undefined ? {} : { ticketNumber: issueNumber }),
+        ...(options?.scanProjectRoot === undefined
+          ? {}
+          : { projectRoot: options.scanProjectRoot }),
+        ...(options?.home === undefined ? {} : { home: options.home }),
+      });
+      return { mode: "issue", page, pagePath, ghostLegs: ghostScan.ghostLegs };
     }
     // Existing page is for a different / absent ticket scope — same kernel recompute.
   } catch (error) {
@@ -364,7 +381,7 @@ async function runAnalystIssueMode(
     ]);
   }
 
-  return { mode: "issue", page, pagePath };
+  return { mode: "issue", page, pagePath, ghostLegs: scan.ghostLegs };
 }
 
 async function runAnalystSweepMode(

package/src/analyst-ledger.ts

@@ -22,6 +22,7 @@ import {
   resolveActivationLedgerHome,
 } from "./activation-ledger-topology.ts";
 import { listBookRunDirectories } from "./role-run-placement.ts";
+import { autopsyWriterLock } from "./public-cli/run-lifecycle.ts";
 import { readRunTicketNumber } from "./run-ticket-number.ts";
 import {
   extractSessionModelSequence,
@@ -87,6 +88,64 @@ async function readExistingRunLifecycleState(
   }
 }
 
+/**
+ * #855 lease check projection for ghost legs — index facts only (ADR 0049).
+ * Does not rename autopsy verdicts into stronger claims than observed.
+ */
+export type AnalystGhostLeaseCheck =
+  | { readonly kind: "holder-dead"; readonly pid: number }
+  | { readonly kind: "no-lease" }
+  | { readonly kind: "unverifiable"; readonly reason: "unreadable" | "unparseable" };
+
+export type AnalystGhostLeg = {
+  readonly runId: string;
+  readonly runState: "admitted" | "running";
+  readonly leaseCheck: AnalystGhostLeaseCheck;
+};
+
+function ghostLeaseCheckFromAutopsy(
+  autopsy: Awaited<ReturnType<typeof autopsyWriterLock>>,
+): AnalystGhostLeaseCheck | undefined {
+  switch (autopsy.verdict) {
+    case "alive":
+      return undefined;
+    case "dead":
+      return { kind: "holder-dead", pid: autopsy.pid };
+    case "absent":
+      return { kind: "no-lease" };
+    case "unknown":
+      return {
+        kind: "unverifiable",
+        reason: autopsy.reason === "unreadable" ? "unreadable" : "unparseable",
+      };
+  }
+}
+
+/**
+ * Classify one admitted|running run against writer lease liveness (#855).
+ * Alive holder → still in-flight (omit). Otherwise → ghost report fact only.
+ */
+async function classifyGhostCandidate(input: {
+  readonly runId: string;
+  readonly runState: "admitted" | "running";
+  readonly runDirectory: string;
+}): Promise<
+  | { readonly kind: "live" }
+  | { readonly kind: "ghost"; readonly leg: AnalystGhostLeg }
+> {
+  const autopsy = await autopsyWriterLock(join(input.runDirectory, "writer.lock"));
+  const leaseCheck = ghostLeaseCheckFromAutopsy(autopsy);
+  if (leaseCheck === undefined) return { kind: "live" };
+  return {
+    kind: "ghost",
+    leg: {
+      runId: input.runId,
+      runState: input.runState,
+      leaseCheck,
+    },
+  };
+}
+
 function parseRunDirectoryName(
   name: string,
 ): { runId: string; role: string } | undefined {
@@ -335,6 +394,8 @@ export type AnalystScopedRunScan = {
   readonly unreadable: readonly AnalystUnreadableRun[];
   /** C4: typed-ticket admits whose projectRoot mechanical key conflicted. */
   readonly scopeConflicts: readonly AnalystScopeConflict[];
+  /** #855: admitted|running runs whose writer lease cannot prove a live holder. */
+  readonly ghostLegs: readonly AnalystGhostLeg[];
 };
 
 async function classifyScopedRun(input: {
@@ -343,9 +404,20 @@ async function classifyScopedRun(input: {
   readonly role: string;
   readonly runDirectory: string;
 }): Promise<
-  | { readonly kind: "readable"; readonly facts: AnalystReadableRunFacts }
-  | { readonly kind: "unreadable"; readonly entry: AnalystUnreadableRun }
+  | {
+      readonly kind: "readable";
+      readonly facts: AnalystReadableRunFacts;
+      /** #855: present terminal still lists ghost when lease cannot prove live. */
+      readonly ghostLeg?: AnalystGhostLeg;
+    }
+  | {
+      readonly kind: "unreadable";
+      readonly entry: AnalystUnreadableRun;
+      /** #855: unreadable terminal still lists ghost when lease cannot prove live. */
+      readonly ghostLeg?: AnalystGhostLeg;
+    }
   | { readonly kind: "live" }
+  | { readonly kind: "ghost"; readonly leg: AnalystGhostLeg }
 > {
   const missingSources: AnalystMissingSource[] = [];
   const reasons: string[] = [];
@@ -434,13 +506,31 @@ async function classifyScopedRun(input: {
 
   // 3) typed terminal artifact — absence is no-receipt only for terminal runs.
   // Live admitted/running/resumable runs (existing run-state) are not dead legs.
+  // #855: writer-lease ghost check is independent of terminal artifact status.
+  // present → still emit metrics; unreadable → still enter missingSources;
+  // admitted|running + non-live lease → still list in ghostLegs (ticket #4).
+  const lifecycle = await readExistingRunLifecycleState(input.runDirectory);
+  let ghostLeg: AnalystGhostLeg | undefined;
+  if (lifecycle === "admitted" || lifecycle === "running") {
+    const ghost = await classifyGhostCandidate({
+      runId: input.runId,
+      runState: lifecycle,
+      runDirectory: input.runDirectory,
+    });
+    if (ghost.kind === "ghost") ghostLeg = ghost.leg;
+  }
+
   try {
     const artifact = await readRunTerminalArtifact(input.runDirectory);
     if (artifact.status === "unreadable") {
       missingSources.push("terminal-artifact");
       reasons.push(`${artifact.file}: ${artifact.reason}`);
     } else if (artifact.status === "absent") {
-      const lifecycle = await readExistingRunLifecycleState(input.runDirectory);
+      if (lifecycle === "admitted" || lifecycle === "running") {
+        // No terminal yet: ghost report only, or live in-flight omit.
+        if (ghostLeg !== undefined) return { kind: "ghost", leg: ghostLeg };
+        return { kind: "live" };
+      }
       if (lifecycle !== undefined && LIVE_RUN_STATES.has(lifecycle)) {
         return { kind: "live" };
       }
@@ -479,6 +569,7 @@ async function classifyScopedRun(input: {
         firstFrameAt,
         lastFrameAt,
       },
+      ...(ghostLeg !== undefined ? { ghostLeg } : {}),
     };
   }
 
@@ -510,6 +601,7 @@ async function classifyScopedRun(input: {
         firstFrameAt: { status: "present", at: frameSpan.startedAt },
         lastFrameAt: { status: "present", at: frameSpan.endedAt },
       },
+      ...(ghostLeg !== undefined ? { ghostLeg } : {}),
     };
   }
 
@@ -525,6 +617,7 @@ async function classifyScopedRun(input: {
       models,
       gateCycles,
     },
+    ...(ghostLeg !== undefined ? { ghostLeg } : {}),
   };
 }
 
@@ -588,11 +681,12 @@ export async function scanAnalystIssueRuns(input: {
   }
 
   if (bookNames.length === 0) {
-    return { runs: [], unreadable: [], scopeConflicts: [] };
+    return { runs: [], unreadable: [], scopeConflicts: [], ghostLegs: [] };
   }
 
   const runs: AnalystReadableRunFacts[] = [];
   const unreadable: AnalystUnreadableRun[] = [];
+  const ghostLegs: AnalystGhostLeg[] = [];
   // scopeConflicts retained on the scan face for page envelope compat; book×ticket
   // scope no longer emits projectRoot dual-key conflicts on the CLI path.
   const scopeConflicts: AnalystScopeConflict[] = [];
@@ -638,9 +732,19 @@ export async function scanAnalystIssueRuns(input: {
         role: parsed.role,
         runDirectory,
       });
-      if (classified.kind === "readable") runs.push(classified.facts);
-      else if (classified.kind === "unreadable") unreadable.push(classified.entry);
+      if (classified.kind === "readable") {
+        runs.push(classified.facts);
+        if (classified.ghostLeg !== undefined) ghostLegs.push(classified.ghostLeg);
+      } else if (classified.kind === "unreadable") {
+        unreadable.push(classified.entry);
+        if (classified.ghostLeg !== undefined) ghostLegs.push(classified.ghostLeg);
+      } else if (classified.kind === "ghost") {
+        ghostLegs.push(classified.leg);
+      }
       // live in-flight runs are omitted from legs and unreadable (not failure/death).
+      // #855 ghost legs are reported separately — not counted as in-flight.
+      // Lease check is independent of terminal artifact: present/unreadable may
+      // still carry a ghostLeg alongside metrics or missingSources.
     }
   }
 
@@ -648,5 +752,6 @@ export async function scanAnalystIssueRuns(input: {
     runs,
     unreadable,
     scopeConflicts,
+    ghostLegs,
   };
 }

package/src/archivist-record-entry.ts

@@ -1,7 +1,7 @@
 /**
  * 司天台唯一 Pi session 记录落盘入口（ADR 0065）。
  * 调用方只声明自己是谁的什么；落点由候簿拓扑算出，签名不含任何落点/路径参数。
- * 「谁调了谁」复用 Pi parentSession + ADR 0047 correlation，不新增 caller 字段。
+ * 「谁调了谁」复用 Pi parentSession，不新增 caller 字段（#855 两面对账 correlation 键已删）。
  */
 import {
   closeSync,

package/src/headless-host/description.ts

@@ -83,7 +83,11 @@ export function headlessTurnArgs(options: {
   readonly description: ClaudePrintHostDescription;
   /** Absolute path written by the adapter; paired with `systemPromptFlag`. */
   readonly systemPromptPath: string;
-  readonly jsonSchema: Readonly<Record<string, unknown>>;
+  /**
+   * Closed JSON Schema for structured_output seats.
+   * Optional: omit for prose-exit seats (#959 navigator) so the model may speak free text.
+   */
+  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;
@@ -99,9 +103,10 @@ export function headlessTurnArgs(options: {
     ...description.fixedArgs,
     description.systemPromptFlag,
     options.systemPromptPath,
-    description.jsonSchemaFlag,
-    JSON.stringify(options.jsonSchema),
   ];
+  if (options.jsonSchema !== undefined) {
+    args.push(description.jsonSchemaFlag, JSON.stringify(options.jsonSchema));
+  }
   if (options.pluginDir) args.push("--plugin-dir", options.pluginDir);
   if (options.mcpConfigPath !== undefined && options.mcpConfigPath !== "") {
     args.push(description.mcpConfigFlag, options.mcpConfigPath);
@@ -145,7 +150,7 @@ function codexTomlStringTable(entries: Readonly<Record<string, string>>): string
  * Free-form JSON leaf for Type.Unknown under Codex strict transport.
  * Strict rejects bare untyped nodes and root-level additionalProperties:true;
  * a $defs anyOf of JSON values (with nested additionalProperties as $ref)
- * is accepted and keeps array/object receipts expressible (navigator candidates).
+ * is accepted and keeps array/object receipts expressible.
  * Package code still does not validate or reject the receipt against schema.
  */
 const CODEX_JSON_VALUE_DEF = "codexJsonValue";
@@ -398,8 +403,11 @@ function codexMcpConfigArgs(
 export function codexTurnArgs(options: {
   /** Absolute path for `-c model_instructions_file=…`. */
   readonly systemPromptPath: string;
-  /** Absolute path for `--output-schema` (closed transport schema). */
-  readonly outputSchemaPath: string;
+  /**
+   * Absolute path for `--output-schema` (closed transport schema).
+   * Optional: omit for prose-exit seats (#959 navigator) so agent_message stays free text.
+   */
+  readonly outputSchemaPath?: string;
   readonly mcpServers: readonly Readonly<Record<string, unknown>>[];
   readonly model?: string;
   readonly effort?: string;
@@ -441,7 +449,9 @@ export function codexTurnArgs(options: {
   }
 
   args.push("-c", `model_instructions_file=${codexTomlString(options.systemPromptPath)}`);
-  args.push("--output-schema", options.outputSchemaPath);
+  if (options.outputSchemaPath !== undefined) {
+    args.push("--output-schema", options.outputSchemaPath);
+  }
   args.push(...codexMcpConfigArgs(options.mcpServers));
 
   if (options.model !== undefined && options.model !== "") {

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

@@ -39,6 +39,7 @@ import {
   isPlainObject,
   type HeadlessHostDescription,
 } from "./description.ts";
+import { NAVIGATOR_OUTPUT_TOOL_NAME } from "../package-contracts/navigator-output.ts";
 
 export type HeadlessRoleTurnHostConfig = Readonly<{
   description: HeadlessHostDescription;
@@ -406,7 +407,8 @@ function terminalFromSpawned(
 function buildTurnArgs(options: {
   readonly description: HeadlessHostDescription;
   readonly systemPromptPath: string;
-  readonly jsonSchema: Readonly<Record<string, unknown>>;
+  /** Closed schema; omit for #959 navigator prose-exit seats. */
+  readonly jsonSchema?: Readonly<Record<string, unknown>>;
   readonly mcpServers: readonly Readonly<Record<string, unknown>>[];
   readonly mcpConfigPath?: string;
   readonly outputSchemaPath?: string;
@@ -422,10 +424,10 @@ function buildTurnArgs(options: {
     if (options.sessionKind === "resume" && !options.sessionId) {
       throw new Error("codex resume requires a bound thread_id");
     }
-    if (options.outputSchemaPath === undefined) throw new Error("codex requires an output schema path");
+    // #959: prose-exit seats (navigator) omit --output-schema; other seats still require it.
     return codexTurnArgs({
       systemPromptPath: options.systemPromptPath,
-      outputSchemaPath: options.outputSchemaPath,
+      ...(options.outputSchemaPath === undefined ? {} : { outputSchemaPath: options.outputSchemaPath }),
       mcpServers: options.mcpServers,
       ...(options.model === undefined ? {} : { model: options.model }),
       ...(options.effort === undefined ? {} : { effort: options.effort }),
@@ -443,7 +445,8 @@ function buildTurnArgs(options: {
   return headlessTurnArgs({
     description: options.description,
     systemPromptPath: options.systemPromptPath,
-    jsonSchema: options.jsonSchema,
+    // #959: navigator omits --json-schema so free-form prose is a lawful exit.
+    ...(options.jsonSchema === undefined ? {} : { jsonSchema: options.jsonSchema }),
     mcpConfigPath: options.mcpConfigPath,
     ...(options.model === undefined ? {} : { model: options.model }),
     ...(options.effort === undefined ? {} : { effort: options.effort }),
@@ -482,12 +485,15 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
         ? (prompt) => applyCodexSkillInvocation(request.methods, prompt)
         : (prompt) => prompt;
       if (codex) {
-        outputSchemaPath = join(request.runDirectory, "headless-output-schema.json");
-        await writeFile(
-          outputSchemaPath,
-          `${JSON.stringify(closeJsonSchemaForCodex(prepared.jsonSchema), null, 2)}\n`,
-          "utf8",
-        );
+        // #959: navigator is a prose-exit seat — no closed output-schema.
+        if (prepared.terminatingToolName !== NAVIGATOR_OUTPUT_TOOL_NAME) {
+          outputSchemaPath = join(request.runDirectory, "headless-output-schema.json");
+          await writeFile(
+            outputSchemaPath,
+            `${JSON.stringify(closeJsonSchemaForCodex(prepared.jsonSchema), null, 2)}\n`,
+            "utf8",
+          );
+        }
       } else {
         mcpConfigPath = join(request.runDirectory, "headless-mcp-config.json");
         await writeFile(
@@ -517,7 +523,10 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
             args = buildTurnArgs({
               description: config.description,
               systemPromptPath,
-              jsonSchema: prepared.jsonSchema,
+              // #959: navigator prose exit — no closed JSON schema on claude either.
+              ...(prepared.terminatingToolName === NAVIGATOR_OUTPUT_TOOL_NAME
+                ? {}
+                : { jsonSchema: prepared.jsonSchema }),
               mcpServers: prepared.mcpServers,
               ...(mcpConfigPath === undefined ? {} : { mcpConfigPath }),
               ...(outputSchemaPath === undefined ? {} : { outputSchemaPath }),
@@ -657,6 +666,20 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
               });
             }
 
+            // #959: navigator prose exit — final agent_message is presented as-is.
+            // Empty text is not a lawful accepted receipt (align pi no_receipt / loud empty).
+            if (prepared.terminatingToolName === NAVIGATOR_OUTPUT_TOOL_NAME) {
+              if (observation.finalMessage.trim() === "") {
+                return terminalFromSpawned(spawned, {
+                  cause: "output",
+                  identity: { name: "HeadlessEmptyOutput", code: "empty-stdout" },
+                  diagnostic: spawned.stderr.trim() || "codex exec produced empty agent_message",
+                  details: { sessionId, exitCode: spawned.code },
+                });
+              }
+              await prepared.ingestStructuredOutput({ prose: observation.finalMessage });
+              return { status: "delivered", stderr: spawned.stderr };
+            }
             let receipt: unknown;
             try {
               receipt = JSON.parse(observation.finalMessage);
@@ -716,6 +739,14 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
 
           if (envelope.structured_output !== undefined) {
             await prepared.ingestStructuredOutput(envelope.structured_output);
+          } else if (
+            prepared.terminatingToolName === NAVIGATOR_OUTPUT_TOOL_NAME
+            && typeof envelope.result === "string"
+            && envelope.result.trim() !== ""
+          ) {
+            // #959: claude prose exit — free-form result text is the receipt body
+            // when structured_output is absent (json-schema omitted for navigator).
+            await prepared.ingestStructuredOutput({ prose: envelope.result });
           }
           return { status: "delivered", stderr: spawned.stderr };
         },