@akagilnc/pi-workflow-roles 0.1.5483 → 0.1.5571

package/dist/public-cli/run-lifecycle.js

@@ -8,14 +8,15 @@
 import { chmod, lstat, open, readdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
 import { activationBookDirectory, resolveActivationLedgerHome, } from "../activation-ledger-topology.js";
-import { listBookRunDirectories } from "../role-run-placement.js";
+import { findRoleRunDirectory, listBookRunDirectories, parseRunLeaf, sessionFileIn } from "../role-run-placement.js";
 import { isSafePositiveTicketNumber } from "../run-ticket-number.js";
 import { CliUsageError } from "./cli-errors.js";
 import { parseCollectorRepository } from "../collector-config.js";
-import { rewriteAdmittedRoleRunPage, rewriteRunDirectoryPathValue, } from "../role-run-relocation.js";
+import { retainedRunPathsMatch, rewriteAdmittedRoleRunPage, rewriteRunDirectoryPathValue, } from "../role-run-relocation.js";
 import { appendEngineSessionMaterial, engineSessionMaterialFromOptions, pickEngineAxis, } from "../package-resources/engine-material.js";
 import { packagedResumeSourcePath, packagedRoleMetadata, } from "../packaged-role-registry.js";
 import { admittedReviewerBaseFault, recordEffectiveInvocationModel, requireAuthorityRef, isReviewerLens, } from "./invocation.js";
+import { readPageSync, writeSectionSync } from "../run-dossier.js";
 import { isRecord, errorText, isEnoent } from "../unknown-value.js";
 /** Default for the #422 configurable single-call auto-resume ceiling
  * (public-cli.json top-level `autoResumeLimit`). No longer the runtime truth
@@ -41,11 +42,10 @@ export function buildAutoResumeContinuationPrompt(options) {
         ...pickEngineAxis(options),
     })).join("\n");
 }
-const RUN_STATE_FILE = "run-state.json";
 const WRITER_LOCK_FILE = "writer.lock";
 export async function writeRoleRunState(runDirectory, record) {
     const payload = { ...record, runDirectory };
-    await writeFile(join(runDirectory, RUN_STATE_FILE), `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    writeSectionSync(runDirectory, "runState", { ...payload });
 }
 function parseSameTicketSummonsMaterials(raw) {
     if (!isRecord(raw))
@@ -106,43 +106,34 @@ function parseCurrentCourtState(raw) {
     };
 }
 async function readRoleRunStateRaw(runDirectory) {
-    let raw;
-    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, runDirectory) {
     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" &&
         record.state !== "running" &&
         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");
+        throw new TypeError("Invalid state.jsonl run-state");
     return {
         runId: record.runId,
         role,
@@ -158,11 +149,9 @@ async function readRoleRunStateDisk(runDirectory) {
     const identity = parseRoleRunIdentity(raw, runDirectory);
     const record = raw;
     if (typeof record.projectRoot !== "string")
-        throw new TypeError("Invalid run-state.json");
+        throw new TypeError("Invalid state.jsonl run-state");
     if (typeof record.sessionDirectory !== "string")
-        throw new TypeError("Invalid run-state.json");
-    if (typeof record.admittedRequestPath !== "string")
-        throw new TypeError("Invalid run-state.json");
+        throw new TypeError("Invalid state.jsonl run-state");
     const storedRunDirectory = typeof record.runDirectory === "string" && record.runDirectory.trim() !== ""
         ? record.runDirectory
         : runDirectory;
@@ -185,7 +174,6 @@ async function readRoleRunStateDisk(runDirectory) {
         bookKey: identity.bookKey,
         projectRoot: record.projectRoot,
         runDirectory: runDir,
-        admittedRequestPath: rewriteRunDirectoryPathValue(record.admittedRequestPath, storedRunDirectory, runDirectory),
         principalWire,
         ...(phase === undefined ? {} : { phase }),
         ...(currentCourt === undefined ? {} : { currentCourt }),
@@ -203,11 +191,10 @@ async function writeRoleRunStateDisk(runDirectory, disk) {
         ...(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). */
 function materializeRoleRunFromDisk(disk, authority) {
@@ -224,7 +211,6 @@ function materializeRoleRunFromDisk(disk, authority) {
                 sessionDirectory: coordinates.sessionDirectory,
                 sessionFile: coordinates.sessionFile,
                 runDirectory: disk.runDirectory,
-                admittedRequestPath: disk.admittedRequestPath,
                 ...(disk.phase === undefined ? {} : { phase: disk.phase }),
             },
         };
@@ -265,14 +251,13 @@ export async function markRunAdmitted(admitted, authority) {
         projectRoot: admitted.projectRoot,
         sessionDirectory,
         sessionFile,
-        admittedRequestPath: admitted.admittedRequestPath,
         ...(workerPhase === undefined ? {} : { phase: workerPhase }),
     });
 }
 /**
  * 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.
@@ -645,33 +630,9 @@ export async function findRunDirectoryById(home, runId, onlyBookKey, onlyRole) {
             return undefined;
         throw error;
     }
-    const matches = [];
-    for (const bookKey of bookKeys) {
-        if (onlyBookKey !== undefined && bookKey !== onlyBookKey)
-            continue;
-        const bookDir = activationBookDirectory(ledgerHome, bookKey);
-        let runDirectories;
-        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);
 }
 /** Code-owned gate inspector summons prefix (public-role-summons / #747). */
 export const GATE_DOSSIER_POINTER_PREFIX = "卷宗指针：";
@@ -688,19 +649,9 @@ export function parentRunPathFromGatePointerInstruction(instruction) {
  * Missing page → undefined; damage / non-ENOENT IO propagates.
  */
 export async function readRunParentPath(runDirectory) {
-    let raw;
-    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)) {
+    const record = readPageSync(runDirectory, "admitted");
+    if (record === undefined)
         return undefined;
-    }
-    const record = raw;
     if (typeof record.sourceRunPath === "string" && record.sourceRunPath.trim() !== "") {
         return record.sourceRunPath;
     }
@@ -723,7 +674,7 @@ async function runHasFormedSessionPrincipal(runDirectory) {
     const sessionFile = 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();
@@ -759,19 +710,15 @@ export async function findLatestRunIdForSeatTicket(input) {
             return undefined;
         throw error;
     }
-    const suffix = `@${input.role}`;
     let best;
     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)
+        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))
+        // 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)))
@@ -817,7 +764,7 @@ async function loadResumableRunRecord(home, runId, authority) {
         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 = [];
@@ -845,9 +792,10 @@ async function loadResumableRunRecord(home, runId, authority) {
     let sourceRunPath;
     let sourceRun;
     try {
-        const raw = JSON.parse(await readFile(run.admittedRequestPath, "utf8"));
-        if (isRecord(raw)) {
-            const record = raw;
+        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
                 : run.runDirectory;
@@ -888,7 +836,7 @@ async function loadResumableRunRecord(home, runId, authority) {
                 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() !== "") {
@@ -907,7 +855,7 @@ async function loadResumableRunRecord(home, runId, authority) {
                 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() !== "") {
@@ -915,9 +863,7 @@ async function loadResumableRunRecord(home, runId, authority) {
             }
             if (isRecord(record.caseIdentity)) {
                 const ci = record.caseIdentity;
-                if (typeof ci.issueNumber === "number" &&
-                    Number.isSafeInteger(ci.issueNumber) &&
-                    ci.issueNumber >= 1 &&
+                if (isSafePositiveTicketNumber(ci.issueNumber) &&
                     typeof ci.runsPath === "string" &&
                     ci.runsPath.trim() !== "") {
                     caseIdentity = { issueNumber: ci.issueNumber, runsPath: ci.runsPath };
@@ -984,9 +930,8 @@ async function loadResumableRunRecord(home, runId, authority) {
     }
     let model;
     try {
-        const invocationRaw = JSON.parse(await readFile(join(run.runDirectory, "invocation.json"), "utf8"));
-        if (isRecord(invocationRaw)) {
-            const rec = invocationRaw;
+        const rec = readPageSync(run.runDirectory, "invocation");
+        if (rec !== undefined) {
             if (typeof rec.provider === "string" && typeof rec.model === "string") {
                 model = {
                     provider: rec.provider,
@@ -1013,9 +958,9 @@ async function loadResumableRunRecord(home, runId, authority) {
             throw new CliUsageError(`role run invocation identity is unreadable: ${runId}`, { cause: error });
         }
     }
-    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, referencedRunId, run.bookKey, referencedRole);
         if (currentSourceRunDirectory !== undefined) {
@@ -1073,7 +1018,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),
     };