@llblab/pi-actors 0.40.0 → 0.41.0

package/dist/lib/session-evidence.js

@@ -0,0 +1,204 @@
+/**
+ * Persisted Pi session evidence reader.
+ * Zones: subagent turns, active session branches, bounded/redacted previews
+ * Owns read-only normalization of session JSONL into inspector-ready turns.
+ */
+import * as Limits from "./limits.js";
+import { readJsonlFileResilient, } from "./state-readers.js";
+const SENSITIVE_KEY = /(?:^|[_-])(?:api[-_]?key|authorization|cookie|credential|password|private[-_]?key|secret|secret[-_]?access[-_]?key|token)$|^(?:access|refresh|auth|api)Token$|^(?:clientSecret|privateKey|secretAccessKey)$/i;
+const SENSITIVE_TEXT = /(bearer\s+)[A-Za-z0-9._~+/=-]+|["']?\b(api[-_]?key|authorization|clientSecret|cookie|password|private[-_]?key|privateKey|secret|secretAccessKey|token)["']?(\s*[:=]\s*)["']?([^\s,;"'}]+)/gi;
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function boundedText(value, maxChars) {
+    if (typeof value !== "string")
+        return undefined;
+    if (/^\s*[\[{]/.test(value)) {
+        try {
+            const structured = JSON.stringify(redactSessionEvidenceValue(JSON.parse(value), maxChars));
+            return structured.length > maxChars
+                ? `${structured.slice(0, Math.max(0, maxChars - 1))}…`
+                : structured;
+        }
+        catch {
+            // Fall through to bounded text redaction.
+        }
+    }
+    const redacted = value.replaceAll(SENSITIVE_TEXT, (match, bearer, key, separator) => bearer ? `${bearer}[REDACTED]` : `${key}${separator}[REDACTED]`);
+    return redacted.length > maxChars
+        ? `${redacted.slice(0, Math.max(0, maxChars - 1))}…`
+        : redacted;
+}
+export function redactSessionEvidenceValue(value, maxTextChars = Limits.SESSION_EVIDENCE_TEXT_CHARS, seen = new WeakSet()) {
+    if (typeof value === "string")
+        return boundedText(value, maxTextChars);
+    if (!value || typeof value !== "object")
+        return value;
+    if (seen.has(value))
+        return "[CIRCULAR]";
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => redactSessionEvidenceValue(item, maxTextChars, seen));
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        SENSITIVE_KEY.test(key)
+            ? "[REDACTED]"
+            : redactSessionEvidenceValue(item, maxTextChars, seen),
+    ]));
+}
+function contentBlocks(message) {
+    return Array.isArray(message.content)
+        ? message.content.map(asRecord)
+        : typeof message.content === "string"
+            ? [{ type: "text", text: message.content }]
+            : [];
+}
+function contentText(message, type, maxChars) {
+    const text = contentBlocks(message)
+        .filter((block) => block.type === type && typeof block[type] === "string")
+        .map((block) => String(block[type]))
+        .join("\n");
+    return boundedText(text, maxChars);
+}
+function activeBranch(entries, path, diagnostics) {
+    const treeEntries = entries.filter((entry) => entry.type !== "session" && typeof entry.id === "string");
+    const leaf = treeEntries.at(-1);
+    if (!leaf || typeof leaf.id !== "string")
+        return [];
+    const byId = new Map(treeEntries.map((entry) => [String(entry.id), entry]));
+    const branch = [];
+    const visited = new Set();
+    let current = leaf;
+    while (current && typeof current.id === "string") {
+        if (visited.has(current.id)) {
+            diagnostics.push({ message: `session entry cycle at ${current.id}`, path });
+            break;
+        }
+        visited.add(current.id);
+        branch.push(current);
+        if (current.parentId === null || current.parentId === undefined)
+            break;
+        if (typeof current.parentId !== "string" || !byId.has(current.parentId)) {
+            diagnostics.push({
+                message: `missing parent ${String(current.parentId)} for ${current.id}`,
+                path,
+            });
+            break;
+        }
+        current = byId.get(current.parentId);
+    }
+    return branch.reverse();
+}
+function toolCalls(message, maxTextChars, maxToolCalls) {
+    return contentBlocks(message)
+        .filter((block) => block.type === "toolCall" &&
+        typeof block.id === "string" &&
+        typeof block.name === "string")
+        .slice(0, maxToolCalls)
+        .map((block) => ({
+        arguments: redactSessionEvidenceValue(block.arguments, maxTextChars),
+        id: String(block.id),
+        name: String(block.name),
+    }));
+}
+export function readSessionEvidence(path, options = {}) {
+    const maxTextChars = Math.max(1, options.maxTextChars ?? Limits.SESSION_EVIDENCE_TEXT_CHARS);
+    const maxToolCalls = Math.max(1, options.maxToolCalls ?? Limits.SESSION_EVIDENCE_MAX_TOOL_CALLS);
+    const maxTurns = Math.max(1, options.maxTurns ?? Limits.SESSION_EVIDENCE_MAX_TURNS);
+    const read = readJsonlFileResilient(path);
+    const diagnostics = [...read.diagnostics];
+    const header = read.records.find((entry) => entry.type === "session");
+    const branch = activeBranch(read.records, path, diagnostics);
+    const turns = [];
+    let pendingUser;
+    let currentTurn;
+    for (const entry of branch) {
+        if (entry.type !== "message")
+            continue;
+        const message = asRecord(entry.message);
+        const role = message.role;
+        if (role === "user") {
+            pendingUser = {
+                id: String(entry.id),
+                text: contentText(message, "text", maxTextChars),
+            };
+            currentTurn = undefined;
+            continue;
+        }
+        if (role === "assistant") {
+            currentTurn = {
+                ...(typeof entry.id === "string" ? { assistantEntryId: entry.id } : {}),
+                ...(contentText(message, "text", maxTextChars)
+                    ? { assistantText: contentText(message, "text", maxTextChars) }
+                    : {}),
+                ...(typeof message.errorMessage === "string"
+                    ? { error: boundedText(message.errorMessage, maxTextChars) }
+                    : {}),
+                index: turns.length + 1,
+                ...(typeof message.model === "string" ? { model: message.model } : {}),
+                ...(typeof message.provider === "string"
+                    ? { provider: message.provider }
+                    : {}),
+                ...(typeof message.stopReason === "string"
+                    ? { stopReason: message.stopReason }
+                    : {}),
+                ...(contentText(message, "thinking", maxTextChars)
+                    ? { thinking: contentText(message, "thinking", maxTextChars) }
+                    : {}),
+                ...(typeof entry.timestamp === "string"
+                    ? { timestamp: entry.timestamp }
+                    : {}),
+                toolCalls: toolCalls(message, maxTextChars, maxToolCalls),
+                unmatchedToolResults: 0,
+                ...(message.usage !== undefined
+                    ? { usage: redactSessionEvidenceValue(message.usage, maxTextChars) }
+                    : {}),
+                ...(pendingUser
+                    ? {
+                        userEntryId: pendingUser.id,
+                        ...(pendingUser.text ? { userText: pendingUser.text } : {}),
+                    }
+                    : {}),
+            };
+            pendingUser = undefined;
+            turns.push(currentTurn);
+            continue;
+        }
+        if (role === "toolResult" && currentTurn) {
+            const callId = typeof message.toolCallId === "string" ? message.toolCallId : "";
+            const call = currentTurn.toolCalls.find((item) => item.id === callId);
+            if (!call) {
+                currentTurn.unmatchedToolResults += 1;
+                continue;
+            }
+            call.result = redactSessionEvidenceValue(message.content, maxTextChars);
+            call.resultError = message.isError === true;
+        }
+    }
+    if (pendingUser) {
+        turns.push({
+            index: turns.length + 1,
+            toolCalls: [],
+            unmatchedToolResults: 0,
+            userEntryId: pendingUser.id,
+            ...(pendingUser.text ? { userText: pendingUser.text } : {}),
+        });
+    }
+    const firstVisibleIndex = Math.max(0, turns.length - maxTurns);
+    const visibleTurns = turns.slice(firstVisibleIndex).map((turn, index) => ({
+        ...turn,
+        index: firstVisibleIndex + index + 1,
+    }));
+    return {
+        ...(branch.at(-1)?.id ? { activeLeafId: String(branch.at(-1)?.id) } : {}),
+        diagnostics,
+        path,
+        ...(header ? { session: asRecord(header) } : {}),
+        totalTurns: turns.length,
+        truncated: turns.length > visibleTurns.length,
+        turns: visibleTurns,
+    };
+}

package/dist/lib/tools-response.d.ts

@@ -3,6 +3,9 @@
  * Zones: compact text summaries, verbose JSON switching, next-action rendering
  * Owns model-facing response helpers shared by public tool execution paths
  */
+export declare function withLeadingBlankLine(text: string): string;
+export declare function spaceToolResult<T>(result: T): T;
+export declare function spaceToolError(error: unknown): unknown;
 export declare function asRecord(value: unknown): Record<string, unknown>;
 export declare function jsonText(value: unknown): string;
 export declare function compactPreview(value: unknown, maxLength?: number): string | undefined;

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

@@ -1,8 +1,8 @@
 ---
 name: actors
-description: Required practical guide for non-trivial pi-actors use. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
+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.0
+  version: 0.41.0
 ---
 
 # Actors (pi-actors)
@@ -53,6 +53,8 @@ Actor-mode trigger: if work may outlive this turn, needs steering/follow-up/arti
 
 Use for long work, background services, subagents, fanout, pipelines, and reusable recipes.
 
+Before a parallel launch, the coordinator should verify five things once: each actor owns a disjoint mutation scope, every run has a stable id, each durable result has an artifact path, every command template respects shell-free argv execution, and completion can return through follow-up delivery without polling. For multiple delegated implementation or review actors, also load the bundled Swarm skill before choosing decomposition, locks, or quorum shape.
+
 ```json
 {
   "as": "run:repo-health",
@@ -64,6 +66,7 @@ Use for long work, background services, subagents, fanout, pipelines, and reusab
 
 Rules:
 
+- Command-template strings execute directly without a shell. Operators such as `&&`, `||`, pipes, redirects, and `cd` remain literal argv unless an explicit trusted shell is the executable. Prefer absolute paths or template arrays for sequencing; put non-trivial shell behavior in a reviewed script.
 - Use `file`/`recipe` for saved recipes; bare names resolve under `~/.pi/agent/recipes`.
 - Use inline `template` for one-off experiments; promote useful repeats to recipes.
 - When a successful actor follow-up suggests persistence, decide whether the pattern deserves durable tool memory; call `register_tool` yourself only when the evidence is strong, and ask before writing the user recipe root.
@@ -122,15 +125,11 @@ 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:
-
-- `/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.
+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.
 
-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. When a deferred actor result gates the next step, wait for that terminal steering notification instead of scheduling continuation loops, repeatedly inspecting, or mutating the actor's reviewed scope. Busy coordinators receive it at the next safe tool boundary; idle coordinators start a normal turn. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue or stuck run.
+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.
 
 ## Runtime Communication Rules
 
@@ -163,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

@@ -1,8 +1,8 @@
 ---
 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.
+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.0
+  version: 0.41.0
 ---
 
 # Swarm
@@ -13,6 +13,8 @@ Subagent orchestration: delegated review, quorum consensus, scoped locks, clean-
 
 Run subagents safely and predictably through reusable orchestration contracts.
 
+Activation rule: load this skill before launching multiple independent actors or subagents, even when the work is creative artifact generation rather than code review. The coordinator owns decomposition, disjoint scopes, launch correctness, result integration, and final validation; participants may choose local content or implementation details independently inside their assigned boundaries.
+
 Swarm is independent. It must not require concrete sibling skill names, private repositories, local model aliases, or a specific tool registry layout. Local agents may bind the contracts to their own tools, command templates, model names, and review protocols.
 
 Maintain this skill as a living orchestration standard. When real swarm work exposes better decomposition shapes, lock etiquette, quorum rules, checkpoint semantics, failure modes, or trade-offs, fold those lessons back here as durable guidance instead of leaving them only in one-off transcripts or backlog notes.

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