@llblab/pi-actors 0.24.6 → 0.24.7

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 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/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.7
 ---
 
 # 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.
 
@@ -152,7 +152,7 @@ When using actors as backlog implementers, avoid one-shot subagents that exit af
 4. Actor posts `task.result` and `awaiting_assignment`.
 5. Actor stays alive until the coordinator sends another `task.assign` or an explicit `control.stop`.
 
-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 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.
 
 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.7
 ---
 
 # 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

@@ -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/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.7",
   "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.7
 ---
 
 # 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.
 
@@ -152,7 +152,7 @@ When using actors as backlog implementers, avoid one-shot subagents that exit af
 4. Actor posts `task.result` and `awaiting_assignment`.
 5. Actor stays alive until the coordinator sends another `task.assign` or an explicit `control.stop`.
 
-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 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.
 
 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.7
 ---
 
 # Swarm