@llblab/pi-actors 0.24.7 → 0.24.8

package/BACKLOG.md

@@ -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.

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 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/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.24.8
 ---
 
 # 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.24.8
 ---
 
 # 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.24.7",
+  "version": "0.24.8",
   "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.24.8
 ---
 
 # 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.24.8
 ---
 
 # Swarm