@akagilnc/pi-workflow-roles 0.1.3280 → 0.1.3353

package/src/collector-role.ts

@@ -21,8 +21,8 @@ import {
   COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
   COLLECTOR_WAIT_TOOL,
-  createCollectorLedger,
   projectEvidenceEntryView,
+  type CollectorConfigState,
   type CollectorLedger,
 } from "./collector-ledger.ts";
 import {
@@ -88,6 +88,7 @@ export type CollectorRoleDependencies = {
   loadSoul(): Promise<string>;
   createTransport(): CollectorGitHubTransport;
   createClock?(): CollectorClock;
+  createLedger(config: CollectorConfigState, clock: CollectorClock, ctx: HostContext): CollectorLedger;
   packageExtensionPath?: string;
 };
 
@@ -249,15 +250,16 @@ export function createCollectorRoleRuntime(
           reason: `通进司禁用工具 ${event.toolName}`,
         };
       }
-      // Concurrency is owned at execute (beginOperational), not announced-batch preflight.
-      // Pi may emit tool_call for every part before any execute runs (ADR 0041).
+      if (event.toolName === COLLECTOR_OUTPUT_TOOL) {
+        activation.ledger.beginOperational(COLLECTOR_OUTPUT_TOOL, event.toolCallId);
+      }
       if (
-        activation.ledger.outputAccepted &&
+        activation.ledger.outputCandidate &&
         event.toolName !== COLLECTOR_OUTPUT_TOOL
       ) {
         return {
           block: true,
-          reason: "回执已受理，本局不再受理操作",
+          reason: "通进司已产出输出候选，本局不再受理操作",
         };
       }
       return undefined;
@@ -270,7 +272,7 @@ export function createCollectorRoleRuntime(
 
     pi.on("session_shutdown", () => {
       if (activation === undefined) return;
-      if (!activation.ledger.outputAccepted || activation.ledger.fatal) {
+      if (activation.ledger.fatal) {
         if (process.exitCode === undefined || process.exitCode === 0) {
           process.exitCode = 1;
         }
@@ -452,8 +454,7 @@ export function createCollectorRoleRuntime(
             params,
             activation.clock,
           );
-          activation.ledger.markOutputAccepted();
-          activation.ledger.completeOperational(toolCallId);
+          activation.ledger.recordOutputCandidate();
           const acceptedDetails = receipt;
           return {
             content: [{
@@ -472,6 +473,8 @@ export function createCollectorRoleRuntime(
             hostActions.failInfrastructure(error, ctx, toolCallId);
           }
           throw error;
+        } finally {
+          activation.ledger.completeOperational(toolCallId);
         }
       },
     });
@@ -488,7 +491,6 @@ export function createCollectorRoleRuntime(
           );
         }
         if (
-          event.reason === "resume" ||
           event.reason === "fork" ||
           event.reason === "reload"
         ) {
@@ -581,11 +583,16 @@ export function createCollectorRoleRuntime(
 
         const clock = dependencies.createClock?.() ?? createSystemCollectorClock();
         const transport = dependencies.createTransport();
-        const ledger = createCollectorLedger({
-          repository,
-          prNumber,
-          manifest,
-        });
+
+        const ledger = dependencies.createLedger(
+          { repository, prNumber, manifest },
+          clock,
+          ctx,
+        );
+
+        if (ledger.activationRecorded) {
+          firstDispatchDone = true;
+        }
 
       activation = {
         soul,

package/src/diarist-mechanical.ts

@@ -223,7 +223,7 @@ function isNotificationRow(type: string, text: string): boolean {
 }
 
 /**
- * Enumerate cc session user/assistant turns under Claude projects roots.
+ * Enumerate cc session user/assistant turns and human queued-command attachments under Claude projects roots.
  * cc-sessions-first source family (ADR 0075).
  * Directory/file/non-empty JSONL line failures throw DiaristSourceReadError
  * (失败诚实：不得把未读懂洗成没有来源块).
@@ -301,11 +301,22 @@ export function readCcSessionBlocks(
             { cause: error },
           );
         }
-        // Unknown row shape (not user/assistant) is ignored — not a read failure.
+        // Unknown row shape (not user/assistant or a human queued-command attachment) is ignored — not a read failure.
         if (!isRecord(parsed)) continue;
         const type = typeof parsed.type === "string" ? parsed.type : "";
-        if (type !== "user" && type !== "assistant") continue;
-        const transcript = messageText(parsed.message ?? parsed);
+        const queuedCommand =
+          type === "attachment" &&
+          isRecord(parsed.attachment) &&
+          parsed.attachment.type === "queued_command" &&
+          isRecord(parsed.attachment.origin) &&
+          parsed.attachment.origin.kind === "human" &&
+          typeof parsed.attachment.prompt === "string"
+            ? parsed.attachment.prompt
+            : undefined;
+        if (type !== "user" && type !== "assistant" && queuedCommand === undefined) {
+          continue;
+        }
+        const transcript = queuedCommand ?? messageText(parsed.message ?? parsed);
         if (transcript.trim() === "") continue;
         const entryId =
           typeof parsed.uuid === "string"
@@ -323,7 +334,7 @@ export function readCcSessionBlocks(
           sourceRef: { sessionFile, entryId },
           transcript,
           timestamp,
-          isUserTurn: type === "user",
+          isUserTurn: type === "user" || queuedCommand !== undefined,
           isNotification: notification,
         });
       }

package/src/gatekeeper-role.ts

@@ -36,6 +36,13 @@ export type GatekeeperResult =
       readonly findings: readonly string[];
       readonly submission: unknown;
     }
+  | {
+      readonly status: "escalate";
+      readonly officer: "inspector" | "notary";
+      readonly reason?: unknown;
+      readonly findings: unknown;
+      readonly submission: unknown;
+    }
   | { readonly status: "no_receipt"; readonly stage: "gatekeeper" | "inspector" | "notary"; readonly reason: string; readonly facts: NoReceiptLifecycleFacts }
   | {
       readonly status: "transport_failure";
@@ -63,6 +70,15 @@ function gateSeatLabel(stage: "gatekeeper" | "inspector" | "notary"): string {
 
 export { GatekeeperDecisionError } from "./submission-errors.ts";
 
+export class GatekeeperEscalationError extends Error {
+  readonly gatekeeper: Extract<GatekeeperResult, { status: "escalate" }>;
+  constructor(gatekeeper: Extract<GatekeeperResult, { status: "escalate" }>) {
+    super(`门下省${gateSeatLabel(gatekeeper.officer)}上呈`);
+    this.name = "GatekeeperEscalationError";
+    this.gatekeeper = gatekeeper;
+  }
+}
+
 export type RunGatekeeperOptions = {
   readonly context: ExtensionContext | HostContext;
   readonly subject: GatekeeperSubject;
@@ -82,8 +98,9 @@ export type GatekeeperPassHostActions = {
 // Unknown fields so wrong types/spellings still reach projection (ADR 0055/0057; 仓第 0 条).
 // Opening goes through the sole openToolObject owner — no parallel transport helper.
 const officerDecisionSchema = openToolObject(Type.Object({
-  status: Type.Unknown({ description: "pass | bounce — 形状指引，非 schema 闸" }),
-  findings: Type.Unknown({ description: "string[] findings，随 pass 或 bounce 留存" }),
+  status: Type.Unknown({ description: "pass | bounce | escalate — 形状指引，非 schema 闸" }),
+  reason: Type.Optional(Type.Unknown({ description: "status 为 escalate 时的理由" })),
+  findings: Type.Unknown({ description: "string[] findings，随 pass、bounce 或 escalate 留存" }),
 }));
 
 
@@ -121,7 +138,7 @@ function subjectTool(subject: GatekeeperSubject): AuditorDecisionTool {
 export function createOfficerDecisionTool(name: string): AuditorDecisionTool {
   return {
     name,
-    description: "提交一份 typed pass/bounce 决议。",
+    description: "提交一份 typed pass/bounce/escalate 决议。",
     parameters: officerDecisionSchema,
     async execute(_id, args) { return result(`已收 ${String((args as { status?: unknown })?.status)}`, args); },
   };
@@ -179,7 +196,7 @@ function noUsableReleaseFailure(
   return {
     status: "transport_failure",
     stage,
-    reason: stage === "gatekeeper" ? "decision 无显式 dispatch" : "decision 无显式 pass/bounce",
+    reason: stage === "gatekeeper" ? "decision 无显式 dispatch" : "decision 无显式 pass/bounce/escalate",
     submission: retainedSubmission(decision),
   };
 }
@@ -224,6 +241,15 @@ function projectOfficerDecision(
       findings: asStringArray(record.findings),
     };
   }
+  if (record.status === "escalate") {
+    return {
+      status: "escalate",
+      officer,
+      ...(Object.hasOwn(record, "reason") ? { reason: record.reason } : {}),
+      findings: record.findings,
+      submission: retainedSubmission(decision),
+    };
+  }
   return noUsableReleaseFailure(officer, decision);
 }
 
@@ -301,6 +327,9 @@ export async function requireGatekeeperPass(options: {
     if (gatekeeper.submission !== undefined) error.submission = gatekeeper.submission;
     options.hostActions.failInfrastructure(error, options.context, options.toolCallId);
   }
+  if (gatekeeper.status === "escalate") {
+    throw new GatekeeperEscalationError(gatekeeper);
+  }
   // Envelope owns the execute→tool_result bridge; this module only projects + throws.
   options.hostActions.bindSubmissionNonPass(options.toolCallId, gatekeeper);
   throw new GatekeeperDecisionError(gatekeeper);

package/src/grok/role-envelope.ts

@@ -623,59 +623,75 @@ export async function prepareGrokRoleEnvelope(options: {
 
   // Shared envelope activation. systemPrompt must be ready before session/new
   // (ACP delivers it there), so activation runs during prepare.
-  await emit("session_start", { reason: request.continuation.kind });
-  const inputResults = await emit("input", { text: request.continuation.prompt, source: "interactive" });
-  let prompt = request.continuation.prompt;
-  for (const value of inputResults) {
-    if (typeof value !== "object" || value === null) continue;
-    const record = value as Record<string, unknown>;
-    if (record.action === "transform" && typeof record.text === "string") prompt = record.text;
-  }
-  // Book the user assignment so judge audit subjects recover it from parent books.
-  if (typeof prompt === "string" && prompt.trim() !== "") {
-    sessionEntries.push({
-      type: "message",
-      message: { role: "user", content: prompt },
+  try {
+    await emit("session_start", { reason: request.continuation.kind });
+    const inputResults = await emit("input", { text: request.continuation.prompt, source: "interactive" });
+    let prompt = request.continuation.prompt;
+    for (const value of inputResults) {
+      if (typeof value !== "object" || value === null) continue;
+      const record = value as Record<string, unknown>;
+      if (record.action === "transform" && typeof record.text === "string") prompt = record.text;
+    }
+    // Book the user assignment so judge audit subjects recover it from parent books.
+    if (typeof prompt === "string" && prompt.trim() !== "") {
+      sessionEntries.push({
+        type: "message",
+        message: { role: "user", content: prompt },
+      });
+    }
+    const basePrompt = await loadMainRoleSessionMaterials(request.activation.role);
+    const methodPrompt = (await Promise.all(request.methods.map(({ path }) => readFile(path, "utf8")))).join("\n\n");
+    const promptResults = await emit("before_agent_start", {
+      prompt,
+      systemPrompt: [basePrompt, methodPrompt].filter(Boolean).join("\n\n"),
+      systemPromptOptions: {},
     });
-  }
-  const basePrompt = await loadMainRoleSessionMaterials(request.activation.role);
-  const methodPrompt = (await Promise.all(request.methods.map(({ path }) => readFile(path, "utf8")))).join("\n\n");
-  const promptResults = await emit("before_agent_start", {
-    prompt,
-    systemPrompt: [basePrompt, methodPrompt].filter(Boolean).join("\n\n"),
-    systemPromptOptions: {},
-  });
-  const systemPromptBody = [...promptResults].reverse().find((value): value is { systemPrompt: string } =>
-    typeof value === "object" && value !== null && "systemPrompt" in value && typeof value.systemPrompt === "string")?.systemPrompt
-    ?? [basePrompt, methodPrompt].filter(Boolean).join("\n\n");
-  // Typed reading materials from agent-start handlers (machine face; independent of prompt bytes).
-  // Folded into the provider-visible systemPrompt by the adapter at the send boundary.
-  const readingMaterials: unknown[] = [];
-  for (const value of promptResults) {
-    if (typeof value !== "object" || value === null) continue;
-    if (!("readingMaterial" in value)) continue;
-    const material = (value as { readingMaterial?: unknown }).readingMaterial;
-    if (material !== undefined) readingMaterials.push(material);
-  }
+    const systemPromptBody = [...promptResults].reverse().find((value): value is { systemPrompt: string } =>
+      typeof value === "object" && value !== null && "systemPrompt" in value && typeof value.systemPrompt === "string")?.systemPrompt
+      ?? [basePrompt, methodPrompt].filter(Boolean).join("\n\n");
+    // Typed reading materials from agent-start handlers (machine face; independent of prompt bytes).
+    // Folded into the provider-visible systemPrompt by the adapter at the send boundary.
+    const readingMaterials: unknown[] = [];
+    for (const value of promptResults) {
+      if (typeof value !== "object" || value === null) continue;
+      if (!("readingMaterial" in value)) continue;
+      const material = (value as { readingMaterial?: unknown }).readingMaterial;
+      if (material !== undefined) readingMaterials.push(material);
+    }
 
-  priorAkRoleRunDir = process.env.AK_ROLE_RUN_DIR;
-  process.env.AK_ROLE_RUN_DIR = request.runDirectory;
-  runDirInjected = true;
+    priorAkRoleRunDir = process.env.AK_ROLE_RUN_DIR;
+    process.env.AK_ROLE_RUN_DIR = request.runDirectory;
+    runDirInjected = true;
 
-  return {
-    mcpServers: [{
-      name: `ak-${request.activation.role}`,
-      command: process.execPath,
-      args: [relay],
-      env: [
-        { name: "AK_GROK_MCP_SOCKET", value: options.socketPath },
-        { name: "AK_GROK_MCP_TOKEN", value: token },
-      ],
-    }],
-    systemPrompt: { body: systemPromptBody, materials: readingMaterials },
-    prompt,
-    abortSignal: hostAbort.signal,
-    closeRound,
-    dispose,
-  };
+    return {
+      mcpServers: [{
+        name: `ak-${request.activation.role}`,
+        command: process.execPath,
+        args: [relay],
+        env: [
+          { name: "AK_GROK_MCP_SOCKET", value: options.socketPath },
+          { name: "AK_GROK_MCP_TOKEN", value: token },
+        ],
+      }],
+      systemPrompt: { body: systemPromptBody, materials: readingMaterials },
+      prompt,
+      abortSignal: hostAbort.signal,
+      closeRound,
+      dispose,
+    };
+  } catch (error) {
+    // listen already succeeded; dispose is not yet caller-owned. Release the
+    // unix listener before surfacing the activation/prepare failure. Keep both
+    // causes when dispose also fails (failure-honesty; do not erase cleanup).
+    try {
+      await dispose();
+    } catch (cleanupFailure) {
+      throw new AggregateError(
+        [error, cleanupFailure],
+        "prepareGrokRoleEnvelope activation failed and its dispose cleanup also failed",
+        { cause: error },
+      );
+    }
+    throw error;
+  }
 }

package/src/inspector-contracts.ts

@@ -1,6 +1,6 @@
 /**
  * Public Inspector (察院) terminating receipt contracts.
- * Lawful explicit releases: pass | bounce.
+ * Lawful explicit releases: pass | bounce | escalate.
  * Dual path: gate-dispatched and independently callable (#568 / ADR 0074).
  */
 
@@ -9,7 +9,8 @@ export const INSPECTOR_ACCEPTED_TEXT = "察院回执已接受";
 
 export type InspectorOutput =
   | { readonly status: "pass"; readonly findings?: unknown }
-  | { readonly status: "bounce"; readonly findings?: unknown };
+  | { readonly status: "bounce"; readonly findings?: unknown }
+  | { readonly status: "escalate"; readonly reason?: unknown; readonly findings?: unknown };
 
 export function validateRecordedInspectorOutput(value: unknown): InspectorOutput {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
@@ -21,7 +22,7 @@ export function validateRecordedInspectorOutput(value: unknown): InspectorOutput
   } catch {
     throw new Error("Inspector output has no execution discriminator");
   }
-  if (status === "pass" || status === "bounce") {
+  if (status === "pass" || status === "bounce" || status === "escalate") {
     return value as InspectorOutput;
   }
   throw new Error("Inspector output has no execution discriminator");
@@ -32,5 +33,7 @@ export function inspectorDecisiveFacts(output: InspectorOutput): Record<string,
   const facts: Record<string, unknown> = { status: output.status };
   const findings = (output as { findings?: unknown }).findings;
   if (findings !== undefined) facts.findings = findings;
+  const reason = (output as { reason?: unknown }).reason;
+  if (reason !== undefined) facts.reason = reason;
   return facts;
 }

package/src/inspector-role.ts

@@ -23,11 +23,14 @@ export const inspectorOutputSchema = withInfrastructureFailureDeclaration(
   openToolObject(
     Type.Object({
       status: Type.Unknown({
-        description: "pass | bounce — 形状指引，非 schema 闸",
+        description: "pass | bounce | escalate — 形状指引，非 schema 闸",
       }),
       findings: Type.Unknown({
         description: "随交卷留存的问题记录",
       }),
+      reason: Type.Optional(Type.Unknown({
+        description: "status 为 escalate 时的上呈理由",
+      })),
     }),
   ),
 );
@@ -44,7 +47,7 @@ export type InspectorRuntimeDependencies = {
 export const INSPECTOR_TOOL_SPEC = {
   name: INSPECTOR_OUTPUT_TOOL_NAME,
   label: "察院输出",
-  description: "察院终局回执，状态为 pass 或 bounce。",
+  description: "察院终局回执，状态为 pass、bounce 或 escalate。",
   promptSnippet: "察院终局回执",
   parameters: inspectorOutputSchema,
 } as const;

package/src/notary-contracts.ts

@@ -1,6 +1,6 @@
 /**
  * Public Notary (符宝郎) terminating receipt contracts.
- * Lawful explicit releases: pass | bounce.
+ * Lawful explicit releases: pass | bounce | escalate.
  * No usable result is infrastructure failure via public settlement, not a judgment status (#475).
  */
 import { Type } from "typebox";
@@ -35,11 +35,14 @@ export const notaryOutputSchema = withInfrastructureFailureDeclaration(
   openToolObject(
     Type.Object({
       status: Type.Unknown({
-        description: "pass | bounce — 形状指引，非 schema 闸",
+        description: "pass | bounce | escalate — 形状指引，非 schema 闸",
       }),
       findings: Type.Unknown({
-        description: "string[] findings，随 pass 或 bounce 留存",
+        description: "string[] findings，随 pass、bounce 或 escalate 留存",
       }),
+      reason: Type.Optional(Type.Unknown({
+        description: "status 为 escalate 时的上呈理由",
+      })),
     }),
   ),
 );
@@ -56,6 +59,11 @@ export type NotaryOutput =
       readonly status: "bounce";
       readonly disposition: "rewrite";
       readonly findings: readonly string[];
+    }
+  | {
+      readonly status: "escalate";
+      readonly reason?: unknown;
+      readonly findings?: unknown;
     };
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -68,7 +76,7 @@ function asStringArray(value: unknown): readonly string[] {
 }
 
 /**
- * Project one lawful explicit Notary release (pass | bounce).
+ * Project one lawful explicit Notary release (pass | bounce | escalate).
  * No throw on shape — ADR 0055 / 第 0 条: already-submitted params are retained as-is;
  * public-terminal projects non-usable releases via typed failure cause.
  */
@@ -86,6 +94,9 @@ export function projectLawfulNotaryOutput(value: unknown): NotaryOutput | undefi
     if (!Array.isArray(clone.findings)) clone.findings = asStringArray(clone.findings);
     return clone as NotaryOutput;
   }
+  if (status === "escalate") {
+    return structuredClone(value) as NotaryOutput;
+  }
   return undefined;
 }
 
@@ -100,7 +111,7 @@ export function retainNotarySubmission(value: unknown): unknown {
 }
 
 /**
- * Settlement/recording path: only lawful recorded pass/bounce.
+ * Settlement/recording path: only lawful recorded pass/bounce/escalate.
  * Does not gate role admission — callers must not use this to reject a submission.
  */
 export function validateRecordedNotaryOutput(value: unknown): NotaryOutput {
@@ -121,5 +132,9 @@ export function notaryDecisiveFacts(output: NotaryOutput): Record<string, unknow
   if (status === "bounce") {
     facts.disposition = "rewrite";
   }
+  if (status === "escalate") {
+    const reason = (output as { reason?: unknown }).reason;
+    if (reason !== undefined) facts.reason = reason;
+  }
   return facts;
 }

package/src/notary-role.ts

@@ -163,7 +163,7 @@ export function createNotaryRoleRuntime(
         pi.registerTool({
           name: NOTARY_OUTPUT_TOOL_NAME,
           label: "符宝郎输出",
-          description: "提交引文保真与票面对齐的 typed pass/bounce 决议。",
+          description: "提交引文保真与票面对齐的 typed pass/bounce/escalate 决议。",
           promptSnippet: "提交符宝郎决议",
           parameters: notaryOutputSchema,
           async execute(toolCallId: string, parameters: unknown, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext, ): Promise<HostToolResult<unknown>> {
@@ -171,7 +171,7 @@ export function createNotaryRoleRuntime(
               throw new Error("符宝郎未激活");
             }
             // Unique submission + terminate only. Shape is not an admission gate
-            // (第 0 条 / ADR 0055): lawful pass/bounce projected; else params as-is.
+            // (第 0 条 / ADR 0055): lawful pass/bounce/escalate projected; else params as-is.
             // #541 infra declaration + sole-final barrier are ledger-owned (#575).
             const lawful = projectLawfulNotaryOutput(parameters);
             const details = lawful ?? retainNotarySubmission(parameters);

package/src/packaged-role-registry.ts

@@ -190,18 +190,6 @@ export const PUBLIC_ROLE_RECORDS = [
 export type PublicRoleRecord = (typeof PUBLIC_ROLE_RECORDS)[number];
 export type PackagedRole = PublicRoleRecord["role"];
 
-/**
- * Seats that refuse resume. Collector/doctor/notary remain pending independent
- * authority review; countersign/gleaner-left revoked by #599 (DK-1/2/3).
- * Inspector is one-shot on the filed-officer envelope (#568 / ADR 0074).
- */
-export const ONE_SHOT_ROLES: readonly PackagedRole[] = [
-  "collector",
-  "doctor",
-  "notary",
-  "inspector",
-];
-
 /**
  * Read-only metadata projection (no sessionMaterials).
  * Distributed per PublicRoleRecord member so role↔field associations stay intact.