@llblab/pi-actors 0.41.0 → 0.41.1

package/lib/inspector.ts

@@ -107,9 +107,12 @@ export function readActorInspectorRuns(
               : {}),
         }];
       })
-      .sort((left, right) =>
-        String(left.updatedAt ?? "").localeCompare(String(right.updatedAt ?? "")),
-      );
+      .sort((left, right) => {
+        const recency = String(right.updatedAt ?? "").localeCompare(
+          String(left.updatedAt ?? ""),
+        );
+        return recency || right.run.localeCompare(left.run);
+      });
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
     return [];

package/lib/observability.ts

@@ -101,15 +101,19 @@ export function createRunUiObservationState(): RunUiObservationState {
 export function readRunUiSnapshot(
   state: RunUiObservationState,
   ownerId: string,
+  options: { includeOutbox?: boolean; stateRoot?: string } = {},
 ): RunUiSnapshot {
-  const summary = summarizeRuns(undefined, ownerId);
+  const summary = summarizeRuns(options.stateRoot, ownerId);
   const status = renderRunStatus(summary, state.frame++);
   return {
-    outboxEvents: detectRunOutboxEvents(
-      state.eventLines,
-      summary,
-      state.outboxEventIds,
-    ),
+    outboxEvents:
+      options.includeOutbox === false
+        ? []
+        : detectRunOutboxEvents(
+            state.eventLines,
+            summary,
+            state.outboxEventIds,
+          ),
     status,
     summary,
     transitions: detectRunTransitions(state.observed, summary),
@@ -134,27 +138,55 @@ export function pruneRunUiObservationState(
 export function deliverRunTransitionNotifications(
   transitions: RunTransition[],
   sink: RunUiNotificationSink,
+  inFlight: Set<string> = new Set(),
 ): void {
   for (const transition of transitions) {
     if (!shouldNotifyRunTransition(transition)) continue;
-    const text = formatRunTransitionMessage(transition);
-    sink.notify(text, getRunTransitionNotificationType(transition));
-    if (!shouldSendRunTransitionFollowUp(transition)) continue;
-    sink.sendFollowUp({
-      customType: "pi-actors-run",
-      content: text,
-      display: true,
-      details: transition,
-    });
-    if (transition.stateDir) {
-      AsyncRuns.markRunTerminalNotificationHandled(
-        transition.stateDir,
-        transition.to,
-      );
+    const key = transition.stateDir ?? transition.run;
+    if (inFlight.has(key)) continue;
+    inFlight.add(key);
+    try {
+      const text = formatRunTransitionMessage(transition);
+      sink.notify(text, getRunTransitionNotificationType(transition));
+      if (!shouldSendRunTransitionFollowUp(transition)) continue;
+      sink.sendFollowUp({
+        customType: "pi-actors-run",
+        content: text,
+        display: true,
+        details: transition,
+      });
+      if (transition.stateDir) {
+        AsyncRuns.markRunTerminalNotificationHandled(
+          transition.stateDir,
+          transition.to,
+        );
+      }
+    } finally {
+      inFlight.delete(key);
     }
   }
 }
 
+export function reconcileRunTerminalNotifications(input: {
+  inFlight?: Set<string>;
+  ownerId: string;
+  sink: RunUiNotificationSink;
+  state: RunUiObservationState;
+  stateRoot?: string;
+}): RunUiSnapshot {
+  const snapshot = readRunUiSnapshot(input.state, input.ownerId, {
+    includeOutbox: false,
+    stateRoot: input.stateRoot,
+  });
+  deliverRunTransitionNotifications(
+    snapshot.transitions,
+    input.sink,
+    input.inFlight,
+  );
+  pruneRunUiObservationState(input.state, snapshot);
+  return snapshot;
+}
+
 export function deliverRunOutboxNotifications(
   events: RunOutboxEvent[],
   sink: RunUiNotificationSink,
@@ -189,18 +221,94 @@ export interface RunRetirementExecution {
   stateDir: string;
 }
 
+export type RunStateWatcherDiagnosticCode =
+  | "attach_failed"
+  | "error"
+  | "removed"
+  | "rearmed";
+
+export interface RunStateWatcherDiagnostic {
+  code: RunStateWatcherDiagnosticCode;
+  id: number;
+  message: string;
+  path: string;
+  scope: "root" | "run";
+  ts: string;
+}
+
 export interface RunStateWatcher {
   close(): void;
+  getDiagnostics(): RunStateWatcherDiagnostic[];
   refresh(): void;
 }
 
+const RUN_WATCHER_DIAGNOSTIC_LIMIT = 32;
+
 export function createRunStateWatcher(input: {
-  stateRoot?: string;
+  exists?: (path: string) => boolean;
+  listDirectories?: (path: string) => string[];
   onChange: () => void;
+  stateRoot?: string;
+  watchPath?: (path: string, onChange: () => void) => FSWatcher;
 }): RunStateWatcher {
   const stateRoot = input.stateRoot ?? Paths.getRunStateRoot();
+  const pathExists = input.exists ?? existsSync;
+  const listDirectories =
+    input.listDirectories ??
+    ((path: string) =>
+      readdirSync(path, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(path, entry.name)));
+  const watchPath = input.watchPath ?? ((path, onChange) => watch(path, onChange));
+  let diagnosticId = 0;
+  let rootDegraded = false;
   let stateRootWatcher: FSWatcher | undefined;
+  const degradedRunDirs = new Set<string>();
+  const diagnostics: RunStateWatcherDiagnostic[] = [];
+  const lastDiagnosticSignatures = new Map<string, string>();
   const runDirWatchers = new Map<string, FSWatcher>();
+  const record = (
+    code: RunStateWatcherDiagnosticCode,
+    scope: "root" | "run",
+    path: string,
+    error?: unknown,
+  ): void => {
+    const detail = error instanceof Error ? `: ${error.message}` : "";
+    const signature = `${code}${detail}`;
+    const signatureKey = `${scope}:${path}`;
+    if (lastDiagnosticSignatures.get(signatureKey) === signature) return;
+    lastDiagnosticSignatures.set(signatureKey, signature);
+    const recovery =
+      code === "rearmed"
+        ? "; terminal watch acceleration restored"
+        : "; terminal reconciliation remains active and watcher rearm will retry";
+    diagnostics.push({
+      code,
+      id: ++diagnosticId,
+      message: `Run-state ${scope} watcher ${code.replace("_", " ")} for ${path}${detail}${recovery}`,
+      path,
+      scope,
+      ts: new Date().toISOString(),
+    });
+    if (diagnostics.length > RUN_WATCHER_DIAGNOSTIC_LIMIT) diagnostics.shift();
+  };
+  const removeRunWatcher = (
+    stateDir: string,
+    watcher: FSWatcher,
+    options: { degraded?: boolean; error?: unknown } = {},
+  ): void => {
+    if (runDirWatchers.get(stateDir) !== watcher) return;
+    watcher.close();
+    runDirWatchers.delete(stateDir);
+    if (options.degraded === false) {
+      degradedRunDirs.delete(stateDir);
+      lastDiagnosticSignatures.delete(`run:${stateDir}`);
+      return;
+    }
+    degradedRunDirs.add(stateDir);
+    if (options.error) record("error", "run", stateDir, options.error);
+    record("removed", "run", stateDir);
+  };
   const close = (): void => {
     stateRootWatcher?.close();
     stateRootWatcher = undefined;
@@ -208,37 +316,95 @@ export function createRunStateWatcher(input: {
     runDirWatchers.clear();
   };
   const watchRunDir = (stateDir: string): void => {
-    if (runDirWatchers.has(stateDir) || !existsSync(stateDir)) return;
+    if (runDirWatchers.has(stateDir) || !pathExists(stateDir)) return;
     try {
-      const watcher = watch(stateDir, input.onChange);
-      watcher.on("error", () => {
-        watcher.close();
-        runDirWatchers.delete(stateDir);
-      });
+      const watcher = watchPath(stateDir, input.onChange);
+      watcher.on("error", (error) =>
+        removeRunWatcher(stateDir, watcher, { error }),
+      );
       runDirWatchers.set(stateDir, watcher);
-    } catch {
-      // Watching is best-effort; explicit inspect remains available.
+      if (degradedRunDirs.delete(stateDir)) record("rearmed", "run", stateDir);
+    } catch (error) {
+      degradedRunDirs.add(stateDir);
+      record("attach_failed", "run", stateDir, error);
     }
   };
   function refresh(): void {
-    if (!existsSync(stateRoot)) return;
+    if (!pathExists(stateRoot)) return;
     if (!stateRootWatcher) {
       try {
-        stateRootWatcher = watch(stateRoot, input.onChange);
-        stateRootWatcher.on("error", () => {
-          stateRootWatcher?.close();
+        const watcher = watchPath(stateRoot, input.onChange);
+        stateRootWatcher = watcher;
+        watcher.on("error", (error) => {
+          if (stateRootWatcher !== watcher) return;
+          watcher.close();
           stateRootWatcher = undefined;
+          rootDegraded = true;
+          record("error", "root", stateRoot, error);
+          record("removed", "root", stateRoot);
         });
-      } catch {
-        // Watching is best-effort; explicit inspect remains available.
+        if (rootDegraded) {
+          rootDegraded = false;
+          record("rearmed", "root", stateRoot);
+        }
+      } catch (error) {
+        rootDegraded = true;
+        record("attach_failed", "root", stateRoot, error);
       }
     }
-    for (const entry of readdirSync(stateRoot, { withFileTypes: true })) {
-      if (!entry.isDirectory()) continue;
-      watchRunDir(`${stateRoot}/${entry.name}`);
+    let stateDirs: string[];
+    try {
+      stateDirs = listDirectories(stateRoot);
+    } catch (error) {
+      record("attach_failed", "root", stateRoot, error);
+      return;
     }
+    const present = new Set(stateDirs);
+    for (const [stateDir, watcher] of runDirWatchers) {
+      if (present.has(stateDir) && pathExists(stateDir)) continue;
+      removeRunWatcher(stateDir, watcher, { degraded: false });
+    }
+    for (const stateDir of stateDirs) watchRunDir(stateDir);
   }
-  return { close, refresh };
+  return {
+    close,
+    getDiagnostics: () => [...diagnostics],
+    refresh,
+  };
+}
+
+export interface RunTerminalReconciliationLoop {
+  close(): void;
+  reconcileNow(): void;
+  start(): void;
+}
+
+export function createRunTerminalReconciliationLoop(input: {
+  intervalMs?: number;
+  onError?: (error: unknown) => void;
+  reconcile: () => void;
+  refreshWatcher: () => void;
+}): RunTerminalReconciliationLoop {
+  const intervalMs = input.intervalMs ?? 10_000;
+  let interval: NodeJS.Timeout | undefined;
+  const reconcileNow = (): void => {
+    try {
+      input.refreshWatcher();
+      input.reconcile();
+    } catch (error) {
+      input.onError?.(error);
+    }
+  };
+  const close = (): void => {
+    if (interval) clearInterval(interval);
+    interval = undefined;
+  };
+  const start = (): void => {
+    close();
+    interval = setInterval(reconcileNow, intervalMs);
+    interval.unref?.();
+  };
+  return { close, reconcileNow, start };
 }
 
 export interface RunRetirementExecutorOptions {

package/lib/tools-response.ts

@@ -7,9 +7,8 @@
 import * as Limits from "./limits.ts";
 import * as ToolsMailbox from "./tools-mailbox.ts";
 
-export function withLeadingBlankLine(text: string): string {
-  if (text.startsWith("\n\n")) return text;
-  return text.startsWith("\n") ? `\n${text}` : `\n\n${text}`;
+export function withLeadingLineBreak(text: string): string {
+  return `\n${text.replace(/^\n+/, "")}`;
 }
 
 export function spaceToolResult<T>(result: T): T {
@@ -25,7 +24,7 @@ export function spaceToolResult<T>(result: T): T {
       typeof (item as { text?: unknown }).text === "string"
         ? {
             ...item,
-            text: withLeadingBlankLine((item as { text: string }).text),
+            text: withLeadingLineBreak((item as { text: string }).text),
           }
         : item,
     ),
@@ -34,10 +33,10 @@ export function spaceToolResult<T>(result: T): T {
 
 export function spaceToolError(error: unknown): unknown {
   if (error instanceof Error) {
-    error.message = withLeadingBlankLine(error.message);
+    error.message = withLeadingLineBreak(error.message);
     return error;
   }
-  return new Error(withLeadingBlankLine(String(error)));
+  return new Error(withLeadingLineBreak(String(error)));
 }
 
 export function asRecord(value: unknown): Record<string, unknown> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.41.0",
+  "version": "0.41.1",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use, including parallel actor launches, subagent fanout, and autonomous coordinator workflows. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.41.0
+  version: 0.41.1
 ---
 
 # Actors (pi-actors)
@@ -125,17 +125,13 @@ Views:
 - `artifacts`: declared artifact paths/status plus the same bounded owned review-evidence manifest when present.
 - `recipes` target: registry summary for active, shadowed, invalid, disabled, and diagnostic recipe entries.
 
-Actor inspector navigation uses one command: `/actors-inspector-toggle` opens the centered overlay. It exposes explicit Tabs → Filters → List → Detail focus zones over the first run owned by the current session. Tabs use ←/→; ↓ enters Filters; ↑ at the top boundary does nothing. The filter bar contains only selectable controls; arrows move focus, Enter opens a compact value popup anchored beneath that filter, ↑/↓ hover a value, and Enter applies it. A filter cannot move down into an empty list. Accent text marks current values, a light background marks keyboard focus, and opening a nested popup preserves both its blue parent filter and the striped timeline outside the occluded cells. Lists use ↑/↓ and Enter; detail uses ↑/↓ and Enter/←. Escape cancels options or closes the overlay. The list body carries the selected run and live status above compact striped evidence rows; tabs, live refresh, empty states, and key hints remain visible so no subcommand grammar is required.
-
-Communication rows retain bounded body previews, capped noisy room traffic, branch-local inbox state, stable event ids, attention markers, and compact roster summaries. Turn rows come only from persisted owned child-session evidence and show source model/text at a glance. Turn detail remains bounded and includes command/stage, session/prompt/recipe provenance, user/assistant text, persisted thinking or explicit reasoning unavailability, stop/usage/error metadata, correlated tool arguments/results, truncation, and parse diagnostics. Active roster members use the target color, departed members stay muted, and display names come from `actor.join` bodies or branch addresses.
-
-Let terminal notifications arrive. They queue through Pi's follow-up delivery mode, so a busy coordinator finishes its current work before receiving concurrently completed actor results; the host's `followUpMode` controls whether queued results arrive together or one at a time. When a deferred actor result gates the next step, wait for that terminal follow-up instead of scheduling continuation loops, repeatedly inspecting, or mutating the actor's reviewed scope. Idle coordinators still start a normal turn through `triggerTurn: true`. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue or stuck run.
+Let terminal notifications arrive. They queue through Pi's follow-up delivery mode, so a busy coordinator finishes its current work before receiving concurrently completed actor results; the host's `followUpMode` controls whether queued results arrive together or one at a time. File watching accelerates delivery, while a bounded ten-second terminal-only reconciliation pass recovers missed or failed watcher activity without replaying outbox traffic; watcher degradation and rearm remain visible diagnostics. When a deferred actor result gates the next step, wait for that terminal follow-up instead of scheduling continuation loops, repeatedly inspecting, or mutating the actor's reviewed scope. Idle coordinators still start a normal turn through `triggerTurn: true`. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue or stuck run.
 
 ## Runtime Communication Rules
 
 - Keep one public communication model: `spawn` creates actors, `message` sends typed envelopes, and `inspect` observes. Avoid adding public side channels or storage nouns when a normal actor address/view can express the operation.
 - Keep route and semantic type separate. Direct, room, coordinator, and session messages may share `type`; delivery behavior comes from `to`.
-- Treat inspector-visible communication logs as recipe evidence. Use `inspect room:<run> view=messages|previews`, `inspect run:<id> view=communication`, and the actor inspector table/full-message views to improve mailbox/artifact conventions after real runs.
+- Treat persisted communication logs as recipe evidence. Use `inspect room:<run> view=messages|previews` and `inspect run:<id> view=communication` to improve mailbox/artifact conventions after real runs.
 - Any UI, summary, or aggregate view that scans run directories must apply coordinator/session ownership filters before exposing summaries or body previews.
 - Treat `communication.json` as visible actor context, not a global mutable truth table. Run-level snapshots should identify the run actor; branch-local snapshots should identify the branch actor.
 - Prefer same-run provenance checks on lateral actor routes. If `from` is accepted for room or branch routes, validate that it belongs to the addressed run.

package/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent and actor orchestration with scoped locks, fanout, and quorum consensus. Use before launching multiple parallel actors or subagents for independent implementation, artifact generation, review, delegated audit, coordinated execution, or any workflow that needs autonomous coordinator decomposition and integration.
 metadata:
-  version: 0.41.0
+  version: 0.41.1
 ---
 
 # Swarm