@akagilnc/pi-workflow-roles 0.1.1751

package/src/sha256.ts

@@ -0,0 +1,6 @@
+import { createHash } from "node:crypto";
+
+/** Canonical lowercase SHA-256 encoding shared by reviewer identity seams. */
+export function sha256Hex(bytes: string | Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}

package/src/sitian-record-entry.ts

@@ -0,0 +1,57 @@
+/**
+ * 司天台唯一 Pi session 记录落盘入口（ADR 0065）。
+ * 调用方只声明自己是谁的什么；落点由候簿拓扑算出，签名不含任何落点/路径参数。
+ * 「谁调了谁」复用 Pi parentSession + ADR 0047 correlation，不新增 caller 字段。
+ */
+import { dirname, resolve, join } from "node:path";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+
+import { resolveBookKeyFromGit } from "./activation-ledger-git.ts";
+import {
+  activationBookDirectory,
+  ensureRealDirectoryTree,
+  physicallyContainedIn,
+  resolveActivationLedgerHome,
+} from "./activation-ledger-topology.ts";
+
+/** Parent session surface needed to link and (when already under home) nest 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. */
+  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. */
+  readonly parent?: RecordSessionParent;
+};
+
+/**
+ * Sole package entry that constructs a durable Pi session record (ADR 0065).
+ * No destination/path parameters — location is computed from ledger topology only.
+ */
+export function createRecordSession(options: CreateRecordSessionOptions): SessionManager {
+  const cwd = options.cwd;
+  const parentFile = options.parent?.getSessionFile();
+  if (parentFile === undefined || parentFile.length === 0) {
+    // No durable parent principal — preserve prior in-memory child behavior.
+    return SessionManager.inMemory(cwd);
+  }
+
+  const ledgerHome = resolveActivationLedgerHome();
+  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.
+  const sessionDir = physicallyContainedIn(ledgerHome, parentResolved)
+    ? join(dirname(parentResolved), options.kind)
+    : join(activationBookDirectory(ledgerHome, resolveBookKeyFromGit(cwd)), options.kind);
+
+  ensureRealDirectoryTree(ledgerHome, sessionDir);
+  return SessionManager.create(cwd, sessionDir, { parentSession: parentFile });
+}

package/src/stderr-jsonl.ts

@@ -0,0 +1,28 @@
+import { writeSync } from "node:fs";
+
+const STDERR_JSONL_WRITE_RETRY_LIMIT = 100;
+
+/**
+ * Write one complete JSONL record to fd 2.
+ * Retries EAGAIN/EINTR and short writes; never writes stdout.
+ */
+export function writeStderrJsonlRecord(
+  record: unknown,
+  write: typeof writeSync = writeSync,
+): void {
+  const bytes = Buffer.from(`${JSON.stringify(record)}\n`);
+  let offset = 0;
+  let retries = 0;
+  while (offset < bytes.length) {
+    try {
+      const written = write(2, bytes, offset, bytes.length - offset);
+      if (written <= 0) throw new Error("stderr JSONL write made no progress");
+      offset += written;
+      retries = 0;
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if ((code === "EAGAIN" || code === "EINTR") && retries++ < STDERR_JSONL_WRITE_RETRY_LIMIT) continue;
+      throw error;
+    }
+  }
+}

package/src/stream-idle-guard.ts

@@ -0,0 +1,98 @@
+/**
+ * Stream idle backstop (#102 / #155 a): first-wait + between-event silence only.
+ * Not a total wall-clock for long thinking turns.
+ *
+ * Default silence budget is owner-final 183s (#102 2026-08-04),
+ * same numeric value as header timeoutMs but a distinct body-idle clock.
+ */
+
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 183_000;
+export const STREAM_IDLE_TIMEOUT_CODE = "AK_STREAM_IDLE_TIMEOUT" as const;
+
+export class StreamIdleTimeoutError extends Error {
+  readonly code = STREAM_IDLE_TIMEOUT_CODE;
+  readonly idleTimeoutMs: number;
+
+  constructor(idleTimeoutMs: number, options?: ErrorOptions) {
+    super(`stream idle timeout after ${idleTimeoutMs}ms`, options);
+    this.name = "StreamIdleTimeoutError";
+    this.idleTimeoutMs = idleTimeoutMs;
+  }
+}
+
+export function isStreamIdleTimeoutError(value: unknown): value is StreamIdleTimeoutError {
+  return value instanceof StreamIdleTimeoutError
+    || (
+      typeof value === "object"
+      && value !== null
+      && (value as { name?: unknown }).name === "StreamIdleTimeoutError"
+      && (value as { code?: unknown }).code === STREAM_IDLE_TIMEOUT_CODE
+    );
+}
+
+export type StreamIdleGuardOptions = {
+  idleTimeoutMs?: number;
+  parentSignal?: AbortSignal;
+};
+
+export type StreamIdleGuard = {
+  readonly signal: AbortSignal;
+  poke(): void;
+  dispose(): void;
+};
+
+export function createStreamIdleGuard(
+  options: StreamIdleGuardOptions = {},
+): StreamIdleGuard {
+  const idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+  const parentSignal = options.parentSignal;
+
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let disposed = false;
+
+  const clear = (): void => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  const arm = (): void => {
+    if (disposed || controller.signal.aborted || idleTimeoutMs <= 0) return;
+    clear();
+    timer = setTimeout(() => {
+      timer = undefined;
+      if (disposed || controller.signal.aborted) return;
+      controller.abort(new StreamIdleTimeoutError(idleTimeoutMs));
+    }, idleTimeoutMs);
+  };
+
+  const onParentAbort = (): void => {
+    if (controller.signal.aborted) return;
+    clear();
+    controller.abort(parentSignal?.reason);
+  };
+
+  if (parentSignal !== undefined) {
+    if (parentSignal.aborted) {
+      controller.abort(parentSignal.reason);
+    } else {
+      parentSignal.addEventListener("abort", onParentAbort);
+    }
+  }
+
+  arm();
+
+  return {
+    signal: controller.signal,
+    poke(): void {
+      arm();
+    },
+    dispose(): void {
+      disposed = true;
+      clear();
+      parentSignal?.removeEventListener("abort", onParentAbort);
+    },
+  };
+}