@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/dist/lib/runs-parent-teardown.js

@@ -0,0 +1,172 @@
+/**
+ * Parent-session actor teardown.
+ * Owns: exact-owner running-run selection, kill revalidation, bounded outcomes, and partial-failure continuation.
+ */
+const SUMMARY_ENTRY_LIMIT = 200;
+const SUMMARY_TEXT_LIMIT = 500;
+function boundedSummaryText(value) {
+    return value.length > SUMMARY_TEXT_LIMIT
+        ? `${value.slice(0, SUMMARY_TEXT_LIMIT - 1)}…`
+        : value;
+}
+export function buildBoundedParentTeardownSummary(result, ownerId, trigger, ts) {
+    const attempts = result.attempts.slice(0, SUMMARY_ENTRY_LIMIT).map((attempt) => ({
+        ownerId: boundedSummaryText(attempt.ownerId),
+        outcome: attempt.outcome,
+        ...(attempt.reason ? { reason: boundedSummaryText(attempt.reason) } : {}),
+        run: boundedSummaryText(attempt.run),
+        ...(attempt.runInstanceId
+            ? { runInstanceId: boundedSummaryText(attempt.runInstanceId) }
+            : {}),
+        stateDir: boundedSummaryText(attempt.stateDir),
+    }));
+    const discoveryFailures = result.discoveryFailures
+        .slice(0, SUMMARY_ENTRY_LIMIT)
+        .map((failure) => ({
+        path: boundedSummaryText(failure.path),
+        reason: boundedSummaryText(failure.reason),
+    }));
+    return {
+        attempted: result.attempted,
+        attempts,
+        attemptsOmitted: Math.max(0, result.attempts.length - attempts.length),
+        discoveryFailed: result.discoveryFailed,
+        discoveryFailures,
+        discoveryFailuresOmitted: Math.max(0, result.discoveryFailures.length - discoveryFailures.length),
+        failed: result.failed,
+        killed: result.killed,
+        ownerId: boundedSummaryText(ownerId),
+        skipped: result.skipped,
+        trigger: boundedSummaryText(trigger),
+        ts: boundedSummaryText(ts),
+        version: 1,
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function candidateFrom(ownerId, status) {
+    if (status.ownerId !== ownerId ||
+        status.status !== "running" ||
+        typeof status.run !== "string" ||
+        typeof status.state_dir !== "string") {
+        return undefined;
+    }
+    return {
+        ownerId,
+        run: status.run,
+        ...(typeof status.run_instance_id === "string"
+            ? { runInstanceId: status.run_instance_id }
+            : {}),
+        stateDir: status.state_dir,
+    };
+}
+export function selectParentRunTeardownCandidates(ownerId, statuses) {
+    if (!ownerId)
+        return [];
+    const byStateDir = new Map();
+    for (const status of statuses) {
+        const candidate = candidateFrom(ownerId, status);
+        if (candidate && !byStateDir.has(candidate.stateDir)) {
+            byStateDir.set(candidate.stateDir, candidate);
+        }
+    }
+    return [...byStateDir.values()].sort((left, right) => left.run.localeCompare(right.run));
+}
+function recordAttempt(deps, attempt) {
+    try {
+        deps.recordAttempt(attempt);
+        return attempt;
+    }
+    catch (error) {
+        return {
+            ...attempt,
+            outcome: "failed",
+            reason: `${attempt.reason ? `${attempt.reason}; ` : ""}evidence: ${errorMessage(error)}`,
+        };
+    }
+}
+export function teardownParentRuns(ownerId, deps) {
+    let discovery;
+    try {
+        const listed = deps.listRunStatuses();
+        discovery = Array.isArray(listed)
+            ? { failures: [], statuses: listed }
+            : listed;
+    }
+    catch (error) {
+        discovery = {
+            failures: [{ path: "<state-root>", reason: errorMessage(error) }],
+            statuses: [],
+        };
+    }
+    const candidates = selectParentRunTeardownCandidates(ownerId, discovery.statuses);
+    const attempts = [];
+    for (const candidate of candidates) {
+        let attempt;
+        try {
+            const current = deps.getRunStatus(candidate.stateDir);
+            if (!candidate.runInstanceId) {
+                attempt = {
+                    ...candidate,
+                    outcome: "failed",
+                    reason: "run generation unavailable",
+                };
+            }
+            else if (current.ownerId !== candidate.ownerId) {
+                attempt = {
+                    ...candidate,
+                    outcome: "skipped",
+                    reason: "ownership changed",
+                };
+            }
+            else if (current.run_instance_id !== candidate.runInstanceId) {
+                attempt = {
+                    ...candidate,
+                    outcome: "skipped",
+                    reason: "run generation changed",
+                };
+            }
+            else if (current.status !== "running") {
+                attempt = {
+                    ...candidate,
+                    outcome: "skipped",
+                    reason: "already terminal",
+                };
+            }
+            else {
+                const killed = deps.killRun(candidate.stateDir, {
+                    ownerId: candidate.ownerId,
+                    runInstanceId: candidate.runInstanceId,
+                });
+                attempt = killed.killed === true
+                    ? { ...candidate, outcome: "killed" }
+                    : {
+                        ...candidate,
+                        outcome: "failed",
+                        reason: typeof killed.reason === "string"
+                            ? killed.reason
+                            : "kill rejected",
+                    };
+            }
+        }
+        catch (error) {
+            attempt = {
+                ...candidate,
+                outcome: "failed",
+                reason: errorMessage(error),
+            };
+        }
+        attempts.push(recordAttempt(deps, attempt));
+    }
+    return {
+        attempted: candidates.length,
+        discoveryFailed: discovery.failures.length,
+        discoveryFailures: discovery.failures,
+        failed: attempts.filter((attempt) => attempt.outcome === "failed").length +
+            discovery.failures.length,
+        killed: attempts.filter((attempt) => attempt.outcome === "killed").length,
+        skipped: attempts.filter((attempt) => attempt.outcome === "skipped").length,
+        attempts,
+    };
+}

package/node_modules/@llblab/pi-actors/dist/lib/runs-process.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Async run process identity helpers.
+ * Owns: cross-platform liveness and stable runner process identity proofs.
+ */
+export interface RunProcessIdentity {
+    command: string;
+    cwd?: string;
+    platform: NodeJS.Platform;
+    start_time: string;
+}
+export type RunProcessIdentityStatus = "valid" | "dead_pid" | "owner_mismatch" | "unsupported_proof";
+export interface RunProcessIdentityResult {
+    status: RunProcessIdentityStatus;
+    valid: boolean;
+}
+type ProcessIdentityReader = (pid: number, runtimePlatform: NodeJS.Platform) => RunProcessIdentity | undefined;
+export declare function isAlive(pid: number): boolean;
+export declare function readProcessIdentity(pid: number, runtimePlatform?: NodeJS.Platform): RunProcessIdentity | undefined;
+export declare function captureRunProcessIdentity(pid: number, cwd: string, stateDir: string, runnerPath: string, runtimePlatform?: NodeJS.Platform, reader?: ProcessIdentityReader): RunProcessIdentity | undefined;
+export declare function verifyRunProcessIdentity(pid: number, expected: RunProcessIdentity | undefined, runtimePlatform?: NodeJS.Platform, reader?: ProcessIdentityReader, alive?: (pid: number) => boolean): RunProcessIdentityResult;
+export declare function isWithinRunnerIdentityGrace(meta: Record<string, unknown>, graceMs: number): boolean;
+export {};

package/node_modules/@llblab/pi-actors/dist/lib/runs-process.js

@@ -0,0 +1,125 @@
+/**
+ * Async run process identity helpers.
+ * Owns: cross-platform liveness and stable runner process identity proofs.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { platform } from "node:os";
+import { posix, win32 } from "node:path";
+export function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readLinuxIdentity(pid) {
+    if (!existsSync(`/proc/${pid}`))
+        return undefined;
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+        const close = stat.lastIndexOf(")");
+        const fields = stat.slice(close + 2).trim().split(/\s+/);
+        const startTime = fields[19];
+        if (!startTime)
+            return undefined;
+        return {
+            command: readFileSync(`/proc/${pid}/cmdline`, "utf8").replaceAll("\0", " ").trim(),
+            cwd: readlinkSync(`/proc/${pid}/cwd`),
+            platform: "linux",
+            start_time: startTime,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function readDarwinIdentity(pid) {
+    const result = spawnSync("ps", ["-p", String(pid), "-o", "lstart=", "-o", "command="], { encoding: "utf8" });
+    if (result.status !== 0)
+        return undefined;
+    const match = result.stdout.trim().match(/^(.{24})\s+(.+)$/s);
+    if (!match)
+        return undefined;
+    return {
+        command: match[2].trim(),
+        platform: "darwin",
+        start_time: match[1].trim(),
+    };
+}
+function readWindowsIdentity(pid) {
+    const command = [
+        `$p = Get-CimInstance Win32_Process -Filter \"ProcessId = ${pid}\";`,
+        "if ($null -eq $p) { exit 3 };",
+        "$p | Select-Object CreationDate,ExecutablePath,CommandLine | ConvertTo-Json -Compress",
+    ].join(" ");
+    const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command], { encoding: "utf8", windowsHide: true });
+    if (result.status !== 0)
+        return undefined;
+    try {
+        const value = JSON.parse(result.stdout);
+        if (typeof value.CreationDate !== "string")
+            return undefined;
+        const executable = typeof value.ExecutablePath === "string" ? value.ExecutablePath : "";
+        const commandLine = typeof value.CommandLine === "string" ? value.CommandLine : "";
+        return {
+            command: `${executable}\n${commandLine}`.trim(),
+            platform: "win32",
+            start_time: value.CreationDate,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readProcessIdentity(pid, runtimePlatform = platform()) {
+    if (runtimePlatform === "linux")
+        return readLinuxIdentity(pid);
+    if (runtimePlatform === "darwin")
+        return readDarwinIdentity(pid);
+    if (runtimePlatform === "win32")
+        return readWindowsIdentity(pid);
+    return undefined;
+}
+export function captureRunProcessIdentity(pid, cwd, stateDir, runnerPath, runtimePlatform = platform(), reader = readProcessIdentity) {
+    const identity = reader(pid, runtimePlatform);
+    if (!identity)
+        return undefined;
+    if (!identity.command.includes(runnerPath) || !identity.command.includes(stateDir)) {
+        return undefined;
+    }
+    const pathApi = runtimePlatform === "win32" ? win32 : posix;
+    const resolvedCwd = pathApi.resolve(cwd);
+    const canonicalCwd = runtimePlatform === platform() && existsSync(resolvedCwd)
+        ? realpathSync.native(resolvedCwd)
+        : resolvedCwd;
+    const expectedCwd = runtimePlatform === "win32" ? canonicalCwd.toLowerCase() : canonicalCwd;
+    const actualCwd = runtimePlatform === "win32" && identity.cwd
+        ? identity.cwd.toLowerCase()
+        : identity.cwd;
+    if (actualCwd && actualCwd !== expectedCwd)
+        return undefined;
+    return identity;
+}
+export function verifyRunProcessIdentity(pid, expected, runtimePlatform = platform(), reader = readProcessIdentity, alive = isAlive) {
+    if (!alive(pid))
+        return { status: "dead_pid", valid: false };
+    if (!expected || expected.platform !== runtimePlatform) {
+        return { status: "unsupported_proof", valid: false };
+    }
+    const current = reader(pid, runtimePlatform);
+    if (!current)
+        return { status: "unsupported_proof", valid: false };
+    const valid = current.start_time === expected.start_time &&
+        current.command === expected.command &&
+        current.cwd === expected.cwd;
+    return { status: valid ? "valid" : "owner_mismatch", valid };
+}
+export function isWithinRunnerIdentityGrace(meta, graceMs) {
+    const createdAt = typeof meta.createdAt === "string" ? Date.parse(meta.createdAt) : NaN;
+    return (Number.isFinite(createdAt) &&
+        Date.now() - createdAt >= 0 &&
+        Date.now() - createdAt <= graceMs);
+}

package/node_modules/@llblab/pi-actors/dist/lib/runs-retention.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Async run retention operations.
+ * Owns: terminal-run archive and prune filesystem behavior.
+ */
+import { cpSync } from "node:fs";
+export type RunRetentionAction = "archive" | "prune";
+export type RunRetentionOutcome = "queued" | "handled" | "failed";
+export declare function appendRunRetentionEvidence(status: Record<string, unknown>, action: RunRetentionAction, outcome: RunRetentionOutcome, options?: {
+    error?: string;
+    id?: string;
+    result?: Record<string, unknown>;
+}): string;
+export declare function archiveTerminalRun(status: Record<string, unknown>): Record<string, unknown>;
+export declare function pruneTerminalRun(status: Record<string, unknown>, options?: {
+    preserveArtifacts?: boolean;
+}, deps?: {
+    copyArtifact?: typeof cpSync;
+}): Record<string, unknown>;

package/node_modules/@llblab/pi-actors/dist/lib/runs-retention.js

@@ -0,0 +1,108 @@
+/**
+ * Async run retention operations.
+ * Owns: terminal-run archive and prune filesystem behavior.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { cpSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { acquireFileMutationLock, writeJsonAtomic, writeTextAtomic } from "./file-state.js";
+import * as Limits from "./limits.js";
+import { readJsonlFileResilient } from "./state-readers.js";
+import { resolveArtifactManifest, } from "./runs-artifacts.js";
+import { safeRunId } from "./runs-identity.js";
+import { assertOwnedRunStateDirectory } from "./runs-ownership.js";
+export function appendRunRetentionEvidence(status, action, outcome, options = {}) {
+    const stateDir = String(status.state_dir);
+    const path = join(dirname(stateDir), "retention.jsonl");
+    const id = options.id ?? randomUUID();
+    const record = {
+        action,
+        ...(options.error ? { error: options.error } : {}),
+        id,
+        outcome,
+        ...(options.result ? { result: options.result } : {}),
+        run: String(status.run ?? basename(stateDir)),
+        ...(typeof status.run_instance_id === "string" ? { run_instance_id: status.run_instance_id } : {}),
+        ts: new Date().toISOString(),
+    };
+    const release = acquireFileMutationLock(path);
+    try {
+        const records = [...readJsonlFileResilient(path).records, record]
+            .slice(-Limits.RUN_RETENTION_MAX_RECORDS);
+        let content = encodeRecords(records);
+        while (records.length && Buffer.byteLength(content) > Limits.RUN_RETENTION_MAX_BYTES) {
+            records.shift();
+            content = encodeRecords(records);
+        }
+        if (!records.includes(record))
+            throw new Error("Run retention record exceeds journal byte limit");
+        writeTextAtomic(path, content);
+    }
+    finally {
+        release();
+    }
+    return id;
+}
+function encodeRecords(records) {
+    return records.length ? `${records.map((value) => JSON.stringify(value)).join("\n")}\n` : "";
+}
+function retainedArtifactFilename(name, path) {
+    const readableName = name.replace(/[^A-Za-z0-9_.-]+/g, "_") || "artifact";
+    const identity = createHash("sha256")
+        .update(`${name}\0${path}`)
+        .digest("hex")
+        .slice(0, 8);
+    return `${readableName}-${identity}--${basename(path)}`;
+}
+function archivePathFor(run, stateDir) {
+    const archiveRoot = join(dirname(stateDir), "archived");
+    mkdirSync(archiveRoot, { recursive: true });
+    return join(archiveRoot, `${safeRunId(run)}-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+}
+export function archiveTerminalRun(status) {
+    const stateDir = String(status.state_dir);
+    const run = String(status.run ?? basename(stateDir));
+    assertOwnedRunStateDirectory(stateDir, run);
+    const archiveDir = archivePathFor(run, stateDir);
+    renameSync(stateDir, archiveDir);
+    mkdirSync(stateDir, { recursive: true });
+    const tombstone = {
+        archived: true,
+        archive_dir: archiveDir,
+        original_state_dir: stateDir,
+        run,
+        status: status.status,
+        ts: new Date().toISOString(),
+    };
+    writeJsonAtomic(join(stateDir, "archive-tombstone.json"), tombstone);
+    return tombstone;
+}
+export function pruneTerminalRun(status, options = {}, deps = {}) {
+    const stateDir = String(status.state_dir);
+    const run = String(status.run ?? basename(stateDir));
+    assertOwnedRunStateDirectory(stateDir, run);
+    const manifest = resolveArtifactManifest(status.artifacts);
+    const preserved = {};
+    if (options.preserveArtifacts && manifest) {
+        const preserveRoot = join(dirname(stateDir), "preserved-artifacts", safeRunId(run));
+        mkdirSync(preserveRoot, { recursive: true });
+        for (const [name, artifact] of Object.entries(manifest)) {
+            if (!artifact.exists)
+                continue;
+            const target = join(preserveRoot, retainedArtifactFilename(name, artifact.path));
+            (deps.copyArtifact ?? cpSync)(artifact.path, target, {
+                force: true,
+                preserveTimestamps: true,
+            });
+            preserved[name] = target;
+        }
+    }
+    rmSync(stateDir, { recursive: true, force: true });
+    return {
+        pruned: true,
+        preserved_artifacts: preserved,
+        run,
+        state_dir: stateDir,
+        ts: new Date().toISOString(),
+    };
+}

package/node_modules/@llblab/pi-actors/dist/lib/runs-start.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Async run start guards.
+ * Owns: active-run reuse checks, start lock acquisition, and safe state-dir
+ * preparation before a new runner process is spawned.
+ */
+import { type FileMutationLockOptions } from "./file-state.ts";
+type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
+export declare function readActiveOwnedRunState(stateDir: string, readJson: RunJsonReader, _runnerPath: string): Record<string, unknown> | undefined;
+export declare function assertNoActiveRunState(stateDir: string, readJson: RunJsonReader, runnerPath: string): void;
+export declare function acquireStateStartLock(stateDir: string, options?: FileMutationLockOptions): () => void;
+export declare function prepareStateDirForStart(stateDir: string, readJson: RunJsonReader, _runnerPath: string): void;
+export {};

package/node_modules/@llblab/pi-actors/dist/lib/runs-start.js

@@ -0,0 +1,68 @@
+/**
+ * Async run start guards.
+ * Owns: active-run reuse checks, start lock acquisition, and safe state-dir
+ * preparation before a new runner process is spawned.
+ */
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { acquireFileMutationLock, } from "./file-state.js";
+import { isAlive, verifyRunProcessIdentity, } from "./runs-process.js";
+export function readActiveOwnedRunState(stateDir, readJson, _runnerPath) {
+    const meta = readJson(join(stateDir, "run.json"));
+    if (!meta)
+        return undefined;
+    const result = readJson(join(stateDir, "result.json"));
+    if (typeof result?.completedAt === "string")
+        return undefined;
+    const pid = Number(meta.pid || 0);
+    if (!pid || !isAlive(pid))
+        return undefined;
+    const identity = verifyRunProcessIdentity(pid, meta.process_identity);
+    if (identity.status === "owner_mismatch") {
+        throw new Error(`Run state process identity does not match the live pid: ${String(meta.run ?? stateDir)}. Refusing to reuse the state directory while pid ${pid} is alive.`);
+    }
+    if (identity.status === "unsupported_proof") {
+        throw new Error(`Run state process identity proof is unavailable: ${String(meta.run ?? stateDir)}. Refusing to reuse the state directory while pid ${pid} is alive.`);
+    }
+    return identity.valid ? meta : undefined;
+}
+export function assertNoActiveRunState(stateDir, readJson, runnerPath) {
+    const meta = readActiveOwnedRunState(stateDir, readJson, runnerPath);
+    if (meta) {
+        throw new Error(`Run state already has an active owned process: ${String(meta.run ?? stateDir)}. Stop it before reusing the same run_id or state_dir.`);
+    }
+}
+export function acquireStateStartLock(stateDir, options = {}) {
+    return acquireFileMutationLock(join(stateDir, ".lifecycle"), options);
+}
+export function prepareStateDirForStart(stateDir, readJson, _runnerPath) {
+    const existing = readJson(join(stateDir, "run.json"));
+    const existingPid = Number(existing?.pid || 0);
+    if (existingPid && isAlive(existingPid)) {
+        const identity = verifyRunProcessIdentity(existingPid, existing?.process_identity);
+        if (identity.status === "owner_mismatch") {
+            throw new Error(`Run state process identity does not match the live pid: ${String(existing?.run ?? stateDir)}. Refusing to prepare the state directory while pid ${existingPid} is alive.`);
+        }
+        if (identity.status === "unsupported_proof") {
+            throw new Error(`Run state process identity proof is unavailable: ${String(existing?.run ?? stateDir)}. Refusing to prepare the state directory while pid ${existingPid} is alive.`);
+        }
+        if (identity.valid) {
+            throw new Error(`Run state already has an active owned process: ${String(existing?.run ?? stateDir)}. Stop it before restarting.`);
+        }
+    }
+    for (const file of [
+        "control-endpoint.json",
+        "controls.jsonl",
+        "events.jsonl",
+        "execution.json",
+        "progress.json",
+        "result.json",
+        "stderr.log",
+        "stdout.log",
+        "terminal-delivery-failure.json",
+        "terminal-handled.json",
+        "trace.jsonl",
+    ]) {
+        rmSync(join(stateDir, file), { force: true });
+    }
+}

package/node_modules/@llblab/pi-actors/dist/lib/runs-status.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Async run status and log readers.
+ * Owns: status derivation from run state files plus bounded log/event tails.
+ */
+export type AsyncRunStatus = "running" | "done" | "failed" | "exited" | "cancelled" | "killed";
+type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
+export declare function buildRunStatus(stateDir: string, runOrDir: string, meta: Record<string, unknown>, readJson: RunJsonReader, _runnerPath: string, _runnerIdentityGraceMs: number): Record<string, unknown>;
+export declare function tailFile(path: string, lines: number): string;
+export declare function tailLines(path: string, lines: number): string[];
+export {};

package/node_modules/@llblab/pi-actors/dist/lib/runs-status.js

@@ -0,0 +1,68 @@
+/**
+ * Async run status and log readers.
+ * Owns: status derivation from run state files plus bounded log/event tails.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { verifyRunProcessIdentity, } from "./runs-process.js";
+import { readJsonlFileResilient } from "./state-readers.js";
+function getInterruptedRunStatus(stateDir) {
+    const trace = readJsonlFileResilient(join(stateDir, "trace.jsonl")).records.slice(-200);
+    for (const event of trace.reverse()) {
+        if (event.kind === "run.kill")
+            return "killed";
+        if (event.kind === "run.cancel")
+            return "cancelled";
+    }
+    const legacyEvents = readJsonlFileResilient(join(stateDir, "events.jsonl")).records.slice(-200);
+    for (const event of legacyEvents.reverse()) {
+        if (event.event === "run.kill")
+            return "killed";
+        if (event.event === "run.cancel")
+            return "cancelled";
+    }
+    return undefined;
+}
+export function buildRunStatus(stateDir, runOrDir, meta, readJson, _runnerPath, _runnerIdentityGraceMs) {
+    const result = readJson(join(stateDir, "result.json"));
+    const pid = Number(meta.pid || 0);
+    const processIdentity = verifyRunProcessIdentity(pid, meta.process_identity);
+    const aliveOwnedRunner = Boolean(pid &&
+        (processIdentity.valid || processIdentity.status === "unsupported_proof"));
+    const status = result
+        ? Number(result.code ?? 0) === 0
+            ? "done"
+            : "failed"
+        : aliveOwnedRunner
+            ? "running"
+            : (getInterruptedRunStatus(stateDir) ?? "exited");
+    const terminalHandled = readJson(join(stateDir, "terminal-handled.json"));
+    const terminalDeliveryFailure = readJson(join(stateDir, "terminal-delivery-failure.json"));
+    return {
+        ...meta,
+        traceFile: join(stateDir, "trace.jsonl"),
+        executionFile: join(stateDir, "execution.json"),
+        process_identity_status: processIdentity.status,
+        progress: readJson(join(stateDir, "progress.json")) || null,
+        result: result || null,
+        ...(terminalDeliveryFailure
+            ? { terminal_delivery_failure: terminalDeliveryFailure } : {}),
+        ...(terminalHandled ? { terminal_handled: terminalHandled } : {}),
+        state_dir: String(meta.state_dir ?? stateDir),
+        stderrLog: join(stateDir, "stderr.log"),
+        stdoutLog: join(stateDir, "stdout.log"),
+        status,
+    };
+}
+export function tailFile(path, lines) {
+    if (!existsSync(path))
+        return "";
+    const content = readFileSync(path, "utf8").trimEnd();
+    if (!content)
+        return "";
+    return content.split("\n").slice(-lines).join("\n");
+}
+export function tailLines(path, lines) {
+    const content = tailFile(path, lines);
+    return content ? content.split("\n") : [];
+}

package/node_modules/@llblab/pi-actors/dist/lib/runs-trace.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Run Trace event journal.
+ * Zones: structured event validation, bounded atomic retention, resilient reads
+ * Owns canonical Run-local Trace persistence; lifecycle projection and owner attention delivery stay in adapters.
+ */
+import type { StateReadDiagnostic } from "./state-readers.ts";
+export interface TraceEvent {
+    id: string;
+    ts: string;
+    kind: string;
+    summary?: string;
+    data?: unknown;
+    level?: "info" | "warning" | "error";
+    attention?: "notify" | "followup";
+}
+export interface AppendTraceEventInput {
+    kind: string;
+    summary?: string;
+    data?: unknown;
+    level?: TraceEvent["level"];
+    attention?: TraceEvent["attention"];
+}
+export interface RunTraceReadEvent {
+    event: TraceEvent;
+    ordinal: number;
+}
+export interface RunTraceJournalRead {
+    diagnostics: StateReadDiagnostic[];
+    events: RunTraceReadEvent[];
+    fileBytes: number;
+    omittedPrefixBytes: number;
+    readBytes: number;
+}
+export interface RunTraceSummary {
+    compacted: boolean;
+    compactions_total: number;
+    dropped_bytes: number;
+    dropped_event_count_exact: boolean;
+    dropped_events: number;
+    history_complete: boolean;
+    retained_bytes: number;
+    retained_events: number;
+}
+export declare function runTraceFile(stateDir: string): string;
+export declare function appendRunTraceEvent(stateDir: string, input: AppendTraceEventInput): TraceEvent;
+export declare function readRunTraceJournal(stateDir: string): RunTraceJournalRead;
+export declare function summarizeRunTraceJournal(read: RunTraceJournalRead): RunTraceSummary;
+export declare function readRunTraceEvents(stateDir: string, limit?: number): TraceEvent[];