@llblab/pi-actors 0.35.0 → 0.37.0

package/lib/tools-inspect.ts

@@ -248,6 +248,181 @@ function compactPiActorsRuntimeStatus(status: Record<string, unknown>): string {
   return `\npi-actors version=${String(status.version)} mode=${String(status.mode)} path=${String(status.package_root)} entrypoint=${String(status.entrypoint)}${status.git_commit ? ` git=${String(status.git_commit)}` : ""}`;
 }
 
+function isStaleClaim(message: AsyncRuns.RunInboxMessage, now: number): boolean {
+  if (message.status !== "claimed") return false;
+  const claimedAt = Date.parse(String(message.claimed_at ?? ""));
+  return Number.isFinite(claimedAt) && now - claimedAt > 5 * 60 * 1000;
+}
+
+function getRunTriageSignals(
+  runs: Array<Record<string, unknown>>,
+): Record<string, unknown> {
+  const now = Date.now();
+  const staleClaims: Array<Record<string, unknown>> = [];
+  const attentionMessages: Array<Record<string, unknown>> = [];
+  for (const run of runs) {
+    const stateDir = String(run.state_dir ?? "");
+    const runId = String(run.run ?? "");
+    if (!stateDir) continue;
+    try {
+      for (const message of AsyncRuns.readRunInboxMessages(stateDir, 200)) {
+        if (!isStaleClaim(message, now)) continue;
+        staleClaims.push({
+          run: runId,
+          id: message.id,
+          claimed_at: message.claimed_at,
+          claimed_by: message.claimed_by,
+          type: message.type,
+        });
+      }
+    } catch {}
+    try {
+      for (const event of AsyncRuns.readRunEvents(stateDir, 80)) {
+        if (event.metadata?.requires_response !== true) continue;
+        attentionMessages.push({
+          run: runId,
+          id: event.id,
+          summary: event.summary,
+          type: event.type ?? event.event,
+        });
+      }
+    } catch {}
+  }
+  return { attention_messages: attentionMessages, stale_claims: staleClaims };
+}
+
+function isTriageHighRiskRecipe(recipe: Record<string, unknown>): boolean {
+  if (recipe.tool !== true) return false;
+  const labels = Array.isArray(recipe.risk_labels)
+    ? recipe.risk_labels.map((label) => String(label))
+    : [];
+  return labels.some((label) => label !== "risk.long_running");
+}
+
+function getPiActorsTriage(
+  ctx: unknown,
+  deps: InspectToolDeps,
+): Record<string, unknown> {
+  const runtime = getPiActorsRuntimeStatus();
+  const currentSession = ToolsAccess.getContextSessionId(ctx);
+  const allRuns = AsyncRuns.listRuns().map((run) =>
+    AsyncRuns.getRunStatus(String(run.state_dir)),
+  );
+  const visibleRuns = currentSession
+    ? allRuns.filter(
+        (run) => !run.ownerId || run.ownerId === currentSession,
+      )
+    : allRuns;
+  const activeRuns = visibleRuns.filter((run) => run.status === "running");
+  const failedRuns = visibleRuns.filter((run) => run.status === "failed");
+  const otherRuns = currentSession
+    ? allRuns.filter((run) => run.ownerId && run.ownerId !== currentSession)
+    : [];
+  const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
+  const discovered = RecipesDiscovery.discoverRecipeSources([
+    { root: recipeRoot, defaultTool: true, mutableUsage: true },
+    { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
+  ]);
+  const recipeSummary: Record<string, unknown> = {
+    ...RecipesDiscovery.summarizeDiscovery(discovered),
+    drafts: RecipesDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
+  };
+  const activeRecipes = Array.isArray(recipeSummary.active)
+    ? (recipeSummary.active as Array<Record<string, unknown>>)
+    : [];
+  const highRiskRecipes = activeRecipes.filter(isTriageHighRiskRecipe);
+  const signals = getRunTriageSignals(visibleRuns);
+  const attentionMessages = signals.attention_messages as Array<
+    Record<string, unknown>
+  >;
+  const staleClaims = signals.stale_claims as Array<Record<string, unknown>>;
+  const invalidRecipes = Array.isArray(recipeSummary.invalid)
+    ? (recipeSummary.invalid as Array<Record<string, unknown>>)
+    : [];
+  const remediations = Array.isArray(recipeSummary.remediations)
+    ? (recipeSummary.remediations as Array<Record<string, unknown>>)
+    : [];
+  const drafts = Array.isArray(recipeSummary.drafts)
+    ? (recipeSummary.drafts as Array<Record<string, unknown>>)
+    : [];
+  const nextActions = [
+    invalidRecipes.length || remediations.length
+      ? "inspect target=recipes view=doctor"
+      : "",
+    drafts.length ? "inspect target=recipes view=summary verbose=true" : "",
+    failedRuns[0]?.run
+      ? `inspect target=run:${String(failedRuns[0].run)} view=tail lines=80`
+      : "",
+    attentionMessages[0]?.run
+      ? `inspect target=run:${String(attentionMessages[0].run)} view=messages`
+      : "",
+    activeRuns.length
+      ? "inspect target=session:all view=runs status=active"
+      : "",
+  ].filter(Boolean);
+  return {
+    runtime,
+    current_session: currentSession ?? null,
+    active_runs: activeRuns.map((run) => ({
+      run: run.run,
+      ownerId: run.ownerId,
+      recipe: run.recipe,
+      status: run.status,
+    })),
+    other_session_runs: otherRuns.length,
+    invalid_recipes: invalidRecipes,
+    blocking_recipes: remediations.filter((item) =>
+      String(item.kind ?? "").startsWith("blocking_"),
+    ),
+    high_risk_recipes: highRiskRecipes.map((recipe) => ({
+      id: recipe.id,
+      path: recipe.path,
+      risk_labels: recipe.risk_labels,
+    })),
+    draft_recipes: drafts,
+    stale_claims: staleClaims,
+    recent_failed_runs: failedRuns.slice(0, 5).map((run) => ({
+      run: run.run,
+      recipe: run.recipe,
+      status: run.status,
+    })),
+    attention_messages: attentionMessages.slice(-10),
+    next_actions: [...new Set(nextActions)].slice(0, 5),
+  };
+}
+
+function compactPiActorsTriage(summary: Record<string, unknown>): string {
+  const runtime = asRecord(summary.runtime);
+  const activeRuns = Array.isArray(summary.active_runs)
+    ? summary.active_runs.length
+    : 0;
+  const invalidRecipes = Array.isArray(summary.invalid_recipes)
+    ? summary.invalid_recipes.length
+    : 0;
+  const blockingRecipes = Array.isArray(summary.blocking_recipes)
+    ? summary.blocking_recipes.length
+    : 0;
+  const highRiskRecipes = Array.isArray(summary.high_risk_recipes)
+    ? summary.high_risk_recipes.length
+    : 0;
+  const drafts = Array.isArray(summary.draft_recipes)
+    ? summary.draft_recipes.length
+    : 0;
+  const staleClaims = Array.isArray(summary.stale_claims)
+    ? summary.stale_claims.length
+    : 0;
+  const failedRuns = Array.isArray(summary.recent_failed_runs)
+    ? summary.recent_failed_runs.length
+    : 0;
+  const attention = Array.isArray(summary.attention_messages)
+    ? summary.attention_messages.length
+    : 0;
+  const nextActions = Array.isArray(summary.next_actions)
+    ? (summary.next_actions as string[])
+    : [];
+  return `\ntriage version=${String(runtime.version ?? "unknown")} mode=${String(runtime.mode ?? "unknown")} active_runs=${activeRuns} other_runs=${String(summary.other_session_runs ?? 0)} invalid_recipes=${invalidRecipes} blocking_recipes=${blockingRecipes} high_risk_recipes=${highRiskRecipes} drafts=${drafts} stale_claims=${staleClaims} failed_runs=${failedRuns} attention=${attention}${ToolsResponse.compactNextActions(nextActions)}`;
+}
+
 function compactToolActor(name: string, tool: Record<string, unknown>): string {
   const parameters = asRecord(tool.parameters);
   const required = Array.isArray(parameters.required)
@@ -414,10 +589,15 @@ export function createInspectToolDefinition<TContext = unknown>(
       }
       if (address.kind === "tool" && address.value) {
         if (address.value === "pi-actors") {
-          if (view !== "status") {
-            throw new Error("inspect tool:pi-actors supports view=status.");
+          if (view !== "status" && view !== "triage") {
+            throw new Error(
+              "inspect tool:pi-actors supports view=status or view=triage.",
+            );
           }
-          const details = getPiActorsRuntimeStatus();
+          const details =
+            view === "triage"
+              ? getPiActorsTriage(ctx, deps)
+              : getPiActorsRuntimeStatus();
           return {
             content: [
               {
@@ -425,7 +605,9 @@ export function createInspectToolDefinition<TContext = unknown>(
                 text: maybeJsonText(
                   details,
                   input.verbose === true,
-                  compactPiActorsRuntimeStatus(details),
+                  view === "triage"
+                    ? compactPiActorsTriage(details)
+                    : compactPiActorsRuntimeStatus(details),
                 ),
               },
             ],

package/lib/tools-response.ts

@@ -173,15 +173,26 @@ export function compactRecipeDoctor(summary: Record<string, unknown>): string {
   const recommendations = Array.isArray(summary.recommendations)
     ? (summary.recommendations as Array<Record<string, unknown>>)
     : [];
+  const riskSummary = Array.isArray(summary.risk_summary)
+    ? (summary.risk_summary as Array<Record<string, unknown>>)
+    : [];
   const counts = { error: 0, info: 0, warning: 0 };
   for (const detail of details) {
     const severity = String(detail.severity ?? "info");
     if (severity === "error" || severity === "warning" || severity === "info")
       counts[severity] += 1;
   }
+  const riskCount = riskSummary.reduce(
+    (total, item) => total + Number(item.count ?? 0),
+    0,
+  );
+  const topRisks = riskSummary
+    .slice(0, 4)
+    .map((item) => `${String(item.label)}:${String(item.count ?? 0)}`)
+    .join(",");
   const topAction = asRecord(summary.top_action);
   const lines = [
-    `recipes doctor errors=${counts.error} warnings=${counts.warning} info=${counts.info} actions=${remediations.length} recommendations=${recommendations.length}`,
+    `recipes doctor errors=${counts.error} warnings=${counts.warning} info=${counts.info} actions=${remediations.length} recommendations=${recommendations.length} risks=${riskCount}${topRisks ? ` top_risks=${topRisks}` : ""}`,
   ];
   if (Object.keys(topAction).length > 0) {
     const action = compactPreview(
@@ -200,8 +211,11 @@ export function compactRecipeDoctor(summary: Record<string, unknown>): string {
     const blocked = item.blocked_fallback
       ? ` blocked=${compactPreview(item.blocked_fallback, Limits.DOCTOR_ACTION_PREVIEW_CHARS)}`
       : "";
+    const labels = Array.isArray(item.risk_labels)
+      ? ` labels=${(item.risk_labels as unknown[]).map(String).slice(0, 4).join(",")}`
+      : "";
     lines.push(
-      `${String(item.severity ?? "info")} kind=${String(item.kind ?? "inspect")} id=${String(item.id ?? "root")}${blocked} action=${action ?? "inspect"}`,
+      `${String(item.severity ?? "info")} kind=${String(item.kind ?? "inspect")} id=${String(item.id ?? "root")}${blocked}${labels} action=${action ?? "inspect"}`,
     );
   }
   const nextActions = Array.isArray(summary.next_actions)

package/lib/tools.ts

@@ -27,7 +27,7 @@ export interface CoreActorToolDefinitionDeps<
   getRuntimeTool: (name: string) => unknown;
   registryRuntime: Pick<
     RegisterToolRuntimeDeps<TContext>,
-    "getExternalToolConflict" | "getTools" | "notify" | "registerRuntimeTool"
+    "getToolNameBlocker" | "getTools" | "notify" | "registerRuntimeTool"
   >;
   setActiveTools: (toolNames: string[]) => void;
 }
@@ -53,7 +53,7 @@ export function createCoreActorToolDefinitions<
     ToolsRegister.createRegisterToolDefinition<TContext>({
       configPath: deps.configPath,
       getActiveTools: deps.getActiveTools,
-      getExternalToolConflict: deps.registryRuntime.getExternalToolConflict,
+      getToolNameBlocker: deps.registryRuntime.getToolNameBlocker,
       getTools: deps.registryRuntime.getTools,
       notify: deps.registryRuntime.notify,
       registerRuntimeTool: deps.registryRuntime.registerRuntimeTool,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [
@@ -29,7 +29,8 @@
     "conformance": "node scripts/conformance.mjs",
     "test": "node --experimental-strip-types --test tests/*.test.ts",
     "pack:dry": "npm pack --dry-run",
-    "validate": "npx tsc --noEmit && npm run build && npm run check && npm test && npm run pack:dry",
+    "recipes:qa": "node scripts/validate-recipe.mjs recipes --all --qa --summary",
+    "validate": "npx tsc --noEmit && npm run recipes:qa && npm run build && npm run check && npm test && npm run pack:dry",
     "build": "node scripts/build-dist.mjs",
     "prepack": "npm run build"
   },

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