@llblab/pi-actors 0.26.3 → 0.27.1

package/BACKLOG.md

@@ -225,12 +225,78 @@ 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: Done.
+- 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.
+
+### M-13 Shadowed Recipe Launch UX
+
+- Priority: High.
+- Status: Planned.
+- Goal: Make broken user recipes that shadow packaged/ad hoc candidates obvious at launch time.
+- Why now: 0.26 dogfood found a broken `~/.pi/agent/recipes/actor-worker.json` shadowing the packaged `actor-worker`; Recipe Doctor exposed the evidence, but the launch path did not provide a direct hint.
+- Direction:
+  - When recipe resolution or launch fails because the active user recipe is invalid/disabled and a lower-priority candidate exists, surface `reason=shadowed_invalid` or `reason=shadowed_disabled` where practical.
+  - Include active path, blocked candidate path, and compact hint: `inspect target=recipes view=doctor`.
+  - Keep remediation advisory only; do not auto-disable, delete, or rewrite user recipes.
+- Acceptance:
+  - Launch failures caused by shadowing include a compact actionable hint.
+  - Verbose details expose the active broken recipe and blocked fallback candidate.
+  - Tests cover invalid and disabled user recipes shadowing a packaged candidate.
+
+### M-14 Session Mismatch Follow-through
+
+- Priority: Medium.
+- Status: Planned.
+- Goal: Extend 0.27 structured session diagnostics consistently across room, branch, run, coordinator, and session workflows.
+- Why now: M-12 established the shape; dogfood should now make every ownership denial equally actionable without relaxing ownership gates.
+- Direction:
+  - Audit all session mismatch errors for consistent `reason`, owner/current session fields, and inspect-session hints.
+  - Keep read/write ownership policy unchanged.
+  - Update docs with session mismatch examples and recovery inspection paths.
+- Acceptance:
+  - Room, branch, run, coordinator, and session denials share the same compact/verbose shape.
+  - Tests cover representative inspect and message paths.
+
+### M-15 Worker Stale-Claim Dogfood
+
+- Priority: Medium.
+- Status: Planned.
+- Goal: Validate and harden actor-worker v2 stale-claim visibility under intentionally stale claimed branch messages.
+- Why now: M-09 exposed `stale_claims`; real dogfood should verify the operator can diagnose stuck claimed work before adding recovery policy.
+- Direction:
+  - Create deterministic stale claimed branch inbox fixtures or smoke tests.
+  - Verify `worker-status.json`, room events, and inspect surfaces make stale claims visible.
+  - Defer auto-recovery unless workflow evidence proves it is safe.
+- Acceptance:
+  - Stale claims are reproducible and visible in worker status.
+  - Tests cover stale-claim counting without adding scheduler/broker policy.
+
 ## 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 +306,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-13 Shadowed Recipe Launch UX.
 ```

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.27.1: Changelog and Backlog Hotfix
+
+- `[Changelog]` Moved the 0.27.0 runtime/session observability notes out of `Unreleased` into a proper release section so published package history matches the npm/tag release.
+- `[Backlog]` Marked M-12 complete and added the next evidence-backed candidates for shadowed recipe launch UX, session mismatch follow-through, and worker stale-claim dogfood.
+
+## 0.27.0: Runtime and Session Observability UX
+
+- `[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.

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)
@@ -660,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;
 }
@@ -716,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.3
+  version: 0.27.1
 ---
 
 # 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.3
+  version: 0.27.1
 ---
 
 # 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)
@@ -871,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;
@@ -961,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") {
@@ -987,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.3",
+  "version": "0.27.1",
   "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.3
+  version: 0.27.1
 ---
 
 # 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.3
+  version: 0.27.1
 ---
 
 # Swarm