@llblab/pi-actors 0.35.0 → 0.36.0

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.35.0
+  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.35.0
+  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

@@ -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/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[],
@@ -181,6 +204,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 +461,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;