@akagilnc/pi-workflow-roles 0.1.2521 → 0.1.2653-next.71811ca

package/src/role-runtime.ts

@@ -1,6 +1,14 @@
 import { writeSync } from "node:fs";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  ExplicitInternalActivationError,
+  type HostContext,
+  type RoleHost,
+} from "./host-contracts.ts";
+import { recordReviewerDispatchRejectionSync } from "./public-cli/reviewer-dispatch-rejection.ts";
+import { createPiRoleHostAdapter, toPiContext, type PiRoleHostAdapter } from "./pi/adapter.ts";
 import { Value } from "typebox/value";
+import { sitianReport } from "./sitian-facade.ts";
 
 import { activationTraceRecordSchema, namedActivationCause, type ActivationTraceRecord, type ActivationTraceWriter } from "./activation-trace.ts";
 import {
@@ -39,7 +47,7 @@ import {
 import type { ComplianceDecision } from "./compliance-transport.ts";
 import { createDoctorRoleRuntime } from "./doctor-role.ts";
 import { createNotaryRoleRuntime } from "./notary-role.ts";
-import { decorateSettlementWithNavigation, formatNavigatorReport, NAVIGATOR_EVENT_TYPE, navigatorSubjectKey, navigatorUnavailableError, subjectPath, type NavigatorAttendance, type NavigatorEvent, type NavigatorPhase, type NavigatorReport, type NavigatorSettlement, type NavigatorSubjectProvenance, type NavigatorWorkContext } from "./navigator-attendance.ts";
+import { decorateSettlementWithNavigation, formatNavigatorReport, NAVIGATOR_EVENT_TYPE, navigatorSubjectKey, navigatorUnavailableError, subjectPath, type NavigatorAttendance, type NavigatorAttendanceOptions, type NavigatorEvent, type NavigatorPhase, type NavigatorReport, type NavigatorSettlement, type NavigatorSubjectProvenance, type NavigatorWorkContext } from "./navigator-attendance.ts";
 import {
   buildNavigatorInfrastructureFailureFact,
   classifyPackagedRoleTerminalResult,
@@ -48,10 +56,6 @@ import {
   resolveLifecycleInvocationPrincipal,
 } from "./navigator-invocation-identity.ts";
 import { recordTypedProviderHttpStatus } from "./typed-provider-http.ts";
-import {
-  ExplicitInternalActivationError,
-  recordReviewerDispatchRejectionSync,
-} from "./public-cli/explicit-internal.ts";
 import { NAVIGATOR_POST_ROLE_GRACE_MS, raceNavigatorGrace } from "./public-cli/settlement.ts";
 import { PACKAGED_ROLE_REGISTRY, packagedRoleMetadata, packagedRoleOutputTool, packagedRolePhaseFlag, type PackagedRole } from "./packaged-role-registry.ts";
 import { isAuditEscalationProjection } from "./audit-escalation.ts";
@@ -197,7 +201,13 @@ import {
   FIXER_FLAG_DEFINITIONS,
   FIXER_OUTPUT_TOOL_NAME,
   FIXER_PHASES,
+  type CoderSkillExpansionEvidenceMissingResult,
 } from "./worker-role.ts";
+
+/** One envelope map for Gatekeeper non-pass and other correct submission rejects (#525). */
+type SubmissionNonPassResult =
+  | GatekeeperNonPassResult
+  | CoderSkillExpansionEvidenceMissingResult;
 import { JUDGE_OUTPUT_TOOL_NAME } from "./package-contracts/judge-output.ts";
 import { REVIEWER_OUTPUT_TOOL_NAME } from "./package-contracts/reviewer-output.ts";
 import { DOCTOR_OUTPUT_TOOL_NAME } from "./doctor-contracts.ts";
@@ -268,7 +278,7 @@ export {
 } from "./tool-execution-observation.ts";
 export type { ToolExecutionObservationRecord, ToolExecutionObservationWriter } from "./tool-execution-observation.ts";
 export { executeAuditorChild } from "./evidence-child-executor.ts";
-export type { AuditorCompletion, AuditorDecisionTool } from "./evidence-child-executor.ts";
+export type { AuditorDecisionTool } from "./evidence-child-executor.ts";
 export {
   NOTARY_OUTPUT_TOOL,
   INSPECTOR_OUTPUT_TOOL,
@@ -300,10 +310,13 @@ export {
 } from "./reviewer-role.ts";
 export {
   CODER_OUTPUT_TOOL_NAME,
+  CODER_SKILL_EXPANSION_EVIDENCE_MISSING_CODE,
+  CoderSkillExpansionEvidenceMissingError,
   FIXER_FLAG_DEFINITIONS,
   FIXER_OUTPUT_TOOL_NAME,
   FIXER_PHASES,
   type CoderOutput,
+  type CoderSkillExpansionEvidenceMissingResult,
   type FixerOutput,
   type WorkerOutput,
 } from "./worker-role.ts";
@@ -344,19 +357,19 @@ export type { MergerGitState, ActiveMergerGitState, CompletedMergerGitState } fr
 export type { MergerRoleDependencies } from "./merger-role.ts";
 
 type WorkerArmable = {
-  activate(context?: ExtensionContext): Promise<void>;
+  activate(context?: HostContext): Promise<void>;
   armSubmissionGate(cwd: string, parent?: { getSessionFile(): string | undefined }): void;
 };
 
 type ActivationRuntime = {
   event: { reason: string };
-  context: ExtensionContext;
+  context: HostContext;
   judge: { activate(): Promise<void> };
   fixer: WorkerArmable;
   coder: WorkerArmable;
   reviewer: {
     activate(
-      context: ExtensionContext,
+      context: HostContext,
       admitted: ReviewerAdmittedInputs,
     ): Promise<ReviewerActivation>;
   };
@@ -364,7 +377,7 @@ type ActivationRuntime = {
   decodeReviewerAdmitted(): ReviewerAdmittedInputs;
   /** Envelope stores live parent activation for agent_start prompt assembly. */
   bindReviewerParent(activation: ReviewerActivation): void;
-  collector: { activate(context: ExtensionContext, event: { reason: string }): Promise<void> };
+  collector: { activate(context: HostContext, event: { reason: string }): Promise<void> };
   doctor: { activate(): Promise<void> };
   notary: { activate(): Promise<void> };
   merger(): Promise<void>;
@@ -492,22 +505,22 @@ export type RoleRuntimeDependencies = {
   loadMergerInput?(path: string): Promise<unknown>;
   mergerGitState?: MergerRoleDependencies["gitState"];
   createMergerGitState?(repositoryRoot: string): MergerRoleDependencies["gitState"];
-  auditDoctorCompliance?(options: { context: ExtensionContext; signal?: AbortSignal }): Promise<ComplianceDecision>;
+  auditDoctorCompliance?(options: { context: HostContext; signal?: AbortSignal }): Promise<ComplianceDecision>;
   createCollectorClock?(): CollectorClock;
   collectorPackageExtensionPath?: string;
-  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>;
+  createNavigatorAttendance?(options: { context: HostContext; 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: HostContext; role: string; phase: NavigatorPhase }): Promise<NavigatorWorkContext>;
   loadCanonicalSkillBinding?(
     name: "tdd" | "code-review",
   ): Promise<AnyCanonicalSkillBinding>;
   runReviewerDispatch?(
     dispatch: AcceptedReviewerExecution,
-    options: { context: ExtensionContext; signal?: AbortSignal },
+    options: { context: HostContext; signal?: AbortSignal },
   ): Promise<ReviewerDispatchRunResult>;
   shutdownReviewerAgent?(): Promise<void>;
-  transcriptFromContext(ctx: ExtensionContext): string;
+  transcriptFromContext(ctx: HostContext): string;
   auditSoulCompliance(
-    options: { context: ExtensionContext; signal?: AbortSignal },
+    options: { context: HostContext; signal?: AbortSignal },
   ): Promise<SoulAuditResult>;
   activationClock?(): string;
   activationTraceWriter?: (record: ActivationTraceRecord) => void | Promise<void>;
@@ -524,12 +537,11 @@ export type RoleRuntimeDependencies = {
   oauthKeepalive?: OAuthKeepaliveOptions;
 };
 
-function abortContext(ctx: ExtensionContext): void {
-  const abort = (ctx as ExtensionContext & { abort?: () => void }).abort;
-  if (typeof abort === "function") abort.call(ctx);
+function abortContext(ctx: { abort(): void }): void {
+  ctx.abort();
 }
 
-function failInfrastructure(error: unknown, ctx: ExtensionContext): never {
+function failInfrastructure(error: unknown, ctx: { mode: string; abort(): void }): never {
   abortContext(ctx);
   if (ctx.mode === "print" || ctx.mode === "json") process.exitCode = 1;
   throw error;
@@ -564,11 +576,11 @@ function buildPendingInfrastructureFailure(error: unknown): PendingInfrastructur
   };
 }
 
-function navigatorPhase(pi: ExtensionAPI, role: string): NavigatorPhase {
+function navigatorPhase(roleHost: RoleHost, role: string): NavigatorPhase {
   const metadata = packagedRoleMetadata(role);
   if (metadata === undefined || metadata.phases[0] === null) return null;
   const phaseFlag = packagedRolePhaseFlag(role);
-  const requested = phaseFlag === undefined ? undefined : pi.getFlag(phaseFlag);
+  const requested = phaseFlag === undefined ? undefined : roleHost.getFlag(phaseFlag);
   return requested === "apply" ? "apply" : "plan";
 }
 
@@ -604,12 +616,15 @@ export function publicNavigatorSettlement(role: string, phase: NavigatorPhase, e
 
 export function createRoleRuntimeExtension(
   dependencies: RoleRuntimeDependencies,
+  injectedPiHostAdapter?: PiRoleHostAdapter,
 ): (pi: ExtensionAPI) => void {
   return (pi) => {
-    pi.registerFlag(ROLE_FLAG.name, ROLE_FLAG.definition);
+    const piHostAdapter = injectedPiHostAdapter ?? createPiRoleHostAdapter(pi);
+    const roleHost = piHostAdapter.host;
+    roleHost.registerFlag(ROLE_FLAG.name, ROLE_FLAG.definition);
     // Reviewer transport flags: shared envelope owns registration (ADR 0018).
     for (const flag of REVIEWER_TRANSPORT_FLAGS) {
-      pi.registerFlag(flag.name, flag.definition);
+      roleHost.registerFlag(flag.name, flag.definition);
     }
 
     let admitted = false;
@@ -627,15 +642,15 @@ export function createRoleRuntimeExtension(
     let navigatorWorkContext: NavigatorWorkContext | undefined;
     /** toolCallId → fact+evidence; one-shot projected onto durable tool_result (#475). */
     const pendingInfrastructureFailures = new Map<string, PendingInfrastructureFailure>();
-    // Envelope-owned execute→tool_result bridge for Gatekeeper non-pass (ADR 0018).
-    const pendingGatekeeperNonPassByToolCallId = new Map<string, GatekeeperNonPassResult>();
-    let engineDetourRegistered = false;
+    // Envelope-owned execute→tool_result bridge for submission non-pass (ADR 0018 / #525).
+    const pendingSubmissionNonPassByToolCallId = new Map<string, SubmissionNonPassResult>();
+    let engineDetourRegistration: ReturnType<typeof registerEngineDetourTool> | undefined;
     // #288 primary-session thin adapter. The policy is the sole budget owner;
     // terminating-tool rejections and mechanical delivery requests share two turns.
     let receiptDelivery = createReceiptDeliveryPolicy();
     let noReceiptRecorded = false;
-    pi.on("input", (event) => {
-      const role = pi.getFlag(ROLE_FLAG.name);
+    roleHost.on("input", (event) => {
+      const role = roleHost.getFlag(ROLE_FLAG.name);
       if (role !== undefined && !admitted) return { action: "handled" as const };
       // Envelope exclusively owns Reviewer Skill invocation transform + original-request capture.
       if (
@@ -653,8 +668,8 @@ export function createRoleRuntimeExtension(
       }
       return { action: "continue" as const };
     });
-    pi.on("before_agent_start", (event, ctx) => {
-      const role = pi.getFlag(ROLE_FLAG.name);
+    roleHost.on("before_agent_start", (event, ctx) => {
+      const role = roleHost.getFlag(ROLE_FLAG.name);
       if (role === undefined) return;
       if (!admitted || selectedRole !== role) {
         failInfrastructure(new ActivationBarrierError(role), ctx);
@@ -691,7 +706,10 @@ export function createRoleRuntimeExtension(
         if (!reviewerExpansionCaptured) {
           if (
             reviewerOriginalRequest === undefined
-            || activeReviewerParent.skillBinding.captureExpansion(event.prompt, reviewerOriginalRequest) === undefined
+            || activeReviewerParent.skillBinding.captureExpansion(
+              roleHost.capabilities?.skillExpansion(event.prompt),
+              reviewerOriginalRequest,
+            ) === undefined
           ) {
             failInfrastructure(
               new Error("Canonical code-review Skill expansion did not match the captured request"),
@@ -710,7 +728,7 @@ export function createRoleRuntimeExtension(
         };
       }
     });
-    pi.on("tool_result", async (event) => {
+    roleHost.on("tool_result", async (event) => {
       const role = selectedRole;
       if (role === undefined) return;
       const pendingInfra = pendingInfrastructureFailures.get(event.toolCallId);
@@ -729,14 +747,14 @@ export function createRoleRuntimeExtension(
         receiptDelivery.recordAccepted();
       } else if (isOutputTool && outputClassification?.kind === "nonterminal" && event.isError) {
         const reason = (event.content ?? [])
-          .map((part) => part.type === "text" ? part.text : "")
+          .map((part) => part.type === "text" && "text" in part ? part.text : "")
           .join("")
           .trim() || "terminating tool rejected";
         receiptDelivery.recordRejected(reason);
       }
       const settlement = publicNavigatorSettlement(
         role,
-        navigatorPhase(pi, role),
+        navigatorPhase(roleHost, role),
         classified,
       );
       if (settlement !== undefined) {
@@ -768,7 +786,7 @@ export function createRoleRuntimeExtension(
                 disposition: "unavailable",
                 invocationId: "post-role-grace-timeout",
                 role,
-                phase: navigatorPhase(pi, role),
+                phase: navigatorPhase(roleHost, role),
                 subjectKey: workContext?.subjectKey ?? "",
                 unavailableReason: "Navigator exceeded post-role delivery grace",
                 unavailableSource: "unknown",
@@ -790,12 +808,12 @@ export function createRoleRuntimeExtension(
       if (infrastructureDetails !== undefined) {
         return { details: infrastructureDetails, isError: true };
       }
-      // Gatekeeper non-pass: throw kept message text for the model; project the
+      // Submission non-pass: throw kept message text for the model; project the
       // envelope-bound structured result onto session details at this tool_result seam.
-      const gatekeeperNonPass = pendingGatekeeperNonPassByToolCallId.get(event.toolCallId);
-      if (gatekeeperNonPass !== undefined) {
-        pendingGatekeeperNonPassByToolCallId.delete(event.toolCallId);
-        return { details: gatekeeperNonPass, isError: true };
+      const submissionNonPass = pendingSubmissionNonPassByToolCallId.get(event.toolCallId);
+      if (submissionNonPass !== undefined) {
+        pendingSubmissionNonPassByToolCallId.delete(event.toolCallId);
+        return { details: submissionNonPass, isError: true };
       }
       // Recommendation rides the accepted settlement record's content so the one
       // mandatory last-ak_*_output extraction surfaces route/next/reason without
@@ -812,7 +830,7 @@ export function createRoleRuntimeExtension(
     // already decided no queued continuation will run, so a triggerTurn there is
     // too late for print/json sessions. `agent_end` is the last production seam
     // whose queued next turn is consumed before settlement.
-    pi.on("agent_end", (event) => {
+    roleHost.on("agent_end", (event, ctx) => {
       const lastMessage = event.messages.at(-1);
       if (lastMessage?.role === "assistant"
         && (lastMessage.stopReason === "error" || lastMessage.stopReason === "aborted")) {
@@ -826,6 +844,16 @@ export function createRoleRuntimeExtension(
         // Keep the package-owned continuation off the public input lifecycle:
         // one-shot roles must not mistake this delivery request for later caller input.
         pi.appendEntry("ak-receipt-delivery-request");
+        try {
+          sitianReport({
+            level: "event",
+            kind: "receipt-delivery",
+            cwd: ctx.cwd,
+            sessionParent: ctx.sessionManager.getSessionFile(),
+            payload: { type: "ak-receipt-delivery-request" },
+            source: "role-runtime",
+          });
+        } catch {}
         pi.sendMessage({
           customType: "ak-receipt-delivery-prompt",
           content: RECEIPT_DELIVERY_PROMPT,
@@ -835,14 +863,22 @@ export function createRoleRuntimeExtension(
         const runPointer = process.env.AK_ROLE_RUN_DIR;
         if (runPointer !== undefined) {
           noReceiptRecorded = true;
-          pi.appendEntry(
-            NO_RECEIPT_LIFECYCLE_ENTRY_TYPE,
-            receiptDelivery.facts({ runPointer, attemptPointer: `current:${runPointer}` }),
-          );
+          const facts = receiptDelivery.facts({ runPointer, attemptPointer: `current:${runPointer}` });
+          pi.appendEntry(NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, facts);
+          try {
+            sitianReport({
+              level: "event",
+              kind: "no-receipt-lifecycle",
+              cwd: ctx.cwd,
+              sessionParent: ctx.sessionManager.getSessionFile(),
+              payload: facts,
+              source: "role-runtime",
+            });
+          } catch {}
         }
       }
     });
-    pi.on("agent_settled", async () => {
+    roleHost.on("agent_settled", async () => {
       if (pendingNavigatorSettlement !== undefined) {
         await pendingNavigatorSettlement;
       }
@@ -864,7 +900,7 @@ export function createRoleRuntimeExtension(
         details: presentation.event,
       }, { triggerTurn: false });
     });
-    pi.on("session_shutdown", async () => {
+    roleHost.on("session_shutdown", async () => {
       // #351: stop OAuth keepalive first so shutdown yields zero further ticks.
       oauthKeepalive.stop();
       // Flush any still-pending affirmative attendance before teardown. Accepted
@@ -887,23 +923,23 @@ export function createRoleRuntimeExtension(
       navigatorAttendance = undefined;
       pendingNavigatorSettlement = undefined;
       pendingInfrastructureFailures.clear();
-      pendingGatekeeperNonPassByToolCallId.clear();
+      pendingSubmissionNonPassByToolCallId.clear();
       observationFace.reset();
     });
 
     const hostActions = {
-      failInfrastructure(error: unknown, ctx: ExtensionContext, toolCallId?: string): never {
+      failInfrastructure(error: unknown, ctx: HostContext, toolCallId?: string): never {
         if (toolCallId !== undefined) {
           pendingInfrastructureFailures.set(toolCallId, buildPendingInfrastructureFailure(error));
         }
         failInfrastructure(error, ctx);
       },
-      bindGatekeeperNonPass(toolCallId: string, result: GatekeeperNonPassResult): void {
-        pendingGatekeeperNonPassByToolCallId.set(toolCallId, result);
+      bindSubmissionNonPass(toolCallId: string, result: SubmissionNonPassResult): void {
+        pendingSubmissionNonPassByToolCallId.set(toolCallId, result);
       },
     };
     const judge = createJudgeRoleRuntime(
-      pi,
+      roleHost,
       {
         loadSoul: dependencies.loadJudgeSoul,
         auditSoulCompliance: dependencies.auditSoulCompliance,
@@ -911,7 +947,7 @@ export function createRoleRuntimeExtension(
       hostActions,
     );
     const fixer = createFixerRoleRuntime(
-      pi,
+      roleHost,
       {
         async loadSoul() {
           if (dependencies.loadFixerSoul === undefined) {
@@ -929,7 +965,7 @@ export function createRoleRuntimeExtension(
       hostActions,
     );
     const coder = createCoderRoleRuntime(
-      pi,
+      roleHost,
       {
         async loadSoul() {
           if (dependencies.loadCoderSoul === undefined) {
@@ -953,7 +989,7 @@ export function createRoleRuntimeExtension(
       hostActions,
     );
     const reviewer = createReviewerRoleRuntime(
-      pi,
+      roleHost,
       {
         async loadSoul() {
           if (dependencies.loadReviewerSoul === undefined) {
@@ -984,12 +1020,12 @@ export function createRoleRuntimeExtension(
       },
       hostActions,
     );
-    const doctor = createDoctorRoleRuntime(pi, {
+    const doctor = createDoctorRoleRuntime(roleHost, {
       async loadSoul() { if (!dependencies.loadDoctorSoul) throw new Error("Doctor runtime dependencies are not configured"); return dependencies.loadDoctorSoul(); },
       async loadCase(path) { if (!dependencies.loadDoctorCase) throw new Error("Doctor runtime dependencies are not configured"); return dependencies.loadDoctorCase(path); },
       async auditCompliance(options) { if (!dependencies.auditDoctorCompliance) throw new Error("Doctor runtime dependencies are not configured"); return dependencies.auditDoctorCompliance(options); },
     }, hostActions);
-    const notary = createNotaryRoleRuntime(pi, {
+    const notary = createNotaryRoleRuntime(roleHost, {
       async loadSoul() {
         if (!dependencies.loadNotarySoul) throw new Error("Notary runtime dependencies are not configured");
         return dependencies.loadNotarySoul();
@@ -1000,7 +1036,7 @@ export function createRoleRuntimeExtension(
       },
     }, hostActions);
     let sessionMergerGitState = dependencies.mergerGitState;
-    const merger = createMergerRoleRuntime(pi, {
+    const merger = createMergerRoleRuntime(roleHost, {
       async loadSoul() { if (!dependencies.loadMergerSoul) throw new Error("Merger runtime dependencies are not configured"); return dependencies.loadMergerSoul(); },
       async loadInput(path) { if (!dependencies.loadMergerInput) throw new Error("Merger runtime dependencies are not configured"); return dependencies.loadMergerInput(path); },
       gitState: {
@@ -1009,7 +1045,7 @@ export function createRoleRuntimeExtension(
       },
     }, hostActions);
     const collector = createCollectorRoleRuntime(
-      pi,
+      roleHost,
       {
         async loadSoul() {
           if (dependencies.loadCollectorSoul === undefined) {
@@ -1049,7 +1085,7 @@ export function createRoleRuntimeExtension(
     // (abort + nonzero print/json exit) with the original cause before that swallow.
     const observe = async (
       run: () => void | Promise<void>,
-      ctx: ExtensionContext,
+      ctx: HostContext,
     ): Promise<void> => {
       try {
         await run();
@@ -1057,20 +1093,20 @@ export function createRoleRuntimeExtension(
         failInfrastructure(error, ctx);
       }
     };
-    pi.on("tool_execution_start", async (event, ctx) => {
+    roleHost.on("tool_execution_start", async (event, ctx) => {
       await observe(() => observationFace.onStart(event), ctx);
     });
-    pi.on("tool_execution_update", async (event, ctx) => {
+    roleHost.on("tool_execution_update", async (event, ctx) => {
       await observe(() => observationFace.onUpdate(event), ctx);
     });
-    pi.on("tool_execution_end", async (event, ctx) => {
+    roleHost.on("tool_execution_end", async (event, ctx) => {
       await observe(() => observationFace.onEnd(event), ctx);
     });
 
     // Public Role run: record typed non-success HTTP for error evidence + v1 resume.
     // 2xx clears prior observation (see recordTypedProviderHttpStatus). Non-success
     // write failure must surface — never silently drop authorized error evidence.
-    pi.on("after_provider_response", async (event, ctx) => {
+    roleHost.on("after_provider_response", async (event, ctx) => {
       const runDir = process.env.AK_ROLE_RUN_DIR;
       if (typeof runDir !== "string" || runDir.trim() === "") return;
       const provider = ctx.model?.provider;
@@ -1096,7 +1132,7 @@ export function createRoleRuntimeExtension(
       }
     });
 
-    pi.on("session_start", async (event, ctx) => {
+    roleHost.on("session_start", async (event, ctx) => {
       admitted = false;
       selectedRole = undefined;
       activeReviewerParent = undefined;
@@ -1108,12 +1144,13 @@ export function createRoleRuntimeExtension(
       pendingNavigatorPresentation = undefined;
       pendingNavigatorSettlement = undefined;
       pendingInfrastructureFailures.clear();
-      pendingGatekeeperNonPassByToolCallId.clear();
+      pendingSubmissionNonPassByToolCallId.clear();
+      engineDetourRegistration?.resetLatch();
       navigatorWorkContext = undefined;
       // #351: OAuth keepalive is orthogonal to --ak-role; start before role early-return
       // so role-less sessions (and reload after shutdown stop) still keep tokens alive.
-      oauthKeepalive.start(ctx);
-      const rawRole = pi.getFlag(ROLE_FLAG.name);
+      oauthKeepalive.start(toPiContext(ctx));
+      const rawRole = roleHost.getFlag(ROLE_FLAG.name);
       if (rawRole === undefined) return;
       const entry = PACKAGED_ROLE_REGISTRY.find(({ role }) => role === rawRole);
       if (entry === undefined) {
@@ -1130,7 +1167,7 @@ export function createRoleRuntimeExtension(
         coder,
         reviewer,
         decodeReviewerAdmitted() {
-          return decodeReviewerAdmittedInputs((name) => pi.getFlag(name));
+          return decodeReviewerAdmittedInputs((name) => roleHost.getFlag(name));
         },
         bindReviewerParent(activation) {
           activeReviewerParent = activation;
@@ -1164,7 +1201,7 @@ export function createRoleRuntimeExtension(
             work = { subjectKey: fallbackSubjectKey, subject: `work subject: ${fallbackSubjectKey}`, authority: "", subjectProvenance: "placeholder" };
           } else {
             try {
-              work = await dependencies.loadNavigatorWorkContext({ context: ctx, role: entry.role, phase: navigatorPhase(pi, entry.role) });
+              work = await dependencies.loadNavigatorWorkContext({ context: ctx, role: entry.role, phase: navigatorPhase(roleHost, entry.role) });
               contextError = work.contextError;
             } catch (error) {
               // Contract: README.md#Navigator-attendance — a failed context load continues with a typed placeholder work context; the original cause is retained in contextError for the typed unavailable report.
@@ -1178,8 +1215,8 @@ export function createRoleRuntimeExtension(
           // session_start is process activation: resume unfinished principal only when marker
           // role/phase/subjectKey still match; mint for contradictory marker, malformed nearest,
           // missing marker, or terminal already completed.
-          const sessionEntries = ctx.sessionManager.getEntries();
-          const invocationPhase = navigatorPhase(pi, entry.role);
+          const sessionEntries = [...ctx.sessionManager.getEntries()];
+          const invocationPhase = navigatorPhase(roleHost, entry.role);
           const lifecyclePrincipal = resolveLifecycleInvocationPrincipal(sessionEntries, {
             role: entry.role,
             phase: invocationPhase,
@@ -1187,12 +1224,23 @@ export function createRoleRuntimeExtension(
           });
           const invocationId = lifecyclePrincipal.invocationId;
           if (!lifecyclePrincipal.resume) {
-            pi.appendEntry(NAVIGATOR_INVOCATION_ENTRY, {
+            const data = {
               invocationId,
               role: entry.role,
               phase: invocationPhase,
               subjectKey: work.subjectKey,
-            });
+            };
+            pi.appendEntry(NAVIGATOR_INVOCATION_ENTRY, data);
+            try {
+              sitianReport({
+                level: "event",
+                kind: "attendance",
+                cwd: ctx.cwd,
+                sessionParent: ctx.sessionManager.getSessionFile(),
+                payload: { type: NAVIGATOR_INVOCATION_ENTRY, ...data },
+                source: "role-runtime",
+              });
+            } catch {}
           }
           navigatorAttendance = await dependencies.createNavigatorAttendance({
             context: ctx,
@@ -1223,8 +1271,11 @@ export function createRoleRuntimeExtension(
         await executeActivationStage(entry.role, activationStage(entry.role, runtime), { clock, writeTrace });
         // #357 T2 / #378 / #380 / #391: any role+engine activation registers the package detour tool once.
         // Gate is env presence only — no per-engine execute branch; no role-module spawn.
-        if (!engineDetourRegistered) {
-          engineDetourRegistered = registerEngineDetourTool(pi, hostActions);
+        if (engineDetourRegistration === undefined) {
+          engineDetourRegistration = registerEngineDetourTool(roleHost, hostActions);
+          if (!engineDetourRegistration.registered) {
+            engineDetourRegistration = undefined;
+          }
         }
         // Worker gates ①②: arm records baseline and runs private one-shot hook uninstall (ADR 0070).
         // Parent session feeds #216 createRecordSession so baseline/bounce survive resume.

package/src/session-opening-materials.ts

@@ -1,14 +1,19 @@
 /**
- * Session opening materials (#443): factory constitution + role soul + role-owned
- * extras, composed at the three existing loader seams. Missing files fail as
- * native readFile errors — no exists/hash/empty guards, no second loader.
- *
- * Auditor composition stays owned by loadAuditorSoul (blank-soul identity);
- * main roles and gatekeeper family share joinPackageMaterials here.
+ * Session opening materials (#443 / #524). Missing files fail as native readFile
+ * errors. Main-role materials derive from PUBLIC_ROLE_RECORDS; gatekeeper seats
+ * stay independent except notary (shared NOTARY_SESSION_MATERIALS). Navigator is
+ * name-only here, not a public role record. Auditor composition stays in
+ * loadAuditorSoul; loaders share joinPackageMaterials.
  */
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 
+import {
+  NOTARY_SESSION_MATERIALS,
+  PUBLIC_ROLE_RECORDS,
+  type PackagedRole,
+} from "./packaged-role-registry.ts";
+
 const packageRootUrl = new URL("..", import.meta.url);
 
 /** Self-locate one package-relative material. Native I/O errors propagate. */
@@ -27,38 +32,19 @@ export async function joinPackageMaterials(
   return chunks.join("\n\n");
 }
 
-/** Seven public main roles + Navigator. Ticket #443 injection roster. */
+type PublicRoleMaterials = {
+  readonly [Role in PackagedRole]: Extract<
+    (typeof PUBLIC_ROLE_RECORDS)[number],
+    { role: Role }
+  >["sessionMaterials"];
+};
+
+/** Derived projection: public records + navigator name-only materials. */
 export const MAIN_ROLE_SESSION_MATERIALS = {
-  judge: [
-    "CLAUDE.md",
-    "souls/judge.md",
-    "souls/audit-law.md",
-    "souls/quality-law.md",
-    "souls/judge-output-guide.md",
-  ],
-  fixer: [
-    "CLAUDE.md",
-    "souls/fixer.md",
-    "souls/quality-law.md",
-    "souls/fixer-output-guide.md",
-  ],
-  coder: [
-    "CLAUDE.md",
-    "souls/coder.md",
-    "souls/quality-law.md",
-    "souls/coder-output-guide.md",
-  ],
-  reviewer: [
-    "CLAUDE.md",
-    "souls/reviewer.md",
-    "souls/audit-law.md",
-    "souls/quality-law.md",
-  ],
-  collector: ["CLAUDE.md", "souls/collector.md"],
-  doctor: ["CLAUDE.md", "souls/doctor.md"],
-  merger: ["CLAUDE.md", "souls/merger.md"],
-  notary: ["CLAUDE.md", "souls/notary.md", "souls/gate-output-guide.md"],
-  navigator: ["CLAUDE.md", "souls/navigator.md"],
+  ...(Object.fromEntries(
+    PUBLIC_ROLE_RECORDS.map((record) => [record.role, record.sessionMaterials]),
+  ) as PublicRoleMaterials),
+  navigator: ["CLAUDE.md", "souls/navigator.md"] as const,
 } as const;
 
 export type MainRoleSession = keyof typeof MAIN_ROLE_SESSION_MATERIALS;
@@ -69,7 +55,7 @@ export function loadMainRoleSessionMaterials(
   return joinPackageMaterials(MAIN_ROLE_SESSION_MATERIALS[role]);
 }
 
-/** Gatekeeper province + Inspector/Notary officer sessions. */
+/** Gatekeeper province; notary reuses the public notary materials definition. */
 export const GATEKEEPER_SESSION_MATERIALS = {
   gatekeeper: [
     "CLAUDE.md",
@@ -83,7 +69,7 @@ export const GATEKEEPER_SESSION_MATERIALS = {
     "souls/quality-law.md",
     "souls/gate-output-guide.md",
   ],
-  notary: ["CLAUDE.md", "souls/notary.md", "souls/gate-output-guide.md"],
+  notary: NOTARY_SESSION_MATERIALS,
 } as const;
 
 export type GatekeeperSessionRole = keyof typeof GATEKEEPER_SESSION_MATERIALS;