@akagilnc/pi-workflow-roles 0.1.5375 → 0.1.5406

package/src/submission-gate.ts

@@ -8,7 +8,8 @@
  *   converged → continue remaining review and settle
  *   continue → raw officer receipt; caller resumes the submitted seat for revision
  *   escalate → return the officer run so the caller can resume that officer directly
- *   unrecognized status → resume officer with plain-language re-ask (no round cap)
+ *   unrecognized status → resume officer with plain-language re-ask, counted
+ *     against the configured ceiling; exhaustion keeps that receipt
  *   transport / no_receipt → present honestly
  * Four pairs: countersign↔notary, judge↔auditor, worker↔inspector, secretariat↔countersign (#969).
  * Code does not judge content, map next-step for parent, or label unreadable/unusable.
@@ -28,21 +29,21 @@ import {
 } from "./gatekeeper-role.ts";
 import type { PublicSummonResult } from "./public-role-summons.ts";
 import type { TerminalResult } from "./public-cli/terminal.ts";
+import { receivedDiscriminator } from "./submission-errors.ts";
+import type { ReviewQueueWord } from "./review-submission.ts";
+import { deliveryLimitFromConfig } from "./receipt-delivery-policy.ts";
 
-/** Queue word of the latest this-terminal payload. History does not outrank it. */
-export function latestQueueStatus(terminal: TerminalResult | undefined): string | undefined {
+/** Received discriminator of the latest payload, retained verbatim for re-ask. */
+export function latestQueueStatus(terminal: TerminalResult | undefined): unknown {
   const outcome = terminal?.roleOutcome;
   if (outcome === undefined) return undefined;
   if (outcome.kind === "audit_escalation") return "escalate";
   if (outcome.kind !== "accepted") return undefined;
   const latest = outcome.payloads?.[outcome.payloads.length - 1];
-  if (isRecord(latest)) {
-    const status = (latest as { status?: unknown }).status;
-    if (typeof status === "string" && status.trim() !== "") return status;
+  if (isRecord(latest) && Object.hasOwn(latest, "status")) {
+    return receivedDiscriminator(latest, "status");
   }
-  return typeof outcome.status === "string" && outcome.status.trim() !== ""
-    ? outcome.status
-    : undefined;
+  return outcome.status;
 }
 
 export function latestQueuePayload(terminal: TerminalResult | undefined): unknown {
@@ -98,6 +99,7 @@ function bookDirectOfficerPointer(
   officer: GateOfficer,
   result: GatekeeperResult,
   summoned: PublicSummonResult,
+  toolCallId: string,
 ): void {
   if (
     result.status !== "converged"
@@ -122,6 +124,7 @@ function bookDirectOfficerPointer(
     ...(typeof summoned.runDirectory === "string" && summoned.runDirectory.trim() !== ""
       ? { runDirectory: summoned.runDirectory }
       : {}),
+    ...(toolCallId.trim() === "" ? {} : { submissionToolCallId: toolCallId }),
   });
 }
 
@@ -131,16 +134,20 @@ function bookDirectOfficerPointer(
  * public terminal without a second authority.
  */
 export type SubmissionGateOutcome = {
-  readonly status: "converged" | "continue" | "escalate";
+  readonly status: ReviewQueueWord | "needs_reask";
   readonly officer: GateOfficer;
   readonly receipt: unknown;
   readonly runId?: string;
   readonly runDirectory?: string;
+  /** Officer terminal already returned by the summon. Present when the reply was not a queue word. */
+  readonly terminal?: TerminalResult;
 };
 
 /**
  * Shared envelope: project gate, book officer pointer, map onto host actions.
- * Review loop has no round cap (#753 no-round-cap).
+ * A real converged / continue / escalate returns immediately. An unreadable
+ * conclusion reasks that officer against the configured ceiling; exhaustion
+ * returns the receipt actually received.
  * On converged, returns the officer snapshot (receipt + nested runId) for seat projection.
  */
 export async function requireSubmissionGate(options: {
@@ -156,9 +163,12 @@ export async function requireSubmissionGate(options: {
   readonly submission?: unknown;
   /** Lowest seam: same as runGatekeeper options.summonOfficer — offline tracers only. */
   readonly summonOfficer?: GateOfficerSummon;
+  /** This loop's ceiling. Absent uses the package default. */
+  readonly autoResumeLimit?: number;
 }): Promise<SubmissionGateOutcome | void> {
   let reask: string | undefined;
-  // No round cap — end only on converged, continue/escalate, or real failure.
+  let reasksSpent = 0;
+  const reaskLimit = deliveryLimitFromConfig(options.autoResumeLimit);
   const summonOfficer =
     options.summonOfficer ??
     createDefaultGateOfficerSummon({
@@ -182,6 +192,7 @@ export async function requireSubmissionGate(options: {
           projected.officer,
           gatekeeper,
           projected.summoned,
+          options.toolCallId,
         );
       } catch (error) {
         options.hostActions.failInfrastructure(error, options.context, options.toolCallId);
@@ -208,6 +219,24 @@ export async function requireSubmissionGate(options: {
       };
     }
     if (gatekeeper.status === "needs_reask") {
+      if (reasksSpent >= reaskLimit) {
+        return {
+          status: "needs_reask",
+          officer: projected.officer,
+          receipt: gatekeeper.receipt,
+          ...(typeof gatekeeper.runId === "string" && gatekeeper.runId.trim() !== ""
+            ? { runId: gatekeeper.runId }
+            : {}),
+          ...(typeof projected.summoned?.runDirectory === "string"
+            && projected.summoned.runDirectory.trim() !== ""
+            ? { runDirectory: projected.summoned.runDirectory }
+            : {}),
+          ...(projected.summoned?.terminal === undefined
+            ? {}
+            : { terminal: projected.summoned.terminal }),
+        };
+      }
+      reasksSpent += 1;
       reask = officerConclusionReask(gatekeeper.receivedStatus);
       continue;
     }

package/src/worker-role.ts

@@ -1,18 +1,15 @@
-import type { RoleHost, HostContext, HostToolResult, HostGatekeeperActions } from "./host-contracts.ts";
-import { Type, type Static } from "typebox";
-import { openToolObject } from "./open-tool-schema.ts";
-import { withTerminatingOutputDeclarations } from "./package-contracts/terminating-infrastructure.ts";
+import type { RoleHost, HostContext, HostGatekeeperActions } from "./host-contracts.ts";
 
 import {
-  CODER_OUTPUT_TOOL_NAME,
-  FIXER_OUTPUT_TOOL_NAME,
   validateAcceptedWorkerDetails,
   type CoderOutput,
   type FixerOutput,
   type WorkerOutput,
   type WorkerRoleLabel,
 } from "./package-contracts/worker-output.ts";
-import { PARTIALLY_COMPLETED_DEFINITION, fixerOutputSchema, validateFixerOutput, type FixerPhase } from "./package-contracts/fixer-output.ts";
+import { validateFixerOutput, type FixerPhase } from "./package-contracts/fixer-output.ts";
+import { registerFiledSubmissionTool } from "./filed-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 import {
   FixerPacketValidationError,
   parseFixerPrerequisites,
@@ -23,7 +20,9 @@ import {
   WorkerCommitReminderError,
   WorkerPrefixReminderError,
   WorkerUnfinishedReasonReminderError,
+  type WorkerSubmissionGate,
 } from "./worker-submission-gates.ts";
+import { deliveryLimitFromEnv } from "./receipt-delivery-policy.ts";
 import {
   fixerBashSeatbeltDenyReason,
   matchFixerBashForbiddenLiteral,
@@ -34,28 +33,10 @@ import { isRecord } from "./unknown-value.ts";
 export {
   CODER_OUTPUT_TOOL_NAME,
   FIXER_OUTPUT_TOOL_NAME,
+  coderOutputSchema,
   validateAcceptedWorkerDetails,
-};
-export type { WorkerOutput };
-
-// 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),
-);
-export type { FixerOutput, CoderOutput };
+} from "./package-contracts/worker-output.ts";
+export type { WorkerOutput, FixerOutput, CoderOutput };
 export const FIXER_FLAG_DEFINITIONS = {
   packet: {
     name: "ak-fix-packet",
@@ -103,7 +84,7 @@ export type CoderRoleDependencies = {
 export type WorkerRoleRuntime = {
   activate(ctx?: HostContext): Promise<void>;
   /** Arm gate ① baseline after envelope places the worktree (coder/fixer). Durable parent required (#857). */
-  armSubmissionGate(cwd: string, parent: { getSessionFile(): string | undefined }): void;
+  armSubmissionGate(cwd: string, parent: { getSessionFile(): string | undefined }, invocationScopeId?: string): void;
 };
 
 /** Read only the field that selects the worker's next package-owned path. */
@@ -128,9 +109,48 @@ export function validateWorkerOutput(
   return validateAcceptedWorkerDetails(output, "Coder") as CoderOutput;
 }
 
+/**
+ * Coder and fixer share one submission sequence: record via the shared tool,
+ * then read status and bounce through the same reminder gate.
+ * Seat differences stay in the ready check and the projection.
+ */
+function registerWorkerSubmission(
+  pi: RoleHost,
+  role: "coder" | "fixer",
+  options: {
+    readonly notReady: string;
+    readonly ready: () => boolean;
+    readonly phase: () => WorkerPhase | undefined;
+    readonly project: (parameters: unknown, phase: WorkerPhase) => WorkerOutput;
+    readonly submissionGate: WorkerSubmissionGate;
+    readonly hostActions: WorkerRoleHostActions;
+  },
+): void {
+  registerFiledSubmissionTool(pi, roleSubmissionDeclaration(role), {
+    readyError: () => (options.ready() ? undefined : options.notReady),
+    beforeAccept: async ({ toolCallId, parameters, ctx }) => {
+      const phase = options.phase();
+      if (phase === undefined) throw new Error(options.notReady);
+      const output = options.project(parameters, phase);
+      const status = workerStatusOf(output);
+      if (status !== undefined) {
+        assertAcceptableThroughHost(
+          options.submissionGate,
+          status,
+          output,
+          options.hostActions,
+          ctx,
+          toolCallId,
+        );
+      }
+      return output;
+    },
+  });
+}
+
 /** Reminder bounces stay typed rejects; IO/infrastructure keep identity via host failInfrastructure. */
 function assertAcceptableThroughHost(
-  submissionGate: { assertAcceptable(status: string, details?: unknown): void },
+  submissionGate: WorkerSubmissionGate,
   status: string,
   details: unknown,
   hostActions: WorkerRoleHostActions,
@@ -155,6 +175,7 @@ export function createFixerRoleRuntime(
   pi: RoleHost,
   dependencies: FixerRoleDependencies,
   hostActions: WorkerRoleHostActions,
+  options?: { readonly unfinishedReasonBounceLimit?: number },
 ): WorkerRoleRuntime {
   let soul: string | undefined;
   let packet: FixerInvocationInput | undefined;
@@ -162,7 +183,12 @@ export function createFixerRoleRuntime(
   let prerequisitesPath: string | undefined;
   let phase: WorkerPhase | undefined;
   let lifecycleRegistered = false;
-  const submissionGate = createWorkerSubmissionGate();
+  // #1132: ADR 0050 缺理由催全次数. The in-process seam passes the value it
+  // already resolved; the Pi child has only the env that seam projected.
+  const submissionGate = createWorkerSubmissionGate({
+    unfinishedReasonBounceLimit: options?.unfinishedReasonBounceLimit
+      ?? deliveryLimitFromEnv(process.env),
+  });
 
   pi.registerFlag(
     FIXER_FLAG_DEFINITIONS.packet.name,
@@ -212,30 +238,13 @@ export function createFixerRoleRuntime(
 
       if (!lifecycleRegistered) {
         lifecycleRegistered = true;
-        pi.registerTool({
-          name: FIXER_OUTPUT_TOOL_NAME,
-          label: "修内司输出",
-          description: "提交修内司终局回执。",
-          promptSnippet: "提交修内司终局回执",
-          parameters: fixerOutputSchema,
-          async execute(toolCallId: string, parameters: unknown, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext): Promise<HostToolResult<unknown>> {
-            if (packet === undefined || phase === undefined) {
-              throw new Error("修内司修理包与阶段未装载");
-            }
-            const output = deepFreeze(validateFixerOutput(parameters, phase));
-            const status = workerStatusOf(output);
-            if (status !== undefined) {
-              assertAcceptableThroughHost(
-                submissionGate,
-                status,
-                output,
-                hostActions,
-                ctx,
-                toolCallId,
-              );
-            }
-            return { content: [], details: output, terminate: true as const };
-          },
+        registerWorkerSubmission(pi, "fixer", {
+          notReady: "修内司修理包与阶段未装载",
+          ready: () => packet !== undefined && phase !== undefined,
+          phase: () => phase,
+          project: (parameters, current) => deepFreeze(validateFixerOutput(parameters, current)),
+          submissionGate,
+          hostActions,
         });
         pi.on("tool_call", (event) => {
           if (event.toolName !== "bash") return;
@@ -263,8 +272,8 @@ export function createFixerRoleRuntime(
         });
       }
     },
-    armSubmissionGate(cwd: string, parent: { getSessionFile(): string | undefined }) {
-      submissionGate.arm(cwd, parent);
+    armSubmissionGate(cwd: string, parent: { getSessionFile(): string | undefined }, invocationScopeId?: string) {
+      submissionGate.arm(cwd, parent, invocationScopeId);
     },
   };
 }
@@ -273,12 +282,17 @@ export function createCoderRoleRuntime(
   pi: RoleHost,
   dependencies: CoderRoleDependencies,
   hostActions: WorkerRoleHostActions,
+  options?: { readonly unfinishedReasonBounceLimit?: number },
 ): WorkerRoleRuntime {
   let soul: string | undefined;
   let task: string | undefined;
   let phase: WorkerPhase | undefined;
   let lifecycleRegistered = false;
-  const submissionGate = createWorkerSubmissionGate();
+  // #1132: same resolved ceiling as the fixer gate. Absent = Pi child env.
+  const submissionGate = createWorkerSubmissionGate({
+    unfinishedReasonBounceLimit: options?.unfinishedReasonBounceLimit
+      ?? deliveryLimitFromEnv(process.env),
+  });
 
   pi.registerFlag("ak-coder-task", {
     description: "Markdown task assigned to the coder role",
@@ -310,32 +324,13 @@ export function createCoderRoleRuntime(
 
       if (!lifecycleRegistered) {
         lifecycleRegistered = true;
-        pi.registerTool({
-          name: CODER_OUTPUT_TOOL_NAME,
-          label: "将作监输出",
-          description: "提交将作监终局回执。",
-          promptSnippet: "提交将作监终局回执",
-          parameters: coderOutputSchema,
-          async execute(toolCallId: string, parameters: unknown, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext): Promise<HostToolResult<unknown>> {
-            if (task === undefined || phase === undefined) {
-              throw new Error("将作监任务与阶段未装载");
-            }
-            const output = validateWorkerOutput(parameters, phase, "Coder");
-            const status = workerStatusOf(output);
-            // #836: skill-expansion evidence rejection deleted (陛下「2.4/5 删」).
-            // Skill still ships with the package (ADR 0052); code no longer refuses on it.
-            if (status !== undefined) {
-              assertAcceptableThroughHost(
-                submissionGate,
-                status,
-                output,
-                hostActions,
-                ctx,
-                toolCallId,
-              );
-            }
-            return { content: [], details: output, terminate: true as const };
-          },
+        registerWorkerSubmission(pi, "coder", {
+          notReady: "将作监任务与阶段未装载",
+          ready: () => task !== undefined && phase !== undefined,
+          phase: () => phase,
+          project: (parameters, current) => validateWorkerOutput(parameters, current, "Coder"),
+          submissionGate,
+          hostActions,
         });
         pi.on("before_agent_start", (event, ctx) => {
           if (soul === undefined) throw new Error("将作监职分未装载");
@@ -346,8 +341,8 @@ export function createCoderRoleRuntime(
         });
       }
     },
-    armSubmissionGate(cwd: string, parent: { getSessionFile(): string | undefined }) {
-      submissionGate.arm(cwd, parent);
+    armSubmissionGate(cwd: string, parent: { getSessionFile(): string | undefined }, invocationScopeId?: string) {
+      submissionGate.arm(cwd, parent, invocationScopeId);
     },
   };
 }

package/src/worker-submission-gates.ts

@@ -16,6 +16,7 @@ import {
   WorkerUnfinishedReasonReminderError,
 } from "./submission-errors.ts";
 import { WORKER_DONE_STATUSES } from "./worker-submission-contracts.ts";
+import { deliveryLimitFromConfig } from "./receipt-delivery-policy.ts";
 
 import { isRecord } from "./unknown-value.ts";
 
@@ -26,6 +27,7 @@ export const WORKER_SUBMISSION_GATE_RECORD_KIND = WORKER_SUBMISSION_GATE_KIND;
 export const WORKER_COMMIT_BASELINE_ENTRY_TYPE = "commit-baseline";
 export const WORKER_COMMIT_REMINDER_BOUNCE_ENTRY_TYPE = "commit-reminder-bounce";
 export const WORKER_PREFIX_REMINDER_BOUNCE_ENTRY_TYPE = "prefix-reminder-bounce";
+export const WORKER_UNFINISHED_REASON_BOUNCE_ENTRY_TYPE = "unfinished-reason-bounce";
 
 /** Historical package hook ownership marker — uninstall criterion only. */
 const HOOK_MARKER = "ak-roles: worker-submission-gates reference-transaction";
@@ -33,7 +35,6 @@ const HOOKS_DIR = "ak-roles-hooks";
 const HOOK_FILE = "reference-transaction";
 /** Open platform-prefix domain (constitution #10) — not a closed singleton. */
 const PLATFORM_PREFIX = /^[A-Za-z][A-Za-z0-9_-]*:/;
-const UNFINISHED_REASON_BOUNCE_LIMIT = 2;
 
 export type WorkerSubmissionGateParent = RecordSessionParent;
 
@@ -171,14 +172,16 @@ function unfinishedReasonPresent(details?: unknown): boolean {
   return containsWrittenReason(details.reason);
 }
 
-function readGateState(session: HostRecordSession): {
+function readGateState(session: HostRecordSession, invocationScopeId?: string): {
   baseline: string | null | undefined;
   reminded: boolean;
   prefixReminded: boolean;
+  unfinishedReasonBounces: number;
 } {
   let baseline: string | null | undefined;
   let reminded = false;
   let prefixReminded = false;
+  let unfinishedReasonBounces = 0;
   for (const entry of session.getEntries()) {
     if (entry.type !== "custom") continue;
     if (entry.customType === WORKER_COMMIT_BASELINE_ENTRY_TYPE) {
@@ -190,9 +193,13 @@ function readGateState(session: HostRecordSession): {
       reminded = true;
     } else if (entry.customType === WORKER_PREFIX_REMINDER_BOUNCE_ENTRY_TYPE) {
       prefixReminded = true;
+    } else if (entry.customType === WORKER_UNFINISHED_REASON_BOUNCE_ENTRY_TYPE
+      && invocationScopeId !== undefined && isRecord(entry.data)
+      && entry.data.invocationScopeId === invocationScopeId) {
+      unfinishedReasonBounces += 1;
     }
   }
-  return { baseline, reminded, prefixReminded };
+  return { baseline, reminded, prefixReminded, unfinishedReasonBounces };
 }
 
 function isAncestor(cwd: string, ancestor: string, descendant: string): boolean {
@@ -234,13 +241,20 @@ export type CreateWorkerSubmissionGateOptions = {
    * Path still derives from required parent session; home only pins ledger root. #604 Scope 2.
    */
   readonly home?: string;
+  /**
+   * #1132: ADR 0050 缺理由催全次数 read from the single configured
+   * `autoResumeLimit` value. Absent = package default. Resolved once here; the
+   * gate never re-reads it per submission. Exhaustion still accepts (照收) —
+   * only the count changes.
+   */
+  readonly unfinishedReasonBounceLimit?: number;
 };
 
 export function createWorkerSubmissionGate(
   options: CreateWorkerSubmissionGateOptions = {},
 ): {
   /** Durable parent is required — ownership must be known at arm (#857 loud failure). */
-  arm(cwd: string, parent: WorkerSubmissionGateParent): void;
+  arm(cwd: string, parent: WorkerSubmissionGateParent, invocationScopeId?: string): void;
   assertAcceptable(status: string, details?: unknown): void;
 } {
   let baseline: string | null | undefined;
@@ -248,11 +262,14 @@ export function createWorkerSubmissionGate(
   let reminded = false;
   let prefixReminded = false;
   let unfinishedReasonBounces = 0;
+  let invocationScopeId: string | undefined;
   let record: HostRecordSession | undefined;
   /** Parent session file retained so every gate sitian write path-derives the same ledger home. */
   let sessionParent: string | undefined;
   const explicitHome =
     typeof options.home === "string" && options.home.length > 0 ? options.home : undefined;
+  // #1132: one configured number, resolved once at gate construction.
+  const unfinishedReasonBounceLimit = deliveryLimitFromConfig(options.unfinishedReasonBounceLimit);
   const head = (cwd: string): string | null => {
     try {
       return git(cwd, ["rev-parse", "HEAD"]);
@@ -273,7 +290,8 @@ export function createWorkerSubmissionGate(
     });
   };
   return {
-    arm(cwd, parent) {
+    arm(cwd, parent, scope) {
+      invocationScopeId = scope;
       uninstallPackageWorkerHooks(cwd);
       root = cwd;
       sessionParent = parent.getSessionFile();
@@ -282,7 +300,8 @@ export function createWorkerSubmissionGate(
         kind: WORKER_SUBMISSION_GATE_RECORD_KIND,
         parent,
       });
-      const prior = readGateState(record);
+      const prior = readGateState(record, invocationScopeId);
+      unfinishedReasonBounces = prior.unfinishedReasonBounces;
       if (prior.baseline !== undefined) {
         baseline = prior.baseline;
         reminded = prior.reminded;
@@ -304,7 +323,10 @@ export function createWorkerSubmissionGate(
     },
     assertAcceptable(status, details) {
       if (status === "unfinished" && !unfinishedReasonPresent(details)) {
-        if (unfinishedReasonBounces < UNFINISHED_REASON_BOUNCE_LIMIT) {
+        if (unfinishedReasonBounces < unfinishedReasonBounceLimit) {
+          record?.appendCustomEntry(WORKER_UNFINISHED_REASON_BOUNCE_ENTRY_TYPE, {
+            version: 1, invocationScopeId,
+          });
           unfinishedReasonBounces += 1;
           throw new WorkerUnfinishedReasonReminderError();
         }
@@ -345,3 +367,6 @@ export function createWorkerSubmissionGate(
     },
   };
 }
+
+/** The gate object returned above. Callers reference this instead of restating assertAcceptable. */
+export type WorkerSubmissionGate = ReturnType<typeof createWorkerSubmissionGate>;