@llblab/pi-actors 0.42.3 → 0.43.1

package/dist/lib/control-projection.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Model-facing Run Control projection.
+ * Zones: structured redaction, bounded Control input/error, decision-useful evidence
+ * Owns safe Control reads; durable journals and lifecycle transitions remain in runs-controls.
+ */
+import type { RunControlRecord, RunControlStatus } from "./runs-controls.ts";
+export interface ProjectedRunControl {
+    action: string;
+    claimed_at?: string;
+    delivered_at?: string;
+    error?: string;
+    failed_at?: string;
+    handled_at?: string;
+    id: string;
+    input?: unknown;
+    queued_at: string;
+    run_instance_id: string;
+    status: RunControlStatus;
+}
+export declare function projectRunControl(control: RunControlRecord): ProjectedRunControl;

package/dist/lib/control-projection.js

@@ -0,0 +1,66 @@
+/**
+ * Model-facing Run Control projection.
+ * Zones: structured redaction, bounded Control input/error, decision-useful evidence
+ * Owns safe Control reads; durable journals and lifecycle transitions remain in runs-controls.
+ */
+import * as Limits from "./limits.js";
+import * as SessionEvidence from "./session-evidence.js";
+const OPTIONAL_TIMESTAMP_FIELDS = [
+    "claimed_at",
+    "delivered_at",
+    "failed_at",
+    "handled_at",
+];
+function boundedRedactedString(value, maxChars) {
+    const redacted = SessionEvidence.redactSessionEvidenceValue(value, maxChars);
+    return typeof redacted === "string"
+        ? redacted
+        : String(redacted).slice(0, maxChars);
+}
+function boundedRedactedValue(value) {
+    const redacted = SessionEvidence.redactSessionEvidenceValue(value, Limits.INSPECTOR_BODY_PREVIEW_CHARS);
+    let serialized;
+    try {
+        serialized = JSON.stringify(redacted);
+    }
+    catch {
+        return "[UNSERIALIZABLE]";
+    }
+    if (serialized === undefined)
+        return "[UNSERIALIZABLE]";
+    if (serialized.length <= Limits.INSPECTOR_BODY_PREVIEW_CHARS)
+        return redacted;
+    let preview = serialized.slice(0, Limits.INSPECTOR_BODY_PREVIEW_CHARS);
+    let bounded = { preview: `${preview}…`, truncated: true };
+    while (preview &&
+        JSON.stringify(bounded).length > Limits.INSPECTOR_BODY_PREVIEW_CHARS) {
+        const excess = JSON.stringify(bounded).length - Limits.INSPECTOR_BODY_PREVIEW_CHARS;
+        preview = preview.slice(0, Math.max(0, preview.length - Math.max(1, excess)));
+        bounded = { preview: `${preview}…`, truncated: true };
+    }
+    return bounded;
+}
+export function projectRunControl(control) {
+    const timestamps = Object.fromEntries(OPTIONAL_TIMESTAMP_FIELDS.flatMap((field) => {
+        const value = control[field];
+        return typeof value === "string"
+            ? [[field, boundedRedactedString(value, Limits.COMPACT_PREVIEW_CHARS)]]
+            : [];
+    }));
+    return {
+        action: boundedRedactedString(control.action, Limits.COMPACT_PREVIEW_CHARS),
+        ...timestamps,
+        ...(typeof control.error === "string"
+            ? {
+                error: boundedRedactedString(control.error, Limits.INSPECTOR_BODY_PREVIEW_CHARS),
+            }
+            : {}),
+        id: boundedRedactedString(control.id, Limits.COMPACT_PREVIEW_CHARS),
+        ...(control.input !== undefined
+            ? { input: boundedRedactedValue(control.input) }
+            : {}),
+        queued_at: boundedRedactedString(control.queued_at, Limits.COMPACT_PREVIEW_CHARS),
+        run_instance_id: boundedRedactedString(control.run_instance_id, Limits.COMPACT_PREVIEW_CHARS),
+        status: boundedRedactedString(control.status, Limits.COMPACT_PREVIEW_CHARS),
+    };
+}

package/dist/lib/control.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 isControlAction(value: string): boolean;
+export declare function normalizeControlAction(value: unknown): string;
+export declare function normalizeControlInput(input: unknown): unknown;
+export declare function normalizeControlRequest(input: unknown): ControlRequest;

package/dist/lib/control.js

@@ -0,0 +1,97 @@
+/**
+ * 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",
+]);
+export function isControlAction(value) {
+    return ACTION_PATTERN.test(value);
+}
+export function normalizeControlAction(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error("control.action is required");
+    }
+    const action = value.trim();
+    if (!isControlAction(action)) {
+        throw new Error(`invalid control action: ${action}`);
+    }
+    if (action.length > Limits.CONTROL_ACTION_MAX_LENGTH) {
+        throw new Error(`control.action exceeds ${Limits.CONTROL_ACTION_MAX_LENGTH} ASCII characters`);
+    }
+    return action;
+}
+export function normalizeControlInput(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");
+    }
+    const bytes = Buffer.byteLength(serialized);
+    if (bytes > Limits.CONTROL_INPUT_MAX_BYTES) {
+        throw new Error(`control.input exceeds ${Limits.CONTROL_INPUT_MAX_BYTES} serialized bytes`);
+    }
+    return JSON.parse(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);
+    const action = normalizeControlAction(record.action);
+    if (record.verbose !== undefined && typeof record.verbose !== "boolean") {
+        throw new Error("control.verbose must be a boolean");
+    }
+    const normalizedInput = record.input === undefined
+        ? undefined
+        : normalizeControlInput(record.input);
+    return {
+        target,
+        action,
+        ...(normalizedInput !== undefined ? { input: normalizedInput } : {}),
+        ...(record.verbose !== undefined ? { verbose: record.verbose } : {}),
+    };
+}

package/dist/lib/draft-sleep.js

@@ -391,7 +391,7 @@ export function createDraftSleepScheduler(deps) {
                                 ...existing,
                                 failedStage: processed.stage ?? "result_processing",
                                 lastError: processed.error ?? "automatic draft review processing failed",
-                                nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"draft\"}",
+                                nextAction: "message target=runtime action=review.retry input={\"scope\":\"draft\"}",
                                 phase: "processing_failed",
                                 processingAttempts: (existing.processingAttempts ?? 0) + 1,
                                 updatedAt: now().toISOString(),
@@ -402,7 +402,7 @@ export function createDraftSleepScheduler(deps) {
                             ...existing,
                             failedStage: processed.stage ?? "review_result",
                             lastError: processed.error ?? "automatic draft reviewer failed",
-                            nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"draft\"}",
+                            nextAction: "message target=runtime action=review.retry input={\"scope\":\"draft\"}",
                             phase: "failed",
                             runId: undefined,
                             updatedAt: now().toISOString(),
@@ -444,7 +444,7 @@ export function createDraftSleepScheduler(deps) {
                             attempts: (prior?.batchId === batch.batchId ? prior.attempts : 0) + 1,
                             failedStage: "review_launch",
                             lastError: error instanceof Error ? error.message : String(error),
-                            nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"draft\"}",
+                            nextAction: "message target=runtime action=review.retry input={\"scope\":\"draft\"}",
                             batchId: batch.batchId,
                             inputPath: batch.inputPath,
                             phase: "failed",

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

@@ -5,10 +5,12 @@
  */
 export declare function mutationLockPath(path: string): string;
 export interface FileMutationLockOptions {
+    onBeforeLockPublish?(): void;
     onBeforeReclaimRemove?(): void;
     onContention?(): void;
     onRemovalContention?(): void;
 }
 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

@@ -3,17 +3,27 @@
  * Zones: file persistence, atomic writes, runtime state support
  * Owns generic durable JSON file writes shared by registry config and async run state.
  */
+import { spawnSync } from "node:child_process";
 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;
+const FILE_MUTATION_LOCK_TIMEOUT_MS = process.platform === "win32" ? 15000 : 5000;
 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)
@@ -33,6 +43,20 @@ export function mutationLockPath(path) {
         .digest("hex");
     return join(FILE_MUTATION_LOCK_ROOT, `${key}.lock`);
 }
+function isZombieProcess(pid) {
+    if (process.platform === "linux")
+        try {
+            const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+            return stat.slice(stat.lastIndexOf(")") + 2).startsWith("Z ");
+        }
+        catch {
+            return false;
+        }
+    if (process.platform !== "darwin")
+        return false;
+    const result = spawnSync("ps", ["-p", String(pid), "-o", "stat="], { encoding: "utf8" });
+    return result.status === 0 && result.stdout.trim().startsWith("Z");
+}
 function lockOwnerStatus(lockPath) {
     try {
         const owner = JSON.parse(readFileSync(join(lockPath, "owner.json"), "utf8"));
@@ -41,6 +65,8 @@ function lockOwnerStatus(lockPath) {
             return "unknown";
         try {
             process.kill(pid, 0);
+            if (Date.now() - statSync(lockPath).mtimeMs > 50 && isZombieProcess(pid))
+                return "dead";
             return "alive";
         }
         catch (error) {
@@ -62,6 +88,46 @@ function readLockToken(lockPath) {
         return undefined;
     }
 }
+function prepareLockBoundary(lockPath, token, onBeforePublish) {
+    const pendingPath = `${lockPath}.${process.pid}.${token}.pending`;
+    try {
+        mkdirSync(pendingPath);
+        writeFileSync(join(pendingPath, "owner.json"), `${JSON.stringify({ pid: process.pid, token, acquired_at: new Date().toISOString() })}\n`, "utf8");
+        onBeforePublish?.();
+        return pendingPath;
+    }
+    catch (error) {
+        try {
+            rmSync(pendingPath, { recursive: true, force: true });
+        }
+        catch { }
+        throw error;
+    }
+}
+function removeLockBoundary(lockPath, token) {
+    if (readLockToken(lockPath) !== token)
+        return false;
+    if (process.platform === "win32")
+        try {
+            rmSync(lockPath, { recursive: true, force: true, maxRetries: 20, retryDelay: 5 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    const removingPath = `${lockPath}.${process.pid}.${randomUUID()}.removing`;
+    try {
+        renameSync(lockPath, removingPath);
+    }
+    catch {
+        return false;
+    }
+    try {
+        rmSync(removingPath, { recursive: true, force: true });
+    }
+    catch { }
+    return true;
+}
 function tryReclaimRemovalBoundary(reclaimPath) {
     if (!existsSync(reclaimPath))
         return;
@@ -72,7 +138,7 @@ function tryReclaimRemovalBoundary(reclaimPath) {
         if ((ownerStatus === "dead" ||
             (ownerStatus === "unknown" && age > FILE_MUTATION_LOCK_STALE_MS)) &&
             readLockToken(reclaimPath) === inspectedToken) {
-            rmSync(reclaimPath, { recursive: true, force: true });
+            removeLockBoundary(reclaimPath, inspectedToken);
         }
     }
     catch {
@@ -82,28 +148,28 @@ function tryReclaimRemovalBoundary(reclaimPath) {
 function withRemovalBoundary(lockPath, action) {
     const reclaimPath = `${lockPath}.reclaim`;
     const token = randomUUID();
+    const pendingPath = prepareLockBoundary(reclaimPath, token);
     try {
-        mkdirSync(reclaimPath);
         try {
-            writeFileSync(join(reclaimPath, "owner.json"), `${JSON.stringify({ pid: process.pid, token, acquired_at: new Date().toISOString() })}\n`, "utf8");
+            renameSync(pendingPath, reclaimPath);
         }
-        catch (error) {
-            rmSync(reclaimPath, { recursive: true, force: true });
-            throw error;
+        catch {
+            tryReclaimRemovalBoundary(reclaimPath);
+            return false;
+        }
+        try {
+            action();
+            return true;
+        }
+        finally {
+            removeLockBoundary(reclaimPath, token);
         }
-    }
-    catch {
-        tryReclaimRemovalBoundary(reclaimPath);
-        return false;
-    }
-    try {
-        action();
-        return true;
     }
     finally {
-        if (readLockToken(reclaimPath) === token) {
-            rmSync(reclaimPath, { recursive: true, force: true });
+        try {
+            rmSync(pendingPath, { recursive: true, force: true });
         }
+        catch { }
     }
 }
 function tryReclaimMutationLock(lockPath, options) {
@@ -120,8 +186,7 @@ function tryReclaimMutationLock(lockPath, options) {
             (ownerStatus === "unknown" && age > FILE_MUTATION_LOCK_STALE_MS)) &&
             readLockToken(lockPath) === inspectedToken) {
             options.onBeforeReclaimRemove?.();
-            rmSync(lockPath, { recursive: true, force: true });
-            reclaimed = true;
+            reclaimed = removeLockBoundary(lockPath, inspectedToken);
         }
     })) {
         return false;
@@ -133,32 +198,34 @@ export function acquireFileMutationLock(path, options = {}) {
     const lockPath = mutationLockPath(path);
     const deadline = Date.now() + FILE_MUTATION_LOCK_TIMEOUT_MS;
     const token = randomUUID();
+    const pendingPath = prepareLockBoundary(lockPath, token, options.onBeforeLockPublish);
     let contentionReported = false;
-    for (;;) {
-        try {
-            mkdirSync(lockPath);
+    try {
+        for (;;) {
             try {
-                writeFileSync(join(lockPath, "owner.json"), `${JSON.stringify({ pid: process.pid, token, acquired_at: new Date().toISOString() })}\n`, "utf8");
+                renameSync(pendingPath, lockPath);
+                break;
             }
             catch (error) {
-                rmSync(lockPath, { recursive: true, force: true });
-                throw error;
+                if (!contentionReported) {
+                    contentionReported = true;
+                    options.onContention?.();
+                }
+                tryReclaimMutationLock(lockPath, options);
+                if (Date.now() >= deadline) {
+                    throw new Error(`Timed out waiting for file mutation lock: ${canonicalMutationPath(path)}`, {
+                        cause: error,
+                    });
+                }
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
             }
-            break;
         }
-        catch (error) {
-            if (!contentionReported) {
-                contentionReported = true;
-                options.onContention?.();
-            }
-            tryReclaimMutationLock(lockPath, options);
-            if (Date.now() >= deadline) {
-                throw new Error(`Timed out waiting for file mutation lock: ${canonicalMutationPath(path)}`, {
-                    cause: error,
-                });
-            }
-            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+    finally {
+        try {
+            rmSync(pendingPath, { recursive: true, force: true });
         }
+        catch { }
     }
     let released = false;
     return () => {
@@ -168,9 +235,7 @@ export function acquireFileMutationLock(path, options = {}) {
         const deadline = Date.now() + FILE_MUTATION_LOCK_TIMEOUT_MS;
         let removalContentionReported = false;
         while (!withRemovalBoundary(lockPath, () => {
-            if (readLockToken(lockPath) === token) {
-                rmSync(lockPath, { recursive: true, force: true });
-            }
+            removeLockBoundary(lockPath, token);
         })) {
             if (!removalContentionReported) {
                 removalContentionReported = true;
@@ -191,11 +256,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 +273,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;

package/dist/lib/inspector-actions.js

@@ -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.
  */
 import { join } from "node:path";
@@ -11,7 +11,7 @@ function bounded(value) {
         ? text
         : `${text.slice(0, FEEDBACK_LIMIT - 1)}…`;
 }
-export function killOwnedInspectorRun(ownerId, run, stateRoot, expectedRunInstanceId, deps) {
+export function killOwnedRunFromInspector(ownerId, run, stateRoot, expectedRunInstanceId, deps) {
     let stateDir;
     try {
         stateDir = join(stateRoot, safeRunId(run));

package/dist/lib/inspector-command.js

@@ -8,13 +8,13 @@ import * as InspectorActions from "./inspector-actions.js";
 import * as InspectorOverlay from "./inspector-overlay.js";
 import * as Paths from "./paths.js";
 export function registerActorInspectorCommand(pi, getRunOwnerId) {
-    pi.registerCommand("actors-inspector", {
-        description: "Open the keyboard-driven actor inspector overlay",
+    pi.registerCommand("actor-inspector", {
+        description: "Open the keyboard-driven Actor Inspector",
         handler: async (_args, ctx) => {
             ctx.ui.setWidget("zz-pi-actors-comms", undefined);
             await ctx.ui.custom((tui, theme, _keybindings, done) => new InspectorOverlay.ActorInspectorOverlay({
                 done,
-                killRun: (run, runInstanceId) => InspectorActions.killOwnedInspectorRun(getRunOwnerId(ctx), run, Paths.EXTENSION_RUNTIME_PATHS.runStateRoot, runInstanceId, {
+                killRun: (run, runInstanceId) => InspectorActions.killOwnedRunFromInspector(getRunOwnerId(ctx), run, Paths.EXTENSION_RUNTIME_PATHS.runStateRoot, runInstanceId, {
                     getRunStatus: AsyncRuns.getRunStatus,
                     killRun: AsyncRuns.killRun,
                 }),