@llblab/pi-actors 0.46.0 → 0.47.0

package/lib/tools-local.ts

@@ -10,6 +10,7 @@ import * as ModelContext from "./model-context.ts";
 import type { RegisteredTool } from "./config.ts";
 import * as Execution from "./execution.ts";
 import * as Prompts from "./prompts.ts";
+import type * as RecipeResolution from "./recipes-context.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import * as RecipesUsage from "./recipes-usage.ts";
 import * as Schema from "./schema.ts";
@@ -18,7 +19,7 @@ import * as ToolsResponse from "./tools-response.ts";
 type JsonSchema = Schema.JsonSchema;
 
 export interface RuntimeToolContext extends ModelContext.CurrentModelContext {
-  activeSkillRecipeContext?: RecipesReferences.ActiveSkillRecipeContext;
+  recipeResolutionContext?: RecipeResolution.RecipeResolutionContext;
   cwd: string;
   sessionManager?: { getSessionId?: () => string };
 }
@@ -67,7 +68,11 @@ function formatRuntimeToolUsageHint(
   required: string[],
   includeRunId: boolean,
 ): string {
-  const optional = cfg.args.filter((arg) => !required.includes(arg));
+  const optional = cfg.args.filter(
+    (arg) =>
+      !RecipesReferences.isRuntimeOwnedRecipeInput(arg) &&
+      !required.includes(arg),
+  );
   const exampleDefaults = {
     ...Schema.getExplicitToolArgDefaults(cfg.recipe?.args),
     ...cfg.defaults,
@@ -176,6 +181,7 @@ export function createRuntimeToolDefinition(
         ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
         : Schema.getRequiredToolArgNames(requiredTemplateConfig);
   for (const arg of cfg.args) {
+    if (RecipesReferences.isRuntimeOwnedRecipeInput(arg)) continue;
     paramSchema[arg] = typedArgSchema(arg, cfg.argTypes?.[arg]);
     if (requiredArgs.has(arg)) required.push(arg);
   }
@@ -244,7 +250,7 @@ export function createRuntimeToolDefinition(
               values: resolveRecipeToolValues(cfg, values, ctx),
             },
             ctx.cwd,
-            { skillContext: ctx.activeSkillRecipeContext },
+            { skillContext: ctx.recipeResolutionContext?.activeSkills },
           );
           return {
             content: [

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

@@ -106,6 +106,8 @@ export function compactAsyncRunStatus(value: unknown): string {
   const result = asRecord(status.result);
   const run = String(status.run ?? "<unknown>");
   const tokens = [`run=${run}`, `status=${String(status.status ?? "unknown")}`];
+  if (status.launch_kind)
+    tokens.push(`launch_kind=${String(status.launch_kind)}`);
   tokens.push(...compactModelPolicy(status.model_policy ?? progress.model_policy));
   if (status.tool) tokens.push(`tool=${String(status.tool)}`);
   if (status.recipe) tokens.push(`recipe=${String(status.recipe)}`);
@@ -238,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 =
@@ -265,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,
@@ -273,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/lib/tools-spawn.ts

@@ -11,13 +11,14 @@ import * as AsyncRuns from "./async-runs.ts";
 import { withFileMutationLock } from "./file-state.ts";
 import * as ModelContext from "./model-context.ts";
 import * as Paths from "./paths.ts";
+import type * as RecipeResolution from "./recipes-context.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import * as RecipesUsage from "./recipes-usage.ts";
 import * as Schema from "./schema.ts";
 import * as ToolsResponse from "./tools-response.ts";
 
 export interface SpawnToolContext extends ModelContext.CurrentModelContext {
-  activeSkillRecipeContext?: RecipesReferences.ActiveSkillRecipeContext;
+  recipeResolutionContext?: RecipeResolution.RecipeResolutionContext;
   cwd: string;
   sessionManager?: { getSessionId?: () => string };
 }
@@ -184,7 +185,7 @@ export function createSpawnToolDefinition<
             : {}),
         },
         ctx.cwd,
-        { skillContext: ctx.activeSkillRecipeContext },
+        { skillContext: ctx.recipeResolutionContext?.activeSkills },
       );
       const draftRecipe = writeSpawnDraftRecipe(input, meta);
       const nextActions = ToolsResponse.runNextActions(meta.run);

package/lib/tools.ts

@@ -25,6 +25,7 @@ export interface CoreActorToolDefinitionDeps<
   configPath: string;
   getActiveTools: () => string[];
   getRuntimeTool: (name: string) => unknown;
+  getRuntimeToolStatus: (name: string) => Record<string, unknown> | undefined;
   handleRuntimeControl?: (
     action: string,
     input: unknown,
@@ -32,7 +33,7 @@ export interface CoreActorToolDefinitionDeps<
   registryRuntime: Pick<
     RegisterToolRuntimeDeps<TContext>,
     "getToolNameBlocker" | "getTools" | "notify" | "registerRuntimeTool"
-  >;
+  > & { getStatus(): import("./runtime.ts").RecipeRegistryStatus };
   setActiveTools: (toolNames: string[]) => void;
 }
 
@@ -78,6 +79,8 @@ export function createCoreActorToolDefinitions<
     }),
     ToolsInspect.createInspectToolDefinition<TContext>({
       getTool: (name) => deps.getRuntimeTool(name),
+      getToolStatus: deps.getRuntimeToolStatus,
+      registryStatus: deps.registryRuntime.getStatus,
     }),
   ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.46.0",
+  "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.
+Register a trusted command directly
+→ use register_tool template="..."
 
-A Run target exposes exactly three inspect views: `recipe`, `trace`, and `control`.
+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. 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.

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

package/skills/actors/references/runs.md

@@ -0,0 +1,39 @@
+# Runs
+
+Use a Run when execution may outlive the current turn, needs declared Control, produces retained artifacts/evidence, fans out, or must remain inspectable.
+
+## Launch
+
+```text
+spawn recipe=<skill>/<recipe> values={...} as=run:<id>
+```
+
+Use the owning capability Skill to choose the Recipe and capability-specific values. Retain the returned Run id. A spawn result reports `launch_kind: "spawn"`; it is never evidence of registered-tool invocation.
+
+## Observe
+
+Normally wait for terminal follow-up. Inspect only when requested, when meaningful attention arrives, or when the Run is overdue or blocked:
+
+```text
+inspect target=run:<id> view=recipe
+inspect target=run:<id> view=trace
+inspect target=run:<id> view=control
+```
+
+Trace is bounded retained observation, so read its completeness summary. Prove final outcomes with terminal status, result, declared artifacts, and execution evidence rather than assuming retained Trace is exhaustive.
+
+## Control
+
+Send an actor-local action only when the root Recipe declares and implements it:
+
+```text
+message target=run:<id> action=<declared-action> input={...}
+```
+
+Inspect Control when readiness, capacity, stale work, or saturation matters. Put large data in an artifact and send only a bounded reference or instruction. Use runtime-owned termination for a stuck Run rather than inventing undeclared service actions.
+
+Control is not actor chat, peer routing, or a task inbox. A Recipe import does not create a peer actor. Several actors/subagents require the `swarm` methodology in addition to these Run mechanics.
+
+## Safety
+
+Operate only on owned Runs and their active generation. Never edit Run state to force an outcome, bypass process identity checks, or signal processes directly from UI/instruction code. Restart creates new generation-local evidence; inspect the exact generation before destructive lifecycle action.

package/skills/artifacts/SKILL.md

@@ -1,16 +1,33 @@
 ---
 name: artifacts
-description: Deterministic artifact writing, reporting, manifests, and bundles for reusable actor workflows.
+description: Use when an actor workflow must write reusable files, reports, manifests, or bundles with deterministic paths and declared outputs.
 ---
 
 # Artifacts
 
-Own reusable capabilities that turn bounded input or prior command output into declared files, reports, manifests, and artifact bundles.
+Use this Skill after the desired durable-output outcome is known. For generic Recipe execution, Runs, persistence, or diagnosis, follow `actors`; this Skill only selects artifact behavior.
 
-## Scope
+## Choose the outcome
 
-- Write or assemble caller-declared artifacts with explicit paths and overwrite policy.
-- Produce bounded human-readable reports and machine-readable manifests.
-- Compose validation evidence into artifact outputs without owning the validation policy.
+| Desired outcome | Recipe | Result |
+| --- | --- | --- |
+| Write one generated artifact and a machine-readable manifest, with optional validation first | `artifacts/bundle` | Primary artifact plus manifest |
+| Generate bounded normalized report content without committing a filesystem write | `artifacts/report` | Report content for review or later composition |
+| Generate and write one artifact | `artifacts/write` | Declared artifact path written with explicit mode |
+| Describe one existing or intended artifact | `artifacts/manifest` | Manifest JSON on stdout; no write |
+| Write prior pipeline output exactly | `artifacts/file-write` | Supporting stdin-to-file write; normally use inside composition |
 
-This Skill does not own repository workflow, multi-agent review methodology, Run lifecycle, retention policy, or transport delivery. Its Recipe identity is `artifacts/<filename stem>`; Recipe files have no top-level `name`. Cross-capability composition uses exact `<skill>/<recipe>` references; helper-backed Recipes use only this Skill's `scripts/` through `{skill_dir}`.
+Prefer `bundle` when both durable content and inventory evidence are required. Prefer `write` for one accepted file. Use `report` while content still needs review. Do not use `file-write` as a content generator. If one selected outcome should become a recurring named tool, use the persistent-capability workflow in `actors`; do not copy its graph.
+
+## Inputs and boundaries
+
+- Keep `input` bounded and evidence-based; choose the current model explicitly where the Recipe requires `model`.
+- Supply caller-owned `artifact_path` and, for `bundle`, a distinct `manifest_path`.
+- `write_mode=create` is the safe default and stops if the target exists. Use `overwrite` or `append` only when the requested mutation is explicit.
+- Parent directories are created by the writer. `~` is resolved for artifact paths.
+- `manifest` reports existence, size, and modification evidence; it does not validate artifact meaning.
+- Validation in `bundle` runs only when `run_validation=true` and uses the caller-supplied trusted command and scope.
+
+## Stop rules
+
+Stop rather than guessing when the target path, overwrite policy, accepted content, model, or validation command is unclear. Do not claim a durable artifact from `report` or `manifest` alone. After a Run starts, use the `actors` evidence and lifecycle protocol; this Skill does not redefine it.