@akagilnc/pi-workflow-roles 0.1.5483 → 0.1.5571

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

@@ -16,7 +16,7 @@ import {
   activationBookDirectory,
   resolveActivationLedgerHome,
 } from "../activation-ledger-topology.ts";
-import { listBookRunDirectories } from "../role-run-placement.ts";
+import { findRoleRunDirectory, listBookRunDirectories, parseRunLeaf, sessionFileIn } from "../role-run-placement.ts";
 import { isSafePositiveTicketNumber } from "../run-ticket-number.ts";
 import { CliUsageError } from "./cli-errors.ts";
 import type { FixerPhase } from "../package-contracts/fixer-output.ts";
@@ -25,6 +25,7 @@ import { parseCollectorRepository } from "../collector-config.ts";
 import type { DoctorCaseIdentity } from "../doctor-contracts.ts";
 import type { NotarySourceRunLocator } from "../notary-contracts.ts";
 import {
+  retainedRunPathsMatch,
   rewriteAdmittedRoleRunPage,
   rewriteRunDirectoryPathValue,
 } from "../role-run-relocation.ts";
@@ -62,6 +63,7 @@ import {
   type ReviewerLens,
 } from "./invocation.ts";
 
+import { readPageSync, writeSectionSync } from "../run-dossier.ts";
 import { isRecord, errorText, isEnoent } from "../unknown-value.ts";
 
 export type RoleRunState = "admitted" | "running" | "resumable" | "terminal";
@@ -82,7 +84,6 @@ export type RoleRunRecord = {
   /** Exact Pi session file principal reopened on resume (not directory-latest). */
   readonly sessionFile: string;
   readonly runDirectory: string;
-  readonly admittedRequestPath: string;
   /** Coder/Fixer — preserved for resume continuation. */
   readonly phase?: CoderPhase | FixerPhase;
 };
@@ -153,7 +154,6 @@ export function buildAutoResumeContinuationPrompt(options: {
   ).join("\n");
 }
 
-const RUN_STATE_FILE = "run-state.json";
 const WRITER_LOCK_FILE = "writer.lock";
 
 export async function writeRoleRunState(
@@ -161,15 +161,11 @@ export async function writeRoleRunState(
   record: Omit<RoleRunRecord, "runDirectory">,
 ): Promise<void> {
   const payload: RoleRunRecord = { ...record, runDirectory };
-  await writeFile(
-    join(runDirectory, RUN_STATE_FILE),
-    `${JSON.stringify(payload, null, 2)}\n`,
-    "utf8",
-  );
+  writeSectionSync(runDirectory, "runState", { ...payload });
 }
 
 /**
- * Uninterpreted principal wire as stored on run-state.json.
+ * Uninterpreted principal wire as stored on the state.jsonl run-state row.
  * Legacy rows may omit sessionFile; only DurablePrincipalAuthority decodes it.
  */
 type RoleRunPrincipalWire = {
@@ -185,7 +181,6 @@ type RoleRunStateDisk = {
   readonly bookKey: string;
   readonly projectRoot: string;
   readonly runDirectory: string;
-  readonly admittedRequestPath: string;
   readonly principalWire: RoleRunPrincipalWire;
   readonly phase?: CoderPhase | FixerPhase;
   /** Open court turn (#637); omit when no unsealed current court. */
@@ -262,20 +257,13 @@ function parseCurrentCourtState(raw: unknown): CurrentCourtState | undefined {
 }
 
 async function readRoleRunStateRaw(runDirectory: string): Promise<unknown | undefined> {
-  let raw: unknown;
-  try {
-    raw = JSON.parse(await readFile(join(runDirectory, RUN_STATE_FILE), "utf8"));
-  } catch (error) {
-    // Only true absence (ENOENT) is a lawful "no run state yet". A real read
-    // failure (EISDIR, EACCES, ...) or a JSON.parse SyntaxError on a present
-    // file is genuine infrastructure/data damage and must keep its own
-    // identity — callers route it through the controlled-failure seam
-    // (markRunRunning/markRunTerminal/recordCurrentCourt)
-    // instead of it being relabeled "run state missing" (#836).
-    if (errorCodeOf(error) === "ENOENT") return undefined;
-    throw error;
-  }
-  return raw;
+  // Only true absence (no state.jsonl run-state row) is a lawful "no run state
+  // yet". A real read failure (EISDIR, EACCES, ...) or an illegal latest payload
+  // is genuine infrastructure/data damage and must keep its own identity —
+  // callers route it through the controlled-failure seam
+  // (markRunRunning/markRunTerminal/recordCurrentCourt) instead of it being
+  // relabeled "run state missing" (#836). readPageSync throws those.
+  return readPageSync(runDirectory, "runState");
 }
 
 function parseRoleRunIdentity(raw: unknown, runDirectory: string): {
@@ -286,15 +274,15 @@ function parseRoleRunIdentity(raw: unknown, runDirectory: string): {
   readonly state: RoleRunState;
 } {
   if (!isRecord(raw)) {
-    throw new TypeError("Invalid run-state.json");
+    throw new TypeError("Invalid state.jsonl run-state");
   }
   const record = raw;
   if (typeof record.runId !== "string" || record.runId.trim() === "") {
-    throw new TypeError("Invalid run-state.json");
+    throw new TypeError("Invalid state.jsonl run-state");
   }
   const role = typeof record.role === "string" ? packagedRoleMetadata(record.role)?.role : undefined;
   if (role === undefined) {
-    throw new TypeError("Invalid run-state.json");
+    throw new TypeError("Invalid state.jsonl run-state");
   }
   if (
     record.state !== "admitted" &&
@@ -302,9 +290,9 @@ function parseRoleRunIdentity(raw: unknown, runDirectory: string): {
     record.state !== "resumable" &&
     record.state !== "terminal"
   ) {
-    throw new TypeError("Invalid run-state.json");
+    throw new TypeError("Invalid state.jsonl run-state");
   }
-  if (typeof record.bookKey !== "string") throw new TypeError("Invalid run-state.json");
+  if (typeof record.bookKey !== "string") throw new TypeError("Invalid state.jsonl run-state");
   return {
     runId: record.runId,
     role,
@@ -321,9 +309,8 @@ async function readRoleRunStateDisk(
   if (raw === undefined) return undefined;
   const identity = parseRoleRunIdentity(raw, runDirectory);
   const record = raw as Record<string, unknown>;
-  if (typeof record.projectRoot !== "string") throw new TypeError("Invalid run-state.json");
-  if (typeof record.sessionDirectory !== "string") throw new TypeError("Invalid run-state.json");
-  if (typeof record.admittedRequestPath !== "string") throw new TypeError("Invalid run-state.json");
+  if (typeof record.projectRoot !== "string") throw new TypeError("Invalid state.jsonl run-state");
+  if (typeof record.sessionDirectory !== "string") throw new TypeError("Invalid state.jsonl run-state");
   const storedRunDirectory =
     typeof record.runDirectory === "string" && record.runDirectory.trim() !== ""
       ? record.runDirectory
@@ -352,11 +339,6 @@ async function readRoleRunStateDisk(
     bookKey: identity.bookKey,
     projectRoot: record.projectRoot,
     runDirectory: runDir,
-    admittedRequestPath: rewriteRunDirectoryPathValue(
-      record.admittedRequestPath,
-      storedRunDirectory,
-      runDirectory,
-    ) as string,
     principalWire,
     ...(phase === undefined ? {} : { phase }),
     ...(currentCourt === undefined ? {} : { currentCourt }),
@@ -378,15 +360,10 @@ async function writeRoleRunStateDisk(
     ...(disk.principalWire.sessionFile === undefined
       ? {}
       : { sessionFile: disk.principalWire.sessionFile }),
-    admittedRequestPath: disk.admittedRequestPath,
     ...(disk.phase === undefined ? {} : { phase: disk.phase }),
     ...(disk.currentCourt === undefined ? {} : { currentCourt: disk.currentCourt }),
   };
-  await writeFile(
-    join(runDirectory, RUN_STATE_FILE),
-    `${JSON.stringify(payload, null, 2)}\n`,
-    "utf8",
-  );
+  writeSectionSync(runDirectory, "runState", payload);
 }
 
 /** One authority.decode of the uninterpreted wire → record + opaque principal (frozen wire itself). */
@@ -407,7 +384,6 @@ function materializeRoleRunFromDisk(
         sessionDirectory: coordinates.sessionDirectory,
         sessionFile: coordinates.sessionFile,
         runDirectory: disk.runDirectory,
-        admittedRequestPath: disk.admittedRequestPath,
         ...(disk.phase === undefined ? {} : { phase: disk.phase }),
       },
     };
@@ -466,7 +442,6 @@ export async function markRunAdmitted(
     projectRoot: admitted.projectRoot,
     sessionDirectory,
     sessionFile,
-    admittedRequestPath: admitted.admittedRequestPath,
     ...(workerPhase === undefined ? {} : { phase: workerPhase }),
   });
 }
@@ -474,7 +449,7 @@ export async function markRunAdmitted(
 /**
  * Shared dispatch execution seam: transition to running, then record the
  * effective launch model (initial or resume override) and the authoritative
- * seat engine/host onto invocation.json.
+ * seat engine/host onto the invocation section.
  * Role runners must not coordinate lifecycle ledger writes themselves.
  * Engine axis is authoritative here (#617): present string is written; omit/undefined
  * clears any prior engine key so unset-engine + resume does not keep a stale value.
@@ -915,31 +890,12 @@ export async function findRunDirectoryById(
     if (errorCodeOf(error) === "ENOENT") return undefined;
     throw error;
   }
-  const matches: string[] = [];
-  for (const bookKey of bookKeys) {
-    if (onlyBookKey !== undefined && bookKey !== onlyBookKey) continue;
-    const bookDir = activationBookDirectory(ledgerHome, bookKey);
-    let runDirectories: string[];
-    try {
-      runDirectories = await listBookRunDirectories(bookDir);
-    } catch (error) {
-      if (errorCodeOf(error) === "ENOENT") continue;
-      throw error;
-    }
-    for (const runDirectory of runDirectories) {
-      const entry = basename(runDirectory);
-      if (
-        (onlyRole === undefined && (entry === `${runId}@judge` || entry.startsWith(`${runId}@`))) ||
-        entry === `${runId}@${onlyRole}`
-      ) {
-        matches.push(runDirectory);
-      }
-    }
-  }
-  if (matches.length === 0) return undefined;
-  if (matches.length === 1) return matches[0];
-  throw new Error(
-    `ambiguous role run id ${runId}: ${matches.join(", ")}`,
+  return findRoleRunDirectory(
+    bookKeys
+      .filter((bookKey) => onlyBookKey === undefined || bookKey === onlyBookKey)
+      .map((bookKey) => activationBookDirectory(ledgerHome, bookKey)),
+    runId,
+    onlyRole,
   );
 }
 
@@ -963,19 +919,8 @@ export function parentRunPathFromGatePointerInstruction(
 export async function readRunParentPath(
   runDirectory: string,
 ): Promise<string | undefined> {
-  let raw: unknown;
-  try {
-    raw = JSON.parse(
-      await readFile(join(runDirectory, "admitted-request.json"), "utf8"),
-    );
-  } catch (error) {
-    if (errorCodeOf(error) === "ENOENT") return undefined;
-    throw error;
-  }
-  if (!isRecord(raw)) {
-    return undefined;
-  }
-  const record = raw;
+  const record = readPageSync(runDirectory, "admitted");
+  if (record === undefined) return undefined;
   if (typeof record.sourceRunPath === "string" && record.sourceRunPath.trim() !== "") {
     return record.sourceRunPath;
   }
@@ -999,7 +944,7 @@ async function runHasFormedSessionPrincipal(runDirectory: string): Promise<boole
     typeof disk.principalWire.sessionFile === "string" &&
     disk.principalWire.sessionFile.trim() !== ""
       ? disk.principalWire.sessionFile
-      : join(disk.principalWire.sessionDirectory, "session.jsonl");
+      : sessionFileIn(disk.principalWire.sessionDirectory);
   try {
     const stat = await lstat(sessionFile);
     return stat.isFile() && !stat.isSymbolicLink();
@@ -1040,17 +985,14 @@ export async function findLatestRunIdForSeatTicket(input: {
     if (errorCodeOf(error) === "ENOENT") return undefined;
     throw error;
   }
-  const suffix = `@${input.role}`;
   let best: string | undefined;
   for (const runDirectory of runDirectories) {
-    const entry = basename(runDirectory);
-    if (!entry.endsWith(suffix)) continue;
-    const runId = entry.slice(0, entry.length - suffix.length);
-    if (runId.length === 0) continue;
+    const parsed = parseRunLeaf(basename(runDirectory));
+    if (parsed === undefined || parsed.role !== input.role) continue;
+    const runId = parsed.runId;
     const parentPath = await readRunParentPath(runDirectory);
-    // The parent's ticket can change after this child was admitted. Within one
-    // book the run leaf is its stable identity; directory placement is not.
-    if (parentPath !== input.parentRunPath && basename(parentPath ?? "") !== basename(input.parentRunPath)) continue;
+    // Follow the parent's retained placement without collapsing distinct book/subject bindings.
+    if (!await retainedRunPathsMatch(parentPath, input.parentRunPath, input.parentRunPath)) continue;
     // Durable fact: never resume-select a provisional that never formed principal.
     if (!(await runHasFormedSessionPrincipal(runDirectory))) continue;
     if (best === undefined || runId > best) best = runId;
@@ -1148,7 +1090,7 @@ async function loadResumableRunRecord(
     throw new CliUsageError(`unknown role run id: ${runId}`);
   }
   const { run, principal } = materialized;
-  // Reconstruct admitted identity from durable run record + admitted-request.json.
+  // Reconstruct admitted identity from durable run record + the admitted section.
   let instruction = "";
   let instructionEmpty = true;
   let attachments: FrozenAttachment[] = [];
@@ -1176,11 +1118,9 @@ async function loadResumableRunRecord(
   let sourceRunPath: string | undefined;
   let sourceRun: NotarySourceRunLocator | undefined;
   try {
-    const raw: unknown = JSON.parse(
-      await readFile(run.admittedRequestPath, "utf8"),
-    );
-    if (isRecord(raw)) {
-      const record = raw as Record<string, unknown>;
+    const record = readPageSync(run.runDirectory, "admitted");
+    if (record === undefined) throw new Error("state.jsonl has no admitted-request row");
+    {
       const storedRunDirectory =
         typeof record.runDirectory === "string" && record.runDirectory.trim() !== ""
           ? record.runDirectory
@@ -1226,7 +1166,7 @@ async function loadResumableRunRecord(
         lens = record.lens;
       }
       // Collector — admitted repository/PR identity (#633 resume).
-      if (typeof record.prNumber === "number" && Number.isSafeInteger(record.prNumber) && record.prNumber >= 1) {
+      if (isSafePositiveTicketNumber(record.prNumber)) {
         prNumber = record.prNumber;
       }
       if (typeof record.repository === "string" && record.repository.trim() !== "") {
@@ -1245,7 +1185,7 @@ async function loadResumableRunRecord(
         waitWindowMs = record.waitWindowMs;
       }
       // Doctor — admitted single-case identity (#633 resume).
-      if (typeof record.issueNumber === "number" && Number.isSafeInteger(record.issueNumber) && record.issueNumber >= 1) {
+      if (isSafePositiveTicketNumber(record.issueNumber)) {
         issueNumber = record.issueNumber;
       }
       if (typeof record.caseRunsPath === "string" && record.caseRunsPath.trim() !== "") {
@@ -1256,9 +1196,7 @@ async function loadResumableRunRecord(
       ) {
         const ci = record.caseIdentity as Record<string, unknown>;
         if (
-          typeof ci.issueNumber === "number" &&
-          Number.isSafeInteger(ci.issueNumber) &&
-          ci.issueNumber >= 1 &&
+          isSafePositiveTicketNumber(ci.issueNumber) &&
           typeof ci.runsPath === "string" &&
           ci.runsPath.trim() !== ""
         ) {
@@ -1341,13 +1279,8 @@ async function loadResumableRunRecord(
   }
   let model: InvocationEffectiveModel | undefined;
   try {
-    const invocationRaw: unknown = JSON.parse(
-      await readFile(join(run.runDirectory, "invocation.json"), "utf8"),
-    );
-    if (
-      isRecord(invocationRaw)
-    ) {
-      const rec = invocationRaw as Record<string, unknown>;
+    const rec = readPageSync(run.runDirectory, "invocation");
+    if (rec !== undefined) {
       if (typeof rec.provider === "string" && typeof rec.model === "string") {
         model = {
           provider: rec.provider,
@@ -1376,9 +1309,9 @@ async function loadResumableRunRecord(
       );
     }
   }
-  const sourceRunLeaf = basename(sourceRunPath ?? "").split("@");
-  const referencedRunId = sourceRun?.runId ?? sourceRunLeaf[0];
-  const referencedRole = sourceRun?.role ?? sourceRunLeaf[1];
+  const sourceRunLeaf = parseRunLeaf(basename(sourceRunPath ?? ""));
+  const referencedRunId = sourceRun?.runId ?? sourceRunLeaf?.runId;
+  const referencedRole = sourceRun?.role ?? sourceRunLeaf?.role;
   if (referencedRunId !== undefined && referencedRunId !== "") {
     const currentSourceRunDirectory = await findRunDirectoryById(
       home,
@@ -1446,7 +1379,6 @@ function resumedBaseAdmitted(loaded: {
     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),
   };