@akagilnc/pi-workflow-roles 0.1.4631 → 0.1.4646

package/dist/public-cli/settlement.js

@@ -32,7 +32,7 @@ import { NOTARY_OUTPUT_TOOL_NAME, } from "../notary-contracts.js";
 import { COUNTERSIGN_OUTPUT_TOOL_NAME, } from "../countersign-contracts.js";
 import { GLEANER_LEFT_OUTPUT_TOOL_NAME, } from "../gleaner-left-contracts.js";
 import { DIARIST_OUTPUT_TOOL_NAME, } from "../diarist-contracts.js";
-import { SECRETARIAT_OUTPUT_TOOL_NAME, } from "../secretariat-contracts.js";
+import { SECRETARIAT_COUNTERSIGN_TERMINAL_FACT_KEY, SECRETARIAT_GATE_OFFICER_ENTRY_TYPE, SECRETARIAT_OUTPUT_TOOL_NAME, } from "../secretariat-contracts.js";
 import { INSPECTOR_OUTPUT_TOOL_NAME, } from "../inspector-contracts.js";
 import { GATEKEEPER_OUTPUT_TOOL_NAME, } from "../package-contracts/gatekeeper-output.js";
 import { NAVIGATOR_OUTPUT_TOOL_NAME, } from "../package-contracts/navigator-output.js";
@@ -2254,11 +2254,104 @@ async function settleLawfulDiaristTerminalResult(admitted, authority, scope) {
 export async function trySettleDiaristTerminalResult(admitted, authority, scope) {
     return settleLawfulDiaristTerminalResult(admitted, authority, scope);
 }
+/**
+ * #969 seat projection sole authority: 给事中 terminal (署|上呈) booked as a
+ * durable custom entry (envelope-safe) — ledger accepted stays LLM params (#836).
+ * Never scan toolResult rows: those are memory-only on headless/ACP (#617/#959).
+ * Receipt bytes stay original; nested runId rides beside them.
+ * Caller must only apply this when the terminal-defining submission actually
+ * produced the officer entry (gate-bound converged, or 给事中 audit_escalation).
+ */
+function countersignTerminalFromEntries(entries) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry?.type !== "custom")
+            continue;
+        if (entry.customType !== SECRETARIAT_GATE_OFFICER_ENTRY_TYPE)
+            continue;
+        const data = entry.data !== null && typeof entry.data === "object" && !Array.isArray(entry.data)
+            ? entry.data
+            : undefined;
+        if (data?.officer !== "countersign")
+            continue;
+        if (data.receipt === undefined)
+            continue;
+        const runId = typeof data.runId === "string" && data.runId.trim() !== ""
+            ? data.runId
+            : undefined;
+        return {
+            receipt: data.receipt,
+            ...(runId === undefined ? {} : { runId }),
+        };
+    }
+    return undefined;
+}
+function withCountersignTerminalFact(roleOutcome, officer) {
+    const prior = roleOutcome.decisiveFacts !== undefined && isRecord(roleOutcome.decisiveFacts)
+        ? roleOutcome.decisiveFacts
+        : {};
+    return {
+        ...roleOutcome,
+        decisiveFacts: {
+            ...prior,
+            [SECRETARIAT_COUNTERSIGN_TERMINAL_FACT_KEY]: officer,
+        },
+    };
+}
+/**
+ * Terminal-defining secretariat submission owns officer projection.
+ * Last readable secretariatStatus on accepted payloads decides: only gate-bound
+ * converged projects a prior durable officer entry. Parent escalate bypasses the
+ * gate and must not inherit a stale pass entry from an earlier turn (#969).
+ */
+function acceptedSecretariatDefinesOfficerProjection(roleOutcome) {
+    const payloads = roleOutcome.payloads ?? [];
+    for (let index = payloads.length - 1; index >= 0; index -= 1) {
+        const payload = payloads[index];
+        if (!isRecord(payload))
+            continue;
+        const status = payload.secretariatStatus;
+        if (typeof status !== "string")
+            continue;
+        return status === "converged";
+    }
+    return false;
+}
 async function settleLawfulSecretariatTerminalResult(admitted, authority, scope) {
-    return settleLawfulSeatAcceptedTerminalResult(admitted, authority, {
+    const settled = await settleLawfulSeatAcceptedTerminalResult(admitted, authority, {
         role: "secretariat",
         toolName: SECRETARIAT_OUTPUT_TOOL_NAME,
     }, scope);
+    if (settled === undefined)
+        return undefined;
+    const coordinates = coordinatesFromAdmitted(authority, admitted);
+    const entries = await readLawfulSettlementEntries(coordinates.sessionFile) ?? [];
+    const officer = countersignTerminalFromEntries(entries);
+    if (officer === undefined)
+        return settled;
+    // 给事中上呈: public payloads = officer receipt; runId + receipt fact beside.
+    // This kind is produced only when beforeAccept booked the officer entry.
+    if (settled.roleOutcome.kind === "audit_escalation") {
+        return {
+            ...settled,
+            roleOutcome: withCountersignTerminalFact({
+                ...settled.roleOutcome,
+                payloads: [officer.receipt],
+            }, officer),
+        };
+    }
+    // Pass (署): keep 中书省 payloads; present 给事中 判词 + runId via decisiveFacts.
+    // Parent escalate accepted terminal must not project a stale prior pass entry.
+    if (settled.roleOutcome.kind === "accepted") {
+        if (!acceptedSecretariatDefinesOfficerProjection(settled.roleOutcome)) {
+            return settled;
+        }
+        return {
+            ...settled,
+            roleOutcome: withCountersignTerminalFact(settled.roleOutcome, officer),
+        };
+    }
+    return settled;
 }
 /** Try to settle a lawful Secretariat Terminal; undefined only for genuine absence. */
 export async function trySettleSecretariatTerminalResult(admitted, authority, scope) {

package/dist/public-role-summons.js

@@ -691,6 +691,25 @@ async function summonGateOfficer(options) {
       ...common
     });
   }
+  if (options.officer === "countersign") {
+    const { runIdFromRunDirectory } = await import("./run-terminal-artifacts.js");
+    const correlationId = runIdFromRunDirectory(options.sourceRunDirectory);
+    if (correlationId === void 0 || correlationId.trim() === "") {
+      throw new Error(
+        `countersign gate summon requires parent runId from sourceRunDirectory: ${options.sourceRunDirectory}`
+      );
+    }
+    const { readBoardTicketNumber } = await import("./run-ticket-number.js");
+    const parentTicket = await readBoardTicketNumber(options.sourceRunDirectory);
+    const instruction = options.reask ?? gateReviewInstruction ?? "";
+    return summonPublicRole({
+      role: "countersign",
+      argv: ["--project", options.cwd, "--", instruction],
+      ...common,
+      correlationId,
+      ...parentTicket === void 0 ? {} : { boundTicketNumber: parentTicket }
+    });
+  }
   return summonPublicRole({
     role: "inspector",
     argv: [`\u5377\u5B97\u6307\u9488\uFF1A${options.sourceRunDirectory}`],

package/dist/secretariat-contracts.js

@@ -1,8 +1,12 @@
 const SECRETARIAT_OUTPUT_TOOL_NAME = "ak_secretariat_output";
 const SECRETARIAT_SUMMON_COUNTERSIGN_TOOL_NAME = "ak_secretariat_summon_countersign";
 const SECRETARIAT_ACCEPTED_TEXT = "\u4E2D\u4E66\u7701\u56DE\u6267\u5DF2\u63A5\u53D7";
+const SECRETARIAT_GATE_OFFICER_ENTRY_TYPE = "ak-secretariat-gate-officer";
+const SECRETARIAT_COUNTERSIGN_TERMINAL_FACT_KEY = "countersignTerminal";
 export {
   SECRETARIAT_ACCEPTED_TEXT,
+  SECRETARIAT_COUNTERSIGN_TERMINAL_FACT_KEY,
+  SECRETARIAT_GATE_OFFICER_ENTRY_TYPE,
   SECRETARIAT_OUTPUT_TOOL_NAME,
   SECRETARIAT_SUMMON_COUNTERSIGN_TOOL_NAME
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.4631",
+  "version": "0.1.4646",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/src/archivist-record-entry.ts

@@ -479,7 +479,7 @@ export const DIRECT_OFFICER_RUN_POINTER_KIND = "direct-officer-run-pointer" as c
 export type DirectOfficerRunPointer = {
   readonly version: 1;
   readonly kind: typeof DIRECT_OFFICER_RUN_POINTER_KIND;
-  readonly officer: "inspector" | "notary" | "auditor";
+  readonly officer: "inspector" | "notary" | "auditor" | "countersign";
   /** Absolute path to the officer session.jsonl 正本. */
   readonly sessionFile: string;
   /** Officer run directory when known. */
@@ -497,7 +497,7 @@ export type DirectOfficerRunPointer = {
  */
 export function bookDirectOfficerRunPointer(options: {
   readonly parentSessionFile: string;
-  readonly officer: "inspector" | "notary" | "auditor";
+  readonly officer: "inspector" | "notary" | "auditor" | "countersign";
   readonly sessionFile: string;
   readonly runDirectory?: string;
 }): DirectOfficerRunPointer {

package/src/audit-escalation.ts

@@ -38,7 +38,7 @@ export type AuditEscalationToolResult = {
 
 export type OfficerAuditEscalationDecision = {
   readonly status: "escalate";
-  readonly officer?: "inspector" | "notary";
+  readonly officer?: "inspector" | "notary" | "countersign";
   readonly reason?: unknown;
   readonly findings?: unknown;
   readonly conflicts?: unknown;

package/src/gatekeeper-pass-envelope.ts

@@ -7,9 +7,10 @@
  *   parent submit → summon officer → read conclusion field
  *   pass → accept end
  *   bounce | escalate → raw officer receipt as tool result back to parent
+ *     — except secretariat_verdict escalate: throw → parent audit_escalation, not raw receipt (#969)
  *   not three-state → resume officer with plain-language re-ask (no round cap)
  *   transport / no_receipt → present honestly
- * Three pairs: countersign↔notary, judge↔auditor, worker↔inspector.
+ * 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.
  */
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -17,7 +18,7 @@ import { bookDirectOfficerRunPointer } from "./archivist-record-entry.ts";
 import type { HostContext, RoleTurnHost } from "./host-contracts.ts";
 import {
   GatekeeperDecisionError,
-  OFFICER_CONCLUSION_REASK,
+  officerConclusionReask,
   projectGatekeeperRun,
   type GatekeeperPassHostActions,
   type GatekeeperResult,
@@ -37,6 +38,8 @@ export function createDefaultGateOfficerSummon(options: {
   readonly home?: string;
   readonly packageRoot?: string;
   readonly roleTurnHost?: RoleTurnHost;
+  /** Composition-root adapters for nested court stations (tests / #969). */
+  readonly hostAdapters?: readonly import("./public-cli/role-turn-host-resolution.ts").NamedRoleTurnHostAdapter[];
   readonly createRunId?: () => string;
 }): GateOfficerSummon {
   return async (officer, sourceRunDirectory, signal, reask, submission) => {
@@ -51,6 +54,7 @@ export function createDefaultGateOfficerSummon(options: {
       ...(options.home === undefined ? {} : { home: options.home }),
       ...(options.packageRoot === undefined ? {} : { packageRoot: options.packageRoot }),
       ...(options.roleTurnHost === undefined ? {} : { roleTurnHost: options.roleTurnHost }),
+      ...(options.hostAdapters === undefined ? {} : { hostAdapters: options.hostAdapters }),
       ...(options.createRunId === undefined ? {} : { createRunId: options.createRunId }),
     });
   };
@@ -92,9 +96,21 @@ function bookDirectOfficerPointer(
   });
 }
 
+/**
+ * Pass snapshot returned to the parent seat (#969).
+ * Carries officer receipt + nested runId so seat settlement can project the
+ * public terminal without a second authority.
+ */
+export type GatekeeperPassOutcome = {
+  readonly officer: GateOfficer;
+  readonly receipt: unknown;
+  readonly runId?: string;
+};
+
 /**
  * Shared envelope: project gate, book officer pointer, map onto host actions.
  * Review loop has no round cap (#753 no-round-cap).
+ * On pass, returns the officer snapshot (receipt + nested runId) for seat projection.
  */
 export async function requireGatekeeperPass(options: {
   readonly context: ExtensionContext | HostContext;
@@ -109,7 +125,7 @@ export async function requireGatekeeperPass(options: {
   readonly submission?: unknown;
   /** Lowest seam: same as runGatekeeper options.summonOfficer — offline tracers only. */
   readonly summonOfficer?: GateOfficerSummon;
-}): Promise<void> {
+}): Promise<GatekeeperPassOutcome | void> {
   let reask: string | undefined;
   // No round cap — end only on pass, bounce/escalate-to-parent, or real failure.
   const summonOfficer =
@@ -140,9 +156,17 @@ export async function requireGatekeeperPass(options: {
         options.hostActions.failInfrastructure(error, options.context, options.toolCallId);
       }
     }
-    if (gatekeeper.status === "pass") return;
+    if (gatekeeper.status === "pass") {
+      return {
+        officer: projected.officer,
+        receipt: gatekeeper.receipt,
+        ...(typeof gatekeeper.runId === "string" && gatekeeper.runId.trim() !== ""
+          ? { runId: gatekeeper.runId }
+          : {}),
+      };
+    }
     if (gatekeeper.status === "needs_reask") {
-      reask = OFFICER_CONCLUSION_REASK;
+      reask = officerConclusionReask(projected.officer);
       continue;
     }
     if (gatekeeper.status === "transport_failure") {
@@ -152,6 +176,14 @@ export async function requireGatekeeperPass(options: {
       });
       options.hostActions.failInfrastructure(failure, options.context, options.toolCallId);
     }
+    // #969: 给事中上呈 ends the secretariat parent — no bind/retry (不回中书省擅改).
+    // Parent beforeAccept converts this into audit_escalation with the officer receipt.
+    if (
+      gatekeeper.status === "escalate"
+      && options.subject.kind === "secretariat_verdict"
+    ) {
+      throw new GatekeeperDecisionError(gatekeeper);
+    }
     // bounce | escalate | no_receipt: parent stands and may resubmit. Not a run abort.
     options.hostActions.bindSubmissionNonPass(options.toolCallId, gatekeeper);
     throw new GatekeeperDecisionError(gatekeeper);

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,