@akagilnc/pi-workflow-roles 0.1.5068 → 0.1.5096

package/src/inspector-contracts.ts

@@ -4,7 +4,7 @@
  * Dual path: gate-dispatched and independently callable (#568 / ADR 0074).
  */
 
-import { REVIEW_SUBMISSION_OUTPUT_TOOL_NAME } from "./review-submission.ts";
+import { REVIEW_QUEUE_STATUSES, REVIEW_SUBMISSION_OUTPUT_TOOL_NAME } from "./review-submission.ts";
 
 export const INSPECTOR_OUTPUT_TOOL_NAME: string = REVIEW_SUBMISSION_OUTPUT_TOOL_NAME;
 export const INSPECTOR_SOURCE_RUN_FLAG = {
@@ -30,7 +30,10 @@ export function validateRecordedInspectorOutput(value: unknown): InspectorOutput
   } catch {
     throw new Error("Inspector output has no execution discriminator");
   }
-  if (status === "converged" || status === "continue" || status === "escalate") {
+  if (typeof status !== "string") {
+    throw new Error("Inspector output has no execution discriminator");
+  }
+  if (REVIEW_QUEUE_STATUSES.has(status)) {
     return value as InspectorOutput;
   }
   throw new Error("Inspector output has no execution discriminator");

package/src/inspector-role.ts

@@ -13,7 +13,7 @@ export { INSPECTOR_OUTPUT_TOOL_NAME as INSPECTOR_OUTPUT_TOOL };
 export type { InspectorOutput };
 export { validateRecordedInspectorOutput };
 
-/** 台院事后察举交卷形状；形状指引，非 schema 闸。 */
+/** 台院事后察举交卷形状。 */
 export const inspectorOutputSchema = reviewSubmissionSchema;
 
 export type InspectorOutputParameters = Static<typeof inspectorOutputSchema>;

package/src/judge-role.ts

@@ -1,19 +1,15 @@
 import type { RoleHost, HostContext, HostToolResult, HostGatekeeperActions } from "./host-contracts.ts";
 import type { Static } from "typebox";
-import { reviewSubmissionSchema } from "./review-submission.ts";
-import { GatekeeperDecisionError, ParentQueueReaskError } from "./submission-errors.ts";
+import { REVIEW_QUEUE_STATUSES, reviewSubmissionSchema } from "./review-submission.ts";
+import { GatekeeperDecisionError, ParentQueueReaskError, unreadableDiscriminatorNotice } from "./submission-errors.ts";
 import { projectGatekeeperEscalation } from "./audit-escalation.ts";
 
 import { readableGateItem } from "./readable-gate-item.ts";
 import {
   JUDGE_OUTPUT_TOOL_NAME,
-  validateAcceptedJudgeDetails,
   type JudgeVerdict,
 } from "./package-contracts/judge-output.ts";
 
-const JUDGE_QUEUE_STATUSES = new Set(["converged", "continue", "escalate"]);
-const JUDGE_STATUS_REASK =
-  "status 不是 converged、continue、escalate 三态之一。请重新交卷，status 写明其一。" as const;
 
 export { JUDGE_OUTPUT_TOOL_NAME };
 export type { JudgeVerdict };
@@ -25,8 +21,6 @@ export type { JudgeVerdict };
 // The shared open schema preserves role-specific prose without adding another contract.
 export const judgeVerdictSchema = reviewSubmissionSchema;
 
-type JudgeVerdictParameters = Static<typeof judgeVerdictSchema>;
-
 export type JudgeRoleDependencies = {
   loadSoul(): Promise<string>;
 };
@@ -36,10 +30,6 @@ export type JudgeRoleHostActions = HostGatekeeperActions & {
   bindPriorGatePass(toolCallId: string, receipt: unknown): void;
 };
 
-export function validateVerdict(verdict: JudgeVerdictParameters): JudgeVerdict {
-  return validateAcceptedJudgeDetails(verdict);
-}
-
 
 export function createJudgeRoleRuntime(
   pi: RoleHost,
@@ -58,7 +48,7 @@ export function createJudgeRoleRuntime(
         pi.registerTool({
           name: JUDGE_OUTPUT_TOOL_NAME,
           label: "大理寺输出",
-          description: "提交大理寺终局判词；受理前经符宝郎内闸与审刑院合规审核。",
+          description: "提交大理寺终局判词。",
           promptSnippet: "提交大理寺终局判词",
           parameters: judgeVerdictSchema,
           async execute(toolCallId: string, parameters: Static<typeof judgeVerdictSchema>, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext): Promise<HostToolResult<unknown>> {
@@ -70,19 +60,21 @@ export function createJudgeRoleRuntime(
               && typeof (parameters as Record<string, unknown>).status === "string"
                 ? (parameters as Record<string, unknown>).status as string
                 : undefined;
-            if (rawStatus === undefined || !JUDGE_QUEUE_STATUSES.has(rawStatus)) {
-              throw new ParentQueueReaskError(JUDGE_STATUS_REASK);
+            if (rawStatus === undefined || !REVIEW_QUEUE_STATUSES.has(rawStatus)) {
+              const received = parameters !== null && typeof parameters === "object" && !Array.isArray(parameters)
+                ? (parameters as Record<string, unknown>).status
+                : undefined;
+              throw new ParentQueueReaskError(unreadableDiscriminatorNotice("status", received));
             }
             if (rawStatus === "escalate") {
               // Parent escalate → throw to caller as-is; officers do not attend (#753 / #756).
-              const verdict = validateVerdict(parameters);
               return {
                 content: [],
-                details: verdict,
+                details: parameters,
                 terminate: true as const,
               };
             }
-            const verdict = validateVerdict(parameters);
+            // Queue membership above is the only three-state check. The receipt is not re-judged.
             // Candidate verdict is already on the parent session books as this
             // tool-call leaf (first-record-then-audit; run 019fea05 L61/L62).
             // #753: 符宝郎内闸 — continue returns the raw receipt as a nonterminal tool result.
@@ -101,7 +93,7 @@ export function createJudgeRoleRuntime(
               if (draftPass?.status === "continue") {
                 return {
                   content: [{ type: "text" as const, text: readableGateItem(draftPass.receipt) }],
-                  details: verdict,
+                  details: parameters,
                   terminate: false,
                 };
               }
@@ -121,18 +113,18 @@ export function createJudgeRoleRuntime(
               if (compliancePass?.status === "continue") {
                 return {
                   content: [draftPass, compliancePass].filter((pass) => pass !== undefined).map((pass) => ({ type: "text" as const, text: readableGateItem(pass.receipt) })),
-                  details: verdict,
+                  details: parameters,
                   terminate: false,
                 };
               }
               return {
                 content: [draftPass, compliancePass].filter((pass) => pass !== undefined).map((pass) => ({ type: "text" as const, text: readableGateItem(pass.receipt) })),
-                details: verdict,
+                details: parameters,
                 terminate: true as const,
               };
             } catch (error) {
               if (error instanceof GatekeeperDecisionError && error.result.status === "escalate") {
-                return projectGatekeeperEscalation(error.result, verdict);
+                return projectGatekeeperEscalation(error.result, parameters);
               }
               throw error;
             }

package/src/merger-contracts.ts

@@ -20,7 +20,7 @@ export const mergerInputSchema = Type.Object({
 // #836 (ADR 0003 Amendment): status kept open like countersignStatus
 // (src/countersign-role.ts) — one shared description across both variants
 // so openToolObjectFromUnion's identical-declaration collapse drops none of it.
-const MERGER_STATUS_DESCRIPTION = "completed | escalate — 形状指引，非 schema 闸" as const;
+const MERGER_STATUS_DESCRIPTION = "completed | escalate" as const;
 const mergerOutputVariants = Type.Union([
   Type.Object({ status: Type.Unknown({ description: MERGER_STATUS_DESCRIPTION }), attemptId: Type.String({ description: "已受理合并 attempt 身份" }), report: Type.String({ description: "如实结果报告" }), mergeCommitId: Type.String({ description: "完成合并 commit object ID" }) }, { additionalProperties: false }),
   Type.Object({ status: Type.Unknown({ description: MERGER_STATUS_DESCRIPTION }), attemptId: Type.String({ description: "已受理合并 attempt 身份" }), diagnosis: Type.String({ description: "合并无法或不应由本席完成的原因（含无进行中合并、无活可干、需新的产品/权力决定）" }), report: Type.String({ description: "如实结果报告" }) }, { additionalProperties: false }),

package/src/navigator-attendance.ts

@@ -8,6 +8,7 @@ import { Type, type Static } from "typebox";
 
 import {
   NAVIGATOR_INVOCATION_ENTRY,
+  NAVIGATOR_ROUTE_PLAYBOOK_FAILURE_ENTRY,
   mintNavigatorInvocationId,
 } from "./navigator-invocation-identity.ts";
 import { PACKAGED_ROLE_REGISTRY, type PackagedRole } from "./packaged-role-registry.ts";
@@ -59,11 +60,12 @@ export {
 export { createNativeNavigatorSessionFactory };
 export { resolveNavigatorSeatSelection };
 import { issueRoot, subjectPath } from "./work-subject-identity.ts";
-import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, RECEIPT_DELIVERY_PROMPT } from "./receipt-delivery-policy.ts";
+import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE } from "./receipt-delivery-policy.ts";
 import { navigatorProseFromUnknown } from "./package-contracts/navigator-output.ts";
+import { persistNavigatorWorkBase } from "./navigator-work-base.ts";
 
 export const NAVIGATOR_EVENT_TYPE = "ak-navigator-attendance" as const;
-export const NAVIGATOR_PREPARE_ACCEPTED_TEXT = "游奕使准备已接受";
+export { NAVIGATOR_ROUTE_PLAYBOOK_FAILURE_ENTRY };
 
 /**
  * Role-input document bytes win verbatim over work-root file authority when non-empty.
@@ -131,23 +133,11 @@ export type NavigatorEvent = {
   arrivalMessage?: string;
 };
 
-export type NavigatorSettlementFact = NavigatorSettlement & { invocationId: string; subjectKey: string };
-export type NavigatorContextProjection = {
-  subjectKey: string;
-  subject: string;
-  authority: string;
-  currentRole: { role: string; phase: NavigatorPhase };
-  /** Present on the unique settlement-bound advice prompt. */
-  currentSettlement?: NavigatorSettlement;
-  publicSettlementHistory: NavigatorSettlementFact[];
-  liveRoleHelp: Array<{ role: NavigatorTargetRole; help: string }>;
-};
-
 // #959: prepare is a prose vehicle. Object root only (ADR 0060); nested shape is
 // never a gate — every object root reaches execute exactly once (Rule 0).
 const prepareSchema = Type.Object({
   prose: Type.Optional(Type.Unknown({
-    description: "游奕使散文建议，原样呈现。不要求 candidates/next 结构。非受理闸",
+    description: "游奕使散文建议，原样呈现。不要求 candidates/next 结构。",
   })),
 }, { additionalProperties: true });
 type PrepareOutput = Static<typeof prepareSchema>;
@@ -157,9 +147,6 @@ export type NavigatorAttendanceOptions = {
   role: string;
   phase: NavigatorPhase;
   subjectKey: string;
-  loadSoul: () => Promise<string>;
-  loadRoutePlaybook?: () => Promise<string>;
-  loadRoleHelp: (role: NavigatorTargetRole) => Promise<string>;
   createSession: NavigatorSessionFactory;
   modelSettingPath?: string;
   subject: string;
@@ -170,7 +157,6 @@ export type NavigatorAttendanceOptions = {
   onEvent: (event: NavigatorEvent, report: NavigatorReport) => void | Promise<void>;
 };
 
-const CONTEXT_ENTRY = "ak-navigator-context";
 const INVOCATION_ENTRY = NAVIGATOR_INVOCATION_ENTRY;
 const SETTLEMENT_ENTRY = "ak-navigator-settlement";
 const unavailableKeys = new Set<NavigatorUnavailableKey>(["context", "session", "model", "thinking", "auth", "quota", "transport", "unknown"]);
@@ -263,7 +249,7 @@ export function createNavigatorPrepareTool(onOutput: (value: PrepareOutput) => v
     async execute(_id, value) {
       // Rule 0: the unique prepare submission is accepted once. Shape is never a gate.
       onOutput(value as PrepareOutput);
-      return { content: [{ type: "text" as const, text: NAVIGATOR_PREPARE_ACCEPTED_TEXT }], details: value, terminate: true as const };
+      return { content: [], details: value, terminate: true as const };
     },
   };
 }
@@ -271,7 +257,7 @@ export function createNavigatorPrepareTool(onOutput: (value: PrepareOutput) => v
 export function formatNavigatorReport(report: NavigatorReport): string {
   const playbookFailure = report.routePlaybookReadFailure === undefined
     ? []
-    : [`路书读取失败：${report.routePlaybookReadFailure}`];
+    : [report.routePlaybookReadFailure];
   if (report.disposition === "no-advice") return playbookFailure.join("\n");
   if (report.disposition === "unavailable") {
     return [...playbookFailure, ...(report.unavailableReason ? [report.unavailableReason] : [])].join("\n");
@@ -300,16 +286,13 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
   let settlementTail: Promise<void> = Promise.resolve();
   let settlementFailure: unknown;
   let preparationFailure: unknown;
-  let routePlaybookReadFailure: string | undefined;
+  let observedRoutePlaybookFailure: string | undefined;
   let disposed = false;
   /** In-flight session teardown; repeat dispose returns the same promise (#959 mutation proof). */
   let closing: Promise<void> | undefined;
   // Shared attendance seam owns nested summon cancel (ADR 0018 / #959).
   // Role session factory only forwards HostContext.signal — never its own controller.
   const nestCancel = new AbortController();
-  /** One-shot live-help warm; consumed by the next prepare so later prepares reread live help. */
-  let warmedHelp: Promise<Array<{ role: NavigatorTargetRole; help: string }>> | undefined;
-
   const sessionHostContext = (): HostContext => {
     const parentSignal = options.context.signal;
     const signal = parentSignal === undefined
@@ -318,19 +301,6 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
     return { ...options.context, signal };
   };
 
-  const loadLiveHelp = async (): Promise<Array<{ role: NavigatorTargetRole; help: string }>> => {
-    try {
-      return await Promise.all(
-        NAVIGATOR_TARGETS.map(async ({ role }) => ({
-          role,
-          help: await options.loadRoleHelp(role),
-        })),
-      );
-    } catch (error) {
-      throw navigatorUnavailableError("transport", error);
-    }
-  };
-
   const unavailable = (invocationId: string, reason: unknown): NavigatorReport => {
     const failure = reason instanceof NavigatorUnavailableError
       ? reason
@@ -342,24 +312,13 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
       unavailableCause: failure.unavailableCause,
     };
   };
-  let routePlaybookSettlement: Promise<void> | undefined;
   /**
-   * Settlement fed for the output prompt. Early prepare() runs the host round
-   * from parent start (ready and wait); settleOnce feeds currentSettlement and
-   * lets navigator speak. No candidates/next parse (owner 2026-09-17 #959).
+   * Settlement is the only model round. Standby records attendance and does not prompt.
+   * Soul and route playbook stay on the navigator system prompt, not this user turn.
    */
   let prepareBoundSettlement: NavigatorSettlement | undefined;
-  type MaterialsBundle = {
-    soul: string;
-    routePlaybook: string;
-    helpContext: string;
-    modelSetting: string;
-    model: ReturnType<typeof parseNavigatorModelSetting>;
-    help: Array<{ role: NavigatorTargetRole; help: string }>;
-    activeSession: NavigatorPreparationSession;
-  };
-  /** Materials + session only — no host prompt (cold settle book-before-feed). */
-  const loadMaterialsAndSession = async (invocationId: string): Promise<MaterialsBundle> => {
+  /** Session only — no host prompt (standby attendance, or cold settle book-before-feed). */
+  const loadMaterialsAndSession = async (invocationId: string): Promise<NavigatorPreparationSession> => {
     if (contextError !== undefined) throw navigatorUnavailableError("context", contextError);
     if (typeof authority !== "string" || authority.trim() === "") {
       throw navigatorUnavailableError(
@@ -367,30 +326,6 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
         new Error("controlling authority content was not supplied as typed work context"),
       );
     }
-    let soul: string;
-    let modelSetting: string;
-    let help: Array<{ role: NavigatorTargetRole; help: string }>;
-    let routePlaybook = "";
-    routePlaybookReadFailure = undefined;
-    const soulPromise = (async () => {
-      try {
-        const text = (await options.loadSoul()).trim();
-        if (!text) throw new Error("Navigator soul is empty");
-        return text;
-      } catch (error) {
-        throw navigatorUnavailableError("context", error);
-      }
-    })();
-    const routePlaybookPromise = (async () => {
-      if (options.loadRoutePlaybook === undefined) return "";
-      try {
-        return await options.loadRoutePlaybook();
-      } catch (error) {
-        routePlaybookReadFailure = error instanceof Error ? error.message : String(error);
-        return "";
-      }
-    })();
-    routePlaybookSettlement = routePlaybookPromise.then(() => undefined);
     const modelPromise = (async () => {
       try {
         const resolved = await resolveNavigatorSeatSelection(options.context);
@@ -400,21 +335,13 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
         throw navigatorUnavailableError("model", error);
       }
     })();
-    const helpPromise = warmedHelp ?? loadLiveHelp();
-    warmedHelp = undefined;
-    [soul, routePlaybook, modelSetting, help] = await Promise.all([
-      soulPromise,
-      routePlaybookPromise,
-      modelPromise,
-      helpPromise,
-    ]);
+    const modelSetting = await modelPromise;
     let model: ReturnType<typeof parseNavigatorModelSetting>;
     try {
       model = parseNavigatorModelSetting(modelSetting);
     } catch (error) {
       throw navigatorUnavailableError("model", error);
     }
-    const helpContext = help.map(({ role, help: text }) => `<role_help role="${role}">\n${text}\n</role_help>`).join("\n");
     const tool = createNavigatorPrepareTool((value) => { outputSink?.(value); });
     if (session === undefined) {
       sessionReady = (async () => {
@@ -457,9 +384,9 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
     }
     if (disposed) throw navigatorUnavailableError("session", new Error("Navigator attendance was disposed"));
     if (session === undefined) throw new Error("Navigator session was not created");
-    return { soul, routePlaybook, helpContext, modelSetting, model, help, activeSession: session };
+    return session;
   };
-  const prepare = async (materialsBundle?: MaterialsBundle): Promise<string | undefined> => {
+  const prepare = async (existingSession?: NavigatorPreparationSession): Promise<string | undefined> => {
     // Exact principal is owned by shared lifecycle (or one mint per attendance).
     // Model/tool/advice paths cannot override it; role-session persistence is
     // pi.appendEntry at lifecycle start — not optional sessionManager probing.
@@ -480,53 +407,14 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
       const merged = [prior, next].filter((part) => part.trim() !== "").join("\n\n");
       output = { prose: merged };
     };
-    // Cold settle passes its first-load bundle; early/warm prepare loads here.
-    const { soul, routePlaybook, helpContext, help, activeSession } =
-      materialsBundle ?? await loadMaterialsAndSession(invocationId);
-      const publicSettlementHistory = activeSession.entries()
-        .filter((entry): entry is { type: "custom"; customType: string; data?: unknown } => exactRecord(entry) && entry.type === "custom" && entry.customType === SETTLEMENT_ENTRY && exactRecord(entry.data))
-        .map((entry) => entry.data as NavigatorSettlementFact);
-      // Prior advice is the host session's own history (CLI resume), not a package ledger.
-      const projection: NavigatorContextProjection = {
+    const activeSession = existingSession ?? await loadMaterialsAndSession(invocationId);
+      // Standby records the invocation entry and does not call the model.
+      if (boundSettlement === undefined) return undefined;
+      const request = JSON.stringify({
+        ...boundSettlement,
+        invocationId,
         subjectKey,
-        subject,
-        authority,
-        currentRole: { role: options.role, phase: options.phase },
-        ...(boundSettlement === undefined ? {} : { currentSettlement: boundSettlement }),
-        publicSettlementHistory,
-        liveRoleHelp: help,
-      };
-      activeSession.appendEntry(CONTEXT_ENTRY, projection);
-      // Early (parent start): full host round — ready and wait. Settlement-bound:
-      // feed the result and let navigator speak (owner 2026-09-17 #959).
-      // ADR 0073: phase behavior text lives in resources/navigator-route-playbook.md;
-      // code only binds a neutral phase pointer + typed materials.
-      const request = boundSettlement === undefined
-        ? [
-          "本轮为待命轮。",
-          `<navigator_soul>\n${soul}\n</navigator_soul>`,
-          ...(routePlaybookReadFailure === undefined
-            ? [`<route_playbook>\n${routePlaybook}\n</route_playbook>`]
-            : ["可选路线手册未能读取。"]),
-          `<work_subject>\n${subject}\n</work_subject>`,
-          `<controlling_authority>\n${authority}\n</controlling_authority>`,
-          `<current_role>\n${JSON.stringify({ role: options.role, phase: options.phase })}\n</current_role>`,
-          `<public_settlement_history>\n${JSON.stringify(projection.publicSettlementHistory)}\n</public_settlement_history>`,
-          `<live_role_help>\n${helpContext}\n</live_role_help>`,
-        ].join("\n\n")
-        : [
-          "本轮为结算投喂轮。",
-          `<navigator_soul>\n${soul}\n</navigator_soul>`,
-          ...(routePlaybookReadFailure === undefined
-            ? [`<route_playbook>\n${routePlaybook}\n</route_playbook>`]
-            : ["可选路线手册未能读取。"]),
-          `<work_subject>\n${subject}\n</work_subject>`,
-          `<controlling_authority>\n${authority}\n</controlling_authority>`,
-          `<current_role>\n${JSON.stringify({ role: options.role, phase: options.phase })}\n</current_role>`,
-          `<current_settlement>\n${JSON.stringify(boundSettlement)}\n</current_settlement>`,
-          `<public_settlement_history>\n${JSON.stringify(projection.publicSettlementHistory)}\n</public_settlement_history>`,
-          `<live_role_help>\n${helpContext}\n</live_role_help>`,
-        ].join("\n\n");
+      });
       try {
         try {
           if (disposed) throw navigatorUnavailableError("session", new Error("Navigator attendance was disposed"));
@@ -535,6 +423,7 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
           // (navigator-public-session). No assistant-entry harvest — entries() is
           // archivist custom-only on the wired factory (#959).
           const promptAllowingRejectedPrepare = async (text: string, deliveryRequest: boolean) => {
+            await persistNavigatorWorkBase(activeSession.recordPointer(), { subject, authority });
             const entryStart = activeSession.entries().length;
             prepareBatchRejected = false;
             let promptFailure: unknown;
@@ -572,7 +461,7 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
           // does not 催交 final advice (owner: prepare then wait for settlement feed).
           if (boundSettlement !== undefined) {
             while (output === undefined && prepareBatchRejected && delivery.nextAction() === "request-delivery") {
-              await promptAllowingRejectedPrepare(RECEIPT_DELIVERY_PROMPT, true);
+              await promptAllowingRejectedPrepare(JSON.stringify(delivery.deliveryState()), true);
             }
             if (output === undefined && delivery.nextAction() === "request-delivery") {
               while (delivery.nextAction() === "request-delivery") {
@@ -618,6 +507,10 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
         preparedProse = normalizePrepareProse(output);
         return preparedProse;
       } finally {
+        const playbookFailure = activeSession.routePlaybookReadFailure?.();
+        observedRoutePlaybookFailure = typeof playbookFailure === "string" && playbookFailure.trim() !== ""
+          ? playbookFailure
+          : undefined;
         outputSink = undefined;
       }
   };
@@ -636,17 +529,6 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
       contextError = next.contextError;
       return closing;
     },
-    /**
-     * Start live-help subprocesses during activation without beginning full
-     * preparation. Next prepare() consumes the warm result; a later prepare
-     * reloads so live help edits remain visible.
-     */
-    warmHelp(): void {
-      if (disposed || warmedHelp !== undefined || preparation !== undefined) return;
-      warmedHelp = loadLiveHelp();
-      // Prevent unhandled rejection if attendance is disposed before prepare.
-      void warmedHelp.catch(() => undefined);
-    },
     prepare(): void {
       if (disposed || preparation !== undefined) return;
       preparationFailure = undefined;
@@ -662,9 +544,6 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
     isPreparing(): boolean {
       return preparationInFlight;
     },
-    knownRoutePlaybookReadFailure(): string | undefined {
-      return routePlaybookReadFailure;
-    },
     settle(settlement: NavigatorSettlement): Promise<void> {
       const next = settlementTail.then(() => settleOnce(settlement));
       // Contract: README.md#Navigator-attendance — rejected attendance settlements are drained only to serialize later attendance; retain the exact rejection for the caller/audit path.
@@ -698,10 +577,11 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
   async function settleOnce(settlement: NavigatorSettlement): Promise<void> {
       // Dispose during post-role grace must ignore late completion entirely (#675).
       if (disposed) return;
+      observedRoutePlaybookFailure = undefined;
       const invocationId = activeInvocationId ?? invocationPrincipal;
       let report: NavigatorReport;
-      // Drain in-flight early prepare (parent-start host round: ready and wait).
-      // Then feed settlement for the output prompt on the same host session.
+      // Drain in-flight standby attendance (record only). Then feed the typed
+      // settlement as the only model round on the same host session.
       if (sessionReady !== undefined) {
         try { await sessionReady; } catch (error) { preparationFailure ??= error; }
       }
@@ -740,12 +620,12 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
         // session already exists so the output prompt can run (owner: 准备好了就等着，
         // 结果出来喂给它让它自己输出).
         if (session !== undefined) preparationFailure = undefined;
-        // Cold settle: materials+session only (no unbound host prompt), then book + feed.
-        // Pass the bundle into prepare so loadLiveHelp/setModel/INVOCATION run once.
-        let coldMaterials: MaterialsBundle | undefined;
+        // Cold settle: session only (no unbound host prompt), then book + feed.
+        // Pass the session into prepare so setModel/INVOCATION run once.
+        let coldSession: NavigatorPreparationSession | undefined;
         if (session === undefined && preparationFailure === undefined) {
           try {
-            coldMaterials = await loadMaterialsAndSession(invocationId);
+            coldSession = await loadMaterialsAndSession(invocationId);
           } catch (error) {
             preparationFailure = error;
           }
@@ -753,7 +633,7 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
         session?.appendEntry(SETTLEMENT_ENTRY, settlementFact);
         if (preparationFailure === undefined) {
           prepareBoundSettlement = settlement;
-          preparation = prepare(coldMaterials);
+          preparation = prepare(coldSession);
           void preparation.catch((error) => { preparationFailure = error; });
           try {
             drainedProse = await preparation;
@@ -777,12 +657,8 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
           report = { disposition: "no-advice" };
         }
       }
-      // A primary preparation failure may reject Promise.all before the optional
-      // routebook read finishes. Preserve that primary unavailable cause while
-      // waiting for, and independently attaching, the routebook diagnostic.
-      await routePlaybookSettlement;
-      if (routePlaybookReadFailure !== undefined) {
-        report = { ...report, routePlaybookReadFailure };
+      if (observedRoutePlaybookFailure !== undefined) {
+        report = { ...report, routePlaybookReadFailure: observedRoutePlaybookFailure };
       }
       const event: NavigatorEvent = {
         version: 1,
@@ -813,8 +689,6 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
       sessionReady = undefined;
       preparedProse = undefined;
       preparationFailure = undefined;
-      routePlaybookSettlement = undefined;
-      routePlaybookReadFailure = undefined;
   }
 }
 

package/src/navigator-invocation-identity.ts

@@ -29,6 +29,8 @@ import { isUuidV7, uuidv7 } from "./uuidv7.ts";
 import { workSubjectKeysEqual } from "./work-subject-identity.ts";
 
 export const NAVIGATOR_INVOCATION_ENTRY = "ak-navigator-invocation" as const;
+/** Native playbook read failure recorded by the navigator process that read the file. */
+export const NAVIGATOR_ROUTE_PLAYBOOK_FAILURE_ENTRY = "ak-navigator-route-playbook-failure" as const;
 
 /** Typed durable infrastructure-failure fact on a packaged role output toolResult. */
 export const NAVIGATOR_INFRASTRUCTURE_FAILURE_KIND = "role_infrastructure_failure" as const;

package/src/navigator-public-session.ts

@@ -6,6 +6,7 @@
  * host conversation continuity uses CLI resume (`resumeRunId`), not a package
  * advice ledger (development-closure: do not invent package-level memory).
  */
+import { existsSync } from "node:fs";
 import { basename } from "node:path";
 
 import { sitianReport } from "./sitian-facade.ts";
@@ -23,6 +24,10 @@ import { runDirectoryFromHostContext, type HostContext } from "./host-contracts.
 import type { PublicSummonResult } from "./public-role-summons.ts";
 import { CliUsageError } from "./public-cli/cli-errors.ts";
 import { isNavigatorSeat } from "./packaged-role-registry.ts";
+import {
+  attachWorkContextPointer,
+  navigatorWorkContextFile,
+} from "./navigator-work-base.ts";
 
 /**
  * Ledger process home for navigator attendance: admitted HostContext.runDirectory
@@ -130,6 +135,7 @@ export function createNativeNavigatorSessionFactory(deps?: {
 
     let providerFailure: NavigatorProviderFailureFact | undefined;
     let noReceipt: NoReceiptLifecycleFacts | undefined;
+    let routePlaybookReadFailure: string | undefined;
     let disposed = false;
     /** In-factory host run id for CLI resume; durable pointer also lives on the nest. */
     let hostRunId = readNavigatorHostRunPointer(sessionManager.getEntries() as readonly unknown[]);
@@ -147,18 +153,23 @@ export function createNativeNavigatorSessionFactory(deps?: {
         }
         providerFailure = undefined;
         noReceipt = undefined;
+        routePlaybookReadFailure = undefined;
         try {
           const summonHome = await resolveNavigatorLedgerHome(context);
           // Admission after every await: dispose during preflight must not start summon
           // (ADR 0018 / #959 — legal HostContext may omit signal).
           if (disposed) return;
           const resumeRunId = hostRunId;
+          const workContextPath = navigatorWorkContextFile(sessionManager.getSessionDir());
+          const argvText = existsSync(workContextPath)
+            ? attachWorkContextPointer(text, workContextPath)
+            : text;
 
           // Call contract only: forward shared-lifecycle signal; do not own AbortController here
           // (ADR 0018 / #959 — cancel ownership stays on the attendance/envelope seam).
           const baseSummon = {
             role: "navigator" as const,
-            argv: [text] as const,
+            argv: [argvText] as const,
             cwd: context.cwd,
             ...(summonHome === undefined ? {} : { home: summonHome }),
             ...(context.signal === undefined ? {} : { signal: context.signal }),
@@ -186,6 +197,10 @@ export function createNativeNavigatorSessionFactory(deps?: {
           // Cancel ownership stays on attendance/envelope; this only closes side effects (#959).
           if (disposed) return;
 
+          const playbookFailure = summoned.terminal?.navigator?.advisoryDiagnostic;
+          routePlaybookReadFailure = typeof playbookFailure === "string" && playbookFailure.trim() !== ""
+            ? playbookFailure
+            : undefined;
           const outcome = summoned.terminal?.roleOutcome;
           if (outcome === undefined) {
             const detail = summoned.stderr?.trim() || `exit ${summoned.exitCode}`;
@@ -258,6 +273,7 @@ export function createNativeNavigatorSessionFactory(deps?: {
       },
       providerFailure: () => providerFailure,
       noReceipt: () => noReceipt,
+      routePlaybookReadFailure: () => routePlaybookReadFailure,
       appendEntry: (customType, data) => {
         sessionManager.appendCustomEntry(customType, data);
         try {

package/src/navigator-role.ts

@@ -14,4 +14,8 @@ export const NAVIGATOR_TOOL_SPEC = {
 
 export type NavigatorRuntimeDependencies = {
   loadSoul(): Promise<string>;
+  /** Standing route playbook. Production omits this and reads the package file once. */
+  loadRoutePlaybook?(): Promise<string>;
+  /** Same read's native failure, for the existing routePlaybookReadFailure outlet. */
+  recordRoutePlaybookReadFailure?(message: string | undefined): void;
 };

package/src/navigator-session-contracts.ts

@@ -203,6 +203,8 @@ export type NavigatorPreparationSession = {
    * independent summon rather than press the session that owes the receipt.
    */
   noReceipt?(): NoReceiptLifecycleFacts | undefined;
+  /** Native message from the nested playbook read, when that read failed. */
+  routePlaybookReadFailure?(): string | undefined;
   setModel?(model: string, thinkingLevel?: string): Promise<void>;
   getThinkingLevel?(): string | undefined;
   recordPointer(): string;