@akagilnc/pi-workflow-roles 0.1.5483 → 0.1.5571

package/src/archivist-record-pointer.ts

@@ -1,7 +1,13 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { basename, join } from "node:path";
 import { isRecord } from "./unknown-value.ts";
+import { latestOfficerPointersFromRecords, RUN_HISTORY_FILE } from "./run-dossier.ts";
+import { OFFICER_POINTER_RECORD_KIND } from "./run-dossier-files.ts";
+import { readSitianRecords, reportRunRecord } from "./sitian-facade.ts";
+
+import { homeFromRunDirectory } from "./activation-ledger-topology.ts";
+import { findRunDirectoryById, readRoleRunIdentity } from "./public-cli/run-lifecycle.ts";
+import { rewriteRunDirectoryPathValue } from "./role-run-relocation.ts";
+import { parseRunLeaf, runDirectoryOfSessionFile } from "./role-run-placement.ts";
 
 /** Typed parent-side pointer to an independent officer run 正本 (ADR 0079 / #675). */
 export const DIRECT_OFFICER_RUN_POINTER_KIND = "direct-officer-run-pointer" as const;
@@ -21,14 +27,17 @@ export type DirectOfficerRunPointer = {
   readonly submissionToolCallId?: string;
 };
 
+/** History record kind of a booked officer pointer (appender routes it to history.jsonl). */
+export { OFFICER_POINTER_RECORD_KIND };
+
 /**
- * Book a typed pointer under parent session/auditor-roles (same nest owner as
- * createRecordSession). Never fabricates user/assistant/toolResult rows (#675).
- * Directory placement stays with the archivist record entry (ADR 0018 / 0065).
+ * Book a typed pointer as one history record of the parent run; the settlement
+ * seam projects the latest per officer into current.json `officers`.
+ * Never fabricates user/assistant/toolResult rows (#675).
  *
- * Stable leaf per officer under one parent (#753 gate-round accounting):
- * same-parent re-summons upsert the same pointer instead of minting N files that
- * each re-scan the full officer session and multiply terminal gate-round counts.
+ * Latest record wins per officer under one parent (#753 gate-round accounting):
+ * a same-parent re-summons supersedes the earlier pointer instead of adding a
+ * second one that re-scans the full officer session and multiplies gate-cycle counts.
  */
 export function bookDirectOfficerRunPointer(options: {
   readonly parentSessionFile: string;
@@ -37,8 +46,6 @@ export function bookDirectOfficerRunPointer(options: {
   readonly runDirectory?: string;
   readonly submissionToolCallId?: string;
 }): DirectOfficerRunPointer {
-  const nest = join(dirname(options.parentSessionFile), "auditor-roles");
-  mkdirSync(nest, { recursive: true });
   const submissionToolCallId = options.submissionToolCallId?.trim() ?? "";
   const pointer: DirectOfficerRunPointer = {
     version: 1,
@@ -50,47 +57,90 @@ export function bookDirectOfficerRunPointer(options: {
       : {}),
     ...(submissionToolCallId === "" ? {} : { submissionToolCallId }),
   };
-  writeFileSync(
-    join(nest, `${options.officer}.pointer.json`),
-    `${JSON.stringify(pointer)}\n`,
-    "utf8",
-  );
+  reportRunRecord(runDirectoryOfSessionFile(options.parentSessionFile), OFFICER_POINTER_RECORD_KIND, pointer, "submission-gate");
   return pointer;
 }
 
+/** Shared strict pointer IO; internal audit wraps unreadability as a re-summons. */
+export async function resolveOfficerPointer(
+  raw: unknown,
+  parentRunDirectory: string,
+): Promise<{
+  sessionFile: string;
+  officer?: DirectOfficerRunPointer["officer"];
+  runDirectory?: string;
+  submissionToolCallId?: string;
+}> {
+  const where = `${parentRunDirectory} officers`;
+  if (!isRecord(raw) || raw.kind !== DIRECT_OFFICER_RUN_POINTER_KIND || raw.version !== 1) {
+    throw new Error(`direct officer run pointer has unknown shape in ${where}`);
+  }
+  if (typeof raw.sessionFile !== "string" || raw.sessionFile.trim() === "") {
+    throw new Error(`direct officer run pointer missing sessionFile in ${where}`);
+  }
+  const officer = raw.officer === "inspector" || raw.officer === "notary"
+    || raw.officer === "auditor" || raw.officer === "countersign" ? raw.officer : undefined;
+  let runDirectory = typeof raw.runDirectory === "string" && raw.runDirectory.trim() !== ""
+    ? raw.runDirectory : undefined;
+  let sessionFile = raw.sessionFile;
+  const recordedRunDirectory = runDirectory ?? runDirectoryOfSessionFile(sessionFile);
+  const leaf = parseRunLeaf(basename(recordedRunDirectory));
+  const parentIdentity = await readRoleRunIdentity(parentRunDirectory);
+  if (leaf !== undefined && parentIdentity !== undefined) {
+    const currentRunDirectory = await findRunDirectoryById(
+      homeFromRunDirectory(parentRunDirectory), leaf.runId, parentIdentity.bookKey, leaf.role,
+    );
+    if (currentRunDirectory !== undefined) {
+      sessionFile = rewriteRunDirectoryPathValue(sessionFile, recordedRunDirectory, currentRunDirectory) as string;
+      if (runDirectory !== undefined) runDirectory = currentRunDirectory;
+    }
+  }
+  const submissionToolCallId = typeof raw.submissionToolCallId === "string"
+    && raw.submissionToolCallId.trim() !== "" ? raw.submissionToolCallId : undefined;
+  return {
+    sessionFile,
+    ...(officer === undefined ? {} : { officer }),
+    ...(runDirectory === undefined ? {} : { runDirectory }),
+    ...(submissionToolCallId === undefined ? {} : { submissionToolCallId }),
+  };
+}
+
 /**
- * Read the one officer pointer. Missing or unreadable is not a pass:
- * the caller re-runs the gate.
+ * The latest pointer booked per officer on one run, as stored. History absent → empty.
+ * Canonical malformed diagnostics are not discarded: a damaged officer source must
+ * not wash into lawful zero rounds (#1161 O1).
  */
+export async function readBookedOfficerPointers(parentRunDirectory: string): Promise<Readonly<Record<string, unknown>>> {
+  const { records, diagnostics } = await readSitianRecords(join(parentRunDirectory, RUN_HISTORY_FILE));
+  if (diagnostics.length > 0) {
+    throw new Error(
+      `${RUN_HISTORY_FILE} has ${diagnostics.length} malformed row(s); officer pointers unreadable: ${parentRunDirectory}`,
+    );
+  }
+  return latestOfficerPointersFromRecords(records);
+}
+
+/** Every pointer booked on one run, in officer-name order. No pointers → []. */
+export async function readOfficerPointers(parentRunDirectory: string): Promise<readonly Awaited<ReturnType<typeof resolveOfficerPointer>>[]> {
+  const officers = await readBookedOfficerPointers(parentRunDirectory);
+  return Promise.all(
+    Object.keys(officers).sort().map((name) => resolveOfficerPointer(officers[name], parentRunDirectory)),
+  );
+}
+
+/** Missing or unreadable is not a pass: the internal audit caller re-runs the gate. */
 export async function readDirectOfficerRunPointer(
   parentSessionFile: string,
   officer: DirectOfficerRunPointer["officer"],
 ): Promise<DirectOfficerRunPointer | undefined> {
   try {
-    const raw: unknown = JSON.parse(await readFile(
-      join(dirname(parentSessionFile), "auditor-roles", `${officer}.pointer.json`),
-      "utf8",
-    ));
-    if (!isRecord(raw) || raw.kind !== DIRECT_OFFICER_RUN_POINTER_KIND || raw.version !== 1) {
-      return undefined;
-    }
-    if (raw.officer !== officer) return undefined;
-    if (typeof raw.sessionFile !== "string" || raw.sessionFile.trim() === "") return undefined;
-    const runDirectory = typeof raw.runDirectory === "string" && raw.runDirectory.trim() !== ""
-      ? raw.runDirectory
-      : undefined;
-    const submissionToolCallId = typeof raw.submissionToolCallId === "string"
-      && raw.submissionToolCallId.trim() !== ""
-      ? raw.submissionToolCallId
-      : undefined;
-    return {
-      version: 1,
-      kind: DIRECT_OFFICER_RUN_POINTER_KIND,
-      officer,
-      sessionFile: raw.sessionFile,
-      ...(runDirectory === undefined ? {} : { runDirectory }),
-      ...(submissionToolCallId === undefined ? {} : { submissionToolCallId }),
-    };
+    const parentRunDirectory = runDirectoryOfSessionFile(parentSessionFile);
+    const pointer = await resolveOfficerPointer(
+      (await readBookedOfficerPointers(parentRunDirectory))[officer],
+      parentRunDirectory,
+    );
+    if (pointer.officer !== officer) return undefined;
+    return { ...pointer, officer, version: 1, kind: DIRECT_OFFICER_RUN_POINTER_KIND };
   } catch {
     return undefined;
   }

package/src/atomic-write.ts

@@ -7,17 +7,19 @@
  * ledger home own confinement via ensureRealDirectoryTree (ADR 0038).
  */
 import { randomUUID } from "node:crypto";
+import type { Mode } from "node:fs";
 import { rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 export async function writeFileAtomically(
   destination: string,
   contents: string | Uint8Array,
+  options?: { readonly mode?: Mode },
 ): Promise<void> {
   const parent = dirname(destination);
   const temporary = join(parent, `.atomic-write-${randomUUID()}.tmp`);
   try {
-    await writeFile(temporary, contents);
+    await writeFile(temporary, contents, options);
     await rename(temporary, destination);
   } catch (error) {
     await rm(temporary, { force: true }).catch(() => undefined);

package/src/auditor-dossier-tool.ts

@@ -1,18 +1,23 @@
-import { dirname, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 
+import { RUN_HISTORY_FILE, RUN_LOG_FILE, runCurrentPath } from "./run-dossier.ts";
 import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { HostContext } from "./host-contracts.ts";
-import { roleRunArtifactsDirectory } from "./role-run-placement.ts";
+import {
+  runDirectoryOfSessionFile,
+  sessionFileOf,
+} from "./role-run-placement.ts";
 import { Type } from "typebox";
 
 export const AUDITOR_DOSSIER_TOOL_NAME = "ak_get_run_dossier" as const;
 
 export type AuditorDossierLocation = {
   readonly runDirectory: string;
-  readonly admittedRequest: string;
+  readonly current: string;
   readonly parentSessionCandidate: string;
   readonly attachments: string;
-  readonly artifacts: string;
+  readonly log: string;
+  readonly history: string;
 };
 
 /** Resolve the exact run binding already carried by the parent record session. */
@@ -20,7 +25,7 @@ export function auditorRunDirectory(context: ExtensionContext | HostContext): st
   const sessionFile = context.sessionManager?.getSessionFile?.();
   if (sessionFile === undefined) return undefined;
   // Sole layout: <run>/session/session.jsonl → climb two levels to the run directory.
-  return resolve(dirname(dirname(sessionFile)));
+  return resolve(runDirectoryOfSessionFile(sessionFile));
 }
 
 /** The one shared, run-bound dossier locator exposed to every auditor seat. */
@@ -43,10 +48,11 @@ export function createAuditorDossierTool(
       // #836: whole run directory pointer — officer finds materials; no leaf preference (A7.2).
       const details: AuditorDossierLocation = {
         runDirectory,
-        admittedRequest: join(runDirectory, "admitted-request.json"),
-        parentSessionCandidate: join(runDirectory, "session", "session.jsonl"),
+        current: runCurrentPath(runDirectory),
+        parentSessionCandidate: sessionFileOf(runDirectory),
         attachments: join(runDirectory, "attachments"),
-        artifacts: roleRunArtifactsDirectory(runDirectory),
+        log: join(runDirectory, RUN_LOG_FILE),
+        history: join(runDirectory, RUN_HISTORY_FILE),
       };
       return {
         content: [{ type: "text", text: JSON.stringify(details) }],

package/src/auditor-soul.ts

@@ -1,6 +1,8 @@
 import { readFile } from "node:fs/promises";
+import { readPageSync } from "./run-dossier.ts";
 import { basename, join } from "node:path";
 
+import { parseRunLeaf } from "./role-run-placement.ts";
 import { isRecord } from "./unknown-value.ts";
 
 import {
@@ -109,7 +111,7 @@ export function loadAuditorReferenceMaterialsFromSubjectInput(raw?: string): Pro
 }
 
 function subjectFromSourceDirectory(sourceRunDirectory: string): AuditorSoulRole | undefined {
-  const role = basename(sourceRunDirectory).split("@")[1];
+  const role = parseRunLeaf(basename(sourceRunDirectory))?.role;
   return isAuditorSoulRole(role) ? role : undefined;
 }
 
@@ -121,15 +123,8 @@ export async function readAuditorResumeBinding(runDirectory: string): Promise<
   | { readonly subject: AuditorSoulRole; readonly sourceRunDirectory: string }
   | undefined
 > {
-  let raw: unknown;
-  try {
-    raw = JSON.parse(await readFile(join(runDirectory, "admitted-request.json"), "utf8")) as unknown;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
-    throw error;
-  }
-  if (!isRecord(raw)) return undefined;
-  const record = raw as { sourceRunPath?: unknown; auditorSubject?: unknown };
+  const record = readPageSync(runDirectory, "admitted");
+  if (record === undefined) return undefined;
   if (typeof record.sourceRunPath !== "string" || record.sourceRunPath.trim() === "") return undefined;
   const subject = isAuditorSoulRole(record.auditorSubject)
     ? record.auditorSubject

package/src/book-topology-migration-placement.ts

@@ -15,9 +15,10 @@ import { isUnboundRunDirectory, roleRunPlacement } from "./role-run-placement.ts
 export { isUnboundRunDirectory };
 import {
   MIGRATION_TICKET_DERIVATION_PAGE,
-  readBoardTicketNumber,
+  readMigrationBoardTicketNumber,
   readMigrationDerivedTicketNumber,
 } from "./run-ticket-number.ts";
+import { readPageSync } from "./run-dossier.ts";
 
 import { isRecord, isEnoent } from "./unknown-value.ts";
 
@@ -83,11 +84,23 @@ export function ticketNumberFromWorktreeBasename(
 
 /**
  * projectRoot from a retained run's durable pages.
- * ENOENT → try next page / undefined; bad JSON and non-ENOENT IO propagate.
+ * New落点 (state rows) first, then pre-#1161 page files at the migration boundary.
+ * ENOENT → try next / undefined; bad JSON and non-ENOENT IO propagate.
  */
 async function readProjectRootFromRun(
   runDirectory: string,
 ): Promise<{ readonly projectRoot: string; readonly sourcePage: string } | undefined> {
+  for (const section of ["admitted", "invocation", "runState"] as const) {
+    try {
+      const page = readPageSync(runDirectory, section);
+      const projectRoot = page?.projectRoot;
+      if (typeof projectRoot === "string" && projectRoot.length > 0) {
+        return { projectRoot, sourcePage: `state.jsonl:${section}` };
+      }
+    } catch (error) {
+      if (!isEnoent(error)) throw error;
+    }
+  }
   for (const page of ["admitted-request.json", "invocation.json", "run-state.json"] as const) {
     const path = join(runDirectory, page);
     try {
@@ -123,7 +136,7 @@ export async function resolveMigratingRunTicket(runDirectory: string): Promise<{
   readonly ticketNumber: number | undefined;
   readonly derivation: MigratingRunTicketDerivation | undefined;
 }> {
-  const boardTicket = await readBoardTicketNumber(runDirectory);
+  const boardTicket = await readMigrationBoardTicketNumber(runDirectory);
   if (boardTicket !== undefined) {
     return {
       ticketNumber: boardTicket,

package/src/book-topology-record-class-migrators.ts

@@ -31,12 +31,14 @@ import {
   type BookTopologyPartitionMigrator,
   type MigrationItemOutcome,
 } from "./book-topology-migration.ts";
-import { S4_SUBMISSION_LEDGER_KINDS } from "./sitian-appender.ts";
 import { projectTicketProvenanceHeader } from "./ticket-provenance-contracts.ts";
 
 import { sha256Hex } from "./sha256.ts";
 import { isRecord, isEnoent } from "./unknown-value.ts";
 
+/** Kinds the retired #852-era submission-ledger volume held (migration of stored runs only). */
+const LEGACY_SUBMISSION_LEDGER_KINDS = new Set(["candidate", "roundContext", "outcome", "sealed", "post-seal-anomaly"]);
+
 const TICKET_PROVENANCE = "ticket-provenance";
 const SUBMISSION_LEDGER = "submission-ledger";
 const ATTEMPT_HISTORY = "attempt-history";
@@ -210,7 +212,7 @@ function runIdFromPayload(payload: unknown): string | undefined {
 function recordClassOfKind(kind: unknown): RecordClass | undefined {
   if (kind === TICKET_PROVENANCE) return TICKET_PROVENANCE;
   if (kind === ATTEMPT_HISTORY) return ATTEMPT_HISTORY;
-  if (typeof kind === "string" && S4_SUBMISSION_LEDGER_KINDS.has(kind)) return SUBMISSION_LEDGER;
+  if (typeof kind === "string" && LEGACY_SUBMISSION_LEDGER_KINDS.has(kind)) return SUBMISSION_LEDGER;
   return undefined;
 }
 

package/src/book-topology-runs-migrator.ts

@@ -26,9 +26,10 @@ import {
   rewriteRoleRunDurablePages,
   type RunDirectoryPathRewrite,
 } from "./role-run-relocation.ts";
+import { renderCurrentSync } from "./run-dossier.ts";
 import {
   MIGRATION_TICKET_DERIVATION_PAGE,
-  readBoardTicketNumber,
+  readMigrationBoardTicketNumber,
 } from "./run-ticket-number.ts";
 
 import { isEnoent } from "./unknown-value.ts";
@@ -151,7 +152,7 @@ async function planBookMoves(
       // #863: board typed ticket on an unbound leaf → place under that ticket.
       // No board ticket → stay unbound. Never invent from prose or derivation.
       const boardTicket = leaf.isDirectory
-        ? await readBoardTicketNumber(leaf.sourcePath)
+        ? await readMigrationBoardTicketNumber(leaf.sourcePath)
         : undefined;
       if (parsed !== undefined && boardTicket !== undefined) {
         targetPath = destinationRunDirectory(
@@ -318,7 +319,7 @@ export async function relocateBoardBoundUnboundRunsInBook(
     const parsed = parseRunLeaf(entry.name);
     if (parsed === undefined) continue;
     const sourcePath = join(unboundRuns, entry.name);
-    const boardTicket = await readBoardTicketNumber(sourcePath);
+    const boardTicket = await readMigrationBoardTicketNumber(sourcePath);
     if (boardTicket === undefined) continue;
     const targetPath = destinationRunDirectory(
       booksDirectory,
@@ -367,6 +368,8 @@ export async function relocateBoardBoundUnboundRunsInBook(
   for (const move of planned) {
     await mkdir(dirname(move.targetPath), { recursive: true });
     await rename(move.sourcePath, move.targetPath);
+    // Same live relocate seam: derived host.original follows the new run directory.
+    renderCurrentSync(move.targetPath);
   }
 
   return planned.map((move) => ({

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-contracts.ts

@@ -49,7 +49,7 @@ export type DoctorSubmission =
 // #836: runtime cost is a fact beside the role payload, never merged into it —
 // DoctorOutput is the accepted payload itself, identical to DoctorSubmission.
 export type DoctorOutput = DoctorSubmission;
-export type DoctorEvidenceEntry = { id: string; kind: "session" | "stderr"; byteLength: number; contentLength: number; sha256: string; content: string };
+export type DoctorEvidenceEntry = { id: string; kind: "session" | "log"; byteLength: number; contentLength: number; sha256: string; content: string };
 export type DoctorCase = { version: 1; identity: DoctorCaseIdentity; evidence: DoctorEvidenceEntry[]; cost: DoctorCaseCost };
 
 // status 的合法词写在 description。交卷原样入账（validateDoctorSubmissionShape），

package/src/doctor-evidence.ts

@@ -1,12 +1,13 @@
 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";
 
 import { isRecord, isMissingPathError } from "./unknown-value.ts";
 
-async function discoverCaseFiles(root: string): Promise<string[]> { const found: string[] = []; async function walk(dir: string, depth: number) { for (const item of await readdir(dir, { withFileTypes: true })) { const path = resolve(dir, item.name); if (item.isDirectory()) { await walk(path, depth + 1); } else if (item.isFile() && (item.name.endsWith(".jsonl") || (item.name === "stderr.log" && depth === 1))) found.push(path); } } await walk(root, 0); return found.sort(); }
+async function discoverCaseFiles(root: string): Promise<string[]> { const found: string[] = []; async function walk(dir: string, depth: number) { for (const item of await readdir(dir, { withFileTypes: true })) { const path = resolve(dir, item.name); if (item.isDirectory()) { await walk(path, depth + 1); } else if (item.isFile() && ((item.name.endsWith(".jsonl") && item.name !== "state.jsonl" && !(item.name === "log.jsonl" && depth === 1)) || (item.name === "log.jsonl" && depth === 1))) found.push(path); } } await walk(root, 0); return found.sort(); }
 function sourceList(count: number, sources: string[]) { return { count, sources: [...new Set(sources)].sort() }; }
 function accumulate(metric: DoctorCount, value: number, source: string) { metric.count += value; if (value) metric.sources.push(source); }
 function timestamp(row: Record<string, unknown>) { return typeof row.timestamp === "string" && Number.isFinite(Date.parse(row.timestamp)) ? row.timestamp : undefined; }
@@ -38,14 +39,17 @@ 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");
   const evidence: DoctorEvidenceEntry[] = [], sessions: DoctorCaseCost["sessions"] = [], statuses: DoctorCaseCost["statuses"] = [], commits: DoctorCaseCost["commits"] = [];
   const turns: DoctorCount = { count: 0, sources: [] }, calls: DoctorCount = { count: 0, sources: [] }, tokens: DoctorCount = { count: 0, sources: [] };
-  for (const path of await discoverCaseFiles(root)) { const id = relative(root, path).split(sep).join("/"); const bytes = await readFile(path); const content = bytes.toString("utf8"); const kind = id.endsWith(".jsonl") ? "session" : "stderr"; evidence.push({ id, kind, byteLength: bytes.byteLength, contentLength: content.length, sha256: sha256Hex(bytes), content }); if (kind === "stderr") continue; const result = deriveSession(content, id); sessions.push(result.session); statuses.push(...result.statuses); commits.push(...result.commits); accumulate(turns, result.turns, id); accumulate(calls, result.calls, id); accumulate(tokens, result.tokens, id); }
+  for (const path of await discoverCaseFiles(root)) { const id = relative(root, path).split(sep).join("/"); const bytes = await readFile(path); const content = bytes.toString("utf8"); const kind = id.split("/").length === 2 && id.endsWith("/log.jsonl") ? "log" : "session"; evidence.push({ id, kind, byteLength: bytes.byteLength, contentLength: content.length, sha256: sha256Hex(bytes), content }); if (kind === "log") continue; const result = deriveSession(content, id); sessions.push(result.session); statuses.push(...result.statuses); commits.push(...result.commits); accumulate(turns, result.turns, id); accumulate(calls, result.calls, id); accumulate(tokens, result.tokens, id); }
   const runDirs = (await readdir(root, { withFileTypes: true })).filter((item) => item.isDirectory()).map((item) => item.name).sort(); const legs = evidence.filter((entry) => entry.kind === "session").map((entry) => entry.id); const retryDirs = runDirs.filter((name) => /(?:^|[-_])retry(?:[-_]|$)/i.test(name)); const rawBytes = evidence.filter((entry) => entry.kind === "session").reduce((sum, entry) => sum + entry.byteLength, 0);
   const cost: DoctorCaseCost = { invocations: sourceList(runDirs.length, runDirs), legs: sourceList(legs.length, legs), modelApiTurns: sourceList(turns.count, turns.sources), outputTokens: sourceList(tokens.count, tokens.sources), toolCalls: sourceList(calls.count, calls.sources), retries: { ...sourceList(retryDirs.length, retryDirs), evidence: "literal run-dir naming" }, statuses, commits, sessions, outputBytes: { ...sourceList(rawBytes, legs), payload: "raw JSONL bytes", providerWireBytes: "unavailable" } };
   return { version: 1, identity: { issueNumber: Number(match[1]), runsPath: await stableRunsIdentity(root) }, evidence, cost };

package/src/engine-detour-tool.ts

@@ -125,7 +125,7 @@ export function createEngineDetourToolDefinition(input: {
         : undefined;
       const runId = runDirectory === undefined ? undefined : runIdFromRunDirectory(runDirectory);
       // Public-invocation scope + selected host from Host envelope only — never
-      // courtAttemptId, never sidecar file, never pre-spawn invocation.json I/O.
+      // courtAttemptId, never sidecar file, never pre-spawn current.json I/O.
       const invocationScopeId =
         typeof ctx.invocationScopeId === "string" && ctx.invocationScopeId.trim() !== ""
           ? ctx.invocationScopeId.trim()

package/src/engine-detour-usage.ts

@@ -15,9 +15,15 @@
  * `ak-role resume`) mints a new one. Never courtAttemptId, never Pi session
  * toolResult join keys, and never a detour-owned sidecar file.
  */
+import { readPageSync, RUN_LOG_FILE } from "./run-dossier.ts";
 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 {
@@ -36,12 +42,11 @@ export const ENGINE_DETOUR_CALL_KIND = "engine-detour-call" as const;
 export const ENGINE_DETOUR_TOOL_USAGE_FACT_KEY = "engineDetourToolUsage" as const;
 
 /**
- * Run-relative sitian volume path for one detour call.
+ * Run-relative path of the log that holds one detour call's record.
  * 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 = RUN_LOG_FILE;
 
 /** stdout UTF-8 byte length (ticket-frozen metric; empty stdout is real 0). */
 export function engineDetourStdoutByteLength(stdout: string): number {
@@ -246,22 +251,14 @@ export async function readEngineDetourToolUsage(input: {
   return { callCount: calls.length, calls };
 }
 
-/** One shared invocation.json reader (ENOENT → undefined; other errors propagate). */
+/** One shared state.jsonl invocation-row reader (absent → undefined; other errors propagate). */
 function readInvocationRecord(
   runDirectory: string,
 ): Record<string, unknown> | undefined {
-  try {
-    const raw = JSON.parse(
-      readFileSync(join(runDirectory, "invocation.json"), "utf8"),
-    ) as unknown;
-    return isRecord(raw) ? raw : undefined;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") return undefined;
-    throw error;
-  }
+  return readPageSync(runDirectory, "invocation");
 }
 
-/** True when invocation.json carries a non-empty engine axis. */
+/** True when the invocation section carries a non-empty engine axis. */
 export async function readInvocationEngineMounted(
   runDirectory: string,
 ): Promise<boolean> {
@@ -288,16 +285,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/external-host-turn-loop.ts

@@ -13,8 +13,33 @@ import type { PreparedRoleTurn } from "./prepared-role-turn.ts";
 import { projectThrownFailureLeaf, retainPackageFault } from "./public-cli/settlement.ts";
 import { describeErrorIdentity } from "./public-cli/run-lifecycle.ts";
 import { deliveryLimitFromConfig } from "./receipt-delivery-policy.ts";
+import { reportRunRecord } from "./sitian-facade.ts";
 import { isOneShotWorkerReminderCode } from "./submission-errors.ts";
 
+/**
+ * What one host start was given: one `turn-delivery` row of history.jsonl per start. History is
+ * the volume whose write failure does not stop a run (#833), so a row that cannot be
+ * written is noted and the host still starts.
+ */
+export async function recordTurnDelivery(
+  runDirectory: string,
+  delivered: { readonly systemPrompt: string; readonly outputSchema?: unknown },
+  source: string,
+): Promise<void> {
+  try {
+    reportRunRecord(runDirectory, "turn-delivery", {
+      systemPrompt: delivered.systemPrompt,
+      ...(delivered.outputSchema === undefined ? {} : { outputSchema: delivered.outputSchema }),
+    }, source);
+  } catch (error) {
+    await retainPackageFault({
+      runDirectory,
+      diagnostic: `turn delivery record failed beside host start: ${describeErrorIdentity(error)}`,
+      error,
+    });
+  }
+}
+
 export type ExternalPreparedTurn = Pick<PreparedRoleTurn, "prompt" | "abortSignal" | "closeRound">;
 
 export type ExternalHostRoundOutcome =