@llblab/pi-actors 0.28.1 → 0.29.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.29.0: Candidate Recipe Memory
+
+- `[Spawn]` Capture inline spawn templates as non-registered candidate recipes under `~/.pi/agent/recipes/candidates`, making successful ad hoc actor patterns easy to replay by explicit path and promote manually.
+- `[Inspect]` Add candidate recipe counts and verbose candidate metadata to recipe registry inspection without registering candidates as tools.
+- `[Skills]` Documented the two-layer executable memory model: candidate recipes as a proving ground and root recipes as active tool memory.
+
 ## 0.28.1: Portable Agent Protocol Hotfix
 
 - `[Docs]` Removed a machine-local private validation skill reference from the repository agent protocol so extension guidance stays portable.

package/dist/lib/paths.d.ts

@@ -8,4 +8,5 @@ export declare function getConfigPath(agentDir?: string): string;
 export declare function getExtensionTmpDir(agentDir?: string, extensionName?: string): string;
 export declare function getRunStateRoot(agentDir?: string): string;
 export declare function getRecipeRoot(agentDir?: string): string;
+export declare function getRecipeCandidateRoot(agentDir?: string): string;
 export declare function getPackagedRecipeRoot(): string;

package/dist/lib/paths.js

@@ -24,6 +24,9 @@ export function getRunStateRoot(agentDir = getAgentDir()) {
 export function getRecipeRoot(agentDir = getAgentDir()) {
     return join(agentDir, "recipes");
 }
+export function getRecipeCandidateRoot(agentDir = getAgentDir()) {
+    return join(getRecipeRoot(agentDir), "candidates");
+}
 export function getPackagedRecipeRoot() {
     const here = dirname(fileURLToPath(import.meta.url));
     const compiledRoot = resolve(here, "..", "..", "recipes");

package/dist/lib/recipe-discovery.d.ts

@@ -47,5 +47,6 @@ export declare function discoverRecipeSources(sources: RecipeDiscoverySource[]):
 export declare function discoverRecipes(roots: string[]): RecipeDiscoveryResult;
 export declare function createRecipeIntegrityManifest(result: RecipeDiscoveryResult): RecipeIntegrityManifestEntry[];
 export declare function getShadowedLaunchDiagnostic(result: RecipeDiscoveryResult, id: string): Record<string, unknown> | undefined;
+export declare function listCandidateRecipes(root: string): Array<Record<string, unknown>>;
 export declare function summarizeDiscovery(result: RecipeDiscoveryResult): Record<string, unknown>;
 export declare function toRegisteredTool(entry: DiscoveredRecipe): RegisteredTool | undefined;

package/dist/lib/recipe-discovery.js

@@ -426,6 +426,17 @@ export function getShadowedLaunchDiagnostic(result, id) {
         reason: active.invalid ? "shadowed_invalid" : "shadowed_disabled",
     };
 }
+export function listCandidateRecipes(root) {
+    return listRecipeFiles(root).map((path) => {
+        const id = RecipeReferences.getRecipeIdFromPath(path);
+        const config = RecipeReferences.readRawRecipeConfig(path);
+        return {
+            id,
+            path,
+            ...(config?.description ? { description: config.description } : {}),
+        };
+    });
+}
 export function summarizeDiscovery(result) {
     const recommendations = result.entries
         .map((entry) => recommendationForEntry(entry, result.active.get(entry.id)?.path))

package/dist/lib/tools.js

@@ -4,7 +4,7 @@
  * Owns generated runtime tool schemas and the register_tool management tool schema
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import * as ActorMessages from "./actor-messages.js";
 import * as ActorRooms from "./actor-rooms.js";
@@ -144,6 +144,8 @@ 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)}`);
     return `\n${tokens.join(" ")}`;
 }
 function compactRunMessages(messages) {
@@ -474,10 +476,13 @@ function compactRecipeRegistry(summary) {
     const diagnostics = Array.isArray(summary.diagnostics)
         ? summary.diagnostics.length
         : 0;
+    const candidates = Array.isArray(summary.candidates)
+        ? summary.candidates.length
+        : 0;
     const recommendations = Array.isArray(summary.recommendations)
         ? summary.recommendations.length
         : 0;
-    return `\nrecipes active=${active} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}`;
+    return `\nrecipes active=${active} candidates=${candidates} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}`;
 }
 function compactActorMessageResult(message, result) {
     const tokens = [
@@ -581,6 +586,40 @@ function shadowedRecipeLaunchDiagnostic(recipe) {
     ]);
     return RecipeDiscovery.getShadowedLaunchDiagnostic(discovery, recipe);
 }
+function candidateRecipeName(run) {
+    return `${run.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "spawn"}.json`;
+}
+function candidateRecipeDefaults(values) {
+    const ignored = new Set([
+        "actor_address",
+        "communication_file",
+        "default_room",
+        "run_id",
+        "state_dir",
+    ]);
+    const defaults = Object.fromEntries(Object.entries(values).filter(([key]) => !ignored.has(key)));
+    return Object.keys(defaults).length > 0 ? defaults : undefined;
+}
+function writeSpawnCandidateRecipe(input, meta) {
+    if (process.env.NODE_TEST_CONTEXT &&
+        process.env.PI_ACTORS_ENABLE_SPAWN_CANDIDATES_IN_TEST !== "1")
+        return undefined;
+    if (input.template === undefined || input.file !== undefined || input.recipe !== undefined)
+        return undefined;
+    const root = Paths.getRecipeCandidateRoot();
+    mkdirSync(root, { recursive: true });
+    const path = join(root, candidateRecipeName(String(meta.run)));
+    const defaults = candidateRecipeDefaults(meta.values);
+    const recipe = {
+        async: true,
+        description: `Candidate recipe captured from spawn run ${String(meta.run)}`,
+        ...(meta.artifacts ? { artifacts: meta.artifacts } : {}),
+        ...(defaults ? { defaults } : {}),
+        template: input.template,
+    };
+    writeFileSync(path, `${JSON.stringify(recipe, null, 2)}\n`, { flag: "wx" });
+    return path;
+}
 function enhanceSpawnRecipeError(error, recipe) {
     const diagnostic = shadowedRecipeLaunchDiagnostic(recipe);
     if (!diagnostic)
@@ -704,16 +743,20 @@ export function createSpawnToolDefinition() {
             catch (error) {
                 throw enhanceSpawnRecipeError(error, recipe);
             }
+            const candidateRecipe = writeSpawnCandidateRecipe(input, meta);
+            const details = candidateRecipe
+                ? { ...meta, candidate_recipe: candidateRecipe }
+                : meta;
             ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
             ActorRooms.writeCommunicationSnapshot(meta.state_dir, String(meta.run));
             return {
                 content: [
                     {
                         type: "text",
-                        text: maybeJsonText(meta, input.verbose === true, compactAsyncRunStatus(meta)),
+                        text: maybeJsonText(details, input.verbose === true, compactAsyncRunStatus(details)),
                     },
                 ],
-                details: meta,
+                details,
             };
         },
     };
@@ -773,7 +816,11 @@ export function createInspectToolDefinition(deps = {}) {
                     },
                     { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
                 ]);
-                const summary = RecipeDiscovery.summarizeDiscovery(discovered);
+                const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
+                const summary = {
+                    ...RecipeDiscovery.summarizeDiscovery(discovered),
+                    candidates: RecipeDiscovery.listCandidateRecipes(join(recipeRoot, "candidates")),
+                };
                 return {
                     content: [
                         {

package/dist/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.28.1
+  version: 0.29.0
 ---
 
 # Actors (pi-actors)
@@ -235,11 +235,16 @@ Priority for same-id recipes:
 
 Only matching filename ids compete. Higher priority shadows lower priority; within one priority layer, same-id JSON shadows Markdown. An invalid or `disabled: true` higher-priority recipe blocks fallback so the agent does not silently run standard-library behavior when a user override is broken or intentionally disabled.
 
-Muscle-memory lens: `~/.pi/agent/recipes/*.json` and `*.md` are the agent's capability memory. Every recipe in that directory becomes an easy-to-call tool automatically and survives into later sessions. Agents grow this memory either by calling `register_tool`, which writes recipe files there under the hood, or by deliberately editing those recipe files. Treat this directory like `MEMORY.md` for executable habits: useful local patterns belong there; packaged recipes elsewhere are reusable components, not tools.
+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`.
+
+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.
 
 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. If the run was repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not wait for UI buttons; do not auto-register every success; do not persist 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 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.
 
 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.28.1
+  version: 0.29.0
 ---
 
 # Swarm
@@ -30,7 +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, command templates, async runs, or services.
+- `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.
 - `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/tool-registry.md

@@ -10,6 +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.
 - 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/paths.ts

@@ -36,6 +36,10 @@ export function getRecipeRoot(agentDir = getAgentDir()): string {
   return join(agentDir, "recipes");
 }
 
+export function getRecipeCandidateRoot(agentDir = getAgentDir()): string {
+  return join(getRecipeRoot(agentDir), "candidates");
+}
+
 export function getPackagedRecipeRoot(): string {
   const here = dirname(fileURLToPath(import.meta.url));
   const compiledRoot = resolve(here, "..", "..", "recipes");

package/lib/recipe-discovery.ts

@@ -575,6 +575,18 @@ export function getShadowedLaunchDiagnostic(
   };
 }
 
+export function listCandidateRecipes(root: string): Array<Record<string, unknown>> {
+  return listRecipeFiles(root).map((path) => {
+    const id = RecipeReferences.getRecipeIdFromPath(path);
+    const config = RecipeReferences.readRawRecipeConfig(path);
+    return {
+      id,
+      path,
+      ...(config?.description ? { description: config.description } : {}),
+    };
+  });
+}
+
 export function summarizeDiscovery(
   result: RecipeDiscoveryResult,
 ): Record<string, unknown> {

package/lib/tools.ts

@@ -5,7 +5,7 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import * as ActorMessages from "./actor-messages.ts";
@@ -183,6 +183,7 @@ 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)}`);
   return `\n${tokens.join(" ")}`;
 }
 
@@ -574,10 +575,13 @@ 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 recommendations = Array.isArray(summary.recommendations)
     ? summary.recommendations.length
     : 0;
-  return `\nrecipes active=${active} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}`;
+  return `\nrecipes active=${active} candidates=${candidates} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} recommendations=${recommendations} diagnostics=${diagnostics}`;
 }
 
 function compactActorMessageResult(
@@ -722,6 +726,50 @@ function shadowedRecipeLaunchDiagnostic(
   return RecipeDiscovery.getShadowedLaunchDiagnostic(discovery, recipe);
 }
 
+function candidateRecipeName(run: string): string {
+  return `${run.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "spawn"}.json`;
+}
+
+function candidateRecipeDefaults(values: Record<string, unknown>): Record<string, unknown> | undefined {
+  const ignored = new Set([
+    "actor_address",
+    "communication_file",
+    "default_room",
+    "run_id",
+    "state_dir",
+  ]);
+  const defaults = Object.fromEntries(
+    Object.entries(values).filter(([key]) => !ignored.has(key)),
+  );
+  return Object.keys(defaults).length > 0 ? defaults : undefined;
+}
+
+function writeSpawnCandidateRecipe(
+  input: Record<string, unknown>,
+  meta: AsyncRuns.AsyncRunMeta,
+): string | undefined {
+  if (
+    process.env.NODE_TEST_CONTEXT &&
+    process.env.PI_ACTORS_ENABLE_SPAWN_CANDIDATES_IN_TEST !== "1"
+  )
+    return undefined;
+  if (input.template === undefined || input.file !== undefined || input.recipe !== undefined)
+    return undefined;
+  const root = Paths.getRecipeCandidateRoot();
+  mkdirSync(root, { recursive: true });
+  const path = join(root, candidateRecipeName(String(meta.run)));
+  const defaults = candidateRecipeDefaults(meta.values);
+  const recipe = {
+    async: true,
+    description: `Candidate recipe captured from spawn run ${String(meta.run)}`,
+    ...(meta.artifacts ? { artifacts: meta.artifacts } : {}),
+    ...(defaults ? { defaults } : {}),
+    template: input.template,
+  };
+  writeFileSync(path, `${JSON.stringify(recipe, null, 2)}\n`, { flag: "wx" });
+  return path;
+}
+
 function enhanceSpawnRecipeError(error: unknown, recipe: unknown): Error {
   const diagnostic = shadowedRecipeLaunchDiagnostic(recipe);
   if (!diagnostic) return error instanceof Error ? error : new Error(String(error));
@@ -911,6 +959,10 @@ export function createSpawnToolDefinition<
       } catch (error) {
         throw enhanceSpawnRecipeError(error, recipe);
       }
+      const candidateRecipe = writeSpawnCandidateRecipe(input, meta);
+      const details = candidateRecipe
+        ? { ...meta, candidate_recipe: candidateRecipe }
+        : meta;
       ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
       ActorRooms.writeCommunicationSnapshot(meta.state_dir, String(meta.run));
       return {
@@ -918,13 +970,13 @@ export function createSpawnToolDefinition<
           {
             type: "text" as const,
             text: maybeJsonText(
-              meta,
+              details,
               input.verbose === true,
-              compactAsyncRunStatus(meta),
+              compactAsyncRunStatus(details),
             ),
           },
         ],
-        details: meta,
+        details,
       };
     },
   };
@@ -1031,7 +1083,11 @@ export function createInspectToolDefinition<TContext = unknown>(
           },
           { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
         ]);
-        const summary = RecipeDiscovery.summarizeDiscovery(discovered);
+        const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
+        const summary = {
+          ...RecipeDiscovery.summarizeDiscovery(discovered),
+          candidates: RecipeDiscovery.listCandidateRecipes(join(recipeRoot, "candidates")),
+        };
         return {
           content: [
             {

package/package.json

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

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.28.1
+  version: 0.29.0
 ---
 
 # Actors (pi-actors)
@@ -235,11 +235,16 @@ Priority for same-id recipes:
 
 Only matching filename ids compete. Higher priority shadows lower priority; within one priority layer, same-id JSON shadows Markdown. An invalid or `disabled: true` higher-priority recipe blocks fallback so the agent does not silently run standard-library behavior when a user override is broken or intentionally disabled.
 
-Muscle-memory lens: `~/.pi/agent/recipes/*.json` and `*.md` are the agent's capability memory. Every recipe in that directory becomes an easy-to-call tool automatically and survives into later sessions. Agents grow this memory either by calling `register_tool`, which writes recipe files there under the hood, or by deliberately editing those recipe files. Treat this directory like `MEMORY.md` for executable habits: useful local patterns belong there; packaged recipes elsewhere are reusable components, not tools.
+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`.
+
+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.
 
 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. If the run was repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not wait for UI buttons; do not auto-register every success; do not persist 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 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.
 
 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.28.1
+  version: 0.29.0
 ---
 
 # Swarm
@@ -30,7 +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, command templates, async runs, or services.
+- `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.
 - `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.