@akagilnc/pi-workflow-roles 0.1.4620 → 0.1.4641

package/src/activation-ledger.ts

@@ -1,25 +1,8 @@
-import {
-  constants,
-  closeSync,
-  fstatSync,
-  openSync,
-  writeSync,
-} from "node:fs";
-import { dirname, isAbsolute, resolve } from "node:path";
-
-import type { ActivationSessionPointer } from "./activation-ledger-session.ts";
-import {
-  ActivationLedgerError,
-  activationWaitingLedgerPath,
-  assertLedgerFileInsideHome,
-  ensureRealDirectoryTree,
-  errorText,
-} from "./activation-ledger-topology.ts";
-
-/** Private open flags: O_NOFOLLOW closes the lstat→open TOCTOU window. */
-const ACTIVATION_LEDGER_APPEND_OPEN_FLAGS =
-  constants.O_APPEND | constants.O_CREAT | constants.O_WRONLY | constants.O_NOFOLLOW;
-
+/**
+ * Activation ledger surface: durable session principal + book/home topology.
+ * #855: two-face waiting.jsonl reconciliation deleted — this module no longer
+ * appends accepted-activation facts or own a waiting path.
+ */
 export {
   ActivationGitRepositoryRequiredError,
   resolveBookKeyFromGit,
@@ -33,219 +16,5 @@ export {
 export {
   ActivationLedgerError,
   activationBookDirectory,
-  activationWaitingLedgerPath,
   resolveActivationLedgerHome,
 } from "./activation-ledger-topology.ts";
-
-/** Caller-preassigned correlation id, or an explicit absent identity (never empty string). */
-export type ActivationCorrelationIdentity =
-  | { readonly kind: "caller"; readonly id: string }
-  | { readonly kind: "absent" };
-
-export const ACCEPTED_ACTIVATION_EVENT = "accepted-activation" as const;
-
-/**
- * Package-owned index-only top-level keys for accepted-activation facts (ADR 0049).
- * Sole machine key contract: projection and tests consume this descriptor — not prose markers.
- */
-export const ACCEPTED_ACTIVATION_FACT_KEYS = Object.freeze([
-  "event",
-  "role",
-  "observedAt",
-  "bookKey",
-  "session",
-  "correlation",
-] as const);
-
-export type AcceptedActivationFactKey = (typeof ACCEPTED_ACTIVATION_FACT_KEYS)[number];
-
-/**
- * Closed activation fact: index fields only (ADR 0049).
- * No prompt, transcript, argv, excerpt, or other content.
- */
-export type AcceptedActivationFact = {
-  readonly event: typeof ACCEPTED_ACTIVATION_EVENT;
-  readonly role: string;
-  readonly observedAt: string;
-  readonly bookKey: string;
-  readonly session: ActivationSessionPointer;
-  readonly correlation: ActivationCorrelationIdentity;
-};
-
-// Keys tuple ↔ fact type must stay exact (compile fail on drift; no second field list).
-type ExactKeyMatch<T, K extends PropertyKey> =
-  Exclude<keyof T, K> | Exclude<K, keyof T> extends never ? true : never;
-const _acceptedActivationFactKeysMatch: ExactKeyMatch<
-  AcceptedActivationFact,
-  AcceptedActivationFactKey
-> = true;
-void _acceptedActivationFactKeysMatch;
-
-/** Trusted typed inputs for building the closed fact (canonical fact minus event discriminant). */
-export type AcceptedActivationFactInput = Omit<AcceptedActivationFact, "event">;
-
-/**
- * Host correlation channel (not a CLI flag): a non-blank AK_CORRELATION_ID carries
- * the caller id verbatim; missing/blank/whitespace-only yields the typed absent identity.
- */
-export function correlationIdentityFromEnv(
-  env: NodeJS.ProcessEnv = process.env,
-): ActivationCorrelationIdentity {
-  const raw = env.AK_CORRELATION_ID;
-  if (typeof raw === "string" && raw.trim().length > 0) {
-    return { kind: "caller", id: raw };
-  }
-  return { kind: "absent" };
-}
-
-/**
- * Descriptor-driven top-level pick: only ACCEPTED_ACTIVATION_FACT_KEYS leave this boundary.
- * Nested session/correlation are rebuilt closed before the pick (ADR 0049: first-phase ledger holds zero content bytes by construction).
- */
-function projectAcceptedActivationFact(
-  input: AcceptedActivationFactInput,
-): AcceptedActivationFact {
-  const closed: AcceptedActivationFact = {
-    event: ACCEPTED_ACTIVATION_EVENT,
-    role: input.role,
-    observedAt: input.observedAt,
-    bookKey: input.bookKey,
-    session: { kind: "session-file", path: input.session.path },
-    correlation: input.correlation.kind === "caller"
-      ? { kind: "caller", id: input.correlation.id }
-      : { kind: "absent" },
-  };
-  // Descriptor is the sole top-level emission contract (typed pick; no content keys).
-  return Object.fromEntries(
-    ACCEPTED_ACTIVATION_FACT_KEYS.map((key) => [key, closed[key]]),
-  ) as AcceptedActivationFact;
-}
-
-/** Construct the closed fact from trusted typed inputs only (descriptor projection — no content keys). */
-export function buildAcceptedActivationFact(input: AcceptedActivationFactInput): AcceptedActivationFact {
-  return projectAcceptedActivationFact(input);
-}
-
-/** Serialize only the closed index fields (descriptor projection — no content keys). */
-export function serializeAcceptedActivationFact(fact: AcceptedActivationFact): string {
-  return `${JSON.stringify(projectAcceptedActivationFact(fact))}\n`;
-}
-
-/**
- * Bare O_APPEND write of one complete line under an absolute ledger home.
- * Private helper: production-bound to writeSync; owns open/write/close honesty only.
- * Close failure cannot mask open/write; simultaneous close is nested evidence.
- */
-function appendActivationLedgerLine(
-  ledgerPath: string,
-  line: Uint8Array,
-  options: { ledgerHome: string },
-): void {
-  if (!isAbsolute(options.ledgerHome)) {
-    throw new ActivationLedgerError(
-      `activation ledger home must be absolute: ${options.ledgerHome}`,
-    );
-  }
-  const resolvedLedger = resolve(ledgerPath);
-  const resolvedHome = resolve(options.ledgerHome);
-  const parent = dirname(resolvedLedger);
-  ensureRealDirectoryTree(resolvedHome, parent);
-  assertLedgerFileInsideHome(resolvedLedger, resolvedHome);
-
-  // Fail-closed guard (same shape as PR #418's publication seam): on platforms
-  // without O_NOFOLLOW (e.g. Windows, nodejs/node#41590) the JS bitwise-or in
-  // ACTIVATION_LEDGER_APPEND_OPEN_FLAGS would silently drop the flag and the
-  // lstat→open TOCTOU anti-symlink protection would vanish while the comment
-  // above still claims it. Refuse loudly via the existing typed ledger failure
-  // channel instead of appending unprotected; never silently degrade.
-  if (typeof constants.O_NOFOLLOW !== "number") {
-    throw new ActivationLedgerError(
-      "activation ledger append requires O_NOFOLLOW open-flag support (anti-symlink TOCTOU protection must not be silently dropped); refusing to append",
-    );
-  }
-  const bytes = Buffer.isBuffer(line) ? line : Buffer.from(line);
-  let ledgerFd: number | undefined;
-  let primaryFailure: unknown;
-  try {
-    try {
-      ledgerFd = openSync(resolvedLedger, ACTIVATION_LEDGER_APPEND_OPEN_FLAGS, 0o644);
-    } catch (error) {
-      // Native ELOOP/filesystem cause retained; no errno dispatch.
-      throw new ActivationLedgerError(
-        `activation ledger failed to open ledger file (${resolvedLedger}): ${errorText(error)}`,
-        { cause: error },
-      );
-    }
-
-    let opened: ReturnType<typeof fstatSync>;
-    try {
-      opened = fstatSync(ledgerFd);
-    } catch (error) {
-      throw new ActivationLedgerError(
-        `activation ledger failed to fstat ledger file (${resolvedLedger}): ${errorText(error)}`,
-        { cause: error },
-      );
-    }
-    if (!opened.isFile()) {
-      throw new ActivationLedgerError(
-        `activation ledger is not a regular file: ${resolvedLedger}`,
-      );
-    }
-
-    const written = writeSync(ledgerFd, bytes, 0, bytes.length, null);
-    if (written !== bytes.length) {
-      throw new ActivationLedgerError(
-        `activation ledger short write: wrote ${written} of ${bytes.length} bytes to ${resolvedLedger}`,
-      );
-    }
-  } catch (error) {
-    primaryFailure = error;
-  }
-
-  if (ledgerFd !== undefined) {
-    try {
-      closeSync(ledgerFd);
-    } catch (closeFailure) {
-      if (primaryFailure !== undefined) {
-        throw new AggregateError(
-          [primaryFailure, closeFailure],
-          "activation ledger operation and close failed",
-          { cause: primaryFailure },
-        );
-      }
-      throw closeFailure;
-    }
-  }
-
-  if (primaryFailure !== undefined) throw primaryFailure;
-}
-
-/**
- * Append one complete JSONL record with one O_APPEND write of the full record.
- * Shared-ledger contract: concurrent successful append-only producers cannot
- * overwrite one another. A short write is an honest infrastructure failure
- * (ADR 0049) — no non-append rollback/truncate. Close failure cannot mask the
- * primary write cause; simultaneous close evidence is retained.
- */
-export function appendAcceptedActivationFact(
-  ledgerPath: string,
-  fact: AcceptedActivationFact,
-  options: { ledgerHome: string },
-): void {
-  appendActivationLedgerLine(
-    ledgerPath,
-    Buffer.from(serializeAcceptedActivationFact(fact), "utf8"),
-    { ledgerHome: options.ledgerHome },
-  );
-}
-
-export function appendAcceptedActivationToBook(options: {
-  ledgerHome: string;
-  fact: AcceptedActivationFact;
-}): void {
-  appendAcceptedActivationFact(
-    activationWaitingLedgerPath(options.ledgerHome, options.fact.bookKey),
-    options.fact,
-    { ledgerHome: options.ledgerHome },
-  );
-}

package/src/analyst-entry.ts

@@ -22,9 +22,12 @@ import {
 } from "./analyst-cohort.ts";
 import {
   scanAnalystIssueRuns,
+  type AnalystGhostLeg,
   type AnalystReadableRunFacts,
   type AnalystScopedRunScan,
 } from "./analyst-ledger.ts";
+
+export type { AnalystGhostLeg, AnalystGhostLeaseCheck } from "./analyst-ledger.ts";
 import {
   mergeAnalystLibraryIndexRows,
   rowFromIssueMetricsPage,
@@ -173,6 +176,11 @@ export type AnalystIssueModeResult = {
   readonly mode: "issue";
   readonly page: AnalystIssueMetricsPage;
   readonly pagePath: string;
+  /**
+   * #855 live observation: admitted|running runs whose writer lease cannot prove
+   * a live holder. Fresh each query — never cached on the metrics page.
+   */
+  readonly ghostLegs: readonly AnalystGhostLeg[];
 };
 
 export type AnalystSweepModeResult = {
@@ -264,7 +272,16 @@ export async function readOrComputeAnalystIssuePage(
     const raw = await readFile(pagePath, "utf8");
     const page = JSON.parse(raw) as AnalystIssueMetricsPage;
     if (cachedPageMatchesRequestedScope(page, { bookKey, ...input })) {
-      return { mode: "issue", page, pagePath };
+      // #855 ghost legs are live observations — always fresh, never from the page cache.
+      const ghostScan = await scanAnalystIssueRuns({
+        bookKey,
+        ...(issueNumber === undefined ? {} : { ticketNumber: issueNumber }),
+        ...(options?.scanProjectRoot === undefined
+          ? {}
+          : { projectRoot: options.scanProjectRoot }),
+        ...(options?.home === undefined ? {} : { home: options.home }),
+      });
+      return { mode: "issue", page, pagePath, ghostLegs: ghostScan.ghostLegs };
     }
     // Existing page is for a different / absent ticket scope — same kernel recompute.
   } catch (error) {
@@ -364,7 +381,7 @@ async function runAnalystIssueMode(
     ]);
   }
 
-  return { mode: "issue", page, pagePath };
+  return { mode: "issue", page, pagePath, ghostLegs: scan.ghostLegs };
 }
 
 async function runAnalystSweepMode(

package/src/analyst-ledger.ts

@@ -22,6 +22,7 @@ import {
   resolveActivationLedgerHome,
 } from "./activation-ledger-topology.ts";
 import { listBookRunDirectories } from "./role-run-placement.ts";
+import { autopsyWriterLock } from "./public-cli/run-lifecycle.ts";
 import { readRunTicketNumber } from "./run-ticket-number.ts";
 import {
   extractSessionModelSequence,
@@ -87,6 +88,64 @@ async function readExistingRunLifecycleState(
   }
 }
 
+/**
+ * #855 lease check projection for ghost legs — index facts only (ADR 0049).
+ * Does not rename autopsy verdicts into stronger claims than observed.
+ */
+export type AnalystGhostLeaseCheck =
+  | { readonly kind: "holder-dead"; readonly pid: number }
+  | { readonly kind: "no-lease" }
+  | { readonly kind: "unverifiable"; readonly reason: "unreadable" | "unparseable" };
+
+export type AnalystGhostLeg = {
+  readonly runId: string;
+  readonly runState: "admitted" | "running";
+  readonly leaseCheck: AnalystGhostLeaseCheck;
+};
+
+function ghostLeaseCheckFromAutopsy(
+  autopsy: Awaited<ReturnType<typeof autopsyWriterLock>>,
+): AnalystGhostLeaseCheck | undefined {
+  switch (autopsy.verdict) {
+    case "alive":
+      return undefined;
+    case "dead":
+      return { kind: "holder-dead", pid: autopsy.pid };
+    case "absent":
+      return { kind: "no-lease" };
+    case "unknown":
+      return {
+        kind: "unverifiable",
+        reason: autopsy.reason === "unreadable" ? "unreadable" : "unparseable",
+      };
+  }
+}
+
+/**
+ * Classify one admitted|running run against writer lease liveness (#855).
+ * Alive holder → still in-flight (omit). Otherwise → ghost report fact only.
+ */
+async function classifyGhostCandidate(input: {
+  readonly runId: string;
+  readonly runState: "admitted" | "running";
+  readonly runDirectory: string;
+}): Promise<
+  | { readonly kind: "live" }
+  | { readonly kind: "ghost"; readonly leg: AnalystGhostLeg }
+> {
+  const autopsy = await autopsyWriterLock(join(input.runDirectory, "writer.lock"));
+  const leaseCheck = ghostLeaseCheckFromAutopsy(autopsy);
+  if (leaseCheck === undefined) return { kind: "live" };
+  return {
+    kind: "ghost",
+    leg: {
+      runId: input.runId,
+      runState: input.runState,
+      leaseCheck,
+    },
+  };
+}
+
 function parseRunDirectoryName(
   name: string,
 ): { runId: string; role: string } | undefined {
@@ -335,6 +394,8 @@ export type AnalystScopedRunScan = {
   readonly unreadable: readonly AnalystUnreadableRun[];
   /** C4: typed-ticket admits whose projectRoot mechanical key conflicted. */
   readonly scopeConflicts: readonly AnalystScopeConflict[];
+  /** #855: admitted|running runs whose writer lease cannot prove a live holder. */
+  readonly ghostLegs: readonly AnalystGhostLeg[];
 };
 
 async function classifyScopedRun(input: {
@@ -343,9 +404,20 @@ async function classifyScopedRun(input: {
   readonly role: string;
   readonly runDirectory: string;
 }): Promise<
-  | { readonly kind: "readable"; readonly facts: AnalystReadableRunFacts }
-  | { readonly kind: "unreadable"; readonly entry: AnalystUnreadableRun }
+  | {
+      readonly kind: "readable";
+      readonly facts: AnalystReadableRunFacts;
+      /** #855: present terminal still lists ghost when lease cannot prove live. */
+      readonly ghostLeg?: AnalystGhostLeg;
+    }
+  | {
+      readonly kind: "unreadable";
+      readonly entry: AnalystUnreadableRun;
+      /** #855: unreadable terminal still lists ghost when lease cannot prove live. */
+      readonly ghostLeg?: AnalystGhostLeg;
+    }
   | { readonly kind: "live" }
+  | { readonly kind: "ghost"; readonly leg: AnalystGhostLeg }
 > {
   const missingSources: AnalystMissingSource[] = [];
   const reasons: string[] = [];
@@ -434,13 +506,31 @@ async function classifyScopedRun(input: {
 
   // 3) typed terminal artifact — absence is no-receipt only for terminal runs.
   // Live admitted/running/resumable runs (existing run-state) are not dead legs.
+  // #855: writer-lease ghost check is independent of terminal artifact status.
+  // present → still emit metrics; unreadable → still enter missingSources;
+  // admitted|running + non-live lease → still list in ghostLegs (ticket #4).
+  const lifecycle = await readExistingRunLifecycleState(input.runDirectory);
+  let ghostLeg: AnalystGhostLeg | undefined;
+  if (lifecycle === "admitted" || lifecycle === "running") {
+    const ghost = await classifyGhostCandidate({
+      runId: input.runId,
+      runState: lifecycle,
+      runDirectory: input.runDirectory,
+    });
+    if (ghost.kind === "ghost") ghostLeg = ghost.leg;
+  }
+
   try {
     const artifact = await readRunTerminalArtifact(input.runDirectory);
     if (artifact.status === "unreadable") {
       missingSources.push("terminal-artifact");
       reasons.push(`${artifact.file}: ${artifact.reason}`);
     } else if (artifact.status === "absent") {
-      const lifecycle = await readExistingRunLifecycleState(input.runDirectory);
+      if (lifecycle === "admitted" || lifecycle === "running") {
+        // No terminal yet: ghost report only, or live in-flight omit.
+        if (ghostLeg !== undefined) return { kind: "ghost", leg: ghostLeg };
+        return { kind: "live" };
+      }
       if (lifecycle !== undefined && LIVE_RUN_STATES.has(lifecycle)) {
         return { kind: "live" };
       }
@@ -479,6 +569,7 @@ async function classifyScopedRun(input: {
         firstFrameAt,
         lastFrameAt,
       },
+      ...(ghostLeg !== undefined ? { ghostLeg } : {}),
     };
   }
 
@@ -510,6 +601,7 @@ async function classifyScopedRun(input: {
         firstFrameAt: { status: "present", at: frameSpan.startedAt },
         lastFrameAt: { status: "present", at: frameSpan.endedAt },
       },
+      ...(ghostLeg !== undefined ? { ghostLeg } : {}),
     };
   }
 
@@ -525,6 +617,7 @@ async function classifyScopedRun(input: {
       models,
       gateCycles,
     },
+    ...(ghostLeg !== undefined ? { ghostLeg } : {}),
   };
 }
 
@@ -588,11 +681,12 @@ export async function scanAnalystIssueRuns(input: {
   }
 
   if (bookNames.length === 0) {
-    return { runs: [], unreadable: [], scopeConflicts: [] };
+    return { runs: [], unreadable: [], scopeConflicts: [], ghostLegs: [] };
   }
 
   const runs: AnalystReadableRunFacts[] = [];
   const unreadable: AnalystUnreadableRun[] = [];
+  const ghostLegs: AnalystGhostLeg[] = [];
   // scopeConflicts retained on the scan face for page envelope compat; book×ticket
   // scope no longer emits projectRoot dual-key conflicts on the CLI path.
   const scopeConflicts: AnalystScopeConflict[] = [];
@@ -638,9 +732,19 @@ export async function scanAnalystIssueRuns(input: {
         role: parsed.role,
         runDirectory,
       });
-      if (classified.kind === "readable") runs.push(classified.facts);
-      else if (classified.kind === "unreadable") unreadable.push(classified.entry);
+      if (classified.kind === "readable") {
+        runs.push(classified.facts);
+        if (classified.ghostLeg !== undefined) ghostLegs.push(classified.ghostLeg);
+      } else if (classified.kind === "unreadable") {
+        unreadable.push(classified.entry);
+        if (classified.ghostLeg !== undefined) ghostLegs.push(classified.ghostLeg);
+      } else if (classified.kind === "ghost") {
+        ghostLegs.push(classified.leg);
+      }
       // live in-flight runs are omitted from legs and unreadable (not failure/death).
+      // #855 ghost legs are reported separately — not counted as in-flight.
+      // Lease check is independent of terminal artifact: present/unreadable may
+      // still carry a ghostLeg alongside metrics or missingSources.
     }
   }
 
@@ -648,5 +752,6 @@ export async function scanAnalystIssueRuns(input: {
     runs,
     unreadable,
     scopeConflicts,
+    ghostLegs,
   };
 }

package/src/archivist-record-entry.ts

@@ -1,7 +1,7 @@
 /**
  * 司天台唯一 Pi session 记录落盘入口（ADR 0065）。
  * 调用方只声明自己是谁的什么；落点由候簿拓扑算出，签名不含任何落点/路径参数。
- * 「谁调了谁」复用 Pi parentSession + ADR 0047 correlation，不新增 caller 字段。
+ * 「谁调了谁」复用 Pi parentSession，不新增 caller 字段（#855 两面对账 correlation 键已删）。
  */
 import {
   closeSync,
@@ -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);