@akagilnc/pi-workflow-roles 0.1.3412 → 0.1.3439

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

@@ -33,9 +33,12 @@ import {
 } from "./compliance-transport.ts";
 import {
   extractSessionTimestampSpan,
+  intervalRowsAroundAnchor,
+  LedgerSessionJsonlError,
   readLedgerSessionJsonl,
   type LedgerSessionRow,
 } from "./ledger-session-read.ts";
+import { isTicketSeatRunBindingRow } from "./ticket-seat-memory.ts";
 
 /** One completed gate round: direct officer receipt or historical province/officer pair. */
 /** Honest origin discriminant: direct summons vs historical province dispatch. */
@@ -91,17 +94,17 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/** Typed parent-attempt id from ak_auditor_parent_attempt_binding — durable invocation association. */
-function extractAttemptEntryId(rows: readonly LedgerSessionRow[]): string | undefined {
-  for (const row of rows) {
-    if (row.type !== "custom" || row.customType !== AUDITOR_PARENT_ATTEMPT_BINDING_ENTRY_TYPE) continue;
-    if (!isRecord(row.data) || !isRecord(row.data.parent)) continue;
-    const id = row.data.parent.attemptEntryId;
-    if (typeof id === "string" && id.length > 0) return id;
-  }
-  return undefined;
+function isParentAttemptBindingRow(row: LedgerSessionRow): boolean {
+  return row.type === "custom" && row.customType === AUDITOR_PARENT_ATTEMPT_BINDING_ENTRY_TYPE;
 }
 
+/** One summons' interval via shared #636 binding-slice (parent-attempt markers). */
+function intervalRowsForGateCall(
+  rows: readonly LedgerSessionRow[],
+  callRowIndex: number,
+): readonly LedgerSessionRow[] {
+  return intervalRowsAroundAnchor(rows, callRowIndex, isParentAttemptBindingRow).rows;
+}
 
 /** Only true absence (ENOENT). ENOTDIR is damaged topology — must stay loud. */
 function isMissingDirectoryError(error: unknown): boolean {
@@ -160,44 +163,6 @@ function acceptedGateReceiptIds(
   return accepted;
 }
 
-/**
- * Last accepted gate terminating toolCall on a nested volume (dispatch or officer).
- * Preference: keep the last accepted receipt; fall back to a rejected call only
- * when no accepted receipt exists (so classify can lawfully omit). Identity only
- * — typed args are validated after recognition so unusable facts fail loud
- * instead of being skipped as "not a gate volume". Soul-audit and other non-gate
- * tools never qualify.
- */
-function extractLastGateToolCall(
-  rows: readonly LedgerSessionRow[],
-): GateToolCall | undefined {
-  const acceptedIds = acceptedGateReceiptIds(rows);
-  let lastAccepted: GateToolCall | undefined;
-  let lastRejected: GateToolCall | undefined;
-  for (const row of rows) {
-    const message = isRecord(row.message) ? row.message : undefined;
-    if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
-    for (const part of message.content) {
-      if (!isRecord(part) || part.type !== "toolCall") continue;
-      if (typeof part.id !== "string" || part.id.length === 0) continue;
-      if (typeof part.name !== "string" || part.name.length === 0) continue;
-      if (!isGateTerminatingToolName(part.name)) continue;
-      const call: GateToolCall = {
-        toolName: part.name,
-        args: isRecord(part.arguments) ? part.arguments : undefined,
-        accepted: acceptedIds.has(part.id),
-      };
-      if (call.accepted) {
-        lastAccepted = call;
-      } else if (lastAccepted === undefined) {
-        // Only retain rejected while no accepted receipt has appeared yet.
-        lastRejected = call;
-      }
-    }
-  }
-  return lastAccepted ?? lastRejected;
-}
-
 function requireAcceptedGateStatus(
   args: Record<string, unknown> | undefined,
   filePath: string,
@@ -243,6 +208,8 @@ type ClassifiedVolume =
       readonly reason?: string;
       /** Present only when the volume carries ak_auditor_parent_attempt_binding. */
       readonly attemptEntryId?: string;
+      /** Binding parent session file when present (#636 multi-parent memory filter). */
+      readonly parentSessionFile?: string;
     }
   | {
       readonly kind: "officer";
@@ -254,30 +221,81 @@ type ClassifiedVolume =
       readonly findingsCount: number;
       readonly officerWallMs: number;
       readonly attemptEntryId?: string;
+      readonly parentSessionFile?: string;
     };
 
-async function classifyAuditorVolume(
-  filePath: string,
-): Promise<ClassifiedVolume | undefined> {
-  // Canonical JSONL errors propagate — failure honesty (never wash to fewer rounds).
-  const rows = await readLedgerSessionJsonl(filePath);
-  // Recognize gate tool first. Non-gate volumes stay omitted; rejected gate
-  // receipts omit before accepted-only span/status validation; once an accepted
-  // receipt is present, required typed facts must not silently under-count.
-  const call = extractLastGateToolCall(rows);
-  if (call === undefined) return undefined;
+/** Nearest preceding attempt binding (id + parent session file) before row index. */
+function nearestAttemptBindingBefore(
+  rows: readonly LedgerSessionRow[],
+  beforeIndex: number,
+): { readonly attemptEntryId?: string; readonly parentSessionFile?: string } {
+  for (let i = beforeIndex - 1; i >= 0; i -= 1) {
+    const row = rows[i]!;
+    if (!isParentAttemptBindingRow(row)) continue;
+    if (!isRecord(row.data) || !isRecord(row.data.parent)) continue;
+    const id = row.data.parent.attemptEntryId;
+    const sessionFile = row.data.parent.sessionFile;
+    return {
+      ...(typeof id === "string" && id.length > 0 ? { attemptEntryId: id } : {}),
+      ...(typeof sessionFile === "string" && sessionFile.length > 0
+        ? { parentSessionFile: sessionFile }
+        : {}),
+    };
+  }
+  return {};
+}
 
-  const attemptEntryId = extractAttemptEntryId(rows);
-  if (!call.accepted) {
-    // Rejected historical dispatch is not a pairing key — omit it so a later
-    // independent direct officer summons remains its own round. Span is not
-    // validated here: accepted-only contract must not throw on rejected volumes.
-    return undefined;
+/**
+ * All accepted gate terminating toolCalls on a volume (dispatch or officer),
+ * each with nearest preceding attempt binding. Ticket-seat continuous memory
+ * (#636) may carry multiple parent summons in one file — last-only would drop rounds.
+ */
+function extractAllAcceptedGateToolCalls(
+  rows: readonly LedgerSessionRow[],
+): ReadonlyArray<GateToolCall & { readonly rowIndex: number; readonly attemptEntryId?: string; readonly parentSessionFile?: string }> {
+  const acceptedIds = acceptedGateReceiptIds(rows);
+  const out: Array<GateToolCall & { readonly rowIndex: number; readonly attemptEntryId?: string; readonly parentSessionFile?: string }> = [];
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+    const row = rows[rowIndex]!;
+    const message = isRecord(row.message) ? row.message : undefined;
+    if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
+    for (const part of message.content) {
+      if (!isRecord(part) || part.type !== "toolCall") continue;
+      if (typeof part.id !== "string" || part.id.length === 0) continue;
+      if (typeof part.name !== "string" || part.name.length === 0) continue;
+      if (!isGateTerminatingToolName(part.name)) continue;
+      if (!acceptedIds.has(part.id)) continue;
+      const binding = nearestAttemptBindingBefore(rows, rowIndex);
+      out.push({
+        toolName: part.name,
+        args: isRecord(part.arguments) ? part.arguments : undefined,
+        accepted: true,
+        rowIndex,
+        ...binding,
+      });
+    }
   }
-  const span = requireAcceptedGateSpan(rows, filePath);
+  return out;
+}
+
+function projectAcceptedGateCall(
+  filePath: string,
+  rows: readonly LedgerSessionRow[],
+  call: GateToolCall & {
+    readonly rowIndex: number;
+    readonly attemptEntryId?: string;
+    readonly parentSessionFile?: string;
+  },
+): ClassifiedVolume | undefined {
+  // Continuous memory volumes carry many summons; span only this binding's interval.
+  const span = requireAcceptedGateSpan(intervalRowsForGateCall(rows, call.rowIndex), filePath);
   const status = requireAcceptedGateStatus(call.args, filePath);
   const findings = asStringFindings(call.args?.findings);
   const findingsCount = findings.length;
+  const bindingFields = {
+    ...(call.attemptEntryId === undefined ? {} : { attemptEntryId: call.attemptEntryId }),
+    ...(call.parentSessionFile === undefined ? {} : { parentSessionFile: call.parentSessionFile }),
+  };
 
   if (DISPATCH_TOOLS.has(call.toolName)) {
     // Lawful province non-dispatch release — opens no round, never unreadable (#597).
@@ -303,7 +321,7 @@ async function classifyAuditorVolume(
       officer,
       status,
       ...(reason === undefined ? {} : { reason }),
-      ...(attemptEntryId === undefined ? {} : { attemptEntryId }),
+      ...bindingFields,
     };
   }
 
@@ -323,10 +341,41 @@ async function classifyAuditorVolume(
     findings,
     findingsCount,
     officerWallMs: span.wallMs,
-    ...(attemptEntryId === undefined ? {} : { attemptEntryId }),
+    ...bindingFields,
   };
 }
 
+async function classifyAuditorVolume(
+  filePath: string,
+): Promise<readonly ClassifiedVolume[]> {
+  // Canonical JSONL errors propagate — failure honesty (never wash to fewer rounds).
+  // Shared ticket-seat main volumes are the exception: later-run damage after a
+  // closed binding must not erase earlier gate rounds (same ownership rule as
+  // timeline attribution). Pure nested gate volumes without run bindings stay loud.
+  let rows: readonly LedgerSessionRow[];
+  try {
+    rows = await readLedgerSessionJsonl(filePath);
+  } catch (error) {
+    if (
+      error instanceof LedgerSessionJsonlError
+      && error.prefixRows.some((row) => isTicketSeatRunBindingRow(row))
+    ) {
+      rows = error.prefixRows;
+    } else {
+      throw error;
+    }
+  }
+  const accepted = extractAllAcceptedGateToolCalls(rows);
+  // Rejected-only / non-gate volumes omit (empty accepted set).
+  if (accepted.length === 0) return [];
+  const volumes: ClassifiedVolume[] = [];
+  for (const call of accepted) {
+    const projected = projectAcceptedGateCall(filePath, rows, call);
+    if (projected !== undefined) volumes.push(projected);
+  }
+  return volumes;
+}
+
 function pairGateRounds(
   volumes: readonly ClassifiedVolume[],
 ): readonly AnalystGateCycleRound[] {
@@ -402,29 +451,49 @@ function pairGateRounds(
 }
 
 /**
- * Read and pair gate-cycle rounds from a run's session/auditor-roles directory.
+ * Read and pair gate-cycle rounds from one or more auditor-roles directories.
  * ENOENT (directory truly absent) → []. ENOTDIR and other errors propagate
  * (failure honesty — damaged topology must not wash to zero rounds).
+ *
+ * #636 ticket-seat memory may place officer volumes under book-level subject
+ * digests shared across parent runs; pass `parentSessionFile` to keep only
+ * rounds whose attempt binding names that parent.
  */
 export async function readAnalystGateCyclesFromAuditorRoles(
-  auditorRolesDirectory: string,
+  auditorRolesDirectory: string | readonly string[],
+  options: {
+    readonly parentSessionFile?: string;
+  } = {},
 ): Promise<readonly AnalystGateCycleRound[]> {
-  let names: string[];
-  try {
-    const entries = await readdir(auditorRolesDirectory, { withFileTypes: true });
-    names = entries
-      .filter((e) => e.isFile() && e.name.endsWith(".jsonl"))
-      .map((e) => e.name)
-      .sort();
-  } catch (error) {
-    if (isMissingDirectoryError(error)) return [];
-    throw error;
-  }
-
+  const directories = typeof auditorRolesDirectory === "string"
+    ? [auditorRolesDirectory]
+    : auditorRolesDirectory;
   const volumes: ClassifiedVolume[] = [];
-  for (const name of names) {
-    const classified = await classifyAuditorVolume(join(auditorRolesDirectory, name));
-    if (classified !== undefined) volumes.push(classified);
+  for (const directory of directories) {
+    let names: string[];
+    try {
+      const entries = await readdir(directory, { withFileTypes: true });
+      names = entries
+        .filter((e) => e.isFile() && e.name.endsWith(".jsonl"))
+        .map((e) => e.name)
+        .sort();
+    } catch (error) {
+      if (isMissingDirectoryError(error)) continue;
+      throw error;
+    }
+    for (const name of names) {
+      const classified = await classifyAuditorVolume(join(directory, name));
+      for (const volume of classified) {
+        if (
+          options.parentSessionFile !== undefined &&
+          volume.parentSessionFile !== undefined &&
+          volume.parentSessionFile !== options.parentSessionFile
+        ) {
+          continue;
+        }
+        volumes.push(volume);
+      }
+    }
   }
   return pairGateRounds(volumes);
 }

package/src/analyst-ledger.ts

@@ -17,6 +17,7 @@ import { join } from "node:path";
 
 import { resolveBookKeyFromGit } from "./activation-ledger-git.ts";
 import {
+  pathContainedIn,
   physicalPathIdentity,
   resolveActivationLedgerHome,
 } from "./activation-ledger-topology.ts";
@@ -24,8 +25,10 @@ import {
   extractSessionModelSequence,
   extractSessionTimestampSpan,
   extractSessionToolIntervals,
+  intervalRowsForMatchingBinding,
   LedgerSessionJsonlError,
   readLedgerSessionJsonl,
+  type LedgerSessionRow,
   type SessionToolInterval,
 } from "./ledger-session-read.ts";
 import {
@@ -43,6 +46,11 @@ import {
   readAnalystGateCyclesFromAuditorRoles,
   type AnalystGateCycleRound,
 } from "./analyst-gate-cycles-read.ts";
+import {
+  isTicketSeatRunBindingRow,
+  resolveTicketSeatMemoryNestDirectories,
+  ticketSeatRunBindingRunId,
+} from "./ticket-seat-memory.ts";
 
 export type { AnalystGateCycleRound } from "./analyst-gate-cycles-read.ts";
 
@@ -201,6 +209,103 @@ async function resolveSessionFile(
   return join(runDirectory, "session", "session.jsonl");
 }
 
+/**
+ * Attribute session rows to one run (#636 D).
+ * Private run volumes (session under runDirectory) keep the whole file.
+ * Shared ticket-seat main volumes must carry this run's binding interval;
+ * whole-volume stats would let later continuations pollute earlier runs.
+ * Unbounded external volumes stay honest missing — never silent full ownership.
+ *
+ * `closed` on shared intervals: a later binding ended ownership before EOF of
+ * the provided rows. On damaged-prefix recovery, only closed intervals keep
+ * full frame/model/tool facts — open intervals may have lost rows to the bad line.
+ * Private volumes are never closed against a prefix (the whole file is this run).
+ */
+function attributeSessionRowsForRun(input: {
+  readonly rows: readonly LedgerSessionRow[];
+  readonly sessionFile: string;
+  readonly runDirectory: string;
+  readonly runId: string;
+}):
+  | {
+      readonly kind: "attributed";
+      readonly rows: readonly LedgerSessionRow[];
+      readonly closed: boolean;
+    }
+  | { readonly kind: "missing-boundary"; readonly reason: string } {
+  if (pathContainedIn(input.runDirectory, input.sessionFile)) {
+    return { kind: "attributed", rows: input.rows, closed: false };
+  }
+  const interval = intervalRowsForMatchingBinding(
+    input.rows,
+    isTicketSeatRunBindingRow,
+    (row) => ticketSeatRunBindingRunId(row) === input.runId,
+  );
+  if (interval === undefined) {
+    return {
+      kind: "missing-boundary",
+      reason:
+        "shared session volume has no ticket-seat run binding for this run",
+    };
+  }
+  return { kind: "attributed", rows: interval.rows, closed: interval.closed };
+}
+
+/**
+ * Admit frame span (and partial edges) from already-attributed session rows.
+ * Shared by the clean parse path and closed-interval damage recovery.
+ */
+function admitFrameSpanFromRows(rows: readonly LedgerSessionRow[]): {
+  readonly frameSpan?: AnalystRunFrameSpan;
+  readonly missingReason?: string;
+  readonly partialFirstFrameAt: AnalystFirstFrameAt;
+  readonly partialLastFrameAt: AnalystOptionalTimestamp;
+  readonly models: readonly string[];
+} {
+  const models = extractSessionModelSequence(rows);
+  const span = extractSessionTimestampSpan(rows);
+  let partialFirstFrameAt: AnalystFirstFrameAt = { status: "absent" };
+  let partialLastFrameAt: AnalystOptionalTimestamp = { status: "absent" };
+  if (span.startedAt === undefined || span.endedAt === undefined) {
+    if (span.startedAt !== undefined) {
+      partialFirstFrameAt = { status: "present", at: span.startedAt };
+    }
+    if (span.endedAt !== undefined) {
+      partialLastFrameAt = { status: "present", at: span.endedAt };
+    }
+    return {
+      models,
+      partialFirstFrameAt,
+      partialLastFrameAt,
+      missingReason: "session timeline has no usable timestamps",
+    };
+  }
+  const startedMs = Date.parse(span.startedAt);
+  const endedMs = Date.parse(span.endedAt);
+  if (!Number.isFinite(startedMs) || !Number.isFinite(endedMs)) {
+    return {
+      models,
+      partialFirstFrameAt: { status: "present", at: span.startedAt },
+      partialLastFrameAt: { status: "present", at: span.endedAt },
+      missingReason: "session timeline timestamps are not parseable instants",
+    };
+  }
+  if (endedMs < startedMs) {
+    return {
+      models,
+      partialFirstFrameAt: { status: "present", at: span.startedAt },
+      partialLastFrameAt: { status: "present", at: span.endedAt },
+      missingReason: "session timeline end is earlier than start",
+    };
+  }
+  return {
+    models,
+    frameSpan: { startedAt: span.startedAt, endedAt: span.endedAt },
+    partialFirstFrameAt: { status: "present", at: span.startedAt },
+    partialLastFrameAt: { status: "present", at: span.endedAt },
+  };
+}
+
 /** Session first/last usable timestamps retained for B-wave wall-clock kernels. */
 export type AnalystRunFrameSpan = {
   readonly startedAt: string;
@@ -277,55 +382,67 @@ async function classifyScopedRun(input: {
   let partialFirstFrameAt: AnalystFirstFrameAt = { status: "absent" };
   let partialLastFrameAt: AnalystOptionalTimestamp = { status: "absent" };
 
-  // 1) session timeline
+  // 1) session timeline — shared ticket-seat volumes slice to this run's binding.
+  // Damage after a closed binding interval must not erase that run's full facts.
   const sessionFile = await resolveSessionFile(input.runDirectory);
-  let rows: Awaited<ReturnType<typeof readLedgerSessionJsonl>> | undefined;
+  let rows: readonly LedgerSessionRow[] | undefined;
+  const admitAttributed = (
+    attributedRows: readonly LedgerSessionRow[],
+  ): void => {
+    rows = attributedRows;
+    const admitted = admitFrameSpanFromRows(attributedRows);
+    models = admitted.models;
+    partialFirstFrameAt = admitted.partialFirstFrameAt;
+    partialLastFrameAt = admitted.partialLastFrameAt;
+    if (admitted.frameSpan !== undefined) {
+      frameSpan = admitted.frameSpan;
+    } else if (admitted.missingReason !== undefined) {
+      missingSources.push("session-timeline");
+      reasons.push(admitted.missingReason);
+    }
+  };
   try {
-    rows = await readLedgerSessionJsonl(sessionFile);
-    models = extractSessionModelSequence(rows);
-    const span = extractSessionTimestampSpan(rows);
-    if (span.startedAt === undefined || span.endedAt === undefined) {
+    const rawRows = await readLedgerSessionJsonl(sessionFile);
+    const attributed = attributeSessionRowsForRun({
+      rows: rawRows,
+      sessionFile,
+      runDirectory: input.runDirectory,
+      runId: input.runId,
+    });
+    if (attributed.kind === "missing-boundary") {
       missingSources.push("session-timeline");
-      reasons.push("session timeline has no usable timestamps");
-      // Span incomplete, but any usable timestamp remains a typed partial fact.
-      if (span.startedAt !== undefined) {
-        partialFirstFrameAt = { status: "present", at: span.startedAt };
-      }
-      if (span.endedAt !== undefined) {
-        partialLastFrameAt = { status: "present", at: span.endedAt };
-      }
+      reasons.push(attributed.reason);
     } else {
-      // frameSpan gate: both edges must parse and end must not precede start.
-      // Damaged spans stay page-local unreadable — never throw or emit negative/NaN wallMs.
-      const startedMs = Date.parse(span.startedAt);
-      const endedMs = Date.parse(span.endedAt);
-      if (!Number.isFinite(startedMs) || !Number.isFinite(endedMs)) {
-        missingSources.push("session-timeline");
-        reasons.push("session timeline timestamps are not parseable instants");
-        partialFirstFrameAt = { status: "present", at: span.startedAt };
-        partialLastFrameAt = { status: "present", at: span.endedAt };
-      } else if (endedMs < startedMs) {
-        missingSources.push("session-timeline");
-        reasons.push("session timeline end is earlier than start");
-        partialFirstFrameAt = { status: "present", at: span.startedAt };
-        partialLastFrameAt = { status: "present", at: span.endedAt };
-      } else {
-        frameSpan = { startedAt: span.startedAt, endedAt: span.endedAt };
-      }
+      admitAttributed(attributed.rows);
     }
   } catch (error) {
-    missingSources.push("session-timeline");
-    reasons.push(errorText(error));
-    // Single parse kernel: recover first/last frame and models from rows read before the loud line.
+    // Single parse kernel: attribute the prefix, then decide by binding closure.
+    // Closed shared interval → full frame/model/tool (damage belongs to a later run).
+    // Open interval / private volume / missing boundary → honest missing + partial edges.
     if (error instanceof LedgerSessionJsonlError) {
-      const span = extractSessionTimestampSpan(error.prefixRows);
-      if (span.startedAt !== undefined) {
-        partialFirstFrameAt = { status: "present", at: span.startedAt };
-      }
-      if (span.endedAt !== undefined) {
-        partialLastFrameAt = { status: "present", at: span.endedAt };
+      const attributed = attributeSessionRowsForRun({
+        rows: error.prefixRows,
+        sessionFile,
+        runDirectory: input.runDirectory,
+        runId: input.runId,
+      });
+      if (attributed.kind === "attributed" && attributed.closed) {
+        admitAttributed(attributed.rows);
+      } else if (attributed.kind === "attributed") {
+        missingSources.push("session-timeline");
+        reasons.push(errorText(error));
+        const admitted = admitFrameSpanFromRows(attributed.rows);
+        models = admitted.models;
+        partialFirstFrameAt = admitted.partialFirstFrameAt;
+        partialLastFrameAt = admitted.partialLastFrameAt;
+      } else {
+        missingSources.push("session-timeline");
+        reasons.push(errorText(error));
+        // missing-boundary on damaged prefix: no partial ownership of sibling runs.
       }
-      models = extractSessionModelSequence(error.prefixRows);
+    } else {
+      missingSources.push("session-timeline");
+      reasons.push(errorText(error));
     }
   }
 
@@ -399,11 +516,21 @@ async function classifyScopedRun(input: {
   // Nested auditor-roles gate pairs stay inside the sole scan (families must
   // not readdir this tree again). Missing directory → []. Damaged discovered
   // nested JSONL is page-local unreadable — never silently under-count rounds.
+  // #636: ticket-seat memory nests via sole discovery helper.
   let gateCycles: readonly AnalystGateCycleRound[];
   try {
-    gateCycles = await readAnalystGateCyclesFromAuditorRoles(
+    const memoryNests = await resolveTicketSeatMemoryNestDirectories({
+      runDirectory: input.runDirectory,
+      seats: ["inspector", "notary"],
+    });
+    const directories = [
       join(input.runDirectory, "session", "auditor-roles"),
-    );
+      ...memoryNests,
+    ];
+    const parentSessionFile = join(input.runDirectory, "session", "session.jsonl");
+    gateCycles = await readAnalystGateCyclesFromAuditorRoles(directories, {
+      parentSessionFile,
+    });
   } catch (error) {
     return {
       kind: "unreadable",

package/src/archivist-record-entry.ts

@@ -3,7 +3,6 @@
  * 调用方只声明自己是谁的什么；落点由候簿拓扑算出，签名不含任何落点/路径参数。
  * 「谁调了谁」复用 Pi parentSession + ADR 0047 correlation，不新增 caller 字段。
  */
-import { createHash } from "node:crypto";
 import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { dirname, resolve, join } from "node:path";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
@@ -18,6 +17,9 @@ import {
   physicallyContainedIn,
   resolveActivationLedgerHomeForPath,
 } from "./activation-ledger-topology.ts";
+import { subjectKeyedRecordDirectory } from "./archivist-record-topology.ts";
+
+export { subjectKeyedRecordDirectory } from "./archivist-record-topology.ts";
 
 const CURRENT_SESSION_LEDGER = "current-session.json";
 
@@ -120,6 +122,13 @@ function assertRecentFinalFileUnderSessionDir(
   }
 }
 
+/** Open result including the sole resumed fact (nest existed before this open). */
+export type RecordSessionOpen = {
+  readonly session: SessionManager;
+  /** True only when an existing same-nest volume was reopened (subject/gate path). */
+  readonly resumed: boolean;
+};
+
 /**
  * Sole package entry that constructs a durable Pi session record (ADR 0065).
  * No destination/path parameters — location is computed from ledger topology only.
@@ -133,8 +142,10 @@ function assertRecentFinalFileUnderSessionDir(
  * a sibling volume selected only by kind/cwd/mtime.
  * New persisted principals materialize their deferred session header before return so
  * custom-entry-only writers do not need a parallel delayed-header helper.
+ *
+ * `resumed` is the sole open-or-continue fact — callers must not re-probe nest existence.
  */
-export function createRecordSession(options: CreateRecordSessionOptions): SessionManager {
+export function createRecordSessionOpen(options: CreateRecordSessionOptions): RecordSessionOpen {
   const cwd = options.cwd;
   const parentFile = options.parent?.getSessionFile();
   // Path → ledger home is owned by topology (explicit env.home nests via parent path).
@@ -144,16 +155,18 @@ export function createRecordSession(options: CreateRecordSessionOptions): Sessio
   let parentSession: string | undefined;
 
   if (options.subject !== undefined) {
-    const digest = createHash("sha256").update(options.subject).digest("hex").slice(0, 32);
-    sessionDir = join(
-      activationBookDirectory(ledgerHome, resolveBookKeyFromGit(cwd)),
-      options.kind,
-      digest,
-    );
+    sessionDir = subjectKeyedRecordDirectory({
+      cwd,
+      kind: options.kind,
+      subject: options.subject,
+      ...(parentFile === undefined || parentFile.length === 0
+        ? {}
+        : { parentSessionFile: parentFile }),
+    });
     parentSession = parentFile && parentFile.length > 0 ? parentFile : undefined;
   } else if (parentFile === undefined || parentFile.length === 0) {
     // No durable parent principal — preserve prior in-memory child behavior.
-    return SessionManager.inMemory(cwd);
+    return { session: SessionManager.inMemory(cwd), resumed: false };
   } else {
     const parentResolved = resolve(parentFile);
     // Nest under parent only when the parent record already lives under the package home.
@@ -177,7 +190,10 @@ export function createRecordSession(options: CreateRecordSessionOptions): Sessio
   if (mayResumeSameNest && nestAlreadyExists) {
     const recentFile = readCurrentSession(sessionDir);
     assertRecentFinalFileUnderSessionDir(sessionDir, recentFile);
-    return SessionManager.open(recentFile, sessionDir, cwd);
+    return {
+      session: SessionManager.open(recentFile, sessionDir, cwd),
+      resumed: true,
+    };
   }
 
   const session = SessionManager.create(
@@ -202,5 +218,10 @@ export function createRecordSession(options: CreateRecordSessionOptions): Sessio
       writeCurrentSession(sessionDir, file);
     }
   }
-  return session;
+  return { session, resumed: false };
+}
+
+/** Session-only facade — most callers only need the manager. */
+export function createRecordSession(options: CreateRecordSessionOptions): SessionManager {
+  return createRecordSessionOpen(options).session;
 }