@llblab/pi-actors 0.40.0 → 0.41.0

package/dist/lib/inspector.d.ts

@@ -3,6 +3,7 @@
  * Zones: terminal run inspection, room/direct message previews, no-dependency UI formatting
  * Owns read-only previews and TUI-ready summaries; actor routing stays outside.
  */
+import * as SessionEvidence from "./session-evidence.ts";
 export interface ActorInspectorPreview {
     body_preview?: string;
     branch?: string;
@@ -45,47 +46,30 @@ export interface ActorInspectorPreviewReadOptions {
     ownerId?: string;
     branch?: string;
     currentRunOnly?: boolean;
+    run?: string;
     channels?: ActorInspectorPreview["channel"][];
     mention?: string;
     readKeys?: Iterable<string>;
     roomLimitPerRun?: number;
     unreadOnly?: boolean;
 }
-export interface ActorInspectorControllerState {
-    branch?: string;
-    channels?: ActorInspectorPreview["channel"][];
-    mention?: string;
-    readKeys: Set<string>;
-    roomLimitPerRun: number;
-    rows: number;
-    selectedSequence?: number;
-    unreadOnly: boolean;
-    visible: boolean;
+export interface ActorInspectorRunItem {
+    run: string;
+    status: string;
+    updatedAt?: string;
 }
-export interface ActorInspectorCommandResult {
-    notify: string;
-    type: "info" | "warning";
-    update: boolean;
+export declare function readActorInspectorRuns(stateRoot: string, ownerId: string): ActorInspectorRunItem[];
+export interface ActorInspectorTurnItem extends SessionEvidence.SessionEvidenceTurn {
+    commandId: string;
+    diagnostics: string[];
+    promptBytes?: number;
+    promptFile?: string;
+    recipeContext?: unknown;
+    sessionFile: string;
+    sessionTruncated: boolean;
+    stage?: string;
 }
-export declare const DEFAULT_ACTOR_INSPECTOR_ROWS = 12;
-export declare const ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS: {
-    filter: string;
-    inspect: string;
-    toggle: string;
-};
-export declare function createActorInspectorControllerState(): ActorInspectorControllerState;
-export declare function getActorInspectorPreviewOptions(state: ActorInspectorControllerState, ownerId: string): ActorInspectorPreviewReadOptions;
-export declare function handleActorInspectorToggle(state: ActorInspectorControllerState, args: unknown): ActorInspectorCommandResult;
-export declare function handleActorInspectorFilter(state: ActorInspectorControllerState, args: unknown): ActorInspectorCommandResult;
-export declare function handleActorInspectorInspect(state: ActorInspectorControllerState, args: unknown, previews: ActorInspectorPreview[]): ActorInspectorCommandResult;
-export declare function selectActorInspectorSequence(state: ActorInspectorControllerState, sequence: number, previews: ActorInspectorPreview[]): ActorInspectorCommandResult;
-export declare function renderActorInspectorPanel(input: {
-    stateRoot: string;
-    state: ActorInspectorControllerState;
-    ownerId: string;
-    width: number;
-    style: ActorInspectorWidgetStyle;
-}): string[];
+export declare function readActorInspectorTurns(stateDir: string): ActorInspectorTurnItem[];
 export declare function inspectorPreviewReadKey(preview: ActorInspectorPreview): string;
 export declare function readActorInspectorPreviews(stateRoot?: string, limit?: number, options?: ActorInspectorPreviewReadOptions): ActorInspectorPreview[];
 export declare function readActorInspectorRoster(stateRoot: string | undefined, run: string, room?: string): ActorInspectorRosterMember[];

package/dist/lib/inspector.js

@@ -8,164 +8,108 @@ import * as path from "node:path";
 import { visibleWidth } from "@earendil-works/pi-tui";
 import * as Limits from "./limits.js";
 import * as Paths from "./paths.js";
+import * as SessionEvidence from "./session-evidence.js";
 import { readJsonFileResilient, readJsonlFileResilient, } from "./state-readers.js";
-export const DEFAULT_ACTOR_INSPECTOR_ROWS = 12;
-export const ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS = {
-    filter: "Filter actor inspector rows: all, room, direct, broadcast, unread, branch <name>, mention <text>",
-    inspect: "Inspect actor message by visible number",
-    toggle: "Toggle actor inspector widget; optional row count",
-};
-export function createActorInspectorControllerState() {
-    return {
-        readKeys: new Set(),
-        roomLimitPerRun: DEFAULT_ACTOR_INSPECTOR_ROWS,
-        rows: DEFAULT_ACTOR_INSPECTOR_ROWS,
-        unreadOnly: false,
-        visible: false,
-    };
-}
-export function getActorInspectorPreviewOptions(state, ownerId) {
-    return {
-        channels: state.channels,
-        currentRunOnly: true,
-        branch: state.branch,
-        mention: state.mention,
-        ownerId,
-        readKeys: state.readKeys,
-        roomLimitPerRun: state.roomLimitPerRun,
-        unreadOnly: state.unreadOnly,
-    };
-}
-export function handleActorInspectorToggle(state, args) {
-    const raw = Array.isArray(args) ? args[0] : String(args ?? "");
-    if (String(raw).trim()) {
-        const rows = Number.parseInt(String(raw), 10);
-        if (!Number.isFinite(rows) || rows <= 0) {
-            return {
-                notify: "Usage: /actors-inspector-toggle [rows] where rows > 0",
-                type: "warning",
-                update: false,
-            };
-        }
-        state.rows = rows;
-        state.roomLimitPerRun = rows;
-        state.selectedSequence = undefined;
-        state.visible = true;
-        return {
-            notify: `Actor inspector rows ${rows}`,
-            type: "info",
-            update: true,
-        };
-    }
-    if (state.selectedSequence !== undefined) {
-        state.selectedSequence = undefined;
-        state.visible = true;
-        return { notify: "Actor inspector table", type: "info", update: true };
+export function readActorInspectorRuns(stateRoot, ownerId) {
+    try {
+        return fs
+            .readdirSync(stateRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .flatMap((entry) => {
+            const stateDir = path.join(stateRoot, entry.name);
+            if (!matchesOwner(stateDir, ownerId))
+                return [];
+            const progress = readJsonFileResilient(path.join(stateDir, "progress.json"), {}).value;
+            const result = readJsonFileResilient(path.join(stateDir, "result.json"), {}).value;
+            return [{
+                    run: entry.name,
+                    status: String(progress.phase ?? (Object.keys(result).length ? "terminal" : "unknown")),
+                    ...(typeof progress.updatedAt === "string"
+                        ? { updatedAt: progress.updatedAt }
+                        : typeof result.completedAt === "string"
+                            ? { updatedAt: result.completedAt }
+                            : {}),
+                }];
+        })
+            .sort((left, right) => String(left.updatedAt ?? "").localeCompare(String(right.updatedAt ?? "")));
     }
-    if (state.visible)
-        state.visible = false;
-    else {
-        state.rows = DEFAULT_ACTOR_INSPECTOR_ROWS;
-        state.roomLimitPerRun = DEFAULT_ACTOR_INSPECTOR_ROWS;
-        state.visible = true;
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        return [];
     }
-    return {
-        notify: `Actor inspector ${state.visible ? "shown" : "hidden"}`,
-        type: "info",
-        update: true,
-    };
 }
-export function handleActorInspectorFilter(state, args) {
-    const parts = Array.isArray(args)
-        ? args.map(String)
-        : String(args ?? "").split(/\s+/);
-    const mode = (parts[0] ?? "").trim().toLowerCase();
-    if (!mode || mode === "all" || mode === "clear") {
-        state.channels = undefined;
-        state.mention = undefined;
-        state.branch = undefined;
-        state.unreadOnly = false;
-    }
-    else if (mode === "room" || mode === "direct" || mode === "broadcast") {
-        state.channels = [mode];
-        state.mention = undefined;
-    }
-    else if (mode === "unread") {
-        state.unreadOnly = true;
-    }
-    else if (mode === "branch" || mode === "current-branch") {
-        const branch = parts.slice(1).join(" ").trim();
-        if (!branch) {
-            return {
-                notify: `Usage: /actors-inspector-filter ${mode} <branch-name>`,
-                type: "warning",
-                update: false,
-            };
-        }
-        state.branch = branch;
-    }
-    else if (mode === "mention") {
-        const mention = parts.slice(1).join(" ").trim();
-        if (!mention) {
-            return {
-                notify: "Usage: /actors-inspector-filter mention <text>",
-                type: "warning",
-                update: false,
-            };
-        }
-        state.channels = undefined;
-        state.mention = mention;
+function ownedSessionPath(stateDir, sessionFile) {
+    if (path.isAbsolute(sessionFile))
+        return undefined;
+    const sessionsRoot = path.resolve(stateDir, "sessions");
+    const resolved = path.resolve(stateDir, sessionFile);
+    if (!resolved.startsWith(`${sessionsRoot}${path.sep}`))
+        return undefined;
+    try {
+        const canonicalRoot = fs.realpathSync(sessionsRoot);
+        const canonicalFile = fs.realpathSync(resolved);
+        return canonicalFile.startsWith(`${canonicalRoot}${path.sep}`)
+            ? canonicalFile
+            : undefined;
     }
-    else {
-        return {
-            notify: "Usage: /actors-inspector-filter all|room|direct|broadcast|unread|branch <name>|mention <text>",
-            type: "warning",
-            update: false,
-        };
+    catch {
+        return undefined;
     }
-    state.selectedSequence = undefined;
-    state.visible = true;
-    return {
-        notify: `Actor inspector filter ${mode || "all"}`,
-        type: "info",
-        update: true,
-    };
 }
-export function handleActorInspectorInspect(state, args, previews) {
-    const raw = Array.isArray(args) ? args[0] : String(args ?? "");
-    return selectActorInspectorSequence(state, Number.parseInt(String(raw), 10), previews);
-}
-export function selectActorInspectorSequence(state, sequence, previews) {
-    if (!Number.isFinite(sequence) || sequence <= 0) {
-        return {
-            notify: "Usage: /actors-inspect <number>",
-            type: "warning",
-            update: false,
-        };
+export function readActorInspectorTurns(stateDir) {
+    const evidence = readJsonFileResilient(path.join(stateDir, "review-evidence.json"), {}).value;
+    const commands = Array.isArray(evidence.commands)
+        ? evidence.commands
+        : [];
+    const recordedFiles = new Set(commands.flatMap((command) => (Array.isArray(command.session_files) ? command.session_files : []).filter((file) => typeof file === "string")));
+    let discoveredCommands = [];
+    try {
+        const sessionsDir = path.join(stateDir, "sessions");
+        discoveredCommands = fs
+            .readdirSync(sessionsDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .flatMap((entry) => {
+            const files = fs
+                .readdirSync(path.join(sessionsDir, entry.name), {
+                withFileTypes: true,
+            })
+                .filter((file) => file.isFile() && file.name.endsWith(".jsonl"))
+                .map((file) => path.join("sessions", entry.name, file.name))
+                .filter((file) => !recordedFiles.has(file));
+            return files.length > 0
+                ? [{ id: entry.name, session_files: files, stage: "subagent" }]
+                : [];
+        });
     }
-    const preview = previews.find((item) => item.sequence === sequence);
-    if (preview)
-        state.readKeys.add(inspectorPreviewReadKey(preview));
-    state.selectedSequence = sequence;
-    state.visible = true;
-    return {
-        notify: `Actor inspect item ${sequence}`,
-        type: "info",
-        update: true,
-    };
-}
-export function renderActorInspectorPanel(input) {
-    const previews = readActorInspectorPreviews(input.stateRoot, input.state.rows, getActorInspectorPreviewOptions(input.state, input.ownerId));
-    const rows = (input.state.selectedSequence !== undefined
-        ? renderInspectorItemView(previews, input.width, input.style, {
-            sequence: input.state.selectedSequence,
-        })
-        : renderInspectorWidget(previews, input.width, input.style)) ?? [];
-    const run = previews[0]?.run;
-    const roster = input.state.selectedSequence === undefined && run
-        ? renderInspectorRosterPanel(readActorInspectorRoster(input.stateRoot, run), input.width, input.style)
-        : undefined;
-    return roster ? [...roster, ...rows] : rows;
+    catch {
+        discoveredCommands = [];
+    }
+    return [...commands, ...discoveredCommands].flatMap((command) => (Array.isArray(command.session_files) ? command.session_files : [])
+        .filter((file) => typeof file === "string")
+        .flatMap((file) => {
+        const sessionPath = ownedSessionPath(stateDir, file);
+        if (!sessionPath)
+            return [];
+        const session = SessionEvidence.readSessionEvidence(sessionPath);
+        return session.turns.map((turn) => ({
+            ...turn,
+            commandId: String(command.id ?? "unknown"),
+            diagnostics: session.diagnostics.map((item) => `${item.line === undefined ? "" : `line ${item.line}: `}${item.message}`),
+            ...(typeof command.prompt_bytes === "number"
+                ? { promptBytes: command.prompt_bytes }
+                : {}),
+            ...(typeof command.prompt_file === "string"
+                ? { promptFile: command.prompt_file }
+                : {}),
+            ...(command.recipe_context !== undefined
+                ? { recipeContext: command.recipe_context }
+                : {}),
+            sessionFile: file,
+            sessionTruncated: session.truncated,
+            ...(typeof command.stage === "string" ? { stage: command.stage } : {}),
+        }));
+    })).map((turn, index) => ({ ...turn, index: index + 1 }));
 }
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
@@ -178,7 +122,8 @@ function readJsonLines(file) {
 function previewValue(value, maxLength = Limits.INSPECTOR_BODY_PREVIEW_CHARS) {
     if (value === undefined)
         return undefined;
-    const text = typeof value === "string" ? value : JSON.stringify(value);
+    const redacted = SessionEvidence.redactSessionEvidenceValue(value);
+    const text = typeof redacted === "string" ? redacted : JSON.stringify(redacted);
     const compact = text.replaceAll(/\s+/g, " ").trim();
     if (!compact)
         return undefined;
@@ -393,6 +338,8 @@ export function readActorInspectorPreviews(stateRoot = Paths.getRunStateRoot(),
             const stateDir = path.join(stateRoot, entry.name);
             if (!matchesOwner(stateDir, options.ownerId))
                 return [];
+            if (options.run && entry.name !== options.run)
+                return [];
             return [
                 ...readRoomPreviews(entry.name, stateDir),
                 ...readInboxPreviews(entry.name, stateDir),

package/dist/lib/limits.d.ts

@@ -9,3 +9,6 @@ export declare const COMPACT_PREVIEW_CHARS = 160;
 export declare const INSPECTOR_BODY_PREVIEW_CHARS = 320;
 export declare const ROOM_MESSAGE_PREVIEW_CHARS = 320;
 export declare const DOCTOR_ACTION_PREVIEW_CHARS = 72;
+export declare const SESSION_EVIDENCE_MAX_TURNS = 100;
+export declare const SESSION_EVIDENCE_TEXT_CHARS = 4000;
+export declare const SESSION_EVIDENCE_MAX_TOOL_CALLS = 100;

package/dist/lib/limits.js

@@ -9,3 +9,6 @@ export const COMPACT_PREVIEW_CHARS = 160;
 export const INSPECTOR_BODY_PREVIEW_CHARS = 320;
 export const ROOM_MESSAGE_PREVIEW_CHARS = 320;
 export const DOCTOR_ACTION_PREVIEW_CHARS = 72;
+export const SESSION_EVIDENCE_MAX_TURNS = 100;
+export const SESSION_EVIDENCE_TEXT_CHARS = 4_000;
+export const SESSION_EVIDENCE_MAX_TOOL_CALLS = 100;

package/dist/lib/observability.d.ts

@@ -50,7 +50,7 @@ export interface RunUiSnapshot {
 }
 export interface RunUiNotificationSink {
     notify(message: string, level: "info" | "warning" | "error"): void;
-    sendSteering(message: {
+    sendFollowUp(message: {
         customType: string;
         content: string;
         display: true;

package/dist/lib/observability.js

@@ -37,7 +37,7 @@ export function deliverRunTransitionNotifications(transitions, sink) {
         sink.notify(text, getRunTransitionNotificationType(transition));
         if (!shouldSendRunTransitionFollowUp(transition))
             continue;
-        sink.sendSteering({
+        sink.sendFollowUp({
             customType: "pi-actors-run",
             content: text,
             display: true,
@@ -56,7 +56,7 @@ export function deliverRunOutboxNotifications(events, sink) {
         sink.notify(text, getRunOutboxNotificationType(event));
         if (!shouldSendRunOutboxFollowUp(event))
             continue;
-        sink.sendSteering({
+        sink.sendFollowUp({
             customType: "pi-actors-run-message",
             content: text,
             display: true,

package/dist/lib/pi.d.ts

@@ -7,7 +7,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 export type { ExtensionAPI, ExtensionContext };
 export interface PiNotificationSink {
     notify(message: string, level: "info" | "warning" | "error"): void;
-    sendSteering(message: {
+    sendFollowUp(message: {
         customType: string;
         content: string;
         display: true;

package/dist/lib/pi.js

@@ -9,8 +9,8 @@ export function getSessionId(ctx) {
 export function createNotificationSink(pi, ctx) {
     return {
         notify: (message, level) => ctx.ui.notify(message, level),
-        sendSteering: (message) => pi.sendMessage(message, {
-            deliverAs: "steer",
+        sendFollowUp: (message) => pi.sendMessage(message, {
+            deliverAs: "followUp",
             triggerTurn: true,
         }),
     };

package/dist/lib/prompts.d.ts

@@ -6,7 +6,7 @@
 export declare const REGISTER_TOOL_DESCRIPTION: string;
 export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent command templates as agent-callable tools";
 export declare const REGISTER_TOOL_GUIDELINES: string[];
-export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. When a deferred actor result gates the next step, wait for its terminal steering notification; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first; for deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
+export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync and shell-free: string leaves split into executable + argv, so operators such as && are literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
 export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
     readonly name: "Tool name in snake_case (e.g., 'transcribe')";
     readonly description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.";

package/dist/lib/prompts.js

@@ -16,17 +16,17 @@ export const REGISTER_TOOL_GUIDELINES = [
 export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.
 - Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.
-- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
+- Command templates stay sync and shell-free: string leaves split into executable + argv, so operators such as && are literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
 - Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
 - ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
 - Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.
 - Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.
-- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. When a deferred actor result gates the next step, wait for its terminal steering notification; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
+- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
 - Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
 - Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
-- For any non-trivial actor use or pi-actors change, read the bundled actors skill first; for deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
+- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
     name: "Tool name in snake_case (e.g., 'transcribe')",
     description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.",

package/dist/lib/recipes-context.d.ts

@@ -14,6 +14,11 @@ export declare function markRecipeContextRecords(records: TemplateRecipeContextR
 export declare function formatRecipeContextJsonl(records: TemplateRecipeContextRecord[], context?: CommandTemplateActorRecipeContext): string;
 export declare function buildRecipeContextPromptBlock(records: TemplateRecipeContextRecord[], context?: CommandTemplateActorRecipeContext): string;
 export declare function appendRecipeContextToPiArgs(command: string, args: string[], records: TemplateRecipeContextRecord[] | undefined, context?: CommandTemplateActorRecipeContext): string[];
+export interface ManagedPiSessionArgs {
+    args: string[];
+    sessionDir?: string;
+}
+export declare function attachPiSessionDir(command: string, args: string[], sessionDir: string): ManagedPiSessionArgs;
 export interface MaterializedPiPrintPromptArgs {
     args: string[];
     promptBytes?: number;

package/dist/lib/recipes-context.js

@@ -134,6 +134,21 @@ export function appendRecipeContextToPiArgs(command, args, records, context) {
     next[promptIndex] = `${next[promptIndex]}\n\n${block}`;
     return next;
 }
+const PI_SESSION_POLICY_FLAGS = new Set([
+    "--fork",
+    "--no-session",
+    "--session",
+    "--session-dir",
+    "--session-id",
+]);
+export function attachPiSessionDir(command, args, sessionDir) {
+    if (!isPiCommand(command) || findPiPrintPromptIndex(args) === undefined) {
+        return { args };
+    }
+    if (args.some((arg) => PI_SESSION_POLICY_FLAGS.has(arg)))
+        return { args };
+    return { args: ["--session-dir", sessionDir, ...args], sessionDir };
+}
 export function materializePiPrintPromptArg(command, args, promptFile) {
     if (!isPiCommand(command))
         return { args };

package/dist/lib/session-evidence.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 { type StateReadDiagnostic } from "./state-readers.ts";
+export interface SessionEvidenceToolCall {
+    arguments?: unknown;
+    id: string;
+    name: string;
+    result?: unknown;
+    resultError?: boolean;
+}
+export interface SessionEvidenceTurn {
+    assistantEntryId?: string;
+    assistantText?: string;
+    error?: string;
+    index: number;
+    model?: string;
+    provider?: string;
+    stopReason?: string;
+    thinking?: string;
+    timestamp?: string;
+    toolCalls: SessionEvidenceToolCall[];
+    unmatchedToolResults: number;
+    usage?: unknown;
+    userEntryId?: string;
+    userText?: string;
+}
+export interface SessionEvidence {
+    activeLeafId?: string;
+    diagnostics: StateReadDiagnostic[];
+    path: string;
+    session?: Record<string, unknown>;
+    totalTurns: number;
+    truncated: boolean;
+    turns: SessionEvidenceTurn[];
+}
+export interface SessionEvidenceReadOptions {
+    maxTextChars?: number;
+    maxToolCalls?: number;
+    maxTurns?: number;
+}
+export declare function redactSessionEvidenceValue(value: unknown, maxTextChars?: number, seen?: WeakSet<object>): unknown;
+export declare function readSessionEvidence(path: string, options?: SessionEvidenceReadOptions): SessionEvidence;