@akagilnc/pi-workflow-roles 0.1.5478 → 0.1.5504

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

@@ -8,11 +8,11 @@
 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";
@@ -645,33 +645,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 = "卷宗指针：";
@@ -723,7 +699,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 +735,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)))
@@ -888,7 +860,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 +879,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 +887,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 };
@@ -1013,9 +983,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) {

package/dist/public-cli/settlement.js

@@ -6,12 +6,13 @@
 import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
 import { lstat, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { sessionFileOf } from "../role-run-placement.js";
 import { writeHardenedArtifactFile } from "./auto-resume.js";
-import { readAnalystGateCyclesFromAuditorRoles, } from "../analyst-gate-cycles-read.js";
 import { sitianReport } from "../sitian-facade.js";
 import { readAttemptScopedSubmissionRows, readRecordedSubmissionRows, readRecordedSubmissions, } from "../submission-ledger.js";
 import { CONTROLLED_FAILURE_CAUSES } from "../host-contracts.js";
 import { childSignalDeathDiagnostic, processCancelDiagnostic, } from "./process-cancel.js";
+import { readStrictPiSessionJsonl } from "../ledger-session-read.js";
 import { serializeThrownValue } from "../serialize-thrown-value.js";
 import { describeErrorIdentity } from "./run-lifecycle.js";
 import { readEngineDetourToolUsage, readInvocationEngineMounted, runDirectoryFromSessionDirectory, sessionFileFromSessionDirectory, withEngineDetourToolUsageFact, } from "../engine-detour-usage.js";
@@ -19,7 +20,7 @@ import { DOCTOR_CANDIDATE_ENTRY_TYPE } from "../dossier-resolution.js";
 import { ensureRunArtifactsDir, homeFromRunDirectory, } from "./invocation.js";
 import { SECRETARIAT_COUNTERSIGN_TERMINAL_FACT_KEY, SECRETARIAT_GATE_OFFICER_ENTRY_TYPE, } from "../secretariat-contracts.js";
 import { findLatestDurablePackagedRoleTerminal, NAVIGATOR_ROUTE_PLAYBOOK_FAILURE_ENTRY, } from "../navigator-invocation-identity.js";
-import { packagedDurableOfficerEntry, packagedRoleAcceptedOutputTool, packagedRoleMetadata, packagedSkipsGateOnInfrastructureStage, } from "../packaged-role-registry.js";
+import { packagedDurableOfficerEntry, packagedRoleAcceptedOutputTool, packagedRoleMetadata, } from "../packaged-role-registry.js";
 import { NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, noReceiptLifecycleFacts, parseNoReceiptLifecycleFacts, priorReceiptContinuation, receiptAttemptPointer, } from "../receipt-delivery-policy.js";
 import { roleRunArtifactsDirectory } from "../role-run-placement.js";
 import { listSeamOwnedUniqueErrorFacePaths, uniqueErrorFallbackName, UNIQUE_ERROR_FALLBACK_STEM, RUN_TERMINAL_ARTIFACT_FILES, RUN_TERMINAL_ERROR_FALLBACK_RELATIVE_PATHS, RUN_TERMINAL_REPORT_FILE, RUN_TERMINAL_ERROR_FILE, RUN_TERMINAL_EVIDENCE_FILE, RUN_TERMINAL_ERROR_SETTLEMENT_FILE, } from "../run-terminal-artifacts.js";
@@ -123,7 +124,7 @@ export async function noteSettlementFault(runDirectory, scope, diagnostic) {
 export function ledgerReadScope(admitted, scope) {
     return {
         home: sealedLedgerHome(admitted),
-        sessionParent: join(admitted.runDirectory, "session", "session.jsonl"),
+        sessionParent: sessionFileOf(admitted.runDirectory),
         ...(scope?.courtAttemptId === undefined || scope.courtAttemptId.length === 0
             ? {}
             : { attemptId: scope.courtAttemptId }),
@@ -297,12 +298,12 @@ async function settleNoReceiptTerminal(admitted, authority, scope, facts) {
     }
     if (scope?.previewOnly !== true)
         await clearOppositeTerminalArtifactFace(admitted.runDirectory);
-    return withOptionalGateProjection({
+    return attachEngineDetourToolUsage({
         roleOutcome,
         navigator: await extractNavigatorFactFromAdmittedSession(coordinates.sessionFile, admitted.runDirectory, scope),
         artifacts: [],
         runId: admitted.runId,
-    }, coordinates.sessionDirectory, detourGateContext(admitted, scope));
+    }, coordinates.sessionDirectory, detourUsageContext(admitted, scope));
 }
 /** Transitional host-session reads remain only for non-sealed failure and audit evidence. */
 function coordinatesFromAdmitted(authority, admitted) {
@@ -638,12 +639,7 @@ export const NAVIGATOR_POST_ROLE_GRACE_MS = 10_000;
  * terminal note it; they do not relabel it as a host session cause.
  */
 export async function readBoundSessionEntries(sessionFile) {
-    const text = await readFile(sessionFile, "utf8");
-    const entries = [];
-    for (const line of text.trim().split("\n").filter(Boolean)) {
-        entries.push(JSON.parse(line));
-    }
-    return entries;
+    return await readStrictPiSessionJsonl(sessionFile);
 }
 /**
  * #419 per-attempt process history. 史必追加，指针可覆盖；指针可以覆盖的前提是史已落。
@@ -737,61 +733,6 @@ function parseNavigatorAttendanceDetails(details) {
         reason: "Navigator attendance disposition is unparseable",
     };
 }
-/**
- * Project direct and historical paired gate rounds onto the public Terminal.
- * actualSeats derive only from accepted receipts, never expected/missing seats.
- */
-export function projectTerminalGateFact(rounds) {
-    if (rounds.length === 0)
-        return undefined;
-    const seen = new Set();
-    for (const round of rounds) {
-        if (round.origin.kind === "historical_dispatch")
-            seen.add("gatekeeper");
-        seen.add(round.officer);
-    }
-    const actualSeats = ["gatekeeper", "inspector", "notary"].filter((seat) => seen.has(seat));
-    return {
-        actualSeats,
-        rounds: rounds.map((round) => ({
-            roundIndex: round.roundIndex,
-            dispatch: round.origin.kind === "direct"
-                ? { kind: "direct", officer: round.officer }
-                : {
-                    kind: "historical_dispatch",
-                    officer: round.officer,
-                    ...(round.origin.reason === undefined
-                        ? {}
-                        : { reason: round.origin.reason }),
-                },
-            officer: {
-                seat: round.officer,
-                status: round.status,
-                findings: round.findings,
-            },
-        })),
-    };
-}
-/**
- * Read gate facts from the run's session/auditor-roles nest (#446/#478).
- * Missing directories → undefined (no-gate zero change).
- * Damaged discovered volumes propagate — never wash to "no gate".
- */
-export async function extractGateFactFromSessionDirectory(sessionDirectory, options = {}) {
-    const directories = [join(sessionDirectory, "auditor-roles")];
-    const parentSessionFile = options.parentSessionFile ?? join(sessionDirectory, "session.jsonl");
-    const rounds = await readAnalystGateCyclesFromAuditorRoles(directories, {
-        parentSessionFile,
-    });
-    return projectTerminalGateFact(rounds);
-}
-/**
- * Attach optional gate projection onto a settled Terminal base.
- * Shared by every settle path so auditor-roles is scanned once here only.
- * `runId` is optional only for a batch projection that has no parent run.
- * Gate read damage is a package note beside the host terminal. It does not
- * replace that terminal and it does not omit the gate without a trace.
- */
 /**
  * #537: project this-invocation ak_engine_detour usage onto decisiveFacts.
  * Absent when engine is not mounted; callCount 0 when mounted with zero calls.
@@ -800,27 +741,27 @@ export async function extractGateFactFromSessionDirectory(sessionDirectory, opti
  * courtAttemptId and never Pi session.jsonl toolResult join. Session damage
  * therefore cannot replace an already-formed roleOutcome (no_receipt / failure).
  */
-async function attachEngineDetourToolUsage(base, sessionDirectory, gateContext = {}) {
-    const runDirectory = typeof gateContext.runDirectory === "string" && gateContext.runDirectory.length > 0
-        ? gateContext.runDirectory
+async function attachEngineDetourToolUsage(base, sessionDirectory, detourContext = {}) {
+    const runDirectory = typeof detourContext.runDirectory === "string" && detourContext.runDirectory.length > 0
+        ? detourContext.runDirectory
         : runDirectoryFromSessionDirectory(sessionDirectory);
     let engineMounted = false;
     try {
         engineMounted = await readInvocationEngineMounted(runDirectory);
     }
     catch (error) {
-        await noteSettlementFault(runDirectory, gateContext.notePackageFault === undefined
+        await noteSettlementFault(runDirectory, detourContext.notePackageFault === undefined
             ? undefined
-            : { notePackageFault: gateContext.notePackageFault }, `engine mount read failed beside host terminal: ${describeErrorIdentity(error)}`);
+            : { notePackageFault: detourContext.notePackageFault }, `engine mount read failed beside host terminal: ${describeErrorIdentity(error)}`);
         return base;
     }
     if (!engineMounted)
         return base;
     // Public-invocation scope from the shared Host envelope (settlement scope), never
     // courtAttemptId and never a detour sidecar file.
-    const invocationScopeId = typeof gateContext.invocationScopeId === "string" &&
-        gateContext.invocationScopeId.length > 0
-        ? gateContext.invocationScopeId
+    const invocationScopeId = typeof detourContext.invocationScopeId === "string" &&
+        detourContext.invocationScopeId.length > 0
+        ? detourContext.invocationScopeId
         : undefined;
     const sessionFile = sessionFileFromSessionDirectory(sessionDirectory);
     let usage;
@@ -833,9 +774,9 @@ async function attachEngineDetourToolUsage(base, sessionDirectory, gateContext =
         });
     }
     catch (error) {
-        await noteSettlementFault(runDirectory, gateContext.notePackageFault === undefined
+        await noteSettlementFault(runDirectory, detourContext.notePackageFault === undefined
             ? undefined
-            : { notePackageFault: gateContext.notePackageFault }, `engine detour read failed beside host terminal: ${describeErrorIdentity(error)}`);
+            : { notePackageFault: detourContext.notePackageFault }, `engine detour read failed beside host terminal: ${describeErrorIdentity(error)}`);
         return base;
     }
     return {
@@ -843,45 +784,16 @@ async function attachEngineDetourToolUsage(base, sessionDirectory, gateContext =
         roleOutcome: withEngineDetourToolUsageFact(base.roleOutcome, usage),
     };
 }
-/** Gate + detour projection context from admitted run + settlement scope. */
-function detourGateContext(admitted, scope) {
+/** Engine-detour usage context from admitted run + settlement scope. */
+function detourUsageContext(admitted, scope) {
     return {
         runDirectory: admitted.runDirectory,
-        ...(scope?.courtAttemptId === undefined || scope.courtAttemptId.length === 0
-            ? {}
-            : { courtAttemptId: scope.courtAttemptId }),
         ...(scope?.invocationScopeId === undefined || scope.invocationScopeId.length === 0
             ? {}
             : { invocationScopeId: scope.invocationScopeId }),
         ...(scope?.notePackageFault === undefined ? {} : { notePackageFault: scope.notePackageFault }),
     };
 }
-async function withOptionalGateProjection(base, sessionDirectory, gateContext = {}) {
-    // A gate transport failure is already represented by typed evidence and has no
-    // accepted gate cycle to project. Re-reading that rejected receipt as an
-    // accepted cycle would replace the original failure with a projection error.
-    const secondaryEvidence = base.roleOutcome.kind === "failure"
-        ? base.roleOutcome.decisiveFacts.secondaryEvidence
-        : undefined;
-    const skipGate = isRecord(secondaryEvidence)
-        && secondaryEvidence.kind === "role_infrastructure_failure"
-        && packagedSkipsGateOnInfrastructureStage(secondaryEvidence.stage);
-    let next = base;
-    if (!skipGate) {
-        try {
-            const gate = await extractGateFactFromSessionDirectory(sessionDirectory, gateContext);
-            if (gate !== undefined)
-                next = { ...base, gate };
-        }
-        catch (error) {
-            const runDirectory = gateContext.runDirectory ?? runDirectoryFromSessionDirectory(sessionDirectory);
-            await noteSettlementFault(runDirectory, gateContext.notePackageFault === undefined
-                ? undefined
-                : { notePackageFault: gateContext.notePackageFault }, `gate read failed beside host terminal: ${describeErrorIdentity(error)}`);
-        }
-    }
-    return attachEngineDetourToolUsage(next, sessionDirectory, gateContext);
-}
 function routePlaybookFailureMessage(entries) {
     for (let i = entries.length - 1; i >= 0; i -= 1) {
         const entry = entries[i];
@@ -1071,12 +983,12 @@ async function finishLawfulSeat(admitted, coordinates, entries, roleOutcome, sco
     const artifacts = scope?.previewOnly === true
         ? []
         : await publishDeclaredSeatArtifacts(admitted, roleOutcome, coordinates, entries, scope?.recordAttemptHistory === true);
-    const terminal = await withOptionalGateProjection({
+    const terminal = await attachEngineDetourToolUsage({
         roleOutcome,
         navigator: extractNavigatorFact(entries),
         artifacts,
         runId: admitted.runId,
-    }, coordinates.sessionDirectory, detourGateContext(admitted, scope));
+    }, coordinates.sessionDirectory, detourUsageContext(admitted, scope));
     return attachRecordedSubmissions(admitted, terminal, scope);
 }
 /**
@@ -1317,26 +1229,14 @@ async function applySecretariatCountersignTerminal(admitted, authority, settled,
     return settled;
 }
 /**
- * After the audit gate returns, attach gate rounds and the secretariat officer
- * fact onto the terminal this turn already settled. Does not publish again —
- * a second publish would append another attempt-history row for the same attempt.
+ * After the audit gate returns, attach the secretariat officer fact onto the
+ * terminal this turn already settled. Does not publish again — a second publish
+ * would append another attempt-history row for the same attempt.
  */
-export async function attachPostAuditProjection(admitted, authority, terminal, scope) {
-    const { sessionDirectory, sessionFile } = coordinatesFromAdmitted(authority, admitted);
-    let gate;
-    try {
-        gate = await extractGateFactFromSessionDirectory(sessionDirectory, {
-            runDirectory: admitted.runDirectory,
-            parentSessionFile: sessionFile,
-        });
-    }
-    catch (error) {
-        await noteSettlementFault(admitted.runDirectory, scope, `gate read failed beside host terminal: ${describeErrorIdentity(error)}`);
-    }
-    const withGate = gate === undefined ? terminal : { ...terminal, gate };
+export async function attachPostAuditCountersignFact(admitted, authority, terminal, scope) {
     if (admitted.role !== "secretariat")
-        return withGate;
-    return applySecretariatCountersignTerminal(admitted, authority, withGate, scope);
+        return terminal;
+    return applySecretariatCountersignTerminal(admitted, authority, terminal, scope);
 }
 function publicationAttemptFromError(path, error) {
     if (error instanceof Error) {
@@ -1538,7 +1438,7 @@ export async function settleFailureTerminalResult(admitted, failure, authority,
         diagnostic: failure.diagnostic,
         decisiveFacts,
     };
-    return withOptionalGateProjection({ roleOutcome, navigator, artifacts, runId: admitted.runId }, sessionDirectory, detourGateContext(admitted, options));
+    return attachEngineDetourToolUsage({ roleOutcome, navigator, artifacts, runId: admitted.runId }, sessionDirectory, detourUsageContext(admitted, options));
 }
 /**
  * Emit one complete failure Terminal on stdout and one concise stderr diagnostic.

package/dist/public-cli/terminal.js

@@ -85,18 +85,6 @@ export function formatTerminalResult(result) {
     for (const artifact of result.artifacts) {
         lines.push(`artifact\t${artifact.kind}\t${encodeTerminalField(artifact.path)}`);
     }
-    // Gate region is unfrozen presentation of typed facts (ADR 0052) — machines
-    // read result.gate, never these row labels.
-    if (result.gate !== undefined) {
-        lines.push(`gate\t${encodeTerminalField(result.gate.actualSeats.join(","))}\t${result.gate.rounds.length}`);
-        for (const round of result.gate.rounds) {
-            const reason = round.dispatch.kind === "historical_dispatch"
-                && round.dispatch.reason !== undefined
-                ? encodeTerminalField(round.dispatch.reason)
-                : "";
-            lines.push(`gate-round\t${round.roundIndex}\t${round.dispatch.kind}\t${round.dispatch.officer}\t${reason}\t${round.officer.seat}\t${encodeTerminalField(round.officer.status)}\t${encodeTerminalField(JSON.stringify(round.officer.findings))}`);
-        }
-    }
     if (result.reviewerChildOutcomes !== undefined) {
         for (const axis of ["completeness", "correctness"]) {
             const child = result.reviewerChildOutcomes[axis];

package/dist/role-run-placement.js

@@ -1,11 +1,35 @@
 import { readdir } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import {
   activationBookDirectory,
   ensureRealDirectoryTree
 } from "./activation-ledger-topology.js";
 import { requireSafePositiveTicketNumber } from "./run-ticket-number.js";
 import { isEnoent } from "./unknown-value.js";
+function formatRunLeaf(runId, role) {
+  return `${runId}@${role}`;
+}
+function parseRunLeaf(name) {
+  const at = name.lastIndexOf("@");
+  if (at <= 0 || at === name.length - 1) return void 0;
+  return { runId: name.slice(0, at), role: name.slice(at + 1) };
+}
+function sessionDirectoryOf(runDirectory) {
+  return join(runDirectory, "session");
+}
+const ROLE_RUN_SESSION_FILENAME = "session.jsonl";
+function sessionFileIn(sessionDirectory) {
+  return join(sessionDirectory, ROLE_RUN_SESSION_FILENAME);
+}
+function sessionFileOf(runDirectory) {
+  return sessionFileIn(sessionDirectoryOf(runDirectory));
+}
+function runDirectoryOfSessionFile(sessionFile) {
+  return dirname(dirname(sessionFile));
+}
+function runDirectoryFromSessionDirectory(sessionDirectory) {
+  return dirname(sessionDirectory);
+}
 async function listBookRunDirectories(bookDir) {
   const out = [];
   const seen = /* @__PURE__ */ new Set();
@@ -39,6 +63,20 @@ async function listBookRunDirectories(bookDir) {
   }
   return out.sort();
 }
+async function findRoleRunDirectory(bookDirectories, runId, onlyRole) {
+  const matches = [];
+  for (const bookDirectory of bookDirectories) {
+    for (const runDirectory of await listBookRunDirectories(bookDirectory)) {
+      const parsed = parseRunLeaf(basename(runDirectory));
+      if (parsed === void 0 || parsed.runId !== runId) continue;
+      if (onlyRole !== void 0 && parsed.role !== onlyRole) continue;
+      matches.push(runDirectory);
+    }
+  }
+  if (matches.length === 0) return void 0;
+  if (matches.length === 1) return matches[0];
+  throw new Error(`ambiguous role run id ${runId}: ${matches.join(", ")}`);
+}
 function roleRunPlacement(ledgerHome, input) {
   const subjectDirectory = "ticketNumber" in input.subject ? String(requireSafePositiveTicketNumber(
     input.subject.ticketNumber,
@@ -48,13 +86,13 @@ function roleRunPlacement(ledgerHome, input) {
     activationBookDirectory(ledgerHome, input.bookKey),
     subjectDirectory,
     "runs",
-    `${input.runId}@${input.role}`
+    formatRunLeaf(input.runId, input.role)
   );
-  const sessionDirectory = join(runDirectory, "session");
+  const sessionDirectory = sessionDirectoryOf(runDirectory);
   return {
     runDirectory,
     sessionDirectory,
-    sessionFile: join(sessionDirectory, "session.jsonl"),
+    sessionFile: sessionFileIn(sessionDirectory),
     artifactsDirectory: roleRunArtifactsDirectory(runDirectory),
     attachmentsDirectory: join(runDirectory, "attachments")
   };
@@ -77,10 +115,19 @@ function ensureRoleRunPlacement(ledgerHome, placement) {
   }
 }
 export {
+  ROLE_RUN_SESSION_FILENAME,
   ensureRoleRunDirectory,
   ensureRoleRunPlacement,
+  findRoleRunDirectory,
+  formatRunLeaf,
   isUnboundRunDirectory,
   listBookRunDirectories,
+  parseRunLeaf,
   roleRunArtifactsDirectory,
-  roleRunPlacement
+  roleRunPlacement,
+  runDirectoryFromSessionDirectory,
+  runDirectoryOfSessionFile,
+  sessionDirectoryOf,
+  sessionFileIn,
+  sessionFileOf
 };

package/dist/role-run-relocation.js

@@ -1,6 +1,6 @@
 /**
  * Single authority for rewriting durable run pages after a run directory moves.
- * Live unbound→ticket relocate and book-topology migration both call this.
+ * Live callers project typed fields; only historical migrators walk durable pages.
  *
  * Scope is typed machine-consumed path fields only — never free text, never
  * frozen attachment/artifact bytes. Nested walk is confined to package-owned
@@ -8,7 +8,10 @@
  */
 import { existsSync } from "node:fs";
 import { readdir, readFile, writeFile } from "node:fs/promises";
-import { join, sep } from "node:path";
+import { dirname, join, sep } from "node:path";
+import { activationBookDirectory, physicalPathIdentity } from "./activation-ledger-topology.js";
+import { readRoleRunIdentity } from "./public-cli/run-lifecycle.js";
+import { findRoleRunDirectory, roleRunPlacement } from "./role-run-placement.js";
 import { AUDITOR_PARENT_ATTEMPT_BINDING_ENTRY_TYPE } from "./compliance-transport.js";
 import { isRecord, isEnoent } from "./unknown-value.js";
 const ADMITTED_PAGE_FIELDS = [
@@ -52,6 +55,40 @@ export function rewriteRunDirectoryPathValue(value, oldRunDirectory, newRunDirec
     }
     return value;
 }
+/** Match physical aliases or a normal unbound→ticket bind, never historical migration layouts. */
+export async function retainedRunPathsMatch(recordedPath, currentPath, currentRunDirectory) {
+    if (recordedPath === currentPath)
+        return true;
+    if (typeof recordedPath !== "string")
+        return false;
+    const recordedPathIdentity = physicalPathIdentity(recordedPath);
+    const currentPathIdentity = physicalPathIdentity(currentPath);
+    if (recordedPathIdentity === currentPathIdentity)
+        return true;
+    if (currentRunDirectory === undefined)
+        return false;
+    const runDirectory = physicalPathIdentity(currentRunDirectory);
+    const identity = await readRoleRunIdentity(runDirectory);
+    if (identity === undefined)
+        return false;
+    for (let directory = runDirectory; dirname(directory) !== directory; directory = dirname(directory)) {
+        const ledgerHome = dirname(dirname(directory));
+        if (directory !== activationBookDirectory(ledgerHome, identity.bookKey))
+            continue;
+        const unbound = roleRunPlacement(ledgerHome, {
+            bookKey: identity.bookKey,
+            subject: { unbound: true },
+            runId: identity.runId,
+            role: identity.role,
+        });
+        if (rewriteRunDirectoryPathValue(recordedPathIdentity, unbound.runDirectory, runDirectory) !== currentPathIdentity) {
+            return false;
+        }
+        const placed = await findRoleRunDirectory([directory], identity.runId, identity.role);
+        return placed !== undefined && physicalPathIdentity(placed) === runDirectory;
+    }
+    return false;
+}
 /**
  * Apply the longest matching oldRunDirectory rewrite. Longer keys win so a
  * nested run path is not partially claimed by a shorter sibling prefix.

package/dist/run-terminal-artifacts.js

@@ -9,7 +9,7 @@
 import { randomUUID } from "node:crypto";
 import { readdir, readFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import { roleRunArtifactsDirectory } from "./role-run-placement.js";
+import { parseRunLeaf, roleRunArtifactsDirectory } from "./role-run-placement.js";
 import { isRecord, errorText, isMissingPathError } from "./unknown-value.js";
 export const RUN_TERMINAL_REPORT_FILE = "report.json";
 export const RUN_TERMINAL_ERROR_FILE = "error.json";
@@ -126,11 +126,7 @@ async function listUniqueErrorFallbackPaths(directories) {
  * Sole authority for runDirectory → runId (last `@` split).
  */
 export function runIdFromRunDirectory(runDirectory) {
-    const name = basename(runDirectory);
-    const at = name.lastIndexOf("@");
-    if (at <= 0 || at === name.length - 1)
-        return undefined;
-    return name.slice(0, at);
+    return parseRunLeaf(basename(runDirectory))?.runId;
 }
 /**
  * Shared parent-directory unique fallback may be adopted only when the

package/dist/run-ticket-number.js

@@ -2,8 +2,33 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { isEnoent, isRecord } from "./unknown-value.js";
 const MIGRATION_TICKET_DERIVATION_PAGE = "migration-ticket-derivation.json";
+function isPositiveTicketNumber(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1;
+}
 function isSafePositiveTicketNumber(value) {
-  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+  return isPositiveTicketNumber(value) && Number.isSafeInteger(value);
+}
+function isTicketNumberString(value) {
+  return typeof value === "string" && /^[1-9][0-9]*$/.test(value);
+}
+function parseTicketNumber(value) {
+  if (isSafePositiveTicketNumber(value)) return value;
+  if (!isTicketNumberString(value)) return void 0;
+  const parsed = Number(value);
+  return isSafePositiveTicketNumber(parsed) ? parsed : void 0;
+}
+function sitianSubjectTicketNumber(subject) {
+  if (typeof subject === "string" || typeof subject === "number") {
+    return parseTicketNumber(subject);
+  }
+  if (subject !== null && typeof subject === "object" && !Array.isArray(subject)) {
+    return parseTicketNumber(subject.ticketNumber);
+  }
+  return void 0;
+}
+function ticketNumberFromSitianSubject(subject) {
+  const parsed = sitianSubjectTicketNumber(subject);
+  return parsed === void 0 ? void 0 : String(parsed);
 }
 function readDeclaredTicketNumber(value) {
   if (isSafePositiveTicketNumber(value)) return value;
@@ -11,8 +36,7 @@ function readDeclaredTicketNumber(value) {
   const trimmed = value.trim();
   const match = /^#?([1-9]\d*)(?!\.\d)(?:\b|$)/.exec(trimmed);
   if (match === null) return void 0;
-  const ticketNumber = Number(match[1]);
-  return isSafePositiveTicketNumber(ticketNumber) ? ticketNumber : void 0;
+  return parseTicketNumber(match[1]);
 }
 function requireSafePositiveTicketNumber(ticketNumber, context = "ticketNumber") {
   if (!isSafePositiveTicketNumber(ticketNumber)) {
@@ -58,10 +82,15 @@ async function readRunTicketNumber(runDirectory) {
 }
 export {
   MIGRATION_TICKET_DERIVATION_PAGE,
+  isPositiveTicketNumber,
   isSafePositiveTicketNumber,
+  isTicketNumberString,
+  parseTicketNumber,
   readBoardTicketNumber,
   readDeclaredTicketNumber,
   readMigrationDerivedTicketNumber,
   readRunTicketNumber,
-  requireSafePositiveTicketNumber
+  requireSafePositiveTicketNumber,
+  sitianSubjectTicketNumber,
+  ticketNumberFromSitianSubject
 };