@llblab/pi-actors 0.30.0 → 0.30.2

package/AGENTS.md

@@ -129,6 +129,8 @@ Pi host
 - Preserve JSON envelope object shape across handoffs.
 - Keep locker state generic and thin; orchestration strategy belongs in the coordinator.
 - Graceful actor retirement is opt-in through recipe/run metadata and must not infer retirement for persistent services or backlog implementers.
+- Script helpers that spawn long-lived child processes should keep those children inside the async run's owned process group unless they also provide an explicit termination bridge; `control.kill` must not leave detached playback/service descendants alive.
+- True daemon recipes are allowed, but daemon ownership belongs to the recipe/script contract: persist a pid or service handle, verify ownership before signaling, expose status/stop semantics, and bridge `control.kill` to daemon cleanup instead of relying on the generic runner to discover detached services.
 
 ## Context And Planning Hygiene
 

package/BACKLOG.md

@@ -41,6 +41,13 @@ Non-goals:
 
 No open hotfix items.
 
+## Backlog Curation Rules
+
+- Completed work belongs in `CHANGELOG.md`, not in `BACKLOG.md`.
+- File length alone is not a domain-split trigger: ~1000-line cohesive domain files are acceptable when ownership is clear.
+- Consider splitting only when a file crosses roughly 2000 lines, mixes real ownership zones, or hides a clearer domain boundary.
+- Prefer semantic compression before file splitting: fewer public nouns, consistent outcomes, compact diagnostics, and domain-owned constants/helpers.
+
 ## Minor Backlog
 
 The backlog is intentionally pruned to the 20% of work most likely to deliver 80% of value for `pi-actors` as a local actor kernel. Bias toward consolidation, smaller public surface area, and reliability over new feature breadth.
@@ -73,6 +80,20 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
   - Stale claims are reproducible and visible in worker status.
   - Tests cover stale-claim counting without adding scheduler/broker policy.
 
+### M-23 Tool Boundary Type Tightening
+
+- Priority: Low.
+- Status: Planned.
+- Goal: Remove avoidable `any` at the Pi/tool boundary where a narrow local type can express the real contract without broad rewiring.
+- Why now: `index.ts` still keeps runtime tool definitions in a `Map<string, any>`; this is small but visible in the composition root.
+- Direction:
+  - Add or reuse a narrow exported tool-definition type from the Pi adapter or tools domain.
+  - Keep SDK details behind `lib/pi.ts`.
+  - Do not introduce a broad type-modeling pass across every schema helper.
+- Acceptance:
+  - `index.ts` no longer uses `Map<string, any>` for actor tool definitions.
+  - TypeScript validation still passes without weakening public tool schemas.
+
 ### M-17 Message Delivery Outcome Contract
 
 - Priority: High.
@@ -108,6 +129,20 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
   - Tests cover valid promotion, invalid candidate, name collision, and packaged-recipe shadowing.
   - Docs explain candidate memory vs active tool memory in one compact section.
 
+### M-24 Registry Path Naming Cleanup
+
+- Priority: Low.
+- Status: Planned.
+- Goal: Reduce legacy-storage naming noise without changing the persistent file path.
+- Why now: `legacy-tool-registry.json` is still a compatibility storage path, but helper names and tests should make clear that the stable path is retained intentionally.
+- Direction:
+  - Prefer neutral helper/test wording such as registry path or retained registry storage path.
+  - Keep the on-disk filename unchanged unless a separate migration is justified.
+  - Do not reintroduce legacy migration code.
+- Acceptance:
+  - Path helpers and tests no longer imply an unfinished migration.
+  - Existing registry storage compatibility remains unchanged.
+
 ### M-19 Recipe Doctor Risk Labels v2
 
 - Priority: Medium.
@@ -193,4 +228,5 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 ```text
 Next milestone: M-14 Session Mismatch Follow-through.
 Then: M-15 Worker Stale-Claim Dogfood → M-17 Message Delivery Outcome Contract → M-18 Candidate Recipe Promotion UX.
+Small cleanup lane: M-23 Tool Boundary Type Tightening → M-24 Registry Path Naming Cleanup.
 ```

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.30.2: Music Player Kill Hotfix
+
+- `[Music Player]` Kept backend player processes inside the async run process group so `control.kill` can terminate an active music-player run without leaving detached `cvlc`/player children alive.
+- `[Docs]` Updated durable project guidance, actor skill guidance, async-run ownership docs, and recipe-library music-player notes to preserve the run-owned process-tree invariant while still allowing true daemon recipes through explicit termination bridges.
+
+## 0.30.1: Backlog Curation Hotfix
+
+- `[Backlog]` Added curation rules clarifying that completed work belongs only in the changelog, that cohesive ~1000-line domain files are acceptable, and that file splitting should follow real ownership boundaries rather than line count alone.
+- `[Backlog]` Added small cleanup candidates for typed tool-boundary tightening and retained registry-path naming clarity without expanding the public actor surface.
+
 ## 0.30.0: Composition Root Compression
 
 - `[Entrypoint]` Added a narrow Pi SDK adapter domain, moved recipe live-reload mechanics into the runtime domain, moved run-state watcher, run UI observation state, and run notification formatting into observability, moved runtime path constants and co-located skill path discovery to the paths domain, grouped core actor tool definitions in the tools domain, and shifted actor-inspector command state/parsing/render selection into the actor-inspector domain so `index.ts` keeps only live Pi wiring.

package/dist/scripts/music-player.mjs

@@ -804,7 +804,6 @@ function playOne(ctx, player, volume, track, index, count) {
     const [command, args] = playerCommand(ctx, player, volume, track);
     writeStatus(ctx, "playing", index, count, track, player, "");
     const child = spawn(command, args, {
-      detached: process.platform !== "win32",
       stdio: ["ignore", "inherit", "inherit"],
     });
     ctx.child = child;

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.30.0
+  version: 0.30.2
 ---
 
 # Actors (pi-actors)
@@ -87,6 +87,7 @@ Envelope fields:
 - 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>`).
 - 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`.
+- Long-lived child processes should remain in the run-owned process group unless the recipe implements an explicit daemon termination bridge; do not leave unowned detached services behind `control.kill`.
 
 Check `inspect view=mailbox` before domain-specific messages.
 

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

package/docs/async-runs.md

@@ -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, `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.
+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. A recipe may manage a true detached daemon, but then daemon ownership is recipe-local: the script must persist and verify a pid or service handle, expose status/stop behavior, and bridge `control.kill` to daemon cleanup. The generic runner does not scan for or guess detached services. 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.
 

package/docs/recipe-library.md

@@ -185,7 +185,7 @@ The wrapper also accepts control commands directly when a caller already has the
 scripts/music-player.mjs next ~/.pi/agent/tmp/pi-actors/runs/music
 ```
 
-Message body is queued in the recipe's run-local mailbox and reconciled by the player loop. The loop treats `wake.jsonl` and `fs.watch` as advisory signals, then verifies the durable inbox signature before taking the inbox lock so unchanged mailboxes are not reread on every tick. On Unix-like hosts, child players run in their own process group so pause/resume/next/stop controls can signal the playback subtree directly. The script writes `status.txt`, `player.json`, and track-change actor messages in the same state dir. Track-change messages stay diagnostic by default; interactive recipes should define a small command vocabulary for addressed messages, emit semantic actor messages for decision points, and let the coordinator react to messages rather than sleep-polling state.
+Message body is queued in the recipe's run-local mailbox and reconciled by the player loop. The loop treats `wake.jsonl` and `fs.watch` as advisory signals, then verifies the durable inbox signature before taking the inbox lock so unchanged mailboxes are not reread on every tick. Backend players stay inside the async run process group so `control.kill` terminates active playback with the run instead of leaving detached player children alive; player-local pause/resume/next/stop controls still signal the current backend pid or process group when available. The script writes `status.txt`, `player.json`, and track-change actor messages in the same state dir. Track-change messages stay diagnostic by default; interactive recipes should define a small command vocabulary for addressed messages, emit semantic actor messages for decision points, and let the coordinator react to messages rather than sleep-polling state.
 
 Cross-platform smoke checklist:
 

package/package.json

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

package/scripts/music-player.mjs

@@ -804,7 +804,6 @@ function playOne(ctx, player, volume, track, index, count) {
     const [command, args] = playerCommand(ctx, player, volume, track);
     writeStatus(ctx, "playing", index, count, track, player, "");
     const child = spawn(command, args, {
-      detached: process.platform !== "win32",
       stdio: ["ignore", "inherit", "inherit"],
     });
     ctx.child = child;

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.30.0
+  version: 0.30.2
 ---
 
 # Actors (pi-actors)
@@ -87,6 +87,7 @@ Envelope fields:
 - 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>`).
 - 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`.
+- Long-lived child processes should remain in the run-owned process group unless the recipe implements an explicit daemon termination bridge; do not leave unowned detached services behind `control.kill`.
 
 Check `inspect view=mailbox` before domain-specific messages.
 

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