@akagilnc/pi-workflow-roles 0.1.5478 → 0.1.5504

package/src/role-runtime.ts

@@ -12,12 +12,14 @@ import {
 
 import { Value } from "typebox/value";
 import { sitianReport } from "./sitian-facade.ts";
+import { sitianReportSafe } from "./host-session-record.ts";
 import { createSubmissionLedgerHost, sealAcceptedSubmission } from "./submission-ledger.ts";
 import { registerFiledSubmissionTool, type FiledSubmissionBeforeAccept } from "./filed-submission.ts";
 import type { RoleSubmissionDeclaration } from "./role-submission-declarations.ts";
 
 import { activationTraceRecordSchema, namedActivationCause, type ActivationTraceRecord, type ActivationTraceWriter } from "./activation-trace.ts";
 import { homeFromRunDirectory } from "./activation-ledger-topology.ts";
+import { isSafePositiveTicketNumber, parseTicketNumber } from "./run-ticket-number.ts";
 import {
   durableSessionPointer,
   resolveBookKeyFromGit,
@@ -207,12 +209,9 @@ function decodeReviewerAdmittedInputs(getFlag: (name: string) => unknown): Revie
     authorityRefs = Object.freeze(parsed as string[]);
   }
 
-  let ticketNumber: number | undefined;
   const rawTicketNumber = getFlag("ak-review-ticket-number");
   // Shape-invalid flag values do not abort: omit typed candidate; branch→commit→degrade continues.
-  if (typeof rawTicketNumber === "string" && /^[1-9]\d*$/.test(rawTicketNumber)) {
-    ticketNumber = Number(rawTicketNumber);
-  }
+  const ticketNumber = parseTicketNumber(rawTicketNumber);
 
   const baseRevision = getFlag("ak-review-base");
   if (typeof baseRevision !== "string" || !baseRevision.trim()) {
@@ -760,15 +759,8 @@ function readDiaristTicketAssertion(
   }
   const raw = submitted.ticketNumber;
   if (raw === null) return { kind: "true-unbound" };
-  if (typeof raw === "number" && Number.isSafeInteger(raw) && raw >= 1) {
-    return { kind: "ticket", ticketNumber: raw };
-  }
-  if (typeof raw === "string" && /^[1-9]\d*$/.test(raw)) {
-    const n = Number(raw);
-    if (Number.isSafeInteger(n) && n >= 1) {
-      return { kind: "ticket", ticketNumber: n };
-    }
-  }
+  const ticketNumber = parseTicketNumber(raw);
+  if (ticketNumber !== undefined) return { kind: "ticket", ticketNumber };
   return { kind: "invalid" };
 }
 
@@ -802,12 +794,9 @@ function readDiaristRunCoordinates(ctx: HostContext): {
   readonly boundTicketNumber?: number;
 } {
   const coordinates = readRoleRunCoordinates(ctx, "diarist accept");
-  const bound =
-    typeof coordinates.admitted.ticketNumber === "number" &&
-    Number.isSafeInteger(coordinates.admitted.ticketNumber) &&
-    coordinates.admitted.ticketNumber >= 1
-      ? coordinates.admitted.ticketNumber
-      : undefined;
+  const bound = isSafePositiveTicketNumber(coordinates.admitted.ticketNumber)
+    ? coordinates.admitted.ticketNumber
+    : undefined;
   return {
     runDirectory: coordinates.runDirectory,
     projectRoot: coordinates.projectRoot,
@@ -1344,16 +1333,14 @@ export function createRoleRuntimeExtension(
               attemptPointer: receiptAttemptPointer(runPointer, ctx.invocationScopeId),
             });
             envelopeHost.appendEntry(NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, facts);
-            try {
-              sitianReport({
-                level: "event",
-                kind: "no-receipt-lifecycle",
-                cwd: ctx.cwd,
-                sessionParent: ctx.sessionManager.getSessionFile(),
-                payload: facts,
-                source: "role-runtime",
-              });
-            } catch {}
+            sitianReportSafe({
+              level: "event",
+              kind: "no-receipt-lifecycle",
+              cwd: ctx.cwd,
+              sessionParent: ctx.sessionManager.getSessionFile(),
+              payload: facts,
+              source: "role-runtime",
+            });
           }
         }
         return;
@@ -1367,16 +1354,14 @@ export function createRoleRuntimeExtension(
           RECEIPT_DELIVERY_REQUEST_ENTRY,
           scopeId.length > 0 ? { invocationScopeId: scopeId } : undefined,
         );
-        try {
-          sitianReport({
-            level: "event",
-            kind: "receipt-delivery",
-            cwd: ctx.cwd,
-            sessionParent: ctx.sessionManager.getSessionFile(),
-            payload: { type: "ak-receipt-delivery-request" },
-            source: "role-runtime",
-          });
-        } catch {}
+        sitianReportSafe({
+          level: "event",
+          kind: "receipt-delivery",
+          cwd: ctx.cwd,
+          sessionParent: ctx.sessionManager.getSessionFile(),
+          payload: { type: "ak-receipt-delivery-request" },
+          source: "role-runtime",
+        });
         envelopeHost.sendMessage({
           customType: "ak-receipt-delivery-prompt",
           content: JSON.stringify(receiptDelivery.deliveryState()),
@@ -1391,16 +1376,14 @@ export function createRoleRuntimeExtension(
             attemptPointer: receiptAttemptPointer(runPointer, ctx.invocationScopeId),
           });
           envelopeHost.appendEntry(NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, facts);
-          try {
-            sitianReport({
-              level: "event",
-              kind: "no-receipt-lifecycle",
-              cwd: ctx.cwd,
-              sessionParent: ctx.sessionManager.getSessionFile(),
-              payload: facts,
-              source: "role-runtime",
-            });
-          } catch {}
+          sitianReportSafe({
+            level: "event",
+            kind: "no-receipt-lifecycle",
+            cwd: ctx.cwd,
+            sessionParent: ctx.sessionManager.getSessionFile(),
+            payload: facts,
+            source: "role-runtime",
+          });
         }
       }
     });
@@ -1765,16 +1748,14 @@ export function createRoleRuntimeExtension(
               subjectKey: work.subjectKey,
             };
             envelopeHost.appendEntry(NAVIGATOR_INVOCATION_ENTRY, data);
-            try {
-              sitianReport({
-                level: "event",
-                kind: "attendance",
-                cwd: ctx.cwd,
-                sessionParent: ctx.sessionManager.getSessionFile(),
-                payload: { type: NAVIGATOR_INVOCATION_ENTRY, ...data },
-                source: "role-runtime",
-              });
-            } catch {}
+            sitianReportSafe({
+              level: "event",
+              kind: "attendance",
+              cwd: ctx.cwd,
+              sessionParent: ctx.sessionManager.getSessionFile(),
+              payload: { type: NAVIGATOR_INVOCATION_ENTRY, ...data },
+              source: "role-runtime",
+            });
           }
           const activation = navigatorActivation;
           navigatorAttendance = await dependencies.createNavigatorAttendance({

package/src/run-terminal-artifacts.ts

@@ -10,7 +10,8 @@ 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.ts";
+import { parseRunLeaf, roleRunArtifactsDirectory } from "./role-run-placement.ts";
+
 import { isRecord, errorText, isMissingPathError } from "./unknown-value.ts";
 
 export const RUN_TERMINAL_REPORT_FILE = "report.json" as const;
@@ -155,10 +156,7 @@ async function listUniqueErrorFallbackPaths(
  * Sole authority for runDirectory → runId (last `@` split).
  */
 export function runIdFromRunDirectory(runDirectory: string): string | undefined {
-  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;
 }
 
 /**

package/src/run-ticket-number.ts

@@ -14,9 +14,48 @@ import { isEnoent, isRecord } from "./unknown-value.ts";
 export const MIGRATION_TICKET_DERIVATION_PAGE =
   "migration-ticket-derivation.json" as const;
 
+/** Positive-integer contract for display / snapshot inputs; binding uses the safe subset below. */
+export function isPositiveTicketNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1;
+}
+
 /** Sole safe-positive ticket invariant (bind / admission / placement / readers). */
 export function isSafePositiveTicketNumber(value: unknown): value is number {
-  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+  return isPositiveTicketNumber(value) && Number.isSafeInteger(value);
+}
+
+/** Shared digit spelling, also used for consumer-specific rejection diagnostics. */
+export function isTicketNumberString(value: unknown): value is string {
+  return typeof value === "string" && /^[1-9][0-9]*$/.test(value);
+}
+
+/**
+ * Ticket spelling shared by placement, migration, and sitian subject routing.
+ * A number, or a digit string with no sign, zero-pad, decimal, or `#`.
+ * Unsafe integers are unidentified. Leading `#N` stays on readDeclaredTicketNumber.
+ */
+export function parseTicketNumber(value: unknown): number | undefined {
+  if (isSafePositiveTicketNumber(value)) return value;
+  if (!isTicketNumberString(value)) return undefined;
+  const parsed = Number(value);
+  return isSafePositiveTicketNumber(parsed) ? parsed : undefined;
+}
+
+/** Ticket number carried by a sitian subject, when the subject is a ticket. */
+export function sitianSubjectTicketNumber(subject: unknown): number | undefined {
+  if (typeof subject === "string" || typeof subject === "number") {
+    return parseTicketNumber(subject);
+  }
+  if (subject !== null && typeof subject === "object" && !Array.isArray(subject)) {
+    return parseTicketNumber((subject as { ticketNumber?: unknown }).ticketNumber);
+  }
+  return undefined;
+}
+
+/** Ticket-provenance directory id from a sitian subject, when the subject is a ticket. */
+export function ticketNumberFromSitianSubject(subject: unknown): string | undefined {
+  const parsed = sitianSubjectTicketNumber(subject);
+  return parsed === undefined ? undefined : String(parsed);
 }
 
 /**
@@ -35,8 +74,7 @@ export function readDeclaredTicketNumber(value: unknown): number | undefined {
   // (word-boundary alone would truncate at the decimal point).
   const match = /^#?([1-9]\d*)(?!\.\d)(?:\b|$)/.exec(trimmed);
   if (match === null) return undefined;
-  const ticketNumber = Number(match[1]);
-  return isSafePositiveTicketNumber(ticketNumber) ? ticketNumber : undefined;
+  return parseTicketNumber(match[1]);
 }
 
 /** Loud reject for non-safe-positive ticket numbers before placement or bind. */

package/src/session-assistant-usage.ts

@@ -3,7 +3,8 @@
  * Accumulates real cost when rows carry it; never invents cost zeros (#675).
  */
 import type { Usage } from "@earendil-works/pi-ai";
-import { join } from "node:path";
+import { ROLE_RUN_SESSION_FILENAME, sessionFileOf } from "./role-run-placement.ts";
+import { readStrictPiSessionJsonl } from "./ledger-session-read.ts";
 
 import type { PublicSummonResult } from "./public-role-summons.ts";
 
@@ -12,25 +13,12 @@ import { errorText } from "./unknown-value.ts";
 export async function readAssistantUsageFromSessionFile(
   sessionFile: string,
 ): Promise<Usage | undefined> {
-  const { readFile } = await import("node:fs/promises");
-  let text: string;
-  try {
-    text = await readFile(sessionFile, "utf8");
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") return undefined;
-    throw error;
-  }
   let rows: Array<{ type?: string; message?: { role?: string; usage?: Usage } }>;
   try {
-    rows = text
-      .trim()
-      .split("\n")
-      .filter(Boolean)
-      .map((line) => JSON.parse(line) as {
-        type?: string;
-        message?: { role?: string; usage?: Usage };
-      });
+    rows = await readStrictPiSessionJsonl(sessionFile) as typeof rows;
   } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") return undefined;
+    if (!(error instanceof SyntaxError)) throw error;
     throw new Error(
       `session usage parse failed (${sessionFile}): ${errorText(error)}`,
       { cause: error },
@@ -95,18 +83,18 @@ export function sessionFileFromPublicSummon(
   summoned: PublicSummonResult,
 ): string | undefined {
   if (typeof summoned.runDirectory === "string" && summoned.runDirectory.trim() !== "") {
-    return join(summoned.runDirectory, "session", "session.jsonl");
+    return sessionFileOf(summoned.runDirectory);
   }
   const fromArtifacts = summoned.terminal?.artifacts
     ?.map((a) => (a as { path?: string }).path)
-    .find((p): p is string => typeof p === "string" && p.endsWith("session.jsonl"));
+    .find((p): p is string => typeof p === "string" && p.endsWith(ROLE_RUN_SESSION_FILENAME));
   if (fromArtifacts !== undefined) return fromArtifacts;
   const outcome = summoned.terminal?.roleOutcome;
   if (outcome === undefined) return undefined;
   const facts = (outcome as { decisiveFacts?: Record<string, unknown> }).decisiveFacts;
   const pointer = facts?.runPointer;
   if (typeof pointer === "string" && pointer.trim() !== "") {
-    return join(pointer, "session", "session.jsonl");
+    return sessionFileOf(pointer);
   }
   return undefined;
 }

package/src/session-identity.ts

@@ -1,6 +1,7 @@
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
+import { writeFileAtomically } from "./atomic-write.ts";
 import type { DurablePrincipal, DurablePrincipalAuthority } from "./host-contracts.ts";
 import {
   DEFAULT_ROLE_TURN_HOST,
@@ -35,9 +36,7 @@ export function createSessionIdentityAuthority(
     async bind(principal, sessionId) {
       const target = bindingPath(principal);
       await mkdir(dirname(target), { recursive: true });
-      const temporary = `${target}.${process.pid}.tmp`;
-      await writeFile(temporary, `${JSON.stringify({ sessionId })}\n`, { encoding: "utf8", mode: 0o600 });
-      await rename(temporary, target);
+      await writeFileAtomically(target, `${JSON.stringify({ sessionId })}\n`, { mode: 0o600 });
     },
   };
 }

package/src/sitian-appender.ts

@@ -7,6 +7,9 @@ import { randomUUID } from "node:crypto";
 import { appendFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
+import { sessionDirectoryOf } from "./role-run-placement.ts";
+import { ticketNumberFromSitianSubject } from "./run-ticket-number.ts";
+
 import { resolveBookKeyFromGit } from "./activation-ledger-git.ts";
 import {
   activationBookDirectory,
@@ -65,6 +68,18 @@ type SitianRecordPath = {
 /** Sole records leaf under every sitian volume directory. */
 const SITIAN_RECORDS_LEAF = "records.jsonl" as const;
 
+export function sitianVolumeDirectory(sessionDirectory: string, category: string): string {
+  return join(sessionDirectory, category);
+}
+
+export function sitianRunVolumeDirectory(runDirectory: string, category: string): string {
+  return sitianVolumeDirectory(sessionDirectoryOf(runDirectory), category);
+}
+
+export function sitianVolumeRecordsFile(volumeDirectory: string): string {
+  return join(volumeDirectory, SITIAN_RECORDS_LEAF);
+}
+
 /**
  * Ticket-provenance under-book paths (docs/dossier-topology.md sole authority).
  * Writer ticket branch and owner-visible shape share this join — one code path.
@@ -75,7 +90,7 @@ function ticketProvenanceUnderBookPaths(
   ticketId: string,
 ): { sessionDir: string; recordFile: string } {
   const sessionDir = join(activationBookDirectory(ledgerHome, bookKey), ticketId);
-  return { sessionDir, recordFile: join(sessionDir, SITIAN_RECORDS_LEAF) };
+  return { sessionDir, recordFile: sitianVolumeRecordsFile(sessionDir) };
 }
 
 /** Pure topology owner shared by ambient writes and explicit-home submission reads. */
@@ -85,14 +100,7 @@ export function resolveSitianRecordPathInLedger(
 ): SitianRecordPath {
   const category = resolveSitianVolumeCategory(input.kind);
   const ticketNumber = category === "ticket-provenance"
-    ? typeof input.subject === "string" && /^[1-9][0-9]*$/.test(input.subject)
-      ? input.subject
-      : typeof input.subject === "object"
-        && typeof input.subject.ticketNumber === "number"
-        && Number.isSafeInteger(input.subject.ticketNumber)
-        && input.subject.ticketNumber > 0
-        ? String(input.subject.ticketNumber)
-        : undefined
+    ? ticketNumberFromSitianSubject(input.subject)
     : undefined;
 
   let sessionDir: string;
@@ -108,7 +116,7 @@ export function resolveSitianRecordPathInLedger(
     recordFile = paths.recordFile;
   } else if (category === "ticket-provenance" && input.runDirectory !== undefined) {
     sessionDir = input.runDirectory;
-    recordFile = join(sessionDir, SITIAN_RECORDS_LEAF);
+    recordFile = sitianVolumeRecordsFile(sessionDir);
   } else {
     if (
       input.sessionParent === undefined
@@ -117,8 +125,8 @@ export function resolveSitianRecordPathInLedger(
     ) {
       throw new Error("Sitian record ownership requires a parent session inside the ledger home");
     }
-    sessionDir = join(dirname(input.sessionParent), category);
-    recordFile = join(sessionDir, SITIAN_RECORDS_LEAF);
+    sessionDir = sitianVolumeDirectory(dirname(input.sessionParent), category);
+    recordFile = sitianVolumeRecordsFile(sessionDir);
   }
   if (!physicallyContainedIn(ledgerHome, sessionDir)) {
     throw new Error("Sitian record ownership requires a directory inside the ledger home");

package/src/submission-ledger.ts

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { sessionFileIn, sessionFileOf } from "./role-run-placement.ts";
 
 import {
   resolveActivationLedgerHome,
@@ -133,7 +133,7 @@ async function submissionRecordFile(cwd: string, runId: string, scope: Submissio
   if (sessionParent === undefined) {
     const discoveredRun = await findRunDirectoryById(scope.home, runId);
     if (discoveredRun === undefined) return undefined;
-    sessionParent = join(discoveredRun, "session", "session.jsonl");
+    sessionParent = sessionFileOf(discoveredRun);
   }
   return resolveSitianRecordPathInLedger({
     level: "event",
@@ -432,12 +432,12 @@ async function restoreState(cwd: string, runId: string, scope: SubmissionLedgerR
 /** Sole HostContext-derived session parent for ledger restore/append (never process.env). */
 function sessionParentFromHostContext(context: HostContext): string | undefined {
   const runDirectory = runDirectoryFromHostContext(context);
-  if (runDirectory !== undefined) return join(runDirectory, "session", "session.jsonl");
+  if (runDirectory !== undefined) return sessionFileOf(runDirectory);
   const sessionFile = context.sessionManager.getSessionFile?.();
   if (typeof sessionFile === "string" && sessionFile.length > 0) return sessionFile;
   const sessionDir = context.sessionManager.getSessionDir?.();
   if (typeof sessionDir === "string" && sessionDir.length > 0) {
-    return join(sessionDir, "session.jsonl");
+    return sessionFileIn(sessionDir);
   }
   return undefined;
 }

package/src/ticket-provenance-contracts.ts

@@ -1,4 +1,6 @@
+import { parseTicketNumber } from "./run-ticket-number.ts";
 import { isRecord } from "./unknown-value.ts";
+
 /**
  * 起居录（ticket-provenance）typed 形状 —— ADR 0075 / ADR 0081 / #1090。
  *
@@ -63,12 +65,7 @@ export type TicketProvenanceLine = {
 };
 
 function positiveInteger(value: unknown): number | undefined {
-  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 1) return value;
-  if (typeof value === "string" && /^[1-9][0-9]*$/.test(value)) {
-    const parsed = Number(value);
-    if (Number.isSafeInteger(parsed)) return parsed;
-  }
-  return undefined;
+  return parseTicketNumber(value);
 }
 
 function projectBound(value: unknown): TicketProvenanceBound | undefined {

package/src/ticket-provenance.ts

@@ -4,7 +4,7 @@
  * 纯追加、不回读历史去重、不折叠。
  */
 import { readFile, unlink } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 
 import {
   errnoCode,
@@ -17,6 +17,8 @@ import {
   type LedgerSessionLine,
 } from "./ledger-session-read.ts";
 import { isSafePositiveTicketNumber } from "./run-ticket-number.ts";
+import { runDirectoryOfSessionFile, sessionFileOf } from "./role-run-placement.ts";
+import { sitianVolumeRecordsFile } from "./sitian-appender.ts";
 import { adaptSessionDialogue, nativeEventId } from "./session-dialogue.ts";
 import {
   appendSitianRecordBlock,
@@ -76,10 +78,7 @@ function isLedgerRoleSessionFile(absolute: string, home?: string): boolean {
       : packageMachineHome();
   const ledgerHome = resolveActivationLedgerHome(machineHome);
   if (!physicallyContainedIn(ledgerHome, absolute)) return false;
-  return (
-    basename(absolute) === "session.jsonl" &&
-    basename(dirname(absolute)) === "session"
-  );
+  return sessionFileOf(runDirectoryOfSessionFile(absolute)) === absolute;
 }
 
 /** Real I/O seam gate: only host session stores or sitian role-run session.jsonl. */
@@ -152,7 +151,7 @@ export async function rehomeUnboundTicketProvenance(
   cwd: string,
   home: string,
 ): Promise<void> {
-  const source = join(runDirectory, "records.jsonl");
+  const source = sitianVolumeRecordsFile(runDirectory);
   let content: string;
   try {
     content = await readFile(source, "utf8");

package/src/ticket-snapshot.ts

@@ -14,6 +14,7 @@
 import { createGhApiRunner, type GhApiRunner } from "./gh-api-runner.ts";
 
 import { isRecord } from "./unknown-value.ts";
+import { isPositiveTicketNumber } from "./run-ticket-number.ts";
 
 export type BookRepoBinding = {
   bookKey: string;
@@ -171,7 +172,7 @@ function parseClosedAt(raw: unknown, label: string): string | null {
 function parseTicketNode(raw: unknown, label: string): ParsedTicketNode {
   if (!isRecord(raw)) throw new Error(`${label} is not an object`);
   const number = raw.number;
-  if (typeof number !== "number" || !Number.isInteger(number) || number < 1) {
+  if (!isPositiveTicketNumber(number)) {
     throw new Error(`${label}.number invalid`);
   }
   if (typeof raw.title !== "string") throw new Error(`${label}.title missing`);
@@ -536,7 +537,7 @@ export function createGhTicketSnapshotTransport(
       const closedNumbers = [
         ...new Set(
           input.closedIssueNumbers.filter(
-            (n) => Number.isInteger(n) && n > 0 && !tickets.has(n),
+            (n) => isPositiveTicketNumber(n) && !tickets.has(n),
           ),
         ),
       ].sort((a, b) => a - b);