@llblab/pi-actors 0.24.6 → 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,16 @@
 
 ## 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.
+- `[Docs]` Updated actor-message, async-run, and actor-skill guidance so only `control.kill` is documented as the action that kills an actor run.
+
 ## 0.24.6: Async Run Restart Status Hotfix
 
 - `[Async Runs]` Treat freshly spawned runner PIDs as running during a short Linux `/proc` identity grace window, preventing restart status checks and immediate run messages from misclassifying a new run as `exited` before its command line is observable.

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/tools.js

@@ -946,11 +946,7 @@ export function createActorMessageToolDefinition(deps = {}) {
                         `Message type ${message.type} is not declared in mailbox.accepts for run:${address.value}.`,
                     ]
                     : [];
-                if (message.type === "control.stop" ||
-                    message.type === "control.cancel") {
-                    result = AsyncRuns.cancelRun(address.value);
-                }
-                else if (message.type === "control.kill") {
+                if (message.type === "control.kill") {
                     result = AsyncRuns.killRun(address.value);
                 }
                 else if (message.type === "control.archive") {

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.6
+  version: 0.24.8
 ---
 
 # Actors (pi-actors)
@@ -86,7 +86,7 @@ Envelope fields:
 - Useful: `summary`, `body`, `from`, `reply_to`, `correlation_id`, `metadata`.
 - Addresses: `run:<id>`, `branch:<run>/<branch>`, `room:<run>`, `tool:<name>`, `coordinator`, `session:<id>`.
 - Room posts require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
-- Standard termination messages: `control.stop`, `control.cancel`, `control.kill`; terminal retention messages: `control.archive`, `control.prune`.
+- Runtime termination message: `control.kill` is the only documented actor message that kills a run. `control.stop` and `control.cancel` are actor-local mailbox vocabulary only when a recipe declares and handles them. Terminal retention messages: `control.archive`, `control.prune`.
 
 Check `inspect view=mailbox` before domain-specific messages.
 
@@ -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 treat `control.stop` / `control.cancel` / `control.kill` as standard stop messages; bounded drains may process available work until a stop message or 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.
+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:
 
@@ -204,7 +204,7 @@ Minimal actor recipe:
   "args": ["path:path", "model:string"],
   "defaults": {},
   "mailbox": {
-    "accepts": ["control.stop", "control.cancel", "control.kill"],
+    "accepts": ["control.kill"],
     "emits": ["command.done", "run.done", "run.failed"]
   },
   "artifacts": { "report": "{path}/report.md" },

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

package/docs/actor-messages.md

@@ -208,7 +208,7 @@ Runtime operations use the actor/message vocabulary:
 ```text
 create detached work -> spawn
 run-local control    -> message to run:<id>
-run stop/kill        -> message type control.stop/control.kill
+run force-kill       -> message type control.kill
 platform control     -> internal adapter selected from run state
 coordinator signal   -> message to coordinator/session
 tool execution       -> message to tool:<name>

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.
 
@@ -165,7 +165,7 @@ Low-level async actions map into the actor surface instead of forming a second p
 - Start → `spawn`
 - Send/control → `message`
 - Status/tail/messages/list → `inspect`
-- Stop/kill → `message` with `control.stop` or `control.kill`, with synchronous results
+- Force kill → `message` with `control.kill`, with synchronous results
 - Archive/prune terminal state → `message` with `control.archive` or `control.prune`, with active runs rejected fail-closed
 
 Compact text is returned by default so async management does not flood agent context; use verbose inspection when the full state object is needed. List output intentionally shares one state root across music, subagents, timers, and other async work; source fields such as `tool` and `recipe` distinguish run purpose when the launcher recorded them. The run root may contain a rebuildable `index.json` with run id, state directory, owner, status, update time, and recipe/tool hints; corrupt indexes fall back to recursive scan. Registered tools are the preferred user-facing surface for reusable recipes. `control.prune` accepts `body.preserve_artifacts=true` to copy existing named artifacts beside the run root before deleting terminal state.
@@ -196,14 +196,14 @@ Portable control matrix:
 | Mailbox-only endpoint | Supported | Supported | Use for cross-platform workers. |
 | FIFO endpoint | Supported | Rejected before delivery | Keep only for Unix-compatible recipes. |
 | Named-pipe endpoint | Optional | Supported | Use for native Windows live delivery. |
-| Cancel/kill | Process group signal with pid fallback | Process-tree adapter | Same public `message` API. |
+| Kill | Process group signal with pid fallback | Process-tree adapter | Same public `message type=control.kill` API. |
 
 
 Runtime wake notifications are now modeled separately from durable queues. Message handling records canonical state in file-backed mailbox/event files before attempting optional live endpoint delivery. Runs may expose a mailbox-only control endpoint when durable inbox plus wake notification is the intended delivery path; FIFO and named-pipe endpoints remain compatibility/fast-wake paths rather than the durable queue itself. Successful FIFO or named-pipe delivery marks the run inbox entry `sent`; mailbox-only delivery leaves the entry queued for the runtime to claim. `wake.jsonl` is an advisory doorbell that lets a live runtime subscribe through file-system notifications plus explicit initial, wake-triggered, and polling reconciliation callbacks. A missed wake must not lose work because actors can re-read the canonical mailbox state. Runtime loops that consume the file-backed mailbox should claim queued run inbox entries, then mark them `handled` or `failed`; the helper path uses a small lock so concurrent reconciliation callbacks do not process the same entry twice.
 
 ## Coordinator Notifications
 
-The launching coordinator should not busy-poll long-running async runs. The extension watches run state directories and delivers terminal `done`/`failed`/unhandled `killed`/`exited` transitions plus script-authored `notify`/`followup` actor messages back to the owning session. This gives the top-level async task a completion signal on the happy path while still letting recipe-local messages bubble up when scripts need finer-grained notifications. Terminal follow-ups include recipe-level named `artifacts` when declared. The generic runner also emits compact `command.done` actor messages for completed leaf commands; recipe authors declare that capability in `mailbox.emits` rather than configuring a separate delivery policy. Failures and in-flight parallel branch completions can bubble as follow-ups, while successful final leaf completions stay diagnostic to avoid flooding long sequential pipelines. Branch-level `command.done` follow-ups omit artifact manifests because the top-level terminal follow-up carries them once. Intentional `control.stop`, `control.kill`, and recipe-local stop commands stay out of follow-up context because the initiating message already returns synchronously. If a follow-up asks for direction, answer with `message` rather than starting a polling loop. Use explicit `inspect` only when a delivered follow-up requests inspection, a real decision depends on state, or a suspected stuck run needs diagnosis — never merely because a timeout elapsed.
+The launching coordinator should not busy-poll long-running async runs. The extension watches run state directories and delivers terminal `done`/`failed`/unhandled `killed`/`exited` transitions plus script-authored `notify`/`followup` actor messages back to the owning session. This gives the top-level async task a completion signal on the happy path while still letting recipe-local messages bubble up when scripts need finer-grained notifications. Terminal follow-ups include recipe-level named `artifacts` when declared. The generic runner also emits compact `command.done` actor messages for completed leaf commands; recipe authors declare that capability in `mailbox.emits` rather than configuring a separate delivery policy. Failures and in-flight parallel branch completions can bubble as follow-ups, while successful final leaf completions stay diagnostic to avoid flooding long sequential pipelines. Branch-level `command.done` follow-ups omit artifact manifests because the top-level terminal follow-up carries them once. Intentional `control.kill` and recipe-local stop commands stay out of follow-up context because the initiating message already returns synchronously or is handled by actor-local policy. If a follow-up asks for direction, answer with `message` rather than starting a polling loop. Use explicit `inspect` only when a delivered follow-up requests inspection, a real decision depends on state, or a suspected stuck run needs diagnosis — never merely because a timeout elapsed.
 
 Ambient status indicators may refresh while work is active, but coordinator attention is driven from run-state changes rather than a coordinator agent loop. This lets the coordinator continue other work after `spawn`; the run signals back through lifecycle state, results, and actor messages. The ambient triangle count represents active async work units: each running async run contributes at least one triangle, and a run with multiple active parallel command/subagent branches contributes the reported active branch count. If a coordinator starts one parent run with four active parallel branches, four triangles are shown; if the same coordinator starts five independent single-branch runs, five triangles are shown.
 
@@ -233,7 +233,7 @@ Use coordinator/session-bound messages for completion and decision points, not f
 
 An async run belongs to the current user, cwd, and launching agent session at start time. Send, cancellation, and force-kill target only the recorded runner pid when command line and cwd still match the recorded owner data. Stale pid reuse must fail closed.
 
-On Unix-like systems, cancel and kill signal the runner process group when available, then fall back to the runner pid. On native Windows, cancel and kill use Windows process-tree termination through the platform adapter. The runner starts command-template children in the owned process tree, so long-running descendants such as audio players should stop with the run instead of becoming orphaned background processes. After the process exits, status reflects the operator action as `cancelled` or `killed` instead of a generic `exited`.
+On Unix-like systems, `control.kill` signals the runner process group when available, then falls back to the runner pid. On native Windows, `control.kill` uses Windows process-tree termination through the platform adapter. The runner starts command-template children in the owned process tree, so long-running descendants such as audio players should stop with the run instead of becoming orphaned background processes. After the process exits, status reflects the operator action as `killed` instead of a generic `exited`. Programmatic `cancelRun()` remains an internal lifecycle helper for retirement and tests, but it is not a documented actor-message action.
 
 State is append-only where practical. Final result writes should be atomic. Recipe-local control endpoints and actor-message logs may live in the state dir. pi-actors core owns the generic run-local message adapter and runtime attention policy; command and message vocabularies belong to the recipe/script.
 
@@ -267,7 +267,7 @@ Interactive sessions expose compact activity with minimal screen cost:
 - With one active command, the triangle blinks between `▶` and `▷`.
 - Triangles disappear as concrete commands exit.
 - No prompt-area widget is shown by default.
-- Terminal `done`/`failed`/unhandled `killed`/`exited` transitions trigger compact follow-up context only in the launching coordinator session; intentional `cancel`, `kill`, and `stop` actions stay out of agent context because the action already reports synchronously.
+- Terminal `done`/`failed`/unhandled `killed`/`exited` transitions trigger compact follow-up context only in the launching coordinator session; intentional `kill` and actor-local stop actions stay out of agent context because the action already reports synchronously or belongs to recipe-local policy.
 - Full logs remain in state files and are accessed through `inspect target=run:<id> view=tail` or the low-level tail adapter.
 
 This keeps background work visible without blocking the agent, occupying the prompt area, or leaking async context into unrelated sessions.

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/lib/tools.ts

@@ -1328,12 +1328,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
                 `Message type ${message.type} is not declared in mailbox.accepts for run:${address.value}.`,
               ]
             : [];
-        if (
-          message.type === "control.stop" ||
-          message.type === "control.cancel"
-        ) {
-          result = AsyncRuns.cancelRun(address.value);
-        } else if (message.type === "control.kill") {
+        if (message.type === "control.kill") {
           result = AsyncRuns.killRun(address.value);
         } else if (message.type === "control.archive") {
           result = AsyncRuns.archiveRun(address.value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.24.6",
+  "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.6
+  version: 0.24.8
 ---
 
 # Actors (pi-actors)
@@ -86,7 +86,7 @@ Envelope fields:
 - Useful: `summary`, `body`, `from`, `reply_to`, `correlation_id`, `metadata`.
 - Addresses: `run:<id>`, `branch:<run>/<branch>`, `room:<run>`, `tool:<name>`, `coordinator`, `session:<id>`.
 - Room posts require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
-- Standard termination messages: `control.stop`, `control.cancel`, `control.kill`; terminal retention messages: `control.archive`, `control.prune`.
+- Runtime termination message: `control.kill` is the only documented actor message that kills a run. `control.stop` and `control.cancel` are actor-local mailbox vocabulary only when a recipe declares and handles them. Terminal retention messages: `control.archive`, `control.prune`.
 
 Check `inspect view=mailbox` before domain-specific messages.
 
@@ -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 treat `control.stop` / `control.cancel` / `control.kill` as standard stop messages; bounded drains may process available work until a stop message or 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.
+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:
 
@@ -204,7 +204,7 @@ Minimal actor recipe:
   "args": ["path:path", "model:string"],
   "defaults": {},
   "mailbox": {
-    "accepts": ["control.stop", "control.cancel", "control.kill"],
+    "accepts": ["control.kill"],
     "emits": ["command.done", "run.done", "run.failed"]
   },
   "artifacts": { "report": "{path}/report.md" },

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