@llblab/pi-kit 0.38.3 → 0.39.0

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

@@ -4,9 +4,33 @@
  * 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 { 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";
+let pendingSpawnAdmission;
+const freshManagedAttempts = new WeakMap();
+/** Available only before this synchronous admission invokes its factory; never retroactively adopt a born process. */
+export function readPendingCommandSpawnAdmission() {
+    return pendingSpawnAdmission;
+}
+/** Kernel-only launch observation capability; copies and references retained past the callback are not authority. */
+export function requireFreshManagedCommandAttempt(context, admission) {
+    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;
+}
+const nativeCloseReceipts = new WeakMap();
+/** Exact retained process close during its synchronous receipt callback, never a serialized terminal claim. */
+export function requireNativeCommandAttemptClose(receipt, admission, child) {
+    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;
+}
 const DEFAULT_COMMAND_CAPTURE_LIMIT_BYTES = 1024 * 1024;
 const COMMAND_TEMPLATE_RISK_LABEL_ORDER = [
     "risk.shell",
@@ -634,7 +658,7 @@ export async function execCommandTemplate(command, args, options = {}) {
                 captureDir: join(options.captureDir, `attempt-${String(attempt).padStart(3, "0")}`),
             }
             : options;
-        const result = await execCommandTemplateOnce(command, args, attemptOptions);
+        const result = await execCommandTemplateOnce(command, args, attemptOptions, attempt);
         if (result.code === 0)
             return result;
         lastResult = result;
@@ -649,8 +673,9 @@ function trimCaptureTail(value, limit) {
         start += 1;
     return value.subarray(start);
 }
-function createBoundedCommandCapture(stream, limit, getCaptureDir, persistCompleteStream) {
+function createBoundedCommandCapture(stream, limit, getCaptureDir, persistCompleteStream, onFailure) {
     let bytes = 0;
+    const digest = stream === "stdout" && persistCompleteStream ? createHash("sha256") : undefined;
     let content = Buffer.alloc(0);
     let file = persistCompleteStream
         ? join(getCaptureDir(), `${stream}.log`)
@@ -658,163 +683,272 @@ function createBoundedCommandCapture(stream, limit, getCaptureDir, persistComple
     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]);
+            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);
             }
-            if (!file) {
-                file = join(getCaptureDir(), `${stream}.log`);
-                writeFileSync(file, content);
+            catch (error) {
+                incomplete = true;
+                onFailure(error);
             }
-            appendFileSync(file, chunk);
-            content = trimCaptureTail(Buffer.concat([content, chunk]), limit);
         },
         result() {
-            if (!file && persistCompleteStream) {
-                file = join(getCaptureDir(), `${stream}.log`);
-                writeFileSync(file, content);
+            let retainedFile = file;
+            let fileBytes;
+            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,
             };
         },
     };
 }
-function execCommandTemplateOnce(command, args, options = {}) {
-    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;
-        const getCaptureDir = () => {
-            if (captureDir)
+function execCommandTemplateOnce(command, args, options, attempt) {
+    return new Promise((resolve, reject) => {
+        let failure;
+        let managed;
+        let invoked = false;
+        let admissionOpen = true;
+        const spawnAdmission = Object.freeze({ attempt });
+        const rememberFailure = (error) => { failure ??= { error }; };
+        const start = () => {
+            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;
+            const getCaptureDir = () => {
+                if (captureDir)
+                    return captureDir;
+                captureDir = options.captureDir
+                    ? resolvePath(options.captureDir)
+                    : mkdtempSync(join(tmpdir(), "pi-actors-command-"));
+                mkdirSync(captureDir, { recursive: true });
                 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;
-        let killTimeoutId;
-        const signalProcessTree = (signal) => {
-            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();
-            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 = [];
-            const collect = (parent) => {
-                for (const child of children.get(parent) ?? []) {
-                    collect(child);
-                    descendants.push(child);
+            };
+            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;
+            let killTimeoutId;
+            const signalProcessTree = (signal) => {
+                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();
+                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 = [];
+                const collect = (parent) => {
+                    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.code !== "ESRCH")
+                            throw error;
+                    }
+                }
+            };
+            const killProcess = () => {
+                if (killed)
+                    return;
+                killed = true;
+                signalProcessTree("SIGTERM");
+                killTimeoutId = setTimeout(() => {
+                    if (!settled)
+                        signalProcessTree("SIGKILL");
+                }, options.killGrace ?? 5000);
             };
-            collect(proc.pid);
-            for (const pid of [...descendants, proc.pid]) {
+            const settle = (code, nativeExitCode, nativeSignal) => {
+                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, ...(stdout.fileBytes === undefined ? {} : { stdoutFileBytes: stdout.fileBytes }) } : {}),
+                    ...(stderr.incomplete ? { stderrCaptureIncomplete: true, ...(stderr.fileBytes === undefined ? {} : { stderrFileBytes: stderr.fileBytes }) } : {}),
+                };
                 try {
-                    process.kill(pid, signal);
+                    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) {
-                    if (error.code !== "ESRCH")
-                        throw error;
+                    rememberFailure(error);
                 }
-            }
-        };
-        const killProcess = () => {
-            if (killed)
-                return;
-            killed = true;
-            signalProcessTree("SIGTERM");
-            killTimeoutId = setTimeout(() => {
-                if (!settled)
-                    signalProcessTree("SIGKILL");
-            }, options.killGrace ?? 5000);
-        };
-        const settle = (code) => {
-            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 (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) => {
+                stdoutCapture.append(data);
+            });
+            proc.stderr?.on("data", (data) => {
+                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();
+        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
-                options.signal.addEventListener("abort", killProcess, { once: true });
+                reject(error);
+        }
+        finally {
+            admissionOpen = false;
+            pendingSpawnAdmission = parentAdmission;
         }
-        if (options.timeout !== undefined && options.timeout > 0)
-            timeoutId = setTimeout(killProcess, options.timeout);
-        proc.stdout?.on("data", (data) => {
-            stdoutCapture.append(data);
-        });
-        proc.stderr?.on("data", (data) => {
-            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));
-        });
     });
 }
 export function buildCommandTemplateInvocation(config, values, cwd, options = {}) {

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

@@ -0,0 +1,32 @@
+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 declare const RUN_STREAM_SOURCE_MAX_BYTES: number;
+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";
+};
+/** Metadata-only: never reads body bytes, regardless of file size. */
+export declare function observeExecutionFileReference(stateDir: string, request: unknown): Readonly<ExecutionFileReferenceReading>;
+/** Raw text is kernel-local input to an authorized projection, never a tool/model result. */
+export declare function readExecutionSessionText(stateDir: string, path: string): Readonly<ExecutionTextReading>;
+/** Explicit command capture input only; neither this read nor its path authorizes publication. */
+export declare function readExecutionCaptureText(stateDir: string, path: string): Readonly<ExecutionTextReading>;
+/** Canonical runner text is kernel-local input, not complete command capture or a model-visible privacy projection. */
+export declare function readExecutionRunnerStreamText(stateDir: string, stream: unknown): Readonly<ExecutionTextReading>;

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

@@ -0,0 +1,128 @@
+/**
+ * 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 } from "node:fs";
+import { isAbsolute, join, resolve, win32 } from "node:path";
+import { SESSION_EVIDENCE_MAX_BYTES } from "./limits.js";
+export const RUN_STREAM_SOURCE_MAX_BYTES = 4 * 1024 * 1024;
+function unavailable(reason) { return Object.freeze({ availability: "unavailable", reason }); }
+function sameObject(left, right) { return left.dev === right.dev && left.ino === right.ino; }
+function sameFile(left, right) {
+    return right.isFile() && sameObject(left, right) && left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+function referencePath(request) {
+    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, request, maxTextBytes) {
+    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 = () => {
+                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;
+            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", path: relative, local_path: path, bytes_total: Number(opened.size), mutable: true, unchanged });
+            return text === undefined ? reference : Object.freeze({ availability: "available", reference, text });
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch (error) {
+        return unavailable(error.code === "ENOENT" ? "reference_missing" : "reference_unavailable");
+    }
+}
+/** Metadata-only: never reads body bytes, regardless of file size. */
+export function observeExecutionFileReference(stateDir, request) {
+    return inspectExecutionFile(stateDir, request);
+}
+/** Raw text is kernel-local input to an authorized projection, never a tool/model result. */
+export function readExecutionSessionText(stateDir, path) {
+    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, path) {
+    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, stream) {
+    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/dist/lib/execution-output.js

@@ -35,10 +35,11 @@ export function trimToTailBytes(value, maxBytes) {
     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) {
     const totalBytes = byteLength(content);

package/node_modules/@llblab/pi-actors/dist/lib/execution-sessions.d.ts

@@ -14,4 +14,22 @@ export interface ExecutionTurnItem extends SessionEvidence.SessionEvidenceTurn {
     sessionTruncated: boolean;
     stage?: string;
 }
-export declare function readExecutionTurns(stateDir: string): ExecutionTurnItem[];
+export declare const EXECUTION_CHRONOLOGY: unique symbol;
+export interface ExecutionChronologyEntry extends SessionEvidence.SessionChronologyEntry {
+    commandId: string;
+    sessionFile: string;
+    sessionOrdinal: number;
+}
+export type ExecutionChronology = Readonly<{
+    basis: "recorded_execution_metadata";
+    entries: readonly Readonly<ExecutionChronologyEntry>[];
+} & ({
+    state: "available";
+} | {
+    state: "unavailable";
+    reason: SessionEvidence.SessionChronologyReason | "source_changed" | "namespace_unavailable";
+})>;
+export type ExecutionTurnCollection = ExecutionTurnItem[] & {
+    readonly [EXECUTION_CHRONOLOGY]?: ExecutionChronology;
+};
+export declare function readExecutionTurns(stateDir: string): ExecutionTurnCollection;