@akagilnc/pi-workflow-roles 0.1.4444 → 0.1.4503

package/src/public-cli/diarist-run.ts

@@ -13,6 +13,7 @@ import {
   bindAdmittedTicketNumber,
   buildInstructionTransportPrompt,
   relocateAdmittedRunToTicket,
+  recordAdmittedCorrelation,
   type AdmittedDiaristInvocation,
   type ParseDiaristArgvResult,
 } from "./invocation.ts";
@@ -94,6 +95,9 @@ function diaristAdapters(
     shouldPresentSettled: () => true,
     // Resume interrupted state: board ticket already on pages, run still under unbound/.
     beforeDispatch: async (admitted, lease) => {
+      if (env.correlationId !== undefined && env.correlationId.trim() !== "") {
+        await recordAdmittedCorrelation(admitted, env.correlationId);
+      }
       await bindAndRelocateDiaristIfBoardBound(admitted, env.principalAuthority, lease);
     },
     // First post-turn assert: accept hook wrote board pages; relocate before lease release.

package/src/public-cli/invocation.ts

@@ -6,11 +6,14 @@ import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import {
   lstat,
+  mkdtemp,
   readFile,
   realpath,
   rename,
+  rm,
   writeFile,
 } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 
 import {
@@ -123,6 +126,8 @@ export type AdmittedRoleInvocationBase = {
    * (ADR 0049 host channel). Admission does not mint ticket-binding ids.
    */
   readonly correlationId?: string;
+  /** Direct callers retained across same-run resumes, in first-observed order. */
+  readonly correlationIds?: readonly string[];
   /**
    * Typed ticketNumber after known-identity reuse or notary source-run inheritance
    * (#635 / #709). Admission does not bind from CLI flag or attachment frontmatter.
@@ -315,6 +320,8 @@ export function issueAdmissionPlacement(
     /** Identity already asserted by 起居郎; never derive this from CLI parameters. */
     readonly subject: RoleRunSubject;
     readonly home?: string;
+    /** Placement may be computed before a same-ticket lookup without touching disk. */
+    readonly materialize?: boolean;
   },
 ): AdmissionPlacement {
   const ledgerHome = resolveActivationLedgerHome(request.home);
@@ -325,7 +332,7 @@ export function issueAdmissionPlacement(
     runId: request.runId,
     role: request.role,
   });
-  ensureRoleRunPlacement(ledgerHome, placement);
+  if (request.materialize !== false) ensureRoleRunPlacement(ledgerHome, placement);
   return {
     principal: authority.seal(placement),
     ...placement,
@@ -530,6 +537,42 @@ export async function bindAdmittedTicketNumber(
   (admitted as { ticketNumber?: number }).ticketNumber = ticketNumber;
 }
 
+/** Persist each direct caller observed while a retained run is resumed. */
+export async function recordAdmittedCorrelation(
+  admitted: AdmittedRoleInvocation,
+  correlationId: string,
+): Promise<void> {
+  const current = JSON.parse(
+    await readFile(admitted.admittedRequestPath, "utf8"),
+  ) as Record<string, unknown>;
+  const prior = [
+    ...(Array.isArray(current.correlationIds)
+      ? current.correlationIds.filter((value): value is string =>
+          typeof value === "string" && value.trim() !== ""
+        )
+      : []),
+    ...(typeof current.correlationId === "string" && current.correlationId.trim() !== ""
+      ? [current.correlationId]
+      : []),
+  ];
+  const correlationIds = [...new Set([...prior, correlationId])];
+  await writeFile(
+    admitted.admittedRequestPath,
+    `${JSON.stringify({ ...current, correlationId, correlationIds }, null, 2)}\n`,
+    "utf8",
+  );
+  await mergeInvocationIdentityPage(admitted.runDirectory, {
+    correlationId,
+    correlationIds,
+  });
+  const mutable = admitted as {
+    correlationId?: string;
+    correlationIds?: readonly string[];
+  };
+  mutable.correlationId = correlationId;
+  mutable.correlationIds = correlationIds;
+}
+
 /**
  * #871: persist the typed co-review set as a countersign run fact (admitted-request +
  * invocation.json). Whole-set replace — never union with a prior set. Main ticket
@@ -1200,11 +1243,9 @@ export function parseFixerArgv(args: readonly string[]): ParseFixerArgvResult {
   };
 }
 
-async function freezeRegularFileAttachment(
+async function readRegularFileAttachment(
   sourcePath: string,
-  destinationDir: string,
-  index: number,
-): Promise<{ attachment: FrozenAttachment; body: Buffer }> {
+): Promise<{ absolute: string; bytes: Buffer }> {
   const absolute = isAbsolute(sourcePath) ? sourcePath : resolve(sourcePath);
   let st;
   try {
@@ -1220,18 +1261,103 @@ async function freezeRegularFileAttachment(
       `attachment must be a regular file (not a directory or symlink): ${sourcePath}`,
     );
   }
-  const bytes = await readFile(absolute);
-  const name = `${String(index).padStart(2, "0")}-${basename(absolute)}`;
-  const frozenPath = join(destinationDir, name);
+  try {
+    return { absolute, bytes: await readFile(absolute) };
+  } catch (error) {
+    throw new CliUsageError(
+      `attachment is not a readable regular file: ${sourcePath}`,
+      { cause: error },
+    );
+  }
+}
+
+export type PreparedAttachment = {
+  readonly absolute: string;
+  readonly snapshotPath: string;
+};
+
+/**
+ * Snapshot deferred inputs sequentially before identity side effects. The staging
+ * files keep aggregate attachment bytes off heap until their final run is known.
+ */
+async function removePreparedAttachmentDirectory(stagingDirectory: string): Promise<void> {
+  await rm(stagingDirectory, { recursive: true, force: true });
+}
+
+/** Own the complete deferred-snapshot lifetime without masking either failure. */
+export async function withPreparedAttachments<T>(
+  attachmentPaths: readonly string[],
+  use: (prepared: readonly PreparedAttachment[]) => Promise<T>,
+): Promise<T> {
+  if (attachmentPaths.length === 0) return await use([]);
+  const stagingDirectory = await mkdtemp(join(tmpdir(), "ak-role-attachments-"));
+  const prepared: PreparedAttachment[] = [];
+  let result: T;
+  try {
+    for (let index = 0; index < attachmentPaths.length; index += 1) {
+      const { absolute, bytes } = await readRegularFileAttachment(attachmentPaths[index]!);
+      const snapshotPath = join(stagingDirectory, String(index).padStart(6, "0"));
+      await writeFile(snapshotPath, bytes);
+      prepared.push({ absolute, snapshotPath });
+    }
+    result = await use(prepared);
+  } catch (primary) {
+    try {
+      await removePreparedAttachmentDirectory(stagingDirectory);
+    } catch (cleanup) {
+      throw new AggregateError(
+        [primary, cleanup],
+        "attachment snapshot operation failed and cleanup also failed",
+        { cause: primary },
+      );
+    }
+    throw primary;
+  }
+  await removePreparedAttachmentDirectory(stagingDirectory);
+  return result;
+}
+
+async function freezeAttachmentBytes(
+  provenancePath: string,
+  bytes: Buffer,
+  destinationDir: string,
+  index: number,
+): Promise<FrozenAttachment> {
+  const frozenPath = join(
+    destinationDir,
+    `${String(index).padStart(2, "0")}-${basename(provenancePath)}`,
+  );
   await writeFile(frozenPath, bytes);
   return {
-    attachment: {
-      provenancePath: absolute,
-      frozenPath,
-      byteLength: bytes.byteLength,
-      sha256: sha256Hex(bytes),
-      mediaKind: "regular-file",
-    },
+    provenancePath,
+    frozenPath,
+    byteLength: bytes.byteLength,
+    sha256: sha256Hex(bytes),
+    mediaKind: "regular-file",
+  };
+}
+
+async function freezePreparedAttachment(
+  prepared: PreparedAttachment,
+  destinationDir: string,
+  index: number,
+): Promise<FrozenAttachment> {
+  return freezeAttachmentBytes(
+    prepared.absolute,
+    await readFile(prepared.snapshotPath),
+    destinationDir,
+    index,
+  );
+}
+
+async function freezeRegularFileAttachment(
+  sourcePath: string,
+  destinationDir: string,
+  index: number,
+): Promise<{ attachment: FrozenAttachment; body: Buffer }> {
+  const { absolute, bytes } = await readRegularFileAttachment(sourcePath);
+  return {
+    attachment: await freezeAttachmentBytes(absolute, bytes, destinationDir, index),
     body: bytes,
   };
 }
@@ -1270,6 +1396,25 @@ export async function freezeAttachmentsIntoRun(
   return freezeAttachments(attachmentPaths, attachmentsDirectory);
 }
 
+/** Freeze prepared bytes and metadata through one path for birth or retained runs. */
+export async function freezePreparedAttachmentsIntoRun(
+  prepared: readonly PreparedAttachment[],
+  runDirectory: string,
+  summonsKey?: string,
+): Promise<readonly FrozenAttachment[]> {
+  if (prepared.length === 0) return [];
+  const ledgerHome = resolveActivationLedgerHome(homeFromRunDirectory(runDirectory));
+  const attachmentsDirectory = summonsKey === undefined
+    ? join(runDirectory, "attachments")
+    : join(runDirectory, "attachments", summonsKey);
+  ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
+  const attachments: FrozenAttachment[] = [];
+  for (let index = 0; index < prepared.length; index += 1) {
+    attachments.push(await freezePreparedAttachment(prepared[index]!, attachmentsDirectory, index));
+  }
+  return attachments;
+}
+
 function ticketAdmissionFields(
   ticketNumber: number | undefined,
 ): { ticketNumber?: number } {
@@ -1515,11 +1660,13 @@ export type AdmitCountersignInvocationOptions = {
   /** Effective model for this invocation — written onto invocation.json. */
   model?: InvocationEffectiveModel;
   correlationId?: string;
+  /** Same-ticket lookup may select an existing run before a new run is persisted. */
+  deferPersistence?: boolean;
 };
 
 /**
- * Atomically admit a Countersign Role run: freeze Attachments, persist the
- * request, write the invocation ledger (#572 / ADR 0074).
+ * Admit a Countersign run immediately, or reserve its coordinates for deferred
+ * materialization after identity lookup (#572 / ADR 0074 / #863).
  */
 export async function admitCountersignInvocation(
   options: AdmitCountersignInvocationOptions,
@@ -1545,9 +1692,12 @@ export async function admitCountersignInvocation(
     role: "countersign",
     subject: { unbound: true },
     home: options.home,
+    materialize: options.deferPersistence !== true,
   });
 
-  const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
+  const attachments = options.deferPersistence === true
+    ? []
+    : await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
   // Ticket binding is LLM-only post-admission (#635); admission stays unbound.
 
   const instruction = options.instruction;
@@ -1571,11 +1721,13 @@ export async function admitCountersignInvocation(
     })),
   };
   const admittedRequestPath = join(runDirectory, "admitted-request.json");
-  await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
-    sessionDirectory,
-    sessionFile,
-  });
-  await writeRoleInvocationLedger({ ...admitted, sessionDirectory, sessionFile }, admitted.role, options.model);
+  if (options.deferPersistence !== true) {
+    await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
+      sessionDirectory,
+      sessionFile,
+    });
+    await writeRoleInvocationLedger({ ...admitted, sessionDirectory, sessionFile }, admitted.role, options.model);
+  }
 
   return {
     role: "countersign",
@@ -1592,6 +1744,36 @@ export async function admitCountersignInvocation(
   };
 }
 
+/** Persist a deferred Countersign admission after same-ticket lookup found no retained run. */
+export async function materializeCountersignInvocation(
+  admitted: AdmittedCountersignInvocation,
+  options: Pick<AdmitCountersignInvocationOptions, "home" | "principalAuthority" | "model"> & {
+    preparedAttachments: readonly PreparedAttachment[];
+  },
+): Promise<void> {
+  const placement = issueAdmissionPlacement(options.principalAuthority, {
+    cwd: admitted.projectRoot,
+    runId: admitted.runId,
+    role: "countersign",
+    subject: { unbound: true },
+    home: options.home,
+  });
+  const attachments = await freezePreparedAttachmentsIntoRun(
+    options.preparedAttachments,
+    admitted.runDirectory,
+  );
+  (admitted as { attachments: readonly FrozenAttachment[] }).attachments = attachments;
+  await writeAdmittedRequestPersistence(admitted.admittedRequestPath, admitted, {
+    sessionDirectory: placement.sessionDirectory,
+    sessionFile: placement.sessionFile,
+  });
+  await writeRoleInvocationLedger(
+    { ...admitted, sessionDirectory: placement.sessionDirectory, sessionFile: placement.sessionFile },
+    admitted.role,
+    options.model,
+  );
+}
+
 /** Build the Pi prompt transport for an admitted Countersign request. */
 export function buildCountersignTransportPrompt(
   admitted: AdmittedCountersignInvocation,

package/src/role-envelope.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import { createServer, type Server, type Socket } from "node:net";
-import { basename, dirname, join } from "node:path";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
@@ -13,15 +13,14 @@ import { requireGatekeeperPass } from "./gatekeeper-pass-envelope.ts";
 import type {
   HostContext,
   HostEventRegistration,
-  HostSkillExpansionEvidence,
   HostToolDefinition,
   RoleEnvelopeHost,
   RoleHost,
   RoleTurnKnownFailure,
   RoleTurnRequest,
 } from "./host-contracts.ts";
+import { hostMethodSkills, installWorkspaceMethodSkills } from "./host-native-method.ts";
 import { packagedRoleOutputTool } from "./packaged-role-registry.ts";
-import { stripSkillFrontmatter } from "./package-resources/method-skill.ts";
 import {
   createRoleRuntimeExtension,
   type RoleRuntimeDependencies,
@@ -44,30 +43,6 @@ type RpcRequest = { readonly id: number; readonly token: string; readonly method
 type ToolCallParams = { readonly name?: unknown; readonly arguments?: unknown };
 type ContentPart = { type: "text"; text: string } | { type: "image"; data: string; mimeType: string };
 
-/**
- * Build host-side Skill expansion evidence from pre-read RoleTurnRequest.methods.
- * Non-pi hosts never parse Pi `/skill:` syntax (ADR 0082: pi is one adapter with
- * no privilege; Pi-only seams stay inside the pi adapter);
- * a single bound method treats the plain prompt as the preserved user message.
- * Pi-native slash forms stay inside `src/pi/` only.
- */
-export function buildSkillExpansion(
-  methodSkills: ReadonlyMap<string, { readonly path: string; readonly body: string }>,
-  prompt: string,
-): HostSkillExpansionEvidence | undefined {
-  if (methodSkills.size !== 1) return undefined;
-  const entry = methodSkills.entries().next().value;
-  if (entry === undefined) return undefined;
-  const [name, method] = entry;
-  return Object.freeze({
-    name,
-    location: method.path,
-    content: method.body,
-    // Non-pi typed chain keeps original task bytes (ticket #822 r3); no consumer trim.
-    userMessage: prompt,
-  });
-}
-
 async function listen(server: Server, path: string): Promise<void> {
   await new Promise<void>((resolve, reject) => {
     server.once("error", reject);
@@ -129,7 +104,6 @@ export async function prepareRoleEnvelope(options: {
   const customEntries: Array<{ customType: string; data: unknown }> = [];
   /** In-memory turn books for role lifecycle and audit subjects. */
   const sessionEntries: Array<Record<string, unknown>> = [];
-  const methodSkills = new Map<string, { path: string; body: string }>();
   let preferredTools: string[] = [];
   let rejection:
     | { readonly code: string; readonly toolCallIds: readonly string[]; readonly message: string }
@@ -140,14 +114,6 @@ export async function prepareRoleEnvelope(options: {
   const runId = request.runDirectory.split("/").filter(Boolean).at(-1) ?? randomUUID();
   await mkdir(request.runDirectory, { recursive: true });
 
-  // Canonical Skill expansion consumes RoleTurnRequest.methods (typed true source).
-  for (const method of request.methods) {
-    if (method.kind !== "skill") continue;
-    const name = basename(dirname(method.path));
-    const raw = await readFile(method.path, "utf8");
-    methodSkills.set(name, { path: method.path, body: stripSkillFrontmatter(raw).trim() });
-  }
-
   // Durable principal file for isAvailable / resumable settlement (public-cli).
   // #617 DK-4: header layout only — never host conversation/tool writeback into Pi JSONL.
   let sessionFile = options.sessionFile ?? join(request.runDirectory, "session", "session.jsonl");
@@ -219,9 +185,8 @@ export async function prepareRoleEnvelope(options: {
       // #836 删 1/A4.5: do not arm closeRound retry with「终局交卷并非本轮唯一工具调用」.
     },
     capabilities: {
-      skillExpansion(prompt): HostSkillExpansionEvidence | undefined {
-        return buildSkillExpansion(methodSkills, prompt);
-      },
+      // #922: native loaders own expansion; package does not pre-read bodies (ADR 0032).
+      skillExpansion() { return undefined; },
     },
     registerFlag(name, definition) { if (!flags.has(name) && definition.default !== undefined) flags.set(name, definition.default); },
     getFlag(name) { return flags.get(name); },
@@ -625,14 +590,10 @@ export async function prepareRoleEnvelope(options: {
         message: { role: "user", content: prompt },
       });
     }
-    // Method notes only here — role before_agent_start injects soul once.
-    // Preloading session materials duplicated soul under the role tag (#632).
-    // #879: case-dossier owner reads runDirectory from this turn's HostContext.
-
-    const methodPrompt = (await Promise.all(request.methods.map(({ path }) => readFile(path, "utf8")))).join("\n\n");
+    // Soul/materials only — forced methods use host-native loaders (#922/#632/#879).
     const promptResults = await emit("before_agent_start", {
       prompt,
-      systemPrompt: methodPrompt,
+      systemPrompt: "",
       systemPromptOptions: {},
     });
     const systemPromptParts = promptResults.flatMap((value) => {
@@ -640,7 +601,7 @@ export async function prepareRoleEnvelope(options: {
       if (!("systemPrompt" in value) || typeof value.systemPrompt !== "string") return [];
       return [value.systemPrompt];
     });
-    const systemPromptBody = systemPromptParts.length > 0 ? systemPromptParts.join("\n\n") : methodPrompt;
+    const systemPromptBody = systemPromptParts.join("\n\n");
     // Typed reading materials from agent-start handlers (incl. single shared
     // case-dossier owner). Folded into provider-visible systemPrompt at send.
     const readingMaterials: unknown[] = [];
@@ -656,6 +617,15 @@ export async function prepareRoleEnvelope(options: {
       throw new Error(`terminating tool not registered after activation: ${terminatingToolName}`);
     }
     const jsonSchema = terminatingToolJsonSchema(terminating.parameters);
+
+    if (request.host === "codex" && hostMethodSkills(request.methods).length > 0) {
+      const packageRoot = options.dependencies.packageRoot;
+      if (typeof packageRoot !== "string" || packageRoot === "") {
+        throw new Error("codex project Skill catalog requires packageRoot");
+      }
+      await installWorkspaceMethodSkills(request.cwd, packageRoot);
+    }
+
     return {
       mcpServers: [{
         name: `ak-${request.activation.role}`,

package/src/role-runtime-dependencies.ts

@@ -10,8 +10,15 @@ import { loadNavigatorWorkContext } from "./navigator-work-context.ts";
 import { loadNotarySourceRunLocator } from "./notary-source-run.ts";
 import { loadPackagedCanonicalSkillBinding } from "./package-resources/method-skill-binding.ts";
 import { formatNavigatorRoleHelp, type RoleRuntimeDependencies } from "./role-runtime.ts";
-import { loadAuditorSoulFromSubjectInput } from "./auditor-soul.ts";
-import { loadGatekeeperSessionMaterials, loadMainRoleSessionMaterials } from "./session-opening-materials.ts";
+import {
+  loadAuditorReferenceMaterialsFromSubjectInput,
+  loadAuditorSoulFromSubjectInput,
+} from "./auditor-soul.ts";
+import {
+  loadGatekeeperSessionMaterials,
+  loadMainRoleReferenceMaterials,
+  loadMainRoleSessionMaterials,
+} from "./session-opening-materials.ts";
 
 const navigatorRoutePlaybookPath = fileURLToPath(
   new URL("../resources/navigator-route-playbook.md", import.meta.url),
@@ -20,12 +27,20 @@ const collectorHandbookSeedPath = fileURLToPath(
   new URL("../resources/collector-bot-handbook.md", import.meta.url),
 );
 
+/** Single packaged source for reference materials across production composition roots. */
+export function loadPackagedRoleReferenceMaterials(role: Parameters<NonNullable<RoleRuntimeDependencies["loadRoleReferenceMaterials"]>>[0]): Promise<string> {
+  return role === "auditor"
+    ? loadAuditorReferenceMaterialsFromSubjectInput()
+    : loadMainRoleReferenceMaterials(role);
+}
+
 /** Host-neutral packaged role runtime deps for the parent-process envelope. */
 export function createRoleRuntimeDependencies(packageRoot: string): RoleRuntimeDependencies {
   const doctorAuditor = createPiDoctorAuditor();
   const navigatorSessionFactory = createNativeNavigatorSessionFactory();
   return {
     packageRoot,
+    loadRoleReferenceMaterials: loadPackagedRoleReferenceMaterials,
     loadJudgeSoul: () => loadMainRoleSessionMaterials("judge"),
     loadFixerSoul: () => loadMainRoleSessionMaterials("fixer"),
     loadFixPacket: (path) => readFile(path, "utf8"),

package/src/role-runtime.ts

@@ -580,6 +580,8 @@ type NavigatorAttendanceDependency = Omit<NavigatorAttendance, "knownRoutePlaybo
 export type RoleRuntimeDependencies = {
   /** Package root for packaged engine-note resolution (#879). */
   packageRoot?: string;
+  /** Non-identity opening materials delivered in the ordinary role brief. */
+  loadRoleReferenceMaterials?(role: PackagedRole): Promise<string>;
   loadJudgeSoul(): Promise<string>;
   loadFixerSoul?(): Promise<string>;
   loadFixPacket?(path: string): Promise<string>;
@@ -1266,7 +1268,8 @@ export function createRoleRuntimeExtension(
     });
 
     let admitted = false;
-    let selectedRole: string | undefined;
+    let selectedRole: PackagedRole | undefined;
+    let roleReferenceMaterials = "";
     /** Live Reviewer parent activation for envelope agent_start prompt assembly. */
     let activeReviewerParent: ReviewerActivation | undefined;
     /** Envelope-owned Reviewer Skill expansion state (ADR 0018 — not a role-module facade). */
@@ -1379,14 +1382,14 @@ export function createRoleRuntimeExtension(
             activeReviewerParent.skillBinding.name,
             text,
           ) ?? text;
-        return text === event.text
-          ? { action: "continue" as const }
-          : { action: "transform" as const, text };
       }
-      return text === event.text
-        ? { action: "continue" as const }
-        : { action: "transform" as const, text };
+      return { action: "continue" as const };
     });
+    // Reference law/guides use the existing typed reading-material channel;
+    // they are not rewritten into operator dialogue or the identity Soul.
+    roleHost.on("before_agent_start", () => roleReferenceMaterials === ""
+      ? undefined
+      : { readingMaterial: { kind: "role-reference-materials", content: roleReferenceMaterials } });
     roleHost.on("before_agent_start", async (event, ctx) => {
       const role = roleHost.getFlag(ROLE_FLAG.name);
       const prompt = event.prompt;
@@ -2070,6 +2073,7 @@ export function createRoleRuntimeExtension(
       }
       admitted = false;
       selectedRole = undefined;
+      roleReferenceMaterials = "";
       activeReviewerParent = undefined;
       reviewerOriginalRequest = undefined;
       reviewerExpansionCaptured = false;
@@ -2230,6 +2234,7 @@ export function createRoleRuntimeExtension(
         }
 
         await executeActivationStage(entry.role, activationStage(entry.role, runtime), { clock, writeTrace });
+        roleReferenceMaterials = await dependencies.loadRoleReferenceMaterials?.(entry.role) ?? "";
         // #357 T2 / #378 / #380 / #391 / #818: any role+engine activation registers the package detour tool once.
         // Gate is resolveEngineName (RoleHost flag → env fallback) — no per-engine execute branch; no role-module spawn.
         if (!engineDetourRegistered) {

package/src/session-opening-materials.ts

@@ -50,12 +50,28 @@ export async function joinPackageMaterials(
   relativePaths: readonly string[],
 ): Promise<string> {
   const chunks: string[] = [];
-  for (const relativePath of relativePaths) {
-    chunks.push(await readPackageMaterial(relativePath));
-  }
+  for (const relativePath of relativePaths) chunks.push(await readPackageMaterial(relativePath));
   return chunks.join("\n\n");
 }
 
+function roleSoulPath(role: string, materials: readonly string[]): string {
+  const suffix = `/souls/${role}.md`;
+  const path = materials.find((candidate) => `/${candidate}`.endsWith(suffix));
+  if (path === undefined) throw new Error(`session materials omit the ${role} Soul`);
+  return path;
+}
+
+async function loadSeparatedSessionPart(
+  role: string,
+  materials: readonly string[],
+  part: "soul" | "references",
+): Promise<string> {
+  const soul = roleSoulPath(role, materials);
+  return part === "soul"
+    ? readPackageMaterial(soul)
+    : joinPackageMaterials(materials.filter((path) => path !== soul));
+}
+
 type PublicRoleMaterials = {
   readonly [Role in PackagedRole]: Extract<
     (typeof PUBLIC_ROLE_RECORDS)[number],
@@ -72,10 +88,12 @@ export const MAIN_ROLE_SESSION_MATERIALS = {
 
 export type MainRoleSession = keyof typeof MAIN_ROLE_SESSION_MATERIALS;
 
-export function loadMainRoleSessionMaterials(
-  role: MainRoleSession,
-): Promise<string> {
-  return joinPackageMaterials(MAIN_ROLE_SESSION_MATERIALS[role]);
+export function loadMainRoleSessionMaterials(role: MainRoleSession): Promise<string> {
+  return loadSeparatedSessionPart(role, MAIN_ROLE_SESSION_MATERIALS[role], "soul");
+}
+
+export function loadMainRoleReferenceMaterials(role: MainRoleSession): Promise<string> {
+  return loadSeparatedSessionPart(role, MAIN_ROLE_SESSION_MATERIALS[role], "references");
 }
 
 /** Gatekeeper province; notary reuses the public notary materials definition. */
@@ -88,8 +106,6 @@ export const GATEKEEPER_SESSION_MATERIALS = {
 
 export type GatekeeperSessionRole = keyof typeof GATEKEEPER_SESSION_MATERIALS;
 
-export function loadGatekeeperSessionMaterials(
-  role: GatekeeperSessionRole,
-): Promise<string> {
-  return joinPackageMaterials(GATEKEEPER_SESSION_MATERIALS[role]);
+export function loadGatekeeperSessionMaterials(role: GatekeeperSessionRole): Promise<string> {
+  return loadSeparatedSessionPart(role, GATEKEEPER_SESSION_MATERIALS[role], "soul");
 }