@akagilnc/pi-workflow-roles 0.1.1817 → 0.1.1837

package/src/public-cli/invocation.ts

@@ -19,6 +19,7 @@ import {
   resolveActivationLedgerHome,
 } from "../activation-ledger-topology.ts";
 import { resolveBookKeyFromGit } from "../activation-ledger-git.ts";
+import { roleRunSessionCoordinates } from "../sitian-role-run-coordinates.ts";
 import {
   loadDoctorCase,
 } from "../doctor-evidence.ts";
@@ -57,14 +58,6 @@ export type FrozenAttachment = {
   readonly mediaKind: "regular-file";
 };
 
-/** Durable Pi session file principal name under a Role run's private session directory. */
-export const ROLE_RUN_SESSION_FILE_NAME = "session.jsonl" as const;
-
-/** Exact Pi session file principal path for a Role run session directory. */
-export function roleRunSessionFile(sessionDirectory: string): string {
-  return join(sessionDirectory, ROLE_RUN_SESSION_FILE_NAME);
-}
-
 /** Shared admitted Role run identity (#106 common Invocation + #109 Coder). */
 export type AdmittedRoleInvocationBase = {
   readonly runId: string;
@@ -583,16 +576,9 @@ export async function admitJudgeInvocation(
     requireOptionPath("--project", options.project);
   }
   const projectRoot = resolve(options.project ?? options.cwd);
-  const bookKey = resolveBookKeyFromGit(projectRoot);
-  const ledgerHome = resolveActivationLedgerHome(() => options.home);
   const runId = (options.createRunId ?? uuidv7)();
-  const runDirectory = join(
-    activationBookDirectory(ledgerHome, bookKey),
-    "runs",
-    `${runId}@judge`,
-  );
-  const sessionDirectory = join(runDirectory, "session");
-  const sessionFile = roleRunSessionFile(sessionDirectory);
+  const { ledgerHome, bookKey, runDirectory, sessionDirectory, sessionFile } =
+    roleRunSessionCoordinates({ cwd: projectRoot, runId, role: "judge", home: options.home });
   const attachmentsDirectory = join(runDirectory, "attachments");
   ensureRealDirectoryTree(ledgerHome, sessionDirectory);
   ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
@@ -728,16 +714,9 @@ export async function admitCoderInvocation(
   }
 
   const projectRoot = resolve(options.project ?? options.cwd);
-  const bookKey = resolveBookKeyFromGit(projectRoot);
-  const ledgerHome = resolveActivationLedgerHome(() => options.home);
   const runId = (options.createRunId ?? uuidv7)();
-  const runDirectory = join(
-    activationBookDirectory(ledgerHome, bookKey),
-    "runs",
-    `${runId}@coder`,
-  );
-  const sessionDirectory = join(runDirectory, "session");
-  const sessionFile = roleRunSessionFile(sessionDirectory);
+  const { ledgerHome, bookKey, runDirectory, sessionDirectory, sessionFile } =
+    roleRunSessionCoordinates({ cwd: projectRoot, runId, role: "coder", home: options.home });
   const attachmentsDirectory = join(runDirectory, "attachments");
   ensureRealDirectoryTree(ledgerHome, sessionDirectory);
   ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
@@ -850,16 +829,9 @@ export async function admitFixerInvocation(
   }
 
   const projectRoot = resolve(options.project ?? options.cwd);
-  const bookKey = resolveBookKeyFromGit(projectRoot);
-  const ledgerHome = resolveActivationLedgerHome(() => options.home);
   const runId = (options.createRunId ?? uuidv7)();
-  const runDirectory = join(
-    activationBookDirectory(ledgerHome, bookKey),
-    "runs",
-    `${runId}@fixer`,
-  );
-  const sessionDirectory = join(runDirectory, "session");
-  const sessionFile = roleRunSessionFile(sessionDirectory);
+  const { ledgerHome, bookKey, runDirectory, sessionDirectory, sessionFile } =
+    roleRunSessionCoordinates({ cwd: projectRoot, runId, role: "fixer", home: options.home });
   const attachmentsDirectory = join(runDirectory, "attachments");
   ensureRealDirectoryTree(ledgerHome, sessionDirectory);
   ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
@@ -1131,16 +1103,9 @@ export async function admitCollectorInvocation(
     repository = resolveGitHubRemoteRepository(projectRoot);
   }
 
-  const bookKey = resolveBookKeyFromGit(projectRoot);
-  const ledgerHome = resolveActivationLedgerHome(() => options.home);
   const runId = (options.createRunId ?? uuidv7)();
-  const runDirectory = join(
-    activationBookDirectory(ledgerHome, bookKey),
-    "runs",
-    `${runId}@collector`,
-  );
-  const sessionDirectory = join(runDirectory, "session");
-  const sessionFile = roleRunSessionFile(sessionDirectory);
+  const { ledgerHome, bookKey, runDirectory, sessionDirectory, sessionFile } =
+    roleRunSessionCoordinates({ cwd: projectRoot, runId, role: "collector", home: options.home });
   const attachmentsDirectory = join(runDirectory, "attachments");
   ensureRealDirectoryTree(ledgerHome, sessionDirectory);
   ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
@@ -1449,8 +1414,9 @@ export async function admitDoctorInvocation(
   }
 
   const projectRoot = resolve(options.project ?? options.cwd);
-  const bookKey = resolveBookKeyFromGit(projectRoot);
-  const ledgerHome = resolveActivationLedgerHome(() => options.home);
+  const runId = (options.createRunId ?? uuidv7)();
+  const { ledgerHome, bookKey, runDirectory, sessionDirectory, sessionFile } =
+    roleRunSessionCoordinates({ cwd: projectRoot, runId, role: "doctor", home: options.home });
 
   let caseRunsPath: string;
   try {
@@ -1492,14 +1458,6 @@ export async function admitDoctorInvocation(
     );
   }
 
-  const runId = (options.createRunId ?? uuidv7)();
-  const runDirectory = join(
-    activationBookDirectory(ledgerHome, bookKey),
-    "runs",
-    `${runId}@doctor`,
-  );
-  const sessionDirectory = join(runDirectory, "session");
-  const sessionFile = roleRunSessionFile(sessionDirectory);
   const attachmentsDirectory = join(runDirectory, "attachments");
   ensureRealDirectoryTree(ledgerHome, sessionDirectory);
   ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
@@ -1659,16 +1617,9 @@ export async function admitReviewerInvocation(
   }
 
   const projectRoot = resolve(options.project ?? options.cwd);
-  const bookKey = resolveBookKeyFromGit(projectRoot);
-  const ledgerHome = resolveActivationLedgerHome(() => options.home);
   const runId = (options.createRunId ?? uuidv7)();
-  const runDirectory = join(
-    activationBookDirectory(ledgerHome, bookKey),
-    "runs",
-    `${runId}@reviewer`,
-  );
-  const sessionDirectory = join(runDirectory, "session");
-  const sessionFile = roleRunSessionFile(sessionDirectory);
+  const { ledgerHome, bookKey, runDirectory, sessionDirectory, sessionFile } =
+    roleRunSessionCoordinates({ cwd: projectRoot, runId, role: "reviewer", home: options.home });
   const attachmentsDirectory = join(runDirectory, "attachments");
   ensureRealDirectoryTree(ledgerHome, sessionDirectory);
   ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
@@ -1887,16 +1838,9 @@ export async function admitMergerInvocation(
     options.gitState ?? createProductionMergerGitState(projectRoot),
   );
 
-  const bookKey = resolveBookKeyFromGit(projectRoot);
-  const ledgerHome = resolveActivationLedgerHome(() => options.home);
   const runId = (options.createRunId ?? uuidv7)();
-  const runDirectory = join(
-    activationBookDirectory(ledgerHome, bookKey),
-    "runs",
-    `${runId}@merger`,
-  );
-  const sessionDirectory = join(runDirectory, "session");
-  const sessionFile = roleRunSessionFile(sessionDirectory);
+  const { ledgerHome, bookKey, runDirectory, sessionDirectory, sessionFile } =
+    roleRunSessionCoordinates({ cwd: projectRoot, runId, role: "merger", home: options.home });
   const attachmentsDirectory = join(runDirectory, "attachments");
   ensureRealDirectoryTree(ledgerHome, sessionDirectory);
   ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);

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

@@ -6,12 +6,8 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 
-import { resolveBookKeyFromGit } from "../activation-ledger-git.ts";
-import {
-  activationBookDirectory,
-  ensureRealDirectoryTree,
-  resolveActivationLedgerHome,
-} from "../activation-ledger-topology.ts";
+import { ensureRealDirectoryTree } from "../activation-ledger-topology.ts";
+import { roleRunSessionCoordinates } from "../sitian-role-run-coordinates.ts";
 import {
   loadPackagedMethodSkillMaterial,
   resolvePackagedMethodSkillPath,
@@ -30,7 +26,6 @@ import {
   admitMergerInvocation,
   buildMergerTransportPrompt,
   MergerEnvelopeDerivationError,
-  roleRunSessionFile,
   type AdmittedMergerInvocation,
 } from "./invocation.ts";
 import {
@@ -414,16 +409,9 @@ async function admitMergerShellForActivationFailure(options: {
   createRunId?: () => string;
 }): Promise<AdmittedMergerInvocation> {
   const projectRoot = resolve(options.project ?? options.cwd);
-  const bookKey = resolveBookKeyFromGit(projectRoot);
-  const ledgerHome = resolveActivationLedgerHome(() => options.home);
   const runId = (options.createRunId ?? uuidv7)();
-  const runDirectory = join(
-    activationBookDirectory(ledgerHome, bookKey),
-    "runs",
-    `${runId}@merger`,
-  );
-  const sessionDirectory = join(runDirectory, "session");
-  const sessionFile = roleRunSessionFile(sessionDirectory);
+  const { ledgerHome, bookKey, runDirectory, sessionDirectory, sessionFile } =
+    roleRunSessionCoordinates({ cwd: projectRoot, runId, role: "merger", home: options.home });
   ensureRealDirectoryTree(ledgerHome, sessionDirectory);
   await mkdir(runDirectory, { recursive: true });
   const emptyDerived = {

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

@@ -15,7 +15,6 @@ import { CliUsageError } from "./cli-errors.ts";
 import type { FixerPhase } from "../package-contracts/fixer-output.ts";
 import type { FixerPrerequisite } from "../package-contracts/fixer-packet.ts";
 import {
-  roleRunSessionFile,
   type AdmittedCoderInvocation,
   type AdmittedFixerInvocation,
   type AdmittedJudgeInvocation,
@@ -187,10 +186,12 @@ export async function writeRoleRunState(
 export async function readRoleRunState(
   runDirectory: string,
 ): Promise<RoleRunRecord | undefined> {
+  let raw: unknown;
   try {
-    const raw: unknown = JSON.parse(
-      await readFile(join(runDirectory, RUN_STATE_FILE), "utf8"),
-    );
+    raw = JSON.parse(await readFile(join(runDirectory, RUN_STATE_FILE), "utf8"));
+  } catch {
+    return undefined;
+  }
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
       return undefined;
     }
@@ -225,12 +226,12 @@ export async function readRoleRunState(
       typeof record.runDirectory === "string" && record.runDirectory.trim() !== ""
         ? record.runDirectory
         : runDirectory;
-    // Prefer durable principal; fall back only for in-progress records that
-    // predate the field but still own a private session directory.
+    // Legacy states predate sessionFile. Their persisted session directory is
+    // the authority for the historical principal, even if project topology moved.
     const sessionFile =
       typeof record.sessionFile === "string" && record.sessionFile.trim() !== ""
         ? record.sessionFile
-        : roleRunSessionFile(record.sessionDirectory);
+        : join(record.sessionDirectory, "session.jsonl");
     let resumable: TypedHttp429Observation | undefined;
     if (record.resumable !== undefined && record.resumable !== null) {
       if (
@@ -264,9 +265,6 @@ export async function readRoleRunState(
       ...(phase === undefined ? {} : { phase }),
       ...(resumable === undefined ? {} : { resumable }),
     };
-  } catch {
-    return undefined;
-  }
 }
 
 export async function markRunAdmitted(

package/src/receipt-delivery-policy.ts

@@ -7,7 +7,7 @@ export const NO_RECEIPT_LIFECYCLE_ENTRY_TYPE = "ak-no-receipt-lifecycle" as cons
 /** The sole schema shared by lifecycle owners and Terminal projections. */
 export type NoReceiptLifecycleFacts = {
   terminalToolCalled: boolean;
-  rejectedReceipts: readonly { reason: string }[];
+  rejectedReceipts: readonly { reason: string; diagnosticAvailable: boolean }[];
   deliveryTurns: typeof RECEIPT_DELIVERY_TURN_LIMIT;
   sessionCompletion: "settled-without-accepted-receipt";
   runPointer: string;
@@ -30,12 +30,15 @@ export function parseNoReceiptLifecycleFacts(input: unknown): NoReceiptLifecycle
     || typeof input.attemptPointer !== "string" || input.attemptPointer.trim() === ""
     || !Array.isArray(input.rejectedReceipts)
     || !input.rejectedReceipts.every((item) => isRecord(item)
-      && typeof item.reason === "string" && item.reason.trim() !== "")) {
+      && typeof item.reason === "string")) {
     throw new TypeError("malformed no-receipt lifecycle facts");
   }
   return {
     terminalToolCalled: input.terminalToolCalled,
-    rejectedReceipts: input.rejectedReceipts.map((item) => ({ reason: item.reason as string })),
+    rejectedReceipts: input.rejectedReceipts.map((item) => ({
+      reason: item.reason as string,
+      diagnosticAvailable: (item.reason as string).trim() !== "",
+    })),
     deliveryTurns: RECEIPT_DELIVERY_TURN_LIMIT,
     sessionCompletion: "settled-without-accepted-receipt",
     runPointer: input.runPointer,
@@ -45,14 +48,20 @@ export function parseNoReceiptLifecycleFacts(input: unknown): NoReceiptLifecycle
 }
 
 export function noReceiptLifecycleFacts(
-  input: Omit<NoReceiptLifecycleFacts, "deliveryTurns" | "sessionCompletion" | "acceptedReceipt"> & { deliveryTurns: number },
+  input: Omit<NoReceiptLifecycleFacts, "rejectedReceipts" | "deliveryTurns" | "sessionCompletion" | "acceptedReceipt"> & {
+    rejectedReceipts: readonly { reason: string }[];
+    deliveryTurns: number;
+  },
 ): NoReceiptLifecycleFacts {
   if (input.deliveryTurns !== RECEIPT_DELIVERY_TURN_LIMIT) {
     throw new TypeError("no-receipt lifecycle requires an exhausted delivery budget");
   }
   return {
     terminalToolCalled: input.terminalToolCalled,
-    rejectedReceipts: input.rejectedReceipts.map(({ reason }) => ({ reason })),
+    rejectedReceipts: input.rejectedReceipts.map(({ reason }) => ({
+      reason,
+      diagnosticAvailable: reason.trim() !== "",
+    })),
     deliveryTurns: RECEIPT_DELIVERY_TURN_LIMIT,
     sessionCompletion: "settled-without-accepted-receipt",
     runPointer: input.runPointer,
@@ -65,14 +74,17 @@ export function createReceiptDeliveryPolicy() {
   let accepted = false;
   let terminalToolCalled = false;
   let deliveryTurns = 0;
-  const rejectedReceipts: { reason: string }[] = [];
+  const rejectedReceipts: { reason: string; diagnosticAvailable: boolean }[] = [];
   return {
-    recordAccepted() { accepted = true; terminalToolCalled = true; },
+    recordAccepted() {
+      accepted = true;
+      terminalToolCalled = true;
+    },
     /** Infrastructure owns terminality and must never trigger receipt催交. */
     stopForInfrastructure() { accepted = true; },
     recordRejected(reason: string) {
       terminalToolCalled = true;
-      rejectedReceipts.push({ reason });
+      rejectedReceipts.push({ reason, diagnosticAvailable: reason.trim() !== "" });
       deliveryTurns = Math.min(RECEIPT_DELIVERY_TURN_LIMIT, deliveryTurns + 1);
     },
     recordDeliveryRequest() {

package/src/reviewer-role.ts

@@ -163,9 +163,9 @@ export function createReviewerRoleRuntime(pi: ExtensionAPI, dependencies: Review
                 try { await dependencies.shutdownAgent?.(); } catch (error) { hostActions.failInfrastructure(ledger.recordInfrastructureFailure(error), toolCtx, id); }
                 return { content: [{ type: "text" as const, text: "Reviewer report accepted" }], details: candidate, terminate: true as const, ...(usage === undefined ? {} : { usage }) };
               },
-              noReceipt: async (auditNoReceipt) => {
+              noReceipt: async (auditNoReceipt, usageProjection) => {
                 try { await dependencies.shutdownAgent?.(); } catch (error) { hostActions.failInfrastructure(ledger.recordInfrastructureFailure(error), toolCtx, id); }
-                return { content: [{ type: "text" as const, text: "Reviewer report accepted; compliance audit produced no receipt" }], details: { ...candidate, auditNoReceipt }, terminate: true as const };
+                return { content: [{ type: "text" as const, text: "Reviewer report accepted; compliance audit produced no receipt" }], details: { ...candidate, auditNoReceipt }, terminate: true as const, ...usageProjection };
               },
               revise: (violations) => {
                 throw new AggregateError([], `Reviewer receipt rejected:\n${violations.join("\n")}`, { cause: Object.freeze([...violations]) });

package/src/role-runtime.ts

@@ -567,8 +567,9 @@ export function createRoleRuntimeExtension(
     // whose queued next turn is consumed before settlement.
     pi.on("agent_end", (event) => {
       const lastMessage = event.messages.at(-1);
-      if (lastMessage?.role === "assistant" && lastMessage.stopReason === "error") {
-        // Provider failure has no tool_result event; classify it here so the
+      if (lastMessage?.role === "assistant"
+        && (lastMessage.stopReason === "error" || lastMessage.stopReason === "aborted")) {
+        // Provider failure/abort has no tool_result event; classify it here so the
         // receipt policy cannot turn infrastructure death into an exit-0 lifecycle.
         receiptDelivery.stopForInfrastructure();
         return;

package/src/sitian-record-entry.ts

@@ -7,6 +7,10 @@ import { dirname, resolve, join } from "node:path";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 
 import { resolveBookKeyFromGit } from "./activation-ledger-git.ts";
+export {
+  roleRunSessionCoordinates,
+  type RoleRunSessionCoordinates,
+} from "./sitian-role-run-coordinates.ts";
 import {
   activationBookDirectory,
   ensureRealDirectoryTree,

package/src/sitian-role-run-coordinates.ts

@@ -0,0 +1,45 @@
+import { join } from "node:path";
+
+import { resolveBookKeyFromGit } from "./activation-ledger-git.ts";
+import {
+  activationBookDirectory,
+  resolveActivationLedgerHome,
+} from "./activation-ledger-topology.ts";
+
+export type RoleRunSessionCoordinates = {
+  readonly ledgerHome: string;
+  readonly bookKey: string;
+  readonly runDirectory: string;
+  readonly sessionDirectory: string;
+  readonly sessionFile: string;
+};
+
+/**
+ * Sole source of public top-level Role run session coordinates.
+ * Callers supply identity only; no destination can be injected.
+ */
+export function roleRunSessionCoordinates(options: {
+  readonly cwd: string;
+  readonly runId: string;
+  readonly role: string;
+  /** Machine-home identity; not a record destination. */
+  readonly home?: string;
+}): RoleRunSessionCoordinates {
+  const ledgerHome = resolveActivationLedgerHome(
+    options.home === undefined ? undefined : () => options.home!,
+  );
+  const bookKey = resolveBookKeyFromGit(options.cwd);
+  const runDirectory = join(
+    activationBookDirectory(ledgerHome, bookKey),
+    "runs",
+    `${options.runId}@${options.role}`,
+  );
+  const sessionDirectory = join(runDirectory, "session");
+  return {
+    ledgerHome,
+    bookKey,
+    runDirectory,
+    sessionDirectory,
+    sessionFile: join(sessionDirectory, "session.jsonl"),
+  };
+}