@llblab/pi-actors 0.26.2 → 0.27.0

package/BACKLOG.md

@@ -225,12 +225,35 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
   - Packaged recipes declare `stop`/`cancel` only when the actor-specific behavior is meaningful.
   - Tests assert that generic mailbox-loop termination is not triggered by `control.stop` or `control.cancel`.
 
+### M-12 Runtime and Session Observability UX
+
+- Priority: High.
+- Status: Planned.
+- Goal: Make reload/session/runtime mismatches visible without changing ownership or lifecycle policy.
+- Why now: 0.26 dogfood showed that actors, mailbox workers, and hotfixes work after a full Pi restart, but ordinary reloads can leave operators unsure which extension code is live. Session ownership mismatches also surface as terse strings instead of structured diagnostics or navigation hints.
+- Direction:
+  - Add an intentional runtime/version inspection surface that reports loaded package version, entrypoint path, source/dist mode, package root, recipe roots, and git commit when available.
+  - Make session ownership denials structured in tool details with compact `reason=session_mismatch owner_session=... current_session=...` text and hints to inspect the owning session.
+  - Make coordinator/session status show when other sessions or other-session runs exist so `runs=0` is not misleading after reload or resume.
+  - Document reload vs full restart verification in the actors/swarm guidance.
+  - Opportunistically improve invalid shadowing recipe launch hints only if it stays diagnostic-only.
+- Non-goals:
+  - No cross-session force kill.
+  - No session attach/adopt/reparent policy.
+  - No relaxation of current ownership gates.
+- Acceptance:
+  - Operators can verify the loaded pi-actors version/path from an inspect/tool surface after reload.
+  - Session mismatch responses carry structured details and a compact human hint.
+  - Coordinator/session status exposes other-session counts without leaking unrelated run details by default.
+  - Tests cover version inspection, session mismatch shape, and other-session count summaries.
+
 ## Explicitly Deferred
 
 These are valid ideas but not current focus. Reintroduce only with concrete evidence from real actor workflows.
 
 - Spawn preflight mode: useful later, but lower value than resilient inspect and mailbox-loop consolidation.
 - Run restart/reattach policy: risky for isolation; defer until corruption recovery and protocol fixtures are stronger.
+- Cross-session force kill or attach/adopt/reparent: useful later, but ownership policy should not change until observability makes current boundaries clear.
 - Actor address helper CLI: keep diagnostics improving opportunistically inside existing parser/tests.
 - Documentation refactor: defer until the canonical mailbox loop and worker recipe exist; avoid rewriting docs twice.
 - Host-level tool unregistration: blocked on host API support.
@@ -240,5 +263,5 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 ## Suggested Milestone Order
 
 ```text
-Next milestone: choose from deferred items only after concrete actor workflow evidence appears.
+Next milestone: M-12 Runtime and Session Observability UX.
 ```

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+- `[Inspect]` Added `inspect target=tool:pi-actors view=status` as a runtime verification surface with loaded version, package root, source/dist mode, entrypoint path, recipe roots, and git commit when available.
+- `[Sessions]` Started structured session mismatch diagnostics with `reason=session_mismatch`, owner/current session fields, and compact inspect-session hints while preserving current ownership gates.
+- `[Sessions]` Added other-session run counts to coordinator/session status summaries so reload/resume states do not misleadingly report only `runs=0` without nearby context.
+
+## 0.26.3: Branch Message Delivery UX Hotfix
+
+- `[Actor Messages]` Treat branch mailbox persistence as a successful queued outcome even when the parent run control endpoint is unavailable, returning compact `queued=true` delivery diagnostics instead of throwing an unframed tool error.
+- `[UX]` Preserve the compact action-output contract for branch `message` calls by keeping delivery diagnostics in the normal result formatter, including the leading blank-line separation used by other tool actions.
+
 ## 0.26.2: Terminal Progress Hotfix
 
 - `[Async Runs]` Keep `progress.json` aligned with terminal kill/cancel handling by writing `phase=killed` or `phase=cancelled` and clearing active subagent counts when a run is stopped by runtime control.

package/dist/lib/tools.js

@@ -3,6 +3,9 @@
  * Zones: pi tools, registry tools, async run launchers
  * Owns generated runtime tool schemas and the register_tool management tool schema
  */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import * as ActorMessages from "./actor-messages.js";
 import * as ActorRooms from "./actor-rooms.js";
 import * as AsyncRuns from "./async-runs.js";
@@ -345,10 +348,21 @@ function compactActorFiles(status) {
         : "";
     return `\nrun=${run}${artifactText}${files.length ? ` files=${files.join(",")}` : ""}`;
 }
-function compactSessionRuns(session, runs) {
+function summarizeOtherSessions(currentSession, allRuns) {
+    const otherRuns = allRuns.filter((run) => run.ownerId && run.ownerId !== currentSession);
+    return {
+        other_runs: otherRuns.length,
+        other_sessions: new Set(otherRuns.map((run) => run.ownerId)).size,
+    };
+}
+function compactSessionRuns(session, runs, summary = {}) {
+    const suffix = [
+        summary.other_sessions !== undefined ? `other_sessions=${String(summary.other_sessions)}` : "",
+        summary.other_runs !== undefined ? `other_runs=${String(summary.other_runs)}` : "",
+    ].filter(Boolean).join(" ");
     if (runs.length === 0)
-        return `\nsession=${session} runs=0`;
-    return `\nsession=${session} runs=${runs.length}\n${runs
+        return `\nsession=${session} runs=0${suffix ? ` ${suffix}` : ""}`;
+    return `\nsession=${session} runs=${runs.length}${suffix ? ` ${suffix}` : ""}\n${runs
         .map((run) => {
         const tokens = [
             `run=${String(run.run ?? "")}`,
@@ -362,6 +376,38 @@ function compactSessionRuns(session, runs) {
     })
         .join("\n")}`;
 }
+function getPiActorsRuntimeStatus() {
+    const packagedRecipeRoot = Paths.getPackagedRecipeRoot();
+    const packageRoot = dirname(packagedRecipeRoot);
+    const packageJsonPath = join(packageRoot, "package.json");
+    const packageJson = existsSync(packageJsonPath)
+        ? JSON.parse(readFileSync(packageJsonPath, "utf8"))
+        : {};
+    let git_commit;
+    try {
+        git_commit = execFileSync("git", ["-C", packageRoot, "rev-parse", "--short", "HEAD"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        git_commit = undefined;
+    }
+    const entrypoint = new URL(import.meta.url).pathname;
+    return {
+        entrypoint,
+        git_commit,
+        mode: entrypoint.includes("/dist/") ? "dist" : "source",
+        package_name: packageJson.name ?? "@llblab/pi-actors",
+        package_root: packageRoot,
+        recipe_root: Paths.getRecipeRoot(),
+        packaged_recipe_root: packagedRecipeRoot,
+        version: packageJson.version ?? "unknown",
+    };
+}
+function compactPiActorsRuntimeStatus(status) {
+    return `\npi-actors version=${String(status.version)} mode=${String(status.mode)} path=${String(status.package_root)} entrypoint=${String(status.entrypoint)}${status.git_commit ? ` git=${String(status.git_commit)}` : ""}`;
+}
 function compactToolActor(name, tool) {
     const parameters = asRecord(tool.parameters);
     const required = Array.isArray(parameters.required)
@@ -441,6 +487,8 @@ function compactActorMessageResult(message, result) {
     ];
     if (result.bytes !== undefined)
         tokens.push(`bytes=${String(result.bytes)}`);
+    if (result.queued === true)
+        tokens.push("queued=true");
     if (result.control)
         tokens.push(`control=${String(result.control)}`);
     if (result.outbox)
@@ -459,6 +507,9 @@ function compactActorMessageResult(message, result) {
         tokens.push(`signal=${String(result.signal)}`);
     if (result.invoked === true)
         tokens.push("invoked=true");
+    if (result.delivery_error) {
+        tokens.push(`delivery_error=${compactPreview(result.delivery_error, 96)}`);
+    }
     return `\n${tokens.join(" ")}`;
 }
 function maybeJsonText(value, verbose, compact) {
@@ -543,7 +594,25 @@ function assertMessageSenderBelongsToRun(message, run, routeLabel) {
 async function routeBranchEnvelope(stateDir, runId, recipient, message, _options) {
     const branchMessage = { ...message, to: recipient };
     ActorRooms.appendBranchInboxMessage(stateDir, runId, recipient, branchMessage);
-    return AsyncRuns.sendRunMessage(runId, JSON.stringify(branchMessage));
+    try {
+        return await AsyncRuns.sendRunMessage(runId, JSON.stringify(branchMessage));
+    }
+    catch (error) {
+        const record = error && typeof error === "object" ? error : {};
+        if (record.queued === true) {
+            return {
+                control_path: record.control_path,
+                control_type: record.control_type,
+                delivery_error: record.delivery_error ?? (error instanceof Error ? error.message : String(error)),
+                inbox_id: record.inbox_id,
+                queued: true,
+                run: runId,
+                sent: false,
+                state_dir: stateDir,
+            };
+        }
+        throw error;
+    }
 }
 function getRoomMulticastRecipients(message, run) {
     const raw = message.metadata?.recipients;
@@ -637,7 +706,13 @@ function assertRunAccessibleToContext(runId, ctx) {
     const status = AsyncRuns.getRunStatus(runId);
     const sessionId = getContextSessionId(ctx);
     if (sessionId && status.ownerId && status.ownerId !== sessionId) {
-        throw new Error(`run:${runId} is owned by session:${status.ownerId}; current session is ${sessionId}.`);
+        throw Object.assign(new Error(`run:${runId} reason=session_mismatch owner_session=${status.ownerId} current_session=${sessionId} hint=inspect_session:${status.ownerId}`), {
+            current_session: sessionId,
+            hint: `inspect target=session:${status.ownerId} view=status`,
+            owner_session: status.ownerId,
+            reason: "session_mismatch",
+            run: runId,
+        });
     }
     return status;
 }
@@ -693,37 +768,54 @@ export function createInspectToolDefinition(deps = {}) {
                     throw new Error("inspect coordinator supports view=status or view=runs.");
                 }
                 const session = requireContextSessionId(ctx, "inspect coordinator");
-                const runs = AsyncRuns.listRuns(undefined, typeof input.status === "string" ? input.status : undefined)
-                    .map((run) => AsyncRuns.getRunStatus(String(run.state_dir)))
-                    .filter((run) => run.ownerId === session);
+                const allRuns = AsyncRuns.listRuns(undefined, typeof input.status === "string" ? input.status : undefined).map((run) => AsyncRuns.getRunStatus(String(run.state_dir)));
+                const runs = allRuns.filter((run) => run.ownerId === session);
+                const sessionSummary = summarizeOtherSessions(session, allRuns);
                 return {
                     content: [
                         {
                             type: "text",
-                            text: maybeJsonText({ session, runs }, input.verbose === true, compactSessionRuns(session, runs)),
+                            text: maybeJsonText({ session, runs, ...sessionSummary }, input.verbose === true, compactSessionRuns(session, runs, sessionSummary)),
                         },
                     ],
-                    details: { session, runs },
+                    details: { session, runs, ...sessionSummary },
                 };
             }
             if (address.kind === "session") {
                 if (view !== "status" && view !== "runs") {
                     throw new Error("inspect session:<id> supports view=status or view=runs.");
                 }
-                const runs = AsyncRuns.listRuns(undefined, typeof input.status === "string" ? input.status : undefined)
-                    .map((run) => AsyncRuns.getRunStatus(String(run.state_dir)))
-                    .filter((run) => address.value === "all" || run.ownerId === address.value);
+                const allRuns = AsyncRuns.listRuns(undefined, typeof input.status === "string" ? input.status : undefined).map((run) => AsyncRuns.getRunStatus(String(run.state_dir)));
+                const runs = allRuns.filter((run) => address.value === "all" || run.ownerId === address.value);
+                const sessionSummary = address.value === "all"
+                    ? {}
+                    : summarizeOtherSessions(address.value || "", allRuns);
                 return {
                     content: [
                         {
                             type: "text",
-                            text: maybeJsonText({ session: address.value, runs }, input.verbose === true, compactSessionRuns(address.value || "", runs)),
+                            text: maybeJsonText({ session: address.value, runs, ...sessionSummary }, input.verbose === true, compactSessionRuns(address.value || "", runs, sessionSummary)),
                         },
                     ],
-                    details: { session: address.value, runs },
+                    details: { session: address.value, runs, ...sessionSummary },
                 };
             }
             if (address.kind === "tool" && address.value) {
+                if (address.value === "pi-actors") {
+                    if (view !== "status") {
+                        throw new Error("inspect tool:pi-actors supports view=status.");
+                    }
+                    const details = getPiActorsRuntimeStatus();
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: maybeJsonText(details, input.verbose === true, compactPiActorsRuntimeStatus(details)),
+                            },
+                        ],
+                        details,
+                    };
+                }
                 if (view !== "status" && view !== "schema") {
                     throw new Error("inspect tool:<name> supports view=status or view=schema.");
                 }

package/dist/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.26.2
+  version: 0.27.0
 ---
 
 # Actors (pi-actors)
@@ -41,7 +41,7 @@ Trusted local capability
 - **Recipe**: saved JSON definition wrapping a template with args, defaults, imports, mailbox, artifacts, metadata, and optional `async: true`.
 - **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, communication snapshot, and artifacts.
 - **Room actor**: shared timeline + roster endpoint addressable as `room:<run>`; every spawned run gets `room:<run>`.
-- **Tool actor**: registered persistent capability addressable as `tool:<name>` and callable through the generated tool or `message`.
+- **Tool actor**: registered persistent capability addressable as `tool:<name>` and callable through the generated tool or `message`. `tool:pi-actors` is reserved for runtime/status inspection.
 - **Coordinator/session**: the current pi session endpoint that receives bounded actor follow-ups.
 - **Mailbox**: public interaction contract: message types the actor accepts/emits.
 - **Artifact**: named durable output path declared by a recipe/run.
@@ -102,6 +102,7 @@ Check `inspect view=mailbox` before domain-specific messages.
 { "target": "room:repo-health", "view": "roster" }
 { "target": "room:repo-health", "view": "contacts" }
 { "target": "room:repo-health", "view": "previews" }
+{ "target": "tool:pi-actors", "view": "status" }
 { "target": "tool:music_player", "view": "status" }
 { "target": "recipes", "view": "status" }
 { "target": "coordinator", "view": "status" }

package/dist/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent orchestration with scoped locks and quorum consensus. Use for multi-model review, parallel scoped work, delegated audit, and coordinated subagent execution.
 metadata:
-  version: 0.26.2
+  version: 0.27.0
 ---
 
 # Swarm

package/docs/tool-registry.md

@@ -19,15 +19,18 @@ Because the user recipe directory is sticky agent muscle memory, runtime launche
 
 `register_tool` is the preferred agent-facing mutation API. It creates, updates, and deletes recipe files in `~/.pi/agent/recipes`; agents do not need to edit the files directly for normal registration. Direct file edits are still valid for operators and advanced agents. Runtime behavior is reactive: file creation, deletion, or edits in the user recipe root trigger validation and tool-set refresh, with invalid recipes surfaced as diagnostics rather than silently ignored.
 
-Inspect the discovered registry with:
+Inspect the loaded pi-actors runtime and discovered registry with:
 
 ```text
+inspect target=tool:pi-actors view=status
 inspect target=recipes view=status
 inspect target=recipes view=doctor
 inspect target=recipes view=summary verbose=true
 ```
 
-The summary reports active, shadowed, invalid, disabled, and diagnostic entries so operators can answer why a tool is present, hidden, broken, or disabled. The doctor view keeps the same registry evidence but promotes an advisory action surface: compact output includes the highest-priority `top` remediation plus ordered actions for invalid/blocking, disabled, risky shell-boundary, and shadowed recipes. Verbose inspection keeps the structured `remediations`, `top_action`, diagnostic details, and blocked lower-priority candidate paths when a broken or disabled higher-priority recipe masks a fallback.
+`tool:pi-actors` is a reserved runtime-status actor: it reports the loaded package version, package root, source/dist mode, entrypoint path, recipe roots, and git commit when available. Use it after reloads to confirm which extension code is actually live.
+
+The recipe summary reports active, shadowed, invalid, disabled, and diagnostic entries so operators can answer why a tool is present, hidden, broken, or disabled. The doctor view keeps the same registry evidence but promotes an advisory action surface: compact output includes the highest-priority `top` remediation plus ordered actions for invalid/blocking, disabled, risky shell-boundary, and shadowed recipes. Verbose inspection keeps the structured `remediations`, `top_action`, diagnostic details, and blocked lower-priority candidate paths when a broken or disabled higher-priority recipe masks a fallback.
 
 ## Registering Tools
 

package/lib/tools.ts

@@ -4,6 +4,10 @@
  * Owns generated runtime tool schemas and the register_tool management tool schema
  */
 
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
 import * as ActorMessages from "./actor-messages.ts";
 import * as ActorRooms from "./actor-rooms.ts";
 import * as AsyncRuns from "./async-runs.ts";
@@ -424,12 +428,30 @@ function compactActorFiles(status: Record<string, unknown>): string {
   return `\nrun=${run}${artifactText}${files.length ? ` files=${files.join(",")}` : ""}`;
 }
 
+function summarizeOtherSessions(
+  currentSession: string,
+  allRuns: Array<Record<string, unknown>>,
+): Record<string, unknown> {
+  const otherRuns = allRuns.filter(
+    (run) => run.ownerId && run.ownerId !== currentSession,
+  );
+  return {
+    other_runs: otherRuns.length,
+    other_sessions: new Set(otherRuns.map((run) => run.ownerId)).size,
+  };
+}
+
 function compactSessionRuns(
   session: string,
   runs: Array<Record<string, unknown>>,
+  summary: Record<string, unknown> = {},
 ): string {
-  if (runs.length === 0) return `\nsession=${session} runs=0`;
-  return `\nsession=${session} runs=${runs.length}\n${runs
+  const suffix = [
+    summary.other_sessions !== undefined ? `other_sessions=${String(summary.other_sessions)}` : "",
+    summary.other_runs !== undefined ? `other_runs=${String(summary.other_runs)}` : "",
+  ].filter(Boolean).join(" ");
+  if (runs.length === 0) return `\nsession=${session} runs=0${suffix ? ` ${suffix}` : ""}`;
+  return `\nsession=${session} runs=${runs.length}${suffix ? ` ${suffix}` : ""}\n${runs
     .map((run) => {
       const tokens = [
         `run=${String(run.run ?? "")}`,
@@ -443,6 +465,39 @@ function compactSessionRuns(
     .join("\n")}`;
 }
 
+function getPiActorsRuntimeStatus(): Record<string, unknown> {
+  const packagedRecipeRoot = Paths.getPackagedRecipeRoot();
+  const packageRoot = dirname(packagedRecipeRoot);
+  const packageJsonPath = join(packageRoot, "package.json");
+  const packageJson = existsSync(packageJsonPath)
+    ? JSON.parse(readFileSync(packageJsonPath, "utf8")) as Record<string, unknown>
+    : {};
+  let git_commit: string | undefined;
+  try {
+    git_commit = execFileSync("git", ["-C", packageRoot, "rev-parse", "--short", "HEAD"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    git_commit = undefined;
+  }
+  const entrypoint = new URL(import.meta.url).pathname;
+  return {
+    entrypoint,
+    git_commit,
+    mode: entrypoint.includes("/dist/") ? "dist" : "source",
+    package_name: packageJson.name ?? "@llblab/pi-actors",
+    package_root: packageRoot,
+    recipe_root: Paths.getRecipeRoot(),
+    packaged_recipe_root: packagedRecipeRoot,
+    version: packageJson.version ?? "unknown",
+  };
+}
+
+function compactPiActorsRuntimeStatus(status: Record<string, unknown>): string {
+  return `\npi-actors version=${String(status.version)} mode=${String(status.mode)} path=${String(status.package_root)} entrypoint=${String(status.entrypoint)}${status.git_commit ? ` git=${String(status.git_commit)}` : ""}`;
+}
+
 function compactToolActor(name: string, tool: Record<string, unknown>): string {
   const parameters = asRecord(tool.parameters);
   const required = Array.isArray(parameters.required)
@@ -535,6 +590,7 @@ function compactActorMessageResult(
     `message=${result.sent === true || result.stopped === true ? "sent" : "not_sent"}`,
   ];
   if (result.bytes !== undefined) tokens.push(`bytes=${String(result.bytes)}`);
+  if (result.queued === true) tokens.push("queued=true");
   if (result.control) tokens.push(`control=${String(result.control)}`);
   if (result.outbox) tokens.push(`messages=${String(result.outbox)}`);
   if (result.message_count !== undefined)
@@ -546,6 +602,9 @@ function compactActorMessageResult(
   if (result.stopped === true) tokens.push("stopped=true");
   if (result.signal) tokens.push(`signal=${String(result.signal)}`);
   if (result.invoked === true) tokens.push("invoked=true");
+  if (result.delivery_error) {
+    tokens.push(`delivery_error=${compactPreview(result.delivery_error, 96)}`);
+  }
   return `\n${tokens.join(" ")}`;
 }
 
@@ -695,7 +754,24 @@ async function routeBranchEnvelope(
     recipient,
     branchMessage,
   );
-  return AsyncRuns.sendRunMessage(runId, JSON.stringify(branchMessage));
+  try {
+    return await AsyncRuns.sendRunMessage(runId, JSON.stringify(branchMessage));
+  } catch (error) {
+    const record = error && typeof error === "object" ? (error as Record<string, unknown>) : {};
+    if (record.queued === true) {
+      return {
+        control_path: record.control_path,
+        control_type: record.control_type,
+        delivery_error: record.delivery_error ?? (error instanceof Error ? error.message : String(error)),
+        inbox_id: record.inbox_id,
+        queued: true,
+        run: runId,
+        sent: false,
+        state_dir: stateDir,
+      };
+    }
+    throw error;
+  }
 }
 
 function getRoomMulticastRecipients(
@@ -850,8 +926,17 @@ function assertRunAccessibleToContext(
   const status = AsyncRuns.getRunStatus(runId);
   const sessionId = getContextSessionId(ctx);
   if (sessionId && status.ownerId && status.ownerId !== sessionId) {
-    throw new Error(
-      `run:${runId} is owned by session:${status.ownerId}; current session is ${sessionId}.`,
+    throw Object.assign(
+      new Error(
+        `run:${runId} reason=session_mismatch owner_session=${status.ownerId} current_session=${sessionId} hint=inspect_session:${status.ownerId}`,
+      ),
+      {
+        current_session: sessionId,
+        hint: `inspect target=session:${status.ownerId} view=status`,
+        owner_session: status.ownerId,
+        reason: "session_mismatch",
+        run: runId,
+      },
     );
   }
   return status;
@@ -940,24 +1025,24 @@ export function createInspectToolDefinition<TContext = unknown>(
           );
         }
         const session = requireContextSessionId(ctx, "inspect coordinator");
-        const runs = AsyncRuns.listRuns(
+        const allRuns = AsyncRuns.listRuns(
           undefined,
           typeof input.status === "string" ? input.status : undefined,
-        )
-          .map((run) => AsyncRuns.getRunStatus(String(run.state_dir)))
-          .filter((run) => run.ownerId === session);
+        ).map((run) => AsyncRuns.getRunStatus(String(run.state_dir)));
+        const runs = allRuns.filter((run) => run.ownerId === session);
+        const sessionSummary = summarizeOtherSessions(session, allRuns);
         return {
           content: [
             {
               type: "text" as const,
               text: maybeJsonText(
-                { session, runs },
+                { session, runs, ...sessionSummary },
                 input.verbose === true,
-                compactSessionRuns(session, runs),
+                compactSessionRuns(session, runs, sessionSummary),
               ),
             },
           ],
-          details: { session, runs },
+          details: { session, runs, ...sessionSummary },
         };
       }
       if (address.kind === "session") {
@@ -966,29 +1051,50 @@ export function createInspectToolDefinition<TContext = unknown>(
             "inspect session:<id> supports view=status or view=runs.",
           );
         }
-        const runs = AsyncRuns.listRuns(
+        const allRuns = AsyncRuns.listRuns(
           undefined,
           typeof input.status === "string" ? input.status : undefined,
-        )
-          .map((run) => AsyncRuns.getRunStatus(String(run.state_dir)))
-          .filter(
-            (run) => address.value === "all" || run.ownerId === address.value,
-          );
+        ).map((run) => AsyncRuns.getRunStatus(String(run.state_dir)));
+        const runs = allRuns.filter(
+          (run) => address.value === "all" || run.ownerId === address.value,
+        );
+        const sessionSummary = address.value === "all"
+          ? {}
+          : summarizeOtherSessions(address.value || "", allRuns);
         return {
           content: [
             {
               type: "text" as const,
               text: maybeJsonText(
-                { session: address.value, runs },
+                { session: address.value, runs, ...sessionSummary },
                 input.verbose === true,
-                compactSessionRuns(address.value || "", runs),
+                compactSessionRuns(address.value || "", runs, sessionSummary),
               ),
             },
           ],
-          details: { session: address.value, runs },
+          details: { session: address.value, runs, ...sessionSummary },
         };
       }
       if (address.kind === "tool" && address.value) {
+        if (address.value === "pi-actors") {
+          if (view !== "status") {
+            throw new Error("inspect tool:pi-actors supports view=status.");
+          }
+          const details = getPiActorsRuntimeStatus();
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: maybeJsonText(
+                  details,
+                  input.verbose === true,
+                  compactPiActorsRuntimeStatus(details),
+                ),
+              },
+            ],
+            details,
+          };
+        }
         if (view !== "status" && view !== "schema") {
           throw new Error(
             "inspect tool:<name> supports view=status or view=schema.",

package/package.json

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

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.26.2
+  version: 0.27.0
 ---
 
 # Actors (pi-actors)
@@ -41,7 +41,7 @@ Trusted local capability
 - **Recipe**: saved JSON definition wrapping a template with args, defaults, imports, mailbox, artifacts, metadata, and optional `async: true`.
 - **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, communication snapshot, and artifacts.
 - **Room actor**: shared timeline + roster endpoint addressable as `room:<run>`; every spawned run gets `room:<run>`.
-- **Tool actor**: registered persistent capability addressable as `tool:<name>` and callable through the generated tool or `message`.
+- **Tool actor**: registered persistent capability addressable as `tool:<name>` and callable through the generated tool or `message`. `tool:pi-actors` is reserved for runtime/status inspection.
 - **Coordinator/session**: the current pi session endpoint that receives bounded actor follow-ups.
 - **Mailbox**: public interaction contract: message types the actor accepts/emits.
 - **Artifact**: named durable output path declared by a recipe/run.
@@ -102,6 +102,7 @@ Check `inspect view=mailbox` before domain-specific messages.
 { "target": "room:repo-health", "view": "roster" }
 { "target": "room:repo-health", "view": "contacts" }
 { "target": "room:repo-health", "view": "previews" }
+{ "target": "tool:pi-actors", "view": "status" }
 { "target": "tool:music_player", "view": "status" }
 { "target": "recipes", "view": "status" }
 { "target": "coordinator", "view": "status" }

package/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent orchestration with scoped locks and quorum consensus. Use for multi-model review, parallel scoped work, delegated audit, and coordinated subagent execution.
 metadata:
-  version: 0.26.2
+  version: 0.27.0
 ---
 
 # Swarm