@akagilnc/pi-workflow-roles 0.1.5483 → 0.1.5571

package/src/ticket-trajectory.ts

@@ -6,7 +6,7 @@
  *
  * Station resolution (four-layer fallback):
  *   1) terminating tool name inside the session (ak_<role>_output)
- *   2) invocation.json role
+ *   2) current.json invocation role
  *   3) run-directory name heuristic
  *   4) unknown (still listed; never dropped)
  *
@@ -18,19 +18,27 @@
  * write does not advertise refresh. Regeneration faults surface the original
  * cause via handle.closed / stop(). Caller stops the handle.
  */
-import { randomUUID } from "node:crypto";
-import { lstat, mkdir, readdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { readSectionSync } from "./run-dossier.ts";
+import { lstat, mkdir, readdir, readFile, realpath } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 
+import { writeFileAtomically } from "./atomic-write.ts";
+import {
+  errnoCode,
+  pathContainedIn,
+  physicalPathIdentity,
+} from "./activation-ledger-topology.ts";
+
 import {
   formatDurationZh,
   formatLocalDateTime,
   formatTokensCompact,
   formatUsdPrecise,
 } from "./human-format.ts";
-import { listBookRunDirectories } from "./role-run-placement.ts";
-import { readRunTicketNumber } from "./run-ticket-number.ts";
+import { listBookRunDirectories, sessionDirectoryOf } from "./role-run-placement.ts";
+import { sitianVolumeDirectory } from "./sitian-appender.ts";
+import { isPositiveTicketNumber, readRunTicketNumber } from "./run-ticket-number.ts";
 import {
   extractSessionTimestampSpan,
   readLedgerSessionJsonl,
@@ -279,9 +287,8 @@ type InvocationInfo = {
 
 async function readInvocation(runDir: string): Promise<InvocationInfo | undefined> {
   try {
-    const raw = await readFile(join(runDir, "invocation.json"), "utf8");
-    const parsed: unknown = JSON.parse(raw);
-    if (!isRecord(parsed)) return undefined;
+    const parsed = readSectionSync(runDir, "invocation");
+    if (parsed === undefined) return undefined;
     const info: InvocationInfo = {};
     if (typeof parsed.role === "string" && parsed.role.trim()) info.role = parsed.role.trim();
     if (typeof parsed.thinking === "string" && parsed.thinking.trim()) info.thinking = parsed.thinking.trim();
@@ -350,7 +357,7 @@ async function listSessionFiles(sessionDir: string): Promise<string[]> {
 
 /** Reviewer parallel axis-leg sessions live under session/reviewer-legs/. */
 async function listAxisLegSessionFiles(sessionDir: string): Promise<string[]> {
-  return listSessionFiles(join(sessionDir, "reviewer-legs"));
+  return listSessionFiles(sitianVolumeDirectory(sessionDir, "reviewer-legs"));
 }
 
 async function maxMtimeMs(paths: readonly string[]): Promise<number> {
@@ -372,7 +379,7 @@ async function parseRunDirectory(runDir: string, ledgerCoord: string): Promise<P
   const runId = basename(runDir);
   const evidenceTarget = await realpathOrLexicalIfMissing(runDir);
   const evidenceHref = pathToFileURL(evidenceTarget).href;
-  const sessionDir = join(runDir, "session");
+  const sessionDir = sessionDirectoryOf(runDir);
   const sessionFiles = await listSessionFiles(sessionDir);
   const axisLegFiles = await listAxisLegSessionFiles(sessionDir);
   const rows: SessionRow[] = [];
@@ -425,7 +432,7 @@ async function parseRunDirectory(runDir: string, ledgerCoord: string): Promise<P
     ...(invocation?.role !== undefined ? { invocationRole: invocation.role } : {}),
   });
 
-  // Session mechanical fields win; invocation.json fills gaps only.
+  // Session mechanical fields win; the invocation section fills gaps only.
   let { model, provider, thinking } = models;
   if (invocation) {
     if (!thinking && invocation.thinking) thinking = invocation.thinking;
@@ -653,12 +660,12 @@ ${stationBlocks || "<p data-empty=\"true\">no runs</p>"}
  * Factory board reuses this — no parallel receipt parser.
  *
  * Book-run attribution (#176 / #859): read typed `ticketNumber` from each run's
- * invocation.json under listBookRunDirectories (flat legacy `runs/` + subject-tree
+ * current.json invocation section under listBookRunDirectories (flat legacy `runs/` + subject-tree
  * `<ticket|unbound>/runs/`). Legacy `issues/<N>/runs` remains a read-only
  * compatibility entrance. Unbound runs never join a ticket.
  */
 
-/** One book run's typed binding projection from invocation.json. */
+/** One book run's typed binding projection from the invocation section. */
 export type FlatRunTicketBinding = {
   readonly runDir: string;
   readonly runFolder: string;
@@ -671,10 +678,10 @@ export type FlatRunTicketBinding = {
 
 /**
  * Book-level run index built once per lane/render and reused per ticket.
- * Pure derived view of book runs' invocation.json files — not a parallel ledger.
+ * Pure derived view of book runs' current.json invocation sections — not a parallel ledger.
  */
 export type TicketTrajectoryBookIndex = {
-  /** ticket number → runs bound via invocation.json ticketNumber. */
+  /** ticket number → runs bound via invocation ticketNumber. */
   readonly runsByTicket: ReadonlyMap<number, readonly FlatRunTicketBinding[]>;
   /** Runs with no typed ticketNumber (unknown/unbound seam). */
   readonly unboundRuns: readonly FlatRunTicketBinding[];
@@ -749,7 +756,7 @@ export async function loadTicketTrajectoryRuns(
   issueNumber: number,
   bookIndex?: TicketTrajectoryBookIndex,
 ): Promise<TicketTrajectoryRun[]> {
-  if (!Number.isInteger(issueNumber) || issueNumber < 1) {
+  if (!isPositiveTicketNumber(issueNumber)) {
     throw new Error("issueNumber must be a positive integer");
   }
   const root = resolve(ledgerDir);
@@ -767,7 +774,7 @@ export async function loadTicketTrajectoryRuns(
     runs.push(parsed);
   }
 
-  // Book runs (flat + subject-tree) bound by typed invocation.json ticketNumber.
+  // Book runs (flat + subject-tree) bound by typed invocation ticketNumber.
   const flatBindings = index.runsByTicket.get(issueNumber) ?? [];
   for (const binding of flatBindings) {
     const resolvedRunDir = resolve(binding.runDir);
@@ -789,7 +796,7 @@ export async function renderTicketTrajectoryHtml(
   now: Date,
   options?: { refreshBoundarySeconds?: number },
 ): Promise<string> {
-  if (!isRecord(ticketSnapshot) || typeof ticketSnapshot.issueNumber !== "number" || !Number.isInteger(ticketSnapshot.issueNumber) || ticketSnapshot.issueNumber < 1) {
+  if (!isRecord(ticketSnapshot) || !isPositiveTicketNumber(ticketSnapshot.issueNumber)) {
     throw new Error("ticketSnapshot.issueNumber must be a positive integer");
   }
   const issueNumber = ticketSnapshot.issueNumber;
@@ -807,118 +814,96 @@ export async function renderTicketTrajectoryHtml(
   });
 }
 
-function isPathInside(parent: string, child: string): boolean {
-  const rel = relative(parent, child);
-  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !rel.startsWith(".."));
+function landsInLedger(ledgerRoot: string, candidate: string): boolean {
+  // mkdir may have materialized a previously dangling ledger alias since the first gate.
+  const physicalRoot = physicalPathIdentity(ledgerRoot);
+  const lexical = resolve(candidate);
+  const physical = physicalPathIdentity(candidate);
+  const inside = (id: string) => physicalRoot === id || pathContainedIn(physicalRoot, id);
+  return inside(lexical) || inside(physical);
 }
 
 /**
- * Resolve the prospective on-disk target of outputPath and refuse any landing
- * inside the ledger — including when the path, a parent, or a trailing segment
- * is a symlink into the ledger tree.
+ * Prospective output must stay outside every ledger root.
+ * Equality counts as inside. Symlink parents are followed by physical identity.
  */
-export async function assertTrajectoryOutputOutsideLedger(
-  ledgerDir: string,
+export async function assertOutputOutsideLedgers(
+  ledgerDirs: readonly string[],
   outputPath: string,
-): Promise<{ ledgerRoot: string; outputAbsolute: string; prospectiveReal: string }> {
-  const ledgerResolved = resolve(ledgerDir);
-  let ledgerRoot: string;
-  try {
-    ledgerRoot = await realpath(ledgerResolved);
-  } catch (error) {
-    if (!isMissingPathError(error)) throw error;
-    ledgerRoot = ledgerResolved;
-  }
+  refusalMessage: string,
+): Promise<{ ledgerRoots: string[]; outputAbsolute: string; prospectiveReal: string }> {
   const outputAbsolute = resolve(outputPath);
-
-  // Walk up until an existing filesystem node is found; realpath that prefix
-  // and rejoin the missing tail so symlink parents are fully followed.
-  const missingTail: string[] = [];
-  let cursor = outputAbsolute;
-  for (;;) {
+  const prospectiveReal = physicalPathIdentity(outputAbsolute);
+  const ledgerRoots: string[] = [];
+  for (const ledgerDir of ledgerDirs) {
+    const ledgerResolved = resolve(ledgerDir);
+    let ledgerRoot: string;
     try {
-      await lstat(cursor);
-      break;
+      ledgerRoot = await realpath(ledgerResolved);
     } catch (error) {
       if (!isMissingPathError(error)) throw error;
-      const parent = dirname(cursor);
-      if (parent === cursor) break;
-      missingTail.push(basename(cursor));
-      cursor = parent;
+      ledgerRoot = physicalPathIdentity(ledgerResolved);
+    }
+    ledgerRoots.push(ledgerRoot);
+    if (landsInLedger(ledgerRoot, prospectiveReal) || landsInLedger(ledgerRoot, outputAbsolute)) {
+      throw new Error(refusalMessage);
     }
   }
-
-  let realPrefix: string;
-  try {
-    realPrefix = await realpath(cursor);
-  } catch (error) {
-    if (!isMissingPathError(error)) throw error;
-    realPrefix = resolve(cursor);
-  }
-
-  const prospectiveReal =
-    missingTail.length === 0 ? realPrefix : resolve(realPrefix, ...missingTail.reverse());
-
-  if (isPathInside(ledgerRoot, prospectiveReal) || isPathInside(ledgerRoot, realPrefix)) {
-    throw new Error("ticket trajectory outputPath must be outside the ledger directory");
-  }
-
-  // Lexical absolute path must also stay outside (defense in depth before mkdir).
-  if (isPathInside(ledgerRoot, outputAbsolute)) {
-    throw new Error("ticket trajectory outputPath must be outside the ledger directory");
-  }
-
-  return { ledgerRoot, outputAbsolute, prospectiveReal };
+  return { ledgerRoots, outputAbsolute, prospectiveReal };
 }
 
 /**
- * Write HTML to an explicit path outside the ledger without following an
- * existing destination inode (hard link / prior file). Temp file + rename
- * replaces the directory entry so a hard-linked ledger twin keeps its bytes.
+ * Write HTML outside the ledgers. Temp+rename does not open an existing inode.
+ * An existing symlink whose target is inside a ledger is refused.
  */
-async function writeHtmlAtomicallyOutsideLedger(input: {
-  ledgerRoot: string;
-  outputAbsolute: string;
-  html: string;
-}): Promise<string> {
-  const parent = dirname(input.outputAbsolute);
+export async function writePageOutsideLedgers(
+  ledgerRoots: readonly string[],
+  outputAbsolute: string,
+  html: string,
+  refusalMessage: string,
+): Promise<string> {
+  const parent = dirname(outputAbsolute);
   await mkdir(parent, { recursive: true });
-
-  // Re-resolve after mkdir: a race or symlink parent must still land outside.
   const parentReal = await realpath(parent);
-  if (isPathInside(input.ledgerRoot, parentReal)) {
-    throw new Error("ticket trajectory outputPath must be outside the ledger directory");
-  }
-
-  const destinationReal = resolve(parentReal, basename(input.outputAbsolute));
-  if (isPathInside(input.ledgerRoot, destinationReal)) {
-    throw new Error("ticket trajectory outputPath must be outside the ledger directory");
+  const destinationReal = resolve(parentReal, basename(outputAbsolute));
+  for (const root of ledgerRoots) {
+    if (landsInLedger(root, parentReal) || landsInLedger(root, destinationReal)) {
+      throw new Error(refusalMessage);
+    }
   }
-
-  // Refuse to write through an existing symlink whose target is inside the ledger.
   try {
-    const existing = await lstat(input.outputAbsolute);
+    const existing = await lstat(outputAbsolute);
     if (existing.isSymbolicLink()) {
-      const target = await realpath(input.outputAbsolute);
-      if (isPathInside(input.ledgerRoot, target)) {
-        throw new Error("ticket trajectory outputPath must be outside the ledger directory");
+      const target = await realpath(outputAbsolute);
+      for (const root of ledgerRoots) {
+        if (landsInLedger(root, target)) throw new Error(refusalMessage);
       }
     }
   } catch (error) {
-    if (!isMissingPathError(error)) throw error;
+    if (errnoCode(error) !== "ENOENT" && errnoCode(error) !== "ENOTDIR") throw error;
   }
+  await writeFileAtomically(outputAbsolute, html);
+  return realpath(outputAbsolute);
+}
 
-  // Same-directory temp + rename: does not open/truncate an existing inode, so a
-  // hard link from outputPath into the ledger cannot smuggle writes back home.
-  const temporary = join(parent, `.ticket-trajectory-${randomUUID()}.html.tmp`);
-  try {
-    await writeFile(temporary, input.html, "utf8");
-    await rename(temporary, input.outputAbsolute);
-  } catch (error) {
-    await rm(temporary, { force: true }).catch(() => undefined);
-    throw error;
-  }
-  return realpath(input.outputAbsolute);
+const TRAJECTORY_OUTPUT_REFUSAL =
+  "ticket trajectory outputPath must be outside the ledger directory";
+
+/**
+ * Resolve the prospective on-disk target of outputPath and refuse any landing
+ * inside the ledger — including when the path, a parent, or a trailing segment
+ * is a symlink into the ledger tree.
+ */
+export async function assertTrajectoryOutputOutsideLedger(
+  ledgerDir: string,
+  outputPath: string,
+): Promise<{ ledgerRoot: string; outputAbsolute: string; prospectiveReal: string }> {
+  const gate = await assertOutputOutsideLedgers([ledgerDir], outputPath, TRAJECTORY_OUTPUT_REFUSAL);
+  return {
+    ledgerRoot: gate.ledgerRoots[0]!,
+    outputAbsolute: gate.outputAbsolute,
+    prospectiveReal: gate.prospectiveReal,
+  };
 }
 
 /**
@@ -943,11 +928,12 @@ export async function writeTicketTrajectoryPage(input: {
       : undefined,
   );
 
-  const outputPath = await writeHtmlAtomicallyOutsideLedger({
-    ledgerRoot: gate.ledgerRoot,
-    outputAbsolute: gate.outputAbsolute,
+  const outputPath = await writePageOutsideLedgers(
+    [gate.ledgerRoot],
+    gate.outputAbsolute,
     html,
-  });
+    TRAJECTORY_OUTPUT_REFUSAL,
+  );
   return { outputPath, html };
 }