@llblab/pi-actors 0.40.1 → 0.41.1

package/AGENTS.md

@@ -43,7 +43,7 @@ Pi host
   - `recipes-references.ts`, `recipes-discovery.ts`, `recipes-usage.ts`: recipe graph, discovery, and usage metadata.
   - `async-runs.ts`: detached run lifecycle facade; `runs-*` subdomains own artifacts, start guards, status, indexes, inbox/outbox, delivery, process control, and retention internals.
   - `runtime-notifier.ts`, `mailbox-loop.ts`: wake notifications and reusable run/branch mailbox worker loops.
-  - `messages.ts`, `rooms.ts`, `recipes-context.ts`, `inspector.ts`, `observability.ts`: addressed message protocol, rooms, recipe prompt context, communication previews, and ambient run status.
+  - `messages.ts`, `rooms.ts`, `recipes-context.ts`, `session-evidence.ts`, `inspector.ts`, `inspector-overlay.ts`, `observability.ts`: addressed message protocol, rooms, recipe prompt context, bounded/redacted child-session turns, inspector evidence/navigation, keyboard-driven overlay UI, and ambient run status.
   - `prompts.ts`, `temp.ts`: LLM-facing copy and temp cleanup.
   - `tools.ts`: public tool family composition and reserved tool names.
   - `tools-message.ts`: public `message` tool behavior, including run controls, branch/room routing, tool actor invocation, and delivery feedback.
@@ -70,7 +70,7 @@ Pi host
 
 - Prefer explicit operator action over silent user-config rewrites.
 - Keep published documentation portable: use `~`, `<repo>`, or relative paths instead of machine-local absolute paths.
-- Preserve runtime output discipline because tool output flows directly into agent context.
+- Preserve runtime output discipline because tool output flows directly into agent context. Tool result/error text contributes exactly one leading line break; Pi's renderer contributes the other break after the call header, producing one empty separator row without doubled gaps.
 - Optimize every actor-facing surface for signal over volume: prefer compact state-backed hints and fewer concepts over broad explanatory prose or speculative guidance.
 - Split broad domains proactively when the current name becomes a generic bucket. Prefer concise domain names that match actual ownership. `tools.ts` is the public tool family owner; decomposed tool subdomains use `tools-<part>.ts` (`tools-message.ts`, `tools-inspect.ts`, `tools-spawn.ts`) under that family. Keep only genuinely cross-family domains unprefixed (`schema.ts`); tool-only helpers stay under `tools-*`. If a `tools-*` helper becomes reused by non-tools domains, remove the `tools-` prefix in the same slice and update ownership comments/imports so the name matches its broader responsibility. Avoid redundant internal `actor-` file prefixes in this actor-scoped package unless the file is deliberately tied to a public actor-named recipe/script/docs surface.
 - Until a stable release greater than `1.x.x`, favor context compression over compatibility shims: do not preserve legacy actor-facing names, aliases, fields, env vars, paths, or docs solely for backward compatibility when a clearer current term exists. Remove compatibility layers in the same slice that renames a concept, and record the break in `CHANGELOG.md`.
@@ -107,7 +107,7 @@ Pi host
 - Preserve node controls: `when`, positive `timeout`, `delay`, bounded `retry`, `failure`, and `recover` cleanup.
 - Persist every async command's complete byte-exact stdout/stderr under command- and retry-specific run-state paths while keeping returned tails bounded and pipeline stdin complete.
 - Keep async run state under `~/.pi/agent/tmp/pi-actors/runs` with injected `{run_id}` and `{state_dir}` values.
-- Preserve event-driven observability: durable retrying terminal follow-up notifications, coordinator-bound outbox messages, branch-aware triangles, process-tree expansion, and bounded body previews. Queue coordinator context through Pi follow-up delivery rather than steering so current work finishes before async results arrive and host follow-up batching policy can combine concurrent completions. Terminal delivery is at-least-once across the unavoidable send/handled-marker crash window.
+- Preserve event-driven observability with bounded reconciliation: file watchers accelerate durable retrying terminal follow-up notifications, while a conservative terminal-only interval recovers missed watcher activity, rearms degraded watchers, and never replays outbox traffic. Queue coordinator context through Pi follow-up delivery rather than steering so current work finishes before async results arrive and host follow-up batching policy can combine concurrent completions. Terminal delivery is at-least-once across the unavoidable send/handled-marker crash window; watch-triggered and periodic delivery share one live-runtime in-flight guard.
 - When a deferred actor result gates the next step, wait for its terminal follow-up. Do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs; inspect early only on operator request, meaningful actor event, or diagnosis of an overdue/stuck run.
 - Do not restore busy-polling examples, duplicate terminal notifications, or duplicate notifications for handled `cancel`, `kill`, or control-stop actions.
 

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## Unreleased
 
+## 0.41.1: Actor Inspector and Delivery Hotfix
+
+- `Terminal Delivery`: Added bounded ten-second terminal reconciliation and watcher rearm so owned terminal follow-ups converge without reload when file watching misses or fails. Delivery still uses Pi follow-ups with owner filtering, `triggerTurn`, no historical outbox replay, and the existing at-least-once handled-marker contract; routine run-directory removal stays quiet while real watcher degradation remains diagnostic.
+- `Actor Inspector`: Finished the 0.41 overlay line around a compact meaning-first workflow. `/actors-inspector` now opens the latest numbered Run; Run, Message, and Turn lists show newest evidence first; bounded menus remain usable on short terminals; and humanized Turn rows lead into wrapped Evidence and a metadata-free readable transcript. Turn content now prioritizes User, Thinking, Assistant, and tool actions before Execution and Provenance, strips prompt transport wrappers in readable mode, keeps logical sections on one stripe, and removes false wraps, clipped values, redundant labels/separators, and blank rows.
+- `Tool Output`: Normalized successful results and errors to contribute exactly one leading line break, preserving one empty separator row beneath Pi's rendered tool-call header without occasional double gaps.
+- `Agent Guidance`: Kept Inspector behavior in user documentation and removed it from the bundled Actors skill, leaving that skill focused on agent-operational `spawn`, `message`, `inspect`, recipes, and lifecycle guidance.
+
+## 0.41.0: Actor Inspector Overlay and Execution Observability
+
+- `[Inspector Menu Alignment]` Shifted value submenus one cell left so adjacent levels share a border, aligned Run and tab labels to one vertical grid, and made the Run dropdown begin immediately below Run by overlaying the tab row. Impact: nested menus read as one connected hierarchy and every top-level control follows the same anchored dropdown rhythm.
+- `[Inspector UX Polish]` Applied the shared focus treatment (`▶`, accent text, neutral background) to timeline rows, exposed non-default filters as compact tab-label suffixes, gave run lifecycle status semantic text color, and split true-empty from filtered-empty guidance. Impact: focus no longer changes visual language between controls and data, hidden filter state stays visible, and empty results explain whether data or the current query is absent.
+- `[Inspector Detail Navigation]` Made Enter/→ open a focused timeline row and Escape/← return from detail; horizontal arrows no longer switch tabs from list focus. Updated contextual footer hints accordingly. Impact: nested list/detail navigation follows the same forward/backward key model as menus, while tab switching remains scoped to tab focus.
+- `[Inspector Message Sender Filter]` Added `From: <actor>` to the Messages filter menu, populated from the selected run's roster, with `all` as the default. Impact: operators can isolate communication emitted by one actor while seeing the current sender scope before opening its values.
+- `[Inspector Nested Menu Context]` Added current values to parent filter items (`Channel: value`, `State: value`, `Subagent: value`) and made unused corners between differently sized parent/value menus transparent to the striped timeline beneath. Impact: operators see filter state before opening alternatives, and nested overlays occlude only useful menu cells.
+- `[Inspector Run And Filter Menus]` Added a top-level owned-run selector with live status, removed run metadata from timeline rows, and moved filters behind Enter on each tab. Filter parameters now open a second value submenu to the right while preserving the parent menu and one-level Escape navigation. Impact: run context stays explicit, the permanent filter row disappears, and Messages/Turns gain compact graphical two-level settings menus.
+- `[Inspector Selection Markers]` Use stable blue brackets for selected Run/tab controls and reserve `▶` for focused menus, values, and timeline rows. Added a direct regression that verifies even timeline rows stay on the dark overlay surface while odd rows receive the neutral stripe background. Impact: selection and focus remain distinct without layout shifts or color-only meaning.
+- `[Inspector List Navigation]` Restored stable even/odd striping by absolute timeline position, made Enter/→ open row detail, and made Escape/← return to the list, with contextual footer hints. Impact: row grouping remains visually stable while scrolling and horizontal navigation follows the same forward/back model as nested menus.
+- `[Inspector Visual Contract]` Stabilized the dogfooded interaction model around top-bounded tabs, availability-aware filter/list navigation, blue current values, neutral focus backgrounds, key-colored footer hints, and filter-anchored nested option overlays that preserve underlying separator and timeline cells outside their rectangle. Impact: the TUI now behaves like a compact graphical tab/filter/select surface instead of a command panel.
+- `[Inspector Naming]` Renamed the `Communications` tab to `Messages`. Impact: the tab now describes its concrete contents with a shorter label that balances visually with `Turns`.
+- `[Inspector Filter UI]` Removed the permanent filter bar in favor of compact tab-anchored parameter/value menus that show current values, preserve the striped timeline beneath unused cells, and expose active non-default filters in the tab label. Impact: filtering stays visible and keyboard-driven without consuming a permanent content row.
+- `[Inspector Turns UI]` Moved turn browsing and detail into the overlay with scrolling viewports, all/single-subagent scope, compact model/tool-count rows, and Enter-opened bounded provenance, prompt/context, user/assistant, persisted-thinking, usage/error, tool argument/result, truncation, and diagnostic evidence. Impact: operators can follow one subagent's complete persisted execution path without commands or leaving the overlay.
+- `[Inspector Messages UI]` Moved message browsing into the overlay with compact striped routes/types/body previews, attention markers, unread/channel/sender filters, roster-derived From options, and bounded detail. Impact: actor communication investigation stays keyboard-driven and discoverable without consuming a row for unread dots or command grammar.
+- `[Inspector Focus Navigation]` Added explicit Run/Tabs/Menu/List/Detail focus zones with availability-aware boundaries, blue selected values, brackets for top-level selection, triangles for focused rows, and contextual key hints. Impact: navigation always has one visible owner and moving focus never mutates filter state.
+- `[Inspector Overlay Integrity]` Normalized persisted tabs and line breaks before every component row is handed to the overlay compositor. Impact: multiline actor messages, prompts, and turn text can no longer escape their assigned row and corrupt the underlying terminal layout during tab navigation.
+- `[Inspector Overlay]` Replaced inspector subcommand handling with `/actors-inspector-toggle`, which opens a centered responsive overlay featuring Run selection, Messages/Turns tabs, nested filters, compact alternating rows, live refresh, distinct empty states, bounded detail, footer key hints, and Escape close. Removed the superseded command controller and below-editor widget lifecycle. Impact: operators can browse execution evidence without memorizing command grammar, and runtime state now has one authoritative UI path.
+- `[Inspector Security]` Reset inspector selection/read state at every Pi session start, revalidate selected-run ownership before turn or roster reads, reject absolute/traversing/symlinked session evidence outside the owned run, and broaden structured/text plus communication-body redaction for common camelCase/private-key credentials. Impact: the upcoming overlay cannot inherit another session's selected evidence or escape its run boundary through mutable manifests.
+- `[Coordinator Turn Provenance]` Replaced coordinator-managed room/swarm subagents' `--no-session` launches with isolated role/phase session directories under the owned run and made the inspector discover those JSONL files alongside command evidence. Impact: manual turn navigation covers coordinator-spawned participants and synthesis actors, not only direct recipe `pi -p` leaves.
+- `[Inspector Turn Detail]` Added bounded manual turn detail for command/stage identity, session and prompt provenance, recipe context, user/assistant text, persisted thinking, stop reason, usage, errors, correlated tool arguments/results, unmatched results, truncation, and parse diagnostics. Impact: operators can inspect what each subagent actually received, produced, and called while missing reasoning stays explicitly unavailable and secret-bearing values remain redacted.
+- `[Turn Evidence]` Added a resilient bounded reader for persisted child Pi sessions that follows the latest JSONL entry branch, groups assistant responses with correlated tool calls/results, retains model/usage/error and host-visible thinking metadata, redacts common secret-bearing fields/text, and diagnoses malformed or incomplete evidence. Impact: inspector navigation can consume one tested turn model instead of parsing raw session files or implying access to unavailable reasoning.
+- `[Execution Observability]` Give every child `pi -p` command an isolated session directory under its owned run state unless the recipe already supplies explicit session policy, and record any resulting JSONL files in command events and review evidence. Impact: the inspector can attribute future turn/tool timelines to exact subagent commands without guessing from global session directories, while `--no-session`, resume, fork, and caller-owned session storage remain authoritative.
+- `[Tool Output]` Separate every pi-actors tool result and thrown error from its rendered tool-call header with one blank line, including core `spawn`, `message`, `inspect`, `register_tool`, and recipe-backed tools. Impact: successful and failed calls remain visually scannable instead of running into the header.
+
 ## 0.40.1: Follow-up Delivery Hotfix
 
 - `[Coordinator Delivery]` Queue terminal and coordinator-bound actor notifications through Pi's `followUp` delivery mode instead of `steer`, while retaining `triggerTurn: true` for idle sessions. Impact: active coordinators finish their current work before actor results arrive, and Pi can apply its configured follow-up batching policy to concurrently completed runs instead of injecting each result between tool calls.

package/README.md

@@ -131,7 +131,7 @@ Routing comes from `to`, actor ownership, and runtime policy. `type` describes i
 | Registry and recipe doctor | Discovered tools, overrides, drafts, invalid recipes, and advisory risk labels | Audit local capability memory before using or promoting it |
 | Draft promotion | Captured ad hoc spawn patterns can become explicit recipes after operator approval | Turn successful improvisation into durable local tools |
 | Review/swarm recipes | Maintained packaged pipelines with preflight, marked semantic evidence, quorum knobs, model/thinking inheritance, one-turn prompt-file transport, and diagnostics | Delegate reviews without rebuilding fanout commands |
-| Actor inspector | Compact TUI/debug views for active actor coordination, unread branch inboxes, room messages, and attention markers | Watch only the actor traffic that matters right now |
+| Actor inspector | One manual `Messages or Turns → filtered timeline → detail` overlay for owned actor messages and persisted subagent sessions, with bounded/redacted prompt, model, thinking, tool, result, usage, and provenance evidence | Follow actor traffic and every persisted subagent turn without exposing another session or inventing hidden reasoning |
 | Packaged recipe QA | Installed-package-safe checks for helper paths, mailbox contracts, platform scope, artifacts, and recipe structure | Keep shipped actor components executable and diagnosable |
 
 ## Golden path: from local workflow to actor memory
@@ -340,6 +340,7 @@ Core docs:
 - [Template recipes](./docs/template-recipes.md)
 - [Async runs](./docs/async-runs.md)
 - [Actor messages](./docs/actor-messages.md)
+- [Actor inspector](./docs/actor-inspector.md)
 - [Tool registry](./docs/tool-registry.md)
 - [Recipe library](./docs/recipe-library.md)
 

package/dist/index.js

@@ -6,7 +6,7 @@
  */
 import * as AsyncRuns from "./lib/async-runs.js";
 import * as CommandTemplates from "./lib/command-templates.js";
-import * as Inspector from "./lib/inspector.js";
+import * as InspectorOverlay from "./lib/inspector-overlay.js";
 import * as Observability from "./lib/observability.js";
 import * as Paths from "./lib/paths.js";
 import * as Pi from "./lib/pi.js";
@@ -14,13 +14,15 @@ import * as Prompts from "./lib/prompts.js";
 import * as Runtime from "./lib/runtime.js";
 import * as Temp from "./lib/temp.js";
 import * as Tools from "./lib/tools.js";
+import * as ToolsResponse from "./lib/tools-response.js";
 export default function toolRegistryExtension(pi) {
     let runsAnimationInterval;
     let runsNotifyTimeout;
     let activeRunContext;
+    let lastRunWatcherDiagnosticId = 0;
     const runUi = Observability.createRunUiObservationState();
     const retirementAttempts = new Set();
-    const actorInspector = Inspector.createActorInspectorControllerState();
+    const terminalNotificationsInFlight = new Set();
     const getRunOwnerId = Pi.getSessionId;
     const retireCandidateRuns = (ctx, summary) => {
         void Observability.executeRunRetirements(summary, {
@@ -34,33 +36,11 @@ export default function toolRegistryExtension(pi) {
         const ownerId = getRunOwnerId(ctx);
         const snapshot = Observability.readRunUiSnapshot(runUi, ownerId);
         ctx.ui.setStatus("zz-pi-actors-runs", snapshot.status ? ctx.ui.theme.fg("dim", snapshot.status) : undefined);
-        ctx.ui.setWidget("zz-pi-actors-comms", actorInspector.visible
-            ? () => ({
-                invalidate() { },
-                render(width) {
-                    return Inspector.renderActorInspectorPanel({
-                        stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
-                        state: actorInspector,
-                        ownerId,
-                        width,
-                        style: {
-                            actor: (text) => ctx.ui.theme.fg("accent", text),
-                            muted: (text) => ctx.ui.theme.fg("dim", text),
-                            preview: (text) => ctx.ui.theme.fg("text", text),
-                            stripe: (text) => text,
-                            stripeAlt: (text) => ctx.ui.theme.bg("customMessageBg", text),
-                            target: (text) => ctx.ui.theme.fg("success", text),
-                            type: (text) => ctx.ui.theme.fg("warning", text),
-                        },
-                    });
-                },
-            })
-            : undefined, { placement: "belowEditor" });
         if (!notify)
             return;
         const notificationSink = Pi.createNotificationSink(pi, ctx);
         retireCandidateRuns(ctx, snapshot.summary);
-        Observability.deliverRunTransitionNotifications(snapshot.transitions, notificationSink);
+        Observability.deliverRunTransitionNotifications(snapshot.transitions, notificationSink, terminalNotificationsInFlight);
         Observability.pruneRunUiObservationState(runUi, snapshot);
         if (!terminalOnly) {
             Observability.deliverRunOutboxNotifications(snapshot.outboxEvents, notificationSink);
@@ -68,22 +48,57 @@ export default function toolRegistryExtension(pi) {
     };
     const closeRunWatchers = () => {
         runWatcher.close();
+        terminalReconciliation.close();
         if (runsNotifyTimeout)
             clearTimeout(runsNotifyTimeout);
         runsNotifyTimeout = undefined;
     };
-    const scheduleRunEventUpdate = (ctx) => {
+    const reportRunWatcherDiagnostics = (ctx) => {
+        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 = () => {
         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();
     const withCurrentThinkingContext = (definition) => {
@@ -92,7 +107,7 @@ export default function toolRegistryExtension(pi) {
         const execute = definition.execute;
         return {
             ...definition,
-            execute: (...args) => {
+            execute: async (...args) => {
                 const nextArgs = [...args];
                 const ctx = nextArgs[4];
                 if (ctx && typeof ctx === "object") {
@@ -101,7 +116,12 @@ export default function toolRegistryExtension(pi) {
                         getThinkingLevel: () => pi.getThinkingLevel(),
                     };
                 }
-                return execute(...nextArgs);
+                try {
+                    return ToolsResponse.spaceToolResult(await execute(...nextArgs));
+                }
+                catch (error) {
+                    throw ToolsResponse.spaceToolError(error);
+                }
             },
         };
     };
@@ -125,17 +145,25 @@ export default function toolRegistryExtension(pi) {
         return { skillPaths };
     });
     pi.on("session_start", async (_event, ctx) => {
+        // 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 () => {
@@ -146,32 +174,26 @@ export default function toolRegistryExtension(pi) {
         closeRunWatchers();
         recipeReload.close();
     });
-    pi.registerCommand("actors-inspector-toggle", {
-        description: Inspector.ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS.toggle,
-        handler: async (args, ctx) => {
-            const result = Inspector.handleActorInspectorToggle(actorInspector, args);
-            if (result.update)
-                updateRunUi(ctx);
-            ctx.ui.notify(result.notify, result.type);
-        },
-    });
-    pi.registerCommand("actors-inspector-filter", {
-        description: Inspector.ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS.filter,
-        handler: async (args, ctx) => {
-            const result = Inspector.handleActorInspectorFilter(actorInspector, args);
-            if (result.update)
-                updateRunUi(ctx);
-            ctx.ui.notify(result.notify, result.type);
-        },
-    });
-    pi.registerCommand("actors-inspect", {
-        description: Inspector.ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS.inspect,
-        handler: async (args, ctx) => {
-            const previews = Inspector.readActorInspectorPreviews(Paths.EXTENSION_RUNTIME_PATHS.runStateRoot, actorInspector.rows, Inspector.getActorInspectorPreviewOptions(actorInspector, getRunOwnerId(ctx)));
-            const result = Inspector.handleActorInspectorInspect(actorInspector, args, previews);
-            if (result.update)
-                updateRunUi(ctx);
-            ctx.ui.notify(result.notify, result.type);
+    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((tui, theme, _keybindings, done) => new InspectorOverlay.ActorInspectorOverlay({
+                done,
+                ownerId: getRunOwnerId(ctx),
+                stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
+                theme,
+                tui,
+            }), {
+                overlay: true,
+                overlayOptions: {
+                    anchor: "center",
+                    width: "94%",
+                    minWidth: 72,
+                    maxHeight: "94%",
+                    margin: 1,
+                },
+            });
         },
     });
     pi.on("before_agent_start", async (event) => ({

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

@@ -0,0 +1,95 @@
+/**
+ * Keyboard-driven actor inspector overlay.
+ * Zones: overlay shell, tabs, owned-run/subagent selection, compact striped rows
+ * Owns interactive TUI navigation; evidence parsing remains in inspector/session domains.
+ */
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type TUI } from "@earendil-works/pi-tui";
+export type ActorInspectorOverlayTab = "communications" | "turns";
+export interface ActorInspectorOverlayOptions {
+    done: () => void;
+    ownerId: string;
+    stateRoot: string;
+    theme: Theme;
+    tui: TUI;
+}
+export declare class ActorInspectorOverlay {
+    private readonly done;
+    private readonly ownerId;
+    private readonly stateRoot;
+    private readonly theme;
+    private readonly tui;
+    private readonly refreshTimer;
+    private runIndex;
+    private communicationChannel;
+    private communicationFrom;
+    private communicationUnread;
+    private contentStripeIndices;
+    private detailCommunication?;
+    private detailOpen;
+    private detailScroll;
+    private detailTurn?;
+    private detailView;
+    private readonly readKeys;
+    private focus;
+    private filterControlIndex;
+    private menuLevel;
+    private selectorIndex;
+    private rowIndex;
+    private selectedRun?;
+    private subagentIndex;
+    private tab;
+    constructor(options: ActorInspectorOverlayOptions);
+    handleInput(data: string): void;
+    render(width: number): string[];
+    invalidate(): void;
+    dispose(): void;
+    private runs;
+    private ensureSelectedRun;
+    private contentViewportRows;
+    private selectRun;
+    private cycleRun;
+    private listItemCount;
+    private selectorAnchor;
+    private renderKeyHints;
+    private renderRunControl;
+    private activeMessageFilters;
+    private renderTabs;
+    private renderRunSelector;
+    private renderTimeline;
+    private communicationPreviews;
+    private communicationActorLabel;
+    private communicationFromOptions;
+    private communicationRows;
+    private renderDetail;
+    private wrapDetailLines;
+    private detailSection;
+    private readableValueLines;
+    private turnEvidenceLines;
+    private readablePromptText;
+    private turnTranscriptLines;
+    private turnItems;
+    private turnRows;
+    private subagents;
+    private valueOptions;
+    private filterOptions;
+    private menuOptions;
+    private backMenu;
+    private openRunMenu;
+    private openFilterMenu;
+    private applyMenuOption;
+    private filterValue;
+    private currentFilterValue;
+    private renderMenuBox;
+    private renderFilterMenus;
+    private openDetail;
+    private backDetail;
+    private closeDetail;
+    private border;
+    private stripeBackground;
+    private stripedRow;
+    private row;
+    private takeVisiblePrefix;
+    private dropVisiblePrefix;
+    private fit;
+}