@llblab/pi-actors 0.46.1 → 0.47.0

package/dist/lib/tools-inspect.js

@@ -3,7 +3,7 @@
  * Zones: Run Recipe/Trace/Control views and runtime/recipe/tool diagnostics
  * Owns exact inspect target/view dispatch; source projection stays in domain modules.
  */
-import { statSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { isAbsolute, join, relative } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
 import * as ControlProjection from "./control-projection.js";
@@ -166,7 +166,105 @@ function portableSkillRecipePath(file, skill, namespaces) {
         ? `<active-skill:${skill}>/${relation.replaceAll("\\", "/")}`
         : `<active-skill:${skill}>`;
 }
-function inspectRecipes(view, deps, context) {
+function portableSkillRecipeDiagnosticReason(diagnostic, namespaces) {
+    let reason = diagnostic.reason;
+    if (diagnostic.file) {
+        reason = reason.replaceAll(diagnostic.file, portableSkillRecipePath(diagnostic.file, diagnostic.skill, namespaces));
+    }
+    for (const root of namespaces[diagnostic.skill] ?? []) {
+        reason = reason.replaceAll(root, `<active-skill:${diagnostic.skill}>`);
+    }
+    return reason;
+}
+function inspectRecipeIdentity(identity, resolutionContext, namespaces, inventory, registryStatus) {
+    const match = /^([a-z][a-z0-9]*(?:-[a-z0-9]+)*)\/([a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/u.exec(identity);
+    const skill = match?.[1] ?? "";
+    const roots = skill ? namespaces[skill] ?? [] : [];
+    const skillActive = roots.length === 1;
+    const matchingComponent = inventory.components.find((component) => component.identity === identity);
+    const matchingRejection = inventory.rejected.find((diagnostic) => diagnostic.skill === skill &&
+        (diagnostic.stem === undefined || diagnostic.stem === match?.[2]));
+    let sourceLocation;
+    let rejectedReason;
+    let resolvable = false;
+    if (!match) {
+        rejectedReason =
+            "Identity must use canonical <skill>/<recipe> syntax.";
+    }
+    else if (roots.length === 0) {
+        rejectedReason = `Active Skill Recipe not found: ${identity}`;
+    }
+    else if (roots.length > 1) {
+        rejectedReason = matchingRejection
+            ? portableSkillRecipeDiagnosticReason(matchingRejection, namespaces)
+            : `Duplicate active Skill identity ${skill}`;
+    }
+    else if (matchingRejection) {
+        rejectedReason = portableSkillRecipeDiagnosticReason(matchingRejection, namespaces);
+        if (matchingRejection.file) {
+            sourceLocation = portableSkillRecipePath(matchingRejection.file, skill, namespaces);
+        }
+    }
+    else {
+        try {
+            const file = RecipesReferences.resolveRecipeReferencePath(identity, resolutionContext?.cwd, resolutionContext?.activeSkills);
+            if (!file || !existsSync(file)) {
+                rejectedReason = `Skill Recipe component not found: ${identity}`;
+            }
+            else {
+                sourceLocation = portableSkillRecipePath(file, skill, namespaces);
+                const recipe = RecipesReferences.readResolvedRecipeConfig(file, [], {
+                    skillContext: resolutionContext?.activeSkills,
+                });
+                if (recipe)
+                    resolvable = true;
+                else {
+                    rejectedReason =
+                        RecipesReferences.diagnoseRawRecipeConfigFailure(file) ??
+                            `Recipe could not be resolved: ${identity}`;
+                }
+            }
+        }
+        catch (error) {
+            rejectedReason = error instanceof Error ? error.message : String(error);
+        }
+    }
+    const componentStatus = resolvable
+        ? "available"
+        : !match
+            ? "invalid_identity"
+            : roots.length === 0
+                ? "skill_inactive"
+                : roots.length > 1
+                    ? "ambiguous_skill"
+                    : matchingRejection
+                        ? "rejected"
+                        : matchingComponent
+                            ? "unresolvable"
+                            : "missing";
+    return {
+        identity,
+        skill_active: skillActive,
+        resolvable,
+        catalog_partial: inventory.partial,
+        component_status: componentStatus,
+        ...(sourceLocation ? { source_location: sourceLocation } : {}),
+        resolution_generation: resolutionContext?.generation ?? registryStatus?.resolution_generation ?? "unavailable",
+        ...(rejectedReason ? { rejected_reason: rejectedReason } : {}),
+        next_actions: resolvable
+            ? [
+                `spawn recipe=${identity}`,
+                `register_tool name=<tool-name> from=${identity}`,
+            ]
+            : roots.length === 0 && skill
+                ? [
+                    `activate Skill ${skill}`,
+                    `inspect target=recipes view=doctor identity=${identity}`,
+                ]
+                : ["inspect target=recipes view=imports verbose=true"],
+    };
+}
+function inspectRecipes(view, input, deps, context) {
     if (view !== "status" &&
         view !== "summary" &&
         view !== "doctor" &&
@@ -188,6 +286,14 @@ function inspectRecipes(view, deps, context) {
         RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT;
     const skillRecipeNamespaces = RecipesReferences.getActiveSkillRecipeNamespaces(activeSkillContext);
     const skillInventory = RecipesReferences.inventoryActiveSkillRecipeComponents(activeSkillContext);
+    const registryStatus = deps.registryStatus?.();
+    const identity = typeof input.identity === "string" ? input.identity.trim() : "";
+    if (identity && view !== "doctor") {
+        throw new Error("inspect recipes identity is supported only with view=doctor.");
+    }
+    if (view === "doctor" && identity) {
+        return inspectRecipeIdentity(identity, resolutionContext, skillRecipeNamespaces, skillInventory, registryStatus);
+    }
     const skillRecipeComponents = skillInventory.components.map((component) => ({
         identity: component.identity,
         source_kind: "active_skill_component",
@@ -196,7 +302,7 @@ function inspectRecipes(view, deps, context) {
         imports: component.imports,
     }));
     const skillRecipeComponentDiagnostics = skillInventory.rejected.map((diagnostic) => ({
-        error: diagnostic.reason,
+        error: portableSkillRecipeDiagnosticReason(diagnostic, skillRecipeNamespaces),
         ...(diagnostic.file
             ? {
                 file: portableSkillRecipePath(diagnostic.file, diagnostic.skill, skillRecipeNamespaces),
@@ -208,9 +314,9 @@ function inspectRecipes(view, deps, context) {
     const discoverySummary = RecipesDiscovery.summarizeDiscovery(discovered);
     const summary = {
         ...discoverySummary,
-        ...(deps.registryStatus
+        ...(registryStatus
             ? {
-                ...deps.registryStatus(),
+                ...registryStatus,
                 watched_root: "~/.pi/agent/recipes",
             }
             : {}),
@@ -322,21 +428,58 @@ function inspectTool(name, view, deps) {
         throw new Error("inspect tool:<name> supports view=status or view=schema.");
     }
     const tool = deps.getTool?.(name);
-    if (!tool)
-        throw new Error(`registered tool not found: ${name}`);
+    const status = deps.getToolStatus?.(name);
+    if (!tool && !status) {
+        throw new Error(`Registered tool not found: ${name}. Next: inspect target=recipes view=doctor; do not substitute spawn for tool invocation.`);
+    }
+    if (view === "schema" && !tool) {
+        throw new Error(`Tool "${name}" is registered but its callable schema is unavailable; callable_now=${String(status?.callable_now ?? false)}, activation_boundary=${String(status?.activation_boundary ?? "host_registration")}. Next: inspect target=tool:${name} view=status.`);
+    }
     return {
         name,
-        ...(view === "status" ? deps.getToolStatus?.(name) : {}),
-        description: tool.description,
-        parameters: tool.parameters,
-        promptSnippet: tool.promptSnippet,
+        ...(view === "status" ? status : {}),
+        ...(tool
+            ? {
+                description: tool.description,
+                parameters: tool.parameters,
+                promptSnippet: tool.promptSnippet,
+            }
+            : {}),
     };
 }
 function compactResult(target, view, details) {
     if (target === "runtime")
         return compactRuntime(view, details);
+    if (target === "recipes" && typeof details.identity === "string") {
+        const lines = [
+            `recipes doctor identity=${details.identity} skill_active=${String(details.skill_active)} resolvable=${String(details.resolvable)} catalog_partial=${String(details.catalog_partial)} component_status=${String(details.component_status)}`,
+            ...(details.source_location
+                ? [`source=${String(details.source_location)}`]
+                : []),
+            `resolution_generation=${String(details.resolution_generation)}`,
+            ...(details.rejected_reason
+                ? [`rejected_reason=${String(details.rejected_reason)}`]
+                : []),
+            ...(details.next_actions ?? []).map((action) => `next=${String(action)}`),
+        ];
+        return `\n${lines.join("\n")}`;
+    }
     if (target === "recipes")
         return ToolsResponse.compactRecipeRegistry(details);
+    if (target.startsWith("tool:") && view === "status") {
+        const required = Array.isArray(details.required_args)
+            ? details.required_args.map(String).join(",") || "none"
+            : "unknown";
+        const optional = Array.isArray(details.optional_args)
+            ? details.optional_args.map(String).join(",") || "none"
+            : "unknown";
+        const next = Array.isArray(details.next_actions) && details.next_actions.length > 0
+            ? String(details.next_actions[0])
+            : details.callable_now === true
+                ? `call tool ${target.slice(5)}`
+                : `register_tool name=${target.slice(5)} update=true`;
+        return `\ntool=${target.slice(5)} source=${String(details.source ?? "unknown")} callable_now=${String(details.callable_now ?? false)} activation_boundary=${String(details.activation_boundary ?? "unknown")} required=${required} optional=${optional} launch_kind=${String(details.launch_kind ?? "none")} spawn_calls=${Number(details.spawn_calls ?? 0)} tool_calls=${Number(details.tool_calls ?? 0)} next=${next}`;
+    }
     if (target.startsWith("tool:"))
         return `\ntool=${target.slice(5)} view=${view}`;
     return `\nrun=${target.slice(4)} view=${view}`;
@@ -347,6 +490,7 @@ export function createInspectToolDefinition(deps = {}) {
         label: "Inspect",
         description: "Inspect a Run's Recipe, Trace, or Control evidence, or runtime/recipe/tool diagnostics.",
         parameters: Schema.objectSchema({
+            identity: Schema.stringSchema("Optional canonical <skill>/<recipe> identity for focused Recipe doctor diagnosis."),
             lines: Schema.stringSchema("Bounded item count for Trace or recent Controls."),
             source: Schema.stringSchema("Optional Trace source: all, lifecycle, control, process, agent, artifact, or runtime."),
             status: Schema.stringSchema("Optional runtime Run status filter."),
@@ -363,7 +507,7 @@ export function createInspectToolDefinition(deps = {}) {
                 details = inspectRuntime(view, input, ctx, deps);
             }
             else if (target === "recipes") {
-                details = inspectRecipes(view, deps, ctx);
+                details = inspectRecipes(view, input, deps, ctx);
             }
             else {
                 const run = parseRunTarget(target);

package/dist/lib/tools-register.js

@@ -24,7 +24,9 @@ export function createRegisterToolDefinition(deps) {
             args: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.args),
             async: booleanSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.async),
             description: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.description),
+            defaults: looseObjectSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.defaults),
             draft: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.draft),
+            from: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.from),
             name: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.name),
             template: unionSchema([
                 stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.template),
@@ -33,7 +35,6 @@ export function createRegisterToolDefinition(deps) {
                 nullSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.templateNull),
             ]),
             update: booleanSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.update),
-            values: looseObjectSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.values),
         }, []),
         execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => Registry.executeRegisterTool(params, ctx, deps),
     };

package/dist/lib/tools-response.js

@@ -204,6 +204,9 @@ export function recipeRegistryNextActions(summary, view) {
     if (view === "doctor" && typeof topAction.action === "string") {
         actions.push(String(topAction.action));
     }
+    if (summary.skill_recipe_catalog_partial === true) {
+        actions.push("inspect target=recipes view=imports verbose=true");
+    }
     if (drafts.length > 0) {
         actions.push("inspect target=recipes view=summary verbose=true");
         const firstPath = typeof drafts[0]?.path === "string" ? drafts[0].path : undefined;
@@ -228,12 +231,13 @@ export function compactRecipeRegistry(summary) {
     const recommendations = Array.isArray(summary.recommendations)
         ? summary.recommendations.length
         : 0;
+    const skillCatalogPartial = summary.skill_recipe_catalog_partial === true;
     const currentPolicy = Array.isArray(summary.active)
         ? summary.active.filter((entry) => entry.current_policy).length
         : 0;
     const nextActions = Array.isArray(summary.next_actions)
         ? summary.next_actions
         : [];
-    return `\nrecipes active=${active} drafts=${drafts} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} current_policy=${currentPolicy} recommendations=${recommendations} diagnostics=${diagnostics}${compactNextActions(nextActions)}`;
+    return `\nrecipes active=${active} drafts=${drafts} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} current_policy=${currentPolicy} skill_catalog_partial=${skillCatalogPartial} recommendations=${recommendations} diagnostics=${diagnostics}${compactNextActions(nextActions)}`;
 }
 export const DEFAULT_INSPECT_LINES = Limits.DEFAULT_INSPECT_LINES;

package/dist/scripts/conformance.mjs

@@ -12,6 +12,7 @@ import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const conformanceSuites = [
+  "tests/agent-journeys.test.ts",
   "tests/control.test.ts",
   "tests/runs-controls.test.ts",
   "tests/runs-trace.test.ts",

package/dist/skills/actors/SKILL.md

@@ -1,104 +1,115 @@
 ---
 name: actors
-description: Required practical guide for non-trivial pi-actors use and Run-kernel work. Read before using or changing spawn, message, inspect, Runs, tools, Recipes, command templates, Control, Trace, artifacts, or lifecycle mechanics.
+description: Use for any non-trivial pi-actors operation, diagnosis, or development involving Recipes, persistent tools, Runs, spawn, message, inspect, Trace, Control, capability specialization, or activation.
 ---
 
-# Actors (pi-actors)
+# Actors
 
-`pi-actors` treats any runnable local capability—a script, tool, service, pipeline, or subagent—as an actor. A Recipe is its reusable executable definition; a Run is one concrete actor instance:
+## Choose the operation
+
+Start from the intended outcome:
 
 ```text
-Recipe --spawn--> Run
-Run = Recipe + Trace + Control
-```
+Run a maintained capability once
+→ use spawn recipe=<skill>/<recipe>
 
-Use the swarm skill separately for decomposition, quorum design, reviewer lenses, and consensus methodology.
+Make a maintained capability a persistent agent-callable tool
+→ use register_tool from=<skill>/<recipe>
 
-## Public Verbs
+Keep the same capability but narrow caller defaults
+→ use register_tool from=<skill>/<recipe> defaults={...}
 
-- `spawn`: create one Run from a Recipe or inline command template.
-- `message`: send one actor-local Control to `run:<id>`, or the reserved review actions to `runtime`.
-- `inspect`: inspect `run:<id>`, `runtime`, `recipes`, or `tool:<name>`.
-- `register_tool`: persist a trusted capability; it does not address a running actor. Trust current-session callability only when its result says `callable_now: true`.
+Register a trusted command directly
+→ use register_tool template="..."
 
-A Run target exposes exactly three inspect views: `recipe`, `trace`, and `control`. Spawning a user Recipe is still a Recipe launch (`launch_kind: "spawn"`), not evidence that its registered tool was exposed or invoked; registered-tool execution reports `launch_kind: "tool"`, and `inspect target=tool:<name> view=status` separates both usage counts.
+Build a reusable multi-node execution graph
+→ author a Recipe with named imports
 
-## Recipe
+Run a long-lived controlled process
+→ spawn its async Recipe, then use message and inspect
 
-A Recipe defines execution. It may declare named typed args, inline fallbacks, configuration `defaults`, composition `values`, imports, artifacts, command-template flags, and `control: ["action"]` when a long-lived service actually consumes actor-local inputs.
+Coordinate several independent actors or subagents
+→ also read the swarm Skill
 
-Do not declare Control for ordinary one-shot work. Runtime lifecycle actions such as `kill` stay runtime-owned and must not appear in Recipe Control declarations. Imported Recipes act as local definitions inside one Run; they do not create nested Runs unless execution explicitly spawns them.
+Choose capability-specific behavior
+→ read the owning capability Skill
 
-Prefer maintained Skill-owned Recipes over ad hoc wrappers. Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`; Recipe files have no top-level `name`. `SKILL.md` `name` is Pi host metadata matching its directory, not an additional pi-actors identity field. Use `<skill>/<recipe>` for an exact direct component or an explicit `.json` / `.md` path. Entry paths resolve from invocation `cwd`; relative imports resolve from the importing Recipe directory. File-backed Recipes own `{recipe_dir}` and Skill Recipes own `{skill_dir}`; callers never pass or override these origins. Skill Recipes are components, not automatic tools. A rejected component makes catalog inspection partial without blocking exact resolution of unrelated valid components in the same live session context. Keep model, thinking, mission, concurrency, quorum, and timeout choices caller-owned unless a Recipe documents a stable policy.
+Diagnose resolution, registration, or activation
+→ use Inspect status/doctor flows and stop on contradictory evidence
+```
+
+Use [persistent tools](./references/persistent-tools.md), [Recipes](./references/recipes.md), [Runs](./references/runs.md), or [diagnostics](./references/diagnostics.md) only when the selected operation needs that detail.
 
-## Trace
+## Core distinctions
 
-Trace records bounded structured observations in `trace.jsonl`:
+Keep these boundaries explicit:
 
-```json
-{
-  "id": "…",
-  "ts": "…",
-  "kind": "progress.update",
-  "summary": "…",
-  "data": {},
-  "level": "info",
-  "attention": "notify"
-}
+```text
+Skill Recipe ≠ registered tool
+spawn ≠ registered-tool invocation
+persisted ≠ callable
+direct delegation ≠ named import composition
+Run Control ≠ actor chat
 ```
 
-Trace never carries sender, recipient, route, reply, or message-envelope fields. It is a bounded retained suffix: the canonical lock appends within 2,048 events and 4 MiB or atomically keeps the newest suffix plus one warning-only `runtime.trace_compacted` marker. That marker means older history was discarded; terminal/result/execution/artifact evidence stays independently authoritative. `inspect view=trace` reports completeness. Equal timestamps use same-source physical order, fixed source rank, then stable id without exposing an ordinal or claiming cross-source causality. Attention is a wake hint, not a queue: persist durable state or an artifact first, use `notify` for visible status, and reserve `followup` for needed coordinator context. Compaction may discard old hints.
+A Skill Recipe is a maintained component addressed by `<skill>/<recipe>`. `spawn` creates a Run from a Recipe. `register_tool` creates or updates a persistent user tool. A tool is callable in the current session only when activation evidence says `callable_now: true`.
 
-## Control
+`actors` owns generic Recipe/tool/Run mechanics. The owning capability Skill owns capability-specific selection and constraints. `swarm` owns multi-actor decomposition and integration methodology.
 
-The public Control request is exact:
+## Persistent capability workflow
 
-```json
-{ "target": "run:<id>", "action": "pause", "input": {}, "verbose": false }
+To make `media/player` callable as `music_player` with a default source:
+
+```text
+register_tool
+  name=music_player
+  from=media/player
+  defaults={"source":"~/Music/1MIX"}
 ```
 
-Valid Controls persist in `controls.jsonl` before delivery; invalid envelopes remain outside it. One token-owned lock rejects a 65th pending Control or 1 MiB rewrite before admission, fails closed on malformed or stale-generation evidence, and atomically admits one queued record. Exact-id claims/finalization preserve a 128-terminal tail, expected-state fencing, and 4 KiB errors. Admitted nonterminal Controls never expire automatically. `inspect view=control` reports capacity, saturation, stale work, bytes, and diagnostics. Endpoints carry immutable startup `run_instance_id`; FIFO and named pipe share limits of 64 action characters, 380 serialized input bytes, and 512 newline-terminated wire bytes. Partial writes fail. Put larger data in an artifact and send only its reference. Delivery revalidates owner, generation, state, and process identity.
+Then:
 
-`kill` remains the runtime recovery path for a stuck saturated Run: it bypasses actor-local Control capacity and adds no synthetic Control. Use actor-local `stop` only when declared and implemented. Restart clears generation-local evidence; archive preserves the bounded terminal tree, while prune preserves only requested artifacts.
+1. Require registration to report successful resolution, validation, persistence, registry admission, host registration, activation, and `callable_now: true`.
+2. Call the actual `music_player` tool. Do not call `spawn` and describe that as tool invocation.
+3. Verify agent-facing evidence reports `launch_kind: "tool"`; use `inspect target=tool:music_player view=status` when usage or activation needs confirmation.
+4. If callability is false, stop at the reported activation boundary. Preserve the logical source and diagnose it; do not substitute a Recipe spawn as proof.
 
-## Run State and Safety
+Use direct delegation for the same maintained capability under a persistent name or narrower defaults. Use named imports only when one Recipe graph contains reusable child nodes. See [persistent tools](./references/persistent-tools.md) and [Recipes](./references/recipes.md).
 
-Run state lives under `~/.pi/agent/tmp/pi-actors/runs/<run>/`. Important evidence includes:
+## Run workflow
 
-- `run.json`: captured Run identity, Recipe, owner, generation, process identity, and policy.
-- `trace.jsonl`: structured observations.
-- `controls.jsonl`: durable actor-local inputs and outcomes.
-- `control-endpoint.json`: generation-fenced service readiness.
-- `execution.json`: command/session provenance and bounded complete-capture references.
-- `result.json`, logs, and declared artifacts.
+A Run is one concrete execution of a Recipe:
 
-Trace/Control quotas do not constrain user-declared artifacts, repositories, media sources, complete captures, or actor-owned workload state. No public noun, tool, target, or view is added by bounded retention.
+```text
+Recipe --spawn--> Run
+Run = Recipe + Trace + Control
+```
 
-Never bypass owner filtering, immutable generation fencing, process-identity verification, path containment, redaction, terminal reconciliation, or shutdown kill behavior. Do not edit active Run state to force a result.
+1. Spawn with the exact logical Recipe identity and caller-owned values.
+2. Retain the returned `run:<id>` and normally wait for terminal follow-up instead of polling.
+3. Inspect `view=trace` when retained observations or attention matter.
+4. Inspect `view=control` before diagnosing service readiness, stale work, or saturation.
+5. Send `message` only for an action declared and consumed by that controlled Recipe.
+6. Use terminal state, result, declared artifacts, and execution evidence to prove completion.
 
-## Operating Pattern
+A Run exposes only `recipe`, `trace`, and `control` views. Control is bounded actor-local input, not peer messaging or chat. See [Runs](./references/runs.md).
 
-1. Inspect the Recipe before launch when its contract or policy matters.
-2. Spawn with explicit values and retain the returned `run:<id>`.
-3. Let short Runs finish; avoid polling.
-4. Inspect Trace when evidence or attention requires it; its summary states whether retained history is complete.
-5. Inspect Control capacity before diagnosing stale work or saturation, then send only declared actor-local Controls.
-6. Use runtime kill/cancel behavior for lifecycle termination.
-7. Inspect artifacts and execution evidence for final validation.
+## Diagnosis and stop rules
 
-If work may outlive the current turn, needs steering, produces artifacts, fans out, or must remain inspectable, use a Run rather than shell backgrounding.
+When a pi-actors operation fails:
 
-## Top Recipes
+1. Keep the intended logical Recipe or tool identity.
+2. Inspect the existing `recipes`, `tool:<name>`, `runtime`, or `run:<id>` surface that owns the failure.
+3. Report resolver, registry, activation, Run, Trace, or Control truth exactly.
+4. Retry only after the owning state is healthy.
 
-- [Repository health](../project-work/recipes/repo-health.json)
-- [Quorum review](../swarm/recipes/quorum-review.json)
-- [Artifact bundle](../artifacts/recipes/bundle.json)
-- [Music player service](../media/recipes/player.json)
-- [Resource locker service](./recipes/resource-locker.json)
+Stop if spawn and registry resolve the same Recipe differently. Stop if registration persists but is not callable. Stop if an operation cannot be proven through pi-actors surfaces.
 
-## Deep References
+Never recover by copying maintained Recipe args, defaults, Control, artifacts, or helper commands. Never hard-code a `{skill_dir}` replacement path. Never introduce `bash -lc`, `eval`, direct bundled-helper execution, or shell backgrounding to bypass resolution. Never call `spawn` and claim a tool call. Use [diagnostics](./references/diagnostics.md) for the safe next action.
 
-- [Recipe library](../../docs/recipe-library.md)
-- [Async Runs](../../docs/async-runs.md)
+## When to read another Skill
 
-Read repository source and tests for exact contracts when changing pi-actors itself. Update this skill whenever durable Run mechanics change.
+- Read the owning capability Skill when choosing or operating that capability pack.
+- Read `swarm` in addition to `actors` for multiple actors/subagents, parallel scopes, reviewer lenses, quorum, conflict handling, or integration.
+- For generic mechanics, this Skill outranks capability Skills and `swarm`. Report a stale Skill if it contradicts Recipe identity, registration, activation, spawn, Inspect, Trace, or Control semantics here.
+- When changing the extension implementation itself, apply project implementation instructions after this operating protocol.

package/dist/skills/actors/references/diagnostics.md

@@ -0,0 +1,44 @@
+# Diagnostics
+
+Preserve the intended logical identity and diagnose through public pi-actors surfaces. Do not inspect raw registry files or implementation source as the normal first response.
+
+## Recipe resolution or catalog failure
+
+```text
+inspect target=recipes view=status
+inspect target=recipes view=doctor identity=<skill>/<recipe>
+```
+
+Use the focused doctor form for one intended identity. It reports active-Skill ownership, exact resolvability, partial-catalog state, component status, portable source location, resolution generation, any rejection, and bounded next actions. Use the unfiltered doctor only for catalog-wide diagnosis. A partial catalog does not imply every exact component is unavailable. If the owning Skill is inactive, report that blocker rather than locating and running its helper manually.
+
+## Persistent tool failure
+
+```text
+inspect target=tool:<name> view=status
+inspect target=tool:<name> view=schema
+```
+
+Distinguish persistence, registry admission, host registration, active-tool membership, and `callable_now`. Confirm the source identity, effective caller schema, separate tool/spawn usage, and last launch kind when exposed.
+
+If persistence succeeded but callability is false, do not use `spawn` and claim the tool worked. Follow the reported activation boundary or stop.
+
+## Run failure
+
+```text
+inspect target=run:<id> view=recipe
+inspect target=run:<id> view=trace
+inspect target=run:<id> view=control
+inspect target=runtime view=status
+```
+
+Use Recipe view for captured identity/launch evidence, Trace for bounded observations, Control for readiness/capacity/stale work, and runtime status for kernel-level health. Treat retained-history completeness honestly.
+
+## Safe failure protocol
+
+1. Keep the exact intended Recipe/tool/Run identity.
+2. Identify the owning public surface.
+3. Record exact resolver, registry, activation, or Run truth.
+4. Apply only the bounded next action returned by that owner.
+5. Retry only after the owning state is healthy.
+
+Stop if evidence remains contradictory or the requested operation cannot be proven. Never recover by copying maintained contracts, hard-coding installation paths, directly executing bundled helpers, adding `bash -lc` or `eval`, shell-backgrounding work, editing unrelated Skills, or relabeling a Recipe spawn as a tool call.

package/dist/skills/actors/references/persistent-tools.md

@@ -0,0 +1,74 @@
+# Persistent Tools
+
+Use a persistent tool when the agent should call a trusted capability by name across turns or sessions. Use `spawn` instead for one-off Recipe execution.
+
+## Choose one source mode
+
+```text
+Maintained or explicit-file Recipe
+→ register_tool from=<skill>/<recipe|path.json|path.md>
+
+Trusted command template
+→ register_tool template="..."
+
+Reviewed captured draft
+→ register_tool draft=<draft-path>
+```
+
+Do not mix source modes.
+
+## Specialize a maintained Recipe
+
+```text
+register_tool
+  name=music_player
+  from=media/player
+  defaults={"source":"~/Music/1MIX"}
+```
+
+`from` means logical direct delegation. The source remains authoritative for async behavior, caller args and types, source defaults, artifacts, Control, and runtime-owned origins. The persistent user Recipe stores only the compact specialization; do not copy inherited fields.
+
+Use `description` to narrow agent-facing intent when useful. Every supplied default must name a caller-owned source arg and satisfy its type or enum. Never default runtime-owned origins.
+
+## Prove registration
+
+Read registration as a state transition, not one success word:
+
+```text
+resolved
+→ validated
+→ persisted
+→ registry_active
+→ host_registered
+→ active_tool
+→ callable_now
+```
+
+When `callable_now` is true, call the actual generated tool and verify `launch_kind: "tool"` when provenance matters. When false, stop at the reported activation boundary and use tool/Recipe diagnosis. A Recipe spawn is not an activation test or tool invocation substitute.
+
+Use:
+
+```text
+inspect target=tool:<name> view=status
+inspect target=tool:<name> view=schema
+inspect target=recipes view=doctor
+```
+
+## Command templates
+
+Use `template` only for a trusted command definition, not to make the agent guess whether a string is command text or Recipe delegation. Give raw command tools an agent-facing description and declare or infer only caller-owned args. Use a Recipe file when reusable composition or lifecycle policy is needed.
+
+## Updates and deletion
+
+Use `update=true` only for an intentional replacement. Preserve the existing capability when candidate resolution, validation, persistence, or activation fails. Use the compact deletion form documented by the live `register_tool` schema; do not create a second deletion mechanism.
+
+## Stop rules
+
+Stop rather than:
+
+- copying source Recipe args, defaults, artifacts, Control, or helper command;
+- invoking a Skill helper by installation path;
+- using `spawn` and claiming the tool was called;
+- treating persistence as callability;
+- adding shell evaluation or backgrounding to bypass registration;
+- editing an unrelated rejected Skill component unless that repair is explicitly requested.

package/dist/skills/actors/references/recipes.md

@@ -0,0 +1,51 @@
+# Recipes
+
+A Recipe is a reusable executable definition. Address a maintained component as `<active-skill>/<direct-filename-stem>` or use an explicit `.json` / `.md` path. Recipe files do not declare their own top-level `name`.
+
+## Direct delegation
+
+Use direct delegation when the root remains fundamentally the same capability under a different persistent name, description, or caller default:
+
+```text
+media/player
+→ music_player with a default source
+```
+
+For agent-facing persistent specialization, use:
+
+```text
+register_tool from=media/player defaults={"source":"~/Music/1MIX"}
+```
+
+The delegated root inherits async behavior, args and types, defaults, artifacts, Control, and runtime-owned origins. Do not copy those fields into the wrapper.
+
+## Named import composition
+
+Use imports when authoring a graph with reusable named nodes:
+
+```json
+{
+  "imports": {
+    "review": "swarm/quorum-review",
+    "report": "artifacts/report"
+  },
+  "template": [
+    { "name": "review" },
+    { "name": "report" }
+  ]
+}
+```
+
+Imports are local definitions inside one execution graph. An imported child does not automatically make its Control contract the root Run's Control contract. Do not use imports merely to wrap one Recipe with defaults.
+
+## Caller and runtime ownership
+
+Callers provide only the effective public args. The runtime owns Recipe/Skill location, Run state, Trace, generation, owner/session, and related execution origins. Never declare, default, or override runtime-owned inputs.
+
+Keep selected model, thinking, mission, concurrency, quorum, and timeout caller-owned unless the capability Skill documents stable policy.
+
+## Resolution behavior
+
+Exact resolution uses the current immutable session Skill context. An invalid unrelated component may make catalog inventory partial, but it must not block an unrelated exact valid identity. A disabled, missing, ambiguous, or changed target fails closed without ambient fallback.
+
+If direct spawn and persistent admission disagree for the same identity, stop and diagnose. Do not switch to an absolute helper path, copy the source contract, or execute the helper directly.