@llblab/pi-actors 0.46.1 → 0.47.0

package/lib/tools-inspect.ts

@@ -4,7 +4,7 @@
  * 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.ts";
@@ -208,8 +208,135 @@ function portableSkillRecipePath(
     : `<active-skill:${skill}>`;
 }
 
+function portableSkillRecipeDiagnosticReason(
+  diagnostic: RecipesReferences.SkillRecipeComponentDiagnostic,
+  namespaces: Record<string, string[]>,
+): string {
+  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: string,
+  resolutionContext: RecipeResolution.RecipeResolutionContext | undefined,
+  namespaces: Record<string, string[]>,
+  inventory: RecipesReferences.SkillRecipeComponentInventory,
+  registryStatus: Runtime.RecipeRegistryStatus | undefined,
+): Record<string, unknown> {
+  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: string | undefined;
+  let rejectedReason: string | undefined;
+  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: string,
+  input: Record<string, unknown>,
   deps: InspectToolDeps,
   context: unknown,
 ): Record<string, unknown> {
@@ -245,6 +372,21 @@ function inspectRecipes(
   );
   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",
@@ -254,7 +396,10 @@ function inspectRecipes(
   }));
   const skillRecipeComponentDiagnostics = skillInventory.rejected.map(
     (diagnostic) => ({
-      error: diagnostic.reason,
+      error: portableSkillRecipeDiagnosticReason(
+        diagnostic,
+        skillRecipeNamespaces,
+      ),
       ...(diagnostic.file
         ? {
             file: portableSkillRecipePath(
@@ -271,9 +416,9 @@ function inspectRecipes(
   const discoverySummary = RecipesDiscovery.summarizeDiscovery(discovered);
   const summary = {
     ...discoverySummary,
-    ...(deps.registryStatus
+    ...(registryStatus
       ? {
-          ...deps.registryStatus(),
+          ...registryStatus,
           watched_root: "~/.pi/agent/recipes",
         }
       : {}),
@@ -399,19 +544,63 @@ function inspectTool(
     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: string, view: string, details: Record<string, unknown>): string {
   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 as unknown[] | undefined) ?? []).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}`;
 }
@@ -426,6 +615,9 @@ export function createInspectToolDefinition<TContext = unknown>(
       "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.",
@@ -453,7 +645,7 @@ export function createInspectToolDefinition<TContext = unknown>(
       if (target === "runtime") {
         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);
         if (run) details = inspectRun(run, view, input, ctx, deps);

package/lib/tools-register.ts

@@ -36,7 +36,11 @@ export function createRegisterToolDefinition<TContext>(
         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),
@@ -45,9 +49,6 @@ export function createRegisterToolDefinition<TContext>(
           nullSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.templateNull),
         ]),
         update: booleanSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.update),
-        values: looseObjectSchema(
-          Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.values,
-        ),
       },
       [],
     ),

package/lib/tools-response.ts

@@ -240,6 +240,9 @@ export function recipeRegistryNextActions(
   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 =
@@ -267,6 +270,7 @@ export function compactRecipeRegistry(
   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 as Array<Record<string, unknown>>).filter(
         (entry) => entry.current_policy,
@@ -275,7 +279,7 @@ export function compactRecipeRegistry(
   const nextActions = Array.isArray(summary.next_actions)
     ? (summary.next_actions as string[])
     : [];
-  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/package.json

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

package/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/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/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/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.