@llblab/pi-actors 0.24.7 → 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:
@@ -211,15 +211,13 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
 ### M-11 Actor Termination Semantics
 
 - Priority: Medium.
-- Status: Open.
+- Status: Open; core mailbox-loop hotfix landed in 0.24.8.
 - Goal: Make `control.kill` the canonical parent-to-actor termination action while keeping `control.stop` and `control.cancel` as actor-domain messages whose meaning depends on the actor protocol.
 - Why now: Mailbox workers need a clearer lifecycle boundary before v2 patterns harden. Treating `stop`, `cancel`, and `kill` as equivalent stop messages blurs actor termination with domain-specific task or playback control.
-- Direction:
-  - Document `control.kill` as the universal lifecycle action for a parent/supervisor terminating an actor or run.
-  - Reframe `control.stop` as actor-defined domain control, such as stopping music playback or ending an actor-specific loop when that actor declares it.
-  - Reframe `control.cancel` as actor-defined domain control, such as cancelling the current subagent task while keeping the worker actor alive for later assignments.
-  - Split mailbox-loop helper semantics so lifecycle termination detection is distinct from general control-message detection.
-  - While the package is pre-1.0, allow a small intentional minor-version contract break: remove legacy treatment that aliases `control.stop` or `control.cancel` to actor termination.
+- Remaining direction:
+  - Audit packaged recipe `mailbox.accepts` declarations so `control.stop` and `control.cancel` appear only when actor-specific behavior is meaningful.
+  - Preserve `control.kill` as the universal lifecycle action for a parent/supervisor terminating an actor or run.
+  - Reframe any remaining docs that imply `control.stop` or `control.cancel` are generic runtime termination aliases.
   - Do not preserve compatibility shims for the old stop/cancel-as-termination behavior before the first 1.0 major release unless a concrete safety issue appears during implementation.
 - Acceptance:
   - Docs and actors skill advertise `control.kill` as canonical parent-to-actor termination.
@@ -242,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,16 @@
 
 ## 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.
+- `[Docs]` Updated worker and recipe guidance so backlog implementer shutdown examples use `control.kill` for runtime termination and describe `control.stop` as domain-local vocabulary.
+
 ## 0.24.7: Actor Message Kill Contract Hotfix
 
 - `[Actor Messages]` Narrowed runtime termination by actor message to `control.kill` only; `control.stop` and `control.cancel` now remain recipe-local mailbox vocabulary instead of aliases for killing/cancelling a run.

package/README.md

@@ -118,7 +118,7 @@ Steer it through messages:
 
 ```text
 message to=run:docs_review type=control.continue body=continue
-message to=run:docs_review type=control.stop body=stop
+message to=run:docs_review type=control.kill body=stop
 ```
 
 ## Actor Rooms

package/dist/lib/mailbox-loop.js

@@ -9,9 +9,7 @@ export function isMailboxLoopStopMessage(message) {
     const type = message && typeof message === "object" && "type" in message
         ? message.type
         : undefined;
-    return (type === "control.stop" ||
-        type === "control.cancel" ||
-        type === "control.kill");
+    return type === "control.kill";
 }
 function messageId(message) {
     return typeof message?.id === "string" ? message.id : undefined;

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.7
+  version: 0.25.0
 ---
 
 # Actors (pi-actors)
@@ -150,9 +150,9 @@ When using actors as backlog implementers, avoid one-shot subagents that exit af
 2. Actor posts `task.claim` to `room:<run>` before editing.
 3. Actor executes and validates the slice.
 4. Actor posts `task.result` and `awaiting_assignment`.
-5. Actor stays alive until the coordinator sends another `task.assign` or an explicit `control.stop`.
+5. Actor stays alive until the coordinator sends another `task.assign` or an explicit `control.kill`.
 
-Use `front`/`back` actors for opposite backlog ends when reducing overlap. Implementer workflows should be packaged as reusable recipe composition, not bespoke scripts: use `coordinator-locker` for queue/assignment/locking, subagent launcher recipes for execution cells, actor-message utility recipes for structured handoffs, and `lib/mailbox-loop.ts` helpers when writing mailbox-consuming workers. Mailbox loops should claim one run or branch inbox message at a time, mark success as `handled`, mark exceptions as `failed`, and may treat declared recipe-local `control.stop` / `control.cancel` / `control.kill` messages as stop messages; bounded drains may process available work until a stop message or max-message guard. Only `control.kill` is the documented runtime action that kills the actor run. If the existing recipe library cannot express the scenario, add missing reusable component recipes first, then compose the higher-level workflow from them. Supervisors should route coordinator assignments by `body.actor`, preserve the assignment as an object rather than a JSON string, and keep stopped-worker summaries tied to the original actor list.
+Use `front`/`back` actors for opposite backlog ends when reducing overlap. Implementer workflows should be packaged as reusable recipe composition, not bespoke scripts: use `coordinator-locker` for queue/assignment/locking, subagent launcher recipes for execution cells, actor-message utility recipes for structured handoffs, and `lib/mailbox-loop.ts` helpers when writing mailbox-consuming workers. Mailbox loops should claim one run or branch inbox message at a time, mark success as `handled`, mark exceptions as `failed`, and treat only `control.kill` as the generic loop termination message; `control.stop` and `control.cancel` are actor-domain messages only when the recipe declares and handles them. Bounded drains may process available work until `control.kill` or a max-message guard. If the existing recipe library cannot express the scenario, add missing reusable component recipes first, then compose the higher-level workflow from them. Supervisors should route coordinator assignments by `body.actor`, preserve the assignment as an object rather than a JSON string, and keep stopped-worker summaries tied to the original actor list.
 
 Current packaged building blocks:
 

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

package/docs/async-runs.md

@@ -146,7 +146,7 @@ The stable loop is:
 2. Actor posts `task.claim` to `room:<run>` before editing.
 3. Actor completes the slice, validates, and posts `task.result` plus `awaiting_assignment`.
 4. Actor remains alive and waits for the next coordinator message.
-5. Coordinator either sends another `task.assign` or sends `control.stop` after confirming no actionable work remains.
+5. Coordinator either sends another `task.assign` or sends `control.kill` after confirming no actionable work remains.
 
 Implementer recipes should declare this contract in `mailbox.accepts` and `mailbox.emits`. They should not self-terminate after a successful slice, and they should not silently self-select a new task unless the coordinator deliberately configured that policy for the run. This keeps task choice centralized while preserving actor-local execution autonomy.
 

package/docs/recipe-library.md

@@ -199,4 +199,4 @@ Cross-platform smoke checklist:
 - Only play trusted local files or URLs.
 - Volume is clamped to `0..100` by the wrapper.
 - Prefer a stable `run_id` such as `music` when the operator expects to control the run by name.
-- Use `message type=control.kill` only when graceful `control.stop` cancellation fails.
+- Use `message type=control.kill` for runtime termination; `control.stop` is a player-domain pause/stop command, not a generic run-kill alias.

package/docs/template-recipes.md

@@ -187,7 +187,7 @@ Recipes do not declare a second event-delivery policy. A running actor emits add
 ```json
 {
   "mailbox": {
-    "accepts": ["control.stop"],
+    "accepts": ["control.kill"],
     "emits": ["command.done", "run.done", "run.failed"]
   },
   "template": "run-subtask {prompt}"

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/mailbox-loop.ts

@@ -57,11 +57,7 @@ export function isMailboxLoopStopMessage(message: unknown): boolean {
     message && typeof message === "object" && "type" in message
       ? (message as { type?: unknown }).type
       : undefined;
-  return (
-    type === "control.stop" ||
-    type === "control.cancel" ||
-    type === "control.kill"
-  );
+  return type === "control.kill";
 }
 
 function messageId(

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.7",
+  "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.7
+  version: 0.25.0
 ---
 
 # Actors (pi-actors)
@@ -150,9 +150,9 @@ When using actors as backlog implementers, avoid one-shot subagents that exit af
 2. Actor posts `task.claim` to `room:<run>` before editing.
 3. Actor executes and validates the slice.
 4. Actor posts `task.result` and `awaiting_assignment`.
-5. Actor stays alive until the coordinator sends another `task.assign` or an explicit `control.stop`.
+5. Actor stays alive until the coordinator sends another `task.assign` or an explicit `control.kill`.
 
-Use `front`/`back` actors for opposite backlog ends when reducing overlap. Implementer workflows should be packaged as reusable recipe composition, not bespoke scripts: use `coordinator-locker` for queue/assignment/locking, subagent launcher recipes for execution cells, actor-message utility recipes for structured handoffs, and `lib/mailbox-loop.ts` helpers when writing mailbox-consuming workers. Mailbox loops should claim one run or branch inbox message at a time, mark success as `handled`, mark exceptions as `failed`, and may treat declared recipe-local `control.stop` / `control.cancel` / `control.kill` messages as stop messages; bounded drains may process available work until a stop message or max-message guard. Only `control.kill` is the documented runtime action that kills the actor run. If the existing recipe library cannot express the scenario, add missing reusable component recipes first, then compose the higher-level workflow from them. Supervisors should route coordinator assignments by `body.actor`, preserve the assignment as an object rather than a JSON string, and keep stopped-worker summaries tied to the original actor list.
+Use `front`/`back` actors for opposite backlog ends when reducing overlap. Implementer workflows should be packaged as reusable recipe composition, not bespoke scripts: use `coordinator-locker` for queue/assignment/locking, subagent launcher recipes for execution cells, actor-message utility recipes for structured handoffs, and `lib/mailbox-loop.ts` helpers when writing mailbox-consuming workers. Mailbox loops should claim one run or branch inbox message at a time, mark success as `handled`, mark exceptions as `failed`, and treat only `control.kill` as the generic loop termination message; `control.stop` and `control.cancel` are actor-domain messages only when the recipe declares and handles them. Bounded drains may process available work until `control.kill` or a max-message guard. If the existing recipe library cannot express the scenario, add missing reusable component recipes first, then compose the higher-level workflow from them. Supervisors should route coordinator assignments by `body.actor`, preserve the assignment as an object rather than a JSON string, and keep stopped-worker summaries tied to the original actor list.
 
 Current packaged building blocks:
 

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