@akagilnc/pi-workflow-roles 0.1.5478 → 0.1.5504

package/src/collector-config.ts

@@ -2,6 +2,7 @@ import { readFile } from "node:fs/promises";
 
 import { sha256Hex } from "./sha256.ts";
 import { isRecord } from "./unknown-value.ts";
+import { isTicketNumberString, parseTicketNumber } from "./run-ticket-number.ts";
 
 export const COLLECTOR_OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;
 export const COLLECTOR_REPO_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,98}[A-Za-z0-9])?$/;
@@ -46,10 +47,11 @@ export function parseCollectorRepository(raw: unknown): CollectorRepository {
 }
 
 export function parseCollectorPrNumber(raw: unknown): number {
-  if (typeof raw === "string" && !/^[1-9][0-9]*$/.test(raw)) fail("Collector pull request number must be a positive safe integer string");
   if (typeof raw !== "string" && typeof raw !== "number") fail("Collector pull request number is required");
-  const value = Number(raw);
-  if (!Number.isSafeInteger(value) || value < 1) fail("Collector pull request number must be a positive safe integer");
+  const value = parseTicketNumber(raw);
+  if (value === undefined) fail(typeof raw === "string" && !isTicketNumberString(raw)
+    ? "Collector pull request number must be a positive safe integer string"
+    : "Collector pull request number must be a positive safe integer");
   return value;
 }
 

package/src/doctor-evidence.ts

@@ -1,6 +1,7 @@
 import { readdir, readFile, realpath, stat } from "node:fs/promises";
 import { dirname, relative, resolve, sep } from "node:path";
 import { sha256Hex } from "./sha256.ts";
+import { physicallyContainedIn } from "./activation-ledger-topology.ts";
 import type { DoctorCase, DoctorCaseCost, DoctorCount, DoctorEvidenceEntry } from "./doctor-contracts.ts";
 import { AcceptedDetailsContractError, acceptedFacts, isTerminatingToolName, validateAcceptedDetails } from "./package-contracts/terminating-tools.ts";
 
@@ -38,8 +39,11 @@ function deriveSession(content: string, id: string): SessionDerivation {
 }
 
 /** Read Pi's retained session directory as the sole raw material for one case. */
-export async function loadDoctorCase(runsPath: string): Promise<DoctorCase> {
+export async function loadDoctorCase(runsPath: string, projectRoot?: string): Promise<DoctorCase> {
   const root = await realpath(runsPath);
+  if (projectRoot !== undefined && !physicallyContainedIn(projectRoot, root)) {
+    throw new Error("doctor --runs escapes the project root");
+  }
   // Canonical <book>/<ticket>/runs; legacy issues/<n>/runs remains read-only compatible.
   const match = root.split(sep).join("/").match(/\/\.ak-roles\/books\/[^/]+\/(?:issues\/)?([1-9]\d*)\/runs$/);
   if (!match) throw new Error("Doctor case must be an .ak-roles/books/<book>/<n>/runs directory");

package/src/engine-detour-usage.ts

@@ -17,9 +17,15 @@
  */
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
+
+export {
+  runDirectoryFromSessionDirectory,
+  sessionFileIn as sessionFileFromSessionDirectory,
+} from "./role-run-placement.ts";
 
 import { ENGINE_DETOUR_TOOL_NAME } from "./engine-detour.ts";
+import { sitianRunVolumeDirectory, sitianVolumeRecordsFile } from "./sitian-appender.ts";
 import {
   readSitianRecords,
   resolveSitianRecordPath,
@@ -40,8 +46,9 @@ export const ENGINE_DETOUR_TOOL_USAGE_FACT_KEY = "engineDetourToolUsage" as cons
  * Openable once the run directory is known from the terminal's run id.
  * Contains no runId bytes itself (#108 + #537).
  */
-export const ENGINE_DETOUR_CALL_RECORD_FILE_RELATIVE =
-  `session/${ENGINE_DETOUR_CALL_KIND}/records.jsonl` as const;
+export const ENGINE_DETOUR_CALL_RECORD_FILE_RELATIVE = sitianVolumeRecordsFile(
+  sitianRunVolumeDirectory("", ENGINE_DETOUR_CALL_KIND),
+);
 
 /** stdout UTF-8 byte length (ticket-frozen metric; empty stdout is real 0). */
 export function engineDetourStdoutByteLength(stdout: string): number {
@@ -288,16 +295,6 @@ export function withEngineDetourToolUsageFact<
   };
 }
 
-/** runDirectory owning a session directory (.../runs/<id>@role/session). */
-export function runDirectoryFromSessionDirectory(sessionDirectory: string): string {
-  return dirname(sessionDirectory);
-}
-
-/** session.jsonl under a session directory. */
-export function sessionFileFromSessionDirectory(sessionDirectory: string): string {
-  return join(sessionDirectory, "session.jsonl");
-}
-
 /**
  * Mint one public-invocation scope id.
  * Call once at the public-entry boundary — never inside the auto-resume loop.

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/description.ts

@@ -130,6 +130,253 @@ function codexTomlStringTable(entries: Readonly<Record<string, string>>): string
   return `{${parts.join(",")}}`;
 }
 
+/**
+ * Free-form JSON leaf for Type.Unknown under Codex strict transport.
+ * Declared contract objects still close with additionalProperties:false.
+ * For Unknown, a $defs anyOf of JSON values with nested additionalProperties
+ * as $ref is accepted by Codex and keeps non-empty object receipts expressible
+ * (native probe). Package code still does not validate or reject the receipt.
+ */
+const CODEX_JSON_VALUE_DEF = "codexJsonValue";
+const CODEX_JSON_VALUE_REF = `#/$defs/${CODEX_JSON_VALUE_DEF}`;
+const CODEX_JSON_VALUE_SCHEMA = Object.freeze({
+  anyOf: Object.freeze([
+    Object.freeze({ type: "string" }),
+    Object.freeze({ type: "number" }),
+    Object.freeze({ type: "boolean" }),
+    Object.freeze({ type: "null" }),
+    Object.freeze({ type: "array", items: Object.freeze({ $ref: CODEX_JSON_VALUE_REF }) }),
+    Object.freeze({
+      type: "object",
+      properties: Object.freeze({}),
+      required: Object.freeze([] as string[]),
+      additionalProperties: Object.freeze({ $ref: CODEX_JSON_VALUE_REF }),
+    }),
+  ]),
+});
+
+/**
+ * Derive a Codex/OpenAI-strict transport schema from the package open schema.
+ * Legal open schema is untouched; this is a host-only transmission projection
+ * (#1148 / #646 / ADR 0057 / ADR 0054): every object closes, every property is
+ * required, originally-optional fields become a null union (official guidance),
+ * and originally-required declared nullability stays. Nested open-tool anyOf
+ * wrappers are flattened so every branch carries `type`, keeping descriptions.
+ * Type.Unknown / description-only leaves become the closed JSON-value $ref.
+ * Package code still does not validate or reject the receipt.
+ */
+export function closeJsonSchemaForCodex(
+  schema: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const closed = closeSchemaNode(schema) as Record<string, unknown>;
+  const existingDefs = isRecord(closed.$defs)
+    ? (closed.$defs as Record<string, unknown>)
+    : {};
+  return {
+    ...closed,
+    $defs: {
+      ...existingDefs,
+      [CODEX_JSON_VALUE_DEF]: CODEX_JSON_VALUE_SCHEMA,
+    },
+  };
+}
+
+/** Pure null leaf only — composite type|null is stripped in-leaf, not dropped whole. */
+function isPureNullTypeSchema(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  if (value.type === "null") return true;
+  if (Array.isArray(value.type) && value.type.length > 0 && value.type.every((t) => t === "null")) {
+    return true;
+  }
+  return false;
+}
+
+/** Declared nullability on the open schema (type|null, anyOf null leaf, or pure null). */
+function schemaDeclaresNull(schema: unknown): boolean {
+  if (!isRecord(schema)) return false;
+  if (isPureNullTypeSchema(schema)) return true;
+  if (Array.isArray(schema.type) && schema.type.includes("null")) return true;
+  if (Array.isArray(schema.anyOf) && schema.anyOf.some(schemaDeclaresNull)) return true;
+  return false;
+}
+
+/**
+ * Within a leaf, remove null members from type arrays.
+ * Null is re-added when the union or property edge originally declared it.
+ */
+function stripNullFromLeafType(leaf: unknown): unknown {
+  if (!isRecord(leaf) || !Array.isArray(leaf.type)) return leaf;
+  const nonNull = leaf.type.filter((t) => t !== "null");
+  if (nonNull.length === leaf.type.length) return leaf;
+  if (nonNull.length === 0) return { ...leaf, type: "null" };
+  if (nonNull.length === 1) return { ...leaf, type: nonNull[0] };
+  return { ...leaf, type: nonNull };
+}
+
+/**
+ * Flatten nested anyOf wrappers into concrete leaf schemas.
+ * Open-tool unions often wrap leaves in description-only anyOf shells that
+ * lack `type`; strict structured output rejects those intermediate nodes.
+ * Nested shell descriptions attach to leaves that lack their own (not onto $ref).
+ * The outermost union keeps its description on the closed node via the caller.
+ */
+function flattenUnionLeaves(schema: unknown, attachShellDescription = false): unknown[] {
+  if (!isRecord(schema)) return [schema];
+  if (!Array.isArray(schema.anyOf)) return [schema];
+  const shellDescription =
+    attachShellDescription && typeof schema.description === "string"
+      ? schema.description
+      : undefined;
+  return schema.anyOf.flatMap((branch) => {
+    const leaves = flattenUnionLeaves(branch, true);
+    if (shellDescription === undefined) return leaves;
+    return leaves.map((leaf) => {
+      if (!isRecord(leaf) || typeof leaf.$ref === "string") return leaf;
+      if (typeof leaf.description === "string") return leaf;
+      return { ...leaf, description: shellDescription };
+    });
+  });
+}
+
+/** Drop pure-null leaves after in-leaf null stripping; property edge may re-add null. */
+function nonNullLeaves(schema: unknown): unknown[] {
+  return flattenUnionLeaves(schema)
+    .map(stripNullFromLeafType)
+    .filter((leaf) => !isPureNullTypeSchema(leaf));
+}
+
+function withDescription(closed: unknown, description: Readonly<{ description?: string }>): unknown {
+  if (description.description === undefined) return closed;
+  // Codex strict does not allow sibling keys on $ref; wrap so guidance is kept.
+  if (isRecord(closed) && typeof closed.$ref === "string") {
+    return { anyOf: [closed], ...description };
+  }
+  // Prefer a leaf's own description (nested anyOf shell) over the outer copy.
+  if (isRecord(closed) && typeof closed.description === "string") return closed;
+  return isRecord(closed) ? { ...closed, ...description } : closed;
+}
+
+/**
+ * Property edge under strict transport.
+ * Optional → closed leaf(s) + null. Required with declared nullability keeps null.
+ * Required without declared null stays non-nullable.
+ */
+function closePropertySchema(schema: unknown, optional: boolean): unknown {
+  const description =
+    isRecord(schema) && typeof schema.description === "string"
+      ? { description: schema.description }
+      : {};
+  const keepNull = optional || schemaDeclaresNull(schema);
+  const leaves = nonNullLeaves(schema).map(closeSchemaNode);
+  if (leaves.length === 0) return { type: "null", ...description };
+  if (!keepNull) {
+    const closed = leaves.length === 1 ? leaves[0] : { anyOf: leaves };
+    return withDescription(closed, description);
+  }
+  return { anyOf: [...leaves, { type: "null" }], ...description };
+}
+
+/**
+ * Strict generators require every schema node to declare `type` (or a $ref).
+ * Type.Unknown / description-only leaves → free JSON $ref (not string): array
+ * and object receipts stay expressible under --output-schema.
+ */
+function ensureTypedLeaf(schema: Record<string, unknown>): Record<string, unknown> {
+  if (schema.type !== undefined) return schema;
+  if (typeof schema.$ref === "string") return schema;
+  if (isRecord(schema.properties) || schema.additionalProperties !== undefined) {
+    return { ...schema, type: "object" };
+  }
+  if (schema.items !== undefined) {
+    return { ...schema, type: "array" };
+  }
+  if (schema.const !== undefined) {
+    const value = schema.const;
+    if (value === null) return { ...schema, type: "null" };
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      return { ...schema, type: typeof value };
+    }
+  }
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+    const sample = schema.enum.find((item) => item !== null);
+    if (typeof sample === "string" || typeof sample === "number" || typeof sample === "boolean") {
+      return { ...schema, type: typeof sample };
+    }
+  }
+  // Free JSON via $defs. $ref must stand alone (strict rejects sibling keys).
+  return { $ref: CODEX_JSON_VALUE_REF };
+}
+
+function originalRequiredNames(node: Record<string, unknown>): ReadonlySet<string> {
+  if (!Array.isArray(node.required)) return new Set();
+  return new Set(node.required.filter((item): item is string => typeof item === "string"));
+}
+
+function closeSchemaNode(node: unknown): unknown {
+  if (!isRecord(node)) return node;
+
+  // Already a ref (free-JSON leaf or pre-existing) — do not retype.
+  if (typeof node.$ref === "string") return node;
+
+  // Union node: flatten then close each concrete leaf (do not keep untyped shells).
+  // Declared null stays — including nested unions such as array items.
+  if (Array.isArray(node.anyOf)) {
+    const description =
+      typeof node.description === "string" ? { description: node.description } : {};
+    const keepNull = schemaDeclaresNull(node);
+    const leaves = nonNullLeaves(node).map(closeSchemaNode);
+    if (leaves.length === 0) return { type: "null", ...description };
+    if (!keepNull) {
+      if (leaves.length === 1) return withDescription(leaves[0], description);
+      return { anyOf: leaves, ...description };
+    }
+    return { anyOf: [...leaves, { type: "null" }], ...description };
+  }
+
+  let out: Record<string, unknown> = { ...node };
+
+  if (node.items !== undefined) {
+    out.items = closeSchemaNode(node.items);
+  }
+  if (isRecord(node.$defs)) {
+    out.$defs = Object.fromEntries(
+      Object.entries(node.$defs).map(([key, value]) => [key, closeSchemaNode(value)]),
+    );
+  }
+
+  const hasProperties = isRecord(node.properties);
+  const isObjectType =
+    node.type === "object"
+    || (Array.isArray(node.type) && node.type.includes("object"))
+    || hasProperties
+    || node.additionalProperties !== undefined;
+
+  if (hasProperties) {
+    const props = node.properties as Record<string, unknown>;
+    const wasRequired = originalRequiredNames(node);
+    const closedProps: Record<string, unknown> = {};
+    const required: string[] = [];
+    for (const [name, propSchema] of Object.entries(props)) {
+      required.push(name);
+      closedProps[name] = closePropertySchema(propSchema, !wasRequired.has(name));
+    }
+    out.properties = closedProps;
+    out.required = required;
+    out.additionalProperties = false;
+    if (out.type === undefined) out.type = "object";
+    // Object nodes must not also carry residual anyOf from the open copy.
+    delete out.anyOf;
+  } else if (isObjectType) {
+    out.additionalProperties = false;
+    if (!Array.isArray(out.required)) out.required = [];
+    if (out.type === undefined) out.type = "object";
+  } else {
+    out = ensureTypedLeaf(out);
+  }
+
+  return out;
+}
+
 /**
  * Project shared-envelope MCP rows into `codex -c mcp_servers.<name>.*` argv pairs.
  * Dot-path + TOML values per official config-advanced; spawn argv (no shell).
@@ -185,7 +432,7 @@ export function codexTurnArgs(options: {
   readonly systemPromptPath: string;
   /**
    * Absolute path for the native `--output-schema` flag.
-   * Pass the declaration unchanged; native strict output cannot promise an open contract.
+   * File holds the Codex-strict transport projection of the open declaration (#1148).
    * Optional for prose-exit seats (#959 navigator) so agent_message stays free text.
    */
   readonly outputSchemaPath?: string;

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

@@ -7,8 +7,7 @@
  * Intermediate AK tools ride the shared envelope MCP relay (Claude `--mcp-config`,
  * codex `-c mcp_servers.*`). The terminating receipt is the host-native schema
  * channel only (#750 submission-tool-is-schema-channel) — terminating tool is not
- * listed on MCP (Claude `--json-schema`, codex `--output-schema` receive the declaration unchanged).
- * Codex native strict output cannot promise an open contract; the adapter reports that gap.
+ * listed on MCP (Claude `--json-schema`, codex `--output-schema` closed projection).
  */
 import { randomUUID } from "node:crypto";
 

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

@@ -10,6 +10,7 @@ import { writeFile } from "node:fs/promises";
 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,
@@ -32,6 +33,7 @@ import {
   recordNativeSessionPointer,
 } from "../host-session-record.ts";
 import {
+  closeJsonSchemaForCodex,
   codexTurnArgs,
   headlessMcpConfigDocument,
   headlessTurnArgs,
@@ -465,16 +467,15 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
       let mcpConfigPath: string | undefined;
       let outputSchemaPath: string | undefined;
       if (codex) {
-        // Send the declaration unchanged. Any native rejection belongs to Codex;
-        // do not close the schema or substitute a different receipt outlet.
+        // #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");
-          await writeFile(outputSchemaPath, `${JSON.stringify(prepared.jsonSchema, null, 2)}\n`, "utf8");
-          await retainPackageFault({
-            runDirectory: request.runDirectory,
-            diagnostic:
-              "codex --output-schema cannot promise this open contract: native strict output requires all properties and additionalProperties:false; the declaration is sent unchanged",
-          });
+          await writeFile(
+            outputSchemaPath,
+            `${JSON.stringify(closeJsonSchemaForCodex(prepared.jsonSchema), null, 2)}\n`,
+            "utf8",
+          );
         }
       } else {
         mcpConfigPath = join(request.runDirectory, "headless-mcp-config.json");
@@ -717,7 +718,7 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
         try {
           if (exitedSessionId !== undefined && exitedSessionId !== "") copyAndRecordHostDossier({
             host: config.hostName, sessionId: exitedSessionId, cwd: request.cwd,
-            sessionDirectory: join(request.runDirectory, "session"), sessionParent,
+            sessionDirectory: sessionDirectoryOf(request.runDirectory), sessionParent,
             continuation: request.continuation,
             ...(request.model !== undefined ? { model: request.model } : {}),
             ...(request.home !== undefined ? { home: request.home } : {}),

package/src/ledger-session-read.ts

@@ -8,6 +8,12 @@ import { isRecord } from "./unknown-value.ts";
 
 export type LedgerSessionRow = Record<string, unknown>;
 
+/** Complete Pi volume decoding: malformed EOF is an error, with no row-shape filtering. */
+export async function readStrictPiSessionJsonl(path: string): Promise<unknown[]> {
+  const text = await readFile(path, "utf8");
+  return text.trim().split("\n").filter(Boolean).map((line) => JSON.parse(line) as unknown);
+}
+
 /**
  * Loud JSONL failure that still retains rows parsed before the bad line.
  * Callers that only need the throw keep catching Error; owners that must

package/src/navigator-public-session.ts

@@ -9,7 +9,7 @@
 import { existsSync } from "node:fs";
 import { basename } from "node:path";
 
-import { sitianReport } from "./sitian-facade.ts";
+import { sitianReportSafe } from "./host-session-record.ts";
 import {
   NavigatorUnavailableError,
   navigatorProviderFailureFromPublicTerminal,
@@ -21,6 +21,7 @@ import {
 } from "./navigator-session-contracts.ts";
 import type { NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
 import { runDirectoryFromHostContext, type HostContext } from "./host-contracts.ts";
+import { parseRunLeaf } from "./role-run-placement.ts";
 import type { PublicSummonResult } from "./public-role-summons.ts";
 import { CliUsageError } from "./public-cli/cli-errors.ts";
 import { isNavigatorSeat } from "./packaged-role-registry.ts";
@@ -57,11 +58,9 @@ async function resolveNavigatorLedgerHome(context: HostContext): Promise<string
 export const NAVIGATOR_HOST_RUN_POINTER_ENTRY = "ak-navigator-host-run";
 
 export function runIdFromNavigatorDirectory(runDirectory: string): string | undefined {
-  const entry = basename(runDirectory);
-  const suffix = "@navigator";
-  if (!entry.endsWith(suffix)) return undefined;
-  const runId = entry.slice(0, entry.length - suffix.length);
-  return runId.length > 0 ? runId : undefined;
+  const parsed = parseRunLeaf(basename(runDirectory));
+  if (parsed === undefined || parsed.role !== "navigator") return undefined;
+  return parsed.runId;
 }
 
 export function readNavigatorHostRunPointer(entries: readonly unknown[]): string | undefined {
@@ -285,18 +284,14 @@ export function createNativeNavigatorSessionFactory(deps?: {
       routePlaybookReadFailure: () => routePlaybookReadFailure,
       appendEntry: (customType, data) => {
         sessionManager.appendCustomEntry(customType, data);
-        try {
-          sitianReport({
-            level: "event",
-            kind: "attendance",
-            cwd: context.cwd,
-            sessionParent: sessionManager.getSessionFile(),
-            payload: { customType, data },
-            source: "navigator-public-session",
-          });
-        } catch {
-          // best-effort
-        }
+        sitianReportSafe({
+          level: "event",
+          kind: "attendance",
+          cwd: context.cwd,
+          sessionParent: sessionManager.getSessionFile(),
+          payload: { customType, data },
+          source: "navigator-public-session",
+        });
       },
       entries: () => sessionManager.getEntries(),
       setModel: async (next, nextThinking) => {

package/src/navigator-work-context.ts

@@ -5,6 +5,8 @@
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 
+import { sessionDirectoryOf } from "./role-run-placement.ts";
+
 import { loadDoctorCase } from "./doctor-evidence.ts";
 import { isEnoent } from "./unknown-value.ts";
 import { runDirectoryFromHostContext, type HostContext } from "./host-contracts.ts";
@@ -69,7 +71,7 @@ export async function loadNavigatorWorkContext(
   const publicRunDir = runDirectoryFromHostContext(options.context);
   const currentSessionDir = options.context.sessionManager.getSessionDir();
   const isBoundPublicRun = publicRunDir !== undefined
-    && resolve(currentSessionDir) === resolve(publicRunDir, "session");
+    && resolve(currentSessionDir) === resolve(sessionDirectoryOf(publicRunDir));
   if (subjectMode === "public-instruction" && isBoundPublicRun) {
     let admitted;
     try {

package/src/notary-role.ts

@@ -1,6 +1,7 @@
 import type { RoleHost, HostContext } from "./host-contracts.ts";
 import { registerFiledSubmissionTool } from "./filed-submission.ts";
 import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
+import { isSafePositiveTicketNumber } from "./run-ticket-number.ts";
 /**
  * Public Notary role runtime — direct officer seat (not through Gatekeeper province).
  * Caller supplies only a source-run locator; Notary self-fetches authoritative materials.
@@ -44,7 +45,7 @@ export function readNotaryTicketFlag(flag: unknown): number | undefined {
   }
   if (flag.trim() === "") return undefined;
   const n = Number(flag);
-  if (!Number.isSafeInteger(n) || n < 1) {
+  if (!isSafePositiveTicketNumber(n)) {
     throw new Error(
       "Notary ak-notary-ticket-number is present but not a safe positive integer string",
     );