@akagilnc/pi-workflow-roles 0.1.3280 → 0.1.3353

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

@@ -28,6 +28,9 @@ export {
 } from "../typed-provider-http.ts";
 import type { FixerPhase } from "../package-contracts/fixer-output.ts";
 import type { FixerPrerequisite } from "../package-contracts/fixer-packet.ts";
+import { parseCollectorRepository } from "../collector-config.ts";
+import type { DoctorCaseIdentity } from "../doctor-contracts.ts";
+import type { NotarySourceRunLocator } from "../notary-contracts.ts";
 import {
   appendEngineSessionMaterial,
   engineSessionMaterialFromOptions,
@@ -40,9 +43,15 @@ import {
   requireAuthorityRef,
   type AdmittedCoderInvocation,
   type AdmittedCountersignInvocation,
+  type AdmittedCollectorInvocation,
+  type AdmittedDoctorInvocation,
+  type AdmittedInspectorInvocation,
+  type AdmittedNotaryInvocation,
   type AdmittedFixerInvocation,
   type AdmittedGleanerLeftInvocation,
+  type AdmittedGatekeeperInvocation,
   type AdmittedJudgeInvocation,
+  type AdmittedNavigatorInvocation,
   type AdmittedMergerInvocation,
   type AdmittedReviewerInvocation,
   type AdmittedRoleInvocation,
@@ -849,6 +858,19 @@ type LoadedAdmittedRequestFields = {
   readonly derived?: DerivedMergerEnvelope;
   readonly correlationId?: string;
   readonly ticketNumber?: number;
+  /** Collector — admitted repository/PR identity restored on resume (#633). */
+  readonly prNumber?: number;
+  readonly repository?: string;
+  readonly repositoryDisplay?: string;
+  readonly requestManifestPath?: string;
+  readonly manifestDigest?: string;
+  /** Doctor — admitted single-case identity restored on resume (#633). */
+  readonly issueNumber?: number;
+  readonly caseRunsPath?: string;
+  readonly caseIdentity?: DoctorCaseIdentity;
+  /** Notary — admitted source-run locator restored on resume (#633). */
+  readonly sourceRunPath?: string;
+  readonly sourceRun?: NotarySourceRunLocator;
   /** Effective model restored from the invocation identity page on resume. */
   readonly model?: InvocationEffectiveModel;
 };
@@ -929,6 +951,16 @@ async function loadResumableRunRecord(
   let derived: DerivedMergerEnvelope | undefined;
   let correlationId: string | undefined;
   let ticketNumber: number | undefined;
+  let prNumber: number | undefined;
+  let repository: string | undefined;
+  let repositoryDisplay: string | undefined;
+  let requestManifestPath: string | undefined;
+  let manifestDigest: string | undefined;
+  let issueNumber: number | undefined;
+  let caseRunsPath: string | undefined;
+  let caseIdentity: DoctorCaseIdentity | undefined;
+  let sourceRunPath: string | undefined;
+  let sourceRun: NotarySourceRunLocator | undefined;
   try {
     const raw: unknown = JSON.parse(
       await readFile(run.admittedRequestPath, "utf8"),
@@ -968,6 +1000,70 @@ async function loadResumableRunRecord(
       ) {
         baseRevision = record.baseRevision;
       }
+      // Collector — admitted repository/PR identity (#633 resume).
+      if (typeof record.prNumber === "number" && Number.isSafeInteger(record.prNumber) && record.prNumber >= 1) {
+        prNumber = record.prNumber;
+      }
+      if (typeof record.repository === "string" && record.repository.trim() !== "") {
+        repository = record.repository;
+      }
+      if (typeof record.repositoryDisplay === "string" && record.repositoryDisplay.trim() !== "") {
+        repositoryDisplay = record.repositoryDisplay;
+      }
+      if (typeof record.requestManifestPath === "string" && record.requestManifestPath.trim() !== "") {
+        requestManifestPath = record.requestManifestPath;
+      }
+      if (typeof record.manifestDigest === "string" && record.manifestDigest.trim() !== "") {
+        manifestDigest = record.manifestDigest;
+      }
+      // Doctor — admitted single-case identity (#633 resume).
+      if (typeof record.issueNumber === "number" && Number.isSafeInteger(record.issueNumber) && record.issueNumber >= 1) {
+        issueNumber = record.issueNumber;
+      }
+      if (typeof record.caseRunsPath === "string" && record.caseRunsPath.trim() !== "") {
+        caseRunsPath = record.caseRunsPath;
+      }
+      if (
+        record.caseIdentity !== null &&
+        typeof record.caseIdentity === "object" &&
+        !Array.isArray(record.caseIdentity)
+      ) {
+        const ci = record.caseIdentity as Record<string, unknown>;
+        if (
+          typeof ci.issueNumber === "number" &&
+          Number.isSafeInteger(ci.issueNumber) &&
+          ci.issueNumber >= 1 &&
+          typeof ci.runsPath === "string" &&
+          ci.runsPath.trim() !== ""
+        ) {
+          caseIdentity = { issueNumber: ci.issueNumber, runsPath: ci.runsPath };
+        }
+      }
+      // Notary — admitted source-run locator identity (#633 resume).
+      if (typeof record.sourceRunPath === "string" && record.sourceRunPath.trim() !== "") {
+        sourceRunPath = record.sourceRunPath;
+      }
+      if (
+        record.sourceRun !== null &&
+        typeof record.sourceRun === "object" &&
+        !Array.isArray(record.sourceRun)
+      ) {
+        const sr = record.sourceRun as Record<string, unknown>;
+        if (
+          typeof sr.runId === "string" &&
+          sr.runId.trim() !== "" &&
+          typeof sr.role === "string" &&
+          sr.role.trim() !== "" &&
+          typeof sr.runDirectory === "string" &&
+          sr.runDirectory.trim() !== ""
+        ) {
+          sourceRun = {
+            runId: sr.runId,
+            role: sr.role,
+            runDirectory: sr.runDirectory,
+          };
+        }
+      }
       if (Array.isArray(record.authorityRefs)) {
         // Reuse unique --authority-ref grammar; blank/inline prose must not resume as authority.
         authorityRefs = Object.freeze(
@@ -1083,6 +1179,16 @@ async function loadResumableRunRecord(
       ...(derived === undefined ? {} : { derived }),
       ...(correlationId === undefined ? {} : { correlationId }),
       ...(ticketNumber === undefined ? {} : { ticketNumber }),
+      ...(prNumber === undefined ? {} : { prNumber }),
+      ...(repository === undefined ? {} : { repository }),
+      ...(repositoryDisplay === undefined ? {} : { repositoryDisplay }),
+      ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
+      ...(manifestDigest === undefined ? {} : { manifestDigest }),
+      ...(issueNumber === undefined ? {} : { issueNumber }),
+      ...(caseRunsPath === undefined ? {} : { caseRunsPath }),
+      ...(caseIdentity === undefined ? {} : { caseIdentity }),
+      ...(sourceRunPath === undefined ? {} : { sourceRunPath }),
+      ...(sourceRun === undefined ? {} : { sourceRun }),
       ...(model === undefined ? {} : { model }),
     },
   };
@@ -1125,23 +1231,23 @@ export type LoadedResumableGleanerLeftRun = {
   readonly observation?: TypedHttp429Observation;
 };
 
+export type LoadedResumableInstructionSeatRun = {
+  readonly admitted: AdmittedGatekeeperInvocation | AdmittedNavigatorInvocation;
+  readonly run: RoleRunRecord;
+  readonly observation?: TypedHttp429Observation;
+};
+
 /**
- * Load a resumable Judge run for resume. Rejects unknown, terminal,
- * non-resumable, and non-Judge IDs without replaying dispatch.
+ * Base admitted projection shared by every seat loader: durable identity +
+ * instruction/attachments + principal + restored ticket identity + model (#633).
+ * Seat loaders add only their seat-specific fields on top.
  */
-export async function loadResumableJudgeRun(
-  home: string,
-  runId: string,
-  authority: DurablePrincipalAuthority,
-): Promise<LoadedResumableJudgeRun> {
-  const loaded = await loadResumableRunRecord(home, runId, authority);
-  if (loaded.run.role !== "judge") {
-    throw new CliUsageError(
-      `role run ${runId} belongs to ${loaded.run.role}, not judge`,
-    );
-  }
-  const admitted: AdmittedJudgeInvocation = {
-    role: "judge",
+function resumedBaseAdmitted(loaded: {
+  readonly run: RoleRunRecord;
+  readonly principal: DurablePrincipal;
+  readonly admittedFields: LoadedAdmittedRequestFields;
+}) {
+  return {
     runId: loaded.run.runId,
     bookKey: loaded.run.bookKey,
     projectRoot: loaded.run.projectRoot,
@@ -1154,6 +1260,16 @@ export async function loadResumableJudgeRun(
     ...(loaded.admittedFields.model === undefined ? {} : { model: loaded.admittedFields.model }),
     ...restoredTicketFields(loaded.admittedFields),
   };
+}
+
+/** Loaded-run envelope projection; seat loaders add only their seat fields. */
+function seatLoadedResult<R extends AdmittedRoleInvocation>(
+  loaded: {
+    readonly run: RoleRunRecord;
+    readonly observation?: TypedHttp429Observation;
+  },
+  admitted: R,
+): { admitted: R; run: RoleRunRecord; observation?: TypedHttp429Observation } {
   return {
     admitted,
     run: loaded.run,
@@ -1161,6 +1277,28 @@ export async function loadResumableJudgeRun(
   };
 }
 
+/**
+ * Load a resumable Judge run for resume. Rejects unknown, terminal,
+ * non-resumable, and non-Judge IDs without replaying dispatch.
+ */
+export async function loadResumableJudgeRun(
+  home: string,
+  runId: string,
+  authority: DurablePrincipalAuthority,
+): Promise<LoadedResumableJudgeRun> {
+  const loaded = await loadResumableRunRecord(home, runId, authority);
+  if (loaded.run.role !== "judge") {
+    throw new CliUsageError(
+      `role run ${runId} belongs to ${loaded.run.role}, not judge`,
+    );
+  }
+  const admitted: AdmittedJudgeInvocation = {
+    role: "judge",
+    ...resumedBaseAdmitted(loaded),
+  };
+  return seatLoadedResult(loaded, admitted);
+}
+
 /**
  * Load a resumable Coder run for resume. Phase and task path are restored from
  * the admitted request so continuation stays role-correct (#109).
@@ -1196,24 +1334,11 @@ export async function loadResumableCoderRun(
   const admitted: AdmittedCoderInvocation = {
     role: "coder",
     phase,
-    runId: loaded.run.runId,
-    bookKey: loaded.run.bookKey,
-    projectRoot: loaded.run.projectRoot,
-    instruction: loaded.admittedFields.instruction,
+    ...resumedBaseAdmitted(loaded),
     instructionEmpty: false,
-    attachments: loaded.admittedFields.attachments,
-    runDirectory: loaded.run.runDirectory,
-    principal: loaded.principal,
-    admittedRequestPath: loaded.run.admittedRequestPath,
     taskPath,
-    ...(loaded.admittedFields.model === undefined ? {} : { model: loaded.admittedFields.model }),
-    ...restoredTicketFields(loaded.admittedFields),
-  };
-  return {
-    admitted,
-    run: loaded.run,
-    ...(loaded.observation === undefined ? {} : { observation: loaded.observation }),
   };
+  return seatLoadedResult(loaded, admitted);
 }
 
 /**
@@ -1252,28 +1377,15 @@ export async function loadResumableFixerRun(
   const admitted: AdmittedFixerInvocation = {
     role: "fixer",
     phase,
-    runId: loaded.run.runId,
-    bookKey: loaded.run.bookKey,
-    projectRoot: loaded.run.projectRoot,
-    instruction: loaded.admittedFields.instruction,
+    ...resumedBaseAdmitted(loaded),
     instructionEmpty: false,
-    attachments: loaded.admittedFields.attachments,
-    runDirectory: loaded.run.runDirectory,
-    principal: loaded.principal,
-    admittedRequestPath: loaded.run.admittedRequestPath,
     packetPath,
     ...(loaded.admittedFields.prerequisitesPath === undefined
       ? {}
       : { prerequisitesPath: loaded.admittedFields.prerequisitesPath }),
     prerequisites,
-    ...(loaded.admittedFields.model === undefined ? {} : { model: loaded.admittedFields.model }),
-    ...restoredTicketFields(loaded.admittedFields),
-  };
-  return {
-    admitted,
-    run: loaded.run,
-    ...(loaded.observation === undefined ? {} : { observation: loaded.observation }),
   };
+  return seatLoadedResult(loaded, admitted);
 }
 
 /**
@@ -1303,25 +1415,11 @@ export async function loadResumableReviewerRun(
   }
   const admitted: AdmittedReviewerInvocation = {
     role: "reviewer",
-    runId: loaded.run.runId,
-    bookKey: loaded.run.bookKey,
-    projectRoot: loaded.run.projectRoot,
-    instruction: loaded.admittedFields.instruction,
-    instructionEmpty: loaded.admittedFields.instructionEmpty,
-    attachments: loaded.admittedFields.attachments,
-    runDirectory: loaded.run.runDirectory,
-    principal: loaded.principal,
-    admittedRequestPath: loaded.run.admittedRequestPath,
+    ...resumedBaseAdmitted(loaded),
     baseRevision,
     authorityRefs: Object.freeze([...(loaded.admittedFields.authorityRefs ?? [])]),
-    ...(loaded.admittedFields.model === undefined ? {} : { model: loaded.admittedFields.model }),
-    ...restoredTicketFields(loaded.admittedFields),
-  };
-  return {
-    admitted,
-    run: loaded.run,
-    ...(loaded.observation === undefined ? {} : { observation: loaded.observation }),
   };
+  return seatLoadedResult(loaded, admitted);
 }
 
 /**
@@ -1341,29 +1439,33 @@ export async function loadResumableCountersignRun(
   }
   const admitted: AdmittedCountersignInvocation = {
     role: "countersign",
-    runId: loaded.run.runId,
-    bookKey: loaded.run.bookKey,
-    projectRoot: loaded.run.projectRoot,
-    instruction: loaded.admittedFields.instruction,
-    instructionEmpty: loaded.admittedFields.instructionEmpty,
-    attachments: loaded.admittedFields.attachments,
-    runDirectory: loaded.run.runDirectory,
-    principal: loaded.principal,
-    admittedRequestPath: loaded.run.admittedRequestPath,
-    ...(loaded.admittedFields.model === undefined ? {} : { model: loaded.admittedFields.model }),
-    ...restoredTicketFields(loaded.admittedFields),
-  };
-  return {
-    admitted,
-    run: loaded.run,
-    ...(loaded.observation === undefined ? {} : { observation: loaded.observation }),
+    ...resumedBaseAdmitted(loaded),
   };
+  return seatLoadedResult(loaded, admitted);
 }
 
 /**
  * Load a resumable Gleaner-Left run for resume (#599). Fixed base restores from
  * the admitted request so continuation stays comparison-correct.
  */
+export async function loadResumableInstructionSeatRun(
+  home: string,
+  runId: string,
+  authority: DurablePrincipalAuthority,
+): Promise<LoadedResumableInstructionSeatRun> {
+  const loaded = await loadResumableRunRecord(home, runId, authority);
+  if (loaded.run.role !== "gatekeeper" && loaded.run.role !== "navigator") {
+    throw new CliUsageError(
+      `role run ${runId} belongs to ${loaded.run.role}, not an instruction seat`,
+    );
+  }
+  const admitted = {
+    role: loaded.run.role,
+    ...resumedBaseAdmitted(loaded),
+  } as AdmittedGatekeeperInvocation | AdmittedNavigatorInvocation;
+  return seatLoadedResult(loaded, admitted);
+}
+
 export async function loadResumableGleanerLeftRun(
   home: string,
   runId: string,
@@ -1383,24 +1485,10 @@ export async function loadResumableGleanerLeftRun(
   }
   const admitted: AdmittedGleanerLeftInvocation = {
     role: "gleaner-left",
-    runId: loaded.run.runId,
-    bookKey: loaded.run.bookKey,
-    projectRoot: loaded.run.projectRoot,
-    instruction: loaded.admittedFields.instruction,
-    instructionEmpty: loaded.admittedFields.instructionEmpty,
-    attachments: loaded.admittedFields.attachments,
-    runDirectory: loaded.run.runDirectory,
-    principal: loaded.principal,
-    admittedRequestPath: loaded.run.admittedRequestPath,
+    ...resumedBaseAdmitted(loaded),
     baseRevision,
-    ...(loaded.admittedFields.model === undefined ? {} : { model: loaded.admittedFields.model }),
-    ...restoredTicketFields(loaded.admittedFields),
-  };
-  return {
-    admitted,
-    run: loaded.run,
-    ...(loaded.observation === undefined ? {} : { observation: loaded.observation }),
   };
+  return seatLoadedResult(loaded, admitted);
 }
 
 export type LoadedResumableMergerRun = {
@@ -1443,25 +1531,172 @@ export async function loadResumableMergerRun(
   }
   const admitted: AdmittedMergerInvocation = {
     role: "merger",
-    runId: loaded.run.runId,
-    bookKey: loaded.run.bookKey,
-    projectRoot: loaded.run.projectRoot,
-    instruction: loaded.admittedFields.instruction,
+    ...resumedBaseAdmitted(loaded),
     instructionEmpty: false,
-    attachments: loaded.admittedFields.attachments,
-    runDirectory: loaded.run.runDirectory,
-    principal: loaded.principal,
-    admittedRequestPath: loaded.run.admittedRequestPath,
     mergerInputPath,
     derived,
-    ...(loaded.admittedFields.model === undefined ? {} : { model: loaded.admittedFields.model }),
-    ...restoredTicketFields(loaded.admittedFields),
   };
-  return {
-    admitted,
-    run: loaded.run,
-    ...(loaded.observation === undefined ? {} : { observation: loaded.observation }),
+  return seatLoadedResult(loaded, admitted);
+}
+
+export type LoadedResumableCollectorRun = {
+  readonly admitted: AdmittedCollectorInvocation;
+  readonly run: RoleRunRecord;
+  readonly observation?: TypedHttp429Observation;
+};
+
+/**
+ * Load a resumable Collector run for resume (#633). Admitted repository/PR
+ * identity restores from the durable admitted request so the continuation
+ * stays binding-correct.
+ */
+export async function loadResumableCollectorRun(
+  home: string,
+  runId: string,
+  authority: DurablePrincipalAuthority,
+): Promise<LoadedResumableCollectorRun> {
+  const loaded = await loadResumableRunRecord(home, runId, authority);
+  if (loaded.run.role !== "collector") {
+    throw new CliUsageError(
+      `role run ${runId} belongs to ${loaded.run.role}, not collector`,
+    );
+  }
+  const { prNumber, repository, repositoryDisplay, manifestDigest } = loaded.admittedFields;
+  if (
+    prNumber === undefined ||
+    repository === undefined ||
+    repositoryDisplay === undefined ||
+    manifestDigest === undefined
+  ) {
+    throw new CliUsageError(
+      `role run admitted collector repository identity is missing: ${runId}`,
+    );
+  }
+  let parsedRepository;
+  try {
+    parsedRepository = parseCollectorRepository(repositoryDisplay);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new CliUsageError(detail, { cause: error });
+  }
+  if (parsedRepository.canonical !== repository) {
+    throw new CliUsageError(
+      `role run admitted collector repository does not match its canonical form: ${runId}`,
+    );
+  }
+  const admitted: AdmittedCollectorInvocation = {
+    role: "collector",
+    ...resumedBaseAdmitted(loaded),
+    prNumber,
+    repository: parsedRepository,
+    ...(loaded.admittedFields.requestManifestPath === undefined
+      ? {}
+      : { requestManifestPath: loaded.admittedFields.requestManifestPath }),
+    manifestDigest,
+  };
+  return seatLoadedResult(loaded, admitted);
+}
+
+export type LoadedResumableDoctorRun = {
+  readonly admitted: AdmittedDoctorInvocation;
+  readonly run: RoleRunRecord;
+  readonly observation?: TypedHttp429Observation;
+};
+
+/**
+ * Load a resumable Doctor run for resume (#633). Issue + retained case
+ * identity restore from the durable admitted request.
+ */
+export async function loadResumableDoctorRun(
+  home: string,
+  runId: string,
+  authority: DurablePrincipalAuthority,
+): Promise<LoadedResumableDoctorRun> {
+  const loaded = await loadResumableRunRecord(home, runId, authority);
+  if (loaded.run.role !== "doctor") {
+    throw new CliUsageError(
+      `role run ${runId} belongs to ${loaded.run.role}, not doctor`,
+    );
+  }
+  const { issueNumber, caseRunsPath, caseIdentity } = loaded.admittedFields;
+  if (
+    issueNumber === undefined ||
+    caseRunsPath === undefined ||
+    caseIdentity === undefined
+  ) {
+    throw new CliUsageError(
+      `role run admitted doctor case identity is missing: ${runId}`,
+    );
+  }
+  const admitted: AdmittedDoctorInvocation = {
+    role: "doctor",
+    ...resumedBaseAdmitted(loaded),
+    issueNumber,
+    caseRunsPath,
+    caseIdentity,
+  };
+  return seatLoadedResult(loaded, admitted);
+}
+
+export type LoadedResumableNotaryRun = {
+  readonly admitted: AdmittedNotaryInvocation;
+  readonly run: RoleRunRecord;
+  readonly observation?: TypedHttp429Observation;
+};
+
+/**
+ * Load a resumable Notary run for resume (#633). Source-run locator restores
+ * from the durable admitted request; the locator is not re-resolved.
+ */
+export async function loadResumableNotaryRun(
+  home: string,
+  runId: string,
+  authority: DurablePrincipalAuthority,
+): Promise<LoadedResumableNotaryRun> {
+  const loaded = await loadResumableRunRecord(home, runId, authority);
+  if (loaded.run.role !== "notary") {
+    throw new CliUsageError(
+      `role run ${runId} belongs to ${loaded.run.role}, not notary`,
+    );
+  }
+  const { sourceRunPath, sourceRun } = loaded.admittedFields;
+  if (sourceRunPath === undefined || sourceRun === undefined) {
+    throw new CliUsageError(
+      `role run admitted notary source-run locator is missing: ${runId}`,
+    );
+  }
+  const admitted: AdmittedNotaryInvocation = {
+    role: "notary",
+    ...resumedBaseAdmitted(loaded),
+    sourceRunPath,
+    sourceRun,
+  };
+  return seatLoadedResult(loaded, admitted);
+}
+
+export type LoadedResumableInspectorRun = {
+  readonly admitted: AdmittedInspectorInvocation;
+  readonly run: RoleRunRecord;
+  readonly observation?: TypedHttp429Observation;
+};
+
+/** Load a resumable Inspector run for resume (#633); base admitted identity only. */
+export async function loadResumableInspectorRun(
+  home: string,
+  runId: string,
+  authority: DurablePrincipalAuthority,
+): Promise<LoadedResumableInspectorRun> {
+  const loaded = await loadResumableRunRecord(home, runId, authority);
+  if (loaded.run.role !== "inspector") {
+    throw new CliUsageError(
+      `role run ${runId} belongs to ${loaded.run.role}, not inspector`,
+    );
+  }
+  const admitted: AdmittedInspectorInvocation = {
+    role: "inspector",
+    ...resumedBaseAdmitted(loaded),
   };
+  return seatLoadedResult(loaded, admitted);
 }
 
 export async function peekRoleRunRole(