@llblab/pi-actors 0.46.1 → 0.48.0

package/dist/lib/runtime.js

@@ -7,6 +7,7 @@ import { existsSync, watch } from "node:fs";
 import { basename, dirname } from "node:path";
 import * as Paths from "./paths.js";
 import * as RecipesDiscovery from "./recipes-discovery.js";
+import * as RecipesReferences from "./recipes-references.js";
 import * as RecipesUsage from "./recipes-usage.js";
 import * as ToolsLocal from "./tools-local.js";
 export function createAutoToolsRuntime(deps) {
@@ -40,6 +41,21 @@ export function createAutoToolsRuntime(deps) {
             template: cfg.template,
         });
     }
+    function registeredToolSource(cfg) {
+        const raw = cfg.sourcePath
+            ? RecipesReferences.readRawRecipeConfig(cfg.sourcePath)
+            : undefined;
+        const template = raw?.template;
+        if (typeof template === "string" &&
+            /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(template)) {
+            return template;
+        }
+        if (typeof template === "string" &&
+            (template.endsWith(".json") || template.endsWith(".md"))) {
+            return `<explicit-file:${basename(template)}>`;
+        }
+        return "template";
+    }
     function deactivateMissingRuntimeTools(activeNames) {
         const stale = [...runtimeTools].filter((name) => !activeNames.has(name));
         if (stale.length === 0)
@@ -105,6 +121,7 @@ export function createAutoToolsRuntime(deps) {
             lines.push("Other registry diagnostics:");
             lines.push(...other.map((warning) => `• ${warning}`));
         }
+        lines.push("Next: inspect target=recipes view=doctor");
         return `${lines.join("\n")}\n`;
     }
     function loadTools(ctx, resolutionContext) {
@@ -164,9 +181,27 @@ export function createAutoToolsRuntime(deps) {
             const usage = cfg.sourcePath
                 ? RecipesUsage.readRecipeUsage(cfg.sourcePath)
                 : undefined;
+            const activation = activationFor(name);
+            const args = RecipesDiscovery.summarizeRegisteredToolArgs(cfg);
             return {
-                ...activationFor(name),
-                launch_kind: usage?.launch_kind,
+                ...activation,
+                activation_boundary: activation.callable_now
+                    ? "current_session"
+                    : !activation.host_registered
+                        ? "host_registration"
+                        : "active_tool_set",
+                persisted: Boolean(cfg.sourcePath),
+                registry_active: true,
+                source: registeredToolSource(cfg),
+                required_args: args.required,
+                optional_args: args.optional,
+                next_actions: activation.callable_now
+                    ? [`call tool ${name}`]
+                    : [
+                        `register_tool name=${name} update=true`,
+                        `inspect target=tool:${name} view=status`,
+                    ],
+                ...(usage?.launch_kind ? { launch_kind: usage.launch_kind } : {}),
                 spawn_calls: Number(usage?.spawn_calls ?? 0),
                 tool_calls: Number(usage?.tool_calls ?? 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,126 @@
 ---
 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
+```
 
-## Trace
+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 records bounded structured observations in `trace.jsonl`:
+## Core distinctions
 
-```json
-{
-  "id": "…",
-  "ts": "…",
-  "kind": "progress.update",
-  "summary": "…",
-  "data": {},
-  "level": "info",
-  "attention": "notify"
-}
+Keep these boundaries explicit:
+
+```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:
+## Local coordinator topology
 
-- `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.
+There are two distinct multi-instance shapes:
 
-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.
+- A gateway-centric system owns ingress, agent-instance creation, routing, and lifecycle outside the agents.
+- A host-coordinator system keeps the current Pi instance as the control plane; companion extensions such as Telegram provide presence, while pi-actors creates explicit local Runs for delegated work.
+
+In host-coordinator mode, the top-level agent receives declarative outcomes, preserves user authority and global context, delegates bounded concrete execution, and owns integration plus final validation. It is not merely another worker after delegation begins. One bounded implementation worker normally runs with reasoning off; consequential output receives a separate reasoning-enabled review. Several independent participants or reviewers additionally use `swarm`.
+
+Delegation is not mandatory for every prompt. Work inline when one short bounded act has one natural validation boundary and spawning would add more coordination than isolation, latency hiding, clean context, or continued coordinator availability can repay. For admitted delegation, prefer terminal follow-up and durable Trace/artifacts; inspect on meaningful attention, operator request, or an evidence-based overdue timer rather than busy polling.
+
+## Run workflow
+
+A Run is one concrete execution of a Recipe:
+
+```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.