@akagilnc/pi-workflow-roles 0.1.4620 → 0.1.4641

package/src/role-runtime.ts

@@ -17,20 +17,10 @@ import { createSubmissionLedgerHost, sealAcceptedSubmission } from "./submission
 import { createCollectorLedger } from "./collector-ledger.ts";
 
 import { activationTraceRecordSchema, namedActivationCause, type ActivationTraceRecord, type ActivationTraceWriter } from "./activation-trace.ts";
+import { homeFromRunDirectory } from "./activation-ledger-topology.ts";
 import {
-  homeFromRunDirectory,
-  resolveActivationLedgerHomeForPath,
-} from "./activation-ledger-topology.ts";
-import {
-  appendAcceptedActivationToBook,
-  buildAcceptedActivationFact,
-  correlationIdentityFromEnv,
   durableSessionPointer,
-  resolveActivationLedgerHome,
   resolveBookKeyFromGit,
-  type AcceptedActivationFact,
-  type ActivationCorrelationIdentity,
-  type ActivationSessionPointer,
 } from "./activation-ledger.ts";
 import { writeStderrJsonlRecord } from "./stderr-jsonl.ts";
 import {
@@ -301,43 +291,18 @@ export {
 export { activationTraceRecordSchema, namedActivationCause } from "./activation-trace.ts";
 export type { ActivationTraceRecord, ActivationTraceWriter } from "./activation-trace.ts";
 export {
-  ACCEPTED_ACTIVATION_EVENT,
-  ACCEPTED_ACTIVATION_FACT_KEYS,
   ActivationGitRepositoryRequiredError,
   ActivationLedgerError,
   ActivationSessionFileMissingError,
   activationBookDirectory,
-  activationWaitingLedgerPath,
-  appendAcceptedActivationFact,
-  appendAcceptedActivationToBook,
-  buildAcceptedActivationFact,
-  correlationIdentityFromEnv,
   durableSessionPointer,
   resolveActivationLedgerHome,
   resolveBookKeyFromGit,
-  serializeAcceptedActivationFact,
 } from "./activation-ledger.ts";
 export type {
-  AcceptedActivationFact,
-  AcceptedActivationFactInput,
-  AcceptedActivationFactKey,
-  ActivationCorrelationIdentity,
   ActivationSessionManager,
   ActivationSessionPointer,
 } from "./activation-ledger.ts";
-export {
-  DISPATCH_STUB_EVENT,
-  buildDispatchStubFact,
-  reconcileInvocation,
-} from "./activation-reconciliation.ts";
-export type {
-  DispatchPointer,
-  DispatchStubFact,
-  DispatchStubFactInput,
-  ProcessLivenessFact,
-  ReconciliationOutcome,
-  ReconciliationSubject,
-} from "./activation-reconciliation.ts";
 export {
   TOOL_EXECUTION_UPDATE_HEARTBEAT,
   TOOL_EXECUTION_UPDATE_THROTTLE_MS,
@@ -349,15 +314,23 @@ export {
   writeToolExecutionObservationRecord,
 } from "./tool-execution-observation.ts";
 export type { ToolExecutionObservationRecord, ToolExecutionObservationWriter } from "./tool-execution-observation.ts";
-export {
+import {
   NOTARY_OUTPUT_TOOL,
   INSPECTOR_OUTPUT_TOOL,
   GatekeeperDecisionError,
   createGatekeeperOutputTool,
   runGatekeeper,
+  gateOfficerForSubject,
 } from "./gatekeeper-role.ts";
+export {
+  NOTARY_OUTPUT_TOOL,
+  INSPECTOR_OUTPUT_TOOL,
+  GatekeeperDecisionError,
+  createGatekeeperOutputTool,
+  runGatekeeper,
+  gateOfficerForSubject,
+};
 export type { GatekeeperResult, GatekeeperSubject, GatekeeperNonPassResult, GateOfficer, RunGatekeeperOptions } from "./gatekeeper-role.ts";
-export { gateOfficerForSubject } from "./gatekeeper-role.ts";
 import { ParentQueueReaskError } from "./submission-errors.ts";
 
 export {
@@ -581,6 +554,13 @@ type NavigatorAttendanceDependency = Omit<NavigatorAttendance, "knownRoutePlaybo
 export type RoleRuntimeDependencies = {
   /** Package root for packaged engine-note resolution (#879). */
   packageRoot?: string;
+  /**
+   * Composition-root adapter table for nested gate officer summons (#969).
+   * Production leaves unset (default pi + packaged externals). Tests inject
+   * faux nested hosts so prepareRoleEnvelope.requireGatekeeperPass is bitten
+   * without reimplementing the envelope summon closure.
+   */
+  hostAdapters?: readonly import("./public-cli/role-turn-host-resolution.ts").NamedRoleTurnHostAdapter[];
   /** Non-identity opening materials delivered in the ordinary role brief. */
   loadRoleReferenceMaterials?(role: PackagedRole): Promise<string>;
   loadJudgeSoul(): Promise<string>;
@@ -1034,18 +1014,137 @@ const COUNTERSIGN_QUEUE_STATUSES = new Set(["converged", "continue", "escalate"]
 const COUNTERSIGN_STATUS_REASK =
   "countersignStatus 不是 converged、continue、escalate 三态之一。请重新交卷，status 写明其一。" as const;
 
+/**
+ * #969 authorized non-pi hosts: Secretariat converged is a candidate ticket —
+ * AK-side submission gate summons 给事中. pi keeps mid-turn summon tool only.
+ */
+const SECRETARIAT_SUBMISSION_GATE_HOSTS = new Set(["codex", "claude", "grok-build"]);
+
+/** Secretariat status words the non-pi submission gate reads (#969). */
+const SECRETARIAT_QUEUE_STATUSES = new Set(["converged", "escalate"]);
+
+/**
+ * Plain-language re-ask when non-pi secretariatStatus is not a known queue word.
+ * Back to secretariat itself — 给事中 is not summoned (#969 / ADR 0055).
+ */
+const SECRETARIAT_STATUS_REASK =
+  "secretariatStatus 不是 converged、escalate 之一。请重新交卷，status 写明其一。" as const;
+
 /**
  * #924 Secretariat on the shared filed-officer envelope + non-terminating
  * summon-countersign tool (auditor dossier extension pattern).
  * Nested countersign lifecycle stays on summonPublicRole (ADR 0018).
- * #924 / 第 0 条: output tool records the receipt as submitted — no status
+ * #924 / 第 0 条 (pi): output tool records the receipt as submitted — no status
  * shape/value reject or reask; legality is content-layer / downstream.
+ * #969 (codex/claude/grok-build): converged arms 既有交卷闸 → 给事中; escalate
+ * skips the gate; other values reask secretariat (ADR 0055).
  */
 export function createSecretariatRoleRuntime(
   roleHost: RoleHost,
   dependencies: SecretariatRuntimeDependencies,
+  hostActions?: import("./host-contracts.ts").HostGatekeeperActions,
 ) {
   let parentInstruction = "";
+  // #969: non-pi submission gate only — pi mid-turn summon path stays untouched.
+  const beforeAccept: FiledOfficerBeforeAccept | undefined =
+    hostActions !== undefined && roleHost.requireGatekeeperPass !== undefined
+      ? async ({ toolCallId, parameters, signal, ctx }) => {
+          const host =
+            typeof ctx.host === "string" && ctx.host.trim() !== ""
+              ? ctx.host.trim()
+              : undefined;
+          if (host === undefined || !SECRETARIAT_SUBMISSION_GATE_HOSTS.has(host)) {
+            return undefined;
+          }
+          const record =
+            parameters !== null && typeof parameters === "object" && !Array.isArray(parameters)
+              ? (parameters as Record<string, unknown>)
+              : undefined;
+          const status =
+            record !== undefined && typeof record.secretariatStatus === "string"
+              ? record.secretariatStatus
+              : undefined;
+          if (status === undefined || !SECRETARIAT_QUEUE_STATUSES.has(status)) {
+            throw new ParentQueueReaskError(SECRETARIAT_STATUS_REASK);
+          }
+          if (status === "escalate") {
+            // Parent escalate → throw to caller as-is; 给事中 does not attend (#969).
+            return undefined;
+          }
+          try {
+            const pass = await roleHost.requireGatekeeperPass!({
+              context: ctx,
+              subject: { kind: "secretariat_verdict" },
+              ...(signal === undefined ? {} : { signal }),
+              hostActions,
+              toolCallId,
+              // #879: this-turn typed payload — identity-bound at submit site.
+              submission: parameters,
+            });
+            // #969: book 给事中 署 snapshot for seat settlement projection (receipt + runId).
+            // Ledger accepted stays LLM params (#836); public terminal reads this entry.
+            if (
+              pass !== undefined
+              && pass !== null
+              && typeof pass === "object"
+              && "receipt" in pass
+            ) {
+              const {
+                SECRETARIAT_GATE_OFFICER_ENTRY_TYPE,
+              } = await import("./secretariat-contracts.ts");
+              const runId =
+                typeof pass.runId === "string" && pass.runId.trim() !== ""
+                  ? pass.runId
+                  : undefined;
+              ctx.sessionManager.appendCustomEntry?.(SECRETARIAT_GATE_OFFICER_ENTRY_TYPE, {
+                officer: "countersign",
+                receipt: pass.receipt,
+                ...(runId === undefined ? {} : { runId }),
+              });
+            }
+            return undefined;
+          } catch (error) {
+            // #969: 给事中上呈 ends parent with officer receipt (no retry / 不擅改).
+            if (
+              error instanceof GatekeeperDecisionError
+              && error.result.status === "escalate"
+            ) {
+              const receipt = error.result.receipt;
+              const receiptRecord =
+                receipt !== null && typeof receipt === "object" && !Array.isArray(receipt)
+                  ? (receipt as Record<string, unknown>)
+                  : undefined;
+              const runId =
+                typeof error.result.runId === "string" && error.result.runId.trim() !== ""
+                  ? error.result.runId
+                  : undefined;
+              // Durable on every host: envelope persists custom entries only
+              // (toolResult rows are memory-only on headless/ACP — #617/#959).
+              const {
+                SECRETARIAT_GATE_OFFICER_ENTRY_TYPE,
+              } = await import("./secretariat-contracts.ts");
+              ctx.sessionManager.appendCustomEntry?.(SECRETARIAT_GATE_OFFICER_ENTRY_TYPE, {
+                officer: "countersign",
+                receipt,
+                ...(runId === undefined ? {} : { runId }),
+              });
+              const { buildAuditEscalationResult } = await import("./audit-escalation.ts");
+              return buildAuditEscalationResult(
+                {
+                  status: "escalate",
+                  officer: "countersign",
+                  ...(receiptRecord !== undefined
+                    && Object.prototype.hasOwnProperty.call(receiptRecord, "decisionGate")
+                    ? { decisionGate: receiptRecord.decisionGate }
+                    : {}),
+                },
+                receipt,
+              );
+            }
+            throw error;
+          }
+        }
+      : undefined;
   const base = createFiledOfficerRuntime(
     roleHost,
     {
@@ -1053,6 +1152,7 @@ export function createSecretariatRoleRuntime(
       tool: SECRETARIAT_OUTPUT_TOOL_SPEC,
       acceptedText: SECRETARIAT_ACCEPTED_TEXT,
       soulTag: "secretariat",
+      ...(beforeAccept === undefined ? {} : { beforeAccept }),
     },
     dependencies,
   );
@@ -1893,7 +1993,10 @@ export function createRoleRuntimeExtension(
       ...(dependencies.packageRoot === undefined
         ? {}
         : { packageRoot: dependencies.packageRoot }),
-    });
+      ...(dependencies.hostAdapters === undefined
+        ? {}
+        : { hostAdapters: dependencies.hostAdapters }),
+    }, hostActions);
     const merger = createMergerRoleRuntime(roleHost, {
       async loadSoul() { if (!dependencies.loadMergerSoul) throw new Error("Merger runtime dependencies are not configured"); return dependencies.loadMergerSoul(); },
       async loadInput(path) { if (!dependencies.loadMergerInput) throw new Error("Merger runtime dependencies are not configured"); return dependencies.loadMergerInput(path); },
@@ -2195,11 +2298,9 @@ export function createRoleRuntimeExtension(
         // Production topology only (ADR 0048/0049): no test-only ledger hooks.
         // Admit durable session file first so lifecycle getEntries/appendEntry are truthful:
         // deferred SM materialization must not wipe an in-memory principal marker.
-        const bookKey = resolveBookKeyFromGit(ctx.cwd);
-        const correlation = correlationIdentityFromEnv();
-        const sessionFile = ctx.sessionManager.getSessionFile?.() || ctx.sessionManager.getSessionDir?.();
-        const ledgerHome = resolveActivationLedgerHomeForPath(sessionFile);
-        const session = durableSessionPointer(ctx.sessionManager);
+        // #855: two-face waiting.jsonl write removed — fail-closed book-key + session only.
+        resolveBookKeyFromGit(ctx.cwd);
+        durableSessionPointer(ctx.sessionManager);
 
         // Station children (court diarist, inner-gate summons) omit navigator sidecar (#840).
         // Top-level public entry legs still attend automatically.
@@ -2314,16 +2415,6 @@ export function createRoleRuntimeExtension(
           if (entry.role === "coder") coder.armSubmissionGate(ctx.cwd, ctx.sessionManager);
           else fixer.armSubmissionGate(ctx.cwd, ctx.sessionManager);
         }
-        appendAcceptedActivationToBook({
-          ledgerHome,
-          fact: buildAcceptedActivationFact({
-            role: entry.role,
-            observedAt: clock(),
-            bookKey,
-            session,
-            correlation,
-          }),
-        });
         admitted = true;
       } catch (error) {
         failInfrastructure(error, ctx);

package/src/secretariat-contracts.ts

@@ -11,6 +11,24 @@ export const SECRETARIAT_OUTPUT_TOOL_NAME = "ak_secretariat_output";
 export const SECRETARIAT_SUMMON_COUNTERSIGN_TOOL_NAME =
   "ak_secretariat_summon_countersign";
 export const SECRETARIAT_ACCEPTED_TEXT = "中书省回执已接受";
+/**
+ * #969 durable custom entry: 给事中 terminal (署|上呈) for seat settlement projection.
+ * Carries original receipt bytes + nested runId. Envelope persists custom entries
+ * (not toolResult rows) — headless/ACP safe. Single authority for public terminal
+ * officer projection (pass and escalate share this entry).
+ */
+export const SECRETARIAT_GATE_OFFICER_ENTRY_TYPE =
+  "ak-secretariat-gate-officer" as const;
+
+/** Decisive-facts key for nested 给事中 terminal on public Secretariat settlement. */
+export const SECRETARIAT_COUNTERSIGN_TERMINAL_FACT_KEY = "countersignTerminal" as const;
+
+export type SecretariatCountersignTerminalFact = {
+  /** Officer receipt original bytes — never rewritten. */
+  readonly receipt: unknown;
+  /** Nested 给事中 runId when known. */
+  readonly runId?: string;
+};
 
 export type SecretariatVerdict =
   | {

package/dist/activation-reconciliation.js

@@ -1,61 +0,0 @@
-const DISPATCH_STUB_EVENT = "dispatch-stub";
-function buildDispatchStubFact(input) {
-  return {
-    event: DISPATCH_STUB_EVENT,
-    observedAt: input.observedAt,
-    bookKey: input.bookKey,
-    dispatch: input.dispatch.kind === "process" ? { kind: "process", pid: input.dispatch.pid } : { kind: "opaque", ref: input.dispatch.ref },
-    correlation: { kind: "caller", id: input.correlation.id }
-  };
-}
-function callerCorrelationId(correlation) {
-  return correlation.kind === "caller" ? correlation.id : void 0;
-}
-function dispatchMatchesActivation(dispatch, activation) {
-  const activationId = callerCorrelationId(activation.correlation);
-  return activationId !== void 0 && activationId === dispatch.correlation.id && activation.bookKey === dispatch.bookKey;
-}
-function reconcileInvocation(subject) {
-  const { dispatch, activation, process } = subject;
-  if (activation !== void 0) {
-    if (dispatch !== void 0 && dispatchMatchesActivation(dispatch, activation)) {
-      return {
-        kind: "matched",
-        correlationId: dispatch.correlation.id,
-        bookKey: dispatch.bookKey
-      };
-    }
-    return {
-      kind: "activation-without-dispatch",
-      correlationId: callerCorrelationId(activation.correlation),
-      bookKey: activation.bookKey
-    };
-  }
-  if (dispatch !== void 0) {
-    if (process === void 0) {
-      throw new TypeError(
-        "reconcileInvocation requires process liveness when activation is absent"
-      );
-    }
-    if (process.state === "alive") {
-      return {
-        kind: "pending",
-        correlationId: dispatch.correlation.id,
-        bookKey: dispatch.bookKey
-      };
-    }
-    return {
-      kind: "ghost",
-      correlationId: dispatch.correlation.id,
-      bookKey: dispatch.bookKey
-    };
-  }
-  throw new TypeError(
-    "reconcileInvocation requires a dispatch stub and/or an accepted-activation fact"
-  );
-}
-export {
-  DISPATCH_STUB_EVENT,
-  buildDispatchStubFact,
-  reconcileInvocation
-};

package/src/activation-reconciliation.ts

@@ -1,163 +0,0 @@
-import type { AcceptedActivationFact } from "./activation-ledger.ts";
-
-/** Event category for pre-dispatch stub facts (#11 producer contract). */
-export const DISPATCH_STUB_EVENT = "dispatch-stub" as const;
-
-/**
- * Non-content dispatch pointer. Carries process identity or an opaque ref —
- * never prompt/argv/content bytes (ADR 0049).
- */
-export type DispatchPointer =
-  | { readonly kind: "process"; readonly pid: number }
-  | { readonly kind: "opaque"; readonly ref: string };
-
-/**
- * Minimum typed dispatch stub the #11 producer supplies before ignition.
- * Index-only: correlation, book, time, event category, non-content pointer.
- */
-export type DispatchStubFact = {
-  readonly event: typeof DISPATCH_STUB_EVENT;
-  readonly observedAt: string;
-  readonly bookKey: string;
-  readonly dispatch: DispatchPointer;
-  readonly correlation: { readonly kind: "caller"; readonly id: string };
-};
-
-/** Trusted typed inputs for building the closed dispatch stub (fact minus event discriminant). */
-export type DispatchStubFactInput = Omit<DispatchStubFact, "event">;
-
-/**
- * Construct the closed dispatch stub from trusted typed inputs only.
- * Nested dispatch/correlation are rebuilt closed (ADR 0049: first-phase ledger holds zero content bytes by construction).
- */
-export function buildDispatchStubFact(input: DispatchStubFactInput): DispatchStubFact {
-  return {
-    event: DISPATCH_STUB_EVENT,
-    observedAt: input.observedAt,
-    bookKey: input.bookKey,
-    dispatch: input.dispatch.kind === "process"
-      ? { kind: "process", pid: input.dispatch.pid }
-      : { kind: "opaque", ref: input.dispatch.ref },
-    correlation: { kind: "caller", id: input.correlation.id },
-  };
-}
-
-/**
- * Truthful process liveness supplied by the consumer.
- * Reconciliation never probes, kills, or retries processes (D1a / #78).
- */
-export type ProcessLivenessFact =
-  | { readonly state: "alive" }
-  | { readonly state: "terminated" };
-
-/**
- * One reconciliation subject as an exclusive complete union (four outcomes only):
- * - activation present → activation required; dispatch/process optional
- * - activation absent → dispatch + truthful process required; activation prohibited
- * No session-file existence oracle (ADR 0047). Untyped JS still hits runtime TypeError.
- */
-export type ReconciliationSubject =
-  | {
-      readonly activation: AcceptedActivationFact;
-      readonly dispatch?: DispatchStubFact;
-      readonly process?: ProcessLivenessFact;
-    }
-  | {
-      readonly activation?: undefined;
-      readonly dispatch: DispatchStubFact;
-      readonly process: ProcessLivenessFact;
-    };
-
-/**
- * Exactly four typed outcomes (D1a):
- * - matched — dispatch stub and matching accepted-activation fact
- * - pending — dispatch present, no activation, process still alive
- * - ghost — dispatch present, no activation, process terminated
- * - activation-without-dispatch — activation fact with no matching stub
- */
-export type ReconciliationOutcome =
-  | {
-      readonly kind: "matched";
-      readonly correlationId: string;
-      readonly bookKey: string;
-    }
-  | {
-      readonly kind: "pending";
-      readonly correlationId: string;
-      readonly bookKey: string;
-    }
-  | {
-      readonly kind: "ghost";
-      readonly correlationId: string;
-      readonly bookKey: string;
-    }
-  | {
-      readonly kind: "activation-without-dispatch";
-      readonly correlationId: string | undefined;
-      readonly bookKey: string;
-    };
-
-function callerCorrelationId(
-  correlation: AcceptedActivationFact["correlation"] | DispatchStubFact["correlation"],
-): string | undefined {
-  return correlation.kind === "caller" ? correlation.id : undefined;
-}
-
-function dispatchMatchesActivation(
-  dispatch: DispatchStubFact,
-  activation: AcceptedActivationFact,
-): boolean {
-  const activationId = callerCorrelationId(activation.correlation);
-  return (
-    activationId !== undefined
-    && activationId === dispatch.correlation.id
-    && activation.bookKey === dispatch.bookKey
-  );
-}
-
-/**
- * Reconcile one invocation's typed dispatch/activation facts against truthful
- * process liveness. Pure: never kills, never retries, never reads session files.
- */
-export function reconcileInvocation(subject: ReconciliationSubject): ReconciliationOutcome {
-  const { dispatch, activation, process } = subject;
-
-  if (activation !== undefined) {
-    if (dispatch !== undefined && dispatchMatchesActivation(dispatch, activation)) {
-      return {
-        kind: "matched",
-        correlationId: dispatch.correlation.id,
-        bookKey: dispatch.bookKey,
-      };
-    }
-    return {
-      kind: "activation-without-dispatch",
-      correlationId: callerCorrelationId(activation.correlation),
-      bookKey: activation.bookKey,
-    };
-  }
-
-  if (dispatch !== undefined) {
-    if (process === undefined) {
-      throw new TypeError(
-        "reconcileInvocation requires process liveness when activation is absent",
-      );
-    }
-    if (process.state === "alive") {
-      return {
-        kind: "pending",
-        correlationId: dispatch.correlation.id,
-        bookKey: dispatch.bookKey,
-      };
-    }
-    return {
-      kind: "ghost",
-      correlationId: dispatch.correlation.id,
-      bookKey: dispatch.bookKey,
-    };
-  }
-
-  throw new TypeError(
-    "reconcileInvocation requires a dispatch stub and/or an accepted-activation fact",
-  );
-}