@llblab/pi-actors 0.19.4 → 0.19.11

package/AGENTS.md

@@ -14,7 +14,7 @@
 ## Topology
 
 - `/index.ts`: Minimal extension coordinator/composition root; it wires live pi ports and should avoid owning domain behavior
-- `/lib/*.ts`: Flat Domain DAG modules for cohesive reusable behavior; `command-templates.ts` mirrors the shared portable command-template standard, `schema.ts` owns tool arg declarations and placeholder-derived tool schemas, `identity.ts` owns names, `config.ts` owns config persistence, `registry.ts` owns registry register/update/delete use-cases, `output.ts` owns result formatting/truncation, `execution.ts` owns registered-tool execution, `recipe-references.ts` owns template recipe reference detection and path resolution, `async-runs.ts` owns async run state, `actor-rooms.ts` owns room timelines/rosters/communication snapshots, `actor-inspector-tui.ts` owns compact terminal previews and selected-message inspection for actor communications, `observability.ts` owns ambient run summaries, `temp.ts` owns pi-agent temp cleanup, `prompts.ts` owns LLM-facing copy, `tools.ts` owns pi-facing tool definitions for both `register_tool`, async run primitives, and generated runtime tools, `runtime.ts` owns load/conflict/registration coordination, and `paths.ts` owns config/tmp path resolution
+- `/lib/*.ts`: Flat Domain DAG modules for cohesive reusable behavior; `command-templates.ts` mirrors the shared portable command-template standard, `schema.ts` owns tool arg declarations and placeholder-derived tool schemas, `identity.ts` owns names, `config.ts` owns config persistence, `registry.ts` owns registry register/update/delete use-cases, `output.ts` owns result formatting/truncation, `execution.ts` owns registered-tool execution, `recipe-references.ts` owns template recipe reference detection and path resolution, `async-runs.ts` owns async run state, `actor-rooms.ts` owns room timelines/rosters/communication snapshots with burst-safe roster and branch snapshot writes, locked branch-local inbox mutations, plus status reads that avoid parsing full timelines, `actor-inspector-tui.ts` owns compact terminal previews, branch-inbox unread/current-branch filtering, and selected-message inspection for actor communications, `observability.ts` owns ambient run summaries, `temp.ts` owns pi-agent temp cleanup, `prompts.ts` owns LLM-facing copy, `tools.ts` owns pi-facing tool definitions for both `register_tool`, async run primitives, and generated runtime tools, `runtime.ts` owns load/conflict/registration coordination, and `paths.ts` owns config/tmp path resolution
 - `index.ts` should import local domains as namespaces (`import * as CommandTemplates from "./lib/command-templates.ts"`) so orchestration reads through domain names instead of flat helper imports
 - `/scripts/*.mjs`: Thin helper processes for detached async run execution; keep policy in registered tool config and reusable logic in `/lib`
 - `/recipes/*.json`: Packaged standard recipe library; keep recipes optional, composable, and policy-light; prefer public args for operator/agent decisions instead of baking project-specific prompts, file names, or concrete model-version defaults into reusable recipes
@@ -43,17 +43,17 @@
 - `Typed arg authoring`: Typed args support `string`, `path`, `int`, `number`, `bool`, and `enum(...)` plus two equivalent readability styles: metadata-first (`args` + `defaults` + simple `{name}` placeholders) for long command lines, and inline-first (`{name:type=default}` placeholders) for compact one-property templates | Trigger: Changing arg parsing, docs, schema generation, or registry serialization | Action: Preserve both styles, keep explicit `args` type declarations higher priority than inline placeholder types, and make breaking cleanup explicit when removing old arg shapes
 - `Template recipe graph`: The valid execution chain is `tool → template → recipe → run → template`; file-backed and co-located recipes are storage variants of that chain | Trigger: Adding registry bindings, recipes, docs, or runtime shortcuts | Action: Keep command templates synchronous and portable, use `async: true` as the detached run switch, require every recipe to own `template` directly, and reject cyclic shortcuts such as recipe-owned `tool`
 - `Layer boundary discipline`: Command-template evolution must be separated from template-recipe configuration and async-run lifecycle configuration | Trigger: Adding syntax, placeholders, imports, async controls, or docs | Action: Put portable execution graph semantics in `docs/command-templates.md`, recipe storage/import/default/reference behavior in `docs/template-recipes.md`, and detached lifecycle/state/IPC behavior in `docs/async-runs.md`; type imported recipes as command-template-shaped recipe definitions, not async-run instances
-- `Executable script recipes`: Recipe templates may point directly at executable helper scripts, including JavaScript `.mjs` files with shebangs; do not prefix such recipes with `node` unless the script is intentionally not executable | Trigger: Adding or editing script-backed recipes and docs | Action: Keep the script executable bit, call `{repo}/scripts/name.mjs ...` directly, and keep the standard library on one maintained wrapper per capability unless a second wrapper has a concrete platform reason
+- `Executable script recipes`: Recipe templates may point directly at executable helper scripts, including JavaScript `.mjs` files with shebangs; do not prefix such recipes with `node` unless the script is intentionally not executable | Trigger: Adding or editing script-backed recipes and docs | Action: Keep the script executable bit, call `{repo}/scripts/name.mjs ...` directly, keep the standard library on one maintained wrapper per capability unless a second wrapper has a concrete platform reason, and ensure installed npm script entrypoints do not import `.ts` files from under `node_modules` through Node native type stripping
 - `Registry safety boundaries`: Tool definitions use `template`, not `script`, and built-in/core tool names must not be shadowed | Trigger: Loading/editing persisted config or registration logic | Action: Reject legacy `script` entries explicitly, avoid silent user-config rewrites outside the repo, and keep conflict checks before persistence/runtime registration
 - `Async run observability`: Ambient triangles count active async work units across the visible run tree: each running async run contributes at least one triangle, reported active parallel command/subagent branches contribute the visible branch count when greater than one, and descendant `pi -p` subagent processes are folded in so coordinator-plus-workers scenarios expand beyond a single coordinator marker. Event-driven terminal/outbox watchers should initiate follow-up for unhandled terminal completion/failure states, failed or in-flight `command.done` branch completions, and coordinator-bound script-authored messages with bounded body previews; actor `message` is the explicit coordinator-to-run command channel paired with these upward events. Do not restore busy-polling loops, sleep-then-status smoke examples, duplicate follow-ups for final successful leaf commands, or duplicate follow-ups for `cancel`, `kill`, or control-stop actions already handled by synchronous tool results. | Trigger: Changing async run UI, notifications, actor-message routing, or smoke-test interpretation | Action: Preserve branch-aware triangles from `progress.activeSubagents`, runtime-inferred branch bubbling for packaged fanout completion, process-tree expansion for coordinator-launched workers, terminal notifications as event-driven behavior, and docs/examples that teach reactive run→coordinator→message loops before sleep-polling patterns.
 - `Communication direction`: The design target is an organic universal message layer across sync tasks, async runs, branches, tools, and coordinators. Breaking changes are allowed to compress concepts, remove accidental duplication, and make duplex communication symmetric where the domain is symmetric. | Trigger: Designing APIs or recipes that communicate | Action: Prefer a concentrated actor/message protocol (`spawn`, `message`, `inspect`, addressed endpoints, typed message envelopes, mailbox accepts/emits) over exposing FIFO/outbox/status mechanics directly; use one envelope for upward, downward, lateral, parent/branch, and branch/parent messages; absorb runtime async primitives into actor API instead of preserving parallel public concepts.
 - `Runtime IO discipline`: Tool stdout and temp state must stay bounded and local | Trigger: Changing execution, formatting, temp files, run state, logs, or artifacts | Action: Keep tail truncation/full-output temp files/failure formatting intact; keep extension-owned temp state under `~/.pi/agent/tmp/pi-actors` unless explicitly overridden
 - `Backlog is planning, not history`: `BACKLOG.md` should contain only completable future work with current task/scope/exit criteria; completed delivery history belongs in `CHANGELOG.md`, and durable or evergreen behavior belongs in `AGENTS.md`, README, docs, or skills | Trigger: Editing backlog or reconciling completed slices | Action: Remove historical progress narratives, version-scoped headings, watch-mode/monitoring principles, open-ended “continue evolving” items, and conditional “if usage proves” notes unless they are framed as a concrete gated task; keep priority order and prefer an 80/20 focus list when many remaining tasks compete for attention
 - `Release artifact hygiene`: PR/release summaries become stale during active branch work and do not belong in the repository documentation tree | Trigger: Preparing release notes or PR bodies | Action: Create temporary/operator-facing artifacts outside the repo only during explicit release finalization; keep durable release evidence in `CHANGELOG.md` and open gates in `BACKLOG.md`
-- `Graceful actor retirement`: Coordinator/helper actors that exist only to supervise a bounded worker tree should have explicit retirement semantics instead of relying on the operator or LLM to remember cleanup | Trigger: Designing coordinator recipes, helper actors, worker fanout, locker-backed swarms, or auto-stop behavior | Action: Make retirement opt-in through recipe/run metadata, retire only after observed child actors or descendant workers are terminal and outputs are flushed, prefer graceful control messages before process termination, record retirement events, and never infer retirement for persistent services or backlog implementers
+- `Graceful actor retirement`: Coordinator/helper actors that exist only to supervise a bounded worker tree should have explicit retirement semantics instead of relying on the operator or LLM to remember cleanup | Trigger: Designing coordinator recipes, helper actors, worker fanout, locker-backed swarms, or auto-stop behavior | Action: Make retirement opt-in through recipe/run metadata, keep candidates blocked while active command-template branches or descendant `pi -p` workers are still running, retire only after observed child actors are terminal and outputs are flushed, prefer graceful control messages before process termination, record retirement events, and never infer retirement for persistent services or backlog implementers
 - `Persistent implementer workflows are recipe composition`: Backlog implementer scenarios should be launched through reusable component recipes, not one-off scripts or ad hoc shell orchestration | Trigger: Designing implementer swarms, backlog workers, coordinator-assigned task loops, or related recipes | Action: Compose cells such as `coordinator-locker`, subagent launchers, and actor-message utilities; preserve JSON envelope object shape across handoffs; add missing reusable component recipes only when needed; update the actors skill launcher map with supported scenarios
 - `Modular coordination and separate lock state`: The coordination of multi-agent workflows is split into two cleanly decoupled layers: the active coordinator and the stateful locker. The locker manages task queueing and resource lock leases over Unix FIFO/pipes without project policy. The coordinator script (`scripts/coordinator.mjs`) manages process pools, rooms, and lifecycles, and supports different pluggable mode strategies (`pipeline`, `fanout`, `pool`, `consensus`). | Trigger: Modifying coordination scripts, queues, locking, or parallel worker flows | Action: Keep the locker generic and thin, and implement all orchestration strategy rules inside the multi-mode coordinator.
-- `Active branch inbox queues`: Direct branch messages are active, work-triggering inbox queues rather than passive files. During subagent execution, the coordinator automatically claims (`claimed`), injects, and handles (`handled`/`failed`) queued branch-local direct messages to allow interactive/resumable worker workflows. | Trigger: Delivering branch messages, executing subagents, or updating branch queues | Action: Ensure direct messages can continue or wake long-lived branch runners, and keep the FIFO queue status transitions clean and fully tested.
+- `Active branch inbox queues`: Direct branch messages are active, work-triggering inbox queues rather than passive files. During subagent execution, the coordinator atomically claims (`claimed`), assigns missing message IDs, injects, and handles (`handled`/`failed`) queued branch-local direct messages to allow interactive/resumable worker workflows. | Trigger: Delivering branch messages, executing subagents, or updating branch queues | Action: Ensure direct messages can continue or wake long-lived branch runners, guard branch-local inbox append/status rewrites with the branch inbox lock, and keep the FIFO queue status transitions clean and fully tested.
 - `Recipe library growth is demand-driven`: Packaged recipes should grow from concrete repeated task patterns, not speculative scenario catalogs | Trigger: Adding packaged utilities, pipelines, or component recipes | Action: Prefer existing component composition, keep recipes policy-light with caller-owned prompts/models/paths/knobs, avoid scenario-specific scripts when existing components suffice, and document new reusable launch scenarios in the actors skill only after the recipe exists
 - `Context sync`: Meaningful implementation or docs changes must reconcile `BACKLOG.md`, `CHANGELOG.md`, README, and docs navigation | Trigger: Closing, narrowing, or discovering work | Action: Run the context validator before final status when practical
 - `Public path hygiene`: Published docs must not include machine-local absolute paths | Trigger: Adding validation commands, examples, or local instructions to README/AGENTS/docs/changelog | Action: Use `~/.pi/...`, `<repo>/...`, `${SKILL_DIR}/...`, or relative paths

package/BACKLOG.md

@@ -8,19 +8,13 @@
 - Goal: Continue evolving actor communication without adding a second public messaging model.
 - Direction:
   - Evaluate whether room storage/routing should remain built into the tool adapter or move behind a dedicated non-LLM communication actor recipe/script, possibly singleton-scoped. Preserve the same public `room:<run>` address and envelope either way.
+  - Treat the next backend decision as an evidence-backed experiment, not a rewrite: stress a real room/direct-message workload, compare the current file-backed adapter with a thin communication actor/helper, and record the decision.
   - Consider reducing direct file-backed state where it improves coherence: model room/roster state as actor-owned data structures served by helper scripts/actors, with files retained only for durable snapshots, recovery, artifacts, or audit logs.
-  - Avoid full roster rewrite amplification during bursty room activity; branch communication snapshot writes are already debounced while root snapshots stay current.
+  - Further storage changes should preserve the current burst/read/concurrency safeguards: branch communication snapshot writes are debounced, root snapshots stay current, roster files are not rewritten during bursts when only `last_seen` changes, room status inspection does not parse full timelines, branch-local inbox append/status rewrites are lock-guarded, and legacy no-ID branch inbox records can be claimed exactly once.
+  - Prevent monolith drift: `actor-rooms.ts` may remain a thin adapter, but growing routing policy, subscription loops, fanout policy, or long-lived state ownership should move behind a focused communication helper/actor rather than accumulating in the tool adapter.
 - Exit:
   - Any backend/storage change preserves existing `spawn` / `message` / `inspect` semantics and room address compatibility.
-
-### Actor Communication TUI Preview
-
-- Priority: High.
-- Goal: Make actor-to-actor communication more navigable in the terminal UI without exposing large payloads by default.
-- Direction:
-  - Add current-branch and unread filters after branch read-state semantics are real.
-- Exit:
-  - Operators can distinguish unread/current-branch messages while retaining intentional full-body inspection.
+  - A short decision note or changelog entry explains why the room backend stayed file-backed or moved behind a communication actor/helper.
 
 ### Graceful Actor Retirement
 
@@ -29,13 +23,25 @@
 - Direction:
   - Build on the existing `retire_when: "children_terminal"` recipe/run metadata contract and observability retirement-candidate detection for ephemeral supervisors.
   - Treat auto-retirement as opt-in only; never infer it for arbitrary long-lived services, user tools, or persistent backlog implementers.
-  - Extend candidate detection from current `progress.activeSubagents === 0` gating to full observed child/descendant actor state rather than log text: the supervisor may retire only when all launched child async runs or descendant `pi -p` workers are terminal and required artifacts/outbox events have been flushed.
+  - Extend candidate detection beyond current active command/proc-descendant gating to full observed child async-run state rather than log text: the supervisor may retire only when all launched child async runs are terminal and required artifacts/outbox events have been flushed.
   - Prefer graceful stop (`control.stop` / actor message) before process termination; escalate only after a bounded timeout and record the retirement event in run state.
   - Preserve manual `cancel` / `kill` semantics and make retirement visible through `inspect` / ambient observability.
 - Exit:
   - A packaged coordinator recipe can launch worker actors, complete its coordination duties, and shut itself down automatically after the worker tree reaches terminal state.
   - Persistent services and implementer actors remain alive unless their recipe explicitly opts into retirement.
 
+### Coordinator Strategy Boundary
+
+- Priority: Medium.
+- Goal: Keep the generic coordinator from becoming a second overloaded monolith as room/direct-message workflows mature.
+- Direction:
+  - Split only at real pressure points: branch inbox claim/finalize helpers, participant execution, room transcript synthesis, and mode strategies are likely seams, but avoid cosmetic module churn.
+  - Preserve the current principle that the locker stays generic/thin and all orchestration policy stays in coordinator strategy code or recipe composition.
+  - Prefer reusable helper modules or small scripts only when at least two packaged workflows need the same behavior.
+- Exit:
+  - Adding a new coordinator mode or packaged multi-agent workflow does not require editing unrelated mode logic.
+  - Existing room-swarm, locker, and direct-branch-message tests still cover the extracted seams.
+
 ### Consensus-First Build Recipe
 
 - Priority: Medium.
@@ -51,6 +57,18 @@
   - A packaged recipe can reproduce the interactive-music-instrument workflow shape for another single-artifact task without copying the demo script.
   - Docs and skills point agents to the packaged recipe and explain when to choose it over a free-form room swarm.
 
+### Actor OS Scenario Smoke Matrix
+
+- Priority: Medium.
+- Goal: Convert the 0.19.x actor-communication hardening into repeatable end-to-end scenario checks instead of relying on ad hoc demos.
+- Direction:
+  - Cover one scenario each for shared room coordination, direct branch work delivery, branch inbox claim/handle/fail transitions, inspector navigation, recipe context injection, recipe persistence suggestion, and opt-in retirement candidate detection.
+  - Keep scenarios local-first and bounded: fake `pi`/models where possible, no external services, no long sleeps, no broad golden transcripts.
+  - Prefer packaged recipes and public `spawn` / `message` / `inspect` calls so the smoke matrix exercises the same surface agents use.
+- Exit:
+  - A single validation command or documented test group verifies the actor OS behaviors that made 0.19.x production-useful.
+  - The smoke matrix catches regressions in actor communication, recipe memory, and observability without requiring a manual swarm demo.
+
 ### Persistent Backlog Implementer Workflow
 
 - Priority: Medium.
@@ -93,10 +111,22 @@
   - Add nested recipe directories only after flat `recipes/*.json` discovery semantics are stable.
   - Keep same-id priority and invalid-blocking behavior explicit if nested ids are introduced.
 
+### Actor Recipe Feedback Loop
+
+- Priority: Low.
+- Goal: Turn actor recipe-context awareness into a practical improvement loop for packaged recipes and operator-owned recipe memory.
+- Direction:
+  - After real multi-agent runs, capture whether child actors report that recipe/import/mailbox/role boundaries fit the task.
+  - Keep the loop advisory and operator-gated: feedback may suggest recipe edits or copying into `~/.pi/agent/recipes`, but must not auto-save or rewrite durable recipes without confirmation.
+  - Prefer small recipe/readme/skill refinements over adding scenario catalogs; recurring patterns should become packaged recipes only after repeated use.
+- Exit:
+  - At least one real run produces recipe-boundary feedback that is either applied to a recipe/docs change or explicitly rejected with rationale.
+
 ### Recipe Usage Telemetry Evolution
 
 - Priority: Low.
 - Goal: Improve long-term operator insight into recipe usefulness without making telemetry noisy.
 - Direction:
   - Consider sidecar stats sync/backup policy after inline user-owned `usage.calls` / `usage.last_called` proves useful.
+  - Consider an operator-approved recipe promotion workflow that turns successful package/ad hoc/direct spawn suggestions into a reviewed `~/.pi/agent/recipes` entry with provenance and diff, without auto-saving.
   - Do not add failure counters as primary usefulness evidence unless there is a strong operator-facing need.

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 0.19.11: Installed Async Runner Hotfix
+
+- `[Async Runs]` Fixed installed npm package async recipe launches on Node 22 by avoiding direct runtime imports of raw `.ts` files from under `node_modules` in `scripts/async-runner.mjs`. Installed runners now copy the package `lib` sources into the run state before importing them, keeping Node native type stripping outside the blocked `node_modules` path.
+- `[Scripts]` Applied the same installed-package import guard to `scripts/validate-recipe.mjs`, so the packaged recipe validator works when invoked from an installed `@llblab/pi-actors` package.
+- `[Tests]` Added installed-package script smoke coverage that copies `lib`/`scripts` under a temporary `node_modules/@llblab/pi-actors` path and verifies both async runner execution and recipe validation avoid `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`.
+- `[Package]` Bumped package metadata, lockfile metadata, and packaged skill metadata to `0.19.11` for the hotfix release.
+
+## 0.19.10: Legacy Branch Message Claim IDs
+
+- `[Branch Messages]` Coordinator claim handling now assigns IDs to older/manual queued branch inbox entries that lack `id`, so injected direct messages can still transition to `handled` or `failed` and do not repeat forever.
+- `[Tests]` Extended direct branch inbox coordinator coverage to include a legacy no-ID message and assert both claimed/handled timestamps are recorded.
+- `[Docs/Context]` Updated actor-message docs, durable project context, package metadata, lockfile metadata, and packaged skill metadata to `0.19.10`.
+
+## 0.19.9: Locked Branch Inbox Mutations
+
+- `[Branch Messages]` Added lock-guarded append and status rewrites for branch-local direct-message inbox files so concurrent direct delivery and coordinator claim/handle transitions do not overwrite each other.
+- `[Coordinator]` Made room-swarm branch prompt execution atomically claim queued direct messages before injection, then mark claimed messages as `handled` or `failed` after the child prompt exits.
+- `[Tests]` Added concurrent branch inbox append coverage and asserted coordinator direct-message handling records both `claimed_at` and `handled_at`.
+- `[Docs/Context]` Updated actor-message docs, project context, backlog safeguards, package metadata, lockfile metadata, and packaged skill metadata to `0.19.9`.
+
+## 0.19.8: Efficient Room Status Reads
+
+- `[Rooms]` Changed room status inspection to count JSONL entries and read only the last timeline record instead of parsing the full room timeline into actor-envelope objects.
+- `[Inspector]` Preserved the existing `inspect room:<run> view=status` shape while reducing storage/read amplification for large room transcripts.
+- `[Docs/Context]` Updated actor-message docs, backlog safeguards, project context, package metadata, lockfile metadata, and skill metadata for `0.19.8`.
+- `[Tests]` Added regression coverage that room status preserves message count and last-message metadata across longer timelines.
+
+## 0.19.7: Burst-Safe Roster Writes
+
+- `[Rooms]` Debounced room roster rewrites when a burst only changes a member's `last_seen`, while still writing semantic roster changes such as role, status, display, caps, claim, or parent immediately.
+- `[Runtime IO]` Added `PI_ACTORS_ROOM_ROSTER_MIN_MS` as the roster-only debounce interval, mirroring the existing communication snapshot debounce approach without changing public `room:<run>` message or inspect semantics.
+- `[Docs/Context]` Updated actor-message docs, project context, and the remaining rooms backlog scope to preserve the new burst-safe roster invariant during future storage/backend changes.
+- `[Tests]` Added regression coverage for roster rewrite debounce and immediate semantic roster updates.
+- `[Package]` Bumped package metadata, lockfile metadata, and packaged skill metadata to `0.19.7` for the hotfix release.
+
+## 0.19.6: Conservative Retirement Candidates
+
+- `[Observability]` Added per-run descendant `pi -p` worker counting and exposes `descendantSubagents` on run observations. Ambient run status still counts active descendant workers, but now retains the per-run attribution needed for supervisor lifecycle decisions.
+- `[Retirement]` Tightened opt-in `retire_when: "children_terminal"` candidate detection so supervisors are not considered retirement-ready while command-template progress or descendant `pi -p` workers are still active.
+- `[Docs/Context]` Updated async-run docs, project context, and the remaining retirement backlog scope to reflect the conservative candidate baseline and the remaining child async-run/output-flush work.
+- `[Tests]` Added regression coverage that blocks retirement candidates with descendant subagents.
+- `[Package]` Bumped package metadata, lockfile metadata, and packaged skill metadata to `0.19.6` for the hotfix release.
+
+## 0.19.5: Branch Inbox Inspector Filters
+
+- `[Actor Inspector]` Added branch-local inbox previews to the compact actor communication table, so queued direct `branch:<run>/<branch>` work is visible alongside room, run inbox, and outbox messages.
+- `[Actor Inspector]` Added `/actors-inspector-filter unread`, `/actors-inspector-filter branch <name>`, and `/actors-inspector-filter current-branch <name>` to focus queued branch inbox work and one branch's room/direct/inbox traffic without exposing full payloads by default.
+- `[Docs/Skills]` Updated README and the packaged actors skill with the new inspector filters and branch-inbox preview behavior.
+- `[Backlog]` Closed the high-priority actor communication TUI preview item now that unread/current-branch navigation is implemented with branch read-state semantics.
+- `[Package]` Bumped package metadata, lockfile metadata, and packaged skill metadata to `0.19.5` for the hotfix release.
+
 ## 0.19.4: User Recipe Collection Suggestions
 
 - `[Observability]` Broadened recipe persistence suggestions from direct inline spawns to the normal user workflow: any successful actor run backed by a recipe outside `~/.pi/agent/recipes` now asks the launching agent to offer copying/registering it into the user recipe root when it fits this machine's recurring workflow.

package/README.md

@@ -155,11 +155,13 @@ The terminal actor inspector is hidden by default. When opened without an explic
 /actors-inspector-toggle 20
 /actors-inspector-filter room
 /actors-inspector-filter direct
+/actors-inspector-filter unread
+/actors-inspector-filter branch front
 /actors-inspector-filter mention checkpoint
 /actors-inspect 3
 ```
 
-The table is compact and optimistic by default: bounded route/type/summary/body previews, capped noisy room rows, and an inline roster summary in the form `name/role` that wraps only when needed. Active roster members use the target color; members that sent `actor.leave` remain visible as inactive/muted participants from the current run. `/actors-inspect <number>` opens the selected row as a full-message view; toggle again to return to the table or close it. Actor display names come from room `actor.join` roster metadata or branch addresses, keeping debugger output plain and name-driven.
+The table is compact and optimistic by default: bounded route/type/summary/body previews, capped noisy room rows, branch-local inbox previews, and an inline roster summary in the form `name/role` that wraps only when needed. Active roster members use the target color; members that sent `actor.leave` remain visible as inactive/muted participants from the current run. Use `unread` to focus queued branch inbox work and `branch <name>` / `current-branch <name>` to focus one branch's room/direct/inbox traffic. `/actors-inspect <number>` opens the selected row as a full-message view; toggle again to return to the table or close it. Actor display names come from room `actor.join` roster metadata or branch addresses, keeping debugger output plain and name-driven.
 
 ## Registry Model
 

package/docs/actor-messages.md

@@ -94,7 +94,7 @@ Transports differ, but the public contract does not:
 
 - `to: run:<id>` routes through the run-local control channel selected by that recipe or runtime adapter.
 - `to: coordinator` routes to the runtime attention path when `from` names a run actor. `to: session:<id>` uses the same actor-message path only when the sender run is owned by that session, making explicit session-directed checkpoints possible without exposing runtime delivery knobs. Generic async-runner `command.done` messages and explicit coordinator/session-bound messages include the actor envelope fields alongside runtime metadata.
-- `to: branch:<run>/<branch>` currently routes through the parent run mailbox with the full envelope preserved so the run or recipe-specific worker protocol can dispatch branch-local control. It also persists a queued branch-local copy under `branches/<branch>/inbox.jsonl`, inspectable with `inspect branch:<run>/<branch> view=mailbox`; compact inspection includes the inbox message `id`, status, route, type, and timestamps so worker protocols can correlate claims/retries. It is not a broadcast room and it does not make an arbitrary prompt process consume the message automatically. Target direction: direct branch messages should become initiating inbox work for long-lived branch runners, delivered into the recipient's next prompt/context as soon as the runner can accept work.
+- `to: branch:<run>/<branch>` currently routes through the parent run mailbox with the full envelope preserved so the run or recipe-specific worker protocol can dispatch branch-local control. It also persists a queued branch-local copy under `branches/<branch>/inbox.jsonl`, inspectable with `inspect branch:<run>/<branch> view=mailbox`; compact inspection includes the inbox message `id`, status, route, type, and timestamps so worker protocols can correlate claims/retries. Branch-local inbox append and status rewrites are guarded by a small lock so direct delivery and coordinator claims do not overwrite each other during bursts. Coordinator claim handling also assigns an ID to older/manual queued records that do not have one so they can still transition to `handled` or `failed` instead of repeating forever. It is not a broadcast room and it does not make an arbitrary prompt process consume the message automatically. Target direction: direct branch messages should become initiating inbox work for long-lived branch runners, delivered into the recipient's next prompt/context as soon as the runner can accept work.
 - `to: room:<run>` appends the full envelope to the room timeline, updates room state for room-control types such as `actor.join` and `actor.leave`, and can route selected-recipient multicast when `metadata.recipients` contains same-run `branch:<run>/<branch>` addresses.
 - `to: tool:<name>` invokes an executable pi tool by name. Object bodies become tool parameters; primitive bodies are passed as `{ "input": body }`.
 
@@ -182,7 +182,7 @@ Recipes can declare their conversational surface:
 }
 ```
 
-`spawn` creates detached `run:<id>` actors from a recipe file/name or inline command template. Spawn metadata may include explicit `state_dir` and named `artifacts` for terminal follow-ups and inspection.
+`spawn` creates detached `run:<id>` actors from a recipe file/name or inline command template. Spawn metadata may include explicit `state_dir` and named `artifacts` for terminal follow-ups and inspection. Room rosters are durable but burst-safe: repeated messages that only update `last_seen` may be coalesced briefly, while semantic roster changes such as role/status/display still write immediately.
 
 ## Inspect
 
@@ -195,7 +195,7 @@ Recipes can declare their conversational surface:
 }
 ```
 
-The implementation supports `status`, `tail`, `messages`, `artifacts`, `files`, `mailbox`, and `communication` for `run:<id>` actors, `status`, `messages`, `previews`, `roster`, and `contacts` for `room:<run>` actors, `status`/`runs` for `coordinator`, `session:<id>`, and `session:all` actors with optional status filtering, and `status`/`schema` for registered `tool:<name>` actors. Room `status` returns compact message/roster counts plus `last_message_at`, `last_message_from`, `last_message_type`, and `last_message_summary` when available. Use `messages` for actor-envelope inspection. `inspect target=coordinator` requires a current coordinator session; use `session:<id>` or `session:all` when the session is intentionally explicit. Direct `run:<id>` and `room:<run>` inspection respects coordinator-session ownership when the current session is known. `inspect` is for decision points and diagnosis only; examples must not teach sleep-then-inspect polling.
+The implementation supports `status`, `tail`, `messages`, `artifacts`, `files`, `mailbox`, and `communication` for `run:<id>` actors, `status`, `messages`, `previews`, `roster`, and `contacts` for `room:<run>` actors, `status`/`runs` for `coordinator`, `session:<id>`, and `session:all` actors with optional status filtering, and `status`/`schema` for registered `tool:<name>` actors. Room `status` returns compact message/roster counts plus `last_message_at`, `last_message_from`, `last_message_type`, and `last_message_summary` when available, without parsing the full timeline into actor envelopes. Use `messages` for actor-envelope inspection. `inspect target=coordinator` requires a current coordinator session; use `session:<id>` or `session:all` when the session is intentionally explicit. Direct `run:<id>` and `room:<run>` inspection respects coordinator-session ownership when the current session is known. `inspect` is for decision points and diagnosis only; examples must not teach sleep-then-inspect polling.
 
 ## Runtime Direction
 

package/docs/async-runs.md

@@ -158,6 +158,8 @@ The actor-level surface is:
 - `message`: send one typed envelope to `run:<id>`, `branch:<run>/<branch>`, `room:<run>`, `tool:<name>`, `coordinator`, or `session:<id>`.
 - `inspect`: intentionally read owned `run:<id>` status, tail, messages, artifacts, files, mailbox metadata, or communication snapshot; read `room:<run>` status, messages, previews, roster, or contacts; read current `coordinator` run inventory only when a coordinator session is known; read `session:<id>` or `session:all` run inventory with optional status filtering when the session is explicit; read `tool:<name>` status or schema for registered tool actors.
 
+Opt-in supervisor retirement uses `retire_when: "children_terminal"` as lifecycle metadata. Candidate detection is conservative: a supervisor is not retirement-ready while command-template progress or descendant `pi -p` worker processes are still active; future retirement execution must also verify child async-run state and flushed outputs before stopping the supervisor.
+
 Low-level async actions map into the actor surface instead of forming a second public model:
 
 - Start → `spawn`

package/index.ts

@@ -54,6 +54,8 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
     | ActorInspectorTui.ActorInspectorPreview["channel"][]
     | undefined;
   let actorInspectorMention: string | undefined;
+  let actorInspectorBranch: string | undefined;
+  let actorInspectorUnreadOnly = false;
   let actorInspectorRoomLimitPerRun = 12;
   let selectedInspectorSequence: number | undefined;
   let recipeWatcherFailureNotified = false;
@@ -90,9 +92,11 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
                   {
                     channels: actorInspectorChannels,
                     currentRunOnly: true,
+                    branch: actorInspectorBranch,
                     mention: actorInspectorMention,
                     ownerId,
                     roomLimitPerRun: actorInspectorRoomLimitPerRun,
+                    unreadOnly: actorInspectorUnreadOnly,
                   },
                 );
                 const rows =
@@ -337,7 +341,7 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
   });
   pi.registerCommand("actors-inspector-filter", {
     description:
-      "Filter actor inspector rows: all, room, direct, broadcast, mention <text>",
+      "Filter actor inspector rows: all, room, direct, broadcast, unread, branch <name>, mention <text>",
     handler: async (args, ctx) => {
       const parts = Array.isArray(args)
         ? args.map(String)
@@ -346,9 +350,23 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
       if (!mode || mode === "all" || mode === "clear") {
         actorInspectorChannels = undefined;
         actorInspectorMention = undefined;
+        actorInspectorBranch = undefined;
+        actorInspectorUnreadOnly = false;
       } else if (mode === "room" || mode === "direct" || mode === "broadcast") {
         actorInspectorChannels = [mode];
         actorInspectorMention = undefined;
+      } else if (mode === "unread") {
+        actorInspectorUnreadOnly = true;
+      } else if (mode === "branch" || mode === "current-branch") {
+        const branch = parts.slice(1).join(" ").trim();
+        if (!branch) {
+          ctx.ui.notify(
+            `Usage: /actors-inspector-filter ${mode} <branch-name>`,
+            "warning",
+          );
+          return;
+        }
+        actorInspectorBranch = branch;
       } else if (mode === "mention") {
         const mention = parts.slice(1).join(" ").trim();
         if (!mention) {
@@ -362,7 +380,7 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
         actorInspectorMention = mention;
       } else {
         ctx.ui.notify(
-          "Usage: /actors-inspector-filter all|room|direct|broadcast|mention <text>",
+          "Usage: /actors-inspector-filter all|room|direct|broadcast|unread|branch <name>|mention <text>",
           "warning",
         );
         return;

package/lib/actor-inspector-tui.ts

@@ -13,9 +13,12 @@ import * as Paths from "./paths.ts";
 
 export interface ActorInspectorPreview {
   body_preview?: string;
+  branch?: string;
   channel: "broadcast" | "direct" | "room";
   from?: string;
   from_display?: string;
+  inbox_status?: string;
+  message_id?: string;
   run: string;
   sequence?: number;
   summary?: string;
@@ -50,10 +53,12 @@ export interface ActorInspectorRosterMember {
 
 export interface ActorInspectorPreviewReadOptions {
   ownerId?: string;
+  branch?: string;
   currentRunOnly?: boolean;
   channels?: ActorInspectorPreview["channel"][];
   mention?: string;
   roomLimitPerRun?: number;
+  unreadOnly?: boolean;
 }
 
 function asRecord(value: unknown): Record<string, unknown> {
@@ -207,6 +212,39 @@ function readInboxPreviews(
     .filter((preview): preview is ActorInspectorPreview => Boolean(preview));
 }
 
+function readBranchInboxPreviews(
+  run: string,
+  stateDir: string,
+): ActorInspectorPreview[] {
+  const branchesDir = path.join(stateDir, "branches");
+  try {
+    return fs
+      .readdirSync(branchesDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .flatMap((entry) =>
+        readJsonLines(path.join(branchesDir, entry.name, "inbox.jsonl"))
+          .map((message): ActorInspectorPreview | undefined => {
+            const preview = previewFromMessage(
+              run,
+              message,
+              String(message.queued_at ?? message.received_at ?? message.timestamp ?? ""),
+            );
+            if (!preview) return undefined;
+            return {
+              ...preview,
+              branch: entry.name,
+              ...(typeof message.id === "string" ? { message_id: message.id } : {}),
+              ...(typeof message.status === "string" ? { inbox_status: message.status } : {}),
+            };
+          })
+          .filter((preview): preview is ActorInspectorPreview => Boolean(preview)),
+      );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    return [];
+  }
+}
+
 function readOutboxPreviews(
   run: string,
   stateDir: string,
@@ -238,6 +276,21 @@ function matchesOwner(stateDir: string, ownerId: string | undefined): boolean {
   return ownerId === undefined || getRunOwnerId(stateDir) === ownerId;
 }
 
+function isUnreadPreview(preview: ActorInspectorPreview): boolean {
+  return preview.inbox_status === "queued" || preview.inbox_status === undefined && preview.branch !== undefined;
+}
+
+function matchesBranchFilter(
+  preview: ActorInspectorPreview,
+  branch: string | undefined,
+): boolean {
+  const name = branch?.trim();
+  if (!name) return true;
+  if (preview.branch !== undefined) return preview.branch === name;
+  const address = `branch:${preview.run}/${name}`;
+  return preview.from === address || preview.to === address;
+}
+
 function matchesPreviewFilter(
   preview: ActorInspectorPreview,
   options: ActorInspectorPreviewReadOptions,
@@ -245,11 +298,15 @@ function matchesPreviewFilter(
   if (options.channels?.length && !options.channels.includes(preview.channel)) {
     return false;
   }
+  if (options.unreadOnly && !isUnreadPreview(preview)) return false;
+  if (!matchesBranchFilter(preview, options.branch)) return false;
   const mention = options.mention?.trim().toLowerCase();
   if (!mention) return true;
   return [
+    preview.branch,
     preview.from,
     preview.from_display,
+    preview.inbox_status,
     preview.to,
     preview.type,
     preview.summary,
@@ -297,6 +354,7 @@ export function readActorInspectorPreviews(
         return [
           ...readRoomPreviews(entry.name, stateDir),
           ...readInboxPreviews(entry.name, stateDir),
+          ...readBranchInboxPreviews(entry.name, stateDir),
           ...readOutboxPreviews(entry.name, stateDir),
         ];
       })

package/lib/actor-rooms.ts

@@ -10,8 +10,8 @@ import * as path from "node:path";
 
 import type { ActorMessage } from "./actor-messages.ts";
 
-const ROOM_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
-const ROOM_LOCK_TIMEOUT_MS = 5000;
+const STATE_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+const STATE_LOCK_TIMEOUT_MS = 5000;
 const DEFAULT_ROOM_MAX_MESSAGES = 10000;
 const DEFAULT_SNAPSHOT_MIN_INTERVAL_MS = 250;
 
@@ -117,9 +117,9 @@ function sleepSync(ms: number): void {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 
-function acquireRoomLock(stateDir: string, room: string): () => void {
-  ensureRoomDir(stateDir, room);
-  const lockDir = path.join(roomDir(stateDir, room), ".append.lock");
+function acquireStateLock(parentDir: string, name: string, label: string): () => void {
+  fs.mkdirSync(parentDir, { recursive: true });
+  const lockDir = path.join(parentDir, name);
   const started = Date.now();
   while (true) {
     try {
@@ -132,24 +132,29 @@ function acquireRoomLock(stateDir: string, room: string): () => void {
     } catch (error) {
       try {
         const stat = fs.statSync(lockDir);
-        if (Date.now() - stat.mtimeMs > ROOM_LOCK_MAX_AGE_MS) {
+        if (Date.now() - stat.mtimeMs > STATE_LOCK_MAX_AGE_MS) {
           fs.rmSync(lockDir, { recursive: true, force: true });
           continue;
         }
       } catch {
         continue;
       }
-      if (Date.now() - started > ROOM_LOCK_TIMEOUT_MS) {
-        throw new Error(
-          `Room append lock timed out for ${room} in ${stateDir}.`,
-          { cause: error },
-        );
+      if (Date.now() - started > STATE_LOCK_TIMEOUT_MS) {
+        throw new Error(`${label} lock timed out.`, { cause: error });
       }
       sleepSync(10);
     }
   }
 }
 
+function acquireRoomLock(stateDir: string, room: string): () => void {
+  return acquireStateLock(roomDir(stateDir, room), ".append.lock", `Room append ${room}`);
+}
+
+function acquireBranchInboxLock(stateDir: string, branch: string): () => void {
+  return acquireStateLock(path.dirname(branchInboxFile(stateDir, branch)), ".inbox.lock", `Branch inbox ${branch}`);
+}
+
 function asRecord(value: unknown): Record<string, unknown> {
   return value && typeof value === "object" && !Array.isArray(value)
     ? (value as Record<string, unknown>)
@@ -191,6 +196,13 @@ function snapshotMinIntervalMs(): number {
   );
 }
 
+function rosterMinIntervalMs(): number {
+  return positiveEnvInt(
+    "PI_ACTORS_ROOM_ROSTER_MIN_MS",
+    DEFAULT_SNAPSHOT_MIN_INTERVAL_MS,
+  );
+}
+
 function compactRoomMessages(stateDir: string, room: string): void {
   const maxMessages = roomMaxMessages();
   const file = messagesFile(stateDir, room);
@@ -204,6 +216,31 @@ function compactRoomMessages(stateDir: string, room: string): void {
   });
 }
 
+function readJsonlLineCount(file: string): number {
+  const stat = fs.statSync(file);
+  if (stat.size === 0) return 0;
+  const fd = fs.openSync(file, "r");
+  try {
+    const chunkSize = 64 * 1024;
+    const chunk = Buffer.allocUnsafe(chunkSize);
+    let position = 0;
+    let count = 0;
+    let lastByte: number | undefined;
+    while (position < stat.size) {
+      const bytesRead = fs.readSync(fd, chunk, 0, Math.min(chunkSize, stat.size - position), position);
+      if (bytesRead <= 0) break;
+      position += bytesRead;
+      for (let index = 0; index < bytesRead; index += 1) {
+        if (chunk[index] === 10) count += 1;
+      }
+      lastByte = chunk[bytesRead - 1];
+    }
+    return lastByte === 10 ? count : count + 1;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
 function readJsonlTailLines(file: string, limit: number): string[] {
   const lineLimit = Math.max(1, limit);
   const stat = fs.statSync(file);
@@ -250,15 +287,38 @@ function writeRoomRoster(
   writeJsonFile(rosterFile(stateDir, room), roster);
 }
 
-function shouldDebounceSnapshot(file: string): boolean {
+function shouldDebounceFile(file: string, minIntervalMs: number): boolean {
   try {
-    return Date.now() - fs.statSync(file).mtimeMs < snapshotMinIntervalMs();
+    return Date.now() - fs.statSync(file).mtimeMs < minIntervalMs;
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
     throw error;
   }
 }
 
+function shouldDebounceSnapshot(file: string): boolean {
+  return shouldDebounceFile(file, snapshotMinIntervalMs());
+}
+
+function comparableRosterMember(member: RoomMember | undefined): string {
+  if (!member) return "";
+  const { last_seen: _lastSeen, ...semantic } = member;
+  return JSON.stringify(semantic);
+}
+
+function shouldWriteRoomRosterMember(
+  stateDir: string,
+  room: string,
+  before: RoomMember | undefined,
+  after: RoomMember,
+): boolean {
+  if (!before) return true;
+  if (comparableRosterMember(before) !== comparableRosterMember(after)) {
+    return true;
+  }
+  return !shouldDebounceFile(rosterFile(stateDir, room), rosterMinIntervalMs());
+}
+
 function updateRosterForMessage(
   stateDir: string,
   room: string,
@@ -269,33 +329,33 @@ function updateRosterForMessage(
   if (!message.from) return roster;
   const body = asRecord(message.body);
   const current = roster[message.from];
-  if (message.type === "actor.leave") {
-    roster[message.from] = {
-      address: message.from,
-      joined_at: current?.joined_at ?? receivedAt,
-      last_seen: receivedAt,
-      ...(current?.caps !== undefined ? { caps: current.caps } : {}),
-      ...(current?.claim !== undefined ? { claim: current.claim } : {}),
-      ...(current?.display !== undefined ? { display: current.display } : {}),
-      ...(current?.parent !== undefined ? { parent: current.parent } : {}),
-      ...(current?.role !== undefined ? { role: current.role } : { role: "actor" }),
-      status: String(body.status ?? "left"),
-    };
+  const next = message.type === "actor.leave"
+    ? {
+        address: message.from,
+        joined_at: current?.joined_at ?? receivedAt,
+        last_seen: receivedAt,
+        ...(current?.caps !== undefined ? { caps: current.caps } : {}),
+        ...(current?.claim !== undefined ? { claim: current.claim } : {}),
+        ...(current?.display !== undefined ? { display: current.display } : {}),
+        ...(current?.parent !== undefined ? { parent: current.parent } : {}),
+        ...(current?.role !== undefined ? { role: current.role } : { role: "actor" }),
+        status: String(body.status ?? "left"),
+      }
+    : {
+        address: message.from,
+        joined_at: current?.joined_at ?? receivedAt,
+        last_seen: receivedAt,
+        ...(body.caps !== undefined ? { caps: body.caps } : current?.caps !== undefined ? { caps: current.caps } : {}),
+        ...(body.claim !== undefined ? { claim: body.claim } : current?.claim !== undefined ? { claim: current.claim } : {}),
+        ...(body.display !== undefined ? { display: body.display } : current?.display !== undefined ? { display: current.display } : {}),
+        ...(body.parent !== undefined ? { parent: body.parent } : current?.parent !== undefined ? { parent: current.parent } : {}),
+        ...(body.role !== undefined ? { role: body.role } : current?.role !== undefined ? { role: current.role } : { role: "actor" }),
+        status: String(body.status ?? current?.status ?? "present"),
+      };
+  roster[message.from] = next;
+  if (shouldWriteRoomRosterMember(stateDir, room, current, next)) {
     writeRoomRoster(stateDir, room, roster);
-    return roster;
   }
-  roster[message.from] = {
-    address: message.from,
-    joined_at: current?.joined_at ?? receivedAt,
-    last_seen: receivedAt,
-    ...(body.caps !== undefined ? { caps: body.caps } : current?.caps !== undefined ? { caps: current.caps } : {}),
-    ...(body.claim !== undefined ? { claim: body.claim } : current?.claim !== undefined ? { claim: current.claim } : {}),
-    ...(body.display !== undefined ? { display: body.display } : current?.display !== undefined ? { display: current.display } : {}),
-    ...(body.parent !== undefined ? { parent: body.parent } : current?.parent !== undefined ? { parent: current.parent } : {}),
-    ...(body.role !== undefined ? { role: body.role } : current?.role !== undefined ? { role: current.role } : { role: "actor" }),
-    status: String(body.status ?? current?.status ?? "present"),
-  };
-  writeRoomRoster(stateDir, room, roster);
   return roster;
 }
 
@@ -325,12 +385,16 @@ export function appendBranchInboxMessage(
 ): void {
   const branch = branchIdFromAddress(address, run);
   if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
-  fs.mkdirSync(path.dirname(branchInboxFile(stateDir, branch)), { recursive: true });
-  fs.writeFileSync(
-    branchInboxFile(stateDir, branch),
-    `${JSON.stringify({ ...message, id: randomUUID(), queued_at: new Date().toISOString(), status: "queued" })}\n`,
-    { flag: "a" },
-  );
+  const releaseLock = acquireBranchInboxLock(stateDir, branch);
+  try {
+    fs.writeFileSync(
+      branchInboxFile(stateDir, branch),
+      `${JSON.stringify({ ...message, id: randomUUID(), queued_at: new Date().toISOString(), status: "queued" })}\n`,
+      { flag: "a" },
+    );
+  } finally {
+    releaseLock();
+  }
 }
 
 export function updateBranchInboxMessageStatus(
@@ -343,18 +407,23 @@ export function updateBranchInboxMessageStatus(
 ): boolean {
   const branch = branchIdFromAddress(address, run);
   if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
-  const file = branchInboxFile(stateDir, branch);
-  const messages = readBranchInboxMessages(stateDir, run, address, Number.MAX_SAFE_INTEGER);
-  let changed = false;
-  const timestampKey = `${status}_at`;
-  const updated = messages.map((message) => {
-    if (message.id !== id) return message;
-    changed = true;
-    return { ...message, ...metadata, [timestampKey]: new Date().toISOString(), status };
-  });
-  if (!changed) return false;
-  fs.writeFileSync(file, `${updated.map((message) => JSON.stringify(message)).join("\n")}\n`);
-  return true;
+  const releaseLock = acquireBranchInboxLock(stateDir, branch);
+  try {
+    const file = branchInboxFile(stateDir, branch);
+    const messages = readBranchInboxMessages(stateDir, run, address, Number.MAX_SAFE_INTEGER);
+    let changed = false;
+    const timestampKey = `${status}_at`;
+    const updated = messages.map((message) => {
+      if (message.id !== id) return message;
+      changed = true;
+      return { ...message, ...metadata, [timestampKey]: new Date().toISOString(), status };
+    });
+    if (!changed) return false;
+    fs.writeFileSync(file, `${updated.map((message) => JSON.stringify(message)).join("\n")}\n`);
+    return true;
+  } finally {
+    releaseLock();
+  }
 }
 
 export function appendRoomMessage(
@@ -427,8 +496,13 @@ export function readRoomMessagePreviews(
 }
 
 export function getRoomStatus(stateDir: string, room: string): RoomStatus {
-  const messages = readRoomMessages(stateDir, room, Number.MAX_SAFE_INTEGER);
-  const last = messages[messages.length - 1];
+  let messageCount = 0;
+  try {
+    messageCount = readJsonlLineCount(messagesFile(stateDir, room));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  const [last] = readRoomMessages(stateDir, room, 1);
   return {
     ...(last
       ? {
@@ -438,7 +512,7 @@ export function getRoomStatus(stateDir: string, room: string): RoomStatus {
           last_message_type: last.type,
         }
       : {}),
-    message_count: messages.length,
+    message_count: messageCount,
     room,
     roster_count: Object.keys(readRoomRoster(stateDir, room)).length,
   };

package/lib/observability.ts

@@ -23,6 +23,7 @@ export type RunOutboxLevel = "info" | "warning" | "error";
 export interface RunObservation {
   activeSubagents?: number;
   completed?: number;
+  descendantSubagents?: number;
   failures?: number;
   ownerId?: string;
   artifacts?: Record<string, string>;
@@ -51,6 +52,7 @@ export interface RunSummary {
 
 export interface RunRetirementCandidate {
   activeSubagents: number;
+  descendantSubagents: number;
   run: string;
   stateDir: string;
 }
@@ -94,7 +96,7 @@ const PROC_DESCENDANT_SCAN_TTL_MS = 1000;
 
 const procDescendantScanCache = new Map<
   string,
-  { count: number; expiresAt: number; signature: string }
+  { counts: Map<string, number>; expiresAt: number; signature: string }
 >();
 
 function toNumber(value: unknown): number | undefined {
@@ -182,18 +184,26 @@ export function summarizeRuns(
     .filter((run): run is RunObservation => Boolean(run))
     .filter((run) => ownerId === undefined || run.ownerId === ownerId)
     .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
-  const runningRuns = runs.filter((run) => run.status === "running");
+  const processSubagentsByRun = countRunningSubagentsByRun(stateRoot, ownerId);
+  const runsWithDescendants = runs.map((run) => {
+    const descendantSubagents = processSubagentsByRun.get(run.run) ?? 0;
+    return descendantSubagents > 0 ? { ...run, descendantSubagents } : run;
+  });
+  const runningRuns = runsWithDescendants.filter((run) => run.status === "running");
   const running = runningRuns.length;
-  const done = runs.filter((run) => run.status === "done").length;
-  const exited = runs.filter((run) => run.status === "exited").length;
-  const failed = runs.filter((run) => run.status === "failed").length;
-  const cancelled = runs.filter((run) => run.status === "cancelled").length;
-  const killed = runs.filter((run) => run.status === "killed").length;
+  const done = runsWithDescendants.filter((run) => run.status === "done").length;
+  const exited = runsWithDescendants.filter((run) => run.status === "exited").length;
+  const failed = runsWithDescendants.filter((run) => run.status === "failed").length;
+  const cancelled = runsWithDescendants.filter((run) => run.status === "cancelled").length;
+  const killed = runsWithDescendants.filter((run) => run.status === "killed").length;
   const progressSubagents = runningRuns.reduce(
     (sum, run) => sum + Math.max(1, Math.floor(run.activeSubagents ?? 0)),
     0,
   );
-  const processSubagents = countRunningSubagents(stateRoot, ownerId);
+  const processSubagents = [...processSubagentsByRun.values()].reduce(
+    (sum, count) => sum + count,
+    0,
+  );
   const runningSubagents = Math.max(progressSubagents, running + processSubagents);
   return {
     cancelled,
@@ -203,8 +213,8 @@ export function summarizeRuns(
     killed,
     running,
     runningSubagents,
-    runs,
-    total: runs.length,
+    runs: runsWithDescendants,
+    total: runsWithDescendants.length,
   };
 }
 
@@ -228,13 +238,13 @@ function getProcCommand(pid: string): string {
   return (readProcFile(`/proc/${pid}/cmdline`) ?? "").replaceAll("\0", " ");
 }
 
-function getRunningRunPids(stateRoot: string, ownerId?: string): Set<string> {
-  const pids = new Set<string>();
+function getRunningRunPidMap(stateRoot: string, ownerId?: string): Map<string, string> {
+  const pids = new Map<string, string>();
   for (const run of summarizeRunsWithoutSubagents(stateRoot, ownerId).runs) {
     if (run.status !== "running") continue;
     const status = AsyncRuns.getRunStatus(join(stateRoot, run.run));
     const pid = Number(status.pid || 0);
-    if (pid > 0) pids.add(String(pid));
+    if (pid > 0) pids.set(String(pid), run.run);
   }
   return pids;
 }
@@ -278,18 +288,18 @@ function summarizeRunsWithoutSubagents(
   };
 }
 
-export function countRunningSubagents(
+export function countRunningSubagentsByRun(
   stateRoot = Paths.getRunStateRoot(),
   ownerId?: string,
-): number {
-  const runPids = getRunningRunPids(stateRoot, ownerId);
-  if (runPids.size === 0 || !existsSync("/proc")) return 0;
-  const signature = [...runPids].sort().join(",");
+): Map<string, number> {
+  const runPidMap = getRunningRunPidMap(stateRoot, ownerId);
+  if (runPidMap.size === 0 || !existsSync("/proc")) return new Map();
+  const signature = [...runPidMap.keys()].sort().join(",");
   const cacheKey = `${stateRoot}\0${ownerId ?? ""}`;
   const cached = procDescendantScanCache.get(cacheKey);
   const now = Date.now();
   if (cached && cached.signature === signature && cached.expiresAt > now) {
-    return cached.count;
+    return new Map(cached.counts);
   }
   const parentByPid = new Map<string, string>();
   const commandByPid = new Map<string, string>();
@@ -297,7 +307,7 @@ export function countRunningSubagents(
   try {
     procEntries = readdirSync("/proc", { withFileTypes: true });
   } catch {
-    return 0;
+    return new Map();
   }
   for (const entry of procEntries) {
     if (!entry.isDirectory() || !/^\d+$/.test(entry.name)) continue;
@@ -306,27 +316,39 @@ export function countRunningSubagents(
     parentByPid.set(entry.name, ppid);
     commandByPid.set(entry.name, getProcCommand(entry.name));
   }
-  const descendantOfRun = (pid: string): boolean => {
+  const runForDescendant = (pid: string): string | undefined => {
     let current = parentByPid.get(pid);
     const seen = new Set<string>();
     while (current && !seen.has(current)) {
-      if (runPids.has(current)) return true;
+      const run = runPidMap.get(current);
+      if (run) return run;
       seen.add(current);
       current = parentByPid.get(current);
     }
-    return false;
+    return undefined;
   };
-  let count = 0;
+  const counts = new Map<string, number>();
   for (const [pid, command] of commandByPid.entries()) {
     if (!command.includes("pi -p") && !command.includes("pi\0-p")) continue;
-    if (descendantOfRun(pid)) count++;
+    const run = runForDescendant(pid);
+    if (run) counts.set(run, (counts.get(run) ?? 0) + 1);
   }
   procDescendantScanCache.set(cacheKey, {
-    count,
+    counts,
     expiresAt: now + PROC_DESCENDANT_SCAN_TTL_MS,
     signature,
   });
-  return count;
+  return new Map(counts);
+}
+
+export function countRunningSubagents(
+  stateRoot = Paths.getRunStateRoot(),
+  ownerId?: string,
+): number {
+  return [...countRunningSubagentsByRun(stateRoot, ownerId).values()].reduce(
+    (sum, count) => sum + count,
+    0,
+  );
 }
 
 export function renderSubagentStatus(
@@ -352,14 +374,19 @@ export function findRunRetirementCandidates(
   summary: RunSummary,
 ): RunRetirementCandidate[] {
   return summary.runs
-    .filter((run) =>
-      run.status === "running" &&
-      run.retireWhen === "children_terminal" &&
-      run.stateDir &&
-      Math.floor(run.activeSubagents ?? 0) <= 0,
-    )
+    .filter((run) => {
+      const activeSubagents = Math.max(0, Math.floor(run.activeSubagents ?? 0));
+      const descendantSubagents = Math.max(0, Math.floor(run.descendantSubagents ?? 0));
+      return (
+        run.status === "running" &&
+        run.retireWhen === "children_terminal" &&
+        run.stateDir &&
+        activeSubagents + descendantSubagents <= 0
+      );
+    })
     .map((run) => ({
       activeSubagents: Math.max(0, Math.floor(run.activeSubagents ?? 0)),
+      descendantSubagents: Math.max(0, Math.floor(run.descendantSubagents ?? 0)),
       run: run.run,
       stateDir: run.stateDir!,
     }));

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.19.4",
+  "version": "0.19.11",
   "private": false,
-  "description": "Actor runtime and orchestrator for agent-managed local processes",
+  "description": "Local Actor Kernel for Pi",
   "keywords": [
     "pi-package",
     "pi-extension",

package/scripts/async-runner.mjs

@@ -11,18 +11,42 @@
  * Keep orchestration policy out of this file.
  */
 
-import { appendFileSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { appendFileSync, cpSync, existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const stateDir = process.argv[2];
 if (!stateDir) {
   console.error("missing state dir");
   process.exit(1);
 }
-const { executeRegisteredTool } = await import("../lib/execution.ts");
-const { execCommandTemplate } = await import("../lib/command-templates.ts");
-const { appendRecipeContextToPiArgs } = await import("../lib/actor-recipe-context.ts");
-const { writeJsonAtomic } = await import("../lib/file-state.ts");
+
+function scriptFile() {
+  return fileURLToPath(import.meta.url);
+}
+
+function isUnderNodeModules(file) {
+  return /[/\\]node_modules[/\\]/.test(file);
+}
+
+function prepareTypeStripImportRoot() {
+  const packageRoot = dirname(dirname(scriptFile()));
+  const sourceLib = join(packageRoot, "lib");
+  if (!isUnderNodeModules(packageRoot)) return sourceLib;
+  const copiedLib = join(stateDir, ".type-strip-lib");
+  if (!existsSync(copiedLib)) cpSync(sourceLib, copiedLib, { recursive: true });
+  return copiedLib;
+}
+
+const typeStripImportRoot = prepareTypeStripImportRoot();
+async function importLib(name) {
+  return import(pathToFileURL(join(typeStripImportRoot, `${name}.ts`)).href);
+}
+
+const { executeRegisteredTool } = await importLib("execution");
+const { execCommandTemplate } = await importLib("command-templates");
+const { appendRecipeContextToPiArgs } = await importLib("actor-recipe-context");
+const { writeJsonAtomic } = await importLib("file-state");
 const runPath = join(stateDir, "run.json");
 const progressPath = join(stateDir, "progress.json");
 const resultPath = join(stateDir, "result.json");

package/scripts/coordinator.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 
 function arg(name, fallback = "") {
   const prefix = `--${name}=`;
@@ -60,6 +60,9 @@ async function sleep(ms) {
   await new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+const STATE_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+const STATE_LOCK_TIMEOUT_MS = 5000;
+
 async function waitForPath(path, timeoutMs = 5000) {
   const started = Date.now();
   while (!existsSync(path)) {
@@ -68,6 +71,37 @@ async function waitForPath(path, timeoutMs = 5000) {
   }
 }
 
+async function acquireStateLock(parentDir, name, label) {
+  await mkdir(parentDir, { recursive: true });
+  const lockDir = `${parentDir}/${name}`;
+  const started = Date.now();
+  while (true) {
+    try {
+      await mkdir(lockDir);
+      await writeFile(`${lockDir}/owner.json`, `${JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() })}\n`, "utf8");
+      return async () => rm(lockDir, { recursive: true, force: true });
+    } catch (error) {
+      try {
+        const current = await stat(lockDir);
+        if (Date.now() - current.mtimeMs > STATE_LOCK_MAX_AGE_MS) {
+          await rm(lockDir, { recursive: true, force: true });
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (Date.now() - started > STATE_LOCK_TIMEOUT_MS) {
+        throw new Error(`${label} lock timed out.`, { cause: error });
+      }
+      await sleep(10);
+    }
+  }
+}
+
+async function acquireBranchInboxLock(runId, branchName) {
+  return acquireStateLock(`${runStateDir(runId)}/branches/${branchName}`, ".inbox.lock", `Branch inbox ${branchName}`);
+}
+
 async function writeLockerMessage(locker, message) {
   if (!locker) return;
   await waitForPath(locker.controlPath);
@@ -186,46 +220,64 @@ async function synthesize(config, locker) {
   process.stdout.write(`artifact=${config.artifactPath}\n`);
 }
 
+async function readInboxLines(inboxPath) {
+  if (!existsSync(inboxPath)) return [];
+  const content = await readFile(inboxPath, "utf8");
+  return content.split("\n").filter(Boolean).map((line) => JSON.parse(line));
+}
+
+async function writeInboxMessages(inboxPath, messages) {
+  await writeFile(inboxPath, messages.map((message) => JSON.stringify(message)).join("\n") + "\n", "utf8");
+}
+
+async function claimQueuedInboxMessages(runId, branchName) {
+  const inboxPath = `${runStateDir(runId)}/branches/${branchName}/inbox.jsonl`;
+  const releaseLock = await acquireBranchInboxLock(runId, branchName);
+  try {
+    const messages = await readInboxLines(inboxPath);
+    const claimedAt = new Date().toISOString();
+    const queuedMessages = [];
+    const updated = messages.map((msg, index) => {
+      if (msg.status !== "queued" && msg.status) return msg;
+      const claimed = {
+        ...msg,
+        claimed_at: claimedAt,
+        id: msg.id || `legacy-${Date.now()}-${index}`,
+        status: "claimed",
+      };
+      queuedMessages.push(claimed);
+      return claimed;
+    });
+    if (queuedMessages.length > 0) await writeInboxMessages(inboxPath, updated);
+    return queuedMessages;
+  } catch {
+    return [];
+  } finally {
+    await releaseLock();
+  }
+}
+
 async function updateInboxMessagesStatus(runId, branchName, ids, status) {
   const inboxPath = `${runStateDir(runId)}/branches/${branchName}/inbox.jsonl`;
+  const releaseLock = await acquireBranchInboxLock(runId, branchName);
   try {
-    if (!existsSync(inboxPath)) return;
-    const content = await readFile(inboxPath, "utf8");
-    const lines = content.split("\n").filter(Boolean);
-    const updatedLines = [];
-    for (const line of lines) {
-      const msg = JSON.parse(line);
-      if (msg.id && ids.includes(msg.id)) {
-        msg.status = status;
-        msg[`${status}_at`] = new Date().toISOString();
-      }
-      updatedLines.push(JSON.stringify(msg));
-    }
-    await writeFile(inboxPath, updatedLines.join("\n") + "\n", "utf8");
-  } catch (err) {
+    const messages = await readInboxLines(inboxPath);
+    const idSet = new Set(ids);
+    const updated = messages.map((msg) => {
+      if (!msg.id || !idSet.has(msg.id)) return msg;
+      return { ...msg, [`${status}_at`]: new Date().toISOString(), status };
+    });
+    await writeInboxMessages(inboxPath, updated);
+  } catch {
     // Best-effort write
+  } finally {
+    await releaseLock();
   }
 }
 
 async function executeParticipantPrompt(role, basePrompt, config) {
   const branchName = role.name;
-  const inboxPath = `${runStateDir(config.runId)}/branches/${branchName}/inbox.jsonl`;
-  const queuedMessages = [];
-  
-  try {
-    if (existsSync(inboxPath)) {
-      const content = await readFile(inboxPath, "utf8");
-      const lines = content.split("\n").filter(Boolean);
-      for (const line of lines) {
-        const msg = JSON.parse(line);
-        if (msg.status === "queued" || !msg.status) {
-          queuedMessages.push(msg);
-        }
-      }
-    }
-  } catch (err) {
-    // Best-effort read
-  }
+  const queuedMessages = await claimQueuedInboxMessages(config.runId, branchName);
 
   let finalPrompt = basePrompt;
   const claimedIds = [];
@@ -239,10 +291,6 @@ async function executeParticipantPrompt(role, basePrompt, config) {
     }
     inboxSection += "\nPlease acknowledge and address these direct messages in your response.\n";
     finalPrompt += inboxSection;
-
-    if (claimedIds.length > 0) {
-      await updateInboxMessagesStatus(config.runId, branchName, claimedIds, "claimed");
-    }
   }
 
   const result = await runPi(finalPrompt, config.model, config.thinking);

package/scripts/validate-recipe.mjs

@@ -1,9 +1,30 @@
 #!/usr/bin/env -S node --experimental-strip-types
-import { existsSync, readdirSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { resolve } from "node:path";
+import { cpSync, existsSync, mkdtempSync, readdirSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
-import { readResolvedRecipeConfig } from "../lib/recipe-references.ts";
+function scriptFile() {
+  return fileURLToPath(import.meta.url);
+}
+
+function isUnderNodeModules(file) {
+  return /[/\\]node_modules[/\\]/.test(file);
+}
+
+function prepareTypeStripImportRoot() {
+  const packageRoot = dirname(dirname(scriptFile()));
+  const sourceLib = join(packageRoot, "lib");
+  if (!isUnderNodeModules(packageRoot)) return sourceLib;
+  const copiedLib = join(mkdtempSync(join(tmpdir(), "pi-actors-validate-lib-")), "lib");
+  cpSync(sourceLib, copiedLib, { recursive: true });
+  return copiedLib;
+}
+
+const typeStripImportRoot = prepareTypeStripImportRoot();
+const { readResolvedRecipeConfig } = await import(
+  pathToFileURL(join(typeStripImportRoot, "recipe-references.ts")).href
+);
 
 function usage() {
   console.error(`Usage:

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.19.4
+  version: 0.19.11
 ---
 
 # Actors (pi-actors)
@@ -122,10 +122,10 @@ Views:
 Actor inspector commands:
 
 - `/actors-inspector-toggle [rows]`: open/close the compact table or set row count; default is 12 log rows when no size is supplied.
-- `/actors-inspector-filter all|room|direct|broadcast|mention <text>`: narrow table previews without changing room/run state.
+- `/actors-inspector-filter all|room|direct|broadcast|unread|branch <name>|current-branch <name>|mention <text>`: narrow table previews without changing room/run state.
 - `/actors-inspect <number>`: open one visible row as a full-message view.
 
-The table is compact and optimistic by default: bounded body previews, capped noisy room rows, and an inline roster summary in the form `name/role` that wraps only when needed. Active roster members use the target color; members that sent `actor.leave` stay visible as inactive/muted participants from the current run. Actor display names come from `actor.join` bodies (`display`) or branch addresses, keeping debugger output plain and name-driven.
+The table is compact and optimistic by default: bounded body previews, capped noisy room rows, branch-local inbox previews, and an inline roster summary in the form `name/role` that wraps only when needed. Use `unread` for queued branch inbox work and `branch <name>` / `current-branch <name>` for one branch's room/direct/inbox traffic. Active roster members use the target color; members that sent `actor.leave` stay visible as inactive/muted participants from the current run. Actor display names come from `actor.join` bodies (`display`) or branch addresses, keeping debugger output plain and name-driven.
 
 Let terminal notifications arrive; avoid sleep-poll loops except during diagnosis.
 

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