@llblab/pi-actors 0.40.0 → 0.41.0

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.
@@ -107,8 +107,8 @@ 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 steering notifications, coordinator-bound outbox messages, branch-aware triangles, process-tree expansion, and bounded body previews. Terminal delivery is at-least-once across the unavoidable send/handled-marker crash window.
-- When a deferred actor result gates the next step, wait for its terminal steering notification. 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.
+- 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.
+- 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.
 
 ## Recipes And Registry

package/BACKLOG.md

@@ -39,7 +39,28 @@ Non-goals:
 
 ## Open Work
 
-No active implementation or release-preparation work remains. The `0.40.0` release candidate is validated locally; commit, tag, merge, publish, and release actions remain operator-gated rather than backlog work.
+### Manual draft-memory consolidation
+
+- [ ] Add a manually invoked command that launches an agent-led consolidation cycle over `~/.pi/agent/recipes/drafts`. The cycle must inventory and classify every draft, propose a complete `promote`, `merge`, or `discard` plan, require explicit operator confirmation before mutations, normalize approved reusable capabilities into active recipe-backed tools under `~/.pi/agent/recipes`, and remove every handled source so the drafts directory finishes empty. It must never run automatically or promote tools silently; preserve evidence for each decision and add regressions for plan-only, confirmation, promotion, merge, discard, failure recovery, and empty-directory completion.
+
+### Overlay actor inspector
+
+- [ ] Replace the command-driven inspector workflow with one large keyboard-driven overlay while preserving the compact striped information design. Stop conditions: `/actors-inspector-toggle` only toggles the overlay; an operator can select an owned run and subagent, switch `Messages` / `Turns` tabs, navigate rows, open/close detail, scroll bounded content, and understand keys/current scope without entering subcommands.
+  - [x] Close the dogfood security prerequisites: reset selection across Pi sessions, revalidate ownership before every selected-run read, contain session evidence beneath the owned run state, broaden structured/text redaction, and add regressions.
+  - [x] Build the centered responsive overlay shell with bordered header/footer, tabs, owned-run/subagent selector, active-scope summary, empty/loading/error states, and Escape close.
+  - [x] Move compact striped Messages rows, filters, unread filtering/attention markers, roster context, and row detail into keyboard navigation.
+  - [x] Move Turns rows and full bounded provenance/tool detail into keyboard navigation with scrolling and explicit persisted/unavailable reasoning labels.
+  - [x] Remove the subcommand grammar and below-editor widget lifecycle, retain only the toggle command, and document discoverable key hints plus responsive behavior.
+  - [ ] Run full package, conformance, and context validation, then close this item. Component input/render/width/scroll/tab/ownership/live-refresh regressions and iterative manual TUI dogfood now cover the accepted visual interaction contract.
+
+### Inspector execution observability
+
+- [x] Consolidate the actor inspector into one manually opened, navigable operator surface for communication and execution evidence. Stop conditions: an operator can choose an owned run/subagent, switch between communication and turn timelines, open one bounded detail view, and inspect every persisted user/assistant/tool-result turn in source order without exposing another session or claiming unavailable hidden reasoning.
+  - [x] Persist deterministic Pi session provenance for each child `pi -p` command under its owned run state, without overriding an explicitly supplied session policy; record the session path in command evidence and tolerate commands that never create a session.
+  - [x] Add a resilient, bounded session-evidence reader that follows the active JSONL entry branch, groups assistant responses with correlated tool calls/results into turns, preserves model/usage/error metadata, redacts sensitive argument/content fields, and reports malformed or incomplete evidence honestly.
+  - [x] Replace communication-specific inspector controller state with a shared navigation model: run selector → `communication` or `turns` timeline → numbered detail, with stable back/toggle/filter behavior and useful empty states for actors that never send messages.
+  - [x] Render compact turn rows and bounded manual detail views for effective prompt/context references, assistant text, host-exposed thinking blocks, tool arguments/results, model/usage, and source-file provenance; label missing reasoning as unavailable rather than inferred.
+  - [x] Add ownership, truncation, redaction, malformed JSONL, active-branch ordering, tool correlation, parallel tool completion, terminal run, coordinator-launched subagent, and communication-navigation regressions; update the Actors skill and inspector documentation after the interaction contract stabilizes.
 
 ## Backlog Curation Rules
 

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## Unreleased
 
+## 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.
+- `[Agent Autonomy]` Clarified in the injected prompt and bundled Actors skill that command-template strings execute directly without shell evaluation, so `&&`, pipes, redirects, and `cd` do not provide shell composition. Strengthened both skill descriptions and added explicit Swarm activation for multiple parallel actors, independent artifact generation, implementation fanout, and review; the coordinator now receives a compact preflight contract for disjoint scopes, stable run ids, artifacts, launch correctness, integration, and final validation. Impact: agents avoid malformed launches such as `cd <dir> && pi ...` and autonomously load the right orchestration guidance before multi-actor work.
+- `[CI Stability]` Wait for the detached runner process to exit before removing the large-review-evidence fixture directory, and wait for the terminal evidence manifest instead of racing its final write. Impact: Linux CI cleanup no longer intermittently fails with `ENOTEMPTY` after the assertions pass.
+
 ## 0.40.0: Durable Review and Runtime Hardening
 
 - `[Runtime]` Collapsed every natural-language positional fragment in child `pi -p` launches into one inspectable prompt file while preserving Pi options and intentional `@file` attachments, so review stages receive one authoritative user turn and preflight diagnostics resolve the concrete stage.

package/README.md

@@ -65,7 +65,7 @@ Use actors instead of ad hoc shell backgrounding when work is long-running, stat
 Start an actor:
 
 ```text
-spawn template="sleep 30 && echo done" as=run:demo
+spawn template="sleep 30" as=run:demo
 ```
 
 Inspect it when you need evidence:
@@ -125,13 +125,13 @@ Routing comes from `to`, actor ownership, and runtime policy. `type` describes i
 | --- | --- | --- |
 | Command templates | Portable command graphs with placeholders, defaults, guards, retries, parallel nodes, recovery, and timeouts | Wrap a trusted local executable without writing a bespoke tool |
 | Recipes | JSON/Markdown capability specs with metadata, args, defaults, imports, mailbox contracts, artifacts, and async mode | Save a known-good local workflow as reusable muscle memory |
-| Async runs | File-backed detached lifecycle, logs, progress, output, cancellation, artifacts, and durable terminal steering notifications | Let model work, media jobs, services, or pipelines continue after the turn |
+| Async runs | File-backed detached lifecycle, logs, progress, output, cancellation, artifacts, and durable terminal follow-up notifications | Let model work, media jobs, services, or pipelines continue after the turn |
 | Message protocol | Typed envelopes across run, tool, branch, room, coordinator, and session targets | Continue, approve, kill, or route work without restarting actors |
 | Rooms and rosters | Run-local group timeline with actor join/leave, contacts, previews, and branch-aware delivery | Coordinate multiple subagents under one visible run |
 | 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
@@ -275,7 +275,7 @@ Packaged recipes are building blocks. Use `spawn file=<recipe>` for maintained p
 | A useful output that should survive context compression | Artifacts |
 | A repeated local workflow | Recipe/tool memory |
 
-When a directly spawned inline/ad hoc actor or a recipe outside the user recipe root completes successfully, `pi-actors` may include a promotion suggestion in its terminal steering notification. The agent should ask first and never auto-save.
+When a directly spawned inline/ad hoc actor or a recipe outside the user recipe root completes successfully, `pi-actors` may include a promotion suggestion in its terminal follow-up notification. The agent should ask first and never auto-save.
 
 ## Platform support
 
@@ -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,13 @@ 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;
     const runUi = Observability.createRunUiObservationState();
     const retirementAttempts = new Set();
-    const actorInspector = Inspector.createActorInspectorControllerState();
     const getRunOwnerId = Pi.getSessionId;
     const retireCandidateRuns = (ctx, summary) => {
         void Observability.executeRunRetirements(summary, {
@@ -34,28 +34,6 @@ 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);
@@ -92,7 +70,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 +79,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,6 +108,8 @@ 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;
         await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
         runtime.loadTools(ctx);
@@ -147,31 +132,25 @@ export default function toolRegistryExtension(pi) {
         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);
+        description: "Toggle 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,84 @@
+/**
+ * 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 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 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 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 closeDetail;
+    private border;
+    private stripeBackground;
+    private stripedRow;
+    private row;
+    private takeVisiblePrefix;
+    private dropVisiblePrefix;
+    private fit;
+}