@akagilnc/pi-workflow-roles 0.1.4620 → 0.1.4641

package/src/gatekeeper-role.ts

@@ -12,30 +12,49 @@ import {
 } from "./package-contracts/gatekeeper-output.ts";
 import type { PublicSummonResult } from "./public-role-summons.ts";
 import type { TerminalResult } from "./public-cli/terminal.ts";
+import { runIdFromRunDirectory } from "./run-terminal-artifacts.ts";
 export const INSPECTOR_OUTPUT_TOOL = INSPECTOR_OUTPUT_TOOL_NAME;
 export const NOTARY_OUTPUT_TOOL = "ak_notary_output";
 
-/** Gate review officers — 台院 / 符宝郎 / 审刑院 (#753 / #756). */
-export type GateOfficer = "inspector" | "notary" | "auditor";
+/** Gate review officers — 台院 / 符宝郎 / 审刑院 / 给事中 (#753 / #756 / #969). */
+export type GateOfficer = "inspector" | "notary" | "auditor" | "countersign";
 
 /** Officer routing only — content is self-fetched via the shared run-dossier tool (#632). */
 export type GatekeeperSubject =
   | { readonly kind: "worker_completion" }
   | { readonly kind: "judge_draft" }
   | { readonly kind: "judge_compliance" }
-  | { readonly kind: "countersign_verdict" };
+  | { readonly kind: "countersign_verdict" }
+  | { readonly kind: "secretariat_verdict" };
 
 /**
  * Gate projection for the review queue (#753 / #750).
  * Code only reads the conclusion field for queueing. Officer words ride as
  * `receipt` unchanged — no findings rewrite, no unreadable/unusable label,
  * no next-step selection for the parent.
+ * `runId` is the nested officer run id when known (summoned.runDirectory /
+ * terminal.runId) — public terminal projection consumes it (#969).
  */
 export type GatekeeperResult =
-  | { readonly status: "pass"; readonly officer: GateOfficer; readonly receipt: unknown }
+  | {
+      readonly status: "pass";
+      readonly officer: GateOfficer;
+      readonly receipt: unknown;
+      readonly runId?: string;
+    }
   /** bounce | escalate: both return the officer receipt to the parent (#753 / #756). */
-  | { readonly status: "bounce"; readonly officer: GateOfficer; readonly receipt: unknown }
-  | { readonly status: "escalate"; readonly officer: GateOfficer; readonly receipt: unknown }
+  | {
+      readonly status: "bounce";
+      readonly officer: GateOfficer;
+      readonly receipt: unknown;
+      readonly runId?: string;
+    }
+  | {
+      readonly status: "escalate";
+      readonly officer: GateOfficer;
+      readonly receipt: unknown;
+      readonly runId?: string;
+    }
   | {
       /**
        * Accepted reply whose conclusion is not pass|bounce|escalate.
@@ -45,6 +64,7 @@ export type GatekeeperResult =
       readonly status: "needs_reask";
       readonly officer: GateOfficer;
       readonly receipt: unknown;
+      readonly runId?: string;
     }
   | { readonly status: "no_receipt"; readonly stage: GateOfficer; readonly reason: string; readonly facts: NoReceiptLifecycleFacts }
   | {
@@ -64,13 +84,15 @@ export type GatekeeperNonPassResult = Extract<
 function gateSeatLabel(stage: GateOfficer): string {
   if (stage === "inspector") return "台院";
   if (stage === "auditor") return "审刑院";
+  if (stage === "countersign") return "给事中";
   return "符宝郎";
 }
 
-/** Subject kind → review officer (#753 countersign/notary, #756 judge/auditor + worker/inspector). */
+/** Subject kind → review officer (#753 countersign/notary, #756 judge/auditor + worker/inspector, #969 secretariat/countersign). */
 export function gateOfficerForSubject(subject: GatekeeperSubject): GateOfficer {
   if (subject.kind === "worker_completion") return "inspector";
   if (subject.kind === "judge_compliance") return "auditor";
+  if (subject.kind === "secretariat_verdict") return "countersign";
   return "notary";
 }
 
@@ -183,6 +205,14 @@ function readRecord(value: unknown): Record<string, unknown> | undefined {
  * `fallbackStatus` is the terminal outcome.status when the receipt body has no status key
  * (keeps missing-args sentinel intact as the receipt).
  */
+/** Map 给事中 countersignStatus onto the shared gate queue words (#969). */
+function gateStatusFromCountersign(status: string): string | undefined {
+  if (status === "converged") return "pass";
+  if (status === "continue") return "bounce";
+  if (status === "escalate") return "escalate";
+  return undefined;
+}
+
 function projectOfficerDecision(
   officer: GateOfficer,
   decision: unknown,
@@ -190,6 +220,26 @@ function projectOfficerDecision(
 ): GatekeeperResult {
   const receipt = retainedReceipt(decision);
   const record = readRecord(decision);
+  // 给事中: only countersignStatus, strict three-word map; never generic status,
+  // never unmapped raw word, never fallbackStatus (#969 / ADR 0040/0055).
+  if (officer === "countersign") {
+    const countersignStatus =
+      record !== undefined && typeof record.countersignStatus === "string"
+        ? record.countersignStatus
+        : undefined;
+    const status =
+      typeof countersignStatus === "string"
+        ? gateStatusFromCountersign(countersignStatus)
+        : undefined;
+    if (status === "pass") {
+      return { status: "pass", officer, receipt };
+    }
+    if (status === "bounce" || status === "escalate") {
+      return { status, officer, receipt };
+    }
+    return { status: "needs_reask", officer, receipt };
+  }
+  // inspector / notary / auditor: shared gate words on generic status.
   const status =
     (record !== undefined && typeof record.status === "string" ? record.status : undefined)
     ?? fallbackStatus;
@@ -240,6 +290,41 @@ function projectOfficerPayloads(
   return projectOfficerDecision(officer, payloads[payloads.length - 1], fallbackStatus);
 }
 
+/** Nested officer runId from summoned.runDirectory, else terminal.runId (#969). */
+export function officerRunIdFromSummoned(summoned: PublicSummonResult): string | undefined {
+  if (typeof summoned.runDirectory === "string" && summoned.runDirectory.trim() !== "") {
+    const fromDir = runIdFromRunDirectory(summoned.runDirectory);
+    if (fromDir !== undefined) return fromDir;
+  }
+  const terminal = summoned.terminal;
+  if (
+    terminal !== undefined
+    && typeof terminal.runId === "string"
+    && terminal.runId.trim() !== ""
+  ) {
+    return terminal.runId;
+  }
+  return undefined;
+}
+
+function withOfficerRunId(
+  result: GatekeeperResult,
+  summoned: PublicSummonResult,
+): GatekeeperResult {
+  if (
+    result.status !== "pass"
+    && result.status !== "bounce"
+    && result.status !== "escalate"
+    && result.status !== "needs_reask"
+  ) {
+    return result;
+  }
+  if (typeof result.runId === "string" && result.runId.trim() !== "") return result;
+  const runId = officerRunIdFromSummoned(summoned);
+  if (runId === undefined) return result;
+  return { ...result, runId };
+}
+
 function projectOfficerTerminal(
   officer: GateOfficer,
   summoned: PublicSummonResult,
@@ -279,25 +364,34 @@ function projectOfficerTerminal(
     };
   }
   if (outcome.kind === "audit_escalation") {
-    return {
-      status: "escalate",
-      officer,
-      // This-court receipt only (#879) — historical rows remain on terminal.submissions.
-      receipt: thisCourt.length > 0 ? thisCourt[thisCourt.length - 1] : retainedReceipt(outcome),
-    };
+    return withOfficerRunId(
+      {
+        status: "escalate",
+        officer,
+        // This-court receipt only (#879) — historical rows remain on terminal.submissions.
+        receipt: thisCourt.length > 0 ? thisCourt[thisCourt.length - 1] : retainedReceipt(outcome),
+      },
+      summoned,
+    );
   }
   if (outcome.kind === "accepted") {
     // outcome.status is the fixture/compat leaf: production settlement leaves
     // it undefined once payloads are recorded, so this only matters when a
     // caller still supplies status without any recorded payload (#836 hang).
-    return projectOfficerPayloads(officer, thisCourt, outcome.status);
+    return withOfficerRunId(
+      projectOfficerPayloads(officer, thisCourt, outcome.status),
+      summoned,
+    );
   }
-  return {
-    status: "needs_reask",
-    officer,
-    // This-court receipt only (#879).
-    receipt: thisCourt.length > 0 ? thisCourt[thisCourt.length - 1] : retainedReceipt(outcome),
-  };
+  return withOfficerRunId(
+    {
+      status: "needs_reask",
+      officer,
+      // This-court receipt only (#879).
+      receipt: thisCourt.length > 0 ? thisCourt[thisCourt.length - 1] : retainedReceipt(outcome),
+    },
+    summoned,
+  );
 }
 
 /** Projection carrier for the shared submit envelope (ADR 0018). No lifecycle book here. */
@@ -311,10 +405,21 @@ export type GatekeeperProjection = {
 /**
  * Plain-language re-ask when the officer conclusion is not pass|bounce|escalate.
  * Not a packaged engine handbook line (#755 exception for 读不出三态).
+ * inspector / notary / auditor keep shared gate words; 给事中 uses own three-state
+ * field and words so reask does not invite non-contract values (#969 / ADR 0055).
  */
 export const OFFICER_CONCLUSION_REASK =
   "上次交卷的结论不是 pass、bounce、escalate 三态之一。请重新输出，结论字段写明其一；打回或上呈的话就是给对方看的原文。" as const;
 
+/** 给事中 re-ask: countersignStatus converged|continue|escalate only (#969). */
+export const COUNTERSIGN_CONCLUSION_REASK =
+  "上次交卷的 countersignStatus 不是 converged、continue、escalate 三态之一。请重新输出，countersignStatus 写明其一；封驳或上呈的话就是给对方看的原文。" as const;
+
+/** Pick the re-ask line for the officer under review. */
+export function officerConclusionReask(officer: GateOfficer): string {
+  return officer === "countersign" ? COUNTERSIGN_CONCLUSION_REASK : OFFICER_CONCLUSION_REASK;
+}
+
 /**
  * Summon (via injected seam) + project. Default summonGateOfficer drive lives
  * on the shared envelope (`gatekeeper-pass-envelope.ts`, ADR 0018 / #675) —

package/src/host-contracts.ts

@@ -337,7 +337,12 @@ type HostEventHandler<K extends keyof HostEventMap> = (event: HostEventMap[K], c
 export type HostEventRegistration = { [K in keyof HostEventMap]: [event: K, handler: HostEventHandler<K>] }[keyof HostEventMap];
 
 type HostGatekeeperSubject = {
-  readonly kind: "worker_completion" | "judge_draft" | "judge_compliance" | "countersign_verdict";
+  readonly kind:
+    | "worker_completion"
+    | "judge_draft"
+    | "judge_compliance"
+    | "countersign_verdict"
+    | "secretariat_verdict";
 };
 /** Gatekeeper non-pass faces returned to parent (#836 includes transport_failure; never kill leg). */
 type HostGatekeeperNonPass = { readonly status: "bounce" | "escalate" | "no_receipt" | "transport_failure" } & Record<string, unknown>;
@@ -388,7 +393,22 @@ export interface RoleHost {
   getAllTools(): Array<{ name: string; sourceInfo?: { path?: string } }>;
   setActiveTools(names: string[]): void;
   getActiveTools(): string[];
-  requireGatekeeperPass?(options: { context: HostContext; subject: HostGatekeeperSubject; signal?: AbortSignal; hostActions: HostGatekeeperActions; toolCallId: string; submission?: unknown }): Promise<void>;
+  /**
+   * Shared gate envelope. On pass may return officer snapshot (receipt + nested
+   * runId) for seat public-terminal projection (#969); callers may ignore it.
+   */
+  requireGatekeeperPass?(options: {
+    context: HostContext;
+    subject: HostGatekeeperSubject;
+    signal?: AbortSignal;
+    hostActions: HostGatekeeperActions;
+    toolCallId: string;
+    submission?: unknown;
+  }): Promise<void | {
+    readonly officer: string;
+    readonly receipt: unknown;
+    readonly runId?: string;
+  }>;
   on(event: "before_agent_start", handler: HostEventHandler<"before_agent_start">): void;
   on(event: "input", handler: HostEventHandler<"input">): void;
   on(event: "tool_call", handler: HostEventHandler<"tool_call">): void;

package/src/pi/adapter.ts

@@ -92,7 +92,11 @@ function requirePiGatekeeperPass(options: {
   hostActions: HostGatekeeperActions;
   toolCallId: string;
   submission?: unknown;
-}): Promise<void> {
+}): Promise<void | {
+  readonly officer: string;
+  readonly receipt: unknown;
+  readonly runId?: string;
+}> {
   return requireGatekeeperPass({
     context: options.context,
     subject: options.subject,

package/src/pi/role-turn-host.ts

@@ -470,9 +470,6 @@ export function createPiRoleTurnHost(config: PiRoleTurnHostConfig): RoleTurnHost
       ) {
         env.AK_ROLE_AUDITOR_SUBJECT = process.env.AK_ROLE_AUDITOR_SUBJECT;
       }
-      if (request.correlationId !== undefined && request.correlationId.trim() !== "") {
-        env.AK_CORRELATION_ID = request.correlationId;
-      }
       if (
         config.recordLaunchedRolePackageIdentity !== undefined &&
         config.observeLaunchedRolePackageIdentity !== undefined

package/src/public-cli/auto-resume.ts

@@ -32,6 +32,7 @@ import {
   type RunWriterLease,
 } from "./run-lifecycle.ts";
 import { parseAutoResumeLimit } from "./config.ts";
+import { processCancelSignalName } from "./process-cancel.ts";
 import { isLawfulTypedTerminalOutcome, formatTerminalResult, type TerminalArtifactRef, type TerminalResult, type TerminalRoleName } from "./terminal.ts";
 import {
   attachRecordedSubmissions,
@@ -473,6 +474,11 @@ export async function runWithAutoResumeLoop<
    * before the first dispatch instead of silently bypassing the ceiling comparison.
    */
   autoResumeLimit?: number | undefined;
+  /**
+   * #855: process-cancel signal. Once aborted by a catchable process signal,
+   * the loop must not dispatch another turn or spawn another child.
+   */
+  signal?: AbortSignal;
   buildInitialPayload: () => TPayload;
   buildResumePayload: () => TPayload;
   dispatch: (payload: TPayload, lease: RunWriterLease, isFirst: boolean, attemptIo: CliIo) => Promise<T>;
@@ -578,6 +584,11 @@ export async function runWithAutoResumeLoop<
         if (terminal !== undefined) presentTerminal(terminal, options.io);
         return result;
       }
+      // #855: process cancel — stop even if dispatch forgot skipAutoResume.
+      if (processCancelSignalName(options.signal) !== undefined) {
+        if (terminal !== undefined) presentTerminal(terminal, options.io);
+        return result;
+      }
     }
 
     if (result !== undefined) {
@@ -616,6 +627,29 @@ export async function runWithAutoResumeLoop<
           terminal,
         } as T;
       }
+      // #855: process cancel on the throw path — do not re-dispatch; name the signal.
+      const cancelName = processCancelSignalName(options.signal);
+      if (cancelName !== undefined) {
+        const terminal = await attachDispatchExceptionTerminal(
+          options.admitted,
+          dispatchExceptionFailureTerminal({
+            role: options.admitted.role,
+            runId: options.admitted.runId,
+            causeError: lastThrownError,
+            errorFiles: retainedErrorFiles,
+            autoResumeAttempts,
+            endReason: `ak-role terminated by ${cancelName}`,
+            everyAttemptThrew,
+          }),
+          options.io,
+        );
+        await finalizeExceptionRunBestEffort(options.admitted.runDirectory, options.io);
+        presentTerminal(terminal, options.io);
+        return {
+          exitCode: 1,
+          terminal,
+        } as T;
+      }
       if (!(await isPrincipalAvailable(options.admitted.principal))) {
         const terminal = await attachDispatchExceptionTerminal(
           options.admitted,

package/src/public-cli/cli.ts

@@ -305,6 +305,11 @@ export type CliEnv = {
    * skip same-ticket auto-resume. Not a public flag — the verb is the choice.
    */
   freshSummons?: true;
+  /**
+   * #855: process-level cancel (SIGTERM/SIGINT/SIGHUP). Nested turns receive
+   * the same signal so hosts can gracefully stop children.
+   */
+  signal?: AbortSignal;
 };
 
 
@@ -413,6 +418,7 @@ function createRoleEnvironment(
       ? {}
       : { autoResumeLimit: options.config.autoResumeLimit }),
     ...(env.freshSummons === true ? { freshSummons: true as const } : {}),
+    ...(env.signal === undefined ? {} : { signal: env.signal }),
   };
 }
 
@@ -1168,6 +1174,30 @@ async function runConfigCommand(
   throw new CliUsageError(`unknown config subcommand: ${args[0]}`);
 }
 
+/**
+ * #855: process-cancel handlers only for commands that run a role turn
+ * (callable roles / resume / new). analyst/roles/config/help keep Node's
+ * default SIGINT/SIGTERM termination — installing handlers would swallow Ctrl+C.
+ */
+export function commandNeedsProcessCancel(argv: readonly string[]): boolean {
+  // Decision-time parse must not escape the CLI usage boundary. Malformed
+  // global flags throw CliUsageError here; return false and let runAkRole
+  // present the same structured usage reject (exit 2). Handlers are moot
+  // when parse fails — install-or-not has no subsequent effect.
+  let parsed: ParsedGlobal;
+  try {
+    parsed = parseArgv(argv);
+  } catch (error) {
+    if (error instanceof CliUsageError) return false;
+    throw error;
+  }
+  if (parsed.help || parsed.command === undefined || parsed.command === "help") {
+    return false;
+  }
+  if (parsed.command === "resume" || parsed.command === "new") return true;
+  return isPublicCallableRole(parsed.command);
+}
+
 export async function runAkRole(
   argv: readonly string[],
   env: CliEnv,

package/src/public-cli/countersign-run.ts

@@ -88,6 +88,22 @@ export type CountersignRunEnv = PostAdmissionEnv & {
    * replace — never union. Production leaves unset outside that handoff.
    */
   pendingCourtTicketNumbers?: readonly number[];
+  /**
+   * #969 gate path: plain-language re-ask when prior 给事中 reply was not three-state.
+   * Wins over gateReviewInstruction when both present (notary/inspector precedent).
+   */
+  reviewReask?: string;
+  /**
+   * #969/#879 Secretariat submission-gate body: verbatim parent payload as dialogue
+   * content when reviewReask is absent. Binding stays ticket / argv instruction.
+   */
+  gateReviewInstruction?: string;
+  /**
+   * #969 gate path: parent run durable board ticket handoff. Same-ticket resume
+   * key and identity 起居郎 bind under this key — never re-derived from receipt
+   * ticketNumber (optional / omit-able payload field).
+   */
+  boundTicketNumber?: number;
 };
 
 /** Project admitted invocation onto the host-neutral turn request. */
@@ -470,6 +486,10 @@ export async function runPublicCountersign(
                 instruction: parsed.instruction,
                 projectRoot: admitted.projectRoot,
                 failureLabel: "unbound summons",
+                // #969: parent durable ticket is the resume/bind key (ADR 0079).
+                ...(env.boundTicketNumber === undefined
+                  ? {}
+                  : { boundTicketNumber: env.boundTicketNumber }),
               },
               env,
               io,
@@ -528,16 +548,30 @@ export async function runPublicCountersign(
           }
 
           // Missing lawful 起居郎 terminal is not countersign body failure: leave
-          // unbound and continue (true-unbound face). Escalate / typed failure above;
-          // bound refresh still fails honest via runCountersignCourtDiaristStation.
+          // unbound and continue (true-unbound face) — unless parent gate handoff
+          // already carries the durable board ticket (#969). Escalate / typed
+          // failure above; bound refresh still fails honest via station.
           if (outcome.identity.kind === "ticket") {
-            const assertedTicket = outcome.identity.ticketNumber;
-            typedTicket = assertedTicket;
+            // #969: parent durable handoff wins over 起居郎 re-assert when both
+            // present (receipt/assert mismatch → parent resume key).
+            typedTicket = isSafePositiveTicketNumber(env.boundTicketNumber)
+              ? env.boundTicketNumber
+              : outcome.identity.ticketNumber;
             // #871: identity may hand a co-review set; absent field defaults to [main].
             typedCourtTicketNumbers = outcome.identity.courtTicketNumbers;
+          } else if (isSafePositiveTicketNumber(env.boundTicketNumber)) {
+            // Parent board handoff present; 起居郎 returned true-unbound — still
+            // resume/bind under the parent key (omitted receipt ticketNumber path).
+            typedTicket = env.boundTicketNumber;
+          }
+          if (typedTicket !== undefined) {
+            // #969/#879: gate re-ask / parent submission body share summons.instruction
+            // (reask wins; argv instruction remains the 起居郎 identity face above).
+            const resumeInstruction =
+              env.reviewReask ?? env.gateReviewInstruction ?? parsed.instruction;
             const summons: SameTicketSummonsMaterials = {
-              instruction: parsed.instruction,
-              instructionEmpty: parsed.instruction.trim() === "",
+              instruction: resumeInstruction,
+              instructionEmpty: resumeInstruction.trim() === "",
             };
             const resumed = await tryResumeSameTicketSeatRun({
               home: env.home,
@@ -641,13 +675,16 @@ export async function runPublicCountersign(
             : { correlationId: env.correlationId }),
           continuation: {
             kind: "initial",
-            prompt: buildCountersignTransportPrompt(
-              admitted,
-              engineSessionMaterialFromOptions({
-                ...pickEngineAxis(env),
-                packageRoot: env.packageRoot,
-              }),
-            ),
+            // #969/#879: gate path first mint carries parent payload as dialogue content;
+            // ordinary public entry keeps package transport prompt.
+            prompt: (env.reviewReask ?? env.gateReviewInstruction)
+              ?? buildCountersignTransportPrompt(
+                admitted,
+                engineSessionMaterialFromOptions({
+                  ...pickEngineAxis(env),
+                  packageRoot: env.packageRoot,
+                }),
+              ),
           },
         };
         // Mutable shell: ticket bind re-projects activation before executeTurn.

package/src/public-cli/main.ts

@@ -34,6 +34,28 @@ process.env.AK_ROLE_PACKAGE_ROOT = packageRoot;
 // The host-provided runtime must be resolvable before the CLI module graph loads it.
 ensureHostPiRuntimeResolvable(packageRoot);
 
-const { runAkRole } = await import("./cli.ts");
-const result = await runAkRole(process.argv.slice(2), { packageRoot });
-process.exitCode = result.exitCode;
+const { runAkRole, commandNeedsProcessCancel } = await import("./cli.ts");
+const { installProcessCancelHandlers } = await import("./process-cancel.ts");
+
+// #855: catchable signals only for role-turn commands. analyst/roles/config/help
+// keep Node default termination — global handlers would swallow Ctrl+C.
+const argv = process.argv.slice(2);
+const processCancel = commandNeedsProcessCancel(argv)
+  ? installProcessCancelHandlers()
+  : undefined;
+try {
+  const result = await runAkRole(argv, {
+    packageRoot,
+    ...(processCancel === undefined ? {} : { signal: processCancel.signal }),
+  });
+  // Signal termination is never a successful public exit, even if a seat
+  // somehow returned zero before settlement folded the abort.
+  process.exitCode =
+    processCancel !== undefined &&
+    processCancel.receivedSignal() !== undefined &&
+    result.exitCode === 0
+      ? 1
+      : result.exitCode;
+} finally {
+  processCancel?.dispose();
+}