@akagilnc/pi-workflow-roles 0.1.1751

package/src/activation-ledger-session.ts

@@ -0,0 +1,188 @@
+import {
+  lstatSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+
+import {
+  activationBookDirectory,
+  ensureRealDirectoryTree,
+  errnoCode,
+  errorText,
+  pathContainedIn,
+} from "./activation-ledger-topology.ts";
+
+export function childSessionManager(parent: { getSessionFile(): string | undefined; getSessionDir(): string } | undefined, cwd: string, childDirectory: string): SessionManager {
+  const parentSession = parent?.getSessionFile();
+  return parentSession === undefined
+    ? SessionManager.inMemory(cwd)
+    : SessionManager.create(cwd, join(parent!.getSessionDir(), childDirectory), { parentSession });
+}
+
+/** Durable pointer to the authoritative Pi session file principal (ADR 0048/0049). */
+export type ActivationSessionPointer = {
+  readonly kind: "session-file";
+  readonly path: string;
+};
+
+/** Session manager surface needed to admit (and, when deferred, materialize) the durable principal. */
+export type ActivationSessionManager = {
+  getSessionFile?(): string | undefined;
+  getHeader?(): { readonly type: string } | null;
+  /** Full SessionManager rebind after early header materialization (keeps Pi append path consistent). */
+  setSessionFile?(path: string): void;
+};
+
+/**
+ * Typed missing durable session principal. Callers discriminate with instanceof/code;
+ * never by parsing message prose. Original filesystem causes are retained.
+ */
+export class ActivationSessionFileMissingError extends Error {
+  readonly code = "AK_ACTIVATION_SESSION_FILE_MISSING" as const;
+  readonly path: string;
+  constructor(path: string, options?: { cause?: unknown }) {
+    super(
+      `Workflow role activation durable session file does not exist: ${path}`,
+      options?.cause === undefined ? undefined : { cause: options.cause },
+    );
+    this.name = "ActivationSessionFileMissingError";
+    this.path = path;
+  }
+}
+
+function materializeDeferredSessionFile(
+  sessionManager: ActivationSessionManager,
+  resolvedFile: string,
+  ledgerHome: string,
+): void {
+  const header = sessionManager.getHeader?.();
+  if (header === null || header === undefined || header.type !== "session") {
+    throw new ActivationSessionFileMissingError(resolvedFile);
+  }
+  ensureRealDirectoryTree(ledgerHome, dirname(resolvedFile));
+  try {
+    writeFileSync(resolvedFile, `${JSON.stringify(header)}\n`, { flag: "wx" });
+  } catch (error) {
+    if (errnoCode(error) !== "EEXIST") {
+      throw new Error(
+        `Workflow role activation failed to materialize durable session file (${resolvedFile}): ${errorText(error)}`,
+        { cause: error },
+      );
+    }
+    // Lost a create race — validate the winner below.
+  }
+  // Rebind full SessionManager so subsequent Pi appends use O_APPEND (flushed=true)
+  // instead of exclusive wx create against the file we just wrote.
+  if (typeof sessionManager.setSessionFile === "function") {
+    sessionManager.setSessionFile(resolvedFile);
+  }
+}
+
+/**
+ * Admit only a durable Pi session file principal under the resolved machine ledger
+ * book (ADR 0048). Requires an existing regular file at admission: resolve real paths
+ * and prove containment under the real book. Reject relative paths, outside-book paths,
+ * directories, symlink escapes, and nonexistent paths that cannot be materialized from
+ * the live SessionManager header. Original filesystem causes are retained.
+ *
+ * Upstream Pi defers exclusive create until the first assistant message. When the path
+ * is the live SessionManager principal under the book and only the header is in memory,
+ * admission materializes that header onto the same path before the fact is written so
+ * the role fact never points at a session that may be created later.
+ */
+export function durableSessionPointer(
+  sessionManager: ActivationSessionManager,
+  options: {
+    ledgerHome: string;
+    bookKey: string;
+  },
+): ActivationSessionPointer {
+  const file = sessionManager.getSessionFile?.();
+  if (typeof file !== "string" || file.length === 0) {
+    throw new Error(
+      "Workflow role activation requires a durable Pi session file principal (getSessionFile); directory-only or --no-session invocations are rejected",
+    );
+  }
+  if (!isAbsolute(file)) {
+    throw new Error(
+      `Workflow role activation requires an absolute durable session file path under the machine ledger book; got relative path: ${file}`,
+    );
+  }
+
+  const resolvedFile = resolve(file);
+  const bookRoot = resolve(activationBookDirectory(options.ledgerHome, options.bookKey));
+  if (!pathContainedIn(bookRoot, resolvedFile)) {
+    throw new Error(
+      `Workflow role activation requires the durable session file principal under the machine ledger book (${bookRoot}); got: ${resolvedFile}`,
+    );
+  }
+
+  try {
+    lstatSync(resolvedFile);
+  } catch (error) {
+    if (errnoCode(error) !== "ENOENT") {
+      throw new Error(
+        `Workflow role activation failed to stat durable session file (${resolvedFile}): ${errorText(error)}`,
+        { cause: error },
+      );
+    }
+    try {
+      materializeDeferredSessionFile(sessionManager, resolvedFile, options.ledgerHome);
+    } catch (materializeError) {
+      // Missing principal: rethrow typed missing-file identity with the original ENOENT cause.
+      // Other materialize failures keep their own typed/native identity.
+      if (materializeError instanceof ActivationSessionFileMissingError) {
+        throw new ActivationSessionFileMissingError(resolvedFile, { cause: error });
+      }
+      throw materializeError;
+    }
+  }
+
+  let realBook: string;
+  try {
+    realBook = realpathSync(bookRoot);
+  } catch (error) {
+    throw new Error(
+      `Workflow role activation machine ledger book is not resolvable (${bookRoot}): ${errorText(error)}`,
+      { cause: error },
+    );
+  }
+
+  let realFile: string;
+  try {
+    realFile = realpathSync(resolvedFile);
+  } catch (error) {
+    throw new ActivationSessionFileMissingError(resolvedFile, { cause: error });
+  }
+
+  if (!pathContainedIn(realBook, realFile)) {
+    throw new Error(
+      `Workflow role activation requires the durable session file principal under the machine ledger book (${realBook}); got: ${realFile}`,
+    );
+  }
+
+  let info: ReturnType<typeof statSync>;
+  try {
+    info = statSync(realFile);
+  } catch (error) {
+    throw new Error(
+      `Workflow role activation failed to stat durable session file (${realFile}): ${errorText(error)}`,
+      { cause: error },
+    );
+  }
+
+  if (info.isDirectory()) {
+    throw new Error(
+      `Workflow role activation durable session principal must be a file, not a directory: ${realFile}`,
+    );
+  }
+  if (!info.isFile()) {
+    throw new Error(
+      `Workflow role activation durable session principal is not a regular file: ${realFile}`,
+    );
+  }
+  return { kind: "session-file", path: realFile };
+}

package/src/activation-ledger-topology.ts

@@ -0,0 +1,301 @@
+import {
+  lstatSync,
+  mkdirSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+/**
+ * Typed activation-ledger path/fs failure. Callers discriminate with instanceof/code;
+ * never by parsing message prose. Original filesystem causes are retained.
+ */
+export class ActivationLedgerError extends Error {
+  readonly code = "AK_ACTIVATION_LEDGER" as const;
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(
+      message,
+      options?.cause === undefined ? undefined : { cause: options.cause },
+    );
+    this.name = "ActivationLedgerError";
+  }
+}
+
+/**
+ * Sole package-owned machine home (ADR 0048 / #78): one enumerable family under
+ * the process home directory. No env override — relative or invocation-varying
+ * homes would split the family and can write into a consumer repository.
+ * Process home must already be absolute; relative HOME is rejected before any write.
+ */
+export function resolveActivationLedgerHome(home: () => string = homedir): string {
+  const processHome = home();
+  if (typeof processHome !== "string" || processHome.length === 0 || !isAbsolute(processHome)) {
+    throw new ActivationLedgerError(
+      `activation ledger process home must be absolute, got ${JSON.stringify(processHome)}`,
+    );
+  }
+  return resolve(processHome, ".ak-roles");
+}
+
+/** Enumerable book directory for one basename key. */
+export function activationBookDirectory(ledgerHome: string, bookKey: string): string {
+  return join(ledgerHome, "books", bookKey);
+}
+
+/** Append-only waiting ledger path for one book. */
+export function activationWaitingLedgerPath(ledgerHome: string, bookKey: string): string {
+  return join(activationBookDirectory(ledgerHome, bookKey), "waiting.jsonl");
+}
+
+/** True when candidate resolves strictly inside root (boundary-safe; not a string-prefix check). */
+export function pathContainedIn(root: string, candidate: string): boolean {
+  const rel = relative(root, candidate);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+/**
+ * Physical path identity: realpath the longest existing prefix, then rejoin any
+ * not-yet-created suffix. Collapses macOS `/var` ↔ `/private/var` so containment
+ * checks do not depend on which side was realpath'd first.
+ */
+export function physicalPathIdentity(path: string): string {
+  const absolute = resolve(path);
+  const missing: string[] = [];
+  let cursor = absolute;
+  while (true) {
+    try {
+      const real = realpathSync(cursor);
+      return missing.length === 0 ? real : join(real, ...missing);
+    } catch (error) {
+      if (errnoCode(error) !== "ENOENT") {
+        // Non-absence failures keep lexical resolve — callers still get a path.
+        return absolute;
+      }
+      const parent = dirname(cursor);
+      if (parent === cursor) return absolute;
+      missing.unshift(basename(cursor));
+      cursor = parent;
+    }
+  }
+}
+
+/** Containment under physical path identity (symlink-stable). */
+export function physicallyContainedIn(root: string, candidate: string): boolean {
+  return pathContainedIn(physicalPathIdentity(root), physicalPathIdentity(candidate));
+}
+
+export function errnoCode(error: unknown): string | undefined {
+  return error !== null && typeof error === "object" && "code" in error
+    && typeof (error as { code: unknown }).code === "string"
+    ? (error as { code: string }).code
+    : undefined;
+}
+
+export function errorText(error: unknown): string {
+  if (!(error instanceof Error)) return String(error);
+  return error.message;
+}
+
+/**
+ * Ensure the configured ledger root is a physical directory identity.
+ * lstat before create/realpath: a root symlink is never admitted, even when its
+ * target is a directory. Missing roots are created; post-create re-lstat covers
+ * a concurrent symlink swap. Native stat/mkdir causes are retained.
+ */
+function assertPhysicalLedgerRoot(absoluteRoot: string): void {
+  let st: ReturnType<typeof lstatSync> | undefined;
+  try {
+    st = lstatSync(absoluteRoot);
+  } catch (error) {
+    if (errnoCode(error) !== "ENOENT") {
+      throw new ActivationLedgerError(
+        `activation ledger failed to stat home (${absoluteRoot}): ${errorText(error)}`,
+        { cause: error },
+      );
+    }
+  }
+
+  if (st === undefined) {
+    try {
+      mkdirSync(absoluteRoot, { recursive: true });
+    } catch (error) {
+      // The configured root has the same first-creator race as nested components:
+      // another process may win after our ENOENT observation. Admit only EEXIST,
+      // then type-check the winner below; every other native failure remains fatal.
+      if (errnoCode(error) !== "EEXIST") {
+        throw new ActivationLedgerError(
+          `activation ledger failed to create home (${absoluteRoot}): ${errorText(error)}`,
+          { cause: error },
+        );
+      }
+    }
+    try {
+      st = lstatSync(absoluteRoot);
+    } catch (error) {
+      throw new ActivationLedgerError(
+        `activation ledger failed to stat home (${absoluteRoot}): ${errorText(error)}`,
+        { cause: error },
+      );
+    }
+  }
+
+  if (st.isSymbolicLink()) {
+    throw new ActivationLedgerError(
+      `activation ledger home is a symbolic link: ${absoluteRoot}`,
+    );
+  }
+  if (!st.isDirectory()) {
+    throw new ActivationLedgerError(`activation ledger home is not a directory: ${absoluteRoot}`);
+  }
+}
+
+/**
+ * Create `targetDir` (and missing parents) under `root` as a physical directory chain.
+ * Every path component under the configured root is type-identified with lstat: a
+ * pre-existing symlink is never admitted — even when its target remains inside the
+ * machine home — so basename book partitions cannot alias across books (ADR 0048).
+ * The configured root itself must be a physical directory. Physical realpath
+ * containment and native filesystem causes are retained.
+ */
+export function ensureRealDirectoryTree(root: string, targetDir: string): string {
+  if (!isAbsolute(root)) {
+    throw new ActivationLedgerError(`activation ledger home must be absolute: ${root}`);
+  }
+  const absoluteRoot = resolve(root);
+  const absoluteTarget = resolve(targetDir);
+  if (absoluteTarget !== absoluteRoot && !pathContainedIn(absoluteRoot, absoluteTarget)) {
+    throw new ActivationLedgerError(
+      `activation ledger path escapes ledger home (${absoluteRoot}): ${absoluteTarget}`,
+    );
+  }
+
+  // Type-identity the configured root before realpath/creation. Nested component
+  // physical identity and containment below still apply once the root is physical.
+  assertPhysicalLedgerRoot(absoluteRoot);
+
+  let realRoot: string;
+  try {
+    realRoot = realpathSync(absoluteRoot);
+  } catch (error) {
+    throw new ActivationLedgerError(
+      `activation ledger home is not resolvable (${absoluteRoot}): ${errorText(error)}`,
+      { cause: error },
+    );
+  }
+  if (!statSync(realRoot).isDirectory()) {
+    throw new ActivationLedgerError(`activation ledger home is not a directory: ${realRoot}`);
+  }
+
+  const rel = absoluteTarget === absoluteRoot ? "" : relative(absoluteRoot, absoluteTarget);
+  if (rel === "") return realRoot;
+  if (isAbsolute(rel) || rel === ".." || rel.startsWith(`..${sep}`)) {
+    throw new ActivationLedgerError(
+      `activation ledger path escapes ledger home (${absoluteRoot}): ${absoluteTarget}`,
+    );
+  }
+
+  let lexicalCursor = absoluteRoot;
+  for (const part of rel.split(sep)) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") {
+      throw new ActivationLedgerError(`activation ledger path contains '..': ${absoluteTarget}`);
+    }
+    lexicalCursor = join(lexicalCursor, part);
+
+    let st: ReturnType<typeof lstatSync>;
+    try {
+      st = lstatSync(lexicalCursor);
+    } catch (error) {
+      if (errnoCode(error) !== "ENOENT") {
+        throw new ActivationLedgerError(
+          `activation ledger failed to stat path component (${lexicalCursor}): ${errorText(error)}`,
+          { cause: error },
+        );
+      }
+      try {
+        mkdirSync(lexicalCursor);
+      } catch (mkdirError) {
+        // Concurrent first-time creators can lose the mkdir race. Only EEXIST is
+        // recoverable; re-lstat/realpath validation below still admits the winner.
+        if (errnoCode(mkdirError) !== "EEXIST") {
+          throw new ActivationLedgerError(
+            `activation ledger failed to create directory (${lexicalCursor}): ${errorText(mkdirError)}`,
+            { cause: mkdirError },
+          );
+        }
+      }
+      try {
+        st = lstatSync(lexicalCursor);
+      } catch (statError) {
+        throw new ActivationLedgerError(
+          `activation ledger failed to stat path component (${lexicalCursor}): ${errorText(statError)}`,
+          { cause: statError },
+        );
+      }
+    }
+
+    // Book partitions and every parent under the machine home must be physical
+    // owned directories — in-home directory symlinks alias partitions (cross-book).
+    if (st.isSymbolicLink()) {
+      throw new ActivationLedgerError(
+        `activation ledger path component is a symbolic link: ${lexicalCursor}`,
+      );
+    }
+
+    if (!st.isDirectory()) {
+      throw new ActivationLedgerError(`activation ledger path component is not a directory: ${lexicalCursor}`);
+    }
+
+    let realCursor: string;
+    try {
+      realCursor = realpathSync(lexicalCursor);
+    } catch (error) {
+      throw new ActivationLedgerError(
+        `activation ledger path component is not resolvable (${lexicalCursor}): ${errorText(error)}`,
+        { cause: error },
+      );
+    }
+    if (realCursor !== realRoot && !pathContainedIn(realRoot, realCursor)) {
+      throw new ActivationLedgerError(
+        `activation ledger path component escapes ledger home (${lexicalCursor} -> ${realCursor})`,
+      );
+    }
+  }
+
+  try {
+    return realpathSync(absoluteTarget);
+  } catch (error) {
+    throw new ActivationLedgerError(
+      `activation ledger directory is not resolvable (${absoluteTarget}): ${errorText(error)}`,
+      { cause: error },
+    );
+  }
+}
+
+/**
+ * Reject a pre-existing ledger-file symlink before open/write follows it.
+ * A computed book may only append to its own regular waiting.jsonl — any symlink,
+ * including a target still inside the machine ledger home (cross-book redirect),
+ * violates ADR 0048 partition identity. Missing paths are admitted (O_CREAT).
+ */
+export function assertLedgerFileInsideHome(ledgerPath: string, ledgerHome: string): void {
+  if (!isAbsolute(ledgerHome)) {
+    throw new ActivationLedgerError(`activation ledger home must be absolute: ${ledgerHome}`);
+  }
+  const resolvedLedger = resolve(ledgerPath);
+  try {
+    if (!lstatSync(resolvedLedger).isSymbolicLink()) return;
+    throw new ActivationLedgerError(
+      `activation ledger file is a symbolic link: ${resolvedLedger}`,
+    );
+  } catch (error) {
+    if (errnoCode(error) !== "ENOENT") {
+      if (error instanceof ActivationLedgerError) throw error;
+      throw new ActivationLedgerError(
+        `activation ledger failed to stat ledger file (${resolvedLedger}): ${errorText(error)}`,
+        { cause: error },
+      );
+    }
+  }
+}