@llblab/pi-actors 0.35.0 → 0.37.0

package/dist/scripts/validate-recipe.mjs

@@ -27,9 +27,9 @@ const { readResolvedRecipeConfig } = await importRuntimeModule("recipes-referenc
 
 export function validateRecipeUsage() {
   return `Usage:
-  validate-recipe.mjs <recipe-file-or-dir> [--all]
+  validate-recipe.mjs <recipe-file-or-dir> [--all] [--qa] [--summary]
 
-Validates one template recipe file, or all *.json/*.md files in a directory when --all is set.`;
+Validates one template recipe file, or all *.json/*.md files in a directory when --all is set. Add --qa for packaged-recipe quality checks. Add --summary for compact CLI output.`;
 }
 
 function expandPath(value) {
@@ -63,14 +63,133 @@ function recipeFiles(target, all) {
     .map((file) => resolve(target, file));
 }
 
-function validateFile(file) {
+function mailboxType(value) {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object" && typeof value.type === "string")
+    return value.type;
+  return undefined;
+}
+
+function collectTemplateStrings(value, out = []) {
+  if (typeof value === "string") out.push(value);
+  else if (Array.isArray(value)) value.forEach((item) => collectTemplateStrings(item, out));
+  else if (value && typeof value === "object") {
+    collectTemplateStrings(value.template, out);
+    collectTemplateStrings(value.recover, out);
+  }
+  return out;
+}
+
+function hasPlatformNote(config) {
+  const text = [
+    config.description,
+    config.platforms,
+    config.platform_notes,
+    config.requirements,
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return /linux|macos|darwin|windows|win32|unix|wsl|cross-platform|portable/i.test(text);
+}
+
+function validateArtifactDeclarations(config) {
+  const diagnostics = [];
+  const artifacts = config.artifacts;
+  if (artifacts === undefined) return diagnostics;
+  if (!artifacts || typeof artifacts !== "object" || Array.isArray(artifacts)) {
+    diagnostics.push("artifacts: must be an object of named artifact paths");
+    return diagnostics;
+  }
+  for (const [name, value] of Object.entries(artifacts)) {
+    const path = typeof value === "string" ? value : value?.path;
+    if (typeof path !== "string" || !path.trim())
+      diagnostics.push(`artifacts.${name}: must declare a non-empty path`);
+    if (typeof path === "string" && /^\/home\//.test(path))
+      diagnostics.push(`artifacts.${name}: must not use a machine-local absolute path`);
+  }
+  return diagnostics;
+}
+
+function validateHelperPaths(file, config) {
+  const diagnostics = [];
+  for (const template of collectTemplateStrings(config.template)) {
+    if (/(^|\s)(?:node\s+)?scripts\/[\w.-]+\.mjs/.test(template))
+      diagnostics.push("template: helper scripts must be referenced through {repo}/scripts for installed packages");
+    for (const match of template.matchAll(/\{repo\}\/scripts\/([^\s"']+\.mjs)/g)) {
+      const scriptPath = join(packageRoot(), "scripts", match[1]);
+      if (!existsSync(scriptPath))
+        diagnostics.push(`template: referenced helper script not found: scripts/${match[1]}`);
+    }
+  }
+  return diagnostics;
+}
+
+function validateMailboxContract(file, config) {
+  const diagnostics = [];
+  const mailbox = config.mailbox;
+  const accepts = Array.isArray(mailbox?.accepts) ? mailbox.accepts : [];
+  const emits = Array.isArray(mailbox?.emits) ? mailbox.emits : [];
+  if (config.async === true && !mailbox)
+    diagnostics.push("mailbox: async recipes must declare mailbox metadata");
+  if (config.async === true && !accepts.map(mailboxType).includes("control.kill"))
+    diagnostics.push("mailbox.accepts: async recipes must include control.kill");
+  const allowedLegacyTypes = new Set(["awaiting_assignment"]);
+  for (const [key, entries] of Object.entries({ accepts, emits })) {
+    entries.forEach((entry, index) => {
+      const type = mailboxType(entry);
+      if (!type) diagnostics.push(`mailbox.${key}[${index}]: must be a string or object with type`);
+      else if (
+        !allowedLegacyTypes.has(type) &&
+        !/^[a-z][a-z0-9_-]*\.(?:[a-z][a-z0-9_-]*|\*)$/.test(type)
+      )
+        diagnostics.push(`mailbox.${key}[${index}]: message type must use channel.action form`);
+    });
+  }
+  const allowedDomainTermination = new Set([
+    "coordinator-locker.json",
+    "locker.json",
+    "music-player.json",
+  ]);
+  const hasDomainTermination = accepts
+    .map(mailboxType)
+    .some((type) => type === "control.stop" || type === "control.cancel");
+  if (hasDomainTermination && !allowedDomainTermination.has(file.split(/[\\/]/).pop()))
+    diagnostics.push("mailbox.accepts: control.stop/control.cancel are reserved for actor-domain handlers");
+  return diagnostics;
+}
+
+function qaDiagnostics(file, config) {
+  const diagnostics = [];
+  const warnings = [];
+  if (typeof config.description !== "string" || !config.description.trim())
+    warnings.push("description: missing or empty");
+  diagnostics.push(...validateMailboxContract(file, config));
+  diagnostics.push(...validateArtifactDeclarations(config));
+  diagnostics.push(...validateHelperPaths(file, config));
+  const platformSpecificTemplate = collectTemplateStrings(config.template).some(
+    (template) =>
+      /(^|\s)(?:systemctl|launchctl|osascript|powershell|pwsh|cmd\.exe|apt|apt-get|dnf|yum|brew|pacman|apk)(\s|$)/i.test(
+        template,
+      ),
+  );
+  if (platformSpecificTemplate && !hasPlatformNote(config))
+    diagnostics.push("platform: platform-specific templates must document platform scope");
+  return { diagnostics, warnings };
+}
+
+function qaOk(qaReport) {
+  return qaReport.diagnostics.length === 0;
+}
+
+function validateFile(file, qa = false) {
   try {
     const config = readResolvedRecipeConfig(file);
     if (!config?.template)
       throw new Error("Recipe must define a non-empty template.");
+    const qaReport = qa ? qaDiagnostics(file, config) : { diagnostics: [], warnings: [] };
     return {
       file,
-      ok: true,
+      ok: qaOk(qaReport),
       name: config.name ?? "",
       async: Boolean(config.async),
       args: Array.isArray(config.args) ? config.args : [],
@@ -93,6 +212,15 @@ function validateFile(file) {
                 : [],
             }
           : undefined,
+      ...(qa
+        ? {
+            qa: {
+              ok: qaOk(qaReport),
+              diagnostics: qaReport.diagnostics,
+              warnings: qaReport.warnings,
+            },
+          }
+        : {}),
       template: templateKind(config.template),
     };
   } catch (error) {
@@ -107,12 +235,13 @@ function validateFile(file) {
 export function validateRecipes(argv) {
   const targetArg = argv.find((arg) => !arg.startsWith("-"));
   const all = argv.includes("--all");
+  const qa = argv.includes("--qa");
   if (!targetArg || argv.includes("--help") || argv.includes("-h")) {
     return { help: true, ok: Boolean(targetArg), usage: validateRecipeUsage() };
   }
 
   const files = recipeFiles(expandPath(targetArg), all);
-  const results = files.map(validateFile);
+  const results = files.map((file) => validateFile(file, qa));
   const failed = results.filter((result) => !result.ok).length;
   return {
     ok: failed === 0,
@@ -123,10 +252,38 @@ export function validateRecipes(argv) {
   };
 }
 
+function summarizeReport(report) {
+  const results = Array.isArray(report.results) ? report.results : [];
+  return {
+    ok: report.ok,
+    total: report.total,
+    passed: report.passed,
+    failed: report.failed,
+    diagnostics: results.reduce(
+      (total, result) => total + (result.qa?.diagnostics?.length ?? 0),
+      0,
+    ),
+    warnings: results.reduce(
+      (total, result) => total + (result.qa?.warnings?.length ?? 0),
+      0,
+    ),
+    failed_files: results
+      .filter((result) => !result.ok)
+      .map((result) => ({
+        file: result.file,
+        ...(result.error ? { error: result.error } : {}),
+        ...(result.qa?.diagnostics?.length
+          ? { diagnostics: result.qa.diagnostics }
+          : {}),
+      })),
+  };
+}
+
 try {
-  const report = validateRecipes(process.argv.slice(2));
+  const argv = process.argv.slice(2);
+  const report = validateRecipes(argv);
   if (report.help) console.error(report.usage);
-  else console.log(JSON.stringify(report, null, 2));
+  else console.log(JSON.stringify(argv.includes("--summary") ? summarizeReport(report) : report, null, 2));
   process.exit(report.ok ? 0 : 1);
 } catch (error) {
   console.error(error instanceof Error ? error.message : String(error));

package/dist/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.35.0
+  version: 0.37.0
 ---
 
 # Actors (pi-actors)
@@ -194,12 +194,14 @@ Rules:
 2. `async: true` makes spawned work a detached actor run.
 3. Public knobs belong in `args`/`defaults`; hidden launch mechanics stay inside `template`.
 4. Use `imports` to compose recipes; imported recipes are definitions, not nested async runs.
-5. Declare `mailbox` for actors that accept or emit meaningful messages.
-6. Declare `artifacts` for durable outputs the coordinator should inspect.
-7. File-backed recipe identity comes from the filename basename; legacy top-level `name` fields are ignored by loaders.
-8. File-backed async recipes pass child `pi -p` actors a bounded JSONL recipe context bundle by default: raw entry/import recipe records, derived `name`, import path/alias, and `"you_are_here": true` on the launching recipe node. Set `"actor_context": false` or `"off"` to suppress it for minimal prompts.
-9. Keep packaged recipes generic: no machine-local paths, no private companion identities, no project-specific defaults unless the recipe is explicitly project-specific.
-10. Do not ship concrete model-version defaults in packaged recipes; expose `model`, `models`, and stage-specific model args so the caller must choose current policy at launch.
+5. Direct recipe delegation is the thin-wrapper case: when a `template` value is just a ready recipe name/path, the intended behavior is to delegate to that recipe rather than execute the recipe file as a program. Use this for simple handoffs and wrapper tools; use `imports` + `{ "name": "alias" }` when you need rich composition, multiple nodes, or import-specific values/defaults.
+6. When exposing an already-authored recipe as a user tool before direct delegation is available or when composition is needed, make a small wrapper recipe in `~/.pi/agent/recipes` that imports the source recipe and uses a `{ "name": "alias" }` node. Do not copy the ready recipe's script command, defaults, mailbox, or artifacts into a second template.
+7. Declare `mailbox` for actors that accept or emit meaningful messages.
+8. Declare `artifacts` for durable outputs the coordinator should inspect.
+9. File-backed recipe identity comes from the filename basename; legacy top-level `name` fields are ignored by loaders.
+10. File-backed async recipes pass child `pi -p` actors a bounded JSONL recipe context bundle by default: raw entry/import recipe records, derived `name`, import path/alias, and `"you_are_here": true` on the launching recipe node. Set `"actor_context": false` or `"off"` to suppress it for minimal prompts.
+11. Keep packaged recipes generic: no machine-local paths, no private companion identities, no project-specific defaults unless the recipe is explicitly project-specific.
+12. Do not ship concrete model-version defaults in packaged recipes; expose `model`, `models`, and stage-specific model args so the caller must choose current policy at launch.
 
 Priority for same-id recipes:
 
@@ -208,7 +210,7 @@ Priority for same-id recipes:
 3. Explicit ad hoc user recipe file outside `~/.pi/agent/recipes`.
 4. User recipe in `~/.pi/agent/recipes/*.json` or `*.md`: highest-priority operator tool surface.
 
-Only matching filename ids compete. Higher priority shadows lower priority; within one priority layer, same-id JSON shadows Markdown. An invalid or `disabled: true` higher-priority recipe blocks fallback so the agent does not silently run standard-library behavior when a user override is broken or intentionally disabled.
+Only matching filename ids compete. Higher priority shadows lower priority; within one priority layer, same-id JSON shadows Markdown. Same-id overrides are normal composition/delegation behavior, not startup-warning material. An invalid or `disabled: true` higher-priority recipe blocks fallback so the agent does not silently run standard-library behavior when a user override is broken or intentionally disabled.
 
 Muscle-memory lens: pi-actors has two durable executable-memory layers.
 
@@ -227,23 +229,53 @@ Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memo
 
 `register_tool` persists trusted local capabilities as recipe files in `~/.pi/agent/recipes/*.json`; hand-authored Markdown recipes in the same directory are also discovered as tools.
 
-Use it when a command/template/recipe should become durable agent muscle memory. Prefer typed args or placeholder-derived args; use `update=true` for replacement and `template=null` or `template=""` for deletion. `register_tool` should create/update/delete recipe files in the user recipe root; direct file editing is allowed but is the lower-level path.
+Use it when a command/template/recipe should become durable agent muscle memory. Prefer typed args or placeholder-derived args; use `update=true` for replacement and `template=null` or `template=""` for deletion. `register_tool` should create/update/delete simple recipe files in the user recipe root; direct recipe-file editing is the right path when the wrapper needs `imports` or other top-level recipe metadata not exposed by the interactive mutation API.
+
+Ready-recipe registration patterns:
+
+Thin delegation target shape:
+
+```json
+{
+  "description": "Run a ready recipe through a local tool name.",
+  "args": ["source:path", "volume:int=70"],
+  "template": "/path/to/ready-recipe.json"
+}
+```
+
+Delegation is for one-to-one handoff: expose or call a maintained recipe directly, preserving that recipe as the source of truth. If the runtime does not yet support direct recipe references in `template`, or if you need composition, use the import-node wrapper below.
+
+Composition/import wrapper:
+
+```json
+{
+  "description": "Run the ABCd context validator through its skill recipe.",
+  "imports": {
+    "validate_context": "{agent}/skills/abcd-context/recipes/validate-context.json"
+  },
+  "args": ["path:path=."],
+  "template": { "name": "validate_context" }
+}
+```
+
+Use delegation or this import pattern whenever a reusable recipe already exists: packaged pi-actors components, project-local recipes, ad hoc reviewed recipe files, and especially skill-owned recipes that wrap skill scripts. The wrapper owns only the public tool name, description, optional narrowed args/defaults, and local usage metadata. The delegated/imported recipe remains the source of truth for the script path, default values, mailbox contract, artifacts, and future fixes.
 
 Tool-registration lenses are open-ended prompts for deciding what deserves durable tool status:
 
 1. **Reliability lens**: register wrappers for operations where agents commonly omit checks, run steps out of order, pass ambiguous inputs, or recover poorly from partial failure.
 2. **Safety lens**: prefer read-only diagnostics, dry-runs, preflights, confirmations, or bounded adapters around high-impact operations before registering direct action tools.
 3. **Context-affordance lens**: register tools whose mere presence in the injected capability list should steer agents toward the right operational habit.
-4. **Existing-recipe lens**: scan already-authored recipes before inventing a new tool. Packaged recipes, ad hoc project recipes, and recipes co-located under skill directories are often the first candidates to copy/register into the user recipe root when they match a recurring local workflow.
-5. **Composition lens**: register small semantic entrypoints over reusable recipe components instead of baking one large scenario-specific shell command into a tool.
-6. **Portability lens**: keep recipe files transportable; make tool exposure a consequence of placement in `~/.pi/agent/recipes`, not recipe-owned markers or machine-local assumptions.
+4. **Existing-recipe lens**: scan already-authored recipes before inventing a new tool. Packaged recipes, ad hoc project recipes, and recipes co-located under skill directories are the first candidates to delegate to or import from a user-root wrapper when they match a recurring local workflow.
+5. **Skill-recipe lens**: when a skill ships a recipe for its script, local tools must delegate to or import that recipe instead of calling the skill script directly. This preserves the skill's maintained interface and keeps future script/default changes centralized.
+6. **Composition lens**: register small semantic entrypoints over reusable recipe components instead of baking one large scenario-specific shell command into a tool; prefer direct delegation for one recipe, imports for composed graphs.
+7. **Portability lens**: keep recipe files transportable; make tool exposure a consequence of placement in `~/.pi/agent/recipes`, not recipe-owned markers or machine-local assumptions.
 
 Default bias: register diagnostic/preflight tools before action tools, and promote existing recipes before writing new orchestration. A good persistent tool shrinks the chance of a subtle operational mistake, not just the number of keystrokes.
 
 Tool templates may be:
 
 - A foreground command template.
-- A file-backed recipe name/path.
+- A file-backed recipe name/path for thin delegation.
 - A complete recipe body, optionally `async: true`.
 
 The user recipe root is the default tool set by location. It accepts canonical JSON recipes and literate Markdown recipes with frontmatter plus fenced `template`/`json recipe` blocks; same-id JSON shadows Markdown in the same priority layer. Packaged recipes are lower-priority standard-library components and are not tools unless copied or registered into the agent recipe root. Ideal runtime behavior is reactive: create/edit/delete recipe files, validate them, then connect valid tools or surface diagnostics without requiring agents to hand-maintain a separate registry.

package/dist/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent orchestration with scoped locks and quorum consensus. Use for multi-model review, parallel scoped work, delegated audit, and coordinated subagent execution.
 metadata:
-  version: 0.35.0
+  version: 0.37.0
 ---
 
 # Swarm

package/docs/recipe-library.md

@@ -115,6 +115,8 @@ Utility recipes cover local operator workflows that do not need subagents:
 - `recipes/utility-skill-summary.json`: Use `scripts/recipe-utils.mjs` to summarize packaged skill frontmatter, body shape, formatter-safe scalar lines, and package-version alignment.
 - `recipes/utility-validate-recipe.json`: Use `scripts/validate-recipe.mjs` to validate one template recipe file, or all packaged recipes in a directory with `all: true`.
 
+Packaged QA is available through the `recipes:qa` npm script. It reports description warnings and fails exact diagnostics for async mailbox contracts, termination vocabulary, artifact paths, platform scope, helper script paths, and missing helper scripts.
+
 These recipes are intentionally small. Register them only for trusted local commands and prefer narrow scopes. Discovery diagnostics flag obvious trust-boundary shapes such as shell/eval/destructive commands; those warnings are operator review aids, not a sandbox. The helper-backed utilities share `scripts/recipe-utils.mjs` so repeated parsing/listing logic stays out of recipe strings.
 
 ## Actor OS Smoke Matrix

package/docs/template-recipes.md

@@ -292,7 +292,26 @@ An import binding may be either a string recipe path/name or an object with:
 
 A template node of `{ "name": "alias" }` is replaced with the imported recipe's command-template graph. Imported recipe defaults are merged with import `defaults`, import `values`, node `defaults`, and node `values`; later layers win. This lets a parent recipe embed a reusable recipe in a sequence or `parallel: true` branch without inventing a workflow language.
 
-Async composition stays explicit: importing a recipe reuses its command-template-shaped definition. It does not start a nested async run. Put `async: true` on the parent recipe when the combined imported graph should run detached as one run with one state dir. Ephemeral coordinator recipes may declare `retire_when: "children_terminal"` as an opt-in lifecycle hint for future graceful retirement handling; persistent services and implementer loops should omit it. For agent-callable fanout, prefer public inputs such as `prompts:array` plus `repeat: "{prompts.length}"`, then select each branch value with `{prompts[index]}` instead of baking concrete prompts or file names into the reusable recipe.
+Use imports as the default adapter for composed ready recipes. A user-root recipe such as `~/.pi/agent/recipes/repo_context_check.json` can import the maintained source recipe and call `{ "name": "alias" }` instead of duplicating the source recipe's script command. Skill scripts are the strongest version of this rule: when a skill provides `recipes/<name>.json` for its `scripts/*` entrypoint, local tools should delegate to or import the skill recipe instead of invoking the script path directly.
+
+## Direct Recipe Delegation
+
+A `template` string that resolves to a recipe name or recipe file path delegates to that recipe instead of executing the recipe file as a binary:
+
+```json
+{
+  "description": "Play music through the packaged player recipe.",
+  "async": true,
+  "defaults": { "source": "~/Music", "volume": "70" },
+  "template": "music-player"
+}
+```
+
+Delegation is a one-to-one handoff for thin wrappers and simple reuse. It uses the same bare-name priority as imports: user-root recipes under `~/.pi/agent/recipes`, then the importing recipe's directory, then packaged standard-library recipes. A higher-priority invalid or disabled recipe still blocks lower-priority fallback so operator overrides fail closed.
+
+Delegated recipes remain the source of truth for their command template, async setting, args/defaults, mailbox, artifacts, and future fixes. Wrapper recipe fields may narrow args/defaults or override lifecycle metadata. Use imports plus `{ "name": "alias" }` when you need rich composition, multiple recipe nodes, import-specific values/defaults, or a pipeline where the reusable recipe is only one step.
+
+Async composition stays explicit: importing or delegating to a recipe reuses its command-template-shaped definition. It does not start a nested async run. Put `async: true` on the parent recipe when the combined imported graph should run detached as one run with one state dir; thin delegation may inherit `async: true` from the delegated recipe. Ephemeral coordinator recipes may declare `retire_when: "children_terminal"` as an opt-in lifecycle hint for future graceful retirement handling; persistent services and implementer loops should omit it. For agent-callable fanout, prefer public inputs such as `prompts:array` plus `repeat: "{prompts.length}"`, then select each branch value with `{prompts[index]}` instead of baking concrete prompts or file names into the reusable recipe.
 
 ```json
 {

package/docs/tool-registry.md

@@ -24,14 +24,15 @@ Inspect the loaded pi-actors runtime and discovered registry with:
 
 ```text
 inspect target=tool:pi-actors view=status
+inspect target=tool:pi-actors view=triage
 inspect target=recipes view=status
 inspect target=recipes view=doctor
 inspect target=recipes view=summary verbose=true
 ```
 
-`tool:pi-actors` is a reserved runtime-status actor: it reports the loaded package version, package root, source/dist mode, entrypoint path, recipe roots, and git commit when available. Use it after reloads to confirm which extension code is actually live.
+`tool:pi-actors` is a reserved runtime-status actor. `view=status` reports the loaded package version, package root, source/dist mode, entrypoint path, recipe roots, and git commit when available. Use it after reloads to confirm which extension code is actually live. `view=triage` adds a compact attention surface for active runs, other-session runs, invalid or blocking recipes, exposed tool recipes with non-lifecycle risk labels, drafts, stale claims, failed runs, attention messages, and next inspect actions without repairing anything. Packaged components and recipes whose only label is `risk.long_running` stay in recipe doctor/summary evidence rather than triage attention.
 
-The recipe summary reports active, shadowed, invalid, disabled, and diagnostic entries so operators can answer why a tool is present, hidden, broken, or disabled. The doctor view keeps the same registry evidence but promotes an advisory action surface: compact output includes the highest-priority `top` remediation plus ordered actions for invalid/blocking, disabled, risky shell-boundary, and shadowed recipes. Verbose inspection keeps the structured `remediations`, `top_action`, diagnostic details, and blocked lower-priority fallback paths when a broken or disabled higher-priority recipe masks a fallback.
+The recipe summary reports active, shadowed, invalid, disabled, and diagnostic entries so operators can answer why a tool is present, hidden, broken, or disabled. The doctor view keeps the same registry evidence but promotes an advisory action surface: compact output includes the highest-priority `top` remediation, risk-label counts, and ordered actions for invalid/blocking, disabled, risky shell-boundary, and shadowed recipes. Verbose inspection keeps per-recipe `risk_labels`, the structured `risk_summary`, `remediations`, `top_action`, diagnostic details, and blocked lower-priority fallback paths when a broken or disabled higher-priority recipe masks a fallback. Risk labels are deterministic review aids, not execution blockers or sandbox claims.
 
 Routine shadowing is quiet. If a bare `spawn` recipe launch already fails because an invalid or `disabled: true` user recipe blocks a lower-priority fallback, the launch error adds compact tokens such as `reason=shadowed_invalid` or `reason=shadowed_disabled`, `active_path`, `blocked_fallback`, and `hint=inspect_recipes_doctor`.
 
@@ -62,18 +63,22 @@ Use `update=true` to overwrite an existing tool. Omit `template` and co-located
 ]
 ```
 
-For reusable actor workflows, register a small tool whose `template` points to an existing actor recipe instead of embedding the launch graph in the tool itself:
+For reusable actor workflows, expose an existing recipe by writing a small wrapper recipe in `~/.pi/agent/recipes` that imports the ready recipe and calls it by alias. This keeps the imported recipe as the source of truth for its script path, defaults, mailbox, artifacts, and future fixes:
 
-```text
-register_tool name=docs_review \
-  description="Start an async docs review actor" \
-  template="docs_review" \
-  args="scope:path,model:string"
+```json
+{
+  "description": "Run the ABCd context validator through its skill recipe.",
+  "imports": {
+    "validate_context": "{agent}/skills/abcd-context/recipes/validate-context.json"
+  },
+  "args": ["path:path=."],
+  "template": { "name": "validate_context" }
+}
 ```
 
-This writes or updates `~/.pi/agent/recipes/docs_review.json` with a recipe-reference template. Its location in the user recipe root makes it a tool. If the referenced recipe contains `async: true`, calling the tool starts a detached actor run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
+Use the same pattern for packaged pi-actors components, reviewed ad hoc recipes, project-local recipe files, and especially skill recipes that wrap skill scripts. Do not register a local tool that calls `~/.pi/agent/skills/<skill>/scripts/*` directly when the skill already ships a recipe. The wrapper's location in the user recipe root makes it a tool; the import preserves the ready recipe's maintained interface.
 
-When co-location is clearer than a separate file, `register_tool` writes the recipe fields directly into the user recipe file:
+When no ready recipe exists and co-location is clearer than a separate file, `register_tool` writes the recipe fields directly into the user recipe file:
 
 ```json
 {

package/index.ts

@@ -106,7 +106,6 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
     exec: CommandTemplates.execCommandTemplate,
     getActiveTools: () => pi.getActiveTools(),
-    getAllTools: () => pi.getAllTools(),
     registerTool: (definition) => {
       actorToolDefinitions.set(definition.name, definition);
       pi.registerTool(definition);

package/lib/async-runs.ts

@@ -67,11 +67,7 @@ import {
   deliverRunMessage,
   type SendRunMessageOptions,
 } from "./runs-messages.ts";
-import {
-  buildRunStatus,
-  tailFile,
-  tailLines,
-} from "./runs-status.ts";
+import { buildRunStatus, tailFile, tailLines } from "./runs-status.ts";
 import { readJsonFileResilient } from "./state-readers.ts";
 
 const RUNNER_IDENTITY_GRACE_MS = 5000;
@@ -213,8 +209,9 @@ function assertNoActiveRunState(stateDir: string): void {
 
 function resolveRecipeFile(file: string): string {
   return (
-    RecipesReferences.getRecipePath(file, DEFAULT_RECIPE_ROOT) ??
-    RecipesReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT)
+    RecipesReferences.resolveRecipeReferencePath(file, Paths.getRecipeRoot()) ??
+    RecipesReferences.getRecipePath(file, Paths.getRecipeRoot()) ??
+    RecipesReferences.resolveRecipePath(file, Paths.getRecipeRoot())
   );
 }
 

package/lib/command-templates.ts

@@ -67,6 +67,29 @@ export interface CommandTemplateExecResult {
   killed: boolean;
 }
 
+export type CommandTemplateRiskLabel =
+  | "risk.shell"
+  | "risk.eval"
+  | "risk.broad_fs_write"
+  | "risk.destructive_fs"
+  | "risk.network"
+  | "risk.external_side_effect"
+  | "risk.long_running"
+  | "risk.platform_specific"
+  | "risk.secret_touching";
+
+const COMMAND_TEMPLATE_RISK_LABEL_ORDER: CommandTemplateRiskLabel[] = [
+  "risk.shell",
+  "risk.eval",
+  "risk.destructive_fs",
+  "risk.broad_fs_write",
+  "risk.external_side_effect",
+  "risk.secret_touching",
+  "risk.network",
+  "risk.long_running",
+  "risk.platform_specific",
+];
+
 export type CommandTemplateExecCommand = (
   command: string,
   args: string[],
@@ -111,18 +134,33 @@ export function resolveInheritedDefaultReferences(
   inheritedDefaults: Record<string, unknown> | undefined,
   runtimeValues: Record<string, unknown> = {},
 ): Record<string, unknown> | undefined {
-  if (!ownDefaults || !inheritedDefaults) return ownDefaults;
+  if (!ownDefaults) return ownDefaults;
   const resolved = { ...ownDefaults };
+  const values = { ...(inheritedDefaults ?? {}), ...runtimeValues };
   for (const [key, value] of Object.entries(ownDefaults)) {
     if (typeof value !== "string") continue;
     const exact = /^\{([A-Za-z_][A-Za-z0-9_-]*)\}$/.exec(value);
-    if (
-      !exact ||
-      Object.hasOwn(runtimeValues, exact[1]) ||
-      !Object.hasOwn(inheritedDefaults, exact[1])
-    )
+    if (exact && Object.hasOwn(values, exact[1])) {
+      resolved[key] = values[exact[1]];
       continue;
-    resolved[key] = inheritedDefaults[exact[1]];
+    }
+    const indexed = value.match(
+      /^\{([A-Za-z_][A-Za-z0-9_-]*)\[([A-Za-z_][A-Za-z0-9_-]*|\d+)\]\}$/,
+    );
+    if (!indexed) continue;
+    const source = values[indexed[1]];
+    const indexValue = /^\d+$/.test(indexed[2])
+      ? indexed[2]
+      : values[indexed[2]];
+    const index = Number(indexValue);
+    if (
+      Array.isArray(source) &&
+      Number.isInteger(index) &&
+      index >= 0 &&
+      index < source.length
+    ) {
+      resolved[key] = source[index] ?? "";
+    }
   }
   return resolved;
 }
@@ -181,6 +219,97 @@ function hasRiskyPathArg(args: string[]): boolean {
   );
 }
 
+function sortRiskLabels(
+  labels: Iterable<CommandTemplateRiskLabel>,
+): CommandTemplateRiskLabel[] {
+  const unique = new Set(labels);
+  return COMMAND_TEMPLATE_RISK_LABEL_ORDER.filter((label) => unique.has(label));
+}
+
+function hasAnyArg(args: string[], values: string[]): boolean {
+  return args.some((arg) => values.includes(arg.toLowerCase()));
+}
+
+function hasSecretTouchingText(parts: string[]): boolean {
+  return parts.some((part) =>
+    /(^|[{}._\-\s/])(?:secret|token|password|passwd|credential|api[_-]?key|private[_-]?key|\.env|ssh[_-]?key)(?:[{}._\-\s/]|$)/i.test(
+      part,
+    ),
+  );
+}
+
+function getLeafCommandTemplateRiskLabels(
+  config: CommandTemplateLeafConfig,
+): CommandTemplateRiskLabel[] {
+  const parts = splitCommandTemplate(config.template);
+  const command = getExecutableName(parts[0]);
+  const args = parts.slice(1);
+  const labels = new Set<CommandTemplateRiskLabel>();
+  if (["bash", "sh", "zsh", "fish"].includes(command)) {
+    labels.add("risk.shell");
+    if (hasAnyFlag(args, ["-c"])) labels.add("risk.eval");
+  }
+  if (
+    ["node", "deno", "bun"].includes(command) &&
+    hasAnyFlag(args, ["-e", "--eval"])
+  ) {
+    labels.add("risk.eval");
+  }
+  if (
+    ["python", "python3", "perl", "ruby"].includes(command) &&
+    hasAnyFlag(args, ["-c", "-e"])
+  ) {
+    labels.add("risk.eval");
+  }
+  if (
+    command === "rm" &&
+    (args.some((arg) => /^-[^-]*r/.test(arg) || /^-[^-]*f/.test(arg)) ||
+      hasRiskyPathArg(args))
+  ) {
+    labels.add("risk.destructive_fs");
+  }
+  if (["mv", "cp", "rsync"].includes(command) && hasRiskyPathArg(args)) {
+    labels.add("risk.broad_fs_write");
+  }
+  if (
+    ["curl", "wget", "ssh", "scp", "sftp", "rsync", "nc", "ncat", "telnet", "ftp"].includes(
+      command,
+    ) ||
+    (command === "git" &&
+      hasAnyArg(args, ["clone", "fetch", "pull", "push", "ls-remote"])) ||
+    ["npm", "pnpm", "yarn", "pip", "cargo"].includes(command)
+  ) {
+    labels.add("risk.network");
+  }
+  if (
+    ["gh", "glab", "hub", "kubectl", "terraform"].includes(command) ||
+    (command === "git" && hasAnyArg(args, ["push"])) ||
+    (["npm", "pnpm", "yarn"].includes(command) &&
+      hasAnyArg(args, ["publish", "login", "logout", "deprecate"]))
+  ) {
+    labels.add("risk.external_side_effect");
+  }
+  if (
+    command === "sleep" ||
+    command === "watch" ||
+    (command === "tail" && hasAnyFlag(args, ["-f"])) ||
+    hasAnyArg(args, ["--watch", "--serve", "serve"])
+  ) {
+    labels.add("risk.long_running");
+  }
+  if (
+    ["systemctl", "launchctl", "osascript", "open", "xdg-open", "powershell", "pwsh", "cmd.exe", "apt", "apt-get", "dnf", "yum", "brew", "pacman", "apk", "xclip", "wl-copy"].includes(
+      command,
+    )
+  ) {
+    labels.add("risk.platform_specific");
+  }
+  if (["pass", "gpg", "ssh-add"].includes(command) || hasSecretTouchingText(parts)) {
+    labels.add("risk.secret_touching");
+  }
+  return sortRiskLabels(labels);
+}
+
 function getLeafCommandTemplateWarnings(
   config: CommandTemplateLeafConfig,
 ): string[] {
@@ -347,6 +476,16 @@ export function getCommandTemplateWarnings(
   ];
 }
 
+export function getCommandTemplateRiskLabels(
+  config: CommandTemplateConfig,
+): CommandTemplateRiskLabel[] {
+  return sortRiskLabels(
+    expandCommandTemplateConfigs(config).flatMap((leaf) =>
+      getLeafCommandTemplateRiskLabels(leaf),
+    ),
+  );
+}
+
 function parseCommandTemplateArgToken(value: string): {
   name: string;
   defaultValue?: string;