@akagilnc/pi-workflow-roles 0.1.4062 → 0.1.4196

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

@@ -0,0 +1,244 @@
+/**
+ * #865 T9: migrate retained runs into ticket-scoped or unbound placement.
+ * Inventory covers legacy flat `runs/`, existing `<ticket>/runs/`, and
+ * `unbound/runs/`. Attribution reuses the shared migrating-run helper;
+ * already-canonical trees copy as-is.
+ */
+import { cp, mkdir, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, sep } from "node:path";
+
+import {
+  destinationRunDirectory,
+  isMigrationEnoent,
+  isTicketNumberString,
+  listBackupRunLeaves,
+  listMigrationBookKeys,
+  resolveMigratingRunTicket,
+} from "./book-topology-migration-placement.ts";
+import {
+  reconcileMigrationPartition,
+  type BookTopologyMigrationContext,
+  type BookTopologyPartitionMigrator,
+  type MigrationItemOutcome,
+} from "./book-topology-migration.ts";
+import {
+  rewriteRoleRunDurablePages,
+  type RunDirectoryPathRewrite,
+} from "./role-run-relocation.ts";
+import { MIGRATION_TICKET_DERIVATION_PAGE } from "./run-ticket-number.ts";
+
+const RUNS_PARTITION = "runs";
+
+const RUN_LEAF =
+  /^([A-Za-z0-9][A-Za-z0-9._-]*)@([A-Za-z][A-Za-z0-9_-]*)$/;
+
+type RunLeaf = { readonly runId: string; readonly role: string };
+
+type PlannedRunMove = {
+  readonly sourcePath: string;
+  readonly sourceIdentity: string;
+  readonly isDirectory: boolean;
+  readonly disposition: "placed" | "unbound";
+  readonly targetPath: string;
+  readonly historicalRunDirectory: string | undefined;
+  readonly derivation:
+    | { readonly ticketNumber: number; readonly projectRoot: string; readonly sourcePage: string }
+    | undefined;
+};
+
+function parseRunLeaf(name: string): RunLeaf | undefined {
+  const match = RUN_LEAF.exec(name);
+  if (match === null) return undefined;
+  return { runId: match[1]!, role: match[2]! };
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (isMigrationEnoent(error)) return false;
+    throw error;
+  }
+}
+
+async function writeDerivationPage(
+  targetRunDirectory: string,
+  derivation: {
+    readonly ticketNumber: number;
+    readonly projectRoot: string;
+    readonly sourcePage: string;
+  },
+): Promise<void> {
+  const page = {
+    ticketNumber: derivation.ticketNumber,
+    derivation: "worktree-path-basename" as const,
+    source: {
+      page: derivation.sourcePage,
+      field: "projectRoot",
+      path: derivation.projectRoot,
+      basename: basename(derivation.projectRoot),
+    },
+  };
+  await writeFile(
+    join(targetRunDirectory, MIGRATION_TICKET_DERIVATION_PAGE),
+    `${JSON.stringify(page, null, 2)}\n`,
+    "utf8",
+  );
+}
+
+async function copyRunTree(
+  source: string,
+  target: string,
+  isDirectory: boolean,
+): Promise<void> {
+  await mkdir(dirname(target), { recursive: true });
+  if (isDirectory) {
+    await cp(source, target, { recursive: true, preserveTimestamps: true });
+    return;
+  }
+  await cp(source, target, { preserveTimestamps: true });
+}
+
+async function planBookMoves(
+  backupBooksDirectory: string,
+  booksDirectory: string,
+  bookKey: string,
+): Promise<readonly PlannedRunMove[]> {
+  const backupBook = join(backupBooksDirectory, bookKey);
+  const claimed = new Map<string, string>();
+  const planned: PlannedRunMove[] = [];
+
+  for (const leaf of await listBackupRunLeaves(backupBook)) {
+    const sourceIdentity = relative(backupBooksDirectory, leaf.sourcePath)
+      .split(sep)
+      .join("/");
+    const parsed = leaf.isDirectory ? parseRunLeaf(leaf.leafName) : undefined;
+
+    let targetPath: string;
+    let disposition: "placed" | "unbound";
+    let historicalRunDirectory: string | undefined;
+    let derivation: PlannedRunMove["derivation"];
+
+    if (leaf.layout === "issues") {
+      // issues/<ticket>/runs/<leaf> → <ticket>/runs/<leaf>; conflict refuses below.
+      const parts = leaf.relativePath.replaceAll("\\", "/").split("/");
+      const ticketStr = parts[1];
+      if (ticketStr !== undefined && isTicketNumberString(ticketStr)) {
+        targetPath = join(booksDirectory, bookKey, ticketStr, "runs", leaf.leafName);
+        disposition = "placed";
+        historicalRunDirectory = join(
+          booksDirectory,
+          bookKey,
+          "issues",
+          ticketStr,
+          "runs",
+          leaf.leafName,
+        );
+      } else {
+        targetPath = join(booksDirectory, bookKey, "unbound", "runs", leaf.leafName);
+        disposition = "unbound";
+        historicalRunDirectory = join(booksDirectory, bookKey, leaf.relativePath);
+      }
+      derivation = undefined;
+    } else if (leaf.layout !== "flat") {
+      targetPath = join(booksDirectory, bookKey, leaf.relativePath);
+      disposition = leaf.layout === "unbound" ? "unbound" : "placed";
+      historicalRunDirectory = undefined;
+      derivation = undefined;
+    } else if (parsed === undefined) {
+      targetPath = join(booksDirectory, bookKey, "unbound", "runs", leaf.leafName);
+      disposition = "unbound";
+      historicalRunDirectory = join(booksDirectory, bookKey, "runs", leaf.leafName);
+      derivation = undefined;
+    } else {
+      const ticket = await resolveMigratingRunTicket(leaf.sourcePath);
+      targetPath = destinationRunDirectory(
+        booksDirectory,
+        bookKey,
+        ticket.ticketNumber,
+        parsed.runId,
+        parsed.role,
+      );
+      disposition = ticket.ticketNumber === undefined ? "unbound" : "placed";
+      historicalRunDirectory = join(booksDirectory, bookKey, "runs", leaf.leafName);
+      derivation =
+        ticket.derivation?.method === "project-root-basename"
+          && ticket.ticketNumber !== undefined
+          ? {
+              ticketNumber: ticket.ticketNumber,
+              projectRoot: ticket.derivation.source,
+              sourcePage: ticket.derivation.sourcePage,
+            }
+          : undefined;
+    }
+
+    const prior = claimed.get(targetPath);
+    if (prior !== undefined) {
+      throw new Error(
+        `book topology migration refuses to overwrite ${targetPath} (already claimed by ${prior}) with ${leaf.sourcePath}`,
+      );
+    }
+    claimed.set(targetPath, leaf.sourcePath);
+    planned.push({
+      sourcePath: leaf.sourcePath,
+      sourceIdentity,
+      isDirectory: leaf.isDirectory,
+      disposition,
+      targetPath,
+      historicalRunDirectory,
+      derivation,
+    });
+  }
+  return planned;
+}
+
+export const bookTopologyRunsMigrator: BookTopologyPartitionMigrator = {
+  partition: RUNS_PARTITION,
+  async migrate(context: BookTopologyMigrationContext) {
+    const outcomes: MigrationItemOutcome[] = [];
+    const { backupBooksDirectory, booksDirectory } = context;
+
+    for (const bookKey of await listMigrationBookKeys(backupBooksDirectory)) {
+      const planned = await planBookMoves(
+        backupBooksDirectory,
+        booksDirectory,
+        bookKey,
+      );
+
+      const crossRunRewrites: RunDirectoryPathRewrite[] = planned
+        .filter((move) => move.isDirectory && move.historicalRunDirectory !== undefined)
+        .map((move) => ({
+          oldRunDirectory: move.historicalRunDirectory!,
+          newRunDirectory: move.targetPath,
+        }));
+
+      for (const move of planned) {
+        if (await pathExists(move.targetPath)) {
+          throw new Error(
+            `book topology migration refuses to overwrite ${move.targetPath} with ${move.sourcePath}`,
+          );
+        }
+        await copyRunTree(move.sourcePath, move.targetPath, move.isDirectory);
+        if (move.isDirectory) {
+          await rewriteRoleRunDurablePages({
+            pagesDirectory: move.targetPath,
+            oldRunDirectory: move.historicalRunDirectory ?? move.targetPath,
+            newRunDirectory: move.targetPath,
+            crossRunRewrites,
+          });
+        }
+        if (move.isDirectory && move.derivation !== undefined) {
+          await writeDerivationPage(move.targetPath, move.derivation);
+        }
+
+        outcomes.push({
+          disposition: move.disposition,
+          source: move.sourceIdentity,
+        });
+      }
+    }
+
+    return reconcileMigrationPartition(RUNS_PARTITION, "entries", outcomes);
+  },
+};

package/src/diarist-contracts.ts

@@ -12,6 +12,10 @@ import type {
   TicketProvenanceSourceKind,
   TicketProvenanceSourceRef,
 } from "./ticket-provenance-contracts.ts";
+import {
+  isSafePositiveTicketNumber,
+  requireSafePositiveTicketNumber,
+} from "./run-ticket-number.ts";
 
 export const DIARIST_OUTPUT_TOOL_NAME = "ak_diarist_output";
 export const DIARIST_ACCEPTED_TEXT = "起居郎回执已接受";
@@ -39,6 +43,15 @@ export type DiaristOutput =
        * LLM owns recognition; mechanical layer does not re-judge the number.
        */
       readonly ticketNumber?: number | null;
+      /**
+       * #871 typed co-review set (ADR 0075 `diarist-resolves-ticket-llm-layer` narrow extension).
+       * Positive integers = tickets that should each receive a diary this court (includes main).
+       * Field absent → no new set this turn (resume keeps stored run fact; first court defaults to [main]).
+       * Explicit empty array → single-ticket face [main] whole-set replace.
+       * Non-empty with zero lawful members after type projection is not a new set (call site).
+       * Mechanical layer only type-projects/dedupes and guarantees principal membership when applying a set.
+       */
+      readonly courtTicketNumbers?: readonly number[] | null;
       /** Whole blocks to append under the asserted ticket. Empty list is lawful. */
       readonly entries?: readonly DiaristEntrySubmission[];
     }
@@ -48,6 +61,109 @@ export type DiaristOutput =
       readonly reason: string;
     };
 
+/**
+ * Sole shape projection for a typed co-review ticket set (#871).
+ * Positive safe integers, first-seen order, duplicates dropped. Not content judgment.
+ * Returns null when `raw` is not an array (callers classify absent vs durable damage).
+ * Returns a possibly empty list when `raw` is an array (unlawful members skipped).
+ * When `principalTicket` is set, that ticket is guaranteed as a member (prepended if missing).
+ */
+export function projectCourtTicketNumbers(
+  raw: unknown,
+  options?: { readonly principalTicket?: number },
+): readonly number[] | null {
+  if (!Array.isArray(raw)) return null;
+  const out: number[] = [];
+  const seen = new Set<number>();
+  for (const item of raw) {
+    if (!isSafePositiveTicketNumber(item)) continue;
+    if (seen.has(item)) continue;
+    seen.add(item);
+    out.push(item);
+  }
+  const principal = options?.principalTicket;
+  if (principal === undefined) return out;
+  requireSafePositiveTicketNumber(principal, "projectCourtTicketNumbers principalTicket");
+  if (seen.has(principal)) return out;
+  return [principal, ...out];
+}
+
+/**
+ * Durable-field interpreter for #871 co-review sets.
+ * Absent key (old-format run) is not damage. Present but empty / non-array /
+ * partially unlawful / missing principal is damage — callers must fail closed,
+ * never wash into main-only.
+ */
+export function interpretDurableCourtTicketNumbers(
+  record: Record<string, unknown>,
+  options?: { readonly principalTicket?: number },
+):
+  | { readonly kind: "absent" }
+  | { readonly kind: "ok"; readonly tickets: readonly number[] }
+  | { readonly kind: "damage"; readonly reason: string } {
+  if (!Object.hasOwn(record, "courtTicketNumbers")) {
+    return { kind: "absent" };
+  }
+  const raw = record.courtTicketNumbers;
+  if (!Array.isArray(raw)) {
+    return {
+      kind: "damage",
+      reason: "courtTicketNumbers is present but not an array",
+    };
+  }
+  if (raw.length === 0) {
+    return {
+      kind: "damage",
+      reason: "courtTicketNumbers is present but empty",
+    };
+  }
+  for (let i = 0; i < raw.length; i += 1) {
+    const item = raw[i];
+    if (!isSafePositiveTicketNumber(item)) {
+      return {
+        kind: "damage",
+        reason: `courtTicketNumbers[${i}] is not a safe positive integer`,
+      };
+    }
+  }
+  // Members are all lawful numbers; sole projection owns dedupe/order.
+  const tickets = projectCourtTicketNumbers(raw);
+  if (tickets === null || tickets.length === 0) {
+    return {
+      kind: "damage",
+      reason: "courtTicketNumbers projected empty after lawful members",
+    };
+  }
+  const principal = options?.principalTicket;
+  if (principal !== undefined) {
+    if (!isSafePositiveTicketNumber(principal)) {
+      return {
+        kind: "damage",
+        reason: "courtTicketNumbers principal ticket is not a safe positive integer",
+      };
+    }
+    if (!tickets.includes(principal)) {
+      return {
+        kind: "damage",
+        reason: `courtTicketNumbers is missing principal ticket #${principal}`,
+      };
+    }
+  }
+  return { kind: "ok", tickets: Object.freeze([...tickets]) };
+}
+
+/** True when two durable #871 sets are byte-identical sequences. */
+export function sameCourtTicketNumbers(
+  left: readonly number[],
+  right: readonly number[],
+): boolean {
+  if (left.length !== right.length) return false;
+  for (let i = 0; i < left.length; i += 1) {
+    if (left[i] !== right[i]) return false;
+  }
+  return true;
+}
+
 export function validateRecordedDiaristOutput(value: unknown): DiaristOutput {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     throw new Error("Diarist output has no execution discriminator");

package/src/diarist-role.ts

@@ -35,6 +35,12 @@ export const diaristOutputSchema = withInfrastructureFailureDeclaration(
             "本庭对象票号（正整数）或 null/省略＝真无票；下游走 typed 键；认不出用 status=escalate，不洗成无录。机械层不重判。",
         }),
       ),
+      courtTicketNumbers: Type.Optional(
+        Type.Unknown({
+          description:
+            "#871 本次合审应各自成录的票号集合（正整数数组，含主票）；单票可省略。机械层只做类型/去重投影，不从散文猜票。",
+        }),
+      ),
       reason: Type.Optional(
         Type.String({
           description: "status 为 escalate 时：认不出本庭对象的原因",

package/src/diarist.ts

@@ -42,6 +42,7 @@ export type DiaristCommitFacts = {
 export async function commitDiaristEntries(input: {
   readonly ticketNumber: number;
   readonly cwd: string;
+  readonly sessionParent: string;
   readonly home?: string;
   readonly entries: readonly unknown[];
 }): Promise<DiaristCommitFacts> {
@@ -59,6 +60,7 @@ export async function commitDiaristEntries(input: {
     appendTicketProvenanceEntry({
       ticketNumber,
       cwd,
+      sessionParent: input.sessionParent,
       ...homeOpt,
       payload: submitted,
       source: "diarist",

package/src/doctor-evidence.ts

@@ -37,7 +37,10 @@ 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> {
-  const root = await realpath(runsPath); 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>/issues/<n>/runs directory");
+  const root = await realpath(runsPath);
+  // 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); }

package/src/doctor-role.ts

@@ -8,7 +8,7 @@ import { DOCTOR_ACCEPTED_AUDIT_NO_RECEIPT_TEXT, DOCTOR_ACCEPTED_TEXT, DOCTOR_EVI
 import { sitianReport } from "./sitian-facade.ts";
 
 export { DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME };
-export const DOCTOR_CASE_FLAG = { name: "ak-doctor-case", definition: { description: "Retained .ak-roles/books/<book>/issues/<n>/runs directory", type: "string" as const } } as const;
+export const DOCTOR_CASE_FLAG = { name: "ak-doctor-case", definition: { description: "Retained .ak-roles/books/<book>/<n>/runs directory", type: "string" as const } } as const;
 export type DoctorRoleDependencies = { loadSoul(): Promise<string>; loadCase(path: string): Promise<DoctorCase>; auditCompliance(options: { context: HostContext; signal?: AbortSignal }): Promise<ComplianceDecision> };
 function appendCandidate(ctx: HostContext, data: unknown): void {
   try {

package/src/navigator-public-session.ts

@@ -17,6 +17,29 @@ import {
   type NavigatorSessionFactory,
 } from "./navigator-session-contracts.ts";
 import type { NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
+import { runDirectoryFromHostContext, type HostContext } from "./host-contracts.ts";
+
+/**
+ * Ledger process home for navigator attendance: admitted HostContext.runDirectory
+ * first, else a parent session file under .ak-roles. Never context.home / env HOME /
+ * passwd guesses — those split the nest from the owning run (#852).
+ */
+async function resolveNavigatorLedgerHome(context: HostContext): Promise<string | undefined> {
+  const { tryHomeFromAkRolesPath } = await import(
+    "./activation-ledger-topology.ts"
+  );
+  const runDirectory = runDirectoryFromHostContext(context);
+  if (runDirectory !== undefined) {
+    const fromRun = tryHomeFromAkRolesPath(runDirectory);
+    if (fromRun !== undefined && fromRun.length > 0) return fromRun;
+  }
+  const parentFile = context.sessionManager?.getSessionFile?.();
+  if (typeof parentFile === "string" && parentFile.trim() !== "") {
+    const fromParent = tryHomeFromAkRolesPath(parentFile);
+    if (fromParent !== undefined && fromParent.length > 0) return fromParent;
+  }
+  return undefined;
+}
 
 export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
   return async ({ context, subject, tool }) => {
@@ -24,12 +47,17 @@ export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
     let thinkingLevel = resolved.thinkingLevel;
 
     // Archivist nest for attendance route memory only (ADR 0018 / 0065) — not a session open.
-    const { createRecordSession } = await import("./archivist-record-entry.ts");
+    // #852: navigator/<work-subject> is the sole book-top exception; always pass subject so
+    // unmaterialized/missing parent still gets a durable nest instead of silent in-memory.
+    // Home comes from HostContext.runDirectory (or ledger parent path) — never context.home.
+    const { createRecordSession, NAVIGATOR_RECORD_KIND } = await import("./archivist-record-entry.ts");
+    const home = await resolveNavigatorLedgerHome(context);
     const sessionManager = createRecordSession({
       cwd: context.cwd,
-      kind: "navigator",
+      kind: NAVIGATOR_RECORD_KIND,
       subject,
-      parent: context.sessionManager,
+      ...(context.sessionManager !== undefined ? { parent: context.sessionManager } : {}),
+      ...(home !== undefined ? { home } : {}),
     });
 
     let providerFailure: NavigatorProviderFailureFact | undefined;
@@ -37,31 +65,6 @@ export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
     let disposed = false;
     let inFlightPrompt: Promise<unknown> | undefined;
 
-    const resolveHome = async (): Promise<string | undefined> => {
-      const parentFile = context.sessionManager?.getSessionFile?.();
-      if (typeof parentFile === "string" && parentFile.trim() !== "") {
-        try {
-          const { tryHomeFromAkRolesPath, homeFromRunDirectory } = await import(
-            "./activation-ledger-topology.ts"
-          );
-          const fromParent = tryHomeFromAkRolesPath(parentFile);
-          if (fromParent !== undefined && fromParent.length > 0) return fromParent;
-          const runDir = parentFile.replace(/\/session\/session\.jsonl$/, "");
-          if (runDir !== parentFile) {
-            try {
-              return homeFromRunDirectory(runDir);
-            } catch {
-              // fall through
-            }
-          }
-        } catch {
-          // fall through
-        }
-      }
-      const envHome = process.env.HOME;
-      return typeof envHome === "string" && envHome.trim() !== "" ? envHome : undefined;
-    };
-
     return {
       prompt: async (text) => {
         if (disposed) {
@@ -72,13 +75,13 @@ export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
         const run = (async () => {
         try {
           const { summonPublicRole } = await import("./public-role-summons.ts");
-          const home = await resolveHome();
+          const summonHome = await resolveNavigatorLedgerHome(context);
           // Public activation — same face as `ak-role navigator <instruction>` (#675).
           const summoned = await summonPublicRole({
             role: "navigator",
             argv: [text],
             cwd: context.cwd,
-            ...(home === undefined ? {} : { home }),
+            ...(summonHome === undefined ? {} : { home: summonHome }),
           });
 
           const outcome = summoned.terminal?.roleOutcome;

package/src/notary-source-run.ts

@@ -13,7 +13,7 @@ import {
   resolveActivationLedgerHome,
 } from "./activation-ledger-topology.ts";
 import type { NotarySourceRunLocator } from "./notary-contracts.ts";
-import { readRoleRunIdentity } from "./public-cli/run-lifecycle.ts";
+import { findRunDirectoryById, readRoleRunIdentity } from "./public-cli/run-lifecycle.ts";
 
 // Run directory leaf: <runId>@<role>. Production uses uuidv7 runIds; offline tracers
 // may use deterministic non-uuid leaves. Role token stays identifier-shaped.
@@ -92,7 +92,8 @@ export async function resolveNotarySourceRunLocator(options: {
   let candidate: string;
   const bare = parseRunDirectoryName(raw);
   if (bare !== undefined && !raw.includes("/") && !raw.includes("\\")) {
-    candidate = join(bookRunsRoot, `${bare.runId}@${bare.role}`);
+    candidate = (await findRunDirectoryById(options.home, bare.runId, bookKey, bare.role))
+      ?? join(bookRunsRoot, `${bare.runId}@${bare.role}`);
   } else {
     candidate = isAbsolute(raw) ? raw : resolve(options.projectRoot, raw);
   }
@@ -100,9 +101,13 @@ export async function resolveNotarySourceRunLocator(options: {
   const real = await requireRunDirectory(candidate, raw);
   const identity = parseRunDirectoryName(basename(real))!;
 
-  const runsRootIdentity = physicalPathIdentity(bookRunsRoot);
+  const bookIdentity = physicalPathIdentity(activationBookDirectory(ledgerHome, bookKey));
   const parentIdentity = physicalPathIdentity(dirname(real));
-  if (parentIdentity !== runsRootIdentity) {
+  const subjectBookIdentity = physicalPathIdentity(dirname(dirname(dirname(real))));
+  if (
+    parentIdentity !== physicalPathIdentity(bookRunsRoot) &&
+    !(basename(dirname(real)) === "runs" && subjectBookIdentity === bookIdentity)
+  ) {
     throw new NotarySourceRunError(
       "notary --source-run must resolve to a retained run under the project machine-ledger book",
     );

package/src/pi/durable-principal.ts

@@ -8,10 +8,8 @@ import type {
   NewDurablePrincipalRequest,
 } from "../host-contracts.ts";
 import { resolveBookKeyFromGit } from "../activation-ledger-git.ts";
-import {
-  activationBookDirectory,
-  resolveActivationLedgerHome,
-} from "../activation-ledger-topology.ts";
+import { resolveActivationLedgerHome } from "../activation-ledger-topology.ts";
+import { roleRunPlacement } from "../role-run-placement.ts";
 
 type PiDurablePrincipal = DurablePrincipal & {
   readonly sessionDirectory: string;
@@ -31,18 +29,16 @@ export function issuePiDurablePrincipalCoordinates(
 } {
   const ledgerHome = resolveActivationLedgerHome(request.home);
   const bookKey = resolveBookKeyFromGit(request.cwd);
-  const runDirectory = join(
-    activationBookDirectory(ledgerHome, bookKey),
-    "runs",
-    `${request.runId}@${request.role}`,
-  );
-  const sessionDirectory = join(runDirectory, "session");
+  const placement = roleRunPlacement(ledgerHome, {
+    bookKey,
+    subject: { unbound: true },
+    runId: request.runId,
+    role: request.role,
+  });
   return {
     ledgerHome,
     bookKey,
-    runDirectory,
-    sessionDirectory,
-    sessionFile: join(sessionDirectory, "session.jsonl"),
+    ...placement,
   };
 }
 

package/src/public-cli/auto-resume.ts

@@ -16,6 +16,7 @@ import { randomUUID } from "node:crypto";
 import { lstat, mkdir, open } from "node:fs/promises";
 import { join } from "node:path";
 
+import { roleRunArtifactsDirectory } from "../role-run-placement.ts";
 import type {
   DurablePrincipal,
   DurablePrincipalAuthority,
@@ -143,11 +144,6 @@ export class TurnDispatchedFailure extends Error {
 /** Session custom-entry type carrying the pointer to one dispatch error file. */
 export const DISPATCH_ERROR_RETENTION_ENTRY_TYPE = "ak_run_dispatch_error_retention" as const;
 
-/** Artifacts subdirectory of a run directory (established run-artifacts location). */
-function runArtifactsDirectory(runDirectory: string): string {
-  return join(runDirectory, "artifacts");
-}
-
 /**
  * #182-A hardened path identity, mirrored from settlement.ts's
  * ensureAuditEvidenceDirectory: a planted symlink at the run directory or the
@@ -163,7 +159,7 @@ export async function ensureRealArtifactsDirectory(runDirectory: string): Promis
   if (runStat.isSymbolicLink() || !runStat.isDirectory()) {
     throw new Error("run artifact retention: run directory is not a real directory");
   }
-  const artifactsDir = runArtifactsDirectory(runDirectory);
+  const artifactsDir = roleRunArtifactsDirectory(runDirectory);
   try {
     const existing = await lstat(artifactsDir);
     if (existing.isSymbolicLink() || !existing.isDirectory()) {