@akagilnc/pi-workflow-roles 0.1.5478 → 0.1.5504

package/dist/session-assistant-usage.js

@@ -1,25 +1,16 @@
-import { join } from "node:path";
+import { ROLE_RUN_SESSION_FILENAME, sessionFileOf } from "./role-run-placement.js";
+import { readStrictPiSessionJsonl } from "./ledger-session-read.js";
 import { errorText } from "./unknown-value.js";
 export async function readAssistantUsageFromSessionFile(sessionFile) {
-    const { readFile } = await import("node:fs/promises");
-    let text;
+    let rows;
     try {
-        text = await readFile(sessionFile, "utf8");
+        rows = await readStrictPiSessionJsonl(sessionFile);
     }
     catch (error) {
         if (error?.code === "ENOENT")
             return undefined;
-        throw error;
-    }
-    let rows;
-    try {
-        rows = text
-            .trim()
-            .split("\n")
-            .filter(Boolean)
-            .map((line) => JSON.parse(line));
-    }
-    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
         throw new Error(`session usage parse failed (${sessionFile}): ${errorText(error)}`, { cause: error });
     }
     let total = 0;
@@ -82,11 +73,11 @@ export async function readAssistantUsageFromSessionFile(sessionFile) {
  */
 export function sessionFileFromPublicSummon(summoned) {
     if (typeof summoned.runDirectory === "string" && summoned.runDirectory.trim() !== "") {
-        return join(summoned.runDirectory, "session", "session.jsonl");
+        return sessionFileOf(summoned.runDirectory);
     }
     const fromArtifacts = summoned.terminal?.artifacts
         ?.map((a) => a.path)
-        .find((p) => typeof p === "string" && p.endsWith("session.jsonl"));
+        .find((p) => typeof p === "string" && p.endsWith(ROLE_RUN_SESSION_FILENAME));
     if (fromArtifacts !== undefined)
         return fromArtifacts;
     const outcome = summoned.terminal?.roleOutcome;
@@ -95,7 +86,7 @@ export function sessionFileFromPublicSummon(summoned) {
     const facts = outcome.decisiveFacts;
     const pointer = facts?.runPointer;
     if (typeof pointer === "string" && pointer.trim() !== "") {
-        return join(pointer, "session", "session.jsonl");
+        return sessionFileOf(pointer);
     }
     return undefined;
 }

package/dist/session-identity.js

@@ -1,5 +1,6 @@
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { writeFileAtomically } from "./atomic-write.js";
 import { DEFAULT_ROLE_TURN_HOST, lookupHeadlessHostDescription, lookupHostDescription, } from "./host-descriptions.js";
 /** Durable session binding stored beside the host-owned session principal. */
 export function createSessionIdentityAuthority(authority, sessionBindingFile) {
@@ -25,9 +26,7 @@ export function createSessionIdentityAuthority(authority, sessionBindingFile) {
         async bind(principal, sessionId) {
             const target = bindingPath(principal);
             await mkdir(dirname(target), { recursive: true });
-            const temporary = `${target}.${process.pid}.tmp`;
-            await writeFile(temporary, `${JSON.stringify({ sessionId })}\n`, { encoding: "utf8", mode: 0o600 });
-            await rename(temporary, target);
+            await writeFileAtomically(target, `${JSON.stringify({ sessionId })}\n`, { mode: 0o600 });
         },
     };
 }

package/dist/sitian-appender.js

@@ -1,6 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { appendFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { sessionDirectoryOf } from "./role-run-placement.js";
+import { ticketNumberFromSitianSubject } from "./run-ticket-number.js";
 import { resolveBookKeyFromGit } from "./activation-ledger-git.js";
 import {
   activationBookDirectory,
@@ -41,13 +43,22 @@ function resolveSitianVolumeCategory(kind) {
   return kind;
 }
 const SITIAN_RECORDS_LEAF = "records.jsonl";
+function sitianVolumeDirectory(sessionDirectory, category) {
+  return join(sessionDirectory, category);
+}
+function sitianRunVolumeDirectory(runDirectory, category) {
+  return sitianVolumeDirectory(sessionDirectoryOf(runDirectory), category);
+}
+function sitianVolumeRecordsFile(volumeDirectory) {
+  return join(volumeDirectory, SITIAN_RECORDS_LEAF);
+}
 function ticketProvenanceUnderBookPaths(ledgerHome, bookKey, ticketId) {
   const sessionDir = join(activationBookDirectory(ledgerHome, bookKey), ticketId);
-  return { sessionDir, recordFile: join(sessionDir, SITIAN_RECORDS_LEAF) };
+  return { sessionDir, recordFile: sitianVolumeRecordsFile(sessionDir) };
 }
 function resolveSitianRecordPathInLedger(input, ledgerHome) {
   const category = resolveSitianVolumeCategory(input.kind);
-  const ticketNumber = category === "ticket-provenance" ? typeof input.subject === "string" && /^[1-9][0-9]*$/.test(input.subject) ? input.subject : typeof input.subject === "object" && typeof input.subject.ticketNumber === "number" && Number.isSafeInteger(input.subject.ticketNumber) && input.subject.ticketNumber > 0 ? String(input.subject.ticketNumber) : void 0 : void 0;
+  const ticketNumber = category === "ticket-provenance" ? ticketNumberFromSitianSubject(input.subject) : void 0;
   let sessionDir;
   let recordFile;
   if (ticketNumber !== void 0) {
@@ -60,13 +71,13 @@ function resolveSitianRecordPathInLedger(input, ledgerHome) {
     recordFile = paths.recordFile;
   } else if (category === "ticket-provenance" && input.runDirectory !== void 0) {
     sessionDir = input.runDirectory;
-    recordFile = join(sessionDir, SITIAN_RECORDS_LEAF);
+    recordFile = sitianVolumeRecordsFile(sessionDir);
   } else {
     if (input.sessionParent === void 0 || input.sessionParent.length === 0 || !physicallyContainedIn(ledgerHome, input.sessionParent)) {
       throw new Error("Sitian record ownership requires a parent session inside the ledger home");
     }
-    sessionDir = join(dirname(input.sessionParent), category);
-    recordFile = join(sessionDir, SITIAN_RECORDS_LEAF);
+    sessionDir = sitianVolumeDirectory(dirname(input.sessionParent), category);
+    recordFile = sitianVolumeRecordsFile(sessionDir);
   }
   if (!physicallyContainedIn(ledgerHome, sessionDir)) {
     throw new Error("Sitian record ownership requires a directory inside the ledger home");
@@ -120,5 +131,8 @@ export {
   appendSitianRecordBlock,
   resolveSitianRecordPath,
   resolveSitianRecordPathInLedger,
-  resolveSitianVolumeCategory
+  resolveSitianVolumeCategory,
+  sitianRunVolumeDirectory,
+  sitianVolumeDirectory,
+  sitianVolumeRecordsFile
 };

package/dist/submission-ledger.js

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { sessionFileIn, sessionFileOf } from "./role-run-placement.js";
 import { resolveActivationLedgerHome, tryHomeFromAkRolesPath, } from "./activation-ledger-topology.js";
 import { courtAttemptIdFromHostContext, runDirectoryFromHostContext, } from "./host-contracts.js";
 import { runIdFromRunDirectory } from "./run-terminal-artifacts.js";
@@ -49,7 +49,7 @@ async function submissionRecordFile(cwd, runId, scope) {
         const discoveredRun = await findRunDirectoryById(scope.home, runId);
         if (discoveredRun === undefined)
             return undefined;
-        sessionParent = join(discoveredRun, "session", "session.jsonl");
+        sessionParent = sessionFileOf(discoveredRun);
     }
     return resolveSitianRecordPathInLedger({
         level: "event",
@@ -265,13 +265,13 @@ async function restoreState(cwd, runId, scope) {
 function sessionParentFromHostContext(context) {
     const runDirectory = runDirectoryFromHostContext(context);
     if (runDirectory !== undefined)
-        return join(runDirectory, "session", "session.jsonl");
+        return sessionFileOf(runDirectory);
     const sessionFile = context.sessionManager.getSessionFile?.();
     if (typeof sessionFile === "string" && sessionFile.length > 0)
         return sessionFile;
     const sessionDir = context.sessionManager.getSessionDir?.();
     if (typeof sessionDir === "string" && sessionDir.length > 0) {
-        return join(sessionDir, "session.jsonl");
+        return sessionFileIn(sessionDir);
     }
     return undefined;
 }

package/dist/ticket-provenance-contracts.js

@@ -1,3 +1,4 @@
+import { parseTicketNumber } from "./run-ticket-number.js";
 import { isRecord } from "./unknown-value.js";
 /**
  * 起居录（ticket-provenance）typed 形状 —— ADR 0075 / ADR 0081 / #1090。
@@ -9,14 +10,7 @@ import { isRecord } from "./unknown-value.js";
 /** Sitian kind for per-ticket court diary volumes. */
 export const TICKET_PROVENANCE_KIND = "ticket-provenance";
 function positiveInteger(value) {
-    if (typeof value === "number" && Number.isSafeInteger(value) && value >= 1)
-        return value;
-    if (typeof value === "string" && /^[1-9][0-9]*$/.test(value)) {
-        const parsed = Number(value);
-        if (Number.isSafeInteger(parsed))
-            return parsed;
-    }
-    return undefined;
+    return parseTicketNumber(value);
 }
 function projectBound(value) {
     if (!isRecord(value))

package/dist/ticket-provenance.js

@@ -4,10 +4,12 @@
  * 纯追加、不回读历史去重、不折叠。
  */
 import { readFile, unlink } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { errnoCode, packageMachineHome, physicallyContainedIn, resolveActivationLedgerHome, } from "./activation-ledger-topology.js";
 import { readLedgerSessionJsonlLines, } from "./ledger-session-read.js";
 import { isSafePositiveTicketNumber } from "./run-ticket-number.js";
+import { runDirectoryOfSessionFile, sessionFileOf } from "./role-run-placement.js";
+import { sitianVolumeRecordsFile } from "./sitian-appender.js";
 import { adaptSessionDialogue, nativeEventId } from "./session-dialogue.js";
 import { appendSitianRecordBlock, appendSitianRecord, resolveSitianRecordPath, } from "./sitian-facade.js";
 import { TICKET_PROVENANCE_KIND, } from "./ticket-provenance-contracts.js";
@@ -48,8 +50,7 @@ function isLedgerRoleSessionFile(absolute, home) {
     const ledgerHome = resolveActivationLedgerHome(machineHome);
     if (!physicallyContainedIn(ledgerHome, absolute))
         return false;
-    return (basename(absolute) === "session.jsonl" &&
-        basename(dirname(absolute)) === "session");
+    return sessionFileOf(runDirectoryOfSessionFile(absolute)) === absolute;
 }
 /** Real I/O seam gate: only host session stores or sitian role-run session.jsonl. */
 function assertDialogueSessionSourcePath(path, home) {
@@ -87,7 +88,7 @@ export function resolveTicketProvenanceVolume(ticketNumber, cwd, home) {
 }
 /** Assign a run-owned unbound diary as its original block through Sitian. */
 export async function rehomeUnboundTicketProvenance(runDirectory, ticketNumber, cwd, home) {
-    const source = join(runDirectory, "records.jsonl");
+    const source = sitianVolumeRecordsFile(runDirectory);
     let content;
     try {
         content = await readFile(source, "utf8");

package/package.json

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

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

@@ -1,8 +1,8 @@
-import { join } from "node:path";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 
 import type { RoleTurnHost, RoleTurnRequest, RoleTurnResult } from "../host-contracts.ts";
+import { sessionDirectoryOf } from "../role-run-placement.ts";
 import {
   createSerializedRoleTurnHost,
   driveExternalRoleTurnRounds,
@@ -496,7 +496,7 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
             host: config.hostName,
             sessionId,
             cwd: request.cwd,
-            sessionDirectory: join(request.runDirectory, "session"),
+            sessionDirectory: sessionDirectoryOf(request.runDirectory),
             sessionParent,
             continuation: request.continuation,
             ...(request.model !== undefined ? { model: request.model } : {}),

package/src/analyst-gate-cycles-read.ts

@@ -1,10 +1,8 @@
 /**
  * Sole nested-volume reader for gate-cycle facts under session/auditor-roles/.
  *
- * Consumers: Analyst sole ledger scan (classifyScopedRun) and Terminal gate
- * projection (#478). Metric families must not open a second disk scan — they
- * consume retained facts. Terminal settlement reuses this same pairing seam
- * (no second auditor-roles scanner).
+ * Consumer: Analyst sole ledger scan (classifyScopedRun). Metric families must
+ * not open a second disk scan — they consume retained facts.
  *
  * Naming: records may carry pre-#440 menxia/jishizhong/fubaolang tool faces or
  * the current gatekeeper/inspector/notary English face. Projection always uses
@@ -38,7 +36,10 @@ import {
   type LedgerSessionRow,
 } from "./ledger-session-read.ts";
 
-import { isRecord, errorText, isEnoent } from "./unknown-value.ts";
+import { isRecord, isEnoent } from "./unknown-value.ts";
+import { retainedRunPathsMatch } from "./role-run-relocation.ts";
+import { runDirectoryOfSessionFile } from "./role-run-placement.ts";
+import { resolveOfficerSessionFromPointerFile } from "./archivist-record-pointer.ts";
 
 /** One completed gate round: direct officer receipt or historical province/officer pair. */
 /** Honest origin discriminant: direct summons vs historical province dispatch. */
@@ -416,32 +417,6 @@ function pairGateRounds(
     .map((round, index) => ({ ...round, roundIndex: index + 1 }));
 }
 
-/** Resolve a direct-officer-run-pointer file to the officer session 正本 path. */
-async function resolveOfficerSessionFromPointerFile(
-  pointerPath: string,
-): Promise<{ sessionFile: string; officer?: "inspector" | "notary" }> {
-  const { readFile } = await import("node:fs/promises");
-  let raw: unknown;
-  try {
-    raw = JSON.parse(await readFile(pointerPath, "utf8"));
-  } catch (error) {
-    throw new Error(
-      `direct officer run pointer unreadable in ${pointerPath}: ${errorText(error)}`,
-      { cause: error },
-    );
-  }
-  if (!isRecord(raw) || raw.kind !== "direct-officer-run-pointer" || raw.version !== 1) {
-    throw new Error(`direct officer run pointer has unknown shape in ${pointerPath}`);
-  }
-  const sessionFile = raw.sessionFile;
-  if (typeof sessionFile !== "string" || sessionFile.trim() === "") {
-    throw new Error(`direct officer run pointer missing sessionFile in ${pointerPath}`);
-  }
-  const officer = raw.officer === "inspector" || raw.officer === "notary"
-    ? raw.officer : undefined;
-  return { sessionFile, ...(officer === undefined ? {} : { officer }) };
-}
-
 /**
  * Read and pair gate-cycle rounds from one or more auditor-roles directories.
  * Accepts historical nested JSONL volumes and #675 direct-officer-run-pointer
@@ -463,7 +438,7 @@ export async function readAnalystGateCyclesFromAuditorRoles(
   const volumes: ClassifiedVolume[] = [];
   // Same officer session pointed at N times (historical multi-mint pointers, or
   // one parent booking many leaves) must classify once — else each accepted
-  // seal is counted ×N in terminal gate-round (#753 acceptance A).
+  // seal is counted ×N in gate-cycle statistics (#753 acceptance A).
   const classifiedOfficerSessions = new Set<string>();
   for (const directory of directories) {
     let names: string[];
@@ -492,12 +467,14 @@ export async function readAnalystGateCyclesFromAuditorRoles(
         if (classifiedOfficerSessions.has(sessionPath)) continue;
         classifiedOfficerSessions.add(sessionPath);
       }
-      const classified = await classifyAuditorVolume(sessionPath, pointer?.officer);
+      const officer = pointer?.officer === "inspector" || pointer?.officer === "notary"
+        ? pointer.officer : undefined;
+      const classified = await classifyAuditorVolume(sessionPath, officer);
       for (const volume of classified) {
         if (
           options.parentSessionFile !== undefined &&
           volume.parentSessionFile !== undefined &&
-          volume.parentSessionFile !== options.parentSessionFile
+          !await retainedRunPathsMatch(volume.parentSessionFile, options.parentSessionFile, runDirectoryOfSessionFile(options.parentSessionFile))
         ) {
           continue;
         }

package/src/analyst-ledger.ts

@@ -21,9 +21,15 @@ import {
   physicalPathIdentity,
   resolveActivationLedgerHome,
 } from "./activation-ledger-topology.ts";
-import { listBookRunDirectories } from "./role-run-placement.ts";
+import {
+  listBookRunDirectories,
+  parseRunLeaf,
+  sessionFileOf,
+} from "./role-run-placement.ts";
+import { sitianRunVolumeDirectory } from "./sitian-appender.ts";
 import { autopsyWriterLock, readRoleRunIdentity } from "./public-cli/run-lifecycle.ts";
 import { readRunTicketNumber } from "./run-ticket-number.ts";
+import { rewriteRunDirectoryPathValue } from "./role-run-relocation.ts";
 import {
   extractSessionModelSequence,
   extractSessionTimestampSpan,
@@ -124,14 +130,6 @@ async function classifyGhostCandidate(input: {
   };
 }
 
-function parseRunDirectoryName(
-  name: string,
-): { runId: string; role: string } | undefined {
-  const at = name.lastIndexOf("@");
-  if (at <= 0 || at === name.length - 1) return undefined;
-  return { runId: name.slice(0, at), role: name.slice(at + 1) };
-}
-
 /**
  * Invocation scope faces used for issue 圈定 (C4 / #399).
  * projectRoot is retained for narrow path match and conflict facts;
@@ -222,12 +220,14 @@ async function resolveSessionFile(
       && typeof parsed.sessionFile === "string"
       && parsed.sessionFile.trim() !== ""
     ) {
-      return parsed.sessionFile;
+      return typeof parsed.runDirectory === "string"
+        ? rewriteRunDirectoryPathValue(parsed.sessionFile, parsed.runDirectory, runDirectory) as string
+        : parsed.sessionFile;
     }
   } catch (error) {
     if (!isMissingPathError(error)) throw error;
   }
-  return join(runDirectory, "session", "session.jsonl");
+  return sessionFileOf(runDirectory);
 }
 
 /**
@@ -579,9 +579,9 @@ async function classifyScopedRun(input: {
   // nested JSONL is page-local unreadable — never silently under-count rounds.
   let gateCycles: readonly AnalystGateCycleRound[];
   try {
-    const parentSessionFile = join(input.runDirectory, "session", "session.jsonl");
+    const parentSessionFile = sessionFileOf(input.runDirectory);
     gateCycles = await readAnalystGateCyclesFromAuditorRoles(
-      join(input.runDirectory, "session", "auditor-roles"),
+      sitianRunVolumeDirectory(input.runDirectory, "auditor-roles"),
       { parentSessionFile },
     );
   } catch (error) {
@@ -697,7 +697,7 @@ export async function scanAnalystIssueRuns(input: {
 
     for (const runDirectory of runDirectories) {
       const runName = basename(runDirectory);
-      const parsed = parseRunDirectoryName(runName);
+      const parsed = parseRunLeaf(runName);
       if (parsed === undefined) continue;
 
       let scopeFields: InvocationScopeFields | undefined;

package/src/archivist-record-entry.ts

@@ -31,6 +31,7 @@ import {
 } from "./archivist-record-topology.ts";
 import type { HostRecordSession, RecordSessionHost } from "./host-contracts.ts";
 import { piRecordSessionHost } from "./pi/record-session-host.ts";
+import { sitianVolumeDirectory } from "./sitian-appender.ts";
 export {
   DIRECT_OFFICER_RUN_POINTER_KIND,
   bookDirectOfficerRunPointer,
@@ -47,7 +48,7 @@ const CURRENT_SESSION_LEDGER = "current-session.json";
 type CurrentSessionRecord = { readonly sessionFile: string };
 
 function readCurrentSession(sessionDir: string): string {
-  const ledger = join(sessionDir, CURRENT_SESSION_LEDGER);
+  const ledger = currentSessionLedgerPath(sessionDir);
   try {
     const value: unknown = JSON.parse(readFileSync(ledger, "utf8"));
     if (
@@ -68,7 +69,7 @@ function readCurrentSession(sessionDir: string): string {
 }
 
 function writeCurrentSession(sessionDir: string, sessionFile: string): void {
-  const ledger = join(sessionDir, CURRENT_SESSION_LEDGER);
+  const ledger = currentSessionLedgerPath(sessionDir);
   try {
     writeFileSync(ledger, `${JSON.stringify({ sessionFile })}\n`, { flag: "wx" });
   } catch (error) {
@@ -420,7 +421,7 @@ export function createRecordSessionOpen(
     // Ordinary kinds: durable parent's file is the sole nesting authority. A divergent
     // SessionManager directory must not create a second placement route.
     // Do not restore generic bookDir/<kind> fallback for foreign/unrooted parents.
-    sessionDir = join(dirname(parentResolved), options.kind);
+    sessionDir = sitianVolumeDirectory(dirname(parentResolved), options.kind);
     parentSession = parentFile;
     mayResumeSameNest = options.kind === WORKER_SUBMISSION_GATE_KIND;
   }

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 { isRecord } from "./unknown-value.ts";
+import { basename, dirname, join } from "node:path";
+import { isRecord, errorText } from "./unknown-value.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, runDirectoryFromSessionDirectory } from "./role-run-placement.ts";
+import { sitianVolumeDirectory } from "./sitian-appender.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,6 +27,13 @@ export type DirectOfficerRunPointer = {
   readonly submissionToolCallId?: string;
 };
 
+function directOfficerRunPointerFile(
+  parentSessionFile: string,
+  officer: DirectOfficerRunPointer["officer"],
+): string {
+  return join(sitianVolumeDirectory(dirname(parentSessionFile), "auditor-roles"), `${officer}.pointer.json`);
+}
+
 /**
  * Book a typed pointer under parent session/auditor-roles (same nest owner as
  * createRecordSession). Never fabricates user/assistant/toolResult rows (#675).
@@ -28,7 +41,7 @@ export type DirectOfficerRunPointer = {
  *
  * 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.
+ * each re-scan the full officer session and multiply gate-cycle counts.
  */
 export function bookDirectOfficerRunPointer(options: {
   readonly parentSessionFile: string;
@@ -37,8 +50,8 @@ export function bookDirectOfficerRunPointer(options: {
   readonly runDirectory?: string;
   readonly submissionToolCallId?: string;
 }): DirectOfficerRunPointer {
-  const nest = join(dirname(options.parentSessionFile), "auditor-roles");
-  mkdirSync(nest, { recursive: true });
+  const pointerFile = directOfficerRunPointerFile(options.parentSessionFile, options.officer);
+  mkdirSync(dirname(pointerFile), { recursive: true });
   const submissionToolCallId = options.submissionToolCallId?.trim() ?? "";
   const pointer: DirectOfficerRunPointer = {
     version: 1,
@@ -51,46 +64,69 @@ export function bookDirectOfficerRunPointer(options: {
     ...(submissionToolCallId === "" ? {} : { submissionToolCallId }),
   };
   writeFileSync(
-    join(nest, `${options.officer}.pointer.json`),
+    pointerFile,
     `${JSON.stringify(pointer)}\n`,
     "utf8",
   );
   return pointer;
 }
 
-/**
- * Read the one officer pointer. Missing or unreadable is not a pass:
- * the caller re-runs the gate.
- */
+/** Shared strict pointer IO; internal audit wraps unreadability as a re-summons. */
+export async function resolveOfficerSessionFromPointerFile(pointerPath: string): Promise<{
+  sessionFile: string;
+  officer?: DirectOfficerRunPointer["officer"];
+  runDirectory?: string;
+  submissionToolCallId?: string;
+}> {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(await readFile(pointerPath, "utf8"));
+  } catch (error) {
+    throw new Error(`direct officer run pointer unreadable in ${pointerPath}: ${errorText(error)}`, { cause: error });
+  }
+  if (!isRecord(raw) || raw.kind !== DIRECT_OFFICER_RUN_POINTER_KIND || raw.version !== 1) {
+    throw new Error(`direct officer run pointer has unknown shape in ${pointerPath}`);
+  }
+  if (typeof raw.sessionFile !== "string" || raw.sessionFile.trim() === "") {
+    throw new Error(`direct officer run pointer missing sessionFile in ${pointerPath}`);
+  }
+  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 parentRunDirectory = runDirectoryFromSessionDirectory(dirname(dirname(pointerPath)));
+  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 }),
+  };
+}
+
+/** 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 pointer = await resolveOfficerSessionFromPointerFile(directOfficerRunPointerFile(parentSessionFile, officer));
+    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,8 +1,12 @@
-import { dirname, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 
 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 {
+  roleRunArtifactsDirectory,
+  runDirectoryOfSessionFile,
+  sessionFileOf,
+} from "./role-run-placement.ts";
 import { Type } from "typebox";
 
 export const AUDITOR_DOSSIER_TOOL_NAME = "ak_get_run_dossier" as const;
@@ -20,7 +24,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. */
@@ -44,7 +48,7 @@ export function createAuditorDossierTool(
       const details: AuditorDossierLocation = {
         runDirectory,
         admittedRequest: join(runDirectory, "admitted-request.json"),
-        parentSessionCandidate: join(runDirectory, "session", "session.jsonl"),
+        parentSessionCandidate: sessionFileOf(runDirectory),
         attachments: join(runDirectory, "attachments"),
         artifacts: roleRunArtifactsDirectory(runDirectory),
       };

package/src/auditor-soul.ts

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 
+import { parseRunLeaf } from "./role-run-placement.ts";
 import { isRecord } from "./unknown-value.ts";
 
 import {
@@ -109,7 +110,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;
 }