@llblab/pi-actors 0.40.1 → 0.41.0

package/dist/lib/tools-response.js

@@ -5,6 +5,37 @@
  */
 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 spaceToolResult(result) {
+    if (!result || typeof result !== "object")
+        return result;
+    const content = result.content;
+    if (!Array.isArray(content))
+        return result;
+    return {
+        ...result,
+        content: content.map((item) => item &&
+            typeof item === "object" &&
+            item.type === "text" &&
+            typeof item.text === "string"
+            ? {
+                ...item,
+                text: withLeadingBlankLine(item.text),
+            }
+            : item),
+    };
+}
+export function spaceToolError(error) {
+    if (error instanceof Error) {
+        error.message = withLeadingBlankLine(error.message);
+        return error;
+    }
+    return new Error(withLeadingBlankLine(String(error)));
+}
 export function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value

package/dist/scripts/async-runner.mjs

@@ -13,6 +13,7 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  readdirSync,
   statSync,
 } from "node:fs";
 import { dirname, join, relative } from "node:path";
@@ -31,8 +32,11 @@ async function importRuntimeModule(name) {
   );
 }
 
-const { appendRecipeContextToPiArgs, materializePiPrintPromptArg } =
-  await importRuntimeModule("recipes-context");
+const {
+  appendRecipeContextToPiArgs,
+  attachPiSessionDir,
+  materializePiPrintPromptArg,
+} = await importRuntimeModule("recipes-context");
 const { buildReviewPreflightDiagnostic, formatReviewPreflightDiagnostic } =
   await importRuntimeModule("preflight-diagnostics");
 const { execCommandTemplate } = await importRuntimeModule("command-templates");
@@ -126,11 +130,24 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
     });
   }
 
+  function commandSessionFiles(sessionDir) {
+    if (!sessionDir) return [];
+    try {
+      return readdirSync(sessionDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+        .map((entry) => relative(stateDir, join(sessionDir, entry.name)))
+        .sort();
+    } catch {
+      return [];
+    }
+  }
+
   function commandEvidenceStartRecord({
     commandDetail,
     commandId,
     materialized,
     options,
+    sessionDir,
     stage,
     occurrence,
   }) {
@@ -155,6 +172,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...(materialized.promptBytes
         ? { prompt_bytes: materialized.promptBytes }
         : {}),
+      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir) } : {}),
       attempts: [],
       semantic_acceptance:
         options?.evidenceContext?.acceptOutput === "review_evidence" ||
@@ -172,6 +190,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
     options,
     result,
     rawExitCode,
+    sessionDir,
     stage,
     occurrence,
     startedAt,
@@ -234,6 +253,10 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...(materialized.promptBytes
         ? { prompt_bytes: materialized.promptBytes }
         : {}),
+      ...(sessionDir ? { session_dir: relative(stateDir, sessionDir) } : {}),
+      ...(commandSessionFiles(sessionDir).length > 0
+        ? { session_files: commandSessionFiles(sessionDir) }
+        : {}),
       attempts,
       exit_code: rawExitCode ?? result.code,
       effective_exit_code: result.code,
@@ -301,21 +324,26 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
   }
 
   async function observedExec(command, args, options) {
+    captureCounter += 1;
+    const commandId = `command-${String(captureCounter).padStart(3, "0")}`;
     const contextArgs = appendRecipeContextToPiArgs(
       command,
       args,
       meta.recipe_context_records,
       options?.actorRecipeContext,
     );
-    const materialized = materializePiPrintPromptArg(
+    const session = attachPiSessionDir(
       command,
       contextArgs,
+      join(stateDir, "sessions", commandId),
+    );
+    const materialized = materializePiPrintPromptArg(
+      command,
+      session.args,
       promptFilePath,
     );
     const execArgs = materialized.args;
     const commandDetail = formatCommandDetail(command, execArgs);
-    captureCounter += 1;
-    const commandId = `command-${String(captureCounter).padStart(3, "0")}`;
     const stage =
       options?.actorRecipeContext?.alias ||
       options?.actorRecipeContext?.name ||
@@ -346,6 +374,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       commandId,
       materialized,
       options,
+      sessionDir: session.sessionDir,
       stage,
       occurrence,
     });
@@ -357,6 +386,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       command: commandDetail,
       ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
       ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
+      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir) } : {}),
     });
     progressRunning();
     const captureDir = join(stateDir, "captures", commandId);
@@ -400,6 +430,7 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       options,
       result,
       rawExitCode: rawResult.code,
+      sessionDir: session.sessionDir,
       stage,
       occurrence,
       startedAt: startedEvidence.started_at,
@@ -426,6 +457,10 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...captureDetails(result),
       ...(materialized.promptFile ? { prompt_file: materialized.promptFile } : {}),
       ...(materialized.promptBytes ? { prompt_bytes: materialized.promptBytes } : {}),
+      ...(session.sessionDir ? { session_dir: relative(stateDir, session.sessionDir) } : {}),
+      ...(commandSessionFiles(session.sessionDir).length > 0
+        ? { session_files: commandSessionFiles(session.sessionDir) }
+        : {}),
       ...(preflightDiagnostic ? { preflight: preflightDiagnostic } : {}),
     });
     outbox(

package/dist/scripts/coordinator.mjs

@@ -238,14 +238,24 @@ function terminateProcessGroup(child, signal) {
   }
 }
 
-function runPi(prompt, model, thinking, ttlMs = 0) {
+function sessionKey(value) {
+  return String(value).replaceAll(/[^A-Za-z0-9_.-]+/g, "-");
+}
+
+function runPi(prompt, model, thinking, ttlMs = 0, sessionDir, ownerSessionId) {
   return new Promise((resolve) => {
     const args = [
       "--tools",
       "inspect,message",
       "--no-context-files",
       "--no-skills",
-      "--no-session",
+      ...(sessionDir
+        ? [
+            "--session-dir",
+            sessionDir,
+            ...(ownerSessionId ? ["--session-id", ownerSessionId] : []),
+          ]
+        : ["--no-session"]),
     ];
     if (model) {
       args.push("--model", model);
@@ -346,7 +356,14 @@ async function synthesize(config, locker) {
   }
   const transcript = await readRoomTranscript(config);
   const prompt = `Synthesize this transcript into a concise Markdown artifact. Mission: ${config.mission}. Include: Title, Consensus, Roles, Protocol, Final Artifact Shape, Next Actions, Open Questions. Use only the transcript evidence below.\n\nTRANSCRIPT:\n${transcript.slice(-24000)}`;
-  const result = await runPi(prompt, config.model, config.thinking, config.subagentTtlMs);
+  const result = await runPi(
+    prompt,
+    config.model,
+    config.thinking,
+    config.subagentTtlMs,
+    `${runStateDir(config.runId)}/sessions/coordinator-synthesis`,
+    config.ownerSessionId,
+  );
   const output = result.stdout.trim();
   const diagnostics = config.stats
     ? `\n\n## Diagnostics\n\nparticipant_attempts=${config.stats.participantAttempts}\nparticipant_success=${config.stats.participantSuccess}\nparticipant_failures=${config.stats.participantFailures}\nsynthesis_code=${result.code}\ntranscript_messages=${transcript.trim() ? transcript.split("\n").length : 0}\n`
@@ -443,7 +460,7 @@ async function updateInboxMessagesStatus(runId, branchName, ids, status) {
   });
 }
 
-async function executeParticipantPrompt(role, basePrompt, config) {
+async function executeParticipantPrompt(role, basePrompt, config, phase) {
   const branchName = role.name;
   const queuedMessages = await claimQueuedInboxMessages(
     config.runId,
@@ -469,7 +486,14 @@ async function executeParticipantPrompt(role, basePrompt, config) {
     finalPrompt += inboxSection;
   }
 
-  const result = await runPi(finalPrompt, config.model, config.thinking, config.subagentTtlMs);
+  const result = await runPi(
+    finalPrompt,
+    config.model,
+    config.thinking,
+    config.subagentTtlMs,
+    `${runStateDir(config.runId)}/sessions/${sessionKey(`${role.name}-${phase}`)}`,
+    config.ownerSessionId,
+  );
 
   if (claimedIds.length > 0) {
     const finalStatus = result.code === 0 ? "handled" : "failed";
@@ -488,7 +512,7 @@ async function participantRound(role, round, config) {
   const displayName = role.name;
   const address = `branch:${config.runId}/${role.name}`;
   const prompt = `You are ${displayName} (${address}), ${role.persona}. Mission: ${config.mission}. Round ${round}/${config.rounds}. First call inspect target=${config.room} view=previews lines=30 and inspect target=${config.room} view=contacts. Then call message once to ${config.room} from ${address} type=chat.message. Body: 2-4 sentences that react to a named participant, propose the next coordination step, and refine the shared artifact. Use contacts for peer names and addresses. End stdout with summary <=160 chars.`;
-  const result = await executeParticipantPrompt(role, prompt, config);
+  const result = await executeParticipantPrompt(role, prompt, config, `round-${round}`);
   if (config.stats) {
     config.stats.participantAttempts += 1;
     if (result.code === 0) config.stats.participantSuccess += 1;
@@ -506,14 +530,28 @@ async function participantJoin(role, config) {
   const displayName = role.name;
   const address = `branch:${config.runId}/${role.name}`;
   const joinPrompt = `You are ${displayName}, ${role.persona}. Mission: ${config.mission}. Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.join', summary='${displayName} joined', body JSON {"role":${JSON.stringify(role.persona)},"display":${JSON.stringify(displayName)},"caps":["coordination","synthesis"],"claim":"coordinate on mission"}. Then print one short line.`;
-  await runPi(joinPrompt, config.model, config.thinking, config.subagentTtlMs);
+  await runPi(
+    joinPrompt,
+    config.model,
+    config.thinking,
+    config.subagentTtlMs,
+    `${runStateDir(config.runId)}/sessions/${sessionKey(`${role.name}-join`)}`,
+    config.ownerSessionId,
+  );
 }
 
 async function participantLeave(role, config) {
   const displayName = role.name;
   const address = `branch:${config.runId}/${role.name}`;
   const leavePrompt = `Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.leave', summary='${displayName} left', body='finished coordinated work'. Then print goodbye.`;
-  await runPi(leavePrompt, config.model, config.thinking, config.subagentTtlMs);
+  await runPi(
+    leavePrompt,
+    config.model,
+    config.thinking,
+    config.subagentTtlMs,
+    `${runStateDir(config.runId)}/sessions/${sessionKey(`${role.name}-leave`)}`,
+    config.ownerSessionId,
+  );
 }
 
 // 1. consensus / swarm mode: iterative chat in a room
@@ -601,7 +639,12 @@ async function runPool(config, locker) {
 
         const taskId = assignedTask.task;
         const prompt = `You are ${role.name}, ${role.persona}. You have been assigned task ${taskId}: "${assignedTask.task}". Solve it as part of the overall mission: ${config.mission}. End your response with a clear summary.`;
-        const result = await executeParticipantPrompt(role, prompt, config);
+        const result = await executeParticipantPrompt(
+          role,
+          prompt,
+          config,
+          `task-${taskId}`,
+        );
 
         process.stdout.write(
           `[${role.name} completed ${taskId}] code=${result.code}\n${result.stdout}\n`,
@@ -711,6 +754,9 @@ if (!config.model) {
   process.exit(2);
 }
 config.room = `room:${config.runId}`;
+config.ownerSessionId = String(
+  (await readJsonFile(`${runStateDir(config.runId)}/run.json`)).ownerId ?? "",
+);
 
 const failures = [];
 const locker = await startLocker(config);

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.40.1
+  version: 0.41.0
 ---
 
 # Actors (pi-actors)
@@ -125,13 +125,9 @@ 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 commands:
+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.
 
-- `/actors-inspector-toggle [rows]`: open/close the compact table or set row count; default is 12 log rows when no size is supplied.
-- `/actors-inspector-filter all|room|direct|broadcast|unread|branch <name>|current-branch <name>|mention <text>`: narrow table previews without changing room/run state.
-- `/actors-inspect <number>`: open one visible row as a full-message view.
-
-The table is compact and optimistic by default: bounded body previews, capped noisy room rows, branch-local inbox previews, stable event ids in selected-message details, and an inline roster summary in the form `name/role` that wraps only when needed. Use `unread` for queued branch inbox work and `branch <name>` / `current-branch <name>` for one branch's room/direct/inbox traffic. Rows with `metadata.requires_response=true` show a `!` attention marker. `/actors-inspect <number>` marks that row read for the current session filter. Active roster members use the target color; members that sent `actor.leave` stay visible as inactive/muted participants from the current run. Actor display names come from `actor.join` bodies (`display`) or branch addresses, keeping debugger output plain and name-driven.
+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.
 
@@ -166,6 +162,8 @@ Controls:
 - `repeat`: repeated node expansion.
 - `output`: output behavior selection.
 - Command stdout/stderr use bounded tails plus complete spill files; tool/run diagnostics expose byte counts, truncation, and spill paths, while pipelines fail with `incomplete pipeline stdin` rather than consuming a partial tail.
+- Detached child `pi -p` commands receive isolated session storage under `sessions/command-NNN` in their owned run state, and command evidence records any resulting JSONL files. Coordinator-managed room/swarm participants use role/phase-scoped directories under the same run-local `sessions/` root so their turns remain discoverable too. Explicit `--no-session`, `--session`, `--session-id`, `--session-dir`, or `--fork` policy remains caller-owned and is never replaced.
+- Persisted child-session inspection follows the latest JSONL entry branch, correlates tool results by call id, bounds previews, and redacts common secret-bearing fields/text. Thinking content is evidence only when Pi persisted an explicit `thinking` block; never infer or advertise hidden reasoning.
 
 Placeholders:
 

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.40.1
+  version: 0.41.0
 ---
 
 # Swarm

package/docs/README.md

@@ -9,6 +9,7 @@ Living index of all documentation in the `/docs` directory.
 - [template-recipes.md](./template-recipes.md) — Saved JSON/Markdown recipe standard, imports, and reusable command-template graph composition
 - [async-runs.md](./async-runs.md) — Detached run lifecycle, state files, actor messages, cancellation, and ambient indicators
 - [actor-messages.md](./actor-messages.md) — Actor/message protocol for symmetric communication primitives
+- [actor-inspector.md](./actor-inspector.md) — Manual owned-run navigation across communication and persisted subagent turns
 - [tool-registry.md](./tool-registry.md) — Local `pi-actors` registry storage and `register_tool` adaptation
 - [recipe-library.md](./recipe-library.md) — Packaged standard recipe library such as async subagents, coordinator pipelines, utilities, and music playback
 - [task-first-recipes.md](./task-first-recipes.md) — Task-first design map for deriving high-level recipes and missing component cells

package/docs/actor-inspector.md

@@ -0,0 +1,72 @@
+# Actor Inspector
+
+The actor inspector is a manually opened, read-only TUI navigator for owned actor runs. It keeps communication evidence and persisted subagent execution evidence in one hierarchy without merging their meanings.
+
+```text
+owned run
+  → messages | turns
+    → filtered timeline
+      → bounded detail
+```
+
+## 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.
+
+The overlay exposes an explicit focus hierarchy:
+
+```text
+Run       Enter opens owned 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
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+## 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.
+
+Communication evidence describes messages between actors. It does not prove model execution.
+
+## Turns Timeline
+
+Detached child `pi -p` commands receive isolated session storage under their owned run state:
+
+```text
+<run-state>/sessions/command-NNN/*.jsonl
+```
+
+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:
+
+- User input associated with the response;
+- Assistant text and host-persisted thinking blocks;
+- Provider, 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.
+
+## 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`.
+
+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.
+
+Ownership filtering happens before run summaries, communication previews, roster data, or session evidence become visible. Selection and read state reset across Pi sessions. Manifest session paths must resolve canonically beneath the selected owned run's `sessions/` directory; absolute paths, traversal, and symlink escapes remain invisible. The inspector never scans another coordinator session's run state into the current view.

package/index.ts

@@ -7,7 +7,7 @@
 
 import * as AsyncRuns from "./lib/async-runs.ts";
 import * as CommandTemplates from "./lib/command-templates.ts";
-import * as Inspector from "./lib/inspector.ts";
+import * as InspectorOverlay from "./lib/inspector-overlay.ts";
 import * as Observability from "./lib/observability.ts";
 import * as Paths from "./lib/paths.ts";
 import * as Pi from "./lib/pi.ts";
@@ -15,6 +15,7 @@ import * as Prompts from "./lib/prompts.ts";
 import * as Runtime from "./lib/runtime.ts";
 import * as Temp from "./lib/temp.ts";
 import * as Tools from "./lib/tools.ts";
+import * as ToolsResponse from "./lib/tools-response.ts";
 
 export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
   let runsAnimationInterval: NodeJS.Timeout | undefined;
@@ -22,7 +23,6 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
   let activeRunContext: Pi.ExtensionContext | undefined;
   const runUi = Observability.createRunUiObservationState();
   const retirementAttempts = new Set<string>();
-  const actorInspector = Inspector.createActorInspectorControllerState();
   const getRunOwnerId = Pi.getSessionId;
   const retireCandidateRuns = (
     ctx: Pi.ExtensionContext,
@@ -47,33 +47,6 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
       "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: number) {
-              return Inspector.renderActorInspectorPanel({
-                stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
-                state: actorInspector,
-                ownerId,
-                width,
-                style: {
-                  actor: (text: string) => ctx.ui.theme.fg("accent", text),
-                  muted: (text: string) => ctx.ui.theme.fg("dim", text),
-                  preview: (text: string) => ctx.ui.theme.fg("text", text),
-                  stripe: (text: string) => text,
-                  stripeAlt: (text: string) =>
-                    ctx.ui.theme.bg("customMessageBg", text),
-                  target: (text: string) => ctx.ui.theme.fg("success", text),
-                  type: (text: string) => ctx.ui.theme.fg("warning", text),
-                },
-              });
-            },
-          })
-        : undefined,
-      { placement: "belowEditor" },
-    );
     if (!notify) return;
     const notificationSink = Pi.createNotificationSink(pi, ctx);
     retireCandidateRuns(ctx, snapshot.summary);
@@ -115,7 +88,7 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     const execute = definition.execute as (...args: unknown[]) => unknown;
     return {
       ...definition,
-      execute: (...args: unknown[]) => {
+      execute: async (...args: unknown[]) => {
         const nextArgs = [...args];
         const ctx = nextArgs[4];
         if (ctx && typeof ctx === "object") {
@@ -124,7 +97,11 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
             getThinkingLevel: () => pi.getThinkingLevel(),
           };
         }
-        return execute(...nextArgs);
+        try {
+          return ToolsResponse.spaceToolResult(await execute(...nextArgs));
+        } catch (error) {
+          throw ToolsResponse.spaceToolError(error);
+        }
       },
     } as T;
   };
@@ -147,6 +124,8 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     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);
@@ -167,39 +146,29 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     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,
+    description: "Toggle the keyboard-driven actor inspector overlay",
+    handler: async (_args, ctx) => {
+      ctx.ui.setWidget("zz-pi-actors-comms", undefined);
+      await ctx.ui.custom<void>(
+        (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,
+          },
+        },
       );
-      if (result.update) updateRunUi(ctx);
-      ctx.ui.notify(result.notify, result.type);
     },
   });
   pi.on("before_agent_start", async (event) => ({