@llblab/pi-actors 0.34.1 → 0.36.0

package/dist/lib/tools-inspect.js

@@ -212,6 +212,170 @@ function getPiActorsRuntimeStatus() {
 function compactPiActorsRuntimeStatus(status) {
     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, now) {
+    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) {
+    const now = Date.now();
+    const staleClaims = [];
+    const attentionMessages = [];
+    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) {
+    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, deps) {
+    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 = {
+        ...RecipesDiscovery.summarizeDiscovery(discovered),
+        drafts: RecipesDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
+    };
+    const activeRecipes = Array.isArray(recipeSummary.active)
+        ? recipeSummary.active
+        : [];
+    const highRiskRecipes = activeRecipes.filter(isTriageHighRiskRecipe);
+    const signals = getRunTriageSignals(visibleRuns);
+    const attentionMessages = signals.attention_messages;
+    const staleClaims = signals.stale_claims;
+    const invalidRecipes = Array.isArray(recipeSummary.invalid)
+        ? recipeSummary.invalid
+        : [];
+    const remediations = Array.isArray(recipeSummary.remediations)
+        ? recipeSummary.remediations
+        : [];
+    const drafts = Array.isArray(recipeSummary.drafts)
+        ? recipeSummary.drafts
+        : [];
+    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) {
+    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
+        : [];
+    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, tool) {
     const parameters = asRecord(tool.parameters);
     const required = Array.isArray(parameters.required)
@@ -314,15 +478,19 @@ export function createInspectToolDefinition(deps = {}) {
             }
             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: [
                             {
                                 type: "text",
-                                text: maybeJsonText(details, input.verbose === true, compactPiActorsRuntimeStatus(details)),
+                                text: maybeJsonText(details, input.verbose === true, view === "triage"
+                                    ? compactPiActorsTriage(details)
+                                    : compactPiActorsRuntimeStatus(details)),
                             },
                         ],
                         details,

package/dist/lib/tools-register.js

@@ -24,6 +24,7 @@ export function createRegisterToolDefinition(deps) {
             args: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.args),
             async: booleanSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.async),
             description: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.description),
+            draft: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.draft),
             name: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.name),
             state_dir: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.state_dir),
             template: unionSchema([

package/dist/lib/tools-response.js

@@ -143,15 +143,23 @@ export function compactRecipeDoctor(summary) {
     const recommendations = Array.isArray(summary.recommendations)
         ? summary.recommendations
         : [];
+    const riskSummary = Array.isArray(summary.risk_summary)
+        ? summary.risk_summary
+        : [];
     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(topAction.action, Limits.DOCTOR_ACTION_PREVIEW_CHARS);
@@ -162,7 +170,10 @@ export function compactRecipeDoctor(summary) {
         const blocked = item.blocked_fallback
             ? ` blocked=${compactPreview(item.blocked_fallback, Limits.DOCTOR_ACTION_PREVIEW_CHARS)}`
             : "";
-        lines.push(`${String(item.severity ?? "info")} kind=${String(item.kind ?? "inspect")} id=${String(item.id ?? "root")}${blocked} action=${action ?? "inspect"}`);
+        const labels = Array.isArray(item.risk_labels)
+            ? ` labels=${item.risk_labels.map(String).slice(0, 4).join(",")}`
+            : "";
+        lines.push(`${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)
         ? summary.next_actions

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.34.1
+  version: 0.36.0
 ---
 
 # Actors (pi-actors)
@@ -194,12 +194,13 @@ 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. When exposing an already-authored recipe as a user tool, 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.
+6. Declare `mailbox` for actors that accept or emit meaningful messages.
+7. Declare `artifacts` for durable outputs the coordinator should inspect.
+8. File-backed recipe identity comes from the filename basename; legacy top-level `name` fields are ignored by loaders.
+9. 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.
+10. Keep packaged recipes generic: no machine-local paths, no private companion identities, no project-specific defaults unless the recipe is explicitly project-specific.
+11. 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:
 
@@ -227,16 +228,32 @@ 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 pattern:
+
+```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 this 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 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 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 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.
+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.
 

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.34.1
+  version: 0.36.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,6 +292,8 @@ 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.
 
+Use imports as the default adapter for exposing ready recipes as local tools. A user-root recipe such as `~/.pi/agent/recipes/repo_context_check.json` should import the maintained source recipe and call `{ "name": "alias" }`, not duplicate 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 must import the skill recipe via `{agent}/skills/<skill>/recipes/<name>.json` instead of invoking the script path directly.
+
 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.
 
 ```json

package/docs/tool-registry.md

@@ -10,7 +10,7 @@ The registry source is location-discovered recipes, not a live tool-only JSON fi
 
 - `~/.pi/agent/recipes/*.json` and `*.md` are the highest-priority user recipe root and the operator-managed tool set.
 - Recipes in that root are tools by location.
-- `~/.pi/agent/recipes/drafts/*.json` stores captured inline-spawn draft recipes, not registered tools. Promote one by moving or copying it up one level into `~/.pi/agent/recipes`. `inspect target=recipes view=summary` reports their count, and verbose output lists their paths/descriptions for explicit replay by file path.
+- `~/.pi/agent/recipes/drafts/*.json` stores captured inline-spawn draft recipes, not registered tools. Promote one with `register_tool name=<tool_name> draft=<draft_path>` or by manually moving/copying it up one level into `~/.pi/agent/recipes`. `inspect target=recipes view=summary` reports their count, and verbose output lists their paths, timestamps, fingerprints, validation state, source run when known, descriptions, and template previews for explicit replay or promotion.
 - Packaged pi-actors recipes are the lower-priority standard library of declarative actor config components, not automatically registered tools.
 - Ad hoc recipe files outside the user recipe root are components unless explicitly registered/copied into `~/.pi/agent/recipes`.
 - Recipe identity is the filename basename; `~/.pi/agent/recipes/docs_review.json` and `docs_review.md` both have id/tool name `docs_review`.
@@ -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`.
 
@@ -51,7 +52,7 @@ register_tool name=call_subagent \
   template="pi -p --model {model} --no-tools {prompt}" args="prompt:string,model:string"
 ```
 
-Use `update=true` to overwrite an existing tool. Omit `template` and co-located recipe fields during update to keep the previous execution binding.
+Use `update=true` to overwrite an existing tool. Omit `template` and co-located recipe fields during update to keep the previous execution binding. To promote a captured draft, pass `name` plus `draft` with a path under `~/.pi/agent/recipes/drafts`; promotion validates the draft before writing `~/.pi/agent/recipes/<name>.json`, preserves the draft file, rejects name collisions unless `update=true`, and leaves shadowing evidence visible through `inspect target=recipes view=summary` or `view=doctor`.
 
 `template` may also be a standard command-template sequence for multi-step tools. Timeout is disabled by default; add explicit positive `timeout` values when individual steps should fail closed:
 
@@ -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
 {