@akagilnc/pi-workflow-roles 0.1.4062 → 0.1.4196

package/src/archivist-record-entry.ts

@@ -3,23 +3,40 @@
  * 调用方只声明自己是谁的什么；落点由候簿拓扑算出，签名不含任何落点/路径参数。
  * 「谁调了谁」复用 Pi parentSession + ADR 0047 correlation，不新增 caller 字段。
  */
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, resolve, join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 
-import { resolveBookKeyFromGit } from "./activation-ledger-git.ts";
 import {
   ActivationLedgerError,
-  activationBookDirectory,
   ensureRealDirectoryTree,
+  errnoCode,
   errorText,
   pathContainedIn,
   physicallyContainedIn,
   resolveActivationLedgerHomeForPath,
 } from "./activation-ledger-topology.ts";
-import { subjectKeyedRecordDirectory } from "./archivist-record-topology.ts";
+import {
+  NAVIGATOR_RECORD_KIND,
+  resolveNavigatorWorkSubjectPlacement,
+} from "./archivist-record-topology.ts";
 
-export { subjectKeyedRecordDirectory } from "./archivist-record-topology.ts";
+export {
+  NAVIGATOR_RECORD_KIND,
+  resolveNavigatorWorkSubjectPlacement,
+} from "./archivist-record-topology.ts";
 
 const CURRENT_SESSION_LEDGER = "current-session.json";
 
@@ -58,20 +75,234 @@ function writeCurrentSession(sessionDir: string, sessionFile: string): void {
   }
 }
 
-/** Parent session surface needed to link and (when already under home) nest the record. */
+/** True when wx lost to a peer creator — native EEXIST on the write itself. */
+function isCurrentSessionClaimRace(error: unknown): boolean {
+  if (!(error instanceof ActivationLedgerError)) return errnoCode(error) === "EEXIST";
+  return errnoCode(error.cause) === "EEXIST";
+}
+
+function currentSessionLedgerPath(sessionDir: string): string {
+  return join(sessionDir, CURRENT_SESSION_LEDGER);
+}
+
+/** Same bounds as Pi readSessionHeader — do not invent a second scan ceiling. */
+const SESSION_HEADER_CHUNK_BYTES = 4096;
+const MAX_SESSION_HEADER_SCAN_BYTES = 1024 * 1024;
+
+type NavigatorSessionHeader = {
+  readonly type: "session";
+  readonly id: string;
+  readonly cwd?: string;
+};
+
+/**
+ * Bounded session-header discovery matching Pi readSessionHeader:
+ * 4KiB chunks, ≤1MiB total, StringDecoder across reads + EOF flush, skip leading
+ * blank lines, first non-blank JSON line only. Accepted session header → value;
+ * complete non-session / malformed first line → rejected (non-candidate, stop);
+ * no complete line yet → incomplete (keep reading). Oversize-without-header →
+ * undefined. Real open/read I/O failures propagate — never washed into non-candidate.
+ */
+type SessionHeaderRead =
+  | { readonly kind: "accepted"; readonly header: NavigatorSessionHeader }
+  | { readonly kind: "rejected" }
+  | { readonly kind: "incomplete" };
+
+function readBoundedSessionHeader(filePath: string): NavigatorSessionHeader | undefined {
+  const fd = openSync(filePath, "r");
+  try {
+    const buffer = Buffer.allocUnsafe(SESSION_HEADER_CHUNK_BYTES);
+    const decoder = new StringDecoder("utf8");
+    let pending = "";
+    let scanned = 0;
+    const consume = (chunk: string): SessionHeaderRead => {
+      pending += chunk;
+      let lineStart = 0;
+      let newlineIndex = pending.indexOf("\n", lineStart);
+      while (newlineIndex !== -1) {
+        const line = pending.slice(lineStart, newlineIndex);
+        lineStart = newlineIndex + 1;
+        newlineIndex = pending.indexOf("\n", lineStart);
+        if (line.trim() === "") continue;
+        // First non-blank complete line decides — never scan past a rejection.
+        pending = pending.slice(lineStart);
+        const header = parseSessionHeaderLine(line);
+        return header === undefined
+          ? { kind: "rejected" }
+          : { kind: "accepted", header };
+      }
+      pending = pending.slice(lineStart);
+      return { kind: "incomplete" };
+    };
+    const finishPending = (tail: string): NavigatorSessionHeader | undefined => {
+      const result = consume(tail);
+      if (result.kind === "accepted") return result.header;
+      if (result.kind === "rejected") return undefined;
+      // EOF with residual non-blank bytes and no newline: treat as one final line.
+      if (pending.trim() === "") return undefined;
+      const header = parseSessionHeaderLine(pending);
+      pending = "";
+      return header;
+    };
+    while (scanned < MAX_SESSION_HEADER_SCAN_BYTES) {
+      const toRead = Math.min(buffer.length, MAX_SESSION_HEADER_SCAN_BYTES - scanned);
+      const bytesRead = readSync(fd, buffer, 0, toRead, null);
+      if (bytesRead === 0) {
+        return finishPending(decoder.end());
+      }
+      scanned += bytesRead;
+      const found = consume(decoder.write(buffer.subarray(0, bytesRead)));
+      if (found.kind === "accepted") return found.header;
+      if (found.kind === "rejected") return undefined;
+    }
+    // Exactly at the scan limit with a complete final line is still accepted;
+    // any further unread byte means the header never arrived in bounds.
+    const probe = Buffer.allocUnsafe(1);
+    if (readSync(fd, probe, 0, 1, null) === 0) {
+      return finishPending(decoder.end());
+    }
+    return undefined;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function parseSessionHeaderLine(line: string): NavigatorSessionHeader | undefined {
+  if (line.trim() === "") return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+  if (
+    typeof parsed !== "object"
+    || parsed === null
+    || (parsed as { type?: unknown }).type !== "session"
+    || typeof (parsed as { id?: unknown }).id !== "string"
+    || (parsed as { id: string }).id.length === 0
+  ) {
+    return undefined;
+  }
+  const cwd = (parsed as { cwd?: unknown }).cwd;
+  return {
+    type: "session",
+    id: (parsed as { id: string }).id,
+    ...(typeof cwd === "string" ? { cwd } : {}),
+  };
+}
+
+/**
+ * Pre-sidecar navigator continuation (historical findMostRecentSession selection):
+ * bounded valid session header, header.cwd resolves equal to the calling cwd,
+ * newest file mtime wins. Nest-local only — not a generic kind fallback.
+ * Returns undefined when no candidate matches (caller mints fresh, old null path).
+ * Directory/stat/read I/O failures propagate as ActivationLedgerError (failure honesty);
+ * format non-candidates stay skippable.
+ */
+function mostRecentNavigatorSessionFile(sessionDir: string, cwd: string): string | undefined {
+  const absoluteSessionDir = resolve(sessionDir);
+  const absoluteCwd = resolve(cwd);
+  let names: string[];
+  try {
+    names = readdirSync(absoluteSessionDir);
+  } catch (error) {
+    throw new ActivationLedgerError(
+      `archivist navigator nest is not readable (${sessionDir}): ${errorText(error)}`,
+      { cause: error },
+    );
+  }
+  const matched: { path: string; mtimeMs: number }[] = [];
+  for (const name of names) {
+    if (!name.endsWith(".jsonl")) continue;
+    const filePath = join(absoluteSessionDir, name);
+    let st;
+    try {
+      st = statSync(filePath);
+    } catch (error) {
+      throw new ActivationLedgerError(
+        `archivist navigator session file is not stat-able (${filePath}): ${errorText(error)}`,
+        { cause: error },
+      );
+    }
+    if (!st.isFile()) continue;
+    let header: NavigatorSessionHeader | undefined;
+    try {
+      header = readBoundedSessionHeader(filePath);
+    } catch (error) {
+      throw new ActivationLedgerError(
+        `archivist navigator session header is not readable (${filePath}): ${errorText(error)}`,
+        { cause: error },
+      );
+    }
+    if (header === undefined) continue;
+    if (typeof header.cwd !== "string" || header.cwd.length === 0) continue;
+    if (resolve(header.cwd) !== absoluteCwd) continue;
+    matched.push({ path: filePath, mtimeMs: st.mtimeMs });
+  }
+  if (matched.length === 0) return undefined;
+  matched.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return matched[0]!.path;
+}
+
+/**
+ * Resume target for an existing navigator work-subject nest.
+ * Prefer the AK current-session sidecar. When absent (legal pre-sidecar / migrated
+ * shape), adopt by historical cwd + mtime recency and write the sidecar once.
+ * No match → undefined so the sole entry mints fresh (old null path).
+ * Ordinary kinds and worker-submission-gate do not use this path.
+ */
+function resolveNavigatorNestContinuation(
+  sessionDir: string,
+  cwd: string,
+): string | undefined {
+  const ledgerPath = currentSessionLedgerPath(sessionDir);
+  if (existsSync(ledgerPath)) {
+    const recentFile = readCurrentSession(sessionDir);
+    assertRecentFinalFileUnderSessionDir(sessionDir, recentFile);
+    return recentFile;
+  }
+  const adopted = mostRecentNavigatorSessionFile(sessionDir, cwd);
+  if (adopted === undefined) return undefined;
+  assertRecentFinalFileUnderSessionDir(sessionDir, adopted);
+  try {
+    writeCurrentSession(sessionDir, adopted);
+    return adopted;
+  } catch (error) {
+    // Concurrent first adopter lost wx — read the winner through the same
+    // containment gate. Other write failures keep their typed cause.
+    if (isCurrentSessionClaimRace(error)) {
+      const recentFile = readCurrentSession(sessionDir);
+      assertRecentFinalFileUnderSessionDir(sessionDir, recentFile);
+      return recentFile;
+    }
+    throw error;
+  }
+}
+
+/** Durable parent session surface that links and nests the record. */
 export type RecordSessionParent = {
   getSessionFile(): string | undefined;
 };
 
 export type CreateRecordSessionOptions = {
-  /** Role working directory — used for git book-key discovery when the parent is not already under home. Not a record destination. */
+  /** Role working directory passed to the record session; not a placement input. */
   readonly cwd: string;
   /** What kind of record this is (e.g. "auditor-roles"). Single path segment; not a destination path. */
   readonly kind: string;
-  /** Optional parent session — supplies parentSession link; nest under parent only when that parent already lives under the ledger home. */
+  /** Parent session — nesting authority for ordinary kinds; optional parentSession link for navigator. */
   readonly parent?: RecordSessionParent;
-  /** Stable work identity for book-level records which continue across role runs. */
+  /**
+   * Durable work-subject intent. For navigator only, selects the book-top
+   * `navigator/<work-subject>` nest (dossier-topology / #852); does not restore
+   * generic kind partitions.
+   */
   readonly subject?: string;
+  /**
+   * Process home when no parent path can derive the ledger home. Not a record
+   * destination — same identity surface as resolveActivationLedgerHome(home).
+   */
+  readonly home?: string;
 };
 
 /** Authorized no-subject kind that may resume the most recent same-nest peer (ADR 0066). Sole string true source for gate resume identity. */
@@ -122,10 +353,10 @@ function assertRecentFinalFileUnderSessionDir(
   }
 }
 
-/** Open result including the sole resumed fact (nest existed before this open). */
+/** Open result including the sole continuation fact. */
 export type RecordSessionOpen = {
   readonly session: SessionManager;
-  /** True only when an existing same-nest volume was reopened (subject/gate path). */
+  /** True when an existing navigator work-subject or worker-submission-gate volume was reopened. */
   readonly resumed: boolean;
 };
 
@@ -136,8 +367,8 @@ export type RecordSessionOpen = {
  * identity is checked once before SessionManager.open (directory walk cannot see a
  * trailing .jsonl symlink). New principals mint under the already-validated sessionDir
  * via destination-free SessionManager.create — no derived postcondition.
- * Resume via the AK-owned current-session ledger is limited to subject-keyed identity
- * and the authorized worker-submission-gate durable path (ADR 0066).
+ * Resume via the AK-owned current-session ledger is limited to navigator work-subject
+ * nests and the authorized worker-submission-gate durable path (ADR 0066 / #852).
  * Other ordinary no-subject children (auditor-roles, evidence-children, …) always mint fresh.
  * New persisted principals materialize their deferred session header before return so
  * custom-entry-only writers do not need a parallel delayed-header helper.
@@ -147,52 +378,68 @@ export type RecordSessionOpen = {
 export function createRecordSessionOpen(options: CreateRecordSessionOptions): RecordSessionOpen {
   const cwd = options.cwd;
   const parentFile = options.parent?.getSessionFile();
-  // Path → ledger home is owned by topology (explicit env.home nests via parent path).
-  const ledgerHome = resolveActivationLedgerHomeForPath(parentFile);
 
   let sessionDir: string;
   let parentSession: string | undefined;
+  let mayResumeSameNest: boolean;
+  let ledgerHome: string;
 
-  if (options.subject !== undefined) {
-    sessionDir = subjectKeyedRecordDirectory({
+  // #852 sole book-top exception: navigator/<work-subject> via one topology authority.
+  // Holds for no parent / unmaterialized parent / materialized parent — never silent in-memory.
+  if (options.kind === NAVIGATOR_RECORD_KIND && options.subject !== undefined) {
+    const placement = resolveNavigatorWorkSubjectPlacement({
       cwd,
-      kind: options.kind,
       subject: options.subject,
       ...(parentFile === undefined || parentFile.length === 0
         ? {}
         : { parentSessionFile: parentFile }),
+      ...(options.home === undefined ? {} : { home: options.home }),
     });
+    sessionDir = placement.sessionDir;
+    ledgerHome = placement.ledgerHome;
     parentSession = parentFile && parentFile.length > 0 ? parentFile : undefined;
+    mayResumeSameNest = true;
   } else if (parentFile === undefined || parentFile.length === 0) {
-    // No durable parent principal — preserve prior in-memory child behavior.
-    return { session: SessionManager.inMemory(cwd), resumed: false };
+    if (options.subject === undefined) {
+      // No durable principal requested: preserve prior in-memory child behavior.
+      return { session: SessionManager.inMemory(cwd), resumed: false };
+    }
+    throw new Error("Durable record ownership requires a parent session inside the ledger home");
   } else {
+    ledgerHome = resolveActivationLedgerHomeForPath(parentFile);
     const parentResolved = resolve(parentFile);
-    // Nest under parent only when the parent record already lives under the package home.
-    // Nest base is dirname(parent file) — the durable principal's directory — never a
-    // separate getSessionDir() that can diverge (empty in-memory dir + durable file).
-    // Otherwise the book is resolved from cwd (ADR 0048) and the kind sits under that book —
-    // workspace / foreign parents cannot drag records out of home.
-    sessionDir = physicallyContainedIn(ledgerHome, parentResolved)
-      ? join(dirname(parentResolved), options.kind)
-      : join(activationBookDirectory(ledgerHome, resolveBookKeyFromGit(cwd)), options.kind);
+    if (!physicallyContainedIn(ledgerHome, parentResolved)) {
+      throw new Error("Durable record ownership requires a parent session inside the ledger home");
+    }
+    // Ordinary kinds: durable parent's file is the sole nesting authority. A divergent
+    // SessionManager directory must not create a second placement route.
+    // Do not restore generic bookDir/<kind> fallback for foreign/unrooted parents.
+    sessionDir = join(dirname(parentResolved), options.kind);
     parentSession = parentFile;
+    mayResumeSameNest = options.kind === WORKER_SUBMISSION_GATE_KIND;
   }
 
   const nestAlreadyExists = existsSync(sessionDir);
   // Directory-chain ownership: containment + physical components (no parallel assert).
   ensureRealDirectoryTree(ledgerHome, sessionDir);
-  // Subject-keyed nests continue by subject digest; worker-submission-gate is the
-  // sole authorized no-subject same-nest continuation. All other kinds mint fresh.
-  const mayResumeSameNest =
-    options.subject !== undefined || options.kind === WORKER_SUBMISSION_GATE_KIND;
   if (mayResumeSameNest && nestAlreadyExists) {
-    const recentFile = readCurrentSession(sessionDir);
-    assertRecentFinalFileUnderSessionDir(sessionDir, recentFile);
-    return {
-      session: SessionManager.open(recentFile, sessionDir, cwd),
-      resumed: true,
-    };
+    if (options.kind === NAVIGATOR_RECORD_KIND) {
+      const recentFile = resolveNavigatorNestContinuation(sessionDir, cwd);
+      if (recentFile !== undefined) {
+        return {
+          session: SessionManager.open(recentFile, sessionDir, cwd),
+          resumed: true,
+        };
+      }
+      // No sidecar and no cwd-matching session — mint fresh in the existing nest.
+    } else {
+      const recentFile = readCurrentSession(sessionDir);
+      assertRecentFinalFileUnderSessionDir(sessionDir, recentFile);
+      return {
+        session: SessionManager.open(recentFile, sessionDir, cwd),
+        resumed: true,
+      };
+    }
   }
 
   const session = SessionManager.create(

package/src/archivist-record-topology.ts

@@ -1,7 +1,11 @@
 /**
- * Pure archivist record placement topology (ADR 0048 / 0065).
+ * Pure archivist record placement topology (ADR 0048 / 0065 / dossier-topology).
  * No SessionManager / pi-coding-agent — cold public-bin and ledger discovery
  * may import this without pulling open-session runtime into the graph.
+ *
+ * Navigator work-subject is the sole book-top subject partition (#852):
+ * books/<book>/navigator/<work-subject-digest>/. Callers must not re-hash
+ * subject or re-join book/navigator/digest themselves.
  */
 import { createHash } from "node:crypto";
 import { join } from "node:path";
@@ -10,30 +14,51 @@ import { resolveBookKeyFromGit } from "./activation-ledger-git.ts";
 import {
   activationBookDirectory,
   resolveActivationLedgerHome,
-  resolveActivationLedgerHomeForPath,
+  tryHomeFromAkRolesPath,
 } from "./activation-ledger-topology.ts";
 
+/** Book-top partition for cross-ticket navigator route-memory (dossier-topology). */
+export const NAVIGATOR_RECORD_KIND = "navigator" as const;
+
+/** One resolved navigator work-subject placement — ledger root and nest together. */
+export type NavigatorWorkSubjectPlacement = {
+  readonly ledgerHome: string;
+  readonly sessionDir: string;
+};
+
 /**
- * Sole subject-keyed nest path under the ledger book (ADR 0048 / 0065).
- * Callers must not re-hash subject or re-join book/kind/digest themselves.
+ * Sole navigator work-subject placement under the ledger book.
+ * Returns ledgerHome and nest once so createRecordSessionOpen does not re-branch
+ * parent/home. Work-subject key shape is sha256(subject) hex truncated to 32
+ * (#852 out of scope — shape unchanged).
+ *
+ * parentSessionFile contributes home only when tryHomeFromAkRolesPath succeeds;
+ * otherwise the explicit home (from HostContext.runDirectory) is kept. Never
+ * invents a second home via passwd/env fallback from a foreign parent path.
  */
-export function subjectKeyedRecordDirectory(input: {
+export function resolveNavigatorWorkSubjectPlacement(input: {
   readonly cwd: string;
-  readonly kind: string;
   readonly subject: string;
-  /** Parent session file — home path-derives from it when present. */
+  /** Parent session file — home path-derives from it only under .ak-roles. */
   readonly parentSessionFile?: string;
-  /** Explicit process home when no parent file is available (discovery-only). */
+  /** Explicit process home when no ledger parent path is available. */
   readonly home?: string;
-}): string {
-  const ledgerHome =
-    input.parentSessionFile !== undefined && input.parentSessionFile.length > 0
-      ? resolveActivationLedgerHomeForPath(input.parentSessionFile)
-      : resolveActivationLedgerHome(input.home);
+}): NavigatorWorkSubjectPlacement {
+  let ledgerHome: string | undefined;
+  if (input.parentSessionFile !== undefined && input.parentSessionFile.length > 0) {
+    const fromParent = tryHomeFromAkRolesPath(input.parentSessionFile);
+    if (fromParent !== undefined && fromParent.length > 0) {
+      ledgerHome = resolveActivationLedgerHome(fromParent);
+    }
+  }
+  ledgerHome ??= resolveActivationLedgerHome(input.home);
   const digest = createHash("sha256").update(input.subject).digest("hex").slice(0, 32);
-  return join(
-    activationBookDirectory(ledgerHome, resolveBookKeyFromGit(input.cwd)),
-    input.kind,
-    digest,
-  );
+  return {
+    ledgerHome,
+    sessionDir: join(
+      activationBookDirectory(ledgerHome, resolveBookKeyFromGit(input.cwd)),
+      NAVIGATOR_RECORD_KIND,
+      digest,
+    ),
+  };
 }

package/src/auditor-dossier-tool.ts

@@ -2,6 +2,7 @@ import { dirname, join, resolve } from "node:path";
 
 import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { HostContext } from "./host-contracts.ts";
+import { roleRunArtifactsDirectory } from "./role-run-placement.ts";
 import { Type } from "typebox";
 
 export const AUDITOR_DOSSIER_TOOL_NAME = "ak_get_run_dossier" as const;
@@ -45,7 +46,7 @@ export function createAuditorDossierTool(
         admittedRequest: join(runDirectory, "admitted-request.json"),
         parentSessionCandidate: join(runDirectory, "session", "session.jsonl"),
         attachments: join(runDirectory, "attachments"),
-        artifacts: join(runDirectory, "artifacts"),
+        artifacts: roleRunArtifactsDirectory(runDirectory),
       };
       return {
         content: [{ type: "text", text: JSON.stringify(details) }],