@llblab/pi-actors 0.46.0 → 0.47.0

package/dist/skills/swarm/references/review-swarms.md

@@ -0,0 +1,115 @@
+# Review Swarms
+
+Use this reference for independent review, delegated audit, research synthesis, quorum judgement, and post-merge review. Generic actor execution remains owned by `actors`.
+
+## Select breadth or confidence
+
+```text
+Different lenses on one target → breadth → lens swarm
+Same exact claim, independent judges → confidence → quorum
+Important lenses each need repeated judges → breadth + confidence → lens swarms of quorums
+```
+
+Use the smallest shape that covers the decision risk. A lens swarm of quorums is reserved for high-impact security, financial, governance, migration, or release decisions.
+
+Primary Recipes:
+
+- `swarm/lens-review` for parallel risk lenses plus verification, merge, judge, and normalized result;
+- `swarm/quorum-review` for one prompt judged independently by explicitly selected models;
+- `swarm/research-synthesis` for plan, evidence map, contradictions, verification, and risk-first synthesis;
+- `swarm/architect` for competing directions and one validated smallest next slice;
+- `swarm/review-readiness` for a multi-lens ship/readiness verdict.
+
+## Lens selection
+
+Choose lenses from plausible failure modes, not from a fixed catalog. Common software lenses include correctness, architecture, security, tests, concurrency, data integrity, performance, operator UX, accessibility, maintainability, documentation, and release risk.
+
+A good lens assignment states:
+
+```markdown
+Target:
+Question or claim:
+Lens:
+Evidence required:
+Out of scope:
+Severity rule:
+Output shape:
+Stop condition:
+```
+
+Do not ask every reviewer to cover everything. Keep reviewers independent until synthesis so one early narrative does not contaminate all findings.
+
+## Quorum design
+
+A quorum keeps the target, claim, evidence standard, and output shape constant while varying independent judges. Before fanout:
+
+1. define the exact decision claim;
+2. define what counts as supporting and contradicting evidence;
+3. select the minimum successful threshold;
+4. choose concurrency and timeout bounds;
+5. preflight model and tool availability;
+6. define how partial results affect status.
+
+Provider or model failure reduces available evidence; it is not a vote. When evidence falls below threshold, mark the result degraded or insufficient data.
+
+## Research evidence
+
+Research participants separate source discovery, verification, contradiction mapping, and synthesis when stakes justify it.
+
+- Every material claim traces to a source note, inspected artifact, or explicit uncertainty.
+- Source quality and confidence remain visible.
+- Contradictory evidence is first-class output.
+- Missing source classes block overconfident synthesis.
+- Unsafe or unverifiable evidence is excluded with a reason.
+
+Do not turn a research swarm into an automatic publication pipeline. Stop at the caller's evidence and decision boundary.
+
+## Merge protocol
+
+A merger is a synthesis participant, not a formatter. It may deduplicate, rank, connect evidence, and add a grounded `merger finding`, but it may not fabricate support.
+
+For serious quorum work, use a clean-context merger. The merger receives all retained participant outputs and must produce:
+
+- status: complete, degraded, or insufficient data;
+- consensus findings and vote shape where applicable;
+- minority high-impact findings;
+- contradictions and unresolved evidence gaps;
+- merger findings, clearly labeled;
+- confidence and limitations;
+- ordered next actions.
+
+Keep raw participant outputs until the merged result is accepted. Preserve attribution for major findings. Never promote repeated low-value observations merely because they are numerous, and never discard a severe evidence-backed minority finding merely because it is unique.
+
+## Conflict and disagreement
+
+Disagreement can mean different assumptions, different evidence, ambiguous criteria, or real uncertainty. The merger records:
+
+```markdown
+Finding:
+Supporting participants and evidence:
+Contradicting participants and evidence:
+Assumption difference:
+Impact if minority view is correct:
+Resolution status:
+Next evidence needed:
+```
+
+Resolve only when evidence supports resolution. Otherwise preserve the disagreement and lower confidence.
+
+## Post-merge review
+
+Use a fresh reviewer when the merged result will drive consequential implementation or decisions. The post-merge reviewer checks the report, not the original target by default:
+
+- evidence traceability;
+- honest severity;
+- correct quorum accounting;
+- preserved minority findings;
+- unsupported merger narrative;
+- actionable next steps;
+- retained uncertainty and contradictions.
+
+Possible decisions are accept, accept with notes, revise merge, rerun bounded quorum, or escalate. Rerun only when the raw evidence or scope is genuinely insufficient, not because the verdict is inconvenient.
+
+## Completion and stop rules
+
+A review swarm is complete only when requested evidence is retained, threshold status is explicit, synthesis preserves dissent, and the coordinator can state the safe decision or next evidence slice. Stop when the claim is ambiguous, target changes during review, preflight fails, evidence is not inspectable, threshold cannot be met, or merger independence required by the stakes is unavailable.

package/docs/README.md

@@ -12,9 +12,9 @@ Living index of all documentation in the `/docs` directory.
 - [recipe-library.md](./recipe-library.md) — Packaged standard recipe library such as async subagents, coordinator pipelines, utilities, and music playback
 - [releasing.md](./releasing.md) — Guarded tag validation, npm Trusted Publisher setup, registry verification, and GitHub Release convergence
 
-## Root Context
+## Project Surfaces
 
-- [Project Context](../AGENTS.md)
-- [Open Backlog](../BACKLOG.md)
-- [Changelog](../CHANGELOG.md)
-- [Root README](../README.md)
+- [Human product entrypoint](../README.md)
+- [Implementation protocol](../AGENTS.md)
+- [Future work](../BACKLOG.md)
+- [Completed delivery history](../CHANGELOG.md)

package/docs/recipe-library.md

@@ -6,34 +6,39 @@ Active Skills provide maintained execution graphs and service definitions. Skill
 
 ### Repository and delivery
 
-- `project-work/repo-health` — repository inspection and bounded health artifact.
-- `project-work/docs-maintenance` — documentation analysis and artifact preparation.
-- `project-work/release-readiness` — release checks and readiness artifact.
-- `project-work/release-summary` — release-summary artifact.
-- `swarm/development-tasking` — task-card and implementation planning pipeline.
+- `project-work/repo-health` — repository status, recent history, docs surface, trusted validation, and bounded report content.
+- `project-work/docs-maintenance` — documentation consistency evidence and a maintenance plan; it does not edit documentation.
+- `project-work/release-readiness` — multi-lens readiness verdict and blockers; it does not publish.
+- `project-work/release-summary` — evidence-only release summary and PR-body draft with no external release side effect.
+- `project-work/run-ops` — read-only report over existing Run state; it does not send Control.
+- `swarm/development-tasking` — bounded task-card and scope-critique pipeline.
 
 ### Review and synthesis
 
 - `swarm/quorum-review` — parallel reviewers with quorum-oriented synthesis.
 - `swarm/review-readiness` — review plus readiness stages.
-- `swarm/research-synthesis` — evidence-oriented research synthesis.
-- `swarm/lens-review` — configurable repeated review lenses.
+- `swarm/research-synthesis` — evidence map, contradiction analysis, and risk-first research synthesis.
+- `swarm/lens-review` — different independent risk lenses for breadth.
+- `swarm/architect` — competing architecture directions and one validated smallest next slice.
 - `swarm/subagent-review-coordinator` — lower-level review/verify/merge/judge composition.
 
 Callers should own model, thinking, concurrency, quorum, and mission policy. Review pipelines preflight provider/model availability before expensive fanout.
 
 ### Artifacts
 
-- `artifacts/report` — prepare one artifact body.
-- `artifacts/write` — prepare and deterministically write an artifact.
+- `artifacts/report` — prepare normalized report content without committing a filesystem write.
+- `artifacts/write` — prepare and deterministically write one artifact with explicit create/overwrite/append policy.
 - `artifacts/bundle` — optional validation, artifact write, manifest generation, and manifest write.
 - `artifacts/file-write` — deterministic create/overwrite/append helper.
 - `artifacts/manifest` — artifact manifest generation.
 
 Artifact pipelines terminate in files/manifests and result evidence; they do not fabricate communication events.
 
-### Controlled services
+### Media and controlled services
 
+- `media/playlist-scan` — shallow unfiltered path inventory.
+- `media/playlist-build` — extension-filtered `paths`, `m3u`, or `inline` playlist output; it does not create a playlist file.
+- `media/library` — filtered playlist plus bounded library-report content; `artifact_path` alone is not durable-write proof.
 - `media/player` — playback service with declared playback actions, `controls.jsonl`, generation-fenced endpoint readiness, state artifact, and playback Trace. Player selection is `player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)=auto`.
 - `actors/resource-locker` — optional queue/lease-lock service with explicit owner/resource input, lock Trace, and a 512-record/1 MiB atomically retained journal.
 

package/docs/template-recipes.md

@@ -147,7 +147,9 @@ Resolution fails before launch when required current policy is unavailable. The
 
 ## Resolution Context
 
-User Recipes under `~/.pi/agent/recipes` remain intentionally registered tools, not an ambient import namespace. Each session receives an immutable active-Skill resolution context from Pi's loaded Skill metadata; pi-actors does not scan ambient Skill roots independently or keep a process-global mutable namespace. A launch captures its resolved graph, so later Skill changes affect only future launches. An invalid or missing exact target fails without fallback. Disabled Recipes cannot launch. Registry watchers converge after atomic changes without executing partial definitions.
+User Recipes under `~/.pi/agent/recipes` remain intentionally registered tools, not an ambient import namespace. Each session receives one immutable resolution context from Pi's loaded Skill metadata; spawn, user-Recipe admission, registration, schema derivation, live inspection, and watcher reconciliation consume that same context rather than scanning ambient Skill roots or keeping a process-global mutable namespace. A launch captures its resolved graph, so later Skill changes affect only future launches. An invalid or missing exact target fails without fallback. Disabled Recipes cannot launch. Registry watchers converge after atomic changes without executing partial definitions.
+
+Active-Skill catalog inventory is fail-soft diagnostic state, not exact-resolution authority. Invalid components are reported individually and make the catalog partial while unrelated valid `<skill>/<recipe>` references remain exactly resolvable.
 
 ## Validation
 

package/docs/tool-registry.md

@@ -6,7 +6,7 @@
 ~/.pi/agent/recipes/*.json
 ```
 
-Each active valid Recipe becomes an agent-callable tool. `register_tool` creates, updates, promotes, or deletes these files through fenced mutation paths.
+Each valid Recipe admitted against the current session context can become an agent-callable tool. `register_tool` creates, updates, promotes, or deletes these files through fenced mutation paths and reports the resulting activation state.
 
 ## Registration
 
@@ -16,13 +16,23 @@ Register a command template:
 register_tool name=repo_check template="make check" description="Run repository checks"
 ```
 
-Register a typed/defaulted template or Recipe-backed definition when reuse justifies it. String templates execute directly without shell semantics; use arrays or an explicit trusted script for sequencing.
+Specialize a maintained Recipe without copying its contract:
+
+```text
+register_tool name=music_player from=media/player defaults={"source":"~/Music/1MIX"}
+```
+
+`from`, `template`, and `draft` are distinct source modes. `from` accepts exact `<skill>/<recipe>` identity or an explicit `.json` / `.md` path and inherits async behavior, args/types, source defaults, artifacts, Control, and runtime-owned origins. `defaults` may set only effective caller-owned args and must satisfy their types. `template` is only for trusted command definitions; public `values` authoring has been removed in favor of caller defaults or an authored Recipe file.
 
 Promote an immutable captured draft only with its draft path and explicit target name. Name collisions require `update=true`. Invalid content fails before active mutation.
 
+Registration resolves the effective delegated contract before persistence, then reports logical `source`, effective `required_args` / `optional_args`, and distinct `persisted`, `registry_active`, `host_registered`, `active_tool`, and `callable_now` states. A callable result points to the actual generated tool as the next action. An uncallable result names its `activation_boundary` and status/doctor action without suggesting spawn as a substitute. Diagnose one maintained source with `inspect target=recipes view=doctor identity=<skill>/<recipe>`; diagnose final activation, source, schema summary, and separate spawn/tool usage with `inspect target=tool:<name> view=status`. Treat the tool as callable in the current session only when `callable_now` is true; persistence alone is not activation proof. Registration results omit raw persisted paths and executable template/config payloads.
+
 ## Resolution
 
-User Recipes are the only file-discovered tool source. Invalid or disabled user entries fail closed. Active Skill Recipes remain exact components outside tool discovery. Runtime reload watches the user Recipe root and converges after atomic changes; stale watcher generations cannot replace current registration state.
+User Recipes are the only file-discovered tool source. Invalid or disabled user entries fail closed. Active Skill Recipes remain exact components outside tool discovery. Spawn, registration, registry admission, schema derivation, and live inspection resolve against one immutable session context containing the current working directory and active Skills. Runtime reload watches the user Recipe root using that current context and converges after atomic changes; stale watcher generations cannot replace current registration state.
+
+Skill component inventory is diagnostic and fail-soft: valid components remain listed and exactly resolvable when an unrelated component is rejected. Recipe inspection reports rejected components and marks the catalog partial instead of treating one bad component as an empty catalog.
 
 Inspect registry state with:
 
@@ -31,7 +41,9 @@ inspect target=recipes view=status
 inspect target=tool:<name> view=status
 ```
 
-Recipe inspection reports active, shadowed, invalid, disabled, diagnostic, risk, usage, and review evidence. Tool inspection reports the current capability definition/schema; a registered tool is not a running actor.
+Recipe inspection reports generation, scan/watch state, active, shadowed, invalid, disabled, component rejection, diagnostic, risk, usage, and review evidence. Tool status reports current activation plus separate `tool_calls` and `spawn_calls`; tool schema reports the caller-owned capability contract. A registered tool is not a running actor.
+
+`spawn recipe=<name>` executes a Recipe and reports `launch_kind: "spawn"`; it does not prove that a registered tool was exposed or invoked. Registered-tool execution reports `launch_kind: "tool"`.
 
 ## Automatic Review
 
@@ -59,9 +71,9 @@ Set `PI_ACTORS_AUTOMATIC_REVIEW=off` to disable scheduling and safe-boundary act
 
 Usage and lineage live in locked metadata ledgers rather than authored Recipe files. Launch accounting briefly shares the portfolio transaction fence so quarantine cannot invalidate an already-authorized launch. Revision snapshots, rollback, demotion, rename, and identical-source deduplication retain CAS/hash evidence.
 
-## Wrapping Existing Recipes
+## Specializing Existing Recipes
 
-Prefer a small user-root wrapper that imports a maintained Recipe by exact `<skill>/<recipe>` identity and delegates by alias. Skill Recipes remain components and are never exposed merely because their Skill is active. Do not duplicate executable templates, defaults, Control declarations, artifacts, or runtime-owned `{recipe_dir}`/`{skill_dir}`. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
+Use `register_tool from=<skill>/<recipe> defaults={...}` for one maintained capability under a persistent name or narrower defaults. The stored user Recipe remains compact direct delegation; it does not copy async, args/types, Control, artifacts, helpers, or runtime-owned `{recipe_dir}`/`{skill_dir}`. Named imports remain for multi-node Recipe composition, not one-source specialization. Skill Recipes remain components and are never exposed merely because their Skill is active. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
 
 ## Safety
 

package/lib/async-runs.ts

@@ -161,6 +161,7 @@ export interface AsyncRunMeta {
   argv: string[];
   createdAt: string;
   cwd: string;
+  launch_kind?: AsyncRunLaunchSource;
   launch_source?: AsyncRunLaunchSource;
   launch_correlation?: {
     correlation_id?: string;
@@ -600,7 +601,10 @@ export function startRun(
       createdAt: new Date().toISOString(),
       cwd,
       ...(startParams.launch_source
-        ? { launch_source: startParams.launch_source }
+        ? {
+            launch_kind: startParams.launch_source,
+            launch_source: startParams.launch_source,
+          }
         : {}),
       ...(startParams.launch_correlation
         ? { launch_correlation: startParams.launch_correlation } : {}),

package/lib/execution.ts

@@ -83,6 +83,7 @@ export interface RegisteredToolExecutionResult {
     command: string;
     fullOutputPath?: string;
     killed: boolean;
+    launch_kind: "tool";
     stderrBytes?: number;
     stderrCapturedBytes?: number;
     stderrFile?: string;
@@ -1136,6 +1137,7 @@ export async function executeRegisteredTool(
       command,
       fullOutputPath: result.stdoutFile ?? formatted.fullOutputPath,
       killed: result.killed,
+      launch_kind: "tool",
       ...getCaptureDetails(result),
       ...(executed.branches.length > 0 ? { branches: executed.branches } : {}),
       ...(executed.failures.length > 0

package/lib/extension-runtime.ts

@@ -9,6 +9,7 @@ import * as CommandTemplates from "./command-templates.ts";
 import * as Paths from "./paths.ts";
 import * as Pi from "./pi.ts";
 import * as Prompts from "./prompts.ts";
+import * as RecipeResolution from "./recipes-context.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import * as RunUiRuntime from "./run-ui-runtime.ts";
 import * as Runtime from "./runtime.ts";
@@ -34,14 +35,21 @@ export function createActorExtensionRuntime(
   pi: Pi.ExtensionAPI,
 ): ActorExtensionRuntime {
   let activeRunContext: Pi.ExtensionContext | undefined;
-  const skillContextsBySession = new Map<
+  const recipeResolutionContextsBySession = new Map<
     string,
-    RecipesReferences.ActiveSkillRecipeContext
+    RecipeResolution.RecipeResolutionContext
   >();
   const getRunOwnerId = Pi.getSessionId;
-  const getSkillContext = (ctx: Pi.ExtensionContext) =>
-    skillContextsBySession.get(getRunOwnerId(ctx)) ??
-    RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT;
+  const getRecipeResolutionContext = (ctx: Pi.ExtensionContext) => {
+    const sessionId = getRunOwnerId(ctx);
+    const resolutionContext = recipeResolutionContextsBySession.get(sessionId);
+    if (!resolutionContext) {
+      throw new Error(
+        `Recipe resolution context is unavailable for session ${sessionId}.`,
+      );
+    }
+    return resolutionContext;
+  };
   const automaticReview = AutomaticReviewRuntime.createAutomaticReviewRuntime({
     getActiveContext: () => activeRunContext,
     getRunOwnerId,
@@ -67,7 +75,7 @@ export function createActorExtensionRuntime(
         if (ctx && typeof ctx === "object") {
           nextArgs[4] = {
             ...(ctx as Record<string, unknown>),
-            activeSkillRecipeContext: getSkillContext(
+            recipeResolutionContext: getRecipeResolutionContext(
               ctx as Pi.ExtensionContext,
             ),
             getThinkingLevel: () => pi.getThinkingLevel(),
@@ -85,6 +93,7 @@ export function createActorExtensionRuntime(
     configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
     exec: CommandTemplates.execCommandTemplate,
     getActiveTools: () => pi.getActiveTools(),
+    getAllTools: () => pi.getAllTools(),
     registerTool: (definition) => {
       const wrapped = withCurrentThinkingContext(definition);
       actorToolDefinitions.set(wrapped.name, wrapped);
@@ -93,13 +102,22 @@ export function createActorExtensionRuntime(
     reservedToolNames: Tools.RESERVED_TOOL_NAMES,
     setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
   });
-  const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime);
+  const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime, {
+    getResolutionContext: () =>
+      activeRunContext
+        ? getRecipeResolutionContext(activeRunContext)
+        : undefined,
+  });
   return {
     beforeAgentStart(systemPrompt, skills, ctx) {
-      skillContextsBySession.set(
-        getRunOwnerId(ctx),
+      const sessionId = getRunOwnerId(ctx);
+      const resolutionContext = RecipeResolution.createRecipeResolutionContext(
+        sessionId,
+        ctx.cwd,
         RecipesReferences.createActiveSkillRecipeContext(skills),
       );
+      recipeResolutionContextsBySession.set(sessionId, resolutionContext);
+      runtime.loadTools(ctx, resolutionContext);
       return {
         systemPrompt: `${systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
       };
@@ -113,16 +131,17 @@ export function createActorExtensionRuntime(
       if (activeRunContext === ctx) automaticReview.schedule();
     },
     onSessionShutdown(reason, ctx) {
-      skillContextsBySession.delete(getRunOwnerId(ctx));
+      recipeResolutionContextsBySession.delete(getRunOwnerId(ctx));
       activeRunContext = undefined;
       automaticReview.close();
       recipeReload.close();
       runUiRuntime.shutdown(reason, ctx);
     },
     async onSessionStart(ctx) {
-      skillContextsBySession.set(
-        getRunOwnerId(ctx),
-        RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT,
+      const sessionId = getRunOwnerId(ctx);
+      recipeResolutionContextsBySession.set(
+        sessionId,
+        RecipeResolution.createEmptyRecipeResolutionContext(sessionId, ctx.cwd),
       );
       ctx.ui.setWidget("zz-pi-actors-comms", undefined);
       activeRunContext = ctx;
@@ -132,7 +151,6 @@ export function createActorExtensionRuntime(
       await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
       if (activeRunContext !== ctx) return;
       automaticReview.start(ctx);
-      runtime.loadTools(ctx);
       runUiRuntime.start(ctx);
       recipeReload.watch(ctx);
     },
@@ -148,6 +166,7 @@ export function createActorExtensionRuntime(
               runtime.getTools(),
               (activeName) => actorToolDefinitions.get(activeName),
             ),
+          getRuntimeToolStatus: runtime.getToolStatus,
           handleRuntimeControl: automaticReview.handleControl,
           registryRuntime: runtime,
           setActiveTools: (toolNames) => pi.setActiveTools(toolNames),

package/lib/inspector.ts

@@ -183,6 +183,7 @@ export function readActorInspectorRecipe(
       logical_reference: primaryLogicalReference,
       ...(typeof primary?.skill === "string" ? { skill: primary.skill } : {}),
       source_kind: primarySourceKind,
+      launch_kind: meta.launch_kind ?? meta.launch_source,
       launch_source: meta.launch_source,
     }),
     launch: redactedRecord({

package/lib/prompts.ts

@@ -5,52 +5,52 @@
  */
 
 export const REGISTER_TOOL_DESCRIPTION =
-  "Register a persistent custom tool from a command template, template recipe path, or co-located template recipe. " +
-  "Definitions are stored as recipe files under ~/.pi/agent/recipes across reloads. " +
-  "Use update=true to overwrite an existing tool, template=null/empty to delete.";
+  "Register a persistent custom tool from one maintained Recipe, command template, or captured draft. " +
+  "Use from for Recipe specialization, template for trusted commands, or draft for promotion. " +
+  "Definitions persist under ~/.pi/agent/recipes; activation is reported separately.";
 
 export const REGISTER_TOOL_PROMPT_SNIPPET =
-  "Register persistent command templates as agent-callable tools";
+  "Register persistent Recipes or command templates as agent-callable tools";
 
 export const REGISTER_TOOL_GUIDELINES = [
-  "Use register_tool to wrap trusted local commands, scripts, programs, libraries, or template recipes as persistent pi tools.",
-  "After register_tool succeeds, the new tool is immediately callable and remains available after reload.",
+  "Use register_tool from=<skill>/<recipe> with defaults={...} to specialize a maintained Recipe without copying its contract.",
+  "Use register_tool template only for trusted command templates, and use register_tool draft only for captured draft promotion.",
+  "After register_tool succeeds, trust its callable_now and activation result; persistence alone is not callability.",
   'Set template=null or template="" in register_tool to delete a persisted tool.',
   "Set update=true in register_tool to overwrite an existing tool registration.",
 ];
 
-export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
-- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.
-- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.
-- Command templates stay sync and shell-free: string leaves split into executable + argv, infer .js/.mjs through node→bun→deno run and .sh through bash, and treat operators such as && as literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
-- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
-- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
-- Recipes own template directly and may declare metadata/defaults/imports/control/artifacts; files >1 MiB or import depth >32 fail closed.
-- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
-- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.
-- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid internal transport vocabulary in public guidance.
-- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
-- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; active-Skill and explicit file Recipes remain components outside user tool discovery; offer to save successful recurring patterns only after confirmation.
-- Prefer maintained active-Skill Recipes with spawn recipe=<skill>/<recipe> before ad hoc scripts/wrappers; explicit file Recipes use exact .json/.md paths; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
-- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
+export const ONBOARDING_SYSTEM_PROMPT = `pi-actors Skill routing:
+- Treat active bundled Skills as the operating authority.
+- For non-trivial pi-actors operation, diagnosis, or development, load and read the actors Skill before acting.
+- For work requiring multiple actors or subagents, additionally load and read the swarm Skill.
+- For capability-specific selection or constraints, load the owning capability Skill; actors owns generic mechanics and swarm owns multi-actor methodology.
+- Keep a Skill Recipe distinct from a registered tool and a Recipe spawn distinct from registered-tool invocation; actors owns the proof rules.
+- Treat persistence or registration as distinct from current callability; actors owns activation proof.
+- On failure or disagreement, preserve the logical Recipe identity, stop, and follow actors diagnosis; never bypass the owning Skills with copied contracts, helper paths, shell evaluation, or background-process workarounds.
+- If a capability Skill conflicts with actors about generic mechanics, follow actors and report the stale capability guidance.
+- README and docs are human-facing references, not the normal agent operating path.
+- AGENTS, source, and tests are implementation protocol and evidence; use them when changing or debugging the extension, not as substitutes for operating Skills.`;
 
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
   name: "Tool name in snake_case (e.g., 'transcribe')",
   description:
     "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.",
+  from:
+    "Recipe to specialize by canonical <skill>/<recipe> identity or explicit .json/.md path. Inherits async, args/types, source defaults, artifacts, Control, and runtime origins.",
+  defaults:
+    "Optional caller-owned defaults. Keys and values must satisfy the effective source or command-template argument contract.",
   draft:
-    "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.",
+    "Promote a captured draft Recipe path from ~/.pi/agent/recipes/drafts. This is a source mode; do not combine it with from or template.",
   async:
     "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.",
   template:
-    "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.",
+    "Trusted command template with {arg} or {arg=default} placeholders. To specialize a Recipe, use from instead. Omitted updates keep the old template; empty string deletes the tool.",
   templateArray:
     "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.",
   templateNull: "Delete the tool when template is null.",
   args: "Optional comma-separated placeholder declarations. Usually omit because args are derived from template placeholders. Interactive shorthand defaults are accepted and normalized. Example: file,lang,mode=fast",
   update: "Set to true to overwrite an existing tool registration.",
-  values:
-    "Optional default runtime placeholder values for a co-located template recipe.",
 } as const;
 
 export function formatRegisteredToolPromptSnippet(template: unknown): string {

package/lib/recipes-context.ts

@@ -1,15 +1,60 @@
 /**
- * Recipe context prompt assembly.
- * Zones: async runner prompt context, recipe provenance, LLM child launches
- * Owns compact actor recipe context records appended to child-agent prompts.
+ * Recipe context contracts and prompt assembly.
+ * Zones: live session resolution, async runner prompt context, recipe provenance, LLM child launches
+ * Owns the immutable live Recipe environment and compact actor context appended to child-agent prompts.
  */
 
+import { createHash } from "node:crypto";
 import { writeFileSync } from "node:fs";
-import { basename } from "node:path";
+import { basename, resolve } from "node:path";
 
 import type { CommandTemplateActorRecipeContext } from "./command-templates.ts";
+import * as RecipesReferences from "./recipes-references.ts";
 import type { TemplateRecipeContextRecord } from "./recipes-references.ts";
 
+export interface RecipeResolutionContext {
+  readonly activeSkills: RecipesReferences.ActiveSkillRecipeContext;
+  readonly cwd: string;
+  readonly generation: string;
+  readonly sessionId: string;
+}
+
+export function createRecipeResolutionContext(
+  sessionId: string,
+  cwd: string,
+  activeSkills: RecipesReferences.ActiveSkillRecipeContext,
+): RecipeResolutionContext {
+  const normalizedSessionId = sessionId.trim();
+  if (!normalizedSessionId) throw new Error("Recipe resolution session id is required.");
+  const normalizedCwd = resolve(cwd);
+  const generation = createHash("sha256")
+    .update(
+      JSON.stringify({
+        activeSkills: RecipesReferences.getActiveSkillRecipeNamespaces(activeSkills),
+        cwd: normalizedCwd,
+        sessionId: normalizedSessionId,
+      }),
+    )
+    .digest("hex");
+  return Object.freeze({
+    activeSkills,
+    cwd: normalizedCwd,
+    generation,
+    sessionId: normalizedSessionId,
+  });
+}
+
+export function createEmptyRecipeResolutionContext(
+  sessionId: string,
+  cwd: string,
+): RecipeResolutionContext {
+  return createRecipeResolutionContext(
+    sessionId,
+    cwd,
+    RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT,
+  );
+}
+
 export interface MarkedRecipeContextRecord extends TemplateRecipeContextRecord {
   you_are_here?: true;
   you_are_here_path?: string;