@llblab/pi-kit 0.38.3 → 0.39.0

package/node_modules/@llblab/pi-actors/lib/command-templates.ts

@@ -4,8 +4,9 @@
  * Owns portable command-template parsing, expansion, risk checks, retries, timeouts, and direct execution.
  */
 
-import { spawn, spawnSync } from "node:child_process";
-import { accessSync, appendFileSync, constants, mkdirSync, mkdtempSync, statSync, writeFileSync } from "node:fs";
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import { createHash } from "node:crypto";
+import { accessSync, appendFileSync, constants, lstatSync, mkdirSync, mkdtempSync, statSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, delimiter, extname, isAbsolute, join, resolve as resolvePath } from "node:path";
 
@@ -56,6 +57,12 @@ export interface CommandTemplateInvocation {
 }
 
 export interface CommandTemplateExecOptions {
+  /** Kernel-only synchronous admission around each native spawn, including retries. */
+  admitSpawn?: (start: () => ChildProcess) => ChildProcess;
+  /** Kernel-only fresh handle after capture/exit management, inside synchronous spawn admission. Not birth proof. */
+  onAttemptManaged?: (context: CommandTemplateManagedAttempt) => void;
+  /** Kernel observation of settled attempts only; no receipt exists for a denied spawn. */
+  onAttemptComplete?: (receipt: CommandTemplateAttemptReceipt) => void;
   cwd?: string;
   timeout?: number;
   signal?: AbortSignal;
@@ -77,6 +84,68 @@ export interface CommandTemplateExecResult {
   stderrFile?: string;
   stdoutTruncated?: boolean;
   stderrTruncated?: boolean;
+  stdoutCaptureIncomplete?: true;
+  stderrCaptureIncomplete?: true;
+  stdoutFileBytes?: number;
+  stderrFileBytes?: number;
+}
+
+export interface CommandTemplateManagedAttempt {
+  readonly attempt: number;
+  readonly process: ChildProcess;
+}
+
+export interface CommandTemplateSpawnAdmission { readonly attempt: number; }
+
+let pendingSpawnAdmission: CommandTemplateSpawnAdmission | undefined;
+const freshManagedAttempts = new WeakMap<CommandTemplateManagedAttempt, { process: ChildProcess; pid: number | undefined; admission: CommandTemplateSpawnAdmission }>();
+
+/** Available only before this synchronous admission invokes its factory; never retroactively adopt a born process. */
+export function readPendingCommandSpawnAdmission(): CommandTemplateSpawnAdmission | undefined {
+  return pendingSpawnAdmission;
+}
+
+/** Kernel-only launch observation capability; copies and references retained past the callback are not authority. */
+export function requireFreshManagedCommandAttempt(context: CommandTemplateManagedAttempt, admission?: CommandTemplateSpawnAdmission): CommandTemplateManagedAttempt {
+  const actual = freshManagedAttempts.get(context);
+  if (!actual || (admission !== undefined && actual.admission !== admission) || context.process !== actual.process || actual.process.pid !== actual.pid) {
+    throw new Error("Native process observation requires a fresh managed attempt from this runtime.");
+  }
+  return context;
+}
+
+export interface CommandTemplateAttemptReceipt {
+  readonly attempt: number;
+  /** Kernel-only digest of observed stdout bytes after complete capture persistence; not exposure/native authority. */
+  readonly stdoutSha256?: string;
+  readonly result: Readonly<CommandTemplateExecResult>;
+  readonly nativeExitCode?: number | null;
+  readonly nativeSignal?: NodeJS.Signals | null;
+}
+
+export interface CommandTemplateNativeClose {
+  readonly pid: number;
+  readonly nativeExitCode: number | null;
+  readonly nativeSignal: NodeJS.Signals | null;
+}
+
+const nativeCloseReceipts = new WeakMap<CommandTemplateAttemptReceipt, {
+  admission: CommandTemplateSpawnAdmission;
+  process: ChildProcess;
+  close: CommandTemplateNativeClose;
+}>();
+
+/** Exact retained process close during its synchronous receipt callback, never a serialized terminal claim. */
+export function requireNativeCommandAttemptClose(
+  receipt: CommandTemplateAttemptReceipt,
+  admission: CommandTemplateSpawnAdmission,
+  child: ChildProcess,
+): CommandTemplateNativeClose {
+  const actual = nativeCloseReceipts.get(receipt);
+  if (!actual || actual.admission !== admission || actual.process !== child || child.pid !== actual.close.pid) {
+    throw new Error("Native settlement requires its exact runtime-local process-close receipt.");
+  }
+  return actual.close;
 }
 
 export type CommandTemplateRiskLabel =
@@ -901,7 +970,7 @@ export async function execCommandTemplate(
           ),
         }
       : options;
-    const result = await execCommandTemplateOnce(command, args, attemptOptions);
+    const result = await execCommandTemplateOnce(command, args, attemptOptions, attempt);
     if (result.code === 0) return result;
     lastResult = result;
   }
@@ -914,6 +983,9 @@ interface BoundedCommandCapture {
     bytes: number;
     content: string;
     file?: string;
+    fileBytes?: number;
+    incomplete?: boolean;
+    sha256?: string;
     truncated: boolean;
   };
 }
@@ -930,39 +1002,54 @@ function createBoundedCommandCapture(
   limit: number,
   getCaptureDir: () => string,
   persistCompleteStream: boolean,
+  onFailure: (error: unknown) => void,
 ): BoundedCommandCapture {
   let bytes = 0;
+  const digest = stream === "stdout" && persistCompleteStream ? createHash("sha256") : undefined;
   let content: Buffer = Buffer.alloc(0);
   let file = persistCompleteStream
     ? join(getCaptureDir(), `${stream}.log`)
     : undefined;
   if (file) writeFileSync(file, Buffer.alloc(0));
   let truncated = false;
+  let incomplete = false;
   return {
     append(value) {
       const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
       bytes += chunk.length;
+      digest?.update(chunk);
       if (bytes > limit) truncated = true;
-      if (!file && bytes <= limit) {
-        content = Buffer.concat([content, chunk]);
-        return;
-      }
-      if (!file) {
-        file = join(getCaptureDir(), `${stream}.log`);
-        writeFileSync(file, content);
-      }
-      appendFileSync(file, chunk);
+      const previous = content;
       content = trimCaptureTail(Buffer.concat([content, chunk]), limit);
+      if (!file && bytes <= limit) return;
+      if (incomplete) return;
+      try {
+        if (!file) {
+          file = join(getCaptureDir(), `${stream}.log`);
+          writeFileSync(file, previous);
+        }
+        appendFileSync(file, chunk);
+      } catch (error) {
+        incomplete = true;
+        onFailure(error);
+      }
     },
     result() {
-      if (!file && persistCompleteStream) {
-        file = join(getCaptureDir(), `${stream}.log`);
-        writeFileSync(file, content);
+      let retainedFile = file;
+      let fileBytes: number | undefined;
+      if (incomplete && file) {
+        try {
+          const stat = lstatSync(file);
+          if (stat.isFile()) fileBytes = stat.size;
+          else retainedFile = undefined;
+        } catch { retainedFile = undefined; }
       }
       return {
         bytes,
         content: content.toString("utf8"),
-        ...(file ? { file } : {}),
+        ...(retainedFile ? { file: retainedFile } : {}),
+        ...(digest && !incomplete && retainedFile ? { sha256: digest.digest("hex") } : {}),
+        ...(incomplete ? { incomplete: true, ...(fileBytes === undefined ? {} : { fileBytes }) } : {}),
         truncated,
       };
     },
@@ -972,134 +1059,196 @@ function createBoundedCommandCapture(
 function execCommandTemplateOnce(
   command: string,
   args: string[],
-  options: CommandTemplateExecOptions = {},
+  options: CommandTemplateExecOptions,
+  attempt: number,
 ): Promise<CommandTemplateExecResult> {
-  return new Promise((resolve) => {
-    const proc = spawn(command, args, {
-      cwd: options.cwd,
-      shell: false,
-      stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
-    });
-    const captureLimit = Math.max(
-      1,
-      options.captureLimitBytes ?? DEFAULT_COMMAND_CAPTURE_LIMIT_BYTES,
-    );
-    let captureDir: string | undefined;
-    const getCaptureDir = (): string => {
-      if (captureDir) return captureDir;
-      captureDir = options.captureDir
-        ? resolvePath(options.captureDir)
-        : mkdtempSync(join(tmpdir(), "pi-actors-command-"));
-      mkdirSync(captureDir, { recursive: true });
-      return captureDir;
-    };
-    const persistCompleteStreams = options.captureDir !== undefined;
-    const stdoutCapture = createBoundedCommandCapture(
-      "stdout",
-      captureLimit,
-      getCaptureDir,
-      persistCompleteStreams,
-    );
-    const stderrCapture = createBoundedCommandCapture(
-      "stderr",
-      captureLimit,
-      getCaptureDir,
-      persistCompleteStreams,
-    );
-    let killed = false;
-    let settled = false;
-    let timeoutId: NodeJS.Timeout | undefined;
-    let killTimeoutId: NodeJS.Timeout | undefined;
-    const signalProcessTree = (signal: NodeJS.Signals): void => {
-      if (proc.pid === undefined) return;
-      if (process.platform === "win32") {
-        spawnSync("taskkill", [
-          "/PID",
-          String(proc.pid),
-          "/T",
-          ...(signal === "SIGKILL" ? ["/F"] : []),
-        ]);
-        return;
-      }
-      const snapshot = spawnSync("ps", ["-eo", "pid=,ppid="], { encoding: "utf8" });
-      const children = new Map<number, number[]>();
-      for (const line of snapshot.stdout?.split(/\r?\n/u) ?? []) {
-        const [pidText, parentText] = line.trim().split(/\s+/u);
-        const pid = Number(pidText);
-        const parent = Number(parentText);
-        if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(parent)) continue;
-        const siblings = children.get(parent) ?? [];
-        siblings.push(pid);
-        children.set(parent, siblings);
-      }
-      const descendants: number[] = [];
-      const collect = (parent: number): void => {
-        for (const child of children.get(parent) ?? []) {
-          collect(child);
-          descendants.push(child);
+  return new Promise((resolve, reject) => {
+    let failure: { error: unknown } | undefined;
+    let managed: ChildProcess | undefined;
+    let invoked = false;
+    let admissionOpen = true;
+    const spawnAdmission = Object.freeze({ attempt });
+    const rememberFailure = (error: unknown): void => { failure ??= { error }; };
+    const start = (): ChildProcess => {
+      if (!admissionOpen) throw new Error("Native spawn admission window is closed.");
+      if (invoked) throw new Error("Native spawn factory may be invoked only once per attempt.");
+      invoked = true;
+      pendingSpawnAdmission = undefined;
+      const captureLimit = Math.max(
+        1,
+        options.captureLimitBytes ?? DEFAULT_COMMAND_CAPTURE_LIMIT_BYTES,
+      );
+      let captureDir: string | undefined;
+      const getCaptureDir = (): string => {
+        if (captureDir) return captureDir;
+        captureDir = options.captureDir
+          ? resolvePath(options.captureDir)
+          : mkdtempSync(join(tmpdir(), "pi-actors-command-"));
+        mkdirSync(captureDir, { recursive: true });
+        return captureDir;
+      };
+      const persistCompleteStreams = options.captureDir !== undefined;
+      const stdoutCapture = createBoundedCommandCapture(
+        "stdout",
+        captureLimit,
+        getCaptureDir,
+        persistCompleteStreams,
+        rememberFailure,
+      );
+      const stderrCapture = createBoundedCommandCapture(
+        "stderr",
+        captureLimit,
+        getCaptureDir,
+        persistCompleteStreams,
+        rememberFailure,
+      );
+      let killed = false;
+      let settled = false;
+      let timeoutId: NodeJS.Timeout | undefined;
+      let killTimeoutId: NodeJS.Timeout | undefined;
+      const signalProcessTree = (signal: NodeJS.Signals): void => {
+        if (proc.pid === undefined) return;
+        if (process.platform === "win32") {
+          spawnSync("taskkill", [
+            "/PID",
+            String(proc.pid),
+            "/T",
+            ...(signal === "SIGKILL" ? ["/F"] : []),
+          ]);
+          return;
+        }
+        const snapshot = spawnSync("ps", ["-eo", "pid=,ppid="], { encoding: "utf8" });
+        const children = new Map<number, number[]>();
+        for (const line of snapshot.stdout?.split(/\r?\n/u) ?? []) {
+          const [pidText, parentText] = line.trim().split(/\s+/u);
+          const pid = Number(pidText);
+          const parent = Number(parentText);
+          if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(parent)) continue;
+          const siblings = children.get(parent) ?? [];
+          siblings.push(pid);
+          children.set(parent, siblings);
+        }
+        const descendants: number[] = [];
+        const collect = (parent: number): void => {
+          for (const child of children.get(parent) ?? []) {
+            collect(child);
+            descendants.push(child);
+          }
+        };
+        collect(proc.pid);
+        for (const pid of [...descendants, proc.pid]) {
+          try {
+            process.kill(pid, signal);
+          } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+          }
         }
       };
-      collect(proc.pid);
-      for (const pid of [...descendants, proc.pid]) {
+      const killProcess = (): void => {
+        if (killed) return;
+        killed = true;
+        signalProcessTree("SIGTERM");
+        killTimeoutId = setTimeout(() => {
+          if (!settled) signalProcessTree("SIGKILL");
+        }, options.killGrace ?? 5000);
+      };
+      const settle = (code: number, nativeExitCode?: number | null, nativeSignal?: NodeJS.Signals | null): void => {
+        if (settled) return;
+        settled = true;
+        if (timeoutId) clearTimeout(timeoutId);
+        if (killTimeoutId) clearTimeout(killTimeoutId);
+        if (options.signal)
+          options.signal.removeEventListener("abort", killProcess);
+        const stdout = stdoutCapture.result();
+        const stderr = stderrCapture.result();
+        const result = {
+          stdout: stdout.content,
+          stderr: stderr.content,
+          code,
+          killed,
+          stdoutBytes: stdout.bytes,
+          stderrBytes: stderr.bytes,
+          ...(stdout.file ? { stdoutFile: stdout.file } : {}),
+          ...(stderr.file ? { stderrFile: stderr.file } : {}),
+          ...(stdout.truncated ? { stdoutTruncated: true } : {}),
+          ...(stderr.truncated ? { stderrTruncated: true } : {}),
+          ...(stdout.incomplete ? { stdoutCaptureIncomplete: true as const, ...(stdout.fileBytes === undefined ? {} : { stdoutFileBytes: stdout.fileBytes }) } : {}),
+          ...(stderr.incomplete ? { stderrCaptureIncomplete: true as const, ...(stderr.fileBytes === undefined ? {} : { stderrFileBytes: stderr.fileBytes }) } : {}),
+        };
         try {
-          process.kill(pid, signal);
-        } catch (error) {
-          if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
-        }
-      }
-    };
-    const killProcess = (): void => {
-      if (killed) return;
-      killed = true;
-      signalProcessTree("SIGTERM");
-      killTimeoutId = setTimeout(() => {
-        if (!settled) signalProcessTree("SIGKILL");
-      }, options.killGrace ?? 5000);
-    };
-    const settle = (code: number): void => {
-      if (settled) return;
-      settled = true;
-      if (timeoutId) clearTimeout(timeoutId);
-      if (killTimeoutId) clearTimeout(killTimeoutId);
-      if (options.signal)
-        options.signal.removeEventListener("abort", killProcess);
-      const stdout = stdoutCapture.result();
-      const stderr = stderrCapture.result();
-      resolve({
-        stdout: stdout.content,
-        stderr: stderr.content,
-        code,
-        killed,
-        stdoutBytes: stdout.bytes,
-        stderrBytes: stderr.bytes,
-        ...(stdout.file ? { stdoutFile: stdout.file } : {}),
-        ...(stderr.file ? { stderrFile: stderr.file } : {}),
-        ...(stdout.truncated ? { stdoutTruncated: true } : {}),
-        ...(stderr.truncated ? { stderrTruncated: true } : {}),
+          if (options.onAttemptComplete) {
+            const receipt = Object.freeze({
+              attempt, result: Object.freeze({ ...result }),
+              ...(stdout.sha256 ? { stdoutSha256: stdout.sha256 } : {}),
+              ...(nativeExitCode !== undefined ? { nativeExitCode } : {}),
+              ...(nativeSignal !== undefined ? { nativeSignal } : {}),
+            });
+            const exitObserved = (Number.isSafeInteger(nativeExitCode) && nativeSignal === null) ||
+              (nativeExitCode === null && typeof nativeSignal === "string" && /^SIG[A-Z0-9]+$/.exec(nativeSignal)?.[0] === nativeSignal);
+            if (exitObserved && Number.isSafeInteger(proc.pid) && Number(proc.pid) > 0 &&
+              proc.exitCode === nativeExitCode && proc.signalCode === nativeSignal) {
+              nativeCloseReceipts.set(receipt, {
+                admission: spawnAdmission, process: proc,
+                close: Object.freeze({ pid: proc.pid!, nativeExitCode: nativeExitCode!, nativeSignal: nativeSignal! }),
+              });
+            }
+            try { options.onAttemptComplete(receipt); }
+            finally { nativeCloseReceipts.delete(receipt); }
+          }
+        } catch (error) { rememberFailure(error); }
+        if (failure) reject(failure.error);
+        else resolve(result);
+      };
+      const proc = spawn(command, args, {
+        cwd: options.cwd,
+        shell: false,
+        stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+      });
+      proc.stdout?.on("data", (data: Buffer) => {
+        stdoutCapture.append(data);
+      });
+      proc.stderr?.on("data", (data: Buffer) => {
+        stderrCapture.append(data);
+      });
+      proc.stdin?.on("error", () => {});
+      proc.on("error", (error) => {
+        const liveHandle = Number.isSafeInteger(proc.pid) && Number(proc.pid) > 0;
+        if (liveHandle) rememberFailure(error);
+        stderrCapture.append(error instanceof Error ? error.message : String(error));
+        if (!liveHandle) settle(1);
       });
+      proc.on("close", (code, signal) => {
+        settle(code ?? 1, code, signal);
+      });
+      managed = proc;
+      try {
+        if (options.signal) {
+          if (options.signal.aborted) killProcess();
+          else
+            options.signal.addEventListener("abort", killProcess, { once: true });
+        }
+        if (options.timeout !== undefined && options.timeout > 0)
+          timeoutId = setTimeout(killProcess, options.timeout);
+        if (options.stdin !== undefined) proc.stdin?.end(options.stdin);
+        if (options.onAttemptManaged) {
+          const context = Object.freeze({ attempt, process: proc });
+          freshManagedAttempts.set(context, { process: proc, pid: proc.pid, admission: spawnAdmission });
+          try { options.onAttemptManaged(context); }
+          finally { freshManagedAttempts.delete(context); }
+        }
+      } catch (error) { rememberFailure(error); }
+      return proc;
     };
-    if (options.signal) {
-      if (options.signal.aborted) killProcess();
-      else
-        options.signal.addEventListener("abort", killProcess, { once: true });
-    }
-    if (options.timeout !== undefined && options.timeout > 0)
-      timeoutId = setTimeout(killProcess, options.timeout);
-    proc.stdout?.on("data", (data: Buffer) => {
-      stdoutCapture.append(data);
-    });
-    proc.stderr?.on("data", (data: Buffer) => {
-      stderrCapture.append(data);
-    });
-    proc.stdin?.on("error", () => {});
-    if (options.stdin !== undefined) proc.stdin?.end(options.stdin);
-    proc.on("error", (error) => {
-      stderrCapture.append(error instanceof Error ? error.message : String(error));
-      settle(1);
-    });
-    proc.on("close", (code) => {
-      settle(code ?? (killed ? 1 : 0));
-    });
+    const parentAdmission = pendingSpawnAdmission;
+    try {
+      pendingSpawnAdmission = spawnAdmission;
+      const proc = options.admitSpawn ? options.admitSpawn(start) : start();
+      if (!managed) throw new Error("Native spawn admission must invoke its managed factory.");
+      if (proc !== managed) throw new Error("Native spawn admission must return its managed process.");
+    } catch (error) {
+      if (managed) rememberFailure(error);
+      else reject(error);
+    } finally { admissionOpen = false; pendingSpawnAdmission = parentAdmission; }
   });
 }
 

package/node_modules/@llblab/pi-actors/lib/execution-files.ts

@@ -0,0 +1,118 @@
+/**
+ * Execution-file layout and metadata observation beneath a caller-admitted Run state root.
+ * Owns: capture/session/canonical-runner stream layout, metadata and bounded strict text inputs through a checked descriptor.
+ * Excludes: Run/generation admission, unrestricted body exposure, discovery, privacy projection, historical-content or native authority.
+ */
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, type BigIntStats } from "node:fs";
+import { isAbsolute, join, resolve, win32 } from "node:path";
+import { SESSION_EVIDENCE_MAX_BYTES } from "./limits.ts";
+
+export type ExecutionFileReferenceReading =
+  | { readonly availability: "available"; readonly path: string; readonly local_path: string;
+      readonly bytes_total: number; readonly mutable: true; readonly unchanged: () => boolean }
+  | { readonly availability: "unavailable"; readonly reason: "invalid_reference" | "reference_missing" |
+      "reference_unavailable" | "reference_changed" | "reference_size_unrepresentable" };
+export const RUN_STREAM_SOURCE_MAX_BYTES = 4 * 1024 * 1024;
+export type ExecutionTextReading =
+  | { readonly availability: "available"; readonly reference: Extract<ExecutionFileReferenceReading, { availability: "available" }>; readonly text: string }
+  | { readonly availability: "unavailable"; readonly reason: Extract<ExecutionFileReferenceReading, { availability: "unavailable" }>["reason"] |
+      "reference_too_large" | "reference_invalid_text" };
+type Unavailable = Extract<ExecutionFileReferenceReading, { availability: "unavailable" }>;
+function unavailable(reason: Unavailable["reason"]): Readonly<Unavailable> { return Object.freeze({ availability: "unavailable", reason }); }
+function sameObject(left: BigIntStats, right: BigIntStats): boolean { return left.dev === right.dev && left.ino === right.ino; }
+function sameFile(left: BigIntStats, right: BigIntStats): boolean {
+  return right.isFile() && sameObject(left, right) && left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+function referencePath(request: unknown): string | undefined {
+  if (!request || typeof request !== "object" || Array.isArray(request)) return undefined;
+  const kind = Object.getOwnPropertyDescriptor(request, "kind")?.value;
+  const path = Object.getOwnPropertyDescriptor(request, "path")?.value;
+  if ((kind !== "session" && kind !== "capture" && kind !== "runner_stream") || typeof path !== "string" || !path || isAbsolute(path) || win32.isAbsolute(path) ||
+    /[\\\u0000-\u001f\u007f]/u.test(path) || (process.platform === "win32" && path.includes(":"))) return undefined;
+  const parts = path.split("/");
+  if (parts.some(part => !part || part === "." || part === "..")) return undefined;
+  if (kind === "runner_stream") return path === "stdout.log" || path === "stderr.log" ? path : undefined;
+  if (kind === "session") return parts[0] === "sessions" && parts.length >= 2 && parts.at(-1)!.endsWith(".jsonl") ? path : undefined;
+  const capture = /^captures\/command-([0-9]{3,})\/attempt-([0-9]{3,})\/(stdout|stderr)\.log$/u.exec(path);
+  return capture && capture.slice(1, 3).every(number => Number.isSafeInteger(Number(number)) && Number(number) > 0) ? path : undefined;
+}
+
+function inspectExecutionFile(stateDir: string, request: unknown): Readonly<ExecutionFileReferenceReading>;
+function inspectExecutionFile(stateDir: string, request: unknown, maxTextBytes: number): Readonly<ExecutionTextReading>;
+function inspectExecutionFile(stateDir: string, request: unknown, maxTextBytes?: number): Readonly<ExecutionFileReferenceReading | ExecutionTextReading> {
+  const relative = referencePath(request);
+  if (!relative) return unavailable("invalid_reference");
+  try {
+    const requestedRoot = resolve(stateDir);
+    const root = lstatSync(requestedRoot, { bigint: true });
+    if (!root.isDirectory() || root.isSymbolicLink()) return unavailable("reference_unavailable");
+    const canonicalRoot = realpathSync(requestedRoot);
+    const canonical = lstatSync(canonicalRoot, { bigint: true });
+    if (!canonical.isDirectory() || !sameObject(root, canonical)) return unavailable("reference_changed");
+    const directories = [{ path: requestedRoot, stamp: root }, { path: canonicalRoot, stamp: canonical }];
+    const parts = relative.split("/");
+    let directory = canonicalRoot;
+    for (const part of parts.slice(0, -1)) {
+      directory = join(directory, part);
+      const stamp = lstatSync(directory, { bigint: true });
+      if (!stamp.isDirectory() || stamp.isSymbolicLink()) return unavailable("reference_unavailable");
+      directories.push({ path: directory, stamp });
+    }
+    const path = join(canonicalRoot, ...parts);
+    const before = lstatSync(path, { bigint: true });
+    if (!before.isFile()) return unavailable("reference_unavailable");
+    if (before.size < 0n || before.size > BigInt(Number.MAX_SAFE_INTEGER)) return unavailable("reference_size_unrepresentable");
+    if (maxTextBytes !== undefined && before.size > BigInt(maxTextBytes)) return Object.freeze({ availability: "unavailable", reason: "reference_too_large" });
+    // Nonblocking/nofollow flags avoid waiting on a leaf replaced with a FIFO or following a leaf alias when supported.
+    const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+      const opened = fstatSync(fd, { bigint: true });
+      if (!sameFile(before, opened)) return unavailable("reference_changed");
+      const unchanged = (): boolean => {
+        try {
+          return directories.every(directory => {
+            const current = lstatSync(directory.path, { bigint: true });
+            return current.isDirectory() && sameObject(directory.stamp, current);
+          }) && sameFile(opened, lstatSync(path, { bigint: true }));
+        } catch { return false; }
+      };
+      let text: string | undefined;
+      if (maxTextBytes !== undefined) {
+        const bytes = Buffer.alloc(Number(opened.size)); let offset = 0;
+        while (offset < bytes.length) {
+          const count = readSync(fd, bytes, offset, bytes.length - offset, offset);
+          if (!count) return unavailable("reference_changed");
+          offset += count;
+        }
+        try { text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: !relative.startsWith("sessions/") }).decode(bytes); }
+        catch { return Object.freeze({ availability: "unavailable", reason: "reference_invalid_text" }); }
+      }
+      if (!sameFile(opened, fstatSync(fd, { bigint: true })) || !unchanged()) return unavailable("reference_changed");
+      const reference = Object.freeze({ availability: "available" as const, path: relative, local_path: path, bytes_total: Number(opened.size), mutable: true as const, unchanged });
+      return text === undefined ? reference : Object.freeze({ availability: "available", reference, text });
+    } finally { closeSync(fd); }
+  } catch (error) {
+    return unavailable((error as NodeJS.ErrnoException).code === "ENOENT" ? "reference_missing" : "reference_unavailable");
+  }
+}
+
+/** Metadata-only: never reads body bytes, regardless of file size. */
+export function observeExecutionFileReference(stateDir: string, request: unknown): Readonly<ExecutionFileReferenceReading> {
+  return inspectExecutionFile(stateDir, request);
+}
+
+/** Raw text is kernel-local input to an authorized projection, never a tool/model result. */
+export function readExecutionSessionText(stateDir: string, path: string): Readonly<ExecutionTextReading> {
+  return inspectExecutionFile(stateDir, { kind: "session", path }, SESSION_EVIDENCE_MAX_BYTES);
+}
+
+/** Explicit command capture input only; neither this read nor its path authorizes publication. */
+export function readExecutionCaptureText(stateDir: string, path: string): Readonly<ExecutionTextReading> {
+  return inspectExecutionFile(stateDir, { kind: "capture", path }, RUN_STREAM_SOURCE_MAX_BYTES);
+}
+
+/** Canonical runner text is kernel-local input, not complete command capture or a model-visible privacy projection. */
+export function readExecutionRunnerStreamText(stateDir: string, stream: unknown): Readonly<ExecutionTextReading> {
+  if (stream !== "stdout" && stream !== "stderr") return unavailable("invalid_reference");
+  return inspectExecutionFile(stateDir, { kind: "runner_stream", path: `${stream}.log` }, RUN_STREAM_SOURCE_MAX_BYTES);
+}

package/node_modules/@llblab/pi-actors/lib/execution-output.ts

@@ -50,10 +50,10 @@ export function byteLength(value: string): number {
 export function trimToTailBytes(value: string, maxBytes: number): string {
   const buffer = Buffer.from(value, "utf8");
   if (buffer.length <= maxBytes) return value;
-  return buffer
-    .subarray(buffer.length - maxBytes)
-    .toString("utf8")
-    .replace(/^\uFFFD+/, "");
+  let start = Math.ceil(buffer.length - maxBytes);
+  // Skip only the cut code point's continuation bytes, not genuine U+FFFD text.
+  while (start < buffer.length && (buffer[start] & 0xc0) === 0x80) start++;
+  return buffer.subarray(start).toString("utf8");
 }
 
 export function truncateTailContent(content: string): {