@akagilnc/pi-workflow-roles 0.1.5375 → 0.1.5406

package/src/gatekeeper-role.ts

@@ -7,10 +7,8 @@ import type { NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
 import { GatekeeperDecisionError, receivedDiscriminator, unreadableDiscriminatorNotice } from "./submission-errors.ts";
 import { INSPECTOR_OUTPUT_TOOL_NAME } from "./inspector-contracts.ts";
 import { REVIEW_QUEUE_STATUSES, REVIEW_SUBMISSION_OUTPUT_TOOL_NAME } from "./review-submission.ts";
-import {
-  GATEKEEPER_OUTPUT_TOOL_NAME,
-  gatekeeperOutputSchema,
-} from "./package-contracts/gatekeeper-output.ts";
+import { GATEKEEPER_OUTPUT_TOOL_NAME } from "./package-contracts/gatekeeper-output.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 import type { PublicSummonResult } from "./public-role-summons.ts";
 import type { TerminalResult } from "./public-cli/terminal.ts";
 import { runIdFromRunDirectory } from "./run-terminal-artifacts.ts";
@@ -60,8 +58,8 @@ export type GatekeeperResult =
   | {
       /**
        * Accepted reply whose conclusion is not converged|continue|escalate.
-       * Envelope resumes the officer with plain-language re-ask — never parent-stands,
-       * never forges continue (#753 / unreadable-conclusion-resume-speaker).
+       * Envelope reasks the officer in plain language against the configured
+       * ceiling, then keeps this receipt. Never parent-stands, never forges continue.
        */
       readonly status: "needs_reask";
       readonly officer: GateOfficer;
@@ -158,13 +156,7 @@ export type SubmissionGateHostActions = {
  * registration envelope — src/role-runtime.ts (ADR 0018). Schema authority is
  * the shared contract module (with infrastructure-failure declaration).
  */
-export const GATEKEEPER_TOOL_SPEC = {
-  name: GATEKEEPER_OUTPUT_TOOL_NAME,
-  label: "门下省决议",
-  description: "门下省终局决议。status 为 dispatch 或 pass。",
-  promptSnippet: "门下省决议",
-  parameters: gatekeeperOutputSchema,
-} as const;
+export const GATEKEEPER_TOOL_SPEC = roleSubmissionDeclaration("gatekeeper");
 
 export type GatekeeperRuntimeDependencies = {
   loadSoul(): Promise<string>;
@@ -199,9 +191,9 @@ function projectOfficerDecision(
 ): GatekeeperResult {
   const receipt = retainedReceipt(decision);
   const record = isRecord(decision) ? decision : undefined;
-  const status =
-    (record !== undefined && typeof record.status === "string" ? record.status : undefined)
-    ?? fallbackStatus;
+  const status = record !== undefined && Object.hasOwn(record, "status")
+    ? receivedDiscriminator(record, "status")
+    : fallbackStatus;
   const queueStatus = typeof status === "string" ? reviewQueueStatus(status) : undefined;
   if (queueStatus === "converged") {
     return { status: "converged", officer, receipt };

package/src/gleaner-left-contracts.ts

@@ -4,10 +4,36 @@
  * No bounce / verdict channel (言不为狱). 原卷保真 (ADR 0055).
  */
 
+import { Type } from "typebox";
+
+import { openToolObject } from "./open-tool-schema.ts";
+import { withTerminatingOutputDeclarations } from "./package-contracts/terminating-infrastructure.ts";
 import { isRecord } from "./unknown-value.ts";
 
 export const GLEANER_LEFT_OUTPUT_TOOL_NAME = "ak_gleaner_left_output";
 
+// #836 r16 class 1: pointer/statement are LLM/human-read narrative content — no
+// code branches on their presence.
+// #1134: `status` alone is the trajectory field (src/gleaner-left-contracts.ts:38
+// recognizes completed to settle); its word rides the description. findings is
+// narrative content declared name + semantic description only — the array type
+// and the nested pointer/statement object shape are deleted, because the package
+// declaration IS the host's pre-dispatch validator. An empty findings list stays
+// a lawful completion; an omitted one is now expressible too.
+export const gleanerLeftOutputSchema = withTerminatingOutputDeclarations(
+  openToolObject(
+    Type.Object({
+      status: Type.Unknown({
+        description: "completed",
+      }),
+      findings: Type.Unknown({
+        description:
+          "弹章列表；每条可含 pointer（文件/行指针）与 statement（疑点陈述），原样留存。空列表合法完局；机器不判弹章是否成立。",
+      }),
+    }),
+  ),
+);
+
 /** Internal transport: comparison-base revision for the unanchored merge-candidate diff. */
 export const GLEANER_LEFT_BASE_FLAG = {
   name: "ak-gleaner-left-base",
@@ -42,4 +68,3 @@ export function validateRecordedGleanerLeftOutput(value: unknown): GleanerLeftOu
   }
   throw new Error("Gleaner-left output has no execution discriminator");
 }
-

package/src/gleaner-left-role.ts

@@ -1,42 +1,20 @@
 import type { Static } from "typebox";
-import { Type } from "typebox";
 
-import { openToolObject } from "./open-tool-schema.ts";
-import { withTerminatingOutputDeclarations } from "./package-contracts/terminating-infrastructure.ts";
 import {
   GLEANER_LEFT_OUTPUT_TOOL_NAME,
+  gleanerLeftOutputSchema,
   validateRecordedGleanerLeftOutput,
   type GleanerLeftOutput,
 } from "./gleaner-left-contracts.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 
 export {
   GLEANER_LEFT_OUTPUT_TOOL_NAME,
+  gleanerLeftOutputSchema,
 } from "./gleaner-left-contracts.ts";
 export type { GleanerLeftOutput };
 export { validateRecordedGleanerLeftOutput };
 
-// #836 r16 class 1: pointer/statement are LLM/human-read narrative content — no
-// code branches on their presence.
-// #1134: `status` alone is the trajectory field (src/gleaner-left-contracts.ts:38
-// recognizes completed to settle); its word rides the description. findings is
-// narrative content declared name + semantic description only — the array type
-// and the nested pointer/statement object shape are deleted, because the package
-// declaration IS the host's pre-dispatch validator. An empty findings list stays
-// a lawful completion; an omitted one is now expressible too.
-export const gleanerLeftOutputSchema = withTerminatingOutputDeclarations(
-  openToolObject(
-    Type.Object({
-      status: Type.Unknown({
-        description: "completed",
-      }),
-      findings: Type.Unknown({
-        description:
-          "弹章列表；每条可含 pointer（文件/行指针）与 statement（疑点陈述），原样留存。空列表合法完局；机器不判弹章是否成立。",
-      }),
-    }),
-  ),
-);
-
 export type GleanerLeftOutputParameters = Static<typeof gleanerLeftOutputSchema>;
 
 export type GleanerLeftRuntimeDependencies = {
@@ -46,10 +24,4 @@ export type GleanerLeftRuntimeDependencies = {
 /**
  * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
  */
-export const GLEANER_LEFT_TOOL_SPEC = {
-  name: GLEANER_LEFT_OUTPUT_TOOL_NAME,
-  label: "左拾遗输出",
-  description: "左拾遗弹章。",
-  promptSnippet: "左拾遗弹章",
-  parameters: gleanerLeftOutputSchema,
-} as const;
+export const GLEANER_LEFT_TOOL_SPEC = roleSubmissionDeclaration("gleaner-left");

package/src/host-contracts.ts

@@ -198,6 +198,13 @@ export type RoleTurnRequest = {
   readonly host?: string;
   /** Station child role run (#840): omit automatic navigator attendance. */
   readonly stationChild?: boolean;
+  /**
+   * #1132: the effective delivery-request ceiling resolved once by the caller
+   * from the single configured `autoResumeLimit` value and projected here, so
+   * the AK execution seam and the host adapter's own re-ask loop share one
+   * number. Absent = package default. Never re-read from disk downstream.
+   */
+  readonly deliveryRequestLimit?: number;
 };
 
 /** Turn result — only fields upper layers currently consume. */

package/src/inspector-role.ts

@@ -1,5 +1,6 @@
 import type { Static } from "typebox";
 import { reviewSubmissionSchema } from "./review-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 import {
   INSPECTOR_OUTPUT_TOOL_NAME,
   validateRecordedInspectorOutput,
@@ -25,10 +26,4 @@ export type InspectorRuntimeDependencies = {
 /**
  * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
  */
-export const INSPECTOR_TOOL_SPEC = {
-  name: INSPECTOR_OUTPUT_TOOL_NAME,
-  label: "台院输出",
-  description: "台院终局回执，状态为 converged、continue 或 escalate。",
-  promptSnippet: "台院终局回执",
-  parameters: inspectorOutputSchema,
-} as const;
+export const INSPECTOR_TOOL_SPEC = roleSubmissionDeclaration("inspector");

package/src/judge-role.ts

@@ -1,15 +1,13 @@
-import {
-  type RoleHost,
-  type HostContext,
-  type HostToolResult,
-} from "./host-contracts.ts";
-import type { Static } from "typebox";
-import { reviewSubmissionSchema } from "./review-submission.ts";
+import { type RoleHost } from "./host-contracts.ts";
+import { REVIEW_QUEUE_STATUSES, reviewSubmissionSchema, type ReviewQueueWord } from "./review-submission.ts";
+import { registerFiledSubmissionTool } from "./filed-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 import { type GatekeeperSubject } from "./gatekeeper-role.ts";
 import {
   JUDGE_OUTPUT_TOOL_NAME,
   type JudgeVerdict,
 } from "./package-contracts/judge-output.ts";
+import type { TerminalResult } from "./public-cli/terminal.ts";
 
 export { JUDGE_OUTPUT_TOOL_NAME };
 export type { JudgeVerdict };
@@ -29,31 +27,50 @@ export async function runJudgeGates(input: {
     readonly receipt?: unknown;
     readonly runId?: string;
     readonly runDirectory?: string;
+    readonly terminal?: TerminalResult;
   } | void>;
 }): Promise<{
-  readonly status: "converged" | "continue" | "escalate";
+  readonly status: ReviewQueueWord | "needs_reask";
   readonly passes: readonly {
     readonly subject: GatekeeperSubject;
-    readonly status: "converged" | "continue" | "escalate";
+    readonly status: ReviewQueueWord | "needs_reask";
     readonly receipt: unknown;
     readonly runId?: string;
     readonly runDirectory?: string;
+    readonly terminal?: TerminalResult;
   }[];
 }> {
   const passes: {
     subject: GatekeeperSubject;
-    status: "converged" | "continue" | "escalate";
+    status: ReviewQueueWord | "needs_reask";
     receipt: unknown;
     runId?: string;
     runDirectory?: string;
+    terminal?: TerminalResult;
   }[] = [];
   for (const subject of JUDGE_GATES) {
     if (await input.gateAlreadyConverged(subject)) continue;
     const pass = await input.runGate(subject);
-    const status = pass?.status;
-    if (pass === undefined || (status !== "converged" && status !== "continue" && status !== "escalate")) {
+    const received = pass?.status;
+    if (pass === undefined || (
+      typeof received !== "string" || (!REVIEW_QUEUE_STATUSES.has(received) && received !== "needs_reask")
+    )) {
       throw new Error("judge gate returned no conclusion");
     }
+    const status = received as ReviewQueueWord | "needs_reask";
+    if (status === "needs_reask") {
+      return {
+        status,
+        passes: [{
+          subject,
+          status,
+          receipt: pass.receipt,
+          ...(pass.runId === undefined ? {} : { runId: pass.runId }),
+          ...(pass.runDirectory === undefined ? {} : { runDirectory: pass.runDirectory }),
+          ...(pass.terminal === undefined ? {} : { terminal: pass.terminal }),
+        }],
+      };
+    }
     passes.push({
       subject,
       status,
@@ -90,18 +107,8 @@ export function createJudgeRoleRuntime(
       if (soul.length === 0) throw new Error("Judge soul is empty");
       if (!lifecycleRegistered) {
         lifecycleRegistered = true;
-        pi.registerTool({
-          name: JUDGE_OUTPUT_TOOL_NAME,
-          label: "大理寺输出",
-          description: "提交大理寺终局判词；交卷调用结束后，由公开调用接缝按判词状态执行适用审核。",
-          promptSnippet: "提交大理寺终局判词",
-          parameters: judgeVerdictSchema,
-          async execute(toolCallId: string, parameters: Static<typeof judgeVerdictSchema>, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext): Promise<HostToolResult<unknown>> {
-            if (soul === undefined) throw new Error("大理寺职分未装载");
-            // ADR 0003: record the original receipt and end the tool call first.
-            // The public seam reads status and chooses the next route.
-            return { content: [], details: parameters, terminate: true };
-          },
+        registerFiledSubmissionTool(pi, roleSubmissionDeclaration("judge"), {
+          readyError: () => (soul === undefined ? "大理寺职分未装载" : undefined),
         });
         pi.on("before_agent_start", (event) => {
           if (soul === undefined) throw new Error("大理寺职分未装载");

package/src/merger-role.ts

@@ -1,10 +1,11 @@
-import type { RoleHost, HostContext } from "./host-contracts.ts";
+import type { RoleHost } from "./host-contracts.ts";
 import {
   MERGER_OUTPUT_TOOL_NAME,
-  mergerOutputSchema,
   validateMergerInput,
   type MergerInput,
 } from "./merger-contracts.ts";
+import { registerFiledSubmissionTool } from "./filed-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 import { exactUtf8 } from "./exact-utf8.ts";
 
 export { MERGER_OUTPUT_TOOL_NAME };
@@ -35,12 +36,8 @@ export function createMergerRoleRuntime(pi: RoleHost, dependencies: MergerRoleDe
       activation = { soul, input };
       if (!registered) {
         registered = true;
-        pi.registerTool({
-          name: MERGER_OUTPUT_TOOL_NAME, label: "合并输出", description: "提交合并结果；输出分支为 completed 与 escalate。", promptSnippet: "提交合并结果", parameters: mergerOutputSchema,
-          async execute(_id: string, params: unknown, _signal: AbortSignal | undefined, _update: unknown, _ctx: HostContext) {
-            if (!activation) throw new Error("校书郎未激活");
-            return { content: [], details: params, terminate: true as const };
-          },
+        registerFiledSubmissionTool(pi, roleSubmissionDeclaration("merger"), {
+          readyError: () => (activation === undefined ? "校书郎未激活" : undefined),
         });
         pi.on("before_agent_start", (event) => {
           if (!activation) throw new Error("校书郎未激活");

package/src/navigator-attendance.ts

@@ -59,7 +59,10 @@ export {
 export { createNativeNavigatorSessionFactory };
 export { resolveNavigatorSeatSelection };
 import { issueRoot, subjectPath } from "./work-subject-identity.ts";
-import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE } 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";
 
@@ -156,6 +159,8 @@ export type NavigatorAttendanceOptions = {
   contextError?: unknown;
   /** Exact principal owned by shared role lifecycle; attendance never overrides it. */
   invocationId?: string;
+  /** Effective ceiling already resolved for this turn (#1132). */
+  deliveryRequestLimit?: number;
   onEvent: (event: NavigatorEvent, report: NavigatorReport) => void | Promise<void>;
 };
 
@@ -416,11 +421,12 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
       try {
         try {
           if (disposed) throw navigatorUnavailableError("session", new Error("Navigator attendance was disposed"));
-          const delivery = createReceiptDeliveryPolicy();
+          // #1132: the ceiling this turn already resolved. Absent = package default.
+          const delivery = createReceiptDeliveryPolicy(options.deliveryRequestLimit);
           // Production prose arrives only via nested summon → prepare tool.execute
           // (navigator-public-session). No assistant-entry harvest — entries() is
           // archivist custom-only on the wired factory (#959).
-          const promptAllowingRejectedPrepare = async (text: string, deliveryRequest: boolean) => {
+          const promptAllowingRejectedPrepare = async (text: string) => {
             await persistNavigatorWorkBase(activeSession.recordPointer(), { subject, authority });
             const entryStart = activeSession.entries().length;
             prepareBatchRejected = false;
@@ -440,31 +446,30 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
               // ineligible for publication before the correction turn starts.
               output = undefined;
               prepareBatchRejected = true;
+              // The correction prompt below is the one spend for this rejection.
               delivery.recordRejected(rejectedReason);
               return;
             }
             if (promptFailure !== undefined) throw promptFailure;
             const sessionNoReceipt = activeSession.noReceipt?.();
             if (sessionNoReceipt !== undefined) {
-              // This session already settled without an accepted receipt on its own
-              // budget; one more prompt opens an independent summon, not a delivery
-              // request on the settled session (#675).
+              // This session already settled without an accepted receipt. Keep the
+              // larger issued count and stop; a nested zero must not wipe prompts
+              // this layer already sent (#675 / #1132).
               delivery.recordNestedNoReceipt(sessionNoReceipt);
               return;
             }
-            if (deliveryRequest && output === undefined) delivery.recordDeliveryRequest();
           };
-          await promptAllowingRejectedPrepare(request, false);
+          await promptAllowingRejectedPrepare(request);
           // Bound output only: correction after rejected prepare. Early ready-wait
           // does not 催交 final advice (owner: prepare then wait for settlement feed).
           if (boundSettlement !== undefined) {
             while (output === undefined && prepareBatchRejected && delivery.nextAction() === "request-delivery") {
-              await promptAllowingRejectedPrepare(JSON.stringify(delivery.deliveryState()), true);
+              delivery.recordDeliveryRequest();
+              await promptAllowingRejectedPrepare(JSON.stringify(delivery.deliveryState()));
             }
             if (output === undefined && delivery.nextAction() === "request-delivery") {
-              while (delivery.nextAction() === "request-delivery") {
-                delivery.recordDeliveryRequest();
-              }
+              delivery.closeBudget();
             }
             if (output === undefined && delivery.nextAction() === "no-receipt" && activeSession.providerFailure?.() === undefined) {
               const facts = delivery.facts({ runPointer: activeSession.recordPointer(), attemptPointer: invocationId });

package/src/navigator-invocation-identity.ts

@@ -214,6 +214,37 @@ export type PackagedRoleTerminalMessage = {
   readonly details?: unknown;
 };
 
+/**
+ * Durable rejection of a packaged output tool.
+ * Unknown tools and infrastructure failures are not receipt rejections.
+ * Empty text is still a rejection. Undefined means "not this fact".
+ */
+export function packagedRoleOutputRejectionReason(message: {
+  readonly toolName?: unknown;
+  readonly isError?: unknown;
+  readonly details?: unknown;
+  readonly content?: unknown;
+}): string | undefined {
+  if (typeof message.toolName !== "string") return undefined;
+  if (!PACKAGED_ROLE_OUTPUT_TOOLS.has(message.toolName) && message.toolName !== "ak_submission_output") {
+    return undefined;
+  }
+  if (message.isError !== true) return undefined;
+  if (classifyPackagedRoleTerminalResult(message).kind !== "nonterminal") return undefined;
+  const content = message.content;
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+  return content.map((part) => {
+    if (
+      isRecord(part) && part.type === "text"
+      && typeof part.text === "string"
+    ) {
+      return part.text;
+    }
+    return "";
+  }).join("").trim();
+}
+
 /**
  * One shared typed terminal classifier for packaged role output toolResults.
  * Consumed by lifecycle principal completion, publicNavigatorSettlement, and

package/src/navigator-role.ts

@@ -1,16 +1,10 @@
-import { NAVIGATOR_OUTPUT_TOOL_NAME, navigatorOutputSchema } from "./package-contracts/navigator-output.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 
 /**
  * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
  * #959: navigator speaks free-form prose; tool is a lifecycle vehicle only.
  */
-export const NAVIGATOR_TOOL_SPEC = {
-  name: NAVIGATOR_OUTPUT_TOOL_NAME,
-  label: "游奕使建议",
-  description: "游奕使终局回执：散文建议，原样呈现。",
-  promptSnippet: "游奕使建议",
-  parameters: navigatorOutputSchema,
-} as const;
+export const NAVIGATOR_TOOL_SPEC = roleSubmissionDeclaration("navigator");
 
 export type NavigatorRuntimeDependencies = {
   loadSoul(): Promise<string>;

package/src/notary-role.ts

@@ -1,4 +1,6 @@
-import type { RoleHost, HostContext, HostToolResult } from "./host-contracts.ts";
+import type { RoleHost, HostContext } from "./host-contracts.ts";
+import { registerFiledSubmissionTool } from "./filed-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 /**
  * Public Notary role runtime — direct officer seat (not through Gatekeeper province).
  * Caller supplies only a source-run locator; Notary self-fetches authoritative materials.
@@ -10,7 +12,6 @@ import {
   NOTARY_OUTPUT_TOOL_NAME,
   NOTARY_SOURCE_RUN_FLAG,
   NOTARY_TICKET_FLAG,
-  notaryOutputSchema,
   type NotarySourceRunLocator,
 } from "./notary-contracts.ts";
 
@@ -156,24 +157,8 @@ export function createNotaryRoleRuntime(
 
       if (!registered) {
         registered = true;
-        pi.registerTool({
-          name: NOTARY_OUTPUT_TOOL_NAME,
-          label: "符宝郎输出",
-          description: "提交引文保真与票面对齐的 converged/continue/escalate 决议。",
-          promptSnippet: "提交符宝郎决议",
-          parameters: notaryOutputSchema,
-          async execute(toolCallId: string, parameters: unknown, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext, ): Promise<HostToolResult<unknown>> {
-            if (activation === undefined) {
-              throw new Error("符宝郎未激活");
-            }
-            // #753: handler only records — params as submitted, no findings/disposition rewrite.
-            // #541 infra declaration + sole-final barrier are ledger-owned (#575).
-            return {
-              content: [],
-              details: parameters,
-              terminate: true as const,
-            };
-          },
+        registerFiledSubmissionTool(pi, roleSubmissionDeclaration("notary"), {
+          readyError: () => (activation === undefined ? "符宝郎未激活" : undefined),
         });
         // Evidence assembly only (ADR 0018): soul + bound projection.
         // Ticket value is envelope-admitted at activate — not re-read from flags here.

package/src/package-contracts/reviewer-output.ts

@@ -1,7 +1,32 @@
 /** Package-owned Reviewer intent — original role payload only (#836 删 8). */
 
+import { Type } from "typebox";
+
+import { openToolObject } from "../open-tool-schema.ts";
+import { withTerminatingOutputDeclarations } from "./terminating-infrastructure.ts";
+
 export const REVIEWER_OUTPUT_TOOL_NAME = "ak_reviewer_output";
 
+const REVIEWER_AMENDMENTS_DESCRIPTION =
+  "已运行 lens 的 amendments 承载 candidates、逐条处置与 verdict 的完整报告（非仅 verdict 行）；显式单轴时另一轴可省略（completeness / correctness）。hard-stop／usage error 为 refused 时，已产出报告仍照录对应 lens 字段。" as const;
+// #1134: `status` alone is the trajectory field (#917 §6 two normal lens verdicts →
+// completed; hard-stop / usage error → refused); its words ride the description.
+// amendments/diagnostic are LLM/human-read narrative content returned as
+// submitted — declaration keeps name + semantic description only, no nested
+// object shape, no string type, no required constraint.
+const REVIEWER_STATUS_DESCRIPTION =
+  "completed | refused。两种正常 lens verdict（completeness / correctness）均 completed；hard-stop 与 usage error 为 refused（已产出报告仍照录进所选 lens amendments）。" as const;
+const reviewerOutputObject = Type.Object({
+  status: Type.Unknown({ description: REVIEWER_STATUS_DESCRIPTION }),
+  amendments: Type.Unknown({ description: REVIEWER_AMENDMENTS_DESCRIPTION }),
+  diagnostic: Type.Unknown({
+    description: "拒绝诊断说明；hard-stop／usage error 原因进此字段，已产出报告另照录 amendments",
+  }),
+});
+export const reviewerOutputSchema = withTerminatingOutputDeclarations(
+  openToolObject(reviewerOutputObject),
+);
+
 /** Seat-owned per-lens finding body text (completeness / correctness). */
 export type ReviewerAmendments = Readonly<
   Partial<Record<"completeness" | "correctness", string>>

package/src/package-contracts/worker-output.ts

@@ -1,19 +1,39 @@
 /** Package-owned independent Coder and Fixer output leaves. */
 
-export {
+import { Type } from "typebox";
+
+import { openToolObject } from "../open-tool-schema.ts";
+import {
   FIXER_OUTPUT_TOOL_NAME,
   fixerOutputSchema,
+  PARTIALLY_COMPLETED_DEFINITION,
   validateFixerOutput,
+  type FixerBlocker,
+  type FixerClassResult,
+  type FixerOutput,
+  type FixerPhase,
 } from "./fixer-output.ts";
+import { fixerPrerequisiteSchema, fixerPrerequisitesSchema, parseFixerPrerequisites, validateFixerPrerequisites } from "./fixer-packet.ts";
+import type { FixerInvocationInput, FixerPrerequisite } from "./fixer-packet.ts";
+import { withTerminatingOutputDeclarations } from "./terminating-infrastructure.ts";
+
+export {
+  FIXER_OUTPUT_TOOL_NAME,
+  fixerOutputSchema,
+  validateFixerOutput,
+  fixerPrerequisiteSchema,
+  fixerPrerequisitesSchema,
+  parseFixerPrerequisites,
+  validateFixerPrerequisites,
+};
 export type {
   FixerBlocker,
   FixerClassResult,
   FixerOutput,
   FixerPhase,
-} from "./fixer-output.ts";
-export { fixerPrerequisiteSchema, fixerPrerequisitesSchema, parseFixerPrerequisites, validateFixerPrerequisites } from "./fixer-packet.ts";
-export type { FixerInvocationInput, FixerPrerequisite } from "./fixer-packet.ts";
-import { validateFixerOutput, type FixerOutput } from "./fixer-output.ts";
+  FixerInvocationInput,
+  FixerPrerequisite,
+};
 
 export const CODER_OUTPUT_TOOL_NAME = "ak_coder_output";
 export type WorkerRoleLabel = "Coder" | "Fixer";
@@ -31,3 +51,21 @@ export function validateAcceptedCoderDetails(output: unknown): CoderOutput {
 export function validateAcceptedWorkerDetails(output: unknown, roleLabel: WorkerRoleLabel = "Coder"): WorkerOutput {
   return roleLabel === "Fixer" ? validateFixerOutput(output) : validateAcceptedCoderDetails(output);
 }
+
+// status 的合法词写在 description。WORKER_DONE_STATUSES 只让 completed /
+// partially_completed 进入提交闸。unfinished 且未见理由说明时，运行时同 run 催全
+// （ADR 0050）；理由在不在不按 JSON 类型判，也不在派发前用长度拒收。
+// report / remainingScope / reason 的声明只留字段名和语义。
+const CODER_STATUS_DESCRIPTION =
+  `planned | completed | refused | partially_completed | unfinished。unfinished：缺前置或违宪约束致本局未完成。${PARTIALLY_COMPLETED_DEFINITION}` as const;
+const coderOutputObject = Type.Object({
+  status: Type.Unknown({ description: CODER_STATUS_DESCRIPTION }),
+  report: Type.Unknown({ description: "如实结果报告" }),
+  remainingScope: Type.Unknown({ description: "本局后剩余工作" }),
+  reason: Type.Unknown({
+    description: "阻断原因：缺前置或违宪约束。缺待决 owner 决定或答复属缺前置。",
+  }),
+});
+export const coderOutputSchema = withTerminatingOutputDeclarations(
+  openToolObject(coderOutputObject),
+);

package/src/pi/adapter.ts

@@ -18,6 +18,12 @@ import type {
 import { createOAuthKeepalive, type OAuthKeepaliveOptions } from "../oauth-keepalive.ts";
 import { createRoleRuntimeExtension, type RoleRuntimeDependencies } from "../role-runtime.ts";
 import { renderAgentStartMaterials } from "../agent-start-materials.ts";
+import { projectCorrectableExecuteRejection } from "../submission-correctable-error.ts";
+import {
+  WorkerCommitReminderError,
+  WorkerPrefixReminderError,
+  WorkerUnfinishedReasonReminderError,
+} from "../submission-errors.ts";
 import { readUserDialogueStdin } from "../user-dialogue-stdin.ts";
 
 export type PiRoleHostAdapter = RoleEnvelopeHost;
@@ -106,14 +112,33 @@ function toPiToolDefinition<S extends TSchema, D>(
     description: tool.description,
     ...(tool.promptSnippet === undefined ? {} : { promptSnippet: tool.promptSnippet }),
     parameters: tool.parameters,
-    execute: async (toolCallId, params, signal, update, context) =>
-      toPiResult(await tool.execute(
-        toolCallId,
-        params as Static<S>,
-        signal,
-        update === undefined ? undefined : (result) => update(toPiResult(result)),
-        projectContext(context),
-      )),
+    execute: async (toolCallId, params, signal, update, context) => {
+      try {
+        return toPiResult(await tool.execute(
+          toolCallId,
+          params as Static<S>,
+          signal,
+          update === undefined ? undefined : (result) => update(toPiResult(result)),
+          projectContext(context),
+        ));
+      } catch (error) {
+        // The worker gate owns these one-shot reminders. Returning them as
+        // isError keeps the code on the tool result so催交 can record the
+        // fact without spending the reminder itself. Other correctable
+        // errors stay native throws.
+        if (!(
+          error instanceof WorkerUnfinishedReasonReminderError
+          || error instanceof WorkerCommitReminderError
+          || error instanceof WorkerPrefixReminderError
+        )) throw error;
+        const projected = projectCorrectableExecuteRejection(error);
+        return {
+          content: [{ type: "text" as const, text: projected.diagnostic }],
+          details: projected.details as D,
+          isError: true as const,
+        };
+      }
+    },
   };
 }