@llblab/pi-actors 0.43.0 → 0.43.1

package/lib/inspector-overlay.ts

@@ -16,6 +16,7 @@ import {
 } from "@earendil-works/pi-tui";
 
 import * as ActorInspector from "./inspector.ts";
+import * as ControlProjection from "./control-projection.ts";
 import * as RunsControls from "./runs-controls.ts";
 import * as RunControlDelivery from "./runs-control-delivery.ts";
 import * as TraceProjection from "./trace-projection.ts";
@@ -58,6 +59,12 @@ const TRACE_SOURCES: TraceProjection.TraceSourceFilter[] = [
   "runtime",
 ];
 
+function newestTraceItems(items: readonly TraceProjection.TraceItem[]): TraceProjection.TraceItem[] {
+  return [...items].sort((left, right) =>
+    right.ts.localeCompare(left.ts) || right.id.localeCompare(left.id),
+  );
+}
+
 export class ActorInspectorOverlay {
   private readonly done: () => void;
   private readonly killRun?: (run: string, runInstanceId: string) => ActorInspectorActionResult;
@@ -77,6 +84,7 @@ export class ActorInspectorOverlay {
   private killDialogChoice: "cancel" | "kill" = "cancel";
   private rowIndex = 0;
   private runCache?: ActorInspector.ActorInspectorRunItem[];
+  private selectedTraceId?: string;
   private runIndex = 0;
   private selectorIndex = 0;
   private selectorMode?: SelectorMode;
@@ -99,8 +107,7 @@ export class ActorInspectorOverlay {
     this.theme = options.theme;
     this.tui = options.tui;
     this.refreshTimer = setInterval(() => {
-      this.runCache = undefined;
-      if (this.focus !== "list" && this.focus !== "detail") this.traceCache = undefined;
+      this.invalidate();
       this.tui.requestRender();
     }, 1_000);
     this.refreshTimer.unref?.();
@@ -110,7 +117,10 @@ export class ActorInspectorOverlay {
     clearInterval(this.refreshTimer);
   }
 
-  invalidate(): void {}
+  invalidate(): void {
+    this.runCache = undefined;
+    this.traceCache = undefined;
+  }
 
   handleInput(data: string): void {
     const runs = this.runs();
@@ -134,10 +144,12 @@ export class ActorInspectorOverlay {
         this.selectorMode = undefined;
         this.focus = this.tab === "trace" ? "tabs" : "runs";
       } else if (this.focus === "detail") {
+        this.selectedTraceId = this.traceDetail?.id;
         this.traceDetail = undefined;
         this.detailScroll = 0;
         this.focus = "list";
       } else if (this.focus === "document" || this.focus === "list") {
+        if (this.focus === "list") this.selectedTraceId = undefined;
         this.focus = "tabs";
       } else {
         this.done();
@@ -179,19 +191,27 @@ export class ActorInspectorOverlay {
       } else if (matchesKey(data, "up")) {
         this.focus = "runs";
       } else if (matchesKey(data, "down")) {
-        this.focus = this.tab === "trace" && this.traceItems(runs[this.runIndex]).length > 0
-          ? "list"
-          : "document";
+        const items = this.tab === "trace" ? this.traceItems(runs[this.runIndex]) : [];
+        this.focus = items.length > 0 ? "list" : "document";
+        if (this.focus === "list") {
+          this.rowIndex = 0;
+          this.selectedTraceId = items[0]?.id;
+        }
       } else if (matchesKey(data, "return")) {
         if (this.tab === "trace") this.openSourceSelector(runs[this.runIndex]);
         else this.focus = "document";
       }
     } else if (this.focus === "list") {
-      const count = this.traceItems(runs[this.runIndex]).length;
-      if (matchesKey(data, "left")) this.focus = "tabs";
-      else if (matchesKey(data, "up")) {
-        if (this.rowIndex === 0) this.focus = "tabs";
-        else this.rowIndex -= 1;
+      const items = this.traceItems(runs[this.runIndex]);
+      const count = items.length;
+      if (matchesKey(data, "left")) {
+        this.selectedTraceId = undefined;
+        this.focus = "tabs";
+      } else if (matchesKey(data, "up")) {
+        if (this.rowIndex === 0) {
+          this.selectedTraceId = undefined;
+          this.focus = "tabs";
+        } else this.rowIndex -= 1;
       } else if (matchesKey(data, "down")) {
         this.rowIndex = Math.min(Math.max(0, count - 1), this.rowIndex + 1);
       } else if (matchesKey(data, "pageUp")) {
@@ -202,13 +222,14 @@ export class ActorInspectorOverlay {
           this.rowIndex + this.contentViewportRows(),
         );
       } else if (matchesKey(data, "return") || matchesKey(data, "right")) {
-        const item = this.traceItems(runs[this.runIndex])[this.rowIndex];
+        const item = items[this.rowIndex];
         if (item) {
           this.traceDetail = item;
           this.detailScroll = 0;
           this.focus = "detail";
         }
       }
+      if (this.focus === "list") this.selectedTraceId = items[this.rowIndex]?.id;
     }
     if (data.toLowerCase() === "f" && this.tab === "trace") {
       this.cycleTraceSource(runs[this.runIndex]);
@@ -273,6 +294,7 @@ export class ActorInspectorOverlay {
     this.documentScroll = 0;
     this.detailScroll = 0;
     this.rowIndex = 0;
+    this.selectedTraceId = undefined;
     this.traceDetail = undefined;
   }
 
@@ -291,6 +313,7 @@ export class ActorInspectorOverlay {
     } else if (matchesKey(data, "pageDown")) {
       this[key] += this.contentViewportRows();
     } else if (matchesKey(data, "left") && target === "detail") {
+      this.selectedTraceId = this.traceDetail?.id;
       this.traceDetail = undefined;
       this.detailScroll = 0;
       this.focus = "list";
@@ -392,7 +415,9 @@ export class ActorInspectorOverlay {
     this.killDialogChoice = "cancel";
     if (!confirmation || !this.killRun) return;
     try {
-      this.feedback = this.killRun(confirmation.run, confirmation.runInstanceId);
+      const result = this.killRun(confirmation.run, confirmation.runInstanceId);
+      this.feedback = result.ok ? undefined : result;
+      if (result.ok) this.invalidate();
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       this.feedback = {
@@ -418,7 +443,6 @@ export class ActorInspectorOverlay {
       `${this.theme.fg("muted", "Current status:")} ${this.theme.fg("warning", confirmation.status)}`,
       "",
       this.theme.fg("text", "This sends canonical kill Control."),
-      this.theme.fg("error", "The action is destructive and cannot be undone."),
       "",
       `${cancel}    ${kill}`,
       "",
@@ -521,7 +545,15 @@ export class ActorInspectorOverlay {
   private renderTraceList(run: ActorInspector.ActorInspectorRunItem): string[] {
     const items = this.traceItems(run);
     if (items.length === 0) return [this.theme.fg("muted", " No Trace evidence")];
+    if (this.selectedTraceId) {
+      const selectedIndex = items.findIndex((item) => item.id === this.selectedTraceId);
+      if (selectedIndex >= 0) this.rowIndex = selectedIndex;
+      else this.selectedTraceId = undefined;
+    }
     this.rowIndex = Math.min(this.rowIndex, items.length - 1);
+    if (this.focus === "list" && !this.selectedTraceId) {
+      this.selectedTraceId = items[this.rowIndex]?.id;
+    }
     const viewportRows = this.contentViewportRows();
     const maxStart = Math.max(0, items.length - viewportRows);
     const start = Math.max(0, Math.min(this.rowIndex - Math.floor(viewportRows / 2), maxStart));
@@ -536,12 +568,12 @@ export class ActorInspectorOverlay {
       const marker = item.level === "error"
         ? this.theme.fg("error", "!")
         : detail.attention
-          ? this.theme.fg("warning", "•")
-          : this.theme.fg("muted", "·");
+          ? this.theme.fg("warning", "A")
+          : " ";
       const prefix = this.focus === "list" && index === this.rowIndex
         ? this.theme.fg("accent", " ▶ ")
         : "   ";
-      const row = `${prefix}${this.theme.fg("text", `#${index + 1}`)} ${marker} ${this.theme.fg("muted", item.source)}/${this.theme.fg(item.level === "error" ? "error" : "accent", item.kind)}  ${this.theme.fg("text", item.summary)}`;
+      const row = `${prefix}${this.theme.fg("text", `#${items.length - index}`)} ${marker} ${this.theme.fg("muted", item.source)}/${this.theme.fg(item.level === "error" ? "error" : "accent", item.kind)}  ${this.theme.fg("text", item.summary)}`;
       return this.focus === "list" && index === this.rowIndex
         ? this.theme.fg("accent", row)
         : row;
@@ -577,7 +609,10 @@ export class ActorInspectorOverlay {
       actor_actions: Array.isArray(meta.control) ? meta.control : [],
       runtime_actions: run.status === "running" ? ["kill"] : ["archive", "prune"],
       endpoint,
-      recent_controls: RunsControls.readRunControlsFromStateDir(stateDir).slice(-20).reverse(),
+      recent_controls: RunsControls.readRunControlsFromStateDir(stateDir)
+        .slice(-20)
+        .reverse()
+        .map(ControlProjection.projectRunControl),
     };
   }
 
@@ -589,10 +624,10 @@ export class ActorInspectorOverlay {
     ) {
       return this.traceCache.items;
     }
-    const items = this.readTrace(path.join(this.stateRoot, run.run), {
+    const items = newestTraceItems(this.readTrace(path.join(this.stateRoot, run.run), {
       limit: 100,
       source: "all",
-    });
+    }));
     this.traceCache = { run: run.run, runInstanceId: run.runInstanceId, items };
     return items;
   }
@@ -627,14 +662,9 @@ export class ActorInspectorOverlay {
     width: number,
   ): { lines: string[]; stripes: number[] } {
     const sections = value && typeof value === "object" && !Array.isArray(value)
-      ? Object.entries(value as Record<string, unknown>).map(([key, item]) => {
-          const inline = this.inlineDocumentValue(item);
-          return inline !== undefined
-            ? [`${key}: ${inline}`]
-            : item && typeof item === "object"
-              ? [`${key}:`, ...this.document(item, 1)]
-              : this.labeledScalarLines(key, item);
-        })
+      ? Object.entries(value as Record<string, unknown>).map(([key, item]) =>
+          this.labeledDocumentLines(key, item)
+        )
       : [this.document(value)];
     const lines: string[] = [];
     const stripes: number[] = [];
@@ -658,23 +688,22 @@ export class ActorInspectorOverlay {
       return undefined;
     }
     if (value && typeof value === "object") {
-      const entries = Object.entries(value as Record<string, unknown>);
-      if (entries.length === 0) return "{}";
-      if (
-        entries.length <= 3 &&
-        entries.every(([, item]) =>
-          (item === null || typeof item !== "object") &&
-          !(typeof item === "string" && /[\r\n]/u.test(item))
-        )
-      ) {
-        return `{ ${entries
-          .map(([key, item]) => `${key}: ${String(item ?? "none")}`)
-          .join(", ")} }`;
-      }
+      if (Object.keys(value as Record<string, unknown>).length === 0) return "{}";
     }
     return undefined;
   }
 
+  private labeledDocumentLines(key: string, value: unknown, depth = 0): string[] {
+    const inline = this.inlineDocumentValue(value);
+    if (inline !== undefined) return [`${"  ".repeat(depth)}${key}: ${inline}`];
+    if (value && typeof value === "object") {
+      const indent = "  ".repeat(depth);
+      const nested = this.document(value, depth);
+      return [`${indent}${key}: ${nested[0]!.slice(indent.length)}`, ...nested.slice(1)];
+    }
+    return this.labeledScalarLines(key, value, depth);
+  }
+
   private labeledScalarLines(key: string, value: unknown, depth = 0): string[] {
     const indent = "  ".repeat(depth);
     const [first = "", ...rest] = String(value ?? "none").split(/\r?\n/u);
@@ -689,25 +718,31 @@ export class ActorInspectorOverlay {
     const inline = this.inlineDocumentValue(value);
     if (inline !== undefined) return [`${"  ".repeat(depth)}${inline}`];
     if (Array.isArray(value)) {
-      return value.flatMap((item, index) => {
-        const marker = `${"  ".repeat(depth)}- #${index + 1}`;
-        const itemInline = this.inlineDocumentValue(item);
-        return itemInline !== undefined
-          ? [`${marker}: ${itemInline}`]
-          : [marker, ...this.document(item, depth + 1)];
-      });
+      const indent = "  ".repeat(depth);
+      return [
+        `${indent}[`,
+        ...value.flatMap((item, index) => {
+          const marker = `${indent}  - #${index + 1}`;
+          const itemInline = this.inlineDocumentValue(item);
+          return itemInline !== undefined
+            ? [`${marker}: ${itemInline}`]
+            : [marker, ...this.document(item, depth + 2)];
+        }),
+        `${indent}]`,
+      ];
     }
     if (typeof value === "object") {
-      return Object.entries(value as Record<string, unknown>).flatMap(([key, item]) => {
-        const itemInline = this.inlineDocumentValue(item);
-        if (itemInline !== undefined) {
-          return [`${"  ".repeat(depth)}${key}: ${itemInline}`];
-        }
-        if (item && typeof item === "object") {
-          return [`${"  ".repeat(depth)}${key}:`, ...this.document(item, depth + 1)];
-        }
-        return this.labeledScalarLines(key, item, depth);
-      });
+      const indent = "  ".repeat(depth);
+      const entries = Object.entries(value as Record<string, unknown>);
+      return [
+        `${indent}{`,
+        ...entries.flatMap(([key, item], index) => {
+          const lines = this.labeledDocumentLines(key, item, depth + 1);
+          if (index < entries.length - 1) lines[lines.length - 1] += ",";
+          return lines;
+        }),
+        `${indent}}`,
+      ];
     }
     return String(value)
       .split(/\r?\n/u)

package/lib/limits.ts

@@ -1,13 +1,15 @@
 /**
- * Shared output and preview size limits.
- * Zones: output governance, Trace previews, inspect defaults
+ * Shared output, preview, and Control envelope limits.
+ * Zones: output governance, Trace previews, Inspect defaults, Control portability
  */
 
 export const DEFAULT_INSPECT_LINES = 40;
 export const TOOL_OUTPUT_MAX_BYTES = 50 * 1024;
 export const TOOL_OUTPUT_MAX_LINES = 2_000;
 export const COMPACT_PREVIEW_CHARS = 160;
-export const CONTROL_INPUT_MAX_BYTES = 64 * 1024;
+export const CONTROL_ACTION_MAX_LENGTH = 64;
+export const CONTROL_INPUT_MAX_BYTES = 380;
+export const CONTROL_WIRE_MAX_BYTES = 512;
 export const INSPECTOR_BODY_PREVIEW_CHARS = 320;
 export const DOCTOR_ACTION_PREVIEW_CHARS = 72;
 export const SESSION_EVIDENCE_MAX_TURNS = 100;

package/lib/prompts.ts

@@ -22,7 +22,7 @@ export const REGISTER_TOOL_GUIDELINES = [
 export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.
 - Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.
-- Command templates stay sync and shell-free: string leaves split into executable + argv, so operators such as && are literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
+- Command templates stay sync and shell-free: string leaves split into executable + argv, infer .js/.mjs through node→bun→deno run and .sh through bash, and treat operators such as && as literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
 - Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
 - ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
 - Recipes own template directly and may declare metadata/defaults/imports/control/artifacts; files >1 MiB or import depth >32 fail closed.

package/lib/recipe-control.ts

@@ -4,7 +4,9 @@
  * Owns pure Recipe control validation; Recipe loading and Run capture stay in recipe/run domains.
  */
 
-const ACTION_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+)*$/;
+import * as Control from "./control.ts";
+import * as Limits from "./limits.ts";
+
 const RUNTIME_RUN_ACTIONS = new Set(["archive", "kill", "prune"]);
 
 export function normalizeRecipeControl(value: unknown): string[] | undefined {
@@ -19,9 +21,14 @@ export function normalizeRecipeControl(value: unknown): string[] | undefined {
       throw new Error("recipe.control actions must be non-empty strings");
     }
     const action = raw.trim();
-    if (!ACTION_PATTERN.test(action)) {
+    if (!Control.isControlAction(action)) {
       throw new Error(`invalid recipe.control action: ${action}`);
     }
+    if (action.length > Limits.CONTROL_ACTION_MAX_LENGTH) {
+      throw new Error(
+        `recipe.control action exceeds ${Limits.CONTROL_ACTION_MAX_LENGTH} ASCII characters: ${action}`,
+      );
+    }
     if (RUNTIME_RUN_ACTIONS.has(action)) {
       throw new Error(
         `recipe.control action is runtime-reserved and must not be declared: ${action}`,

package/lib/review-control.ts

@@ -124,14 +124,13 @@ export function controlAutomaticReview(
   return {
     ...result,
     next_actions: nextActions,
-    sent: result.changed === true,
   };
 }
 
-export function parseAutomaticReviewScope(body: unknown): AutomaticReviewScope {
-  const record = body && typeof body === "object" && !Array.isArray(body)
-    ? body as Record<string, unknown>
+export function parseAutomaticReviewScope(input: unknown): AutomaticReviewScope {
+  const record = input && typeof input === "object" && !Array.isArray(input)
+    ? input as Record<string, unknown>
     : {};
   if (record.scope === "draft" || record.scope === "tool") return record.scope;
-  throw new Error("review control requires body.scope=draft or body.scope=tool.");
+  throw new Error("review Control requires input.scope=draft or input.scope=tool.");
 }

package/lib/runs-control-delivery.ts

@@ -15,6 +15,8 @@ import {
 import { createConnection } from "node:net";
 import { join } from "node:path";
 
+import * as Control from "./control.ts";
+import * as Limits from "./limits.ts";
 import {
   appendRunControlInStateDir,
   updateRunControlStatusInStateDir,
@@ -37,7 +39,26 @@ export interface DeliverRunControlRequest {
   run_instance_id: string;
 }
 
-export const FIFO_ATOMIC_CONTROL_MAX_BYTES = 512;
+const PREFLIGHT_CONTROL_ID = "00000000-0000-4000-8000-000000000000";
+
+export function encodeRunControlWire(wire: {
+  action: string;
+  id: string;
+  input?: unknown;
+}): { bytes: number; payload: string } {
+  const payload = `${JSON.stringify({
+    id: wire.id,
+    action: wire.action,
+    ...(wire.input !== undefined ? { input: wire.input } : {}),
+  })}\n`;
+  const bytes = Buffer.byteLength(payload);
+  if (bytes > Limits.CONTROL_WIRE_MAX_BYTES) {
+    throw new Error(
+      `Run Control wire record exceeds the ${Limits.CONTROL_WIRE_MAX_BYTES}-byte portable bound`,
+    );
+  }
+  return { bytes, payload };
+}
 
 export function readRunControlEndpoint(
   stateDir: string,
@@ -107,7 +128,21 @@ export async function deliverRunControl(
   request: DeliverRunControlRequest,
   options: DeliverRunControlOptions = {},
 ): Promise<Record<string, unknown>> {
-  const control = appendRunControlInStateDir(stateDir, request);
+  const action = Control.normalizeControlAction(request.action);
+  const input = request.input === undefined
+    ? undefined
+    : Control.normalizeControlInput(request.input);
+  const normalizedRequest = {
+    action,
+    ...(input !== undefined ? { input } : {}),
+    run_instance_id: request.run_instance_id,
+  };
+  encodeRunControlWire({
+    id: PREFLIGHT_CONTROL_ID,
+    action,
+    ...(input !== undefined ? { input } : {}),
+  });
+  const control = appendRunControlInStateDir(stateDir, normalizedRequest);
   const endpoint = readRunControlEndpoint(stateDir, request.run_instance_id);
   if (!endpoint) {
     updateRunControlStatusInStateDir(
@@ -118,31 +153,24 @@ export async function deliverRunControl(
       ["queued", "delivered"],
     );
     throw Object.assign(new Error("Run Control endpoint is not ready."), {
-      action: request.action,
+      action,
       control_id: control.id,
       reason: "endpoint_not_ready",
       run,
       run_instance_id: request.run_instance_id,
     });
   }
-  const wire = {
-    id: control.id,
-    action: request.action,
-    ...(request.input !== undefined ? { input: request.input } : {}),
-  };
-  const payload = `${JSON.stringify(wire)}\n`;
-  const bytes = Buffer.byteLength(payload);
   try {
+    const { bytes, payload } = encodeRunControlWire({
+      id: control.id,
+      action,
+      ...(input !== undefined ? { input } : {}),
+    });
     let written: number;
     if (endpoint.type === "fifo") {
       if ((options.platform ?? process.platform) === "win32") {
         throw new Error("FIFO Control delivery is unsupported on native Windows");
       }
-      if (bytes > FIFO_ATOMIC_CONTROL_MAX_BYTES) {
-        throw new Error(
-          `FIFO Control payload exceeds the ${FIFO_ATOMIC_CONTROL_MAX_BYTES}-byte portable atomic-write bound`,
-        );
-      }
       written = sendToFifo(endpoint, payload);
     } else {
       written = await sendToNamedPipe(endpoint, payload, options.namedPipeSend);
@@ -152,7 +180,7 @@ export async function deliverRunControl(
     }
     updateRunControlStatusInStateDir(stateDir, control.id, "delivered");
     return {
-      action: request.action,
+      action,
       bytes,
       control_id: control.id,
       delivery: "delivered",
@@ -170,7 +198,7 @@ export async function deliverRunControl(
       ["queued", "delivered"],
     );
     throw Object.assign(new Error(`Run Control delivery failed: ${reason}`), {
-      action: request.action,
+      action,
       control_id: control.id,
       endpoint_type: endpoint.type,
       reason: "delivery_failed",

package/lib/runs-controls.ts

@@ -9,7 +9,11 @@ import { writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { acquireFileMutationLock, writeTextAtomic } from "./file-state.ts";
-import { readJsonlFileResilient } from "./state-readers.ts";
+import {
+  readJsonlFileResilient,
+  type JsonlReadResult,
+} from "./state-readers.ts";
+
 export const RUN_CONTROL_TERMINAL_LIMIT = 128;
 
 export type RunControlStatus =
@@ -45,9 +49,14 @@ export function runControlsFile(stateDir: string): string {
   return join(stateDir, "controls.jsonl");
 }
 
+export function readRunControlJournalFromStateDir(
+  stateDir: string,
+): JsonlReadResult<unknown> {
+  return readJsonlFileResilient<unknown>(runControlsFile(stateDir));
+}
+
 export function readRunControlsFromStateDir(stateDir: string): RunControlRecord[] {
-  return readJsonlFileResilient<RunControlRecord>(runControlsFile(stateDir))
-    .records;
+  return readRunControlJournalFromStateDir(stateDir).records as RunControlRecord[];
 }
 
 function acquireRunControlsLock(stateDir: string): () => void {

package/lib/runs-trace.ts

@@ -1,13 +1,14 @@
 /**
  * Run Trace event journal.
- * Zones: structured event validation, bounded append, resilient bounded reads
- * Owns Run-local semantic Trace events; lifecycle projection and owner attention delivery stay in adapters.
+ * Zones: structured event validation, token-locked append-only writes, resilient bounded reads
+ * Owns canonical Run-local Trace persistence; lifecycle projection and owner attention delivery stay in adapters.
  */
 
 import { randomUUID } from "node:crypto";
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { withFileMutationLock } from "./file-state.ts";
 import * as Limits from "./limits.ts";
 import { readJsonlFileResilient } from "./state-readers.ts";
 
@@ -104,23 +105,26 @@ export function appendRunTraceEvent(
   stateDir: string,
   input: AppendTraceEventInput,
 ): TraceEvent {
-  const normalized = normalizeTraceEventInput(input);
-  const event: TraceEvent = {
-    id: randomUUID(),
-    ts: new Date().toISOString(),
-    ...normalized,
-  };
-  let encoded: string;
-  try {
-    encoded = JSON.stringify(event);
-  } catch {
-    throw new Error("Trace event data must be JSON-serializable");
-  }
-  if (Buffer.byteLength(encoded) > Limits.TRACE_EVENT_MAX_BYTES) {
-    throw new Error(`Trace event exceeds ${Limits.TRACE_EVENT_MAX_BYTES} bytes`);
-  }
-  writeFileSync(runTraceFile(stateDir), `${encoded}\n`, { flag: "a" });
-  return event;
+  const path = runTraceFile(stateDir);
+  return withFileMutationLock(path, () => {
+    const normalized = normalizeTraceEventInput(input);
+    const event: TraceEvent = {
+      id: randomUUID(),
+      ts: new Date().toISOString(),
+      ...normalized,
+    };
+    let encoded: string;
+    try {
+      encoded = JSON.stringify(event);
+    } catch {
+      throw new Error("Trace event data must be JSON-serializable");
+    }
+    if (Buffer.byteLength(encoded) > Limits.TRACE_EVENT_MAX_BYTES) {
+      throw new Error(`Trace event exceeds ${Limits.TRACE_EVENT_MAX_BYTES} bytes`);
+    }
+    writeFileSync(path, `${encoded}\n`, { flag: "a" });
+    return event;
+  });
 }
 
 export function readRunTraceEvents(

package/lib/runtime-identity.ts

@@ -0,0 +1,39 @@
+/**
+ * Immutable runtime package identity.
+ * Zones: source/installed package version resolution and Run-state schema marker
+ * Owns package-local identity reads; runtime status and Run persistence remain in their domains.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const RUN_STATE_SCHEMA = "run-kernel-v1" as const;
+
+let cachedVersion: string | undefined;
+
+export function getPackageVersion(): string {
+  if (cachedVersion) return cachedVersion;
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  for (const path of [
+    join(moduleDir, "..", "package.json"),
+    join(moduleDir, "..", "..", "package.json"),
+  ]) {
+    try {
+      const pkg = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+      if (
+        pkg.name === "@llblab/pi-actors" &&
+        typeof pkg.version === "string" &&
+        pkg.version.length > 0 &&
+        pkg.version.length <= 128 &&
+        pkg.version.trim() === pkg.version
+      ) {
+        cachedVersion = pkg.version;
+        return cachedVersion;
+      }
+    } catch {
+      // Source and installed-dist modes resolve through different package ancestors.
+    }
+  }
+  throw new Error("pi-actors package identity is unavailable");
+}