@llblab/pi-actors 0.30.2 → 0.32.0

package/lib/tools.ts

@@ -187,12 +187,23 @@ function formatFailureCount(value: unknown): number | undefined {
   return Array.isArray(value) ? value.length : undefined;
 }
 
+function actorRunNextActions(run: unknown): string[] {
+  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: unknown): string {
   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) tokens.push(`tool=${String(status.tool)}`);
@@ -211,8 +222,11 @@ function compactAsyncRunStatus(value: unknown): string {
     tokens.push(`failures=${failures}`);
   if (result.code !== undefined) 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(" ")}`;
 }
 
@@ -437,6 +451,15 @@ function compactArtifactPath(value: unknown): string {
   return String(record.path ?? "<missing>");
 }
 
+function artifactNextActions(run: unknown, artifacts: Record<string, unknown>): string[] {
+  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: Record<string, unknown>): string {
   const run = String(status.run ?? "<unknown>");
   const artifacts = asRecord(status.artifacts);
@@ -455,7 +478,11 @@ function compactActorFiles(status: Record<string, unknown>): string {
         .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(
@@ -607,9 +634,43 @@ function compactRecipeDoctor(summary: Record<string, unknown>): string {
       `${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 as string[])
+    : [];
+  if (nextActions.length > 0) lines[0] = `${lines[0]}${compactNextActions(nextActions)}`;
   return `\n${lines.join("\n")}`;
 }
 
+function recipeRegistryNextActions(summary: Record<string, unknown>, view: string): string[] {
+  const actions: string[] = [];
+  const drafts = Array.isArray(summary.drafts)
+    ? (summary.drafts as Array<Record<string, unknown>>)
+    : [];
+  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: string[]): string {
+  return actions.length
+    ? ` next=${actions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`
+    : "";
+}
+
 function compactRecipeRegistry(summary: Record<string, unknown>): string {
   const active = Array.isArray(summary.active) ? summary.active.length : 0;
   const shadowed = Array.isArray(summary.shadowed)
@@ -622,13 +683,43 @@ function compactRecipeRegistry(summary: Record<string, unknown>): string {
   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 as string[])
+    : [];
+  return `\nrecipes active=${active} drafts=${drafts} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}${compactNextActions(nextActions)}`;
+}
+
+function actorMessageNextActions(
+  message: ActorMessages.ActorMessage,
+  result: Record<string, unknown>,
+): string[] {
+  const actions: string[] = [];
+  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(
@@ -656,6 +747,11 @@ function compactActorMessageResult(
   if (result.delivery_error) {
     tokens.push(`delivery_error=${compactPreview(result.delivery_error, 96)}`);
   }
+  const nextActions = Array.isArray(result.next_actions)
+    ? (result.next_actions as string[])
+    : actorMessageNextActions(message, result);
+  if (nextActions.length > 0)
+    tokens.push(`next=${nextActions.map((action) => action.replaceAll(/\s+/g, "_")).join("|")}`);
   return `\n${tokens.join(" ")}`;
 }
 
@@ -818,7 +914,7 @@ function writeSpawnCandidateRecipe(
   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,
@@ -942,7 +1038,7 @@ export function createSpawnToolDefinition<
     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.",
+      "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(
@@ -1023,9 +1119,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 {
@@ -1067,6 +1168,33 @@ function requireContextSessionId(ctx: unknown, actor: string): string {
   return sessionId;
 }
 
+function sessionMismatchError(input: {
+  currentSession?: string;
+  expectedSession?: string;
+  run?: string;
+  target?: string;
+}): Error {
+  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: string,
   ctx: unknown,
@@ -1074,18 +1202,11 @@ function assertRunAccessibleToContext(
   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",
-        run: runId,
-      },
-    );
+    throw sessionMismatchError({
+      currentSession: sessionId,
+      expectedSession: String(status.ownerId),
+      run: runId,
+    });
   }
   return status;
 }
@@ -1103,7 +1224,7 @@ export function createInspectToolDefinition<TContext = unknown>(
     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.",
+      "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."),
@@ -1111,13 +1232,13 @@ export function createInspectToolDefinition<TContext = unknown>(
           "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>.",
+          "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.",
+          "Inspection view. Core run views: status, tail, messages, artifacts, files, mailbox. Advanced views include communication, roster, and contacts.",
         ),
       },
       ["target", "view"],
@@ -1152,12 +1273,19 @@ export function createInspectToolDefinition<TContext = unknown>(
           { 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: [
             {
@@ -1471,7 +1599,14 @@ export function createInspectToolDefinition<TContext = unknown>(
               | undefined,
           );
           const details = artifactManifest
-            ? { ...status, artifact_manifest: artifactManifest }
+            ? {
+                ...status,
+                artifact_manifest: artifactManifest,
+                next_actions: artifactNextActions(
+                  status.run ?? runId,
+                  asRecord(status.artifacts),
+                ),
+              }
             : status;
           return {
             content: [
@@ -1557,7 +1692,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
     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.",
+      "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([
@@ -1579,7 +1714,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
         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>.",
+          "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.",
@@ -1748,14 +1883,20 @@ export function createActorMessageToolDefinition<TContext = unknown>(
         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, {
@@ -1779,18 +1920,22 @@ export function createActorMessageToolDefinition<TContext = unknown>(
           `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" as const,
             text: maybeJsonText(
-              { message, result },
+              { message, result: resultWithNext },
               input.verbose === true,
-              compactActorMessageResult(message, result),
+              compactActorMessageResult(message, resultWithNext),
             ),
           },
         ],
-        details: { message, result },
+        details: { message, result: resultWithNext },
       };
     },
   };

package/package.json

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

package/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/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.