@llblab/pi-actors 0.30.2 → 0.32.0

package/dist/lib/tools.js

@@ -128,12 +128,23 @@ function asRecord(value) {
 function formatFailureCount(value) {
     return Array.isArray(value) ? value.length : undefined;
 }
+function actorRunNextActions(run) {
+    const id = String(run ?? "").trim();
+    if (!id)
+        return [];
+    return [
+        `inspect target=run:${id} view=status`,
+        `inspect target=run:${id} view=messages`,
+        `message to=run:${id} type=<actor.action>`,
+    ];
+}
 function compactAsyncRunStatus(value) {
     const status = asRecord(value);
     const progress = asRecord(status.progress);
     const result = asRecord(status.result);
+    const run = String(status.run ?? "<unknown>");
     const tokens = [
-        `run=${String(status.run ?? "<unknown>")}`,
+        `run=${run}`,
         `status=${String(status.status ?? "unknown")}`,
     ];
     if (status.tool)
@@ -157,8 +168,12 @@ function compactAsyncRunStatus(value) {
         tokens.push(`code=${String(result.code)}`);
     if (result.killed === true)
         tokens.push("killed=true");
-    if (status.candidate_recipe)
-        tokens.push(`candidate_recipe=${String(status.candidate_recipe)}`);
+    const draftRecipe = status.draft_recipe ?? status.candidate_recipe;
+    if (draftRecipe)
+        tokens.push(`draft_recipe=${String(draftRecipe)}`);
+    const nextActions = actorRunNextActions(run);
+    if (nextActions.length > 0)
+        tokens.push(`next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`);
     return `\n${tokens.join(" ")}`;
 }
 function compactRunMessages(messages) {
@@ -343,6 +358,15 @@ function compactArtifactPath(value) {
     const record = asRecord(value);
     return String(record.path ?? "<missing>");
 }
+function artifactNextActions(run, artifacts) {
+    const id = String(run ?? "").trim();
+    if (!id || Object.keys(artifacts).length === 0)
+        return [];
+    return [
+        `inspect target=run:${id} view=artifacts verbose=true`,
+        `inspect target=run:${id} view=messages`,
+    ];
+}
 function compactActorFiles(status) {
     const run = String(status.run ?? "<unknown>");
     const artifacts = asRecord(status.artifacts);
@@ -361,7 +385,11 @@ function compactActorFiles(status) {
             .map(([key, value]) => `${key}:${compactArtifactPath(value)}`)
             .join(",")}`
         : "";
-    return `\nrun=${run}${artifactText}${files.length ? ` files=${files.join(",")}` : ""}`;
+    const nextActions = artifactNextActions(run, artifacts);
+    const nextText = nextActions.length
+        ? ` next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`
+        : "";
+    return `\nrun=${run}${artifactText}${files.length ? ` files=${files.join(",")}` : ""}${nextText}`;
 }
 function summarizeOtherSessions(currentSession, allRuns) {
     const otherRuns = allRuns.filter((run) => run.ownerId && run.ownerId !== currentSession);
@@ -481,8 +509,42 @@ function compactRecipeDoctor(summary) {
             : "";
         lines.push(`${String(item.severity ?? "info")} kind=${String(item.kind ?? "inspect")} id=${String(item.id ?? "root")}${blocked} action=${action ?? "inspect"}`);
     }
+    const nextActions = Array.isArray(summary.next_actions)
+        ? summary.next_actions
+        : [];
+    if (nextActions.length > 0)
+        lines[0] = `${lines[0]}${compactNextActions(nextActions)}`;
     return `\n${lines.join("\n")}`;
 }
+function recipeRegistryNextActions(summary, view) {
+    const actions = [];
+    const drafts = Array.isArray(summary.drafts)
+        ? summary.drafts
+        : [];
+    const invalid = Array.isArray(summary.invalid) ? summary.invalid.length : 0;
+    const diagnostics = Array.isArray(summary.diagnostics)
+        ? summary.diagnostics.length
+        : 0;
+    const topAction = asRecord(summary.top_action);
+    if (view !== "doctor" && (invalid > 0 || diagnostics > 0)) {
+        actions.push("inspect target=recipes view=doctor");
+    }
+    if (view === "doctor" && typeof topAction.action === "string") {
+        actions.push(String(topAction.action));
+    }
+    if (drafts.length > 0) {
+        actions.push("inspect target=recipes view=summary verbose=true");
+        const firstPath = typeof drafts[0]?.path === "string" ? drafts[0].path : undefined;
+        if (firstPath)
+            actions.push(`spawn file=${firstPath}`);
+    }
+    return [...new Set(actions)].slice(0, 4);
+}
+function compactNextActions(actions) {
+    return actions.length
+        ? ` next=${actions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`
+        : "";
+}
 function compactRecipeRegistry(summary) {
     const active = Array.isArray(summary.active) ? summary.active.length : 0;
     const shadowed = Array.isArray(summary.shadowed)
@@ -495,13 +557,41 @@ function compactRecipeRegistry(summary) {
     const diagnostics = Array.isArray(summary.diagnostics)
         ? summary.diagnostics.length
         : 0;
-    const candidates = Array.isArray(summary.candidates)
-        ? summary.candidates.length
-        : 0;
+    const drafts = Array.isArray(summary.drafts)
+        ? summary.drafts.length
+        : Array.isArray(summary.candidates)
+            ? summary.candidates.length
+            : 0;
     const recommendations = Array.isArray(summary.recommendations)
         ? summary.recommendations.length
         : 0;
-    return `\nrecipes active=${active} candidates=${candidates} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}`;
+    const nextActions = Array.isArray(summary.next_actions)
+        ? summary.next_actions
+        : [];
+    return `\nrecipes active=${active} drafts=${drafts} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}${compactNextActions(nextActions)}`;
+}
+function actorMessageNextActions(message, result) {
+    const actions = [];
+    const address = ActorMessages.parseActorAddress(message.to);
+    if (result.delivery_error || result.sent === false) {
+        if (address.kind === "run" && address.value) {
+            actions.push(`inspect target=run:${address.value} view=status`);
+            actions.push(`inspect target=run:${address.value} view=mailbox`);
+        }
+        else if (address.kind === "branch" && address.value) {
+            actions.push(`inspect target=branch:${address.value}/${address.branch ?? "main"} view=mailbox`);
+            actions.push(`inspect target=run:${address.value} view=status`);
+        }
+    }
+    if (result.queued === true) {
+        if (address.kind === "branch" && address.value) {
+            actions.push(`inspect target=branch:${address.value}/${address.branch ?? "main"} view=mailbox`);
+        }
+        else if (address.kind === "run" && address.value) {
+            actions.push(`inspect target=run:${address.value} view=mailbox`);
+        }
+    }
+    return [...new Set(actions)].slice(0, 3);
 }
 function compactActorMessageResult(message, result) {
     const tokens = [
@@ -534,6 +624,11 @@ function compactActorMessageResult(message, result) {
     if (result.delivery_error) {
         tokens.push(`delivery_error=${compactPreview(result.delivery_error, 96)}`);
     }
+    const nextActions = Array.isArray(result.next_actions)
+        ? result.next_actions
+        : actorMessageNextActions(message, result);
+    if (nextActions.length > 0)
+        tokens.push(`next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`);
     return `\n${tokens.join(" ")}`;
 }
 function maybeJsonText(value, verbose, compact) {
@@ -635,7 +730,7 @@ function writeSpawnCandidateRecipe(input, meta) {
     const defaults = candidateRecipeDefaults(meta.values);
     const recipe = {
         async: true,
-        description: `Candidate recipe captured from spawn run ${String(meta.run)}`,
+        description: `Draft recipe captured from spawn run ${String(meta.run)}`,
         ...(meta.artifacts ? { artifacts: meta.artifacts } : {}),
         ...(defaults ? { defaults } : {}),
         template: input.template,
@@ -720,7 +815,7 @@ export function createSpawnToolDefinition() {
     return {
         name: "spawn",
         label: "Spawn",
-        description: "Create an addressable actor from a recipe file or inline command template. Currently spawns run:<id> actors backed by async runs.",
+        description: "Create an addressable actor from a recipe file or inline command template. Use instead of ad hoc shell backgrounding for work that may outlive this turn, needs steering/follow-up/artifacts, runs as a service, fans out, or should be inspected later. Currently spawns run:<id> actors backed by async runs.",
         parameters: objectSchema({
             artifacts: looseObjectSchema("Optional named artifact paths for the spawned actor."),
             as: stringSchema("Optional actor address for the spawned run, e.g. run:<id>."),
@@ -770,9 +865,14 @@ export function createSpawnToolDefinition() {
                 throw enhanceSpawnRecipeError(error, recipe);
             }
             const candidateRecipe = writeSpawnCandidateRecipe(input, meta);
-            const details = candidateRecipe
-                ? { ...meta, candidate_recipe: candidateRecipe }
-                : meta;
+            const nextActions = actorRunNextActions(meta.run);
+            const details = {
+                ...meta,
+                ...(candidateRecipe
+                    ? { candidate_recipe: candidateRecipe, draft_recipe: candidateRecipe }
+                    : {}),
+                next_actions: nextActions,
+            };
             ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
             ActorRooms.writeCommunicationSnapshot(meta.state_dir, String(meta.run));
             return {
@@ -797,15 +897,29 @@ function requireContextSessionId(ctx, actor) {
     }
     return sessionId;
 }
+function sessionMismatchError(input) {
+    const ownerSession = input.expectedSession ?? "none";
+    const currentSession = input.currentSession ?? "none";
+    const actor = input.run ? `run:${input.run}` : (input.target ?? "session");
+    const hintTarget = input.expectedSession
+        ? `session:${input.expectedSession}`
+        : "session:all";
+    return Object.assign(new Error(`${actor} reason=session_mismatch owner_session=${ownerSession} current_session=${currentSession} hint=inspect_session:${input.expectedSession ?? "all"}`), {
+        current_session: input.currentSession,
+        hint: `inspect target=${hintTarget} view=status`,
+        owner_session: input.expectedSession,
+        reason: "session_mismatch",
+        run: input.run,
+        target: input.target,
+    });
+}
 function assertRunAccessibleToContext(runId, ctx) {
     const status = AsyncRuns.getRunStatus(runId);
     const sessionId = getContextSessionId(ctx);
     if (sessionId && status.ownerId && status.ownerId !== 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",
+        throw sessionMismatchError({
+            currentSession: sessionId,
+            expectedSession: String(status.ownerId),
             run: runId,
         });
     }
@@ -818,13 +932,13 @@ export function createInspectToolDefinition(deps = {}) {
     return {
         name: "inspect",
         label: "Inspect",
-        description: "Intentionally inspect an actor. Supports run:<id> views: status, tail, messages, artifacts, files, mailbox, communication; room:<run> status/messages/previews/roster/contacts; coordinator/session status; and tool:<name> status/schema.",
+        description: "Intentionally inspect actors at decision points, after follow-ups, or during diagnosis instead of polling. Core targets are run:<id> and tool:<name>; advanced targets include branch:<run>/<branch>, room:<run>, coordinator, session:<id>, and session:all.",
         parameters: objectSchema({
             lines: stringSchema("Line count for tail/messages views. Default 40."),
             status: stringSchema("Optional session run filter: all, running, active, terminal, done, failed, cancelled, killed, or exited."),
-            target: stringSchema("Actor address to inspect, e.g. run:<id>, room:<run>, coordinator, session:<id>, session:all, or tool:<name>."),
+            target: stringSchema("Actor address to inspect, e.g. run:<id> or tool:<name>; advanced: branch:<run>/<branch>, room:<run>, coordinator, session:<id>, session:all."),
             verbose: booleanSchema("Return full JSON instead of compact text where available."),
-            view: stringSchema("Inspection view: status, tail, messages, artifacts, files, mailbox, communication, roster, or contacts."),
+            view: stringSchema("Inspection view. Core run views: status, tail, messages, artifacts, files, mailbox. Advanced views include communication, roster, and contacts."),
         }, ["target", "view"]),
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const input = asRecord(params);
@@ -846,10 +960,15 @@ export function createInspectToolDefinition(deps = {}) {
                     { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
                 ]);
                 const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
-                const summary = {
+                const summaryBase = {
                     ...RecipeDiscovery.summarizeDiscovery(discovered),
+                    drafts: RecipeDiscovery.listCandidateRecipes(join(recipeRoot, "candidates")),
                     candidates: RecipeDiscovery.listCandidateRecipes(join(recipeRoot, "candidates")),
                 };
+                const summary = {
+                    ...summaryBase,
+                    next_actions: recipeRegistryNextActions(summaryBase, view),
+                };
                 return {
                     content: [
                         {
@@ -1067,7 +1186,11 @@ export function createInspectToolDefinition(deps = {}) {
                     const status = assertRunAccessibleToContext(runId, ctx);
                     const artifactManifest = AsyncRuns.resolveArtifactManifest(status.artifacts);
                     const details = artifactManifest
-                        ? { ...status, artifact_manifest: artifactManifest }
+                        ? {
+                            ...status,
+                            artifact_manifest: artifactManifest,
+                            next_actions: artifactNextActions(status.run ?? runId, asRecord(status.artifacts)),
+                        }
                         : status;
                     return {
                         content: [
@@ -1122,7 +1245,7 @@ export function createActorMessageToolDefinition(deps = {}) {
     return {
         name: "message",
         label: "Message",
-        description: "Send one typed addressed message. Routes to run:<id> mailboxes, branch:<run>/<branch> mailboxes, room:<run> timelines/rosters, tool:<name> calls, and coordinator/session-bound run messages.",
+        description: "Send one typed addressed message to steer an existing actor instead of restarting it. Core routes are run:<id> and tool:<name>; advanced routes include branch:<run>/<branch>, room:<run> group timelines, coordinator, and session:<id>.",
         parameters: objectSchema({
             body: unionSchema([
                 stringSchema("Message body. For run:<id>, this is the run-local command line."),
@@ -1134,7 +1257,7 @@ export function createActorMessageToolDefinition(deps = {}) {
             metadata: looseObjectSchema("Optional structured metadata for routing or domain hints."),
             reply_to: stringSchema("Optional message id this message replies to."),
             summary: stringSchema("Optional short human-facing summary."),
-            to: stringSchema("Destination actor address, e.g. run:<id>, branch:<run>/<branch>, room:<run>, coordinator, session:<id>, or tool:<name>."),
+            to: stringSchema("Destination actor address, e.g. run:<id> or tool:<name>; advanced: branch:<run>/<branch>, room:<run>, coordinator, session:<id>."),
             type: stringSchema("Semantic message type, e.g. control.approve or checkpoint.needs_scope."),
             verbose: booleanSchema("Return full JSON instead of compact text."),
         }, ["to", "type"]),
@@ -1249,10 +1372,20 @@ export function createActorMessageToolDefinition(deps = {}) {
                 const senderStatus = assertRunAccessibleToContext(sender.value, ctx);
                 if (address.kind === "session") {
                     if (!senderStatus.ownerId) {
-                        throw new Error(`message to session:${address.value} requires sender run owner ${address.value}; got no owner.`);
+                        throw sessionMismatchError({
+                            currentSession: undefined,
+                            expectedSession: address.value,
+                            run: sender.value,
+                            target: `session:${address.value}`,
+                        });
                     }
                     if (senderStatus.ownerId !== address.value) {
-                        throw new Error(`message to session:${address.value} requires sender run owner ${address.value}; got ${senderStatus.ownerId}.`);
+                        throw sessionMismatchError({
+                            currentSession: String(senderStatus.ownerId),
+                            expectedSession: address.value,
+                            run: sender.value,
+                            target: `session:${address.value}`,
+                        });
                     }
                 }
                 result = AsyncRuns.appendRunOutboxEvent(sender.value, {
@@ -1274,14 +1407,18 @@ export function createActorMessageToolDefinition(deps = {}) {
             else {
                 throw new Error(`message currently supports run:<id>, branch:<run>/<branch>, room:<run>, tool:<name>, coordinator, and session:<id> destinations; unsupported destination: ${message.to}`);
             }
+            const nextActions = actorMessageNextActions(message, result);
+            const resultWithNext = nextActions.length
+                ? { ...result, next_actions: nextActions }
+                : result;
             return {
                 content: [
                     {
                         type: "text",
-                        text: maybeJsonText({ message, result }, input.verbose === true, compactActorMessageResult(message, result)),
+                        text: maybeJsonText({ message, result: resultWithNext }, input.verbose === true, compactActorMessageResult(message, resultWithNext)),
                     },
                 ],
-                details: { message, result },
+                details: { message, result: resultWithNext },
             };
         },
     };

package/dist/skills/actors/SKILL.md

@@ -1,13 +1,13 @@
 ---
 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.
+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.
 metadata:
-  version: 0.30.2
+  version: 0.32.0
 ---
 
 # Actors (pi-actors)
 
-`pi-actors` turns trusted local capabilities into addressable actors. This skill is the compact operator/reference layer for the extension itself: tools, nouns, lifecycle, message protocol, recipes, and common edge cases. It is not a multi-agent strategy guide; use a swarm skill for decomposition, quorum design, reviewer lenses, and consensus methodology.
+`pi-actors` turns trusted local capabilities into addressable actors. This skill is the required practical layer for any non-trivial pi-actors use or repo change: tools, nouns, lifecycle, message protocol, recipes, and common edge cases. It is not a multi-agent strategy guide; use a swarm skill for decomposition, quorum design, reviewer lenses, and consensus methodology.
 
 Maintain this skill as the extension's agent-facing manual. When implementation changes reveal new durable mechanics, invariants, warnings, or safer operating patterns, update this skill alongside code/docs so future agents learn the current actor model instead of rediscovering it.
 
@@ -39,15 +39,16 @@ Trusted local capability
 
 - **Command template**: portable execution graph. String leaf, sequence array, or object node with controls.
 - **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>`.
+- **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, and artifacts.
 - **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.
+- **Mailbox**: interaction contract: message types the actor accepts/emits.
+- **Advanced group/coordination surfaces**: `branch:<run>/<branch>`, `room:<run>`, `coordinator`, `session:<id>`, and communication snapshots exist for multi-actor workflows and diagnostics; do not make them the default mental model.
 
 ## Three Verbs
 
+Actor-mode trigger: if work may outlive this turn, needs steering/follow-up/artifacts, runs as a service, fans out, or should be resumed/inspected later, use `spawn → message → inspect` instead of ad hoc shell backgrounding. Keep short foreground checks as normal tools.
+
 ### `spawn` — create a run actor
 
 Use for long work, background services, subagents, fanout, pipelines, and reusable recipes.
@@ -84,8 +85,9 @@ Envelope fields:
 
 - Required: `to`, `type`.
 - Useful: `summary`, `body`, `from`, `reply_to`, `correlation_id`, `metadata`.
-- Addresses: `run:<id>`, `branch:<run>/<branch>`, `room:<run>`, `tool:<name>`, `coordinator`, `session:<id>`.
-- Room posts require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
+- Core addresses: `run:<id>`, `tool:<name>`.
+- Advanced addresses: `branch:<run>/<branch>`, `room:<run>` for group timeline/roster, `coordinator`, `session:<id>`.
+- Group posts to `room:<run>` require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
 - Runtime termination message: `control.kill` is the only documented actor message that kills a run. `control.stop` and `control.cancel` are actor-local mailbox vocabulary only when a recipe declares and handles them. Terminal retention messages: `control.archive`, `control.prune`.
 - Long-lived child processes should remain in the run-owned process group unless the recipe implements an explicit daemon termination bridge; do not leave unowned detached services behind `control.kill`.
 
@@ -97,12 +99,7 @@ Check `inspect view=mailbox` before domain-specific messages.
 { "target": "run:repo-health", "view": "status" }
 { "target": "run:repo-health", "view": "tail", "lines": "80" }
 { "target": "run:repo-health", "view": "messages" }
-{ "target": "run:repo-health", "view": "communication" }
 { "target": "run:repo-health", "view": "artifacts" }
-{ "target": "room:repo-health", "view": "status" }
-{ "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" }
@@ -114,10 +111,10 @@ Views:
 - `status`: lifecycle, pid, values, progress, result, compact summary.
 - `tail`: recent stdout/stderr/log tail.
 - `messages`: actor messages emitted by the run, or room timeline entries for `room:*`.
-- `communication`: run/branch communication snapshot with self/root/default-room/member/contact hints.
-- `roster`: room member list with address, role, parent, caps, claim, status, and last seen.
-- `contacts`: roster-derived direct-message targets without full roster metadata.
-- `previews`: TUI-ready bounded room message previews with timestamp/from/to/type/summary/body_preview.
+- Advanced `communication`: run/branch group-coordination snapshot with self/root/default-room/member/contact hints.
+- Advanced `roster`: room member list with address, role, parent, caps, claim, status, and last seen.
+- Advanced `contacts`: roster-derived direct-message targets without full roster metadata.
+- Advanced `previews`: TUI-ready bounded group-message previews with timestamp/from/to/type/summary/body_preview.
 - `mailbox`: declared accepts/emits contract for runs; queued direct branch inbox messages for `branch:<run>/<branch>` with `id`, status, route/type, and queue/handling timestamps.
 - `files`: run state directory file list.
 - `artifacts`: declared artifact paths/status.
@@ -216,13 +213,13 @@ Only matching filename ids compete. Higher priority shadows lower priority; with
 Muscle-memory lens: pi-actors has two durable executable-memory layers.
 
 1. `~/.pi/agent/recipes/*.json` and `*.md` are the agent's active capability memory. Every recipe in that directory becomes an easy-to-call tool automatically and survives into later sessions. Descriptions matter here because they become the tool's operator-facing title/context.
-2. `~/.pi/agent/recipes/candidates/*.json` is candidate memory captured from successful inline `spawn template=...` runs. Candidates are not registered tools and do not enter the injected tool surface. They remain reusable by explicit path, e.g. `spawn file="~/.pi/agent/recipes/candidates/<name>.json"`, and can be promoted by moving or copying one level up into `~/.pi/agent/recipes`.
+2. `~/.pi/agent/recipes/candidates/*.json` is draft memory captured from successful inline `spawn template=...` runs. The directory name is retained for compatibility; treat these as drafts, not active tools. Drafts do not enter the injected tool surface. They remain reusable by explicit path, e.g. `spawn file="~/.pi/agent/recipes/candidates/<name>.json"`, and can be promoted by moving or copying one level up into `~/.pi/agent/recipes`.
 
-Agents grow active memory by calling `register_tool` or by deliberate recipe-file edits. They grow candidate memory by trying ad hoc actors successfully. Treat both as executable habits: candidates are the workbench/proving ground; root recipes are promoted muscle memory.
+Agents grow active memory by calling `register_tool` or by deliberate recipe-file edits. They grow draft memory by trying ad hoc actors successfully. Treat both as executable habits: drafts are the workbench/proving ground; root recipes are promoted muscle memory.
 
 Usage lens: user recipes may carry extension-maintained launch metadata such as `usage.calls` and `usage.last_called`. The extension increments the counter when it starts that concrete recipe; agents should not hand-edit counters as part of normal recipe maintenance. Treat usage as evidence for usefulness analysis: heavily used recipes are good candidates for promotion, documentation, or stronger tests; unused recipes are cleanup candidates. Do not use failure counts as a primary usefulness signal because failures may reflect bad caller judgment rather than bad recipes. Do not delete or demote solely from counters without operator approval.
 
-Promotion lens: successful transient/ad hoc actor runs are evidence, not commands. Inline spawns leave candidate recipes as replayable evidence, not active tools. If a candidate is repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by moving/copying it into `~/.pi/agent/recipes` or by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not auto-register every success; do not promote temp paths, secrets, one-off prompts, or project-private assumptions without normalization and approval.
+Promotion lens: successful transient/ad hoc actor runs are evidence, not commands. Inline spawns leave draft recipes as replayable evidence, not active tools. If a draft is repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by moving/copying it into `~/.pi/agent/recipes` or by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not auto-register every success; do not promote temp paths, secrets, one-off prompts, or project-private assumptions without normalization and approval.
 
 Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memory set. For each stale, duplicate, too-specific, or low-value recipe, choose one explicit action: keep as a tool, move it out of the agent recipe root to retain recipe-only memory, merge into a better recipe, or delete/archive the file. Prefer moving over deletion when the recipe may still be useful as a component. Never silently remove tools during unrelated work.
 

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.30.2
+  version: 0.32.0
 ---
 
 # Swarm
@@ -30,8 +30,8 @@ Maintain this skill as a living orchestration standard. When real swarm work exp
 - `Async Run`: A local lifecycle envelope around a command-template swarm composer or utility. It owns state, logs, status, cancellation, and observability, not swarm semantics.
 - `Lens`: A deliberately narrow cognitive role assigned to one subagent, such as security, tests, architecture, economics, or operator UX.
 - `Task Card`: A bounded implementation assignment with goal, allowed files, avoided files, expected output, and validation gates.
-- `Component Capability`: An abstract adapter operation such as launcher, reviewer, verifier, merger, quorum, checkpoint, follow-up, judge, or normalizer. Swarm may target these capabilities, but local adapters bind them to concrete tools, recipes, candidate recipes, command templates, async runs, or services.
-- `Candidate Recipe`: A reusable but non-registered recipe captured from a successful inline actor spawn. It can be replayed by explicit file path and later promoted into the active tool recipe root after enough dogfood.
+- `Component Capability`: An abstract adapter operation such as launcher, reviewer, verifier, merger, quorum, checkpoint, follow-up, judge, or normalizer. Swarm may target these capabilities, but local adapters bind them to concrete tools, recipes, draft recipes, command templates, async runs, or services.
+- `Draft Recipe`: A reusable but non-registered recipe captured from a successful inline actor spawn. It can be replayed by explicit file path and later promoted into the active tool recipe root after enough dogfood. Its compatibility storage path may still include `recipes/candidates`.
 - `Coordinator Checkpoint`: A deliberate subagent pause where the subagent preserves its working context, sends a bounded question or status to the orchestrator, receives a coordinator reply, and continues in the same subagent context.
 - `Evidence Checkpoint`: A deliberate stop where a subagent records sources, assumptions, confidence, contradictions, or blocking evidence gaps before synthesis.
 - `Integrator`: The human or agent that merges isolated branches/worktrees into the shared target and owns conflict resolution.

package/docs/actor-messages.md

@@ -199,7 +199,7 @@ Recipes can declare their conversational surface:
 }
 ```
 
-The implementation supports `status`, `tail`, `messages`, `artifacts`, `files`, `mailbox`, and `communication` for `run:<id>` actors, `status`, `messages`, `previews`, `roster`, and `contacts` for `room:<run>` actors, `status`/`runs` for `coordinator`, `session:<id>`, and `session:all` actors with optional status filtering, and `status`/`schema` for registered `tool:<name>` actors. Run mailbox inspection shows recipe-declared mailbox metadata plus recent durable run inbox entries; branch mailbox inspection shows branch-local queued/claimed/handled records. Room `status` returns compact message/roster counts plus `last_message_at`, `last_message_from`, `last_message_type`, and `last_message_summary` when available, without parsing the full timeline into actor envelopes. Use `messages` for actor-envelope inspection. `inspect target=coordinator` requires a current coordinator session; use `session:<id>` or `session:all` when the session is intentionally explicit. Direct `run:<id>` and `room:<run>` inspection respects coordinator-session ownership when the current session is known. `inspect` is for decision points and diagnosis only; examples must not teach sleep-then-inspect polling.
+The implementation supports `status`, `tail`, `messages`, `artifacts`, `files`, `mailbox`, and `communication` for `run:<id>` actors, `status`, `messages`, `previews`, `roster`, and `contacts` for `room:<run>` actors, `status`/`runs` for `coordinator`, `session:<id>`, and `session:all` actors with optional status filtering, and `status`/`schema` for registered `tool:<name>` actors. Run mailbox inspection shows recipe-declared mailbox metadata plus recent durable run inbox entries; branch mailbox inspection shows branch-local queued/claimed/handled records. Room `status` returns compact message/roster counts plus `last_message_at`, `last_message_from`, `last_message_type`, and `last_message_summary` when available, without parsing the full timeline into actor envelopes. Use `messages` for actor-envelope inspection. `inspect target=coordinator` requires a current coordinator session; use `session:<id>` or `session:all` when the session is intentionally explicit. Direct `run:<id>` and `room:<run>` inspection respects coordinator-session ownership when the current session is known. Ownership denials use `reason=session_mismatch owner_session=<id> current_session=<id> hint=inspect_session:<id>`; recover by inspecting the hinted `session:<id>` instead of forcing cross-session control. `inspect` is for decision points and diagnosis only; examples must not teach sleep-then-inspect polling.
 
 ## Runtime Direction
 

package/docs/async-runs.md

@@ -6,6 +6,8 @@ Async runs are detached executions of a template recipe or inline command templa
 
 **Scope:** run id, state path, runner pid, process-group cancellation, logs, status, tail, list, script-authored actor messages, run-local control messages, cancel, force-kill, terminal result state, ambient activity indicators, and extension-owned temp storage. No scheduler, queue daemon, workflow DSL, distributed worker, or second execution language.
 
+Actor-mode trigger: choose an async run when work may outlive the current turn, needs later steering or inspection, produces artifacts/follow-ups, runs as a service, fans out, or should become repeatable recipe memory. Keep short foreground checks in ordinary tools/templates.
+
 Layer boundary: async-run configuration may inject lifecycle values such as `{run_id}` and `{state_dir}` and may choose detached execution through `async: true`, but it does not add command-template graph syntax. Recipe imports and recipe-local references belong to the template-recipe layer; status, control messages, actor messages, cancel, and kill belong to the async-run layer.
 
 ---

package/docs/tool-registry.md

@@ -10,7 +10,7 @@ The registry source is location-discovered recipes, not a live tool-only JSON fi
 
 - `~/.pi/agent/recipes/*.json` and `*.md` are the highest-priority user recipe root and the operator-managed tool set.
 - Recipes in that root are tools by location.
-- `~/.pi/agent/recipes/candidates/*.json` are captured inline-spawn candidates, not registered tools; promote one by moving or copying it up one level into `~/.pi/agent/recipes`. `inspect target=recipes view=summary` reports their count, and verbose output lists their paths/descriptions for explicit replay by file path.
+- `~/.pi/agent/recipes/candidates/*.json` stores captured inline-spawn draft recipes, not registered tools. The directory name is retained for compatibility; model-facing output calls them drafts. Promote one by moving or copying it up one level into `~/.pi/agent/recipes`. `inspect target=recipes view=summary` reports their count, and verbose output lists their paths/descriptions for explicit replay by file path.
 - Packaged pi-actors recipes are the lower-priority standard library of declarative actor config components, not automatically registered tools.
 - Ad hoc recipe files outside the user recipe root are components unless explicitly registered/copied into `~/.pi/agent/recipes`.
 - Recipe identity is the filename basename; `~/.pi/agent/recipes/docs_review.json` and `docs_review.md` both have id/tool name `docs_review`.

package/lib/observability.ts

@@ -1021,19 +1021,31 @@ function formatRecipePersistenceSuggestion(transition: RunTransition): string {
   return `\nAgent note: this actor was spawned directly and completed successfully. If this pattern fits this machine's recurring workflow, ask the operator whether to save it as a durable recipe/tool under ~/.pi/agent/recipes with register_tool. Do not auto-save without confirmation.`;
 }
 
+function formatTransitionNextActions(transition: RunTransition): string {
+  const actions = [
+    `inspect target=run:${transition.run} view=status`,
+    transition.to === "done" && Object.keys(transition.artifacts ?? {}).length > 0
+      ? `inspect target=run:${transition.run} view=artifacts`
+      : `inspect target=run:${transition.run} view=tail`,
+    `inspect target=run:${transition.run} view=messages`,
+  ].filter(Boolean);
+  return `\nNext actions: ${actions.join(" | ")}`;
+}
+
 export function formatRunTransitionMessage(transition: RunTransition): string {
   const artifacts = formatNamedArtifacts(transition.artifacts);
   const runFiles = formatRunFileList(getRunArtifacts(transition));
   const persistenceSuggestion = formatRecipePersistenceSuggestion(transition);
+  const nextActions = formatTransitionNextActions(transition);
   if (transition.to === "done")
-    return `Run ${transition.run} completed successfully.${artifacts}${runFiles}\nUse inspect target=run:${transition.run} view=status or view=tail if the result needs inspection.${persistenceSuggestion}`;
+    return `Run ${transition.run} completed successfully.${artifacts}${runFiles}${nextActions}${persistenceSuggestion}`;
   if (transition.to === "failed")
-    return `Run ${transition.run} failed.${artifacts}${runFiles}\nUse inspect target=run:${transition.run} view=status or view=tail for details.`;
+    return `Run ${transition.run} failed.${artifacts}${runFiles}${nextActions}`;
   if (transition.to === "cancelled")
-    return `Run ${transition.run} was cancelled. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
+    return `Run ${transition.run} was cancelled.${nextActions}`;
   if (transition.to === "killed")
-    return `Run ${transition.run} was force-killed. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
+    return `Run ${transition.run} was force-killed.${nextActions}`;
   if (transition.to === "exited")
-    return `Run ${transition.run} exited before writing a result. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
-  return `Run ${transition.run} finished with status ${transition.to}. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
+    return `Run ${transition.run} exited before writing a result.${nextActions}`;
+  return `Run ${transition.run} finished with status ${transition.to}.${nextActions}`;
 }

package/lib/prompts.ts

@@ -27,12 +27,12 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - ~/.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.
-- Use spawn/message/inspect for actor-level start/send/observe; avoid runtime/FIFO/outbox vocabulary in public guidance.
+- 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 status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.
 - 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.
-- Foreground tools/templates fit short work; async recipes/runs fit subagents, services, fanout, media, and long pipelines.
 - Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.
-- For deeper pi-actors guidance, inspect installed extension sources/docs/recipes; README and docs are not automatically in context.`;
+- 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 const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
   name: "Tool name in snake_case (e.g., 'transcribe')",