@akagilnc/pi-workflow-roles 0.1.3280 → 0.1.3353

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

@@ -1,7 +1,8 @@
 /**
  * Public Inspector Role run: admit instruction/attachments → shared post-admission
- * coordinator → settle Terminal result (#568 / ADR 0074). One-shot: pass/bounce, 无 resume.
- * Dual path with gate-province dispatch; this module is the direct command face.
+ * coordinator → settle Terminal result (#568 / ADR 0074). Lawful releases:
+ * pass/bounce/escalate. #633: manual resume continues the exact session. Dual path
+ * with gate-province dispatch; this module is the direct command face.
  */
 import type { DurablePrincipalAuthority, RoleTurnRequest } from "../host-contracts.ts";
 import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
@@ -14,9 +15,16 @@ import {
 } from "./invocation.ts";
 import {
   runPostAdmissionOneShot,
+  type PostAdmissionAdapters,
   type PostAdmissionEnv,
+  runPostAdmissionSeatResume,
+  resumeTurnRequestProjectionOptions,
 } from "./post-admission.ts";
-import { markRunAdmitted } from "./run-lifecycle.ts";
+import {
+  loadResumableInspectorRun,
+  markRunAdmitted,
+  type PublicResumeRequest,
+} from "./run-lifecycle.ts";
 import {
   presentStructuralRejection,
   trySettleInspectorTerminalResult,
@@ -110,10 +118,46 @@ export async function runPublicInspector(
     env,
     io,
     request: turnRequest,
-    adapters: {
-      trySettle: (admitted, authority) => trySettleInspectorTerminalResult(admitted, authority),
-      shouldPresentSettled: () => true,
-    },
+    adapters: inspectorAdapters(),
+    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+  });
+}
+
+function inspectorAdapters(): PostAdmissionAdapters<AdmittedInspectorInvocation> {
+  return {
+    trySettle: (admitted, authority) => trySettleInspectorTerminalResult(admitted, authority),
+    shouldPresentSettled: () => true,
+  };
+}
+
+/**
+ * Resume a previously admitted Inspector run (#633); the session principal reopens.
+ */
+export async function runPublicInspectorResume(
+  request: PublicResumeRequest,
+  env: InspectorRunEnv,
+  io: CliIo,
+): Promise<{
+  exitCode: number;
+  admitted?: AdmittedInspectorInvocation;
+  terminal?: TerminalResult;
+}> {
+  return await runPostAdmissionSeatResume({
+    request,
+    env,
+    io,
+    load: () =>
+      loadResumableInspectorRun(
+      env.home,
+      request.runId,
+      env.principalAuthority,
+    ),
+    buildTurnRequest: (admitted) =>
+      buildInspectorTurnRequest(
+      admitted,
+      resumeTurnRequestProjectionOptions(admitted, request, env),
+    ),
+    adapters: inspectorAdapters(),
     ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
   });
 }

package/src/public-cli/instruction-seat-run.ts

@@ -17,10 +17,14 @@ import {
 } from "./invocation.ts";
 import {
   runPostAdmissionOneShot,
+  runPostAdmissionSeatResume,
+  resumeTurnRequestProjectionOptions,
   type PostAdmissionEnv,
 } from "./post-admission.ts";
 import {
+  loadResumableInstructionSeatRun,
   markRunAdmitted,
+  type PublicResumeRequest,
 } from "./run-lifecycle.ts";
 import {
   presentStructuralRejection,
@@ -75,6 +79,29 @@ function instructionSeatAdapters() {
   };
 }
 
+export async function runPublicInstructionSeatResume(
+  request: PublicResumeRequest,
+  env: InstructionSeatRunEnv,
+  io: CliIo,
+): Promise<{ exitCode: number; terminal?: TerminalResult }> {
+  return await runPostAdmissionSeatResume({
+    request,
+    env,
+    io,
+    load: () => loadResumableInstructionSeatRun(
+      env.home,
+      request.runId,
+      env.principalAuthority,
+    ),
+    buildTurnRequest: (admitted) => buildInstructionSeatTurnRequest(
+      admitted,
+      resumeTurnRequestProjectionOptions(admitted, request, env),
+    ),
+    adapters: instructionSeatAdapters(),
+    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+  });
+}
+
 export async function runPublicInstructionSeat(
   argv: readonly string[],
   env: InstructionSeatRunEnv,

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

@@ -34,10 +34,11 @@ import {
   type RoleTurnRequestProjectionOptions,
 } from "./turn-request.ts";
 import {
-  runPostAdmissionManualResume,
   runPostAdmissionResumable,
   type PostAdmissionAdapters,
   type PostAdmissionEnv,
+  runPostAdmissionSeatResume,
+  resumeTurnRequestProjectionOptions,
 } from "./post-admission.ts";
 
 export type JudgeRunEnv = PostAdmissionEnv & {
@@ -176,43 +177,17 @@ export async function runPublicResume(
   admitted?: AdmittedJudgeInvocation;
   terminal?: TerminalResult;
 }> {
-  let loaded;
-  try {
-    loaded = await loadResumableJudgeRun(env.home, request.runId, env.principalAuthority);
-  } catch (error) {
-    if (error instanceof CliUsageError) {
-      presentStructuralRejection(error, io);
-      return { exitCode: 2 };
-    }
-    throw error;
-  }
-
-  const { admitted } = loaded;
-  const turnRequest = buildJudgeTurnRequest(admitted, {
-    packageRoot: env.packageRoot,
-    home: env.home,
-    agentDir: env.agentDir,
-    ...(env.model === undefined ? {} : { model: env.model }),
-    ...(env.engine === undefined ? {} : { engine: env.engine }),
-    ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
-    ...(admitted.correlationId === undefined && env.correlationId === undefined
-      ? {}
-      : { correlationId: admitted.correlationId ?? env.correlationId }),
-    continuation: {
-      kind: "resume",
-      prompt: buildResumeContinuationPrompt({
-        packageRoot: env.packageRoot,
-        ...(env.engine === undefined ? {} : { engine: env.engine }),
-        ...(request.message === undefined ? {} : { message: request.message }),
-      }),
-    },
-  });
-
-  return await runPostAdmissionManualResume({
-    admitted,
+  return await runPostAdmissionSeatResume({
+    request,
     env,
     io,
-    request: turnRequest,
+    load: () =>
+      loadResumableJudgeRun(env.home, request.runId, env.principalAuthority),
+    buildTurnRequest: (admitted) =>
+      buildJudgeTurnRequest(
+      admitted,
+      resumeTurnRequestProjectionOptions(admitted, request, env),
+    ),
     adapters: judgeAdapters(),
     ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
   });

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

@@ -53,6 +53,7 @@ import {
   runPostAdmissionResumable,
   type PostAdmissionAdapters,
   type PostAdmissionEnv,
+  resumeTurnRequestProjectionOptions,
 } from "./post-admission.ts";
 
 export type MergerRunEnv = PostAdmissionEnv & {
@@ -403,25 +404,10 @@ export async function runPublicMergerResume(
     )) as { exitCode: number; admitted: AdmittedMergerInvocation; terminal: TerminalResult };
   }
 
-  const turnRequest = buildMergerTurnRequest(admitted, {
-    packageRoot: env.packageRoot,
-    home: env.home,
-    agentDir: env.agentDir,
-    ...(env.model === undefined ? {} : { model: env.model }),
-    ...(env.engine === undefined ? {} : { engine: env.engine }),
-    ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
-    ...(admitted.correlationId === undefined && env.correlationId === undefined
-      ? {}
-      : { correlationId: admitted.correlationId ?? env.correlationId }),
-    continuation: {
-      kind: "resume",
-      prompt: buildResumeContinuationPrompt({
-        packageRoot: env.packageRoot,
-        ...(env.engine === undefined ? {} : { engine: env.engine }),
-        ...(request.message === undefined ? {} : { message: request.message }),
-      }),
-    },
-  });
+  const turnRequest = buildMergerTurnRequest(
+    admitted,
+    resumeTurnRequestProjectionOptions(admitted, request, env),
+  );
 
   return await runPostAdmissionManualResume({
     admitted,

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

@@ -14,9 +14,16 @@ import {
 } from "./invocation.ts";
 import {
   runPostAdmissionOneShot,
+  type PostAdmissionAdapters,
   type PostAdmissionEnv,
+  runPostAdmissionSeatResume,
+  resumeTurnRequestProjectionOptions,
 } from "./post-admission.ts";
-import { markRunAdmitted } from "./run-lifecycle.ts";
+import {
+  loadResumableNotaryRun,
+  markRunAdmitted,
+  type PublicResumeRequest,
+} from "./run-lifecycle.ts";
 import {
   presentStructuralRejection,
   trySettleNotaryTerminalResult,
@@ -109,11 +116,53 @@ export async function runPublicNotary(
     env,
     io,
     request: turnRequest,
-    adapters: {
-      trySettle: (admitted, authority) => trySettleNotaryTerminalResult(admitted, authority),
-      // Accepted receipts and failure terminals both present via shared path.
-      shouldPresentSettled: () => true,
+    adapters: notaryAdapters(),
+    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+  });
+}
+
+function notaryAdapters(): PostAdmissionAdapters<AdmittedNotaryInvocation> {
+  return {
+    trySettle: (admitted, authority) => trySettleNotaryTerminalResult(admitted, authority),
+    // Accepted receipts and failure terminals both present via shared path.
+    shouldPresentSettled: () => true,
+  };
+}
+
+/**
+ * Resume a previously admitted Notary run (#633). Source-run locator restores
+ * from the durable admitted request (never re-resolved); the session principal reopens.
+ */
+export async function runPublicNotaryResume(
+  request: PublicResumeRequest,
+  env: NotaryRunEnv,
+  io: CliIo,
+): Promise<{
+  exitCode: number;
+  admitted?: AdmittedNotaryInvocation;
+  terminal?: TerminalResult;
+}> {
+  return await runPostAdmissionSeatResume({
+    request,
+    env,
+    io,
+    load: () => {
+      if (request.message !== undefined) {
+        throw new CliUsageError(
+          "notary rejects caller prompt/instruction; only zero caller-prompt continuation admitted",
+        );
+      }
+      return loadResumableNotaryRun(
+        env.home,
+        request.runId,
+        env.principalAuthority,
+      );
     },
+    buildTurnRequest: (admitted) => buildNotaryTurnRequest(
+      admitted,
+      resumeTurnRequestProjectionOptions(admitted, request, env),
+    ),
+    adapters: notaryAdapters(),
     ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
   });
 }

package/src/public-cli/option-definitions.ts

@@ -1182,7 +1182,7 @@ const ROLE_COMMAND_HELP = {
   },
   collector: {
     command: "collector",
-    summary: "Collect GitHub PR review evidence (one-shot).",
+    summary: "Collect GitHub PR review evidence.",
     usage: ["ak-role collector --pr <number> [options] [instruction]"],
     examples: [
       "ak-role collector --pr 42 --repo owner/repository",
@@ -1191,7 +1191,7 @@ const ROLE_COMMAND_HELP = {
   },
   doctor: {
     command: "doctor",
-    summary: "Diagnose one retained case (one-shot).",
+    summary: "Diagnose one retained case.",
     usage: ["ak-role doctor --issue <number> [options] [instruction]"],
     examples: [
       'ak-role doctor --issue 115 "Diagnose this retained case."',
@@ -1290,7 +1290,7 @@ const SUPPORT_COMMAND_HELP = {
   resume: {
     command: "resume",
     summary:
-      "Resume a role run under the live seat table (model/host/engine); session principal must still exist.",
+      "Resume a role run under the live seat table (model/host/engine); session principal must still exist. [message] applies only to seats that accept caller instruction; Notary/符宝郎 must omit message and derives evidence from the existing source-run/dossier binding.",
     usage: ["ak-role resume <runId> [message]"],
     examples: [
       "ak-role resume 01abc…",

package/src/public-cli/post-admission.ts

@@ -8,6 +8,13 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import {
+  buildResumeContinuationPrompt,
+  type PublicResumeRequest,
+} from "./run-lifecycle.ts";
+import { CliUsageError } from "./cli-errors.ts";
+import type { RoleTurnRequestProjectionOptions } from "./turn-request.ts";
+
 import type {
   ControlledFailureCause,
   DurablePrincipal,
@@ -404,6 +411,75 @@ export async function dispatchPostAdmissionTurn<
   }
 }
 
+/**
+ * Shared resume continuation projection (#471 / #600 / #633): seat-table
+ * model/engine/timeout axes, restored correlation, and the package resume
+ * envelope (message optional). Seats add only their activation projection.
+ */
+export function resumeTurnRequestProjectionOptions(
+  admitted: AdmittedRoleInvocation,
+  request: PublicResumeRequest,
+  env: PostAdmissionEnv,
+): RoleTurnRequestProjectionOptions {
+  return {
+    packageRoot: env.packageRoot,
+    home: env.home,
+    agentDir: env.agentDir,
+    ...(env.model === undefined ? {} : { model: env.model }),
+    ...(env.engine === undefined ? {} : { engine: env.engine }),
+    ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
+    ...(admitted.correlationId === undefined && env.correlationId === undefined
+      ? {}
+      : { correlationId: admitted.correlationId ?? env.correlationId }),
+    continuation: {
+      kind: "resume",
+      prompt: buildResumeContinuationPrompt({
+        packageRoot: env.packageRoot,
+        ...(env.engine === undefined ? {} : { engine: env.engine }),
+        ...(request.message === undefined ? {} : { message: request.message }),
+      }),
+    },
+  };
+}
+
+/**
+ * Shared manual-resume orchestration for seats whose continuation is the
+ * package resume envelope (#599 / #633): load → structural rejection → seat
+ * turn projection → runPostAdmissionManualResume. Seat-owned loader validation,
+ * turn builder, and adapters stay on the seat.
+ */
+export async function runPostAdmissionSeatResume<
+  A extends AdmittedRoleInvocation,
+  T extends TerminalResult = TerminalResult,
+>(input: {
+  request: PublicResumeRequest;
+  env: PostAdmissionEnv;
+  io: CliIo;
+  load: () => Promise<{ admitted: A }>;
+  buildTurnRequest: (admitted: A) => RoleTurnRequest;
+  adapters: PostAdmissionAdapters<A, T>;
+  effectiveEngine?: string;
+}): Promise<{ exitCode: number; admitted?: A; terminal?: T }> {
+  let loaded;
+  try {
+    loaded = await input.load();
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      presentStructuralRejection(error, input.io);
+      return { exitCode: 2 };
+    }
+    throw error;
+  }
+  return await runPostAdmissionManualResume({
+    admitted: loaded.admitted,
+    env: input.env,
+    io: input.io,
+    request: input.buildTurnRequest(loaded.admitted),
+    adapters: input.adapters,
+    ...(input.effectiveEngine === undefined ? {} : { effectiveEngine: input.effectiveEngine }),
+  });
+}
+
 /**
  * Shared post-admission one-shot path: writer lease, then turn dispatch.
  * Initial facades own the durable admitted mark (markRunAdmitted) before

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

@@ -48,6 +48,7 @@ import {
   runPostAdmissionResumable,
   type PostAdmissionAdapters,
   type PostAdmissionEnv,
+  resumeTurnRequestProjectionOptions,
 } from "./post-admission.ts";
 
 export type ReviewerRunEnv = PostAdmissionEnv & {
@@ -271,25 +272,10 @@ export async function runPublicReviewerResume(
     )) as { exitCode: number; admitted: AdmittedReviewerInvocation; terminal: TerminalResult };
   }
 
-  const turnRequest = buildReviewerTurnRequest(admitted, {
-    packageRoot: env.packageRoot,
-    home: env.home,
-    agentDir: env.agentDir,
-    ...(env.model === undefined ? {} : { model: env.model }),
-    ...(env.engine === undefined ? {} : { engine: env.engine }),
-    ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
-    ...(admitted.correlationId === undefined && env.correlationId === undefined
-      ? {}
-      : { correlationId: admitted.correlationId ?? env.correlationId }),
-    continuation: {
-      kind: "resume",
-      prompt: buildResumeContinuationPrompt({
-        packageRoot: env.packageRoot,
-        ...(env.engine === undefined ? {} : { engine: env.engine }),
-        ...(request.message === undefined ? {} : { message: request.message }),
-      }),
-    },
-  });
+  const turnRequest = buildReviewerTurnRequest(
+    admitted,
+    resumeTurnRequestProjectionOptions(admitted, request, env),
+  );
 
   return await runPostAdmissionManualResume({
     admitted,