@akagilnc/pi-workflow-roles 0.1.1840 → 0.1.1854

package/dist/in-process-session.js

@@ -5,17 +5,31 @@
  * does not statically reach @earendil-works/pi-coding-agent.
  */
 import { createAgentSession, DefaultResourceLoader, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { createRecordSession } from "./sitian-record-entry.js";
+function resolveSessionManager(options) {
+    if (options.sessionManager !== undefined)
+        return options.sessionManager;
+    return createRecordSession({
+        cwd: options.cwd,
+        kind: options.kind,
+        ...(options.subject === undefined ? {} : { subject: options.subject }),
+        ...(options.parent === undefined ? {} : { parent: options.parent }),
+    });
+}
 /**
  * Single createAgentSession + Settings construction for all in-process children.
+ * Child SessionManager construction for identity-declared records lives here so
+ * role modules do not call createRecordSession directly.
  */
 export async function openInProcessAgentSession(options) {
     const settings = SettingsManager.inMemory({ compaction: { enabled: false }, retry: { enabled: false } });
+    const sessionManager = resolveSessionManager(options);
     const createArgs = {
         cwd: options.cwd,
         model: options.model,
         thinkingLevel: options.thinkingLevel ?? "off",
         modelRuntime: options.modelRuntime,
-        sessionManager: options.sessionManager,
+        sessionManager,
         settingsManager: settings,
         ...(options.noTools === undefined ? {} : { noTools: options.noTools }),
         ...(options.tools === undefined ? {} : { tools: options.tools }),

package/dist/navigator-attendance.js

@@ -1,8 +1,8 @@
 import { createHash } from "node:crypto";
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
@@ -11,8 +11,6 @@ import {
   mintNavigatorInvocationId
 } from "./navigator-invocation-identity.js";
 import { PACKAGED_ROLE_REGISTRY, packagedRoleMetadata } from "./packaged-role-registry.js";
-import { resolveBookKeyFromGit } from "./activation-ledger-git.js";
-import { activationBookDirectory, resolveActivationLedgerHome } from "./activation-ledger-topology.js";
 import { openInProcessAgentSession } from "./in-process-session.js";
 import { renderPublicAkRoleCommand } from "./public-command-renderer.js";
 import { issueRoot, subjectPath } from "./work-subject-identity.js";
@@ -218,14 +216,6 @@ function navigatorSubjectKeyForInput(subjectRoot, reference, cwd = process.cwd()
   }
   return navigatorSubjectKey(subjectRoot, resolvedReference);
 }
-function subjectDirectory(cwd, subjectKey) {
-  const book = activationBookDirectory(
-    resolveActivationLedgerHome(),
-    resolveBookKeyFromGit(cwd)
-  );
-  const digest = createHash("sha256").update(subjectKey).digest("hex").slice(0, 32);
-  return join(book, "navigator", digest);
-}
 function navigatorModelSettingPath() {
   return join(process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"), "navigator-model.json");
 }
@@ -341,7 +331,6 @@ function createNavigatorAttendance(options) {
   let subject = options.subject;
   let authority = options.authority;
   let contextError = options.contextError;
-  let sessionDir = options.sessionDir;
   let candidates;
   const invocationPrincipal = options.invocationId ?? mintNavigatorInvocationId();
   let activeInvocationId = invocationPrincipal;
@@ -454,7 +443,7 @@ ${text}
       sessionReady = (async () => {
         let created;
         try {
-          created = await options.createSession({ context: options.context, sessionDir, ...options.modelSettingPath === void 0 ? {} : { modelSettingPath: options.modelSettingPath }, tool });
+          created = await options.createSession({ context: options.context, subject: subjectKey, ...options.modelSettingPath === void 0 ? {} : { modelSettingPath: options.modelSettingPath }, tool });
         } catch (error) {
           throw navigatorUnavailableError("session", error);
         }
@@ -584,7 +573,7 @@ ${helpContext}
           await promptAllowingRejectedPrepare(RECEIPT_DELIVERY_PROMPT, true);
         }
         if (output === void 0 && delivery.nextAction() === "no-receipt" && activeSession.providerFailure?.() === void 0) {
-          const facts = delivery.facts({ runPointer: sessionDir, attemptPointer: invocationId });
+          const facts = delivery.facts({ runPointer: activeSession.recordPointer(), attemptPointer: invocationId });
           activeSession.appendEntry(NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, facts);
           preparationNoReceipt = true;
           candidates = [];
@@ -622,7 +611,6 @@ ${helpContext}
       subject = next.subject;
       authority = next.authority;
       contextError = next.contextError;
-      sessionDir = options.sessionDirectory?.(next.subjectKey) ?? options.sessionDir;
     },
     /**
      * Start live-help subprocesses during activation without beginning full
@@ -777,7 +765,7 @@ ${helpContext}
 }
 function createNativeNavigatorSessionFactory(defaultModelSettingPath = navigatorModelSettingPath()) {
   const sharedModelRuntime = ModelRuntime.create({ allowModelNetwork: false });
-  return async ({ context, sessionDir, modelSettingPath, tool }) => {
+  return async ({ context, subject, modelSettingPath, tool }) => {
     let configured;
     try {
       configured = await readNavigatorModelSetting(modelSettingPath ?? defaultModelSettingPath);
@@ -800,15 +788,6 @@ function createNativeNavigatorSessionFactory(defaultModelSettingPath = navigator
       throw navigatorUnavailableError("auth", error);
     }
     if (!auth.ok) throw new NavigatorUnavailableError("auth", auth.error);
-    try {
-      const sessionInfo = await stat(sessionDir);
-      if (!sessionInfo.isDirectory()) throw new NavigatorUnavailableError("session", `Navigator session path is not a directory: ${sessionDir}`);
-    } catch (error) {
-      if (error instanceof NavigatorUnavailableError) throw error;
-      if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
-        throw navigatorUnavailableError("session", error);
-      }
-    }
     let providerFailure;
     const assignProviderFailure = (fact) => {
       if (fact !== void 0) providerFailure = fact;
@@ -959,10 +938,12 @@ function createNativeNavigatorSessionFactory(defaultModelSettingPath = navigator
     try {
       opened = await openInProcessAgentSession({
         cwd: context.cwd,
+        kind: "navigator",
+        subject,
+        parent: context.sessionManager,
         model,
         modelRuntime,
         thinkingLevel: parsed.thinkingLevel,
-        sessionManager: SessionManager.continueRecent(context.cwd, sessionDir),
         noTools: "all",
         tools: [NAVIGATOR_PREPARE_TOOL_NAME],
         customTools: [tool]
@@ -1016,6 +997,7 @@ function createNativeNavigatorSessionFactory(defaultModelSettingPath = navigator
         }
       },
       getThinkingLevel: () => opened.session.thinkingLevel,
+      recordPointer: () => opened.session.sessionManager.getSessionDir(),
       dispose: () => opened.dispose()
     };
   };
@@ -1028,11 +1010,6 @@ function registerNavigatorModelCommand(pi, path = navigatorModelSettingPath()) {
     }
   });
 }
-function navigatorSessionDirectory(context, subjectKey) {
-  const current = context.sessionManager.getSessionDir();
-  const key = subjectKey ?? subjectPath(current, context.cwd);
-  return subjectDirectory(context.cwd, key);
-}
 export {
   NAVIGATOR_DEFAULT_MODEL,
   NAVIGATOR_EVENT_TYPE,
@@ -1048,7 +1025,6 @@ export {
   navigatorModelSettingPath,
   navigatorProviderFailure,
   navigatorProviderFailureFromError,
-  navigatorSessionDirectory,
   navigatorSubjectKey,
   navigatorSubjectKeyForInput,
   navigatorUnavailableError,

package/dist/sitian-record-entry.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { dirname, resolve, join } from "node:path";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 import { resolveBookKeyFromGit } from "./activation-ledger-git.js";
@@ -10,13 +11,26 @@ import {
   physicallyContainedIn,
   resolveActivationLedgerHome
 } from "./activation-ledger-topology.js";
+const { findMostRecentSession } = await import(new URL("./core/session-manager.js", import.meta.resolve("@earendil-works/pi-coding-agent")).href);
 function createRecordSession(options) {
   const cwd = options.cwd;
   const parentFile = options.parent?.getSessionFile();
+  const ledgerHome = resolveActivationLedgerHome();
+  if (options.subject !== void 0) {
+    const digest = createHash("sha256").update(options.subject).digest("hex").slice(0, 32);
+    const sessionDir2 = join(
+      activationBookDirectory(ledgerHome, resolveBookKeyFromGit(cwd)),
+      options.kind,
+      digest
+    );
+    ensureRealDirectoryTree(ledgerHome, sessionDir2);
+    const recentFile = findMostRecentSession(sessionDir2, cwd);
+    if (recentFile !== null) return SessionManager.open(recentFile, sessionDir2, cwd);
+    return SessionManager.create(cwd, sessionDir2, parentFile ? { parentSession: parentFile } : void 0);
+  }
   if (parentFile === void 0 || parentFile.length === 0) {
     return SessionManager.inMemory(cwd);
   }
-  const ledgerHome = resolveActivationLedgerHome();
   const parentResolved = resolve(parentFile);
   const sessionDir = physicallyContainedIn(ledgerHome, parentResolved) ? join(dirname(parentResolved), options.kind) : join(activationBookDirectory(ledgerHome, resolveBookKeyFromGit(cwd)), options.kind);
   ensureRealDirectoryTree(ledgerHome, sessionDir);

package/extensions/role-runtime.ts

@@ -23,7 +23,6 @@ import {
   createNativeNavigatorSessionFactory,
   createNavigatorAttendance,
   navigatorUnavailableError,
-  navigatorSessionDirectory,
   navigatorSubjectKey,
   navigatorSubjectKeyForInput,
   registerNavigatorModelCommand,
@@ -261,14 +260,11 @@ export default function roleRuntime(pi: ExtensionAPI): void {
     auditDoctorCompliance: createPiDoctorAuditor(),
     loadNavigatorWorkContext: (options) => loadNavigatorWorkContext(pi, options),
     createNavigatorAttendance: (options) => {
-      const sessionDir = navigatorSessionDirectory(options.context, options.subjectKey);
       return createNavigatorAttendance({
         context: options.context,
         role: options.role,
         phase: options.phase,
         subjectKey: options.subjectKey,
-        sessionDir,
-        sessionDirectory: (subjectKey) => navigatorSessionDirectory(options.context, subjectKey),
         subject: options.subject,
         authority: options.authority,
         invocationId: options.invocationId,

package/package.json

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

package/src/in-process-session.ts

@@ -14,14 +14,15 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import type { Api, Model } from "@earendil-works/pi-ai";
 
-export type OpenInProcessAgentSessionOptions = {
+import { createRecordSession } from "./sitian-record-entry.ts";
+
+type OpenInProcessAgentSessionBase = {
   readonly cwd: string;
   /** Required when loading a resource loader / systemPrompt. Callers own scratch lifecycle. */
   readonly agentDir?: string;
   readonly model: Model<Api>;
   readonly modelRuntime: ModelRuntime;
   readonly thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
-  readonly sessionManager: SessionManager;
   readonly systemPrompt?: string;
   readonly customTools?: ToolDefinition[];
   readonly noTools?: "all" | "builtin";
@@ -29,20 +30,56 @@ export type OpenInProcessAgentSessionOptions = {
   readonly tools?: string[];
 };
 
+/**
+ * Shared open admits exactly one session source:
+ * - pre-built sessionManager, or
+ * - kind/subject/parent identity relations (Sitian obtains the manager).
+ * Encoded as a type relation — no runtime missing-arg guard.
+ */
+export type OpenInProcessAgentSessionOptions =
+  | (OpenInProcessAgentSessionBase & {
+      readonly sessionManager: SessionManager;
+      readonly kind?: never;
+      readonly subject?: never;
+      readonly parent?: never;
+    })
+  | (OpenInProcessAgentSessionBase & {
+      readonly sessionManager?: undefined;
+      /** Record kind for the Sitian entry. */
+      readonly kind: string;
+      /** Stable work identity for book-level records which continue across role runs. */
+      readonly subject?: string;
+      /** Optional parent session — supplies parentSession link / nest principal. */
+      readonly parent?: { getSessionFile(): string | undefined };
+    });
+
+function resolveSessionManager(options: OpenInProcessAgentSessionOptions): SessionManager {
+  if (options.sessionManager !== undefined) return options.sessionManager;
+  return createRecordSession({
+    cwd: options.cwd,
+    kind: options.kind,
+    ...(options.subject === undefined ? {} : { subject: options.subject }),
+    ...(options.parent === undefined ? {} : { parent: options.parent }),
+  });
+}
+
 /**
  * Single createAgentSession + Settings construction for all in-process children.
+ * Child SessionManager construction for identity-declared records lives here so
+ * role modules do not call createRecordSession directly.
  */
 export async function openInProcessAgentSession(
   options: OpenInProcessAgentSessionOptions,
 ): Promise<{ session: Awaited<ReturnType<typeof createAgentSession>>["session"]; dispose(): void }> {
   const settings = SettingsManager.inMemory({ compaction: { enabled: false }, retry: { enabled: false } });
+  const sessionManager = resolveSessionManager(options);
 
   const createArgs: Parameters<typeof createAgentSession>[0] = {
     cwd: options.cwd,
     model: options.model,
     thinkingLevel: options.thinkingLevel ?? "off",
     modelRuntime: options.modelRuntime,
-    sessionManager: options.sessionManager,
+    sessionManager,
     settingsManager: settings,
     ...(options.noTools === undefined ? {} : { noTools: options.noTools }),
     ...(options.tools === undefined ? {} : { tools: options.tools }),

package/src/navigator-attendance.ts

@@ -1,9 +1,9 @@
 import { createHash } from "node:crypto";
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
-import { ModelRuntime, SessionManager, type ExtensionContext, type ExtensionAPI, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { ModelRuntime, type ExtensionContext, type ExtensionAPI, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
 import { Value } from "typebox/value";
@@ -13,8 +13,6 @@ import {
   mintNavigatorInvocationId,
 } from "./navigator-invocation-identity.ts";
 import { PACKAGED_ROLE_REGISTRY, type PackagedRole, packagedRoleMetadata } from "./packaged-role-registry.ts";
-import { resolveBookKeyFromGit } from "./activation-ledger-git.ts";
-import { activationBookDirectory, resolveActivationLedgerHome } from "./activation-ledger-topology.ts";
 import { openInProcessAgentSession } from "./in-process-session.ts";
 import { renderPublicAkRoleCommand } from "./public-command-renderer.ts";
 import { issueRoot, subjectPath } from "./work-subject-identity.ts";
@@ -233,12 +231,14 @@ export type NavigatorPreparationSession = {
   providerFailure?(): NavigatorProviderFailureFact | undefined;
   setModel?(model: string, thinkingLevel: "off" | "max"): Promise<void>;
   getThinkingLevel?(): string;
+  /** Durable record pointer for unchanged no-receipt lifecycle facts. Required — missing pointer fails honestly. */
+  recordPointer(): string;
   dispose(): void;
 };
 
 export type NavigatorSessionFactory = (options: {
   context: ExtensionContext;
-  sessionDir: string;
+  subject: string;
   modelSettingPath?: string;
   tool: ToolDefinition;
 }) => Promise<NavigatorPreparationSession>;
@@ -248,7 +248,6 @@ export type NavigatorAttendanceOptions = {
   role: string;
   phase: NavigatorPhase;
   subjectKey: string;
-  sessionDir: string;
   loadSoul: () => Promise<string>;
   loadRoutePlaybook?: () => Promise<string>;
   loadRoleHelp: (role: NavigatorTargetRole) => Promise<string>;
@@ -257,7 +256,6 @@ export type NavigatorAttendanceOptions = {
   subject: string;
   authority: string;
   contextError?: unknown;
-  sessionDirectory?: (subjectKey: string) => string;
   /** Exact principal owned by shared role lifecycle; attendance never overrides it. */
   invocationId?: string;
   onEvent: (event: NavigatorEvent, report: NavigatorReport) => void | Promise<void>;
@@ -426,15 +424,6 @@ export function navigatorSubjectKeyForInput(subjectRoot: string, reference: stri
   return navigatorSubjectKey(subjectRoot, resolvedReference);
 }
 
-function subjectDirectory(cwd: string, subjectKey: string): string {
-  const book = activationBookDirectory(
-    resolveActivationLedgerHome(),
-    resolveBookKeyFromGit(cwd),
-  );
-  const digest = createHash("sha256").update(subjectKey).digest("hex").slice(0, 32);
-  return join(book, "navigator", digest);
-}
-
 export function navigatorModelSettingPath(): string {
   return join(process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"), "navigator-model.json");
 }
@@ -588,7 +577,6 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
   let subject = options.subject;
   let authority = options.authority;
   let contextError = options.contextError;
-  let sessionDir = options.sessionDir;
   let candidates: NavigatorCandidate[] | undefined;
   // Shared lifecycle owns the principal when supplied; otherwise mint once per attendance.
   const invocationPrincipal = options.invocationId ?? mintNavigatorInvocationId();
@@ -721,7 +709,7 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
         sessionReady = (async () => {
           let created: NavigatorPreparationSession;
           try {
-            created = await options.createSession({ context: options.context, sessionDir, ...(options.modelSettingPath === undefined ? {} : { modelSettingPath: options.modelSettingPath }), tool });
+            created = await options.createSession({ context: options.context, subject: subjectKey, ...(options.modelSettingPath === undefined ? {} : { modelSettingPath: options.modelSettingPath }), tool });
           } catch (error) {
             throw navigatorUnavailableError("session", error);
           }
@@ -841,7 +829,7 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
             await promptAllowingRejectedPrepare(RECEIPT_DELIVERY_PROMPT, true);
           }
           if (output === undefined && delivery.nextAction() === "no-receipt" && activeSession.providerFailure?.() === undefined) {
-            const facts = delivery.facts({ runPointer: sessionDir, attemptPointer: invocationId });
+            const facts = delivery.facts({ runPointer: activeSession.recordPointer(), attemptPointer: invocationId });
             activeSession.appendEntry(NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, facts);
             preparationNoReceipt = true;
             candidates = [];
@@ -884,7 +872,6 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
       subject = next.subject;
       authority = next.authority;
       contextError = next.contextError;
-      sessionDir = options.sessionDirectory?.(next.subjectKey) ?? options.sessionDir;
     },
     /**
      * Start live-help subprocesses during activation without beginning full
@@ -1056,7 +1043,7 @@ export function createNativeNavigatorSessionFactory(defaultModelSettingPath = na
   // Pre-warm once per factory (per process). Concurrent prepares share the same
   // runtime construction rather than each paying ModelRuntime.create under load.
   const sharedModelRuntime = ModelRuntime.create({ allowModelNetwork: false });
-  return async ({ context, sessionDir, modelSettingPath, tool }) => {
+  return async ({ context, subject, modelSettingPath, tool }) => {
     let configured: string;
     try {
       configured = await readNavigatorModelSetting(modelSettingPath ?? defaultModelSettingPath);
@@ -1079,16 +1066,6 @@ export function createNativeNavigatorSessionFactory(defaultModelSettingPath = na
       throw navigatorUnavailableError("auth", error);
     }
     if (!auth.ok) throw new NavigatorUnavailableError("auth", auth.error);
-    try {
-      const sessionInfo = await stat(sessionDir);
-      if (!sessionInfo.isDirectory()) throw new NavigatorUnavailableError("session", `Navigator session path is not a directory: ${sessionDir}`);
-    } catch (error) {
-      if (error instanceof NavigatorUnavailableError) throw error;
-      // Contract: README.md#Navigator-attendance — the resumable session directory may be created by session setup; retain and classify every other filesystem cause.
-      if (!(error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT")) {
-        throw navigatorUnavailableError("session", error);
-      }
-    }
     let providerFailure: NavigatorProviderFailureFact | undefined;
     const assignProviderFailure = (fact: NavigatorProviderFailureFact | undefined): void => {
       if (fact !== undefined) providerFailure = fact;
@@ -1253,13 +1230,15 @@ export function createNativeNavigatorSessionFactory(defaultModelSettingPath = na
     }
     let opened: Awaited<ReturnType<typeof openInProcessAgentSession>>;
     try {
-      // Shared in-process session open (#233) — same ModelRuntime module instance.
+      // Shared in-process session open (#233) — Sitian SessionManager from identity relations.
       opened = await openInProcessAgentSession({
         cwd: context.cwd,
+        kind: "navigator",
+        subject,
+        parent: context.sessionManager,
         model,
         modelRuntime,
         thinkingLevel: parsed.thinkingLevel,
-        sessionManager: SessionManager.continueRecent(context.cwd, sessionDir),
         noTools: "all",
         tools: [NAVIGATOR_PREPARE_TOOL_NAME],
         customTools: [tool],
@@ -1312,6 +1291,7 @@ export function createNativeNavigatorSessionFactory(defaultModelSettingPath = na
         }
       },
       getThinkingLevel: () => opened.session.thinkingLevel,
+      recordPointer: () => opened.session.sessionManager.getSessionDir(),
       dispose: () => opened.dispose(),
     };
   };
@@ -1326,10 +1306,4 @@ export function registerNavigatorModelCommand(pi: ExtensionAPI, path = navigator
   });
 }
 
-export function navigatorSessionDirectory(context: ExtensionContext, subjectKey?: string): string {
-  const current = context.sessionManager.getSessionDir();
-  const key = subjectKey ?? subjectPath(current, context.cwd);
-  return subjectDirectory(context.cwd, key);
-}
-
 export { subjectPath };

package/src/reviewer-role.ts

@@ -120,7 +120,7 @@ export function createReviewerRoleRuntime(pi: ExtensionAPI, dependencies: Review
     if (!registered) {
       registered = true;
       pi.registerTool({ name: REVIEWER_OUTPUT_TOOL_NAME, label: "Reviewer Output", description: "Submit the thin Reviewer receipt after semantic compliance audit.", promptSnippet: "Submit the final Reviewer receipt", promptGuidelines: [`Use ${REVIEWER_OUTPUT_TOOL_NAME} as the sole final action.`,
-          "This runtime provides no sub-agent tool; produce the Standards and Spec review legs sequentially in this session yourself — that is the canonical execution of the review Skill here."], parameters: reviewerOutputSchema,
+          "This runtime executes the Standards and Spec review legs for you as package-managed evidence-child sessions — that IS this runtime's implementation of the review Skill's parallel sub-agents. Do not refuse because no Agent tool appears in your tool list, and do not substitute your own sub-processes; work with the legs the runtime provides."], parameters: reviewerOutputSchema,
         async execute(id, parameters, signal, _update, toolCtx): Promise<AgentToolResult<unknown>> {
           if (!soul || !binding) throw new Error("Reviewer inputs were not loaded");
           requireSoleReviewerOutputCall(id, toolCtx);

package/src/role-runtime.ts

@@ -337,7 +337,7 @@ export type RoleRuntimeDependencies = {
   auditDoctorCompliance?(options: { context: ExtensionContext; signal?: AbortSignal }): Promise<ComplianceDecision>;
   createCollectorClock?(): CollectorClock;
   collectorPackageExtensionPath?: string;
-  createNavigatorAttendance?(options: { context: ExtensionContext; role: string; phase: NavigatorPhase; subjectKey: string; subject: string; authority: string; contextError?: unknown; sessionDirectory?: (subjectKey: string) => string; invocationId: string; onEvent: (event: import("./navigator-attendance.ts").NavigatorEvent, report: import("./navigator-attendance.ts").NavigatorReport) => void | Promise<void> }): NavigatorAttendanceDependency | Promise<NavigatorAttendanceDependency>;
+  createNavigatorAttendance?(options: { context: ExtensionContext; role: string; phase: NavigatorPhase; subjectKey: string; subject: string; authority: string; contextError?: unknown; invocationId: string; onEvent: (event: import("./navigator-attendance.ts").NavigatorEvent, report: import("./navigator-attendance.ts").NavigatorReport) => void | Promise<void> }): NavigatorAttendanceDependency | Promise<NavigatorAttendanceDependency>;
   loadNavigatorWorkContext?(options: { context: ExtensionContext; role: string; phase: NavigatorPhase }): Promise<NavigatorWorkContext>;
   loadCanonicalSkillBinding?(
     name: "tdd" | "code-review",

package/src/sitian-record-entry.ts

@@ -3,6 +3,7 @@
  * 调用方只声明自己是谁的什么；落点由候簿拓扑算出，签名不含任何落点/路径参数。
  * 「谁调了谁」复用 Pi parentSession + ADR 0047 correlation，不新增 caller 字段。
  */
+import { createHash } from "node:crypto";
 import { dirname, resolve, join } from "node:path";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 
@@ -18,6 +19,13 @@ import {
   resolveActivationLedgerHome,
 } from "./activation-ledger-topology.ts";
 
+// continueRecent always allocates a deferred sessionFile; this is the discovery result.
+const { findMostRecentSession } = await import(
+  new URL("./core/session-manager.js", import.meta.resolve("@earendil-works/pi-coding-agent")).href,
+) as {
+  findMostRecentSession: (sessionDir: string, cwd?: string) => string | null;
+};
+
 /** Parent session surface needed to link and (when already under home) nest the record. */
 export type RecordSessionParent = {
   getSessionFile(): string | undefined;
@@ -30,6 +38,8 @@ export type CreateRecordSessionOptions = {
   readonly kind: string;
   /** Optional parent session — supplies parentSession link; nest under parent only when that parent already lives under the ledger home. */
   readonly parent?: RecordSessionParent;
+  /** Stable work identity for book-level records which continue across role runs. */
+  readonly subject?: string;
 };
 
 /**
@@ -39,12 +49,30 @@ export type CreateRecordSessionOptions = {
 export function createRecordSession(options: CreateRecordSessionOptions): SessionManager {
   const cwd = options.cwd;
   const parentFile = options.parent?.getSessionFile();
+  const ledgerHome = resolveActivationLedgerHome();
+
+  if (options.subject !== undefined) {
+    const digest = createHash("sha256").update(options.subject).digest("hex").slice(0, 32);
+    const sessionDir = join(
+      activationBookDirectory(ledgerHome, resolveBookKeyFromGit(cwd)),
+      options.kind,
+      digest,
+    );
+    ensureRealDirectoryTree(ledgerHome, sessionDir);
+    // Delegate discovery to Pi so custom-directory continuation retains its
+    // mtime ordering, valid-header scan, and cwd filtering semantics.
+    const recentFile = findMostRecentSession(sessionDir, cwd);
+    if (recentFile !== null) return SessionManager.open(recentFile, sessionDir, cwd);
+    return SessionManager.create(cwd, sessionDir, parentFile
+      ? { parentSession: parentFile }
+      : undefined);
+  }
+
   if (parentFile === undefined || parentFile.length === 0) {
     // No durable parent principal — preserve prior in-memory child behavior.
     return SessionManager.inMemory(cwd);
   }
 
-  const ledgerHome = resolveActivationLedgerHome();
   const parentResolved = resolve(parentFile);
 
   // Nest under parent only when the parent record already lives under the package home.