@llblab/pi-actors 0.42.3 → 0.43.0

package/dist/lib/async-runs.js

@@ -4,7 +4,7 @@
  */
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { closeSync, existsSync, mkdirSync, openSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, statSync, } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { writeJsonAtomic } from "./file-state.js";
@@ -15,16 +15,16 @@ import * as RecipesUsage from "./recipes-usage.js";
 import { resolveArtifactPaths, } from "./runs-artifacts.js";
 import { safeRunId } from "./runs-identity.js";
 import { buildTerminalProgress, markTerminalHandled, signalOwnedRunProcess, } from "./runs-control.js";
-import { buildRunOutboxEventPayload, parseRunOutboxEventLine, } from "./runs-outbox.js";
 import { claimRunStateDirectory } from "./runs-ownership.js";
-import { archiveTerminalRun, pruneTerminalRun } from "./runs-retention.js";
+import { appendRunRetentionEvidence, archiveTerminalRun, pruneTerminalRun, } from "./runs-retention.js";
 import { captureRunProcessIdentity, verifyRunProcessIdentity, } from "./runs-process.js";
 import * as RunsStart from "./runs-start.js";
+import { appendRunTraceEvent } from "./runs-trace.js";
 import * as RunsIndex from "./runs-index.js";
 import * as RunsParentTeardown from "./runs-parent-teardown.js";
-import { claimRunInboxMessageInStateDir, parseRunInboxLine, processRunInboxMessagesInStateDir, runInboxFile, updateRunInboxMessageStatusInStateDir, } from "./runs-mailbox.js";
-import { deliverRunMessage, } from "./runs-messages.js";
-import { buildRunStatus, tailFile, tailLines, } from "./runs-status.js";
+import { appendRunControlInStateDir, updateRunControlStatusInStateDir, } from "./runs-controls.js";
+import { deliverRunControl, } from "./runs-control-delivery.js";
+import { buildRunStatus, tailFile, } from "./runs-status.js";
 import { readJsonFileResilient } from "./state-readers.js";
 const RUNNER_IDENTITY_GRACE_MS = 5000;
 export function normalizeRunTransportContext(value) {
@@ -238,11 +238,9 @@ export function startRun(params, cwd) {
     const stateDir = resolveStateDir(startParams, run);
     const values = {
         ...(startParams.values || {}),
-        actor_address: `run:${run}`,
-        communication_file: join(stateDir, "communication.json"),
-        default_room: `room:${run}`,
         run_id: run,
         state_dir: stateDir,
+        trace_file: join(stateDir, "trace.jsonl"),
     };
     const modelPolicy = describeCurrentPolicyProvenance({
         defaults: startParams.defaults,
@@ -300,6 +298,7 @@ export function startRun(params, cwd) {
             run,
             run_instance_id: randomUUID(),
             state_dir: stateDir,
+            state_schema: "run-kernel-v1",
             status: "running",
             ...(startParams.tool ? { tool: startParams.tool } : {}),
             template: resolved.template,
@@ -307,7 +306,9 @@ export function startRun(params, cwd) {
             model_policy: modelPolicy,
             ...(artifacts ? { artifacts } : {}),
             ...(startParams.control ? { control: startParams.control } : {}),
-            ...(startParams.mailbox ? { mailbox: startParams.mailbox } : {}),
+            ...(startParams.control_endpoint
+                ? { control_endpoint: startParams.control_endpoint }
+                : {}),
             ...(startParams.notification_policy === "silent"
                 ? { notification_policy: "silent" }
                 : {}),
@@ -340,7 +341,14 @@ export function startRun(params, cwd) {
         if (processIdentity)
             meta.process_identity = processIdentity;
         writeJsonAtomic(join(stateDir, "run.json"), meta);
-        writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ event: "run.start", run, run_instance_id: meta.run_instance_id, pid: meta.pid, ts: new Date().toISOString() })}\n`, { flag: "a" });
+        appendRunTraceEvent(stateDir, {
+            kind: "run.start",
+            summary: `Run ${run} started`,
+            data: {
+                pid: meta.pid,
+                run_instance_id: meta.run_instance_id,
+            },
+        });
         child.unref();
         return meta;
     }
@@ -348,7 +356,6 @@ export function startRun(params, cwd) {
         releaseStartLock();
     }
 }
-export { parseRunOutboxEventLine } from "./runs-outbox.js";
 function resolveRunStateDir(runOrDir) {
     return resolve(/[\\/]/u.test(runOrDir)
         ? runOrDir
@@ -403,17 +410,19 @@ export function teardownRunsOwnedByParent(ownerId, stateRoot = DEFAULT_STATE_ROO
                 current.run_instance_id !== attempt.runInstanceId) {
                 throw new Error("run generation changed before teardown evidence");
             }
-            writeFileSync(join(attempt.stateDir, "events.jsonl"), `${JSON.stringify({
-                event: "run.parent_teardown",
-                ownerId: attempt.ownerId,
-                outcome: attempt.outcome,
-                reason: attempt.reason,
-                run: attempt.run,
-                run_instance_id: attempt.runInstanceId,
-                type: "control.kill",
-                trigger: options.trigger ?? "parent_shutdown",
-                ts: new Date().toISOString(),
-            })}\n`, { flag: "a" });
+            appendRunTraceEvent(attempt.stateDir, {
+                kind: "run.parent_teardown",
+                summary: `Parent teardown ${attempt.outcome}`,
+                data: {
+                    outcome: attempt.outcome,
+                    owner_id: attempt.ownerId,
+                    reason: attempt.reason,
+                    run: attempt.run,
+                    run_instance_id: attempt.runInstanceId,
+                    trigger: options.trigger ?? "parent_shutdown",
+                },
+                ...(attempt.outcome === "failed" ? { level: "error" } : {}),
+            });
         },
     });
     const summaryPath = join(stateRoot, "teardown", `${Date.now()}-${randomUUID()}.json`);
@@ -437,73 +446,43 @@ export function teardownRunsOwnedByParent(ownerId, stateRoot = DEFAULT_STATE_ROO
 export function tailRun(runOrDir, lines = 40) {
     const status = getRunStatus(runOrDir);
     const stateDir = String(status.state_dir);
-    const events = tailFile(join(stateDir, "events.jsonl"), lines);
-    if (events)
-        return events;
+    const trace = tailFile(join(stateDir, "trace.jsonl"), lines);
+    if (trace)
+        return trace;
     return (tailFile(join(stateDir, "stdout.log"), lines) ||
         tailFile(join(stateDir, "stderr.log"), lines));
 }
-export function readRunEvents(runOrDir, lines = 40) {
-    const status = getRunStatus(runOrDir);
-    const stateDir = String(status.state_dir);
-    const run = String(status.run ?? runOrDir);
-    return tailLines(join(stateDir, "outbox.jsonl"), lines)
-        .map((line, index) => parseRunOutboxEventLine(line, run, stateDir, index))
-        .filter((event) => Boolean(event));
-}
-export function readRunInboxMessages(runOrDir, lines = 40) {
-    const status = getRunStatus(runOrDir);
-    const stateDir = String(status.state_dir);
-    return tailLines(runInboxFile(stateDir), lines)
-        .map(parseRunInboxLine)
-        .filter((message) => Boolean(message));
-}
-export function updateRunInboxMessageStatus(runOrDir, id, nextStatus, metadata = {}) {
-    const status = getRunStatus(runOrDir);
-    const stateDir = String(status.state_dir);
-    return updateRunInboxMessageStatusInStateDir(stateDir, id, nextStatus, metadata);
-}
-export function claimRunInboxMessage(runOrDir, owner = "runtime", statuses = ["queued"]) {
-    const status = getRunStatus(runOrDir);
-    const stateDir = String(status.state_dir);
-    return claimRunInboxMessageInStateDir(stateDir, owner, statuses);
-}
-export async function processRunInboxMessages(runOrDir, handler, options = {}) {
-    const status = getRunStatus(runOrDir);
-    return processRunInboxMessagesInStateDir(String(status.state_dir), handler, options);
-}
-export function appendRunOutboxEvent(runOrDir, event) {
-    const status = getRunStatus(runOrDir);
-    const stateDir = String(status.state_dir);
-    const run = String(status.run ?? runOrDir);
-    const payload = buildRunOutboxEventPayload(run, event);
-    const line = `${JSON.stringify(payload)}\n`;
-    writeFileSync(join(stateDir, "outbox.jsonl"), line, { flag: "a" });
-    return {
-        bytes: Buffer.byteLength(line),
-        outbox: "outbox.jsonl",
-        run,
-        sent: true,
-        state_dir: stateDir,
-    };
-}
-export async function sendRunMessage(runOrDir, message, options = {}) {
-    const status = getRunStatus(runOrDir);
-    const stateDir = String(status.state_dir);
-    const run = String(status.run ?? runOrDir);
-    const pid = Number(status.pid || 0);
-    const identity = verifyRunProcessIdentity(pid, status.process_identity);
-    if (status.status !== "running") {
-        if (identity.status === "owner_mismatch" ||
-            identity.status === "unsupported_proof") {
-            throw new Error(`Run process identity ${identity.status}: ${run}`);
+export async function sendRunControl(runOrDir, request, options = {}) {
+    const stateDir = resolveRunStateDir(runOrDir);
+    const releaseControlLock = RunsStart.acquireStateStartLock(stateDir);
+    try {
+        const status = getRunStatus(stateDir);
+        const run = String(status.run ?? runOrDir);
+        if (options.ownerId !== undefined && status.ownerId !== options.ownerId) {
+            throw Object.assign(new Error(`Run ownership changed: ${run}`), {
+                reason: "owner_mismatch",
+            });
+        }
+        if (status.run_instance_id !== request.run_instance_id) {
+            throw Object.assign(new Error(`Run generation changed: ${run}`), {
+                reason: "generation_mismatch",
+            });
         }
-        throw new Error(`Run is not running: ${run}`);
+        if (status.status !== "running") {
+            throw Object.assign(new Error(`Run is not running: ${run}`), {
+                reason: "terminal_state",
+            });
+        }
+        const pid = Number(status.pid || 0);
+        const identity = verifyRunProcessIdentity(pid, status.process_identity);
+        if (!identity.valid) {
+            throw Object.assign(new Error(`Run process identity ${identity.status}: ${run}`), { reason: `process_identity_${identity.status}` });
+        }
+        return await deliverRunControl(run, stateDir, request, options);
     }
-    if (!identity.valid) {
-        throw new Error(`Run process identity ${identity.status}: ${run}`);
+    finally {
+        releaseControlLock();
     }
-    return deliverRunMessage(status, run, stateDir, message, options);
 }
 export { getRunProcessSignalPlan } from "./runs-control.js";
 function markTerminalProgress(stateDir, phase) {
@@ -513,9 +492,9 @@ function markTerminalProgress(stateDir, phase) {
         : undefined;
     writeJsonAtomic(join(stateDir, "progress.json"), buildTerminalProgress(progress, phase));
 }
-function finalizeInterruptedReviewEvidence(stateDir, phase, signal) {
-    const evidencePath = join(stateDir, "review-evidence.json");
-    const manifest = readJson(evidencePath);
+function finalizeInterruptedExecution(stateDir, phase, signal) {
+    const executionPath = join(stateDir, "execution.json");
+    const manifest = readJson(executionPath);
     if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
         return;
     const record = manifest;
@@ -564,7 +543,7 @@ function finalizeInterruptedReviewEvidence(stateDir, phase, signal) {
                 : {}),
         };
     });
-    writeJsonAtomic(evidencePath, {
+    writeJsonAtomic(executionPath, {
         ...record,
         status: phase,
         commands,
@@ -585,43 +564,80 @@ function stopRun(runOrDir, signal, event, expected = {}) {
             status.run_instance_id !== expected.runInstanceId) {
             return { stopped: false, reason: "run generation changed", status };
         }
+        const control = event === "run.kill" && typeof status.run_instance_id === "string"
+            ? appendRunControlInStateDir(stateDir, {
+                action: "kill",
+                run_instance_id: status.run_instance_id,
+            })
+            : undefined;
+        if (control) {
+            updateRunControlStatusInStateDir(stateDir, control.id, "claimed", {}, ["queued"]);
+        }
+        const finish = (result) => {
+            if (!control)
+                return result;
+            const handled = result.stopped === true;
+            updateRunControlStatusInStateDir(stateDir, control.id, handled ? "handled" : "failed", handled ? {} : { error: String(result.reason ?? "kill rejected") }, ["claimed"]);
+            return { ...result, control_id: control.id };
+        };
         const pid = Number(status.pid || 0);
         if (status.status !== "running" && status.status !== "exited") {
-            return { stopped: false, reason: "not running", status };
+            return finish({ stopped: false, reason: "not running", status });
         }
         const identity = verifyRunProcessIdentity(pid, status.process_identity);
         if (status.status === "exited") {
             if (identity.status === "owner_mismatch" ||
                 identity.status === "unsupported_proof") {
-                return {
+                return finish({
                     stopped: false,
                     reason: identity.status.replaceAll("_", " "),
                     process_identity_status: identity.status,
                     status,
-                };
+                });
             }
-            return { stopped: false, reason: "not running", status };
+            return finish({ stopped: false, reason: "not running", status });
         }
         if (!identity.valid) {
-            return {
+            return finish({
                 stopped: false,
                 reason: identity.status.replaceAll("_", " "),
                 process_identity_status: identity.status,
                 status,
-            };
+            });
+        }
+        let signalResult;
+        try {
+            signalResult = signalOwnedRunProcess(pid, signal, status.process_identity);
+        }
+        catch (error) {
+            if (control) {
+                updateRunControlStatusInStateDir(stateDir, control.id, "failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            throw error;
         }
-        const signalResult = signalOwnedRunProcess(pid, signal, status.process_identity);
-        writeFileSync(join(stateDir, "events.jsonl"), `${JSON.stringify({ event, pid, signal, ...signalResult, ts: new Date().toISOString() })}\n`, { flag: "a" });
+        appendRunTraceEvent(stateDir, {
+            kind: event,
+            summary: `${event === "run.kill" ? "Killed" : "Cancelled"} Run process`,
+            data: { pid, signal, ...signalResult },
+        });
         markTerminalHandled(stateDir, { event, signal });
         if (event === "run.kill") {
-            finalizeInterruptedReviewEvidence(stateDir, "killed", signal);
+            finalizeInterruptedExecution(stateDir, "killed", signal);
             markTerminalProgress(stateDir, "killed");
         }
         if (event === "run.cancel") {
-            finalizeInterruptedReviewEvidence(stateDir, "cancelled", signal);
+            finalizeInterruptedExecution(stateDir, "cancelled", signal);
             markTerminalProgress(stateDir, "cancelled");
         }
-        return { stopped: true, pid, signal, ...signalResult, state_dir: stateDir };
+        return finish({
+            stopped: true,
+            pid,
+            signal,
+            ...signalResult,
+            state_dir: stateDir,
+        });
     }
     finally {
         releaseControlLock();
@@ -653,18 +669,52 @@ export function cancelRun(runOrDir, expected = {}) {
         ? { cancelled: result.stopped, ...result }
         : result;
 }
-function assertTerminalRun(runOrDir) {
-    const status = getRunStatus(runOrDir);
-    if (status.status === "running") {
-        throw new Error("Only terminal runs can be archived or pruned.");
+function retainRun(runOrDir, action, expected, options = {}) {
+    const stateDir = resolveRunStateDir(runOrDir);
+    const releaseControlLock = RunsStart.acquireStateStartLock(stateDir);
+    let status;
+    let evidenceId;
+    try {
+        expected.onLocked?.();
+        status = getRunStatus(stateDir);
+        if (expected.ownerId !== undefined && status.ownerId !== expected.ownerId) {
+            return { [`${action}d`]: false, reason: "ownership changed", status };
+        }
+        if (expected.runInstanceId !== undefined &&
+            status.run_instance_id !== expected.runInstanceId) {
+            return { [`${action}d`]: false, reason: "run generation changed", status };
+        }
+        if (status.status === "running") {
+            throw new Error("Only terminal runs can be archived or pruned.");
+        }
+        evidenceId = appendRunRetentionEvidence(status, action, "queued");
+        const result = action === "archive"
+            ? archiveTerminalRun(status)
+            : pruneTerminalRun(status, options);
+        appendRunRetentionEvidence(status, action, "handled", {
+            id: evidenceId,
+            result,
+        });
+        return { ...result, retention_id: evidenceId };
+    }
+    catch (error) {
+        if (status && evidenceId) {
+            appendRunRetentionEvidence(status, action, "failed", {
+                error: error instanceof Error ? error.message : String(error),
+                id: evidenceId,
+            });
+        }
+        throw error;
+    }
+    finally {
+        releaseControlLock();
     }
-    return status;
 }
-export function archiveRun(runOrDir) {
-    return archiveTerminalRun(assertTerminalRun(runOrDir));
+export function archiveRun(runOrDir, expected = {}) {
+    return retainRun(runOrDir, "archive", expected);
 }
-export function pruneRun(runOrDir, options = {}) {
-    return pruneTerminalRun(assertTerminalRun(runOrDir), options);
+export function pruneRun(runOrDir, options = {}, expected = {}) {
+    return retainRun(runOrDir, "prune", expected, options);
 }
 export function killRun(runOrDir, expected = {}) {
     const result = stopRun(runOrDir, "SIGKILL", "run.kill", expected);

package/dist/lib/control.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Run Control request contract.
+ * Zones: public request validation, Run/runtime target normalization, input bounds
+ * Owns pure Control validation; journaling, delivery, and lifecycle mutation stay in adapters.
+ */
+export interface ControlRequest {
+    target: `run:${string}` | "runtime";
+    action: string;
+    input?: unknown;
+    verbose?: boolean;
+}
+export declare function normalizeControlRequest(input: unknown): ControlRequest;

package/dist/lib/control.js

@@ -0,0 +1,84 @@
+/**
+ * Run Control request contract.
+ * Zones: public request validation, Run/runtime target normalization, input bounds
+ * Owns pure Control validation; journaling, delivery, and lifecycle mutation stay in adapters.
+ */
+import * as Limits from "./limits.js";
+const RUN_ID_PATTERN = /^[A-Za-z0-9_.-]+$/;
+const ACTION_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+)*$/;
+const CONTROL_FIELDS = new Set(["action", "input", "target", "verbose"]);
+const REMOVED_FIELDS = new Set([
+    "body",
+    "correlation_id",
+    "from",
+    "metadata",
+    "reply_to",
+    "summary",
+    "to",
+    "type",
+]);
+function serializedInputBytes(input) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(input);
+    }
+    catch {
+        throw new Error("control.input must be JSON-serializable");
+    }
+    if (serialized === undefined) {
+        throw new Error("control.input must be JSON-serializable");
+    }
+    return Buffer.byteLength(serialized);
+}
+function normalizeTarget(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error("control.target is required");
+    }
+    const target = value.trim();
+    if (target === "runtime")
+        return target;
+    if (!target.startsWith("run:")) {
+        throw new Error(`unsupported control target: ${target}; use run:<id> or runtime`);
+    }
+    const run = target.slice(4);
+    if (!RUN_ID_PATTERN.test(run)) {
+        throw new Error(`invalid control Run target: ${target}`);
+    }
+    return `run:${run}`;
+}
+export function normalizeControlRequest(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("control request must be an object");
+    }
+    const record = input;
+    const fields = Object.keys(record);
+    const removed = fields.filter((field) => REMOVED_FIELDS.has(field));
+    if (removed.length > 0) {
+        throw new Error(`actor-message fields are removed: ${removed.sort().join(", ")}; use target, action, input, verbose`);
+    }
+    const unknown = fields.filter((field) => !CONTROL_FIELDS.has(field));
+    if (unknown.length > 0) {
+        throw new Error(`unsupported control fields: ${unknown.sort().join(", ")}`);
+    }
+    const target = normalizeTarget(record.target);
+    if (typeof record.action !== "string" || !record.action.trim()) {
+        throw new Error("control.action is required");
+    }
+    const action = record.action.trim();
+    if (!ACTION_PATTERN.test(action)) {
+        throw new Error(`invalid control action: ${action}`);
+    }
+    if (record.verbose !== undefined && typeof record.verbose !== "boolean") {
+        throw new Error("control.verbose must be a boolean");
+    }
+    if (record.input !== undefined &&
+        serializedInputBytes(record.input) > Limits.CONTROL_INPUT_MAX_BYTES) {
+        throw new Error(`control.input exceeds ${Limits.CONTROL_INPUT_MAX_BYTES} bytes`);
+    }
+    return {
+        target,
+        action,
+        ...(record.input !== undefined ? { input: record.input } : {}),
+        ...(record.verbose !== undefined ? { verbose: record.verbose } : {}),
+    };
+}

package/dist/lib/execution-sessions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Run-owned execution session evidence.
+ * Zones: execution manifest session discovery, canonical containment, rich turn correlation
+ * Owns reusable agent-turn loading; Trace and TUI projection stay in their adapters.
+ */
+import * as SessionEvidence from "./session-evidence.ts";
+export interface ExecutionTurnItem extends SessionEvidence.SessionEvidenceTurn {
+    commandId: string;
+    diagnostics: string[];
+    promptBytes?: number;
+    promptFile?: string;
+    recipeContext?: unknown;
+    sessionFile: string;
+    sessionTruncated: boolean;
+    stage?: string;
+}
+export declare function readExecutionTurns(stateDir: string): ExecutionTurnItem[];

package/dist/lib/execution-sessions.js

@@ -0,0 +1,85 @@
+/**
+ * Run-owned execution session evidence.
+ * Zones: execution manifest session discovery, canonical containment, rich turn correlation
+ * Owns reusable agent-turn loading; Trace and TUI projection stay in their adapters.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as SessionEvidence from "./session-evidence.js";
+import { readJsonFileResilient } from "./state-readers.js";
+function ownedSessionPath(stateDir, sessionFile) {
+    if (path.isAbsolute(sessionFile))
+        return undefined;
+    const sessionsRoot = path.resolve(stateDir, "sessions");
+    const resolved = path.resolve(stateDir, sessionFile);
+    if (!resolved.startsWith(`${sessionsRoot}${path.sep}`))
+        return undefined;
+    try {
+        const canonicalRoot = fs.realpathSync(sessionsRoot);
+        const canonicalFile = fs.realpathSync(resolved);
+        return canonicalFile.startsWith(`${canonicalRoot}${path.sep}`)
+            ? canonicalFile
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readExecutionTurns(stateDir) {
+    const execution = readJsonFileResilient(path.join(stateDir, "execution.json"), {}).value;
+    const commands = Array.isArray(execution.commands)
+        ? execution.commands
+        : [];
+    const recordedFiles = new Set(commands.flatMap((command) => (Array.isArray(command.session_files) ? command.session_files : []).filter((file) => typeof file === "string")));
+    let discoveredCommands = [];
+    try {
+        const sessionsDir = path.join(stateDir, "sessions");
+        discoveredCommands = fs
+            .readdirSync(sessionsDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .flatMap((entry) => {
+            const files = fs
+                .readdirSync(path.join(sessionsDir, entry.name), {
+                withFileTypes: true,
+            })
+                .filter((file) => file.isFile() && file.name.endsWith(".jsonl"))
+                .map((file) => path.posix.join("sessions", entry.name, file.name))
+                .filter((file) => !recordedFiles.has(file));
+            return files.length > 0
+                ? [{ id: entry.name, session_files: files, stage: "subagent" }]
+                : [];
+        });
+    }
+    catch {
+        discoveredCommands = [];
+    }
+    return [...commands, ...discoveredCommands]
+        .flatMap((command) => (Array.isArray(command.session_files) ? command.session_files : [])
+        .filter((file) => typeof file === "string")
+        .flatMap((file) => {
+        const sessionPath = ownedSessionPath(stateDir, file);
+        if (!sessionPath)
+            return [];
+        const session = SessionEvidence.readSessionEvidence(sessionPath);
+        return session.turns.map((turn) => ({
+            ...turn,
+            commandId: String(command.id ?? "unknown"),
+            diagnostics: session.diagnostics.map((item) => `${item.line === undefined ? "" : `line ${item.line}: `}${item.message}`),
+            ...(typeof command.prompt_bytes === "number"
+                ? { promptBytes: command.prompt_bytes }
+                : {}),
+            ...(typeof command.prompt_file === "string"
+                ? { promptFile: command.prompt_file }
+                : {}),
+            ...(command.recipe_context !== undefined
+                ? { recipeContext: command.recipe_context }
+                : {}),
+            sessionFile: file,
+            sessionTruncated: session.truncated,
+            ...(typeof command.stage === "string"
+                ? { stage: command.stage }
+                : {}),
+        }));
+    }))
+        .map((turn, index) => ({ ...turn, index: index + 1 }));
+}

package/dist/lib/file-state.d.ts

@@ -11,4 +11,5 @@ export interface FileMutationLockOptions {
 }
 export declare function acquireFileMutationLock(path: string, options?: FileMutationLockOptions): () => void;
 export declare function withFileMutationLock<T>(path: string, mutate: () => T, options?: FileMutationLockOptions): T;
+export declare function writeTextAtomic(path: string, content: string): void;
 export declare function writeJsonAtomic(path: string, value: unknown): void;

package/dist/lib/file-state.js

@@ -4,7 +4,7 @@
  * Owns generic durable JSON file writes shared by registry config and async run state.
  */
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, parse, resolve } from "node:path";
 const FILE_MUTATION_LOCK_TIMEOUT_MS = 5000;
@@ -12,8 +12,17 @@ const FILE_MUTATION_LOCK_STALE_MS = 30000;
 const FILE_MUTATION_LOCK_ROOT = join(tmpdir(), "pi-actors-file-locks");
 function canonicalMutationPath(path) {
     const absolute = resolve(path);
-    const suffix = [];
-    let existing = absolute;
+    try {
+        if (lstatSync(absolute).isSymbolicLink()) {
+            const target = realpathSync.native(absolute);
+            return process.platform === "win32" ? target.toLowerCase() : target;
+        }
+    }
+    catch {
+        /* Materialization may race lock-key derivation; canonicalize through the parent. */
+    }
+    const suffix = [basename(absolute)];
+    let existing = dirname(absolute);
     while (!existsSync(existing)) {
         const parent = dirname(existing);
         if (parent === existing || existing === parse(existing).root)
@@ -191,11 +200,11 @@ export function withFileMutationLock(path, mutate, options = {}) {
         release();
     }
 }
-export function writeJsonAtomic(path, value) {
+export function writeTextAtomic(path, content) {
     mkdirSync(dirname(path), { recursive: true });
     const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
     try {
-        writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        writeFileSync(tempPath, content, "utf8");
         renameSync(tempPath, path);
     }
     catch (error) {
@@ -208,3 +217,6 @@ export function writeJsonAtomic(path, value) {
         throw error;
     }
 }
+export function writeJsonAtomic(path, value) {
+    writeTextAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
+}

package/dist/lib/inspector-actions.d.ts

@@ -1,5 +1,5 @@
 /**
- * Actor Inspector run actions.
+ * Actor Inspector actions for concrete Run instances.
  * Owns: exact-session run-action authorization, canonical kill routing, and bounded operator feedback.
  */
 export interface ActorInspectorKillResult {
@@ -13,4 +13,4 @@ export interface ActorInspectorKillDeps {
         runInstanceId: string;
     }) => Record<string, unknown>;
 }
-export declare function killOwnedInspectorRun(ownerId: string, run: string, stateRoot: string, expectedRunInstanceId: string, deps: ActorInspectorKillDeps): ActorInspectorKillResult;
+export declare function killOwnedRunFromInspector(ownerId: string, run: string, stateRoot: string, expectedRunInstanceId: string, deps: ActorInspectorKillDeps): ActorInspectorKillResult;