@akagilnc/pi-workflow-roles 0.1.5068 → 0.1.5096

package/src/role-runtime.ts

@@ -23,6 +23,7 @@ import {
   durableSessionPointer,
   resolveBookKeyFromGit,
 } from "./activation-ledger.ts";
+import { readPackageMaterial } from "./session-opening-materials.ts";
 import { writeStderrJsonlRecord } from "./stderr-jsonl.ts";
 import {
   createToolExecutionObservationFace,
@@ -38,7 +39,7 @@ import {
 } from "./engine-detour.ts";
 import { engineSessionMaterialFromOptions } from "./package-resources/engine-material.ts";
 import { registerEngineDetourTool } from "./engine-detour-tool.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 type { CollectorClock } from "./collector-evidence.ts";
 import type { CollectorGitHubTransport } from "./collector-github.ts";
 import {
@@ -98,7 +99,8 @@ import {
   type AuditorRuntimeDependencies,
 } from "./auditor-role.ts";
 
-import { formatNavigatorReport, NAVIGATOR_EVENT_TYPE, navigatorSubjectKey, navigatorUnavailableError, subjectPath, type NavigatorAttendance, type NavigatorAttendanceOptions, type NavigatorEvent, type NavigatorPhase, type NavigatorReport, type NavigatorSettlement, type NavigatorSubjectProvenance, type NavigatorTargetRole, type NavigatorWorkContext } from "./navigator-attendance.ts";
+import { formatNavigatorReport, NAVIGATOR_EVENT_TYPE, NAVIGATOR_ROUTE_PLAYBOOK_FAILURE_ENTRY, navigatorSubjectKey, navigatorUnavailableError, subjectPath, type NavigatorAttendance, type NavigatorAttendanceOptions, type NavigatorEvent, type NavigatorPhase, type NavigatorReport, type NavigatorSettlement, type NavigatorSubjectProvenance, type NavigatorWorkContext } from "./navigator-attendance.ts";
+import { loadNavigatorWorkBaseSuffix } from "./navigator-work-base.ts";
 import {
   buildNavigatorInfrastructureFailureFact,
   classifyPackagedRoleTerminalResult,
@@ -108,7 +110,7 @@ import {
 } from "./navigator-invocation-identity.ts";
 import { recordTypedProviderHttpStatus } from "./typed-provider-http.ts";
 import { NAVIGATOR_POST_ROLE_GRACE_MS, raceNavigatorGrace } from "./public-cli/settlement.ts";
-import { PACKAGED_ROLE_REGISTRY, isOfficerReviewSeat, packagedRoleActivationFlags, packagedRoleInputFlag, packagedRoleMetadata, packagedRoleOutputTool, packagedRolePhaseFlag, type PackagedRole } from "./packaged-role-registry.ts";
+import { PACKAGED_ROLE_REGISTRY, isOfficerReviewSeat, packagedRoleActivationFlags, packagedRoleMetadata, packagedRoleOutputTool, packagedRolePhaseFlag, type PackagedRole } from "./packaged-role-registry.ts";
 import { isAuditEscalationProjection } from "./audit-escalation.ts";
 import {
   createJudgeRoleRuntime,
@@ -301,7 +303,6 @@ import {
   NOTARY_OUTPUT_TOOL,
   INSPECTOR_OUTPUT_TOOL,
   GatekeeperDecisionError,
-  createGatekeeperOutputTool,
   runGatekeeper,
   gateOfficerForSubject,
 } from "./gatekeeper-role.ts";
@@ -309,12 +310,12 @@ export {
   NOTARY_OUTPUT_TOOL,
   INSPECTOR_OUTPUT_TOOL,
   GatekeeperDecisionError,
-  createGatekeeperOutputTool,
   runGatekeeper,
   gateOfficerForSubject,
 };
 export type { GatekeeperResult, GatekeeperSubject, SubmissionGateNonPassResult, GateOfficer, RunGatekeeperOptions } from "./gatekeeper-role.ts";
-import { ParentQueueReaskError } from "./submission-errors.ts";
+import { ParentQueueReaskError, unreadableDiscriminatorNotice } from "./submission-errors.ts";
+import { REVIEW_QUEUE_STATUSES } from "./review-submission.ts";
 
 export {
   DOCTOR_EVIDENCE_TOOL_NAME,
@@ -451,29 +452,7 @@ export const ROLE_FLAG = {
   },
 } as const;
 
-/** Host-neutral in-process role help for Navigator prepare (Pi and Grok share this). */
-export function formatNavigatorRoleHelp(role: NavigatorTargetRole): string {
-  const metadata = packagedRoleMetadata(role);
-  const lines = [
-    `Usage: ak-role ${role}`,
-    ROLE_FLAG.definition.description,
-  ];
-  const inputFlag = packagedRoleInputFlag(role);
-  if (inputFlag !== undefined) {
-    lines.push(`  --${inputFlag} <value>    ${role} input material`);
-  }
-  const phaseFlag = packagedRolePhaseFlag(role);
-  if (phaseFlag !== undefined && metadata !== undefined) {
-    lines.push(
-      `  --${phaseFlag} <value>    ${role} phase: ${(metadata.phases.filter((p) => p !== null) as string[]).join(" | ")}`,
-    );
-  }
-  lines.push(`Public next-command form: ak-role ${role}`);
-  return lines.join("\n");
-}
-
-type NavigatorAttendanceDependency = Omit<NavigatorAttendance, "knownRoutePlaybookReadFailure"> &
-  Partial<Pick<NavigatorAttendance, "knownRoutePlaybookReadFailure">>;
+type NavigatorAttendanceDependency = NavigatorAttendance;
 
 export type RoleRuntimeDependencies = {
   /** Package root for packaged engine-note resolution (#879). */
@@ -753,7 +732,7 @@ export function createNavigatorRoleRuntime(
   roleHost: RoleHost,
   dependencies: NavigatorRuntimeDependencies,
 ) {
-  return createFiledOfficerRuntime(
+  const base = createFiledOfficerRuntime(
     roleHost,
     {
       role: "navigator",
@@ -762,6 +741,43 @@ export function createNavigatorRoleRuntime(
     },
     dependencies,
   );
+  let playbookBound = false;
+  return {
+    async activate() {
+      await base.activate();
+      if (playbookBound) return;
+      playbookBound = true;
+      // Standing system prompt, not a per-turn user message. Native read failure
+      // is the explanation (ADR 0061); no code-written sentence.
+      const loadRoutePlaybook = dependencies.loadRoutePlaybook
+        ?? (() => readPackageMaterial("resources/navigator-route-playbook.md"));
+      let playbookRead: Promise<string> | undefined;
+      roleHost.on("before_agent_start", async (event) => {
+        const basePrompt = typeof event.systemPrompt === "string" ? event.systemPrompt : "";
+        const parts: string[] = [];
+        try {
+          playbookRead ??= loadRoutePlaybook();
+          const content = await playbookRead;
+          dependencies.recordRoutePlaybookReadFailure?.(undefined);
+          if (content.trim() !== "") parts.push(content);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          if (message.trim() !== "") {
+            dependencies.recordRoutePlaybookReadFailure?.(message);
+            parts.push(message);
+          }
+        }
+        const prompt = typeof event.prompt === "string" ? event.prompt : "";
+        const work = await loadNavigatorWorkBaseSuffix(prompt);
+        if (work !== undefined && work.trim() !== "") parts.push(work);
+        if (parts.length === 0) return;
+        const text = parts.join("\n\n");
+        return {
+          systemPrompt: basePrompt.trim() === "" ? text : `${basePrompt}\n\n${text}`,
+        };
+      });
+    },
+  };
 }
 
 /** #675: public 审刑院 seat on the shared filed-officer envelope. */
@@ -872,8 +888,6 @@ function readDiaristRunCoordinates(ctx: HostContext): {
 const DIARIST_BOUNDS_REASK =
   "边界无法使用。请重交 sessions：每卷 path + ranges，每端以原生 id 或本轮行号二选一指名。" as const;
 const DIARIST_ROUTING_STATUSES = new Set(["completed", "escalate"]);
-const DIARIST_STATUS_REASK =
-  "status 不是 completed、escalate 之一。请重新交卷，status 写明其一。" as const;
 
 /**
  * #708 / #779 / #901: 起居郎 public seat on the shared filed-officer envelope.
@@ -900,7 +914,7 @@ export function createDiaristRoleRuntime(
         // before interpreting any other submitted field; caller-owned data stays open.
         const status = submitted?.status;
         if (typeof status !== "string" || !DIARIST_ROUTING_STATUSES.has(status)) {
-          throw new ParentQueueReaskError(DIARIST_STATUS_REASK);
+          throw new ParentQueueReaskError(unreadableDiscriminatorNotice("status", submitted?.status));
         }
         if (status === "escalate") return parameters;
         const assertion = readDiaristTicketAssertion(submitted);
@@ -943,26 +957,9 @@ export function createDiaristRoleRuntime(
   );
 }
 
-/** Shared review-submission status words the queue reads (#1028). */
-const COUNTERSIGN_QUEUE_STATUSES = new Set(["converged", "continue", "escalate"]);
-
-/**
- * Plain-language re-ask when status is not a known queue word.
- * Back to countersign itself — notary is not summoned (#753).
- */
-const COUNTERSIGN_STATUS_REASK =
-  "status 不是 converged、continue、escalate 三态之一。请重新交卷，status 写明其一。" as const;
-
-/** Secretariat status words the submission gate reads. */
+/** Secretariat status words the submission gate reads. Not the review three-state field. */
 const SECRETARIAT_QUEUE_STATUSES = new Set(["converged", "escalate"]);
 
-/**
- * Plain-language re-ask when secretariatStatus is not a known queue word.
- * Back to secretariat itself — 给事中 is not summoned for escalation.
- */
-const SECRETARIAT_STATUS_REASK =
-  "secretariatStatus 不是 converged、escalate 之一。请重新交卷，status 写明其一。" as const;
-
 /**
  * Secretariat output is terminal; converged submissions enter the shared
  * submission gate on every host that mounts gatekeeper actions.
@@ -989,7 +986,9 @@ export function createSecretariatRoleRuntime(
               ? record.secretariatStatus
               : undefined;
           if (status === undefined || !SECRETARIAT_QUEUE_STATUSES.has(status)) {
-            throw new ParentQueueReaskError(SECRETARIAT_STATUS_REASK);
+            throw new ParentQueueReaskError(
+              unreadableDiscriminatorNotice("secretariatStatus", record?.secretariatStatus),
+            );
           }
           if (status === "escalate") {
             // Parent escalate → throw to caller as-is; countersign does not attend.
@@ -1132,10 +1131,10 @@ export function createCountersignRoleRuntime(
             record !== undefined && typeof record.status === "string"
               ? record.status
               : undefined;
-          if (status === undefined || !COUNTERSIGN_QUEUE_STATUSES.has(status)) {
+          if (status === undefined || !REVIEW_QUEUE_STATUSES.has(status)) {
             // Parent status unreadable → back to countersign itself; do not summon notary,
             // do not forge an officer bounce face (#753).
-            throw new ParentQueueReaskError(COUNTERSIGN_STATUS_REASK);
+            throw new ParentQueueReaskError(unreadableDiscriminatorNotice("status", record?.status));
           }
           if (status === "escalate") {
             // Parent escalate → throw to caller as-is; notary does not attend (#753).
@@ -1327,13 +1326,11 @@ export function createRoleRuntimeExtension(
         const raced = await raceNavigatorGrace(settlePromise, NAVIGATOR_POST_ROLE_GRACE_MS);
         if (raced.status !== "timeout") return;
         if (pendingNavigatorPresentation === undefined) {
-          const routePlaybookReadFailure = attendance.knownRoutePlaybookReadFailure?.();
           const report: NavigatorReport = {
             disposition: "unavailable",
             unavailableReason: "Navigator exceeded post-role delivery grace",
             unavailableSource: "unknown",
             unavailableCause: "unknown",
-            ...(routePlaybookReadFailure === undefined ? {} : { routePlaybookReadFailure }),
           };
           const event: NavigatorEvent = {
             version: 1,
@@ -1345,7 +1342,6 @@ export function createRoleRuntimeExtension(
             unavailableReason: "Navigator exceeded post-role delivery grace",
             unavailableSource: "unknown",
             unavailableCause: "unknown",
-            ...(routePlaybookReadFailure === undefined ? {} : { routePlaybookReadFailure }),
           };
           pendingNavigatorPresentation = { event, report };
         }
@@ -1616,7 +1612,7 @@ export function createRoleRuntimeExtension(
         } catch {}
         envelopeHost.sendMessage({
           customType: "ak-receipt-delivery-prompt",
-          content: RECEIPT_DELIVERY_PROMPT,
+          content: JSON.stringify(receiptDelivery.deliveryState()),
           display: false,
         }, { triggerTurn: true, deliverAs: "followUp" });
       } else if (receiptDelivery.nextAction() === "no-receipt" && !noReceiptRecorded) {
@@ -1789,6 +1785,11 @@ export function createRoleRuntimeExtension(
     });
     const navigator = createNavigatorRoleRuntime(roleHost, {
       loadSoul: () => requireRoleSoul("navigator"),
+      recordRoutePlaybookReadFailure: (message) => {
+        envelopeHost.appendEntry(NAVIGATOR_ROUTE_PLAYBOOK_FAILURE_ENTRY, {
+          message: message ?? "",
+        });
+      },
     });
     const auditor = createAuditorRoleRuntime(roleHost, {
       loadSoul: () => requireRoleSoul("auditor"),
@@ -2175,11 +2176,8 @@ export function createRoleRuntimeExtension(
               pendingNavigatorPresentation = { event: navigatorEvent, report };
             },
           });
-          // Warm live help during activation so prepare is not help-bound under load.
-          // Concrete work context also starts full preparation so session create
-          // overlaps the role run. Placeholder subjects wait for before_agent_start
-          // (user prompt may replace the subject key) but still inherit warm help.
-          navigatorAttendance.warmHelp?.();
+          // Concrete work context starts standby attendance (record only, no model).
+          // Placeholder subjects wait for before_agent_start (user prompt may replace the subject key).
           if (
             navigatorWorkContext.contextError === undefined &&
             navigatorWorkContext.subjectProvenance !== "placeholder"

package/src/secretariat-role.ts

@@ -12,12 +12,12 @@ import { SECRETARIAT_OUTPUT_TOOL_NAME, type SecretariatVerdict } from "./secreta
 export { SECRETARIAT_OUTPUT_TOOL_NAME } from "./secretariat-contracts.ts";
 export type { SecretariatVerdict };
 
-/** 中书省终局回执形状；形状指引，非 schema 闸。 */
+/** 中书省终局回执形状。 */
 export const secretariatVerdictSchema = withTerminatingOutputDeclarations(
   Type.Object(
     {
       secretariatStatus: Type.Unknown({
-        description: "converged | escalate（终局形状指引，非闸）",
+        description: "converged | escalate",
       }),
       ticketNumber: Type.Optional(
         Type.Number({ description: "本票号；署时指向最终正文所在票" }),
@@ -44,7 +44,7 @@ export type SecretariatVerdictParameters = Static<typeof secretariatVerdictSchem
 export const SECRETARIAT_OUTPUT_TOOL_SPEC = {
   name: SECRETARIAT_OUTPUT_TOOL_NAME,
   label: "中书省输出",
-  description: "中书省终局回执（署或上呈）；给事中封驳须改票重送，不在此终局。",
+  description: "中书省终局回执。",
   promptSnippet: "中书省终局回执",
   parameters: secretariatVerdictSchema,
 } as const;

package/src/submission-errors.ts

@@ -58,6 +58,22 @@ export class WorkerUnfinishedReasonReminderError extends Error {
   }
 }
 
+/**
+ * Host constraint missed a routing discriminator (#1055).
+ * Names live only in the submission schema. This notice carries the field and the received value.
+ */
+export function unreadableDiscriminatorNotice(field: string, received: unknown): string {
+  if (received === undefined) return `读不出 ${field}`;
+  return `读不出 ${field}：${readableGateItem(received)}`;
+}
+
+/** The received discriminator only — never the rest of the receipt. */
+export function receivedDiscriminator(receipt: unknown, field: string): unknown {
+  if (receipt === null || typeof receipt !== "object" || Array.isArray(receipt)) return undefined;
+  if (!Object.hasOwn(receipt, field)) return undefined;
+  return (receipt as Record<string, unknown>)[field];
+}
+
 /**
  * Parent seat status unreadable for queueing (#753).
  * Correctable back to the parent itself — not a gate officer bounce, no officer field.

package/src/submission-gate.ts

@@ -27,6 +27,7 @@ import {
   type GateOfficerSummon,
 } from "./gatekeeper-role.ts";
 import type { PublicSummonResult } from "./public-role-summons.ts";
+
 import { sessionFileFromPublicSummon } from "./session-assistant-usage.ts";
 
 /**
@@ -178,7 +179,7 @@ export async function requireSubmissionGate(options: {
       };
     }
     if (gatekeeper.status === "needs_reask") {
-      reask = officerConclusionReask(projected.officer);
+      reask = officerConclusionReask(gatekeeper.receivedStatus);
       continue;
     }
     if (gatekeeper.status === "transport_failure") {

package/src/submission-ledger.ts

@@ -20,7 +20,8 @@ import type { SitianRecord } from "./sitian-contracts.ts";
 import { findRunDirectoryById } from "./public-cli/run-lifecycle.ts";
 import type { TerminalRoleName } from "./public-cli/terminal.ts";
 import { isCorrectableExecuteError } from "./submission-correctable-error.ts";
-import { failOnInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.ts";
+import { failOnInfrastructureFailureDeclaration, infrastructureFailureDiagnostic } from "./package-contracts/terminating-infrastructure.ts";
+import { REVIEW_SUBMISSION_OUTPUT_TOOL_NAME } from "./review-submission.ts";
 
 export type SubmissionCall = { readonly id: string; readonly name: string };
 export type SubmissionOutcomeKind = "correctable-rejection" | "audit-escalation" | "infrastructure";
@@ -678,17 +679,28 @@ export function createSubmissionLedgerHost(
           });
           let result: HostToolResult<unknown>;
           try {
-            failOnInfrastructureFailureDeclaration(
-              params,
-              {
-                failInfrastructure(error, ctx) {
-                  failInfrastructure(error, ctx);
+            // A review escalate that carries the failure declaration is the
+            // seat's own submission. Every other declaration stays on the
+            // host-failure seam. Tool identity comes from the registry map.
+            const reviewEscalate = tool.name === REVIEW_SUBMISSION_OUTPUT_TOOL_NAME
+              && infrastructureFailureDiagnostic(params) !== undefined
+              && params !== null
+              && typeof params === "object"
+              && !Array.isArray(params)
+              && (params as Record<string, unknown>).status === "escalate";
+            if (!reviewEscalate) {
+              failOnInfrastructureFailureDeclaration(
+                params,
+                {
+                  failInfrastructure(error, ctx) {
+                    failInfrastructure(error, ctx);
+                  },
                 },
-              },
-              context,
-              toolCallId,
-              tool.bounceInfrastructureDeclaration,
-            );
+                context,
+                toolCallId,
+                tool.bounceInfrastructureDeclaration,
+              );
+            }
             result = await tool.execute(toolCallId, params, signal, update, context);
           } catch (error) {
             if (isCorrectableExecuteError(error)) {

package/src/worker-role.ts

@@ -5,7 +5,7 @@ import { withTerminatingOutputDeclarations } from "./package-contracts/terminati
 
 import { readableGateItem } from "./readable-gate-item.ts";
 import { projectGatekeeperEscalation } from "./audit-escalation.ts";
-import { GatekeeperDecisionError, ParentQueueReaskError } from "./submission-errors.ts";
+import { GatekeeperDecisionError, ParentQueueReaskError, unreadableDiscriminatorNotice } from "./submission-errors.ts";
 import {
   CODER_OUTPUT_TOOL_NAME,
   FIXER_OUTPUT_TOOL_NAME,
@@ -44,11 +44,11 @@ export type { WorkerOutput };
 // no code branches on their length. `reason` alone keeps minLength: the worker
 // gate reads `reason.trim().length > 0` to pick typed-reminder-bounce vs accept
 // (src/worker-submission-gates.ts:159-163,297-302).
-// #836 (ADR 0003 Amendment): status kept open like countersignStatus
-// (src/countersign-role.ts) — one shared description across every variant
+// Worker status is not the review three-state field (#1055): schema stays open.
+// One shared description across every variant
 // so openToolObjectFromUnion's identical-declaration collapse drops none of it.
 const CODER_STATUS_DESCRIPTION =
-  "planned | completed | refused | partially_completed | unfinished — 形状指引，非 schema 闸；completed 回执含 TDD、同模式、引入回归、行为事实四项证据；unfinished 缺前置或违宪约束致本局未完成时可用，缺待决 owner 决定或答复属缺前置。" as const;
+  "planned | completed | refused | partially_completed | unfinished。unfinished：缺前置或违宪约束致本局未完成。" as const;
 const coderOutputVariants = Type.Union([
   Type.Object({
     status: Type.Unknown({ description: CODER_STATUS_DESCRIPTION }),
@@ -135,8 +135,6 @@ const WORKER_ROUTING_STATUSES = new Set([
   "partially_completed",
   "unfinished",
 ]);
-const WORKER_STATUS_REASK =
-  "status 不是 planned、completed、refused、partially_completed、unfinished 之一。请重新交卷，status 写明其一。" as const;
 
 /** Read only the field that selects the worker's next package-owned path. */
 function workerStatusOf(output: WorkerOutput): string | undefined {
@@ -148,7 +146,7 @@ function workerStatusOf(output: WorkerOutput): string | undefined {
 function requireReadableWorkerStatus(output: WorkerOutput): string {
   const status = workerStatusOf(output);
   if (status === undefined || !WORKER_ROUTING_STATUSES.has(status)) {
-    throw new ParentQueueReaskError(WORKER_STATUS_REASK);
+    throw new ParentQueueReaskError(unreadableDiscriminatorNotice("status", isRecord(output) ? output.status : undefined));
   }
   return status;
 }
@@ -256,7 +254,7 @@ export function createFixerRoleRuntime(
         pi.registerTool({
           name: FIXER_OUTPUT_TOOL_NAME,
           label: "修内司输出",
-          description: "提交修内司终局回执；基础设施失败走 abort，不经本工具。",
+          description: "提交修内司终局回执。",
           promptSnippet: "提交修内司终局回执",
           parameters: fixerOutputSchema,
           async execute(toolCallId: string, parameters: unknown, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext): Promise<HostToolResult<unknown>> {
@@ -383,7 +381,7 @@ export function createCoderRoleRuntime(
         pi.registerTool({
           name: CODER_OUTPUT_TOOL_NAME,
           label: "将作监输出",
-          description: "提交将作监终局回执；本工具无 escalate 通道。",
+          description: "提交将作监终局回执。",
           promptSnippet: "提交将作监终局回执",
           parameters: coderOutputSchema,
           async execute(toolCallId: string, parameters: unknown, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext): Promise<HostToolResult<unknown>> {