@llblab/pi-actors 0.41.0 → 0.41.1

package/dist/lib/observability.d.ts

@@ -3,6 +3,7 @@
  * Zones: async runtime, ambient UI, diagnostics
  * Owns ambient summaries, terminal events, and run outbox delivery for detached command-template runs
  */
+import { type FSWatcher } from "node:fs";
 import * as AsyncRuns from "./async-runs.ts";
 export type RunObservedStatus = "running" | "done" | "failed" | "exited" | "cancelled" | "killed";
 export type RunOutboxDelivery = "log" | "notify" | "followup";
@@ -58,9 +59,19 @@ export interface RunUiNotificationSink {
     }): void;
 }
 export declare function createRunUiObservationState(): RunUiObservationState;
-export declare function readRunUiSnapshot(state: RunUiObservationState, ownerId: string): RunUiSnapshot;
+export declare function readRunUiSnapshot(state: RunUiObservationState, ownerId: string, options?: {
+    includeOutbox?: boolean;
+    stateRoot?: string;
+}): RunUiSnapshot;
 export declare function pruneRunUiObservationState(state: RunUiObservationState, snapshot: Pick<RunUiSnapshot, "summary" | "transitions">): void;
-export declare function deliverRunTransitionNotifications(transitions: RunTransition[], sink: RunUiNotificationSink): void;
+export declare function deliverRunTransitionNotifications(transitions: RunTransition[], sink: RunUiNotificationSink, inFlight?: Set<string>): void;
+export declare function reconcileRunTerminalNotifications(input: {
+    inFlight?: Set<string>;
+    ownerId: string;
+    sink: RunUiNotificationSink;
+    state: RunUiObservationState;
+    stateRoot?: string;
+}): RunUiSnapshot;
 export declare function deliverRunOutboxNotifications(events: RunOutboxEvent[], sink: RunUiNotificationSink): void;
 export interface RunRetirementCandidate {
     activeSubagents: number;
@@ -76,14 +87,38 @@ export interface RunRetirementExecution {
     run: string;
     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;
 }
 export declare function createRunStateWatcher(input: {
-    stateRoot?: string;
+    exists?: (path: string) => boolean;
+    listDirectories?: (path: string) => string[];
     onChange: () => void;
+    stateRoot?: string;
+    watchPath?: (path: string, onChange: () => void) => FSWatcher;
 }): RunStateWatcher;
+export interface RunTerminalReconciliationLoop {
+    close(): void;
+    reconcileNow(): void;
+    start(): void;
+}
+export declare function createRunTerminalReconciliationLoop(input: {
+    intervalMs?: number;
+    onError?: (error: unknown) => void;
+    reconcile: () => void;
+    refreshWatcher: () => void;
+}): RunTerminalReconciliationLoop;
 export interface RunRetirementExecutorOptions {
     attempted?: Set<string>;
     cancelRun: (candidate: RunRetirementCandidate) => Record<string, unknown>;

package/dist/lib/observability.js

@@ -16,11 +16,13 @@ export function createRunUiObservationState() {
         outboxEventIds: new Map(),
     };
 }
-export function readRunUiSnapshot(state, ownerId) {
-    const summary = summarizeRuns(undefined, ownerId);
+export function readRunUiSnapshot(state, ownerId, options = {}) {
+    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),
@@ -29,25 +31,43 @@ export function readRunUiSnapshot(state, ownerId) {
 export function pruneRunUiObservationState(state, snapshot) {
     pruneRunObservationState(state.observed, state.eventLines, snapshot.summary, snapshot.transitions.map((transition) => transition.stateDir ?? transition.run), state.outboxEventIds);
 }
-export function deliverRunTransitionNotifications(transitions, sink) {
+export function deliverRunTransitionNotifications(transitions, sink, inFlight = new Set()) {
     for (const transition of transitions) {
         if (!shouldNotifyRunTransition(transition))
             continue;
-        const text = formatRunTransitionMessage(transition);
-        sink.notify(text, getRunTransitionNotificationType(transition));
-        if (!shouldSendRunTransitionFollowUp(transition))
+        const key = transition.stateDir ?? transition.run;
+        if (inFlight.has(key))
             continue;
-        sink.sendFollowUp({
-            customType: "pi-actors-run",
-            content: text,
-            display: true,
-            details: transition,
-        });
-        if (transition.stateDir) {
-            AsyncRuns.markRunTerminalNotificationHandled(transition.stateDir, transition.to);
+        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) {
+    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, sink) {
     for (const event of events) {
         if (!shouldNotifyRunOutboxEvent(event))
@@ -64,10 +84,58 @@ export function deliverRunOutboxNotifications(events, sink) {
         });
     }
 }
+const RUN_WATCHER_DIAGNOSTIC_LIMIT = 32;
 export function createRunStateWatcher(input) {
     const stateRoot = input.stateRoot ?? Paths.getRunStateRoot();
+    const pathExists = input.exists ?? existsSync;
+    const listDirectories = input.listDirectories ??
+        ((path) => 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;
+    const degradedRunDirs = new Set();
+    const diagnostics = [];
+    const lastDiagnosticSignatures = new Map();
     const runDirWatchers = new Map();
+    const record = (code, scope, path, error) => {
+        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, watcher, options = {}) => {
+        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 = () => {
         stateRootWatcher?.close();
         stateRootWatcher = undefined;
@@ -76,42 +144,92 @@ export function createRunStateWatcher(input) {
         runDirWatchers.clear();
     };
     const watchRunDir = (stateDir) => {
-        if (runDirWatchers.has(stateDir) || !existsSync(stateDir))
+        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);
+            if (degradedRunDirs.delete(stateDir))
+                record("rearmed", "run", stateDir);
         }
-        catch {
-            // Watching is best-effort; explicit inspect remains available.
+        catch (error) {
+            degradedRunDirs.add(stateDir);
+            record("attach_failed", "run", stateDir, error);
         }
     };
     function refresh() {
-        if (!existsSync(stateRoot))
+        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);
                 });
+                if (rootDegraded) {
+                    rootDegraded = false;
+                    record("rearmed", "root", stateRoot);
+                }
             }
-            catch {
-                // Watching is best-effort; explicit inspect remains available.
+            catch (error) {
+                rootDegraded = true;
+                record("attach_failed", "root", stateRoot, error);
             }
         }
-        for (const entry of readdirSync(stateRoot, { withFileTypes: true })) {
-            if (!entry.isDirectory())
+        let stateDirs;
+        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;
-            watchRunDir(`${stateRoot}/${entry.name}`);
+            removeRunWatcher(stateDir, watcher, { degraded: false });
         }
+        for (const stateDir of stateDirs)
+            watchRunDir(stateDir);
     }
-    return { close, refresh };
+    return {
+        close,
+        getDiagnostics: () => [...diagnostics],
+        refresh,
+    };
+}
+export function createRunTerminalReconciliationLoop(input) {
+    const intervalMs = input.intervalMs ?? 10_000;
+    let interval;
+    const reconcileNow = () => {
+        try {
+            input.refreshWatcher();
+            input.reconcile();
+        }
+        catch (error) {
+            input.onError?.(error);
+        }
+    };
+    const close = () => {
+        if (interval)
+            clearInterval(interval);
+        interval = undefined;
+    };
+    const start = () => {
+        close();
+        interval = setInterval(reconcileNow, intervalMs);
+        interval.unref?.();
+    };
+    return { close, reconcileNow, start };
 }
 const TERMINAL = new Set([
     "done",

package/dist/lib/tools-response.d.ts

@@ -3,7 +3,7 @@
  * Zones: compact text summaries, verbose JSON switching, next-action rendering
  * Owns model-facing response helpers shared by public tool execution paths
  */
-export declare function withLeadingBlankLine(text: string): string;
+export declare function withLeadingLineBreak(text: string): string;
 export declare function spaceToolResult<T>(result: T): T;
 export declare function spaceToolError(error: unknown): unknown;
 export declare function asRecord(value: unknown): Record<string, unknown>;

package/dist/lib/tools-response.js

@@ -5,10 +5,8 @@
  */
 import * as Limits from "./limits.js";
 import * as ToolsMailbox from "./tools-mailbox.js";
-export function withLeadingBlankLine(text) {
-    if (text.startsWith("\n\n"))
-        return text;
-    return text.startsWith("\n") ? `\n${text}` : `\n\n${text}`;
+export function withLeadingLineBreak(text) {
+    return `\n${text.replace(/^\n+/, "")}`;
 }
 export function spaceToolResult(result) {
     if (!result || typeof result !== "object")
@@ -24,17 +22,17 @@ export function spaceToolResult(result) {
             typeof item.text === "string"
             ? {
                 ...item,
-                text: withLeadingBlankLine(item.text),
+                text: withLeadingLineBreak(item.text),
             }
             : item),
     };
 }
 export function spaceToolError(error) {
     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) {
     return value && typeof value === "object" && !Array.isArray(value)

package/dist/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/dist/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

package/docs/actor-inspector.md

@@ -11,35 +11,36 @@ owned run
 
 ## Navigation
 
-`/actors-inspector-toggle` opens one centered overlay and remains the only command to remember. The first run owned by the current Pi session becomes the active run automatically; an empty session still exposes functional tabs and filters.
+`/actors-inspector` opens one centered overlay and remains the only command to remember. The latest run owned by the current Pi session becomes active automatically; an empty session still exposes functional tabs and filters.
 
 The overlay exposes an explicit focus hierarchy:
 
 ```text
-Run       Enter opens owned runs, ↓ enters tabs
+Run       ←/→ chooses the previous/next owned run, Enter opens runs, ↓ enters tabs
 Tabs      ←/→ chooses Messages or Turns, Enter opens filter parameters
 Filters   ↑/↓ chooses Channel/State or Subagent, Enter opens values to the right
 Values    ↑/↓ hovers, Enter applies, Escape returns one menu level
 List      ↑/↓ chooses, Enter/→ opens detail
-Detail    ↑/↓ scroll, Escape/← returns
+Detail    ↑/↓ scroll, Enter/→ opens readable transcript, Escape/← returns
+Readable  ↑/↓ scroll, Escape/← returns to evidence detail
 Escape    Close (or cancel the active options popup)
 ```
 
 Navigation stays bounded by available actions. `↑` on Run does nothing because no higher control exists. `↓` on Tabs enters the timeline only when it contains rows. Empty timelines therefore never receive focus.
 
-Selection and focus remain separate visual states. Accent-blue text marks the current tab, active filter popup, and applied option. A light neutral background plus `▶` marks every selectable control or timeline row that currently owns keyboard focus. Opening a popup keeps its parent filter blue so the relationship remains visible. The footer uses accent color only for key names and arrows; descriptions remain muted.
+Selection and focus remain separate visual states. Accent-blue text marks the current tab, active filter popup, and applied option. The Run control uses `← … →` markers plus a light neutral background to show both focus and horizontal cycling; menus and timeline rows retain the single `▶` focus marker, while selected tabs retain brackets. Opening a popup keeps its parent filter blue so the relationship remains visible. The footer uses accent color only for key names and arrows; descriptions remain muted.
 
-The top Run control aligns vertically with the tab labels, names the selected owned run, and colors its textual lifecycle status semantically. Enter opens available owned runs immediately beneath it, overlaying the tab row rather than leaving a detached gap. The timeline no longer renders run metadata as a data row.
+The top Run control aligns vertically with the tab labels, names the selected owned run, and colors its textual lifecycle status semantically. ←/→ cycles owned runs directly with wraparound, while Enter opens the complete owned-run list immediately beneath the control. That run list starts one cell farther left than the filter menus so its border aligns with the Run control rather than the tab/filter grid. It still overlays the tab row rather than leaving a detached gap. The timeline no longer renders run metadata as a data row.
 
-Filters live behind their tab rather than occupying a permanent row. Non-default filters remain visible as compact suffixes in the tab label, so hidden state never silently changes the timeline. Enter on Messages opens `Channel: <current>`, `State: <current>`, and `From: <current>`; `From` draws its values from the selected run's roster and limits rows to one actor. Enter on Turns opens `Subagent: <current>`. Enter on a parameter opens its alternative values as a second menu to the right while the parent and current value remain visible. Parent and child share their touching border rather than leaving or doubling a spacer column. Escape returns one level at a time. Moving focus never applies a value.
+Filters live behind their tab rather than occupying a permanent row. Non-default filters remain visible as compact parenthesized suffixes in the tab label, so hidden state never silently changes the timeline. Enter on Messages opens `Channel: <current>`, `State: <current>`, and `From: <current>`; `From` draws its values from the selected run's roster and limits rows to one actor. Enter on Turns opens `Subagent: <current>`. Enter on a parameter opens its alternative values as a second menu to the right while the parent and current value remain visible. Parent and child share their touching border rather than leaving or doubling a spacer column. Escape returns one level at a time. Moving focus never applies a value.
 
-Nested menus overlay rather than replace the timeline. Only rows and columns containing menu borders or values occlude underlying cells. When adjacent menus have different heights, the unused corner remains transparent and preserves the separator, striped background, and timeline data beneath it.
+Nested menus overlay rather than replace the timeline. Only rows and columns containing menu borders or values occlude underlying cells. When adjacent menus have different heights, the unused corner remains transparent and preserves the separator, striped background, and timeline data beneath it. Every run, filter, and nested value menu is viewport-bounded: ↑/↓ moves through the complete option set, the visible window follows focus, and `↑`/`↓` border markers disclose hidden options above or below without growing past the available inspector rows.
 
-The overlay uses most of the available terminal width and height. The bordered header keeps both tabs visible, while the list body shows the selected run and its current status above the evidence rows. Evidence rows retain stable alternating backgrounds based on their absolute timeline position, including while scrolling: even rows keep the dark overlay background, while odd rows use the neutral `customMessageBg` stripe. The footer exposes the active keys. Messages retain attention markers and unread filtering and open into bounded detail without leaving the overlay. The overlay refreshes while visible and distinguishes true empty timelines from filtered-empty results; filtered-empty copy points back to Enter on the active tab without moving focus.
+The overlay uses most of the available terminal width and height and reduces its content/menu viewport on shorter terminals. The bordered header keeps both tabs visible, while the list body shows the selected run and its current status above the evidence rows. Run, Message, and Turn lists place the newest retained item directly below their control; a newly opened Inspector therefore selects the latest owned run, and ↓ moves backward in time toward older entries. Run options, Messages, and Turns all use compact descending `#N` labels, providing one timestamp-free time axis without repeating type words on every row. Evidence rows retain stable alternating backgrounds based on their absolute timeline position, including while scrolling: even rows keep the dark overlay background, while odd rows use the neutral `customMessageBg` stripe. Unused viewport padding stays on the plain overlay background instead of drawing fake striped rows beneath the last item. The footer exposes the active keys. Messages retain attention markers and unread filtering and open into bounded detail without leaving the overlay. The overlay refreshes while visible and distinguishes true empty timelines from filtered-empty results; filtered-empty copy points back to Enter on the active tab without moving focus.
 
 ## Communication Timeline
 
-The communication timeline reads run-local room, direct, branch-inbox, and coordinator/session message evidence. It preserves channel/sender filters, unread state, attention markers, roster-derived sender options, and bounded body previews. Unread remains filterable but does not consume a row column with a separate dot marker.
+The communication timeline reads run-local room, direct, branch-inbox, and coordinator/session message evidence. Rows display their stable `#N` sequence in newest-first order. It preserves channel/sender filters, unread state, attention markers, roster-derived sender options, and bounded body previews. Unread remains filterable but does not consume a row column with a separate dot marker.
 
 Communication evidence describes messages between actors. It does not prove model execution.
 
@@ -53,19 +54,23 @@ Detached child `pi -p` commands receive isolated session storage under their own
 
 The runner records direct command-template session files in `review-evidence.json`. Coordinator-managed room/swarm participants also persist role/phase-scoped directories under the same `sessions/` root; the inspector discovers those owned files even though the coordinator, rather than the command-template runner, launched them. Explicit caller session policy (`--no-session`, `--session`, `--session-id`, `--session-dir`, or `--fork`) remains authoritative and is not replaced. A command may therefore have no inspector-visible session.
 
-The turns timeline follows the latest persisted entry branch in each recorded Pi session and groups:
+The turns timeline follows the latest persisted entry branch in each recorded Pi session and displays numbered turns newest-first. Each list row begins with compact `#N`, then a humanized `Subagent N` derived from the internal `command-NNN` session owner, followed by an optional parenthesized semantic stage such as `(reviewer)`. The internal command id remains available in evidence detail for provenance but no longer acts as the unexplained primary list label. The visible model column shows only the model id, not its provider. Tool activity appears as a compact parenthesized action summary such as `(read)`, `(read, bash)`, or `(3 tools)`; `(error)` appears only when the turn or a tool result failed.
+
+Each turn groups:
 
 - User input associated with the response;
 - Assistant text and host-persisted thinking blocks;
-- Provider, model, stop reason, usage, and error metadata;
+- Model, stop reason, usage, and error metadata;
 - Tool calls in assistant source order;
 - Tool results correlated by `toolCallId`, regardless of completion order.
 
-Enter opens the selected turn inside the overlay. Detail adds command/stage identity, session and prompt paths, recipe-context reference, tool arguments/results, truncation state, unmatched result counts, and parse diagnostics. ↑/↓ scroll long detail while the footer keeps return/close keys visible.
+Enter/→ opens the selected turn as structured evidence inside the overlay. A compact `Subagent N` heading with an optional meaningful role leads into meaning-first sections: User, persisted Thinking, Assistant, Tools, Execution, and Diagnostics. A final Provenance section retains session/prompt paths, truncation state, and recipe context without making transport metadata the first screen. Generic internal stages such as `command` and `subagent` stay hidden; technical `command-NNN` provenance remains available through the session and prompt paths without producing a redundant `Command / command-NNN (command)` block. Secondary qualifiers use parentheses rather than centered-dot separators. Long text, paths, and structured values wrap to subsequent terminal rows instead of receiving visual ellipsis; lines that already fit the available inner width remain intact, leading indentation is reserved before wrapping long unbroken paths so it cannot become a whitespace-only row, and every section plus all of its explicit or wrapped continuations keeps one background stripe. Blank-only source lines and trailing line breaks are omitted from both evidence and readable rendering. Section boundaries change the stripe without inserting separator rows, so the next heading follows the previous value immediately. ↑/↓ scrolls the resulting visual-row document while the footer remains visible. Source evidence remains bounded by the persisted session reader, but the detail view no longer truncates that retained evidence to one terminal row per field.
+
+Enter/→ once more opens a plain readable transcript of the same turn. This second level removes provenance, model, usage, ids, and other evidence metadata, retaining only User, Thinking when persisted, Assistant, Tool input/result, and Error content in execution order. When Pi persisted the user prompt as one `<file name="…">…</file>` transport wrapper, readable mode removes that wrapper and shows only its actual prompt text. Structured values render as indented key/value text rather than one-line JSON. Escape/← returns from transcript to evidence detail, then from evidence detail to the Turns list.
 
 ## Evidence And Privacy Boundary
 
-The inspector reads file-backed evidence; it does not reconstruct hidden provider reasoning or claim access to data Pi did not persist. When no explicit thinking block exists, detail shows `reasoning unavailable`.
+The inspector reads file-backed evidence; it does not reconstruct hidden provider reasoning or claim access to data Pi did not persist. When no explicit thinking block exists, Execution reports `thinking: not persisted`.
 
 Session text, communication bodies, and structured values remain bounded. Common secret-bearing keys, camelCase/private-key credentials, serialized JSON credentials, and inline credential patterns are redacted before rendering. Malformed JSONL lines, missing parents, cycles, missing sessions, and incomplete tool correlation remain diagnostic states rather than inferred data.
 

package/docs/async-runs.md

@@ -218,7 +218,7 @@ Runtime wake notifications are now modeled separately from durable queues. Messa
 
 The launching coordinator should not busy-poll long-running async runs. The extension watches run state directories and queues terminal `done`/`failed`/unhandled `killed`/`exited` transitions back to the owning session through Pi's `followUp` delivery mode with `triggerTurn: true`; a busy coordinator finishes its current work before queued actor results arrive, while an idle coordinator starts a normal turn without a racy manual idle check. Pi's configured `followUpMode` determines whether concurrently queued results arrive together or one at a time. Script-authored `notify`/`followup` actor messages still follow their declared outbox delivery policy. Terminal notifications include recipe-level named `artifacts` when declared. The generic runner also emits compact `command.done` actor messages for completed leaf commands; recipe authors declare that capability in `mailbox.emits` rather than configuring a separate delivery policy. Failures and in-flight parallel branch completions can bubble according to outbox policy, while successful final leaf completions stay diagnostic to avoid flooding long sequential pipelines. Intentional `control.kill` and recipe-local stop commands stay out of coordinator context because the initiating message already returns synchronously or is handled by actor-local policy. If a notification asks for direction, answer with `message` rather than starting a polling loop. Use explicit `inspect` only when a delivered notification requests inspection, a real decision depends on state, or a suspected stuck run needs diagnosis — never merely because a timeout elapsed.
 
-Ambient status indicators may refresh while work is active, but coordinator attention is driven from run-state changes rather than a coordinator agent loop. This lets the coordinator continue other work after `spawn`; the run signals back through lifecycle state, results, and actor messages. An owned terminal run without `terminal-handled.json` remains retry-eligible during same-runtime and extension/session replacement reconciliation; the marker is written only after successful follow-up delivery, and initial reconciliation does not replay historical outbox traffic. This is an at-least-once contract: a process crash after send but before marker persistence can produce a duplicate notification, while a failed send remains durably retryable. The ambient triangle count represents active async work units: each running async run contributes at least one triangle, and a run with multiple active parallel command/subagent branches contributes the reported active branch count. If a coordinator starts one parent run with four active parallel branches, four triangles are shown; if the same coordinator starts five independent single-branch runs, five triangles are shown.
+Ambient status indicators may refresh while work is active, but coordinator attention is driven from run-state changes rather than a coordinator agent loop. This lets the coordinator continue other work after `spawn`; the run signals back through lifecycle state, results, and actor messages. File-system watchers accelerate live discovery, while a bounded ten-second terminal-only reconciliation pass scans owned unhandled terminal state without reading or replaying outbox traffic. Failed root or run-directory watcher attachment, runtime errors, error-driven watcher removal, and successful rearm remain available as bounded runtime diagnostics; normal run-directory deletion stays quiet; reconciliation rearms degraded watchers but does not depend on them. An owned terminal run without `terminal-handled.json` remains retry-eligible during same-runtime and extension/session replacement reconciliation; the marker is written only after successful follow-up delivery, and initial reconciliation does not replay historical outbox traffic. Watch-triggered and periodic delivery share an in-flight guard so one live runtime sends one follow-up when both paths race. This is an at-least-once contract: a process crash after send but before marker persistence can produce a duplicate notification, while a failed send remains durably retryable. The ambient triangle count represents active async work units: each running async run contributes at least one triangle, and a run with multiple active parallel command/subagent branches contributes the reported active branch count. If a coordinator starts one parent run with four active parallel branches, four triangles are shown; if the same coordinator starts five independent single-branch runs, five triangles are shown.
 
 ## Run Actor Messages
 

package/index.ts

@@ -21,8 +21,10 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
   let runsAnimationInterval: NodeJS.Timeout | undefined;
   let runsNotifyTimeout: NodeJS.Timeout | undefined;
   let activeRunContext: Pi.ExtensionContext | undefined;
+  let lastRunWatcherDiagnosticId = 0;
   const runUi = Observability.createRunUiObservationState();
   const retirementAttempts = new Set<string>();
+  const terminalNotificationsInFlight = new Set<string>();
   const getRunOwnerId = Pi.getSessionId;
   const retireCandidateRuns = (
     ctx: Pi.ExtensionContext,
@@ -53,6 +55,7 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     Observability.deliverRunTransitionNotifications(
       snapshot.transitions,
       notificationSink,
+      terminalNotificationsInFlight,
     );
     Observability.pruneRunUiObservationState(runUi, snapshot);
     if (!terminalOnly) {
@@ -64,22 +67,56 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
   };
   const closeRunWatchers = (): void => {
     runWatcher.close();
+    terminalReconciliation.close();
     if (runsNotifyTimeout) clearTimeout(runsNotifyTimeout);
     runsNotifyTimeout = undefined;
   };
-  const scheduleRunEventUpdate = (ctx: Pi.ExtensionContext): void => {
+  const reportRunWatcherDiagnostics = (ctx: Pi.ExtensionContext): void => {
+    for (const diagnostic of runWatcher.getDiagnostics()) {
+      if (diagnostic.id <= lastRunWatcherDiagnosticId) continue;
+      lastRunWatcherDiagnosticId = diagnostic.id;
+      ctx.ui.notify(
+        diagnostic.message,
+        diagnostic.code === "rearmed" ? "info" : "warning",
+      );
+    }
+  };
+  const scheduleRunEventUpdate = (): void => {
     if (runsNotifyTimeout) clearTimeout(runsNotifyTimeout);
     runsNotifyTimeout = setTimeout(() => {
+      const ctx = activeRunContext;
+      if (!ctx) return;
       runWatcher.refresh();
       updateRunUi(ctx, true);
+      reportRunWatcherDiagnostics(ctx);
     }, 50);
     runsNotifyTimeout.unref?.();
   };
   const runWatcher = Observability.createRunStateWatcher({
     stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
-    onChange: () =>
-      activeRunContext && scheduleRunEventUpdate(activeRunContext),
+    onChange: scheduleRunEventUpdate,
   });
+  const terminalReconciliation =
+    Observability.createRunTerminalReconciliationLoop({
+      onError: (error) => {
+        const ctx = activeRunContext;
+        if (!ctx) return;
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(`Actor terminal reconciliation failed: ${message}`, "error");
+      },
+      reconcile: () => {
+        const ctx = activeRunContext;
+        if (!ctx) return;
+        Observability.reconcileRunTerminalNotifications({
+          inFlight: terminalNotificationsInFlight,
+          ownerId: getRunOwnerId(ctx),
+          sink: Pi.createNotificationSink(pi, ctx),
+          state: runUi,
+        });
+        reportRunWatcherDiagnostics(ctx);
+      },
+      refreshWatcher: () => runWatcher.refresh(),
+    });
   const actorToolDefinitions = new Map<string, Tools.ActorToolDefinition>();
   const withCurrentThinkingContext = <T extends Tools.ActorToolDefinition>(
     definition: T,
@@ -127,15 +164,19 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     // Clear the pre-overlay widget after hot reloads from older pi-actors builds.
     ctx.ui.setWidget("zz-pi-actors-comms", undefined);
     activeRunContext = ctx;
+    closeRunWatchers();
+    recipeReload.close();
     await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
+    if (activeRunContext !== ctx) return;
     runtime.loadTools(ctx);
     updateRunUi(ctx, true, true);
-    closeRunWatchers();
-    recipeReload.close();
     runWatcher.refresh();
+    terminalReconciliation.start();
     recipeReload.watch(ctx);
     if (runsAnimationInterval) clearInterval(runsAnimationInterval);
-    runsAnimationInterval = setInterval(() => updateRunUi(ctx, false), 1000);
+    runsAnimationInterval = setInterval(() => {
+      if (activeRunContext === ctx) updateRunUi(ctx, false);
+    }, 1000);
     runsAnimationInterval.unref?.();
   });
   pi.on("session_shutdown", async () => {
@@ -145,8 +186,8 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     closeRunWatchers();
     recipeReload.close();
   });
-  pi.registerCommand("actors-inspector-toggle", {
-    description: "Toggle the keyboard-driven actor inspector overlay",
+  pi.registerCommand("actors-inspector", {
+    description: "Open the keyboard-driven actor inspector overlay",
     handler: async (_args, ctx) => {
       ctx.ui.setWidget("zz-pi-actors-comms", undefined);
       await ctx.ui.custom<void>(