@llblab/pi-actors 0.28.1 → 0.29.1

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.29.1: Subagent TTL Kill Hotfix
+
+- `[Coordinator]` Added `subagent_ttl_ms` / `--subagent-ttl-ms` to the room-swarm adapter so timed-out subagent `pi -p` processes are terminated instead of only awaited.
+
+## 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/coordinator.js

@@ -200,7 +200,25 @@ async function stopLocker(locker) {
             locker.child.kill("SIGTERM");
     }
 }
-function runPi(prompt, model, thinking) {
+function terminateProcessGroup(child, signal) {
+    if (!child.pid)
+        return;
+    try {
+        if (process.platform !== "win32")
+            process.kill(-child.pid, signal);
+        else
+            child.kill(signal);
+    }
+    catch {
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // Process already exited.
+        }
+    }
+}
+function runPi(prompt, model, thinking, ttlMs = 0) {
     return new Promise((resolve) => {
         const args = [
             "--tools",
@@ -216,17 +234,57 @@ function runPi(prompt, model, thinking) {
             args.push("--thinking", thinking);
         }
         args.push("-p", prompt);
-        const child = spawn("pi", args, { stdio: ["ignore", "pipe", "pipe"] });
+        const child = spawn("pi", args, {
+            detached: process.platform !== "win32",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
         let stdout = "";
         let stderr = "";
+        let settled = false;
+        let timedOut = false;
+        let ttlTimer;
+        let forceTimer;
+        const clearTimers = () => {
+            if (ttlTimer)
+                clearTimeout(ttlTimer);
+            if (forceTimer)
+                clearTimeout(forceTimer);
+        };
+        if (ttlMs > 0) {
+            ttlTimer = setTimeout(() => {
+                timedOut = true;
+                stderr += `\nSubagent TTL expired after ${ttlMs}ms; terminating process group.\n`;
+                terminateProcessGroup(child, "SIGTERM");
+                forceTimer = setTimeout(() => terminateProcessGroup(child, "SIGKILL"), 1000);
+            }, ttlMs);
+        }
         child.stdout.on("data", (chunk) => {
             stdout += chunk;
         });
         child.stderr.on("data", (chunk) => {
             stderr += chunk;
         });
-        child.on("close", (code) => resolve({ code, stdout, stderr }));
-        child.on("error", (error) => resolve({ code: 1, stdout, stderr: String(error) }));
+        child.on("close", (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimers();
+            resolve({
+                code: timedOut ? 124 : (code ?? (signal ? 1 : 0)),
+                killed: timedOut,
+                signal,
+                stderr,
+                stdout,
+                timed_out: timedOut,
+            });
+        });
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimers();
+            resolve({ code: 1, stdout, stderr: String(error) });
+        });
     });
 }
 async function readRoomTranscript(config) {
@@ -268,7 +326,7 @@ async function synthesize(config, locker) {
     }
     const transcript = await readRoomTranscript(config);
     const prompt = `Synthesize this transcript into a concise Markdown artifact. Mission: ${config.mission}. Include: Title, Consensus, Roles, Protocol, Final Artifact Shape, Next Actions, Open Questions. Use only the transcript evidence below.\n\nTRANSCRIPT:\n${transcript.slice(-24000)}`;
-    const result = await runPi(prompt, config.model, config.thinking);
+    const result = await runPi(prompt, config.model, config.thinking, config.subagentTtlMs);
     const output = result.stdout.trim();
     const diagnostics = config.stats
         ? `\n\n## Diagnostics\n\nparticipant_attempts=${config.stats.participantAttempts}\nparticipant_success=${config.stats.participantSuccess}\nparticipant_failures=${config.stats.participantFailures}\nsynthesis_code=${result.code}\ntranscript_messages=${transcript.trim() ? transcript.split("\n").length : 0}\n`
@@ -371,7 +429,7 @@ async function executeParticipantPrompt(role, basePrompt, config) {
             "\nPlease acknowledge and address these direct messages in your response.\n";
         finalPrompt += inboxSection;
     }
-    const result = await runPi(finalPrompt, config.model, config.thinking);
+    const result = await runPi(finalPrompt, config.model, config.thinking, config.subagentTtlMs);
     if (claimedIds.length > 0) {
         const finalStatus = result.code === 0 ? "handled" : "failed";
         await updateInboxMessagesStatus(config.runId, branchName, claimedIds, finalStatus);
@@ -399,13 +457,13 @@ async function participantJoin(role, config) {
     const displayName = role.name;
     const address = `branch:${config.runId}/${role.name}`;
     const joinPrompt = `You are ${displayName}, ${role.persona}. Mission: ${config.mission}. Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.join', summary='${displayName} joined', body JSON {"role":${JSON.stringify(role.persona)},"display":${JSON.stringify(displayName)},"caps":["coordination","synthesis"],"claim":"coordinate on mission"}. Then print one short line.`;
-    await runPi(joinPrompt, config.model, config.thinking);
+    await runPi(joinPrompt, config.model, config.thinking, config.subagentTtlMs);
 }
 async function participantLeave(role, config) {
     const displayName = role.name;
     const address = `branch:${config.runId}/${role.name}`;
     const leavePrompt = `Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.leave', summary='${displayName} left', body='finished coordinated work'. Then print goodbye.`;
-    await runPi(leavePrompt, config.model, config.thinking);
+    await runPi(leavePrompt, config.model, config.thinking, config.subagentTtlMs);
 }
 // 1. consensus / swarm mode: iterative chat in a room
 async function runConsensus(config, locker) {
@@ -559,6 +617,7 @@ export async function runCoordinator(argv = process.argv.slice(2)) {
         artifactPath: arg("artifact-path", ""),
         locker: boolArg("locker", false),
         lockerLeaseMs: numberArg("locker-lease-ms", 600000),
+        subagentTtlMs: numberArg("subagent-ttl-ms", 0),
         stats: {
             participantAttempts: 0,
             participantSuccess: 0,

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/recipes/pipeline-room-swarm.json

@@ -11,6 +11,7 @@
     "delay:int",
     "locker:bool",
     "locker_lease_ms:int",
+    "subagent_ttl_ms:int",
     "artifact_path:path",
     "repo:path"
   ],
@@ -23,6 +24,7 @@
     "delay": "10",
     "locker": "false",
     "locker_lease_ms": "600000",
+    "subagent_ttl_ms": "0",
     "artifact_path": "{state_dir}/room-swarm-artifact.md",
     "repo": "~/.pi/agent/extensions/pi-actors"
   },
@@ -44,5 +46,5 @@
       "run.failed"
     ]
   },
-  "template": "{repo}/scripts/coordinator.mjs --run-id={run_id} --mode={mode} --mission={mission} --model={model} --thinking={thinking} --roles={roles} --roles-path={roles_path} --rounds={rounds} --delay={delay} --locker={locker} --locker-lease-ms={locker_lease_ms} --artifact-path={artifact_path}"
+  "template": "{repo}/scripts/coordinator.mjs --run-id={run_id} --mode={mode} --mission={mission} --model={model} --thinking={thinking} --roles={roles} --roles-path={roles_path} --rounds={rounds} --delay={delay} --locker={locker} --locker-lease-ms={locker_lease_ms} --subagent-ttl-ms={subagent_ttl_ms} --artifact-path={artifact_path}"
 }

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.1
 ---
 
 # 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.
 
@@ -297,7 +302,7 @@ Use packaged recipes by name with `spawn file=<name>` for async actors, or regis
 - [`pipeline-docs-maintenance`](../../recipes/pipeline-docs-maintenance.json): docs index/review/planning → maintenance artifact.
 - Artifacts: [`pipeline-artifact-report`](../../recipes/pipeline-artifact-report.json), [`pipeline-artifact-write`](../../recipes/pipeline-artifact-write.json), [`pipeline-artifact-bundle`](../../recipes/pipeline-artifact-bundle.json).
 - Review gates: [`pipeline-quorum-review`](../../recipes/pipeline-quorum-review.json), [`pipeline-review-readiness`](../../recipes/pipeline-review-readiness.json).
-- Task-first workflows: [`pipeline-architect-coordinator`](../../recipes/pipeline-architect-coordinator.json), [`pipeline-research-synthesis`](../../recipes/pipeline-research-synthesis.json), [`pipeline-development-tasking`](../../recipes/pipeline-development-tasking.json), [`pipeline-checkpoint-continuation`](../../recipes/pipeline-checkpoint-continuation.json), [`pipeline-media-library`](../../recipes/pipeline-media-library.json), [`pipeline-room-swarm`](../../recipes/pipeline-room-swarm.json). For room swarms, choose `mode` from `consensus`, `pipeline`, `fanout`, or `pool`; prefer `roles_path` for custom role JSON and keep role `name` ASCII-safe for branch addresses. Use `locker=true` when the swarm needs a coordinator-locker-backed artifact lock and journal.
+- Task-first workflows: [`pipeline-architect-coordinator`](../../recipes/pipeline-architect-coordinator.json), [`pipeline-research-synthesis`](../../recipes/pipeline-research-synthesis.json), [`pipeline-development-tasking`](../../recipes/pipeline-development-tasking.json), [`pipeline-checkpoint-continuation`](../../recipes/pipeline-checkpoint-continuation.json), [`pipeline-media-library`](../../recipes/pipeline-media-library.json), [`pipeline-room-swarm`](../../recipes/pipeline-room-swarm.json). For room swarms, choose `mode` from `consensus`, `pipeline`, `fanout`, or `pool`; prefer `roles_path` for custom role JSON and keep role `name` ASCII-safe for branch addresses. Set `subagent_ttl_ms` when participant processes need a hard kill budget. Use `locker=true` when the swarm needs a coordinator-locker-backed artifact lock and journal.
 
 ### Utilities
 

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.1
 ---
 
 # 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/recipe-library.md

@@ -84,7 +84,7 @@ Pipeline recipes demonstrate second-order composition:
 - `recipes/pipeline-development-tasking.json`: Plan → task card → critique → integrator handoff.
 - `recipes/pipeline-docs-maintenance.json`: Docs index → documentation review → maintenance plan → artifact report.
 - `recipes/pipeline-media-library.json`: Playlist build → media-library artifact report.
-- `recipes/pipeline-room-swarm.json`: Room participants join `room:<run>`, coordinate over repeated room-visible rounds, leave cleanly, and synthesize the room transcript into a caller-provided artifact path. Supported coordinator modes are `consensus`, `pipeline`, `fanout`, and `pool`; unknown modes fail closed instead of silently running consensus. Keep model/thinking/mission policy caller-owned. Custom roles can be supplied with `roles_path` as a JSON array of `{ "name", "persona" }` objects; `name` stays ASCII-safe for `branch:<run>/<name>` addresses and debugger output remains plain and name-driven. The packaged swarm uses contacts for peer awareness but does not rely on direct branch delivery unless a caller-specific worker protocol consumes branch envelopes. Set `locker=true` to compose a local `coordinator-locker` cell under `{state_dir}/locker` for artifact ownership, resource lease locks, and a decision journal without merging locker policy into the room-participant script.
+- `recipes/pipeline-room-swarm.json`: Room participants join `room:<run>`, coordinate over repeated room-visible rounds, leave cleanly, and synthesize the room transcript into a caller-provided artifact path. Supported coordinator modes are `consensus`, `pipeline`, `fanout`, and `pool`; unknown modes fail closed instead of silently running consensus. Keep model/thinking/mission policy caller-owned. Custom roles can be supplied with `roles_path` as a JSON array of `{ "name", "persona" }` objects; `name` stays ASCII-safe for `branch:<run>/<name>` addresses and debugger output remains plain and name-driven. The packaged swarm uses contacts for peer awareness but does not rely on direct branch delivery unless a caller-specific worker protocol consumes branch envelopes. Set `subagent_ttl_ms` to a positive millisecond budget when participant `pi -p` processes must be killed instead of awaited indefinitely. Set `locker=true` to compose a local `coordinator-locker` cell under `{state_dir}/locker` for artifact ownership, resource lease locks, and a decision journal without merging locker policy into the room-participant script.
 - `recipes/pipeline-artifact-report.json`: Normalize → artifact-shaped output → actor-message-shaped record. This pipeline prepares a candidate artifact and emits `artifact.prepared`/`artifact.blocked`; the `artifact_path` is a target path, not a guarantee that the file was written.
 - `recipes/pipeline-artifact-write.json`: Normalize → artifact-shaped output → deterministic artifact write → actor-message-shaped record. Use only when the caller explicitly wants filesystem writes; `write_mode` is `create`, `overwrite`, or `append`.
 - `recipes/pipeline-artifact-bundle.json`: Optional validation → deterministic artifact write → machine-readable manifest generation → deterministic manifest write → actor-message-shaped record. Use when the caller explicitly wants a filesystem handoff bundle with both artifact and manifest paths.

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/coordinator.ts

@@ -220,7 +220,21 @@ async function stopLocker(locker) {
   }
 }
 
-function runPi(prompt, model, thinking) {
+function terminateProcessGroup(child, signal) {
+  if (!child.pid) return;
+  try {
+    if (process.platform !== "win32") process.kill(-child.pid, signal);
+    else child.kill(signal);
+  } catch {
+    try {
+      child.kill(signal);
+    } catch {
+      // Process already exited.
+    }
+  }
+}
+
+function runPi(prompt, model, thinking, ttlMs = 0) {
   return new Promise((resolve) => {
     const args = [
       "--tools",
@@ -237,19 +251,53 @@ function runPi(prompt, model, thinking) {
     }
     args.push("-p", prompt);
 
-    const child = spawn("pi", args, { stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawn("pi", args, {
+      detached: process.platform !== "win32",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
     let stdout = "";
     let stderr = "";
+    let settled = false;
+    let timedOut = false;
+    let ttlTimer;
+    let forceTimer;
+    const clearTimers = () => {
+      if (ttlTimer) clearTimeout(ttlTimer);
+      if (forceTimer) clearTimeout(forceTimer);
+    };
+    if (ttlMs > 0) {
+      ttlTimer = setTimeout(() => {
+        timedOut = true;
+        stderr += `\nSubagent TTL expired after ${ttlMs}ms; terminating process group.\n`;
+        terminateProcessGroup(child, "SIGTERM");
+        forceTimer = setTimeout(() => terminateProcessGroup(child, "SIGKILL"), 1000);
+      }, ttlMs);
+    }
     child.stdout.on("data", (chunk) => {
       stdout += chunk;
     });
     child.stderr.on("data", (chunk) => {
       stderr += chunk;
     });
-    child.on("close", (code) => resolve({ code, stdout, stderr }));
-    child.on("error", (error) =>
-      resolve({ code: 1, stdout, stderr: String(error) }),
-    );
+    child.on("close", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      resolve({
+        code: timedOut ? 124 : (code ?? (signal ? 1 : 0)),
+        killed: timedOut,
+        signal,
+        stderr,
+        stdout,
+        timed_out: timedOut,
+      });
+    });
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      resolve({ code: 1, stdout, stderr: String(error) });
+    });
   });
 }
 
@@ -294,7 +342,7 @@ async function synthesize(config, locker) {
   }
   const transcript = await readRoomTranscript(config);
   const prompt = `Synthesize this transcript into a concise Markdown artifact. Mission: ${config.mission}. Include: Title, Consensus, Roles, Protocol, Final Artifact Shape, Next Actions, Open Questions. Use only the transcript evidence below.\n\nTRANSCRIPT:\n${transcript.slice(-24000)}`;
-  const result = await runPi(prompt, config.model, config.thinking);
+  const result = await runPi(prompt, config.model, config.thinking, config.subagentTtlMs);
   const output = result.stdout.trim();
   const diagnostics = config.stats
     ? `\n\n## Diagnostics\n\nparticipant_attempts=${config.stats.participantAttempts}\nparticipant_success=${config.stats.participantSuccess}\nparticipant_failures=${config.stats.participantFailures}\nsynthesis_code=${result.code}\ntranscript_messages=${transcript.trim() ? transcript.split("\n").length : 0}\n`
@@ -417,7 +465,7 @@ async function executeParticipantPrompt(role, basePrompt, config) {
     finalPrompt += inboxSection;
   }
 
-  const result = await runPi(finalPrompt, config.model, config.thinking);
+  const result = await runPi(finalPrompt, config.model, config.thinking, config.subagentTtlMs);
 
   if (claimedIds.length > 0) {
     const finalStatus = result.code === 0 ? "handled" : "failed";
@@ -454,14 +502,14 @@ async function participantJoin(role, config) {
   const displayName = role.name;
   const address = `branch:${config.runId}/${role.name}`;
   const joinPrompt = `You are ${displayName}, ${role.persona}. Mission: ${config.mission}. Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.join', summary='${displayName} joined', body JSON {"role":${JSON.stringify(role.persona)},"display":${JSON.stringify(displayName)},"caps":["coordination","synthesis"],"claim":"coordinate on mission"}. Then print one short line.`;
-  await runPi(joinPrompt, config.model, config.thinking);
+  await runPi(joinPrompt, config.model, config.thinking, config.subagentTtlMs);
 }
 
 async function participantLeave(role, config) {
   const displayName = role.name;
   const address = `branch:${config.runId}/${role.name}`;
   const leavePrompt = `Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.leave', summary='${displayName} left', body='finished coordinated work'. Then print goodbye.`;
-  await runPi(leavePrompt, config.model, config.thinking);
+  await runPi(leavePrompt, config.model, config.thinking, config.subagentTtlMs);
 }
 
 // 1. consensus / swarm mode: iterative chat in a room
@@ -646,6 +694,7 @@ const config = {
   artifactPath: arg("artifact-path", ""),
   locker: boolArg("locker", false),
   lockerLeaseMs: numberArg("locker-lease-ms", 600000),
+  subagentTtlMs: numberArg("subagent-ttl-ms", 0),
   stats: {
     participantAttempts: 0,
     participantSuccess: 0,

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.1",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/recipes/pipeline-room-swarm.json

@@ -11,6 +11,7 @@
     "delay:int",
     "locker:bool",
     "locker_lease_ms:int",
+    "subagent_ttl_ms:int",
     "artifact_path:path",
     "repo:path"
   ],
@@ -23,6 +24,7 @@
     "delay": "10",
     "locker": "false",
     "locker_lease_ms": "600000",
+    "subagent_ttl_ms": "0",
     "artifact_path": "{state_dir}/room-swarm-artifact.md",
     "repo": "~/.pi/agent/extensions/pi-actors"
   },
@@ -44,5 +46,5 @@
       "run.failed"
     ]
   },
-  "template": "{repo}/scripts/coordinator.mjs --run-id={run_id} --mode={mode} --mission={mission} --model={model} --thinking={thinking} --roles={roles} --roles-path={roles_path} --rounds={rounds} --delay={delay} --locker={locker} --locker-lease-ms={locker_lease_ms} --artifact-path={artifact_path}"
+  "template": "{repo}/scripts/coordinator.mjs --run-id={run_id} --mode={mode} --mission={mission} --model={model} --thinking={thinking} --roles={roles} --roles-path={roles_path} --rounds={rounds} --delay={delay} --locker={locker} --locker-lease-ms={locker_lease_ms} --subagent-ttl-ms={subagent_ttl_ms} --artifact-path={artifact_path}"
 }

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.1
 ---
 
 # 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.
 
@@ -297,7 +302,7 @@ Use packaged recipes by name with `spawn file=<name>` for async actors, or regis
 - [`pipeline-docs-maintenance`](../../recipes/pipeline-docs-maintenance.json): docs index/review/planning → maintenance artifact.
 - Artifacts: [`pipeline-artifact-report`](../../recipes/pipeline-artifact-report.json), [`pipeline-artifact-write`](../../recipes/pipeline-artifact-write.json), [`pipeline-artifact-bundle`](../../recipes/pipeline-artifact-bundle.json).
 - Review gates: [`pipeline-quorum-review`](../../recipes/pipeline-quorum-review.json), [`pipeline-review-readiness`](../../recipes/pipeline-review-readiness.json).
-- Task-first workflows: [`pipeline-architect-coordinator`](../../recipes/pipeline-architect-coordinator.json), [`pipeline-research-synthesis`](../../recipes/pipeline-research-synthesis.json), [`pipeline-development-tasking`](../../recipes/pipeline-development-tasking.json), [`pipeline-checkpoint-continuation`](../../recipes/pipeline-checkpoint-continuation.json), [`pipeline-media-library`](../../recipes/pipeline-media-library.json), [`pipeline-room-swarm`](../../recipes/pipeline-room-swarm.json). For room swarms, choose `mode` from `consensus`, `pipeline`, `fanout`, or `pool`; prefer `roles_path` for custom role JSON and keep role `name` ASCII-safe for branch addresses. Use `locker=true` when the swarm needs a coordinator-locker-backed artifact lock and journal.
+- Task-first workflows: [`pipeline-architect-coordinator`](../../recipes/pipeline-architect-coordinator.json), [`pipeline-research-synthesis`](../../recipes/pipeline-research-synthesis.json), [`pipeline-development-tasking`](../../recipes/pipeline-development-tasking.json), [`pipeline-checkpoint-continuation`](../../recipes/pipeline-checkpoint-continuation.json), [`pipeline-media-library`](../../recipes/pipeline-media-library.json), [`pipeline-room-swarm`](../../recipes/pipeline-room-swarm.json). For room swarms, choose `mode` from `consensus`, `pipeline`, `fanout`, or `pool`; prefer `roles_path` for custom role JSON and keep role `name` ASCII-safe for branch addresses. Set `subagent_ttl_ms` when participant processes need a hard kill budget. Use `locker=true` when the swarm needs a coordinator-locker-backed artifact lock and journal.
 
 ### Utilities
 

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.1
 ---
 
 # 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.