@llblab/pi-actors 0.24.8 → 0.25.0

package/BACKLOG.md

@@ -165,7 +165,7 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
 ### M-08 Recipe Doctor Remediation UX
 
 - Priority: High.
-- Status: Open.
+- Status: Done.
 - Goal: Turn recipe doctor output into an operator action surface, not just a diagnostic listing.
 - Why now: Recipe registry warnings are intentionally actionable; the next value is helping operators decide whether to fix, disable, delete, or inspect a recipe without hiding the warning.
 - Direction:
@@ -240,8 +240,8 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 ## Suggested Milestone Order
 
 ```text
-0.25 — Operator remediation and worker maturity:
-  M-08, M-09
+0.25 — Worker maturity:
+  M-09
 
 0.26 — Package contract hardening and lifecycle semantics:
   M-10, M-11

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.25.0: Recipe Doctor Remediation UX
+
+- `[Recipe Doctor]` Added prioritized advisory remediations to recipe doctor output, including a compact top action, structured verbose remediation entries, blocked lower-priority candidates for invalid/disabled overrides, and ordered coverage for invalid, disabled, shadowed, and risky shell-boundary recipes.
+- `[Docs]` Documented the recipe doctor remediation surface in the tool registry guide.
+
 ## 0.24.8: Mailbox Loop Kill Contract Hotfix
 
 - `[Mailbox Loop]` Aligned generic mailbox-loop termination with the actor-message kill contract: only `control.kill` stops generic loop drains; `control.stop` and `control.cancel` remain actor-domain messages unless a recipe handles them explicitly.

package/dist/lib/recipe-discovery.js

@@ -273,6 +273,10 @@ function diagnosticSeverity(message) {
     return "info";
 }
 function diagnosticSuggestedAction(message) {
+    if (/world-writable|group-writable/i.test(message))
+        return "tighten recipe root permissions";
+    if (/invokes bash/i.test(message))
+        return "audit the trusted shell boundary and keep only if intentional";
     if (/must define template/i.test(message))
         return "add a template field or remove the recipe";
     if (/JSON|Expected|parse/i.test(message))
@@ -285,10 +289,6 @@ function diagnosticSuggestedAction(message) {
         return "split large prompt or data into separate files";
     if (/repeat must/i.test(message))
         return "use a positive repeat count or an array-typed repeat source";
-    if (/world-writable|group-writable/i.test(message))
-        return "tighten recipe root permissions";
-    if (/invokes bash/i.test(message))
-        return "audit the trusted shell boundary or move details to recipe doctor";
     if (/shadows/i.test(message))
         return "confirm the active override or rename one recipe";
     if (/disabled/i.test(message))
@@ -323,6 +323,84 @@ function diagnosticDetails(result) {
             String(a.message).localeCompare(String(b.message)));
     });
 }
+function remediationForEntry(entry, activePath) {
+    const riskyDiagnostics = entry.diagnostics.filter((message) => diagnosticSeverity(message) === "warning");
+    const blockedCandidate = entry.shadows[0];
+    if (entry.invalid) {
+        return {
+            id: entry.id,
+            kind: blockedCandidate ? "blocking_invalid" : "invalid",
+            severity: "error",
+            path: entry.path,
+            ...(blockedCandidate ? { blocked_candidate: blockedCandidate } : {}),
+            reason: blockedCandidate
+                ? "invalid higher-priority recipe blocks a lower-priority candidate"
+                : "recipe is invalid and cannot be exposed as a tool",
+            action: "fix recipe syntax/config, or disable/delete/archive it to restore fallback",
+        };
+    }
+    if (entry.disabled && entry.active) {
+        return {
+            id: entry.id,
+            kind: blockedCandidate ? "blocking_disabled" : "disabled",
+            severity: "warning",
+            path: entry.path,
+            ...(blockedCandidate ? { blocked_candidate: blockedCandidate } : {}),
+            reason: blockedCandidate
+                ? "disabled higher-priority recipe intentionally blocks a lower-priority candidate"
+                : "recipe is disabled and not exposed as a tool",
+            action: "keep disabled intentionally, re-enable, or delete/archive the file",
+        };
+    }
+    if (riskyDiagnostics.length > 0) {
+        return {
+            id: entry.id,
+            kind: "risky_shell_boundary",
+            severity: "warning",
+            path: entry.path,
+            reason: riskyDiagnostics[0],
+            action: "audit trusted command boundary; keep only if the recipe is local and intentional",
+        };
+    }
+    if (entry.shadowed) {
+        return {
+            id: entry.id,
+            kind: "shadowed",
+            severity: "info",
+            path: entry.path,
+            ...(activePath ? { active_path: activePath } : {}),
+            reason: activePath
+                ? `shadowed by ${activePath}`
+                : "shadowed by a higher-priority recipe",
+            action: "keep as fallback/component, merge, rename, delete, or archive",
+        };
+    }
+    return undefined;
+}
+function remediationRank(item) {
+    const kind = String(item.kind ?? "");
+    if (kind === "blocking_invalid")
+        return 0;
+    if (kind === "invalid")
+        return 1;
+    if (kind === "blocking_disabled")
+        return 2;
+    if (kind === "risky_shell_boundary")
+        return 3;
+    if (kind === "disabled")
+        return 4;
+    if (kind === "shadowed")
+        return 5;
+    return 6;
+}
+function discoveryRemediations(result) {
+    return result.entries
+        .map((entry) => remediationForEntry(entry, result.active.get(entry.id)?.path))
+        .filter((entry) => Boolean(entry))
+        .sort((a, b) => remediationRank(a) - remediationRank(b) ||
+        String(a.id).localeCompare(String(b.id)) ||
+        String(a.path).localeCompare(String(b.path)));
+}
 function recommendationForEntry(entry, activePath) {
     const recommendation = cleanupRecommendation(entry);
     if (!recommendation)
@@ -341,6 +419,7 @@ export function summarizeDiscovery(result) {
         .filter((entry) => Boolean(entry))
         .sort((a, b) => String(a.id).localeCompare(String(b.id)) ||
         String(a.path).localeCompare(String(b.path)));
+    const remediations = discoveryRemediations(result);
     return {
         active: [...result.active.values()]
             .map((entry) => ({
@@ -378,6 +457,8 @@ export function summarizeDiscovery(result) {
             .map((entry) => ({ id: entry.id, path: entry.path }))
             .sort((a, b) => a.id.localeCompare(b.id)),
         recommendations,
+        remediations,
+        top_action: remediations[0],
         diagnostics: result.diagnostics,
         diagnostic_details: diagnosticDetails(result),
         integrity_manifest: createRecipeIntegrityManifest(result),

package/dist/lib/tools.js

@@ -387,6 +387,9 @@ function compactRecipeDoctor(summary) {
     const details = Array.isArray(summary.diagnostic_details)
         ? summary.diagnostic_details
         : [];
+    const remediations = Array.isArray(summary.remediations)
+        ? summary.remediations
+        : [];
     const recommendations = Array.isArray(summary.recommendations)
         ? summary.recommendations
         : [];
@@ -396,11 +399,20 @@ function compactRecipeDoctor(summary) {
         if (severity === "error" || severity === "warning" || severity === "info")
             counts[severity] += 1;
     }
+    const topAction = asRecord(summary.top_action);
     const lines = [
-        `recipes doctor errors=${counts.error} warnings=${counts.warning} info=${counts.info} recommendations=${recommendations.length}`,
+        `recipes doctor errors=${counts.error} warnings=${counts.warning} info=${counts.info} actions=${remediations.length} recommendations=${recommendations.length}`,
     ];
-    for (const detail of details.slice(0, 8)) {
-        lines.push(`${String(detail.severity ?? "info")} id=${String(detail.id ?? "root")} action=${compactPreview(detail.action, Limits.DOCTOR_ACTION_PREVIEW_CHARS) ?? "inspect"}`);
+    if (Object.keys(topAction).length > 0) {
+        const action = compactPreview(topAction.action, Limits.DOCTOR_ACTION_PREVIEW_CHARS);
+        lines.push(`top severity=${String(topAction.severity ?? "info")} kind=${String(topAction.kind ?? "inspect")} id=${String(topAction.id ?? "root")} action=${action ?? "inspect"}`);
+    }
+    for (const item of remediations.slice(0, 8)) {
+        const action = compactPreview(item.action, Limits.DOCTOR_ACTION_PREVIEW_CHARS);
+        const blocked = item.blocked_candidate
+            ? ` blocked=${compactPreview(item.blocked_candidate, 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"}`);
     }
     return `\n${lines.join("\n")}`;
 }

package/dist/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.24.8
+  version: 0.25.0
 ---
 
 # Actors (pi-actors)

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.24.8
+  version: 0.25.0
 ---
 
 # Swarm

package/docs/tool-registry.md

@@ -23,10 +23,11 @@ Inspect the discovered registry with:
 
 ```text
 inspect target=recipes view=status
+inspect target=recipes view=doctor
 inspect target=recipes view=summary verbose=true
 ```
 
-The summary reports active, shadowed, invalid, disabled, and diagnostic entries so operators can answer why a tool is present, hidden, broken, or disabled.
+The 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 candidate paths when a broken or disabled higher-priority recipe masks a fallback.
 
 ## Registering Tools
 

package/lib/recipe-discovery.ts

@@ -403,6 +403,10 @@ function diagnosticSeverity(message: string): "info" | "warning" | "error" {
 }
 
 function diagnosticSuggestedAction(message: string): string {
+  if (/world-writable|group-writable/i.test(message))
+    return "tighten recipe root permissions";
+  if (/invokes bash/i.test(message))
+    return "audit the trusted shell boundary and keep only if intentional";
   if (/must define template/i.test(message))
     return "add a template field or remove the recipe";
   if (/JSON|Expected|parse/i.test(message))
@@ -414,10 +418,6 @@ function diagnosticSuggestedAction(message: string): string {
     return "split large prompt or data into separate files";
   if (/repeat must/i.test(message))
     return "use a positive repeat count or an array-typed repeat source";
-  if (/world-writable|group-writable/i.test(message))
-    return "tighten recipe root permissions";
-  if (/invokes bash/i.test(message))
-    return "audit the trusted shell boundary or move details to recipe doctor";
   if (/shadows/i.test(message))
     return "confirm the active override or rename one recipe";
   if (/disabled/i.test(message))
@@ -455,6 +455,93 @@ function diagnosticDetails(
   });
 }
 
+function remediationForEntry(
+  entry: DiscoveredRecipe,
+  activePath: string | undefined,
+): Record<string, unknown> | undefined {
+  const riskyDiagnostics = entry.diagnostics.filter(
+    (message) => diagnosticSeverity(message) === "warning",
+  );
+  const blockedCandidate = entry.shadows[0];
+  if (entry.invalid) {
+    return {
+      id: entry.id,
+      kind: blockedCandidate ? "blocking_invalid" : "invalid",
+      severity: "error",
+      path: entry.path,
+      ...(blockedCandidate ? { blocked_candidate: blockedCandidate } : {}),
+      reason: blockedCandidate
+        ? "invalid higher-priority recipe blocks a lower-priority candidate"
+        : "recipe is invalid and cannot be exposed as a tool",
+      action: "fix recipe syntax/config, or disable/delete/archive it to restore fallback",
+    };
+  }
+  if (entry.disabled && entry.active) {
+    return {
+      id: entry.id,
+      kind: blockedCandidate ? "blocking_disabled" : "disabled",
+      severity: "warning",
+      path: entry.path,
+      ...(blockedCandidate ? { blocked_candidate: blockedCandidate } : {}),
+      reason: blockedCandidate
+        ? "disabled higher-priority recipe intentionally blocks a lower-priority candidate"
+        : "recipe is disabled and not exposed as a tool",
+      action: "keep disabled intentionally, re-enable, or delete/archive the file",
+    };
+  }
+  if (riskyDiagnostics.length > 0) {
+    return {
+      id: entry.id,
+      kind: "risky_shell_boundary",
+      severity: "warning",
+      path: entry.path,
+      reason: riskyDiagnostics[0],
+      action: "audit trusted command boundary; keep only if the recipe is local and intentional",
+    };
+  }
+  if (entry.shadowed) {
+    return {
+      id: entry.id,
+      kind: "shadowed",
+      severity: "info",
+      path: entry.path,
+      ...(activePath ? { active_path: activePath } : {}),
+      reason: activePath
+        ? `shadowed by ${activePath}`
+        : "shadowed by a higher-priority recipe",
+      action: "keep as fallback/component, merge, rename, delete, or archive",
+    };
+  }
+  return undefined;
+}
+
+function remediationRank(item: Record<string, unknown>): number {
+  const kind = String(item.kind ?? "");
+  if (kind === "blocking_invalid") return 0;
+  if (kind === "invalid") return 1;
+  if (kind === "blocking_disabled") return 2;
+  if (kind === "risky_shell_boundary") return 3;
+  if (kind === "disabled") return 4;
+  if (kind === "shadowed") return 5;
+  return 6;
+}
+
+function discoveryRemediations(
+  result: RecipeDiscoveryResult,
+): Array<Record<string, unknown>> {
+  return result.entries
+    .map((entry) =>
+      remediationForEntry(entry, result.active.get(entry.id)?.path),
+    )
+    .filter((entry): entry is Record<string, unknown> => Boolean(entry))
+    .sort(
+      (a, b) =>
+        remediationRank(a) - remediationRank(b) ||
+        String(a.id).localeCompare(String(b.id)) ||
+        String(a.path).localeCompare(String(b.path)),
+    );
+}
+
 function recommendationForEntry(
   entry: DiscoveredRecipe,
   activePath: string | undefined,
@@ -483,6 +570,7 @@ export function summarizeDiscovery(
         String(a.id).localeCompare(String(b.id)) ||
         String(a.path).localeCompare(String(b.path)),
     );
+  const remediations = discoveryRemediations(result);
   return {
     active: [...result.active.values()]
       .map((entry) => ({
@@ -520,6 +608,8 @@ export function summarizeDiscovery(
       .map((entry) => ({ id: entry.id, path: entry.path }))
       .sort((a, b) => a.id.localeCompare(b.id)),
     recommendations,
+    remediations,
+    top_action: remediations[0],
     diagnostics: result.diagnostics,
     diagnostic_details: diagnosticDetails(result),
     integrity_manifest: createRecipeIntegrityManifest(result),

package/lib/tools.ts

@@ -470,6 +470,9 @@ function compactRecipeDoctor(summary: Record<string, unknown>): string {
   const details = Array.isArray(summary.diagnostic_details)
     ? (summary.diagnostic_details as Array<Record<string, unknown>>)
     : [];
+  const remediations = Array.isArray(summary.remediations)
+    ? (summary.remediations as Array<Record<string, unknown>>)
+    : [];
   const recommendations = Array.isArray(summary.recommendations)
     ? (summary.recommendations as Array<Record<string, unknown>>)
     : [];
@@ -479,12 +482,26 @@ function compactRecipeDoctor(summary: Record<string, unknown>): string {
     if (severity === "error" || severity === "warning" || severity === "info")
       counts[severity] += 1;
   }
+  const topAction = asRecord(summary.top_action);
   const lines = [
-    `recipes doctor errors=${counts.error} warnings=${counts.warning} info=${counts.info} recommendations=${recommendations.length}`,
+    `recipes doctor errors=${counts.error} warnings=${counts.warning} info=${counts.info} actions=${remediations.length} recommendations=${recommendations.length}`,
   ];
-  for (const detail of details.slice(0, 8)) {
+  if (Object.keys(topAction).length > 0) {
+    const action = compactPreview(
+      topAction.action,
+      Limits.DOCTOR_ACTION_PREVIEW_CHARS,
+    );
+    lines.push(
+      `top severity=${String(topAction.severity ?? "info")} kind=${String(topAction.kind ?? "inspect")} id=${String(topAction.id ?? "root")} action=${action ?? "inspect"}`,
+    );
+  }
+  for (const item of remediations.slice(0, 8)) {
+    const action = compactPreview(item.action, Limits.DOCTOR_ACTION_PREVIEW_CHARS);
+    const blocked = item.blocked_candidate
+      ? ` blocked=${compactPreview(item.blocked_candidate, Limits.DOCTOR_ACTION_PREVIEW_CHARS)}`
+      : "";
     lines.push(
-      `${String(detail.severity ?? "info")} id=${String(detail.id ?? "root")} action=${compactPreview(detail.action, Limits.DOCTOR_ACTION_PREVIEW_CHARS) ?? "inspect"}`,
+      `${String(item.severity ?? "info")} kind=${String(item.kind ?? "inspect")} id=${String(item.id ?? "root")}${blocked} action=${action ?? "inspect"}`,
     );
   }
   return `\n${lines.join("\n")}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.24.8",
+  "version": "0.25.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.24.8
+  version: 0.25.0
 ---
 
 # Actors (pi-actors)

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.24.8
+  version: 0.25.0
 ---
 
 # Swarm