@llblab/pi-actors 0.19.3 → 0.19.10

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
@@ -39,7 +39,7 @@
 
 - `Knowledge surface separation`: pi-actors has distinct knowledge surfaces with different context-entry behavior: injected prompt is always present and should stay a tiny bootstrap/reminder; packaged `actors` skill is auto-matched by name/description and should signal that its body is the highest-density practical guide for operating the extension plus the shortest navigator to bundled recipes; packaged `swarm` skill is auto-matched for multi-agent methodology, strategies, standards, and portable examples; README is the human entrypoint explaining concept, rhythm, benefits, and scenarios but is not automatically in context; `/docs` are detailed transportable standards read on demand; `AGENTS.md` is project context and architectural constraints for agents changing the repo | Trigger: Editing prompt copy, README, docs, skills, or project context | Action: Keep each surface on its own wave, avoid duplicating prompt and skill headers, keep the actors skill recipe navigator compact and concrete, avoid duplicating scenario catalogs or changelog narratives in the actors skill, avoid turning the prompt into docs, keep multi-agent methodology in swarm-oriented guidance rather than the actors skill, keep packaged extension skill metadata versions synchronized with `package.json` version, and avoid extra colons in skill frontmatter scalar lines because skill formatters treat them poorly
 - `Tool registry is executable muscle memory`: `~/.pi/agent/recipes/*.json` is the persistent user tool surface by location: every recipe in that agent root is automatically registered as an agent tool across sessions, and `register_tool` creates/updates/deletes recipe files there under the hood | Trigger: Any runtime registration, recipe discovery, migration, docs, skill, prompt, or recipe authoring work | Action: Treat the directory like `MEMORY.md` for executable habits; preserve filename identity, atomic writes, explicit operator-gated migration paths, and never author a recipe-owned `tool` property in repository recipes, docs, or fixtures; packaged/ad hoc recipes outside the agent root are components, not tools
-- `Current runtime contract`: Register trusted command templates with tool names from registry keys, placeholder-derived args, progressive typed arg declarations, inline/default/`??`/ternary config fallback, placeholder-derived numeric node controls, split-first command-arg construction, sequential or `parallel: true` composition, direct no-shell execution, optional per-node `when`, optional per-node positive `timeout` disabled by default, lightweight warnings for obvious trusted-executable risk shapes, per-node `delay`, bounded leaf/node `retry`, `failure: "continue|branch|root"` propagation, `recover` cleanup between retry attempts, template recipes with explicit `async: true` detached mode, actor-oriented `spawn`/`message`/`inspect` tools with run-local JSONL outbox messages, Unix FIFO send, graceful cancel, and force kill, generic detached run primitives with process-group cancellation, injected async `{run_id}` and `{state_dir}` values, coordinator-scoped event-driven observability with at least one triangle per active async run and extra triangles for active parallel branches, runtime-inferred `command.done` bubbling for packaged multi-agent fanout, terminal follow-ups for `done`/`failed`/unhandled `killed`/`exited` states, recipe-persistence suggestions for successful direct inline/ad hoc `spawn` runs that are not already durable user recipes, named recipe `artifacts`, recipe `mailbox` metadata, `template` recipe references, recipe-layer `imports`, file-backed async recipe JSONL context bundles for child `pi -p` actors with raw entry/import recipes and `"you_are_here": true`, co-located recipe entries, `~/.pi/agent/recipes/*.json` template recipe files, run state under `~/.pi/agent/tmp/pi-actors/runs`, and `{file}` as the canonical local file path arg | Trigger: Changing registration or invocation behavior | Action: Keep README, command-template docs, template-recipe docs, async-run docs, actor-message docs, implementation, and migration notes aligned
+- `Current runtime contract`: Register trusted command templates with tool names from registry keys, placeholder-derived args, progressive typed arg declarations, inline/default/`??`/ternary config fallback, placeholder-derived numeric node controls, split-first command-arg construction, sequential or `parallel: true` composition, direct no-shell execution, optional per-node `when`, optional per-node positive `timeout` disabled by default, lightweight warnings for obvious trusted-executable risk shapes, per-node `delay`, bounded leaf/node `retry`, `failure: "continue|branch|root"` propagation, `recover` cleanup between retry attempts, template recipes with explicit `async: true` detached mode, actor-oriented `spawn`/`message`/`inspect` tools with run-local JSONL outbox messages, Unix FIFO send, graceful cancel, and force kill, generic detached run primitives with process-group cancellation, injected async `{run_id}` and `{state_dir}` values, coordinator-scoped event-driven observability with at least one triangle per active async run and extra triangles for active parallel branches, runtime-inferred `command.done` bubbling for packaged multi-agent fanout, terminal follow-ups for `done`/`failed`/unhandled `killed`/`exited` states, recipe-persistence suggestions for successful direct inline/ad hoc `spawn` runs and successful recipes outside the durable user recipe root, named recipe `artifacts`, recipe `mailbox` metadata, `template` recipe references, recipe-layer `imports`, file-backed async recipe JSONL context bundles for child `pi -p` actors with raw entry/import recipes and `"you_are_here": true`, co-located recipe entries, `~/.pi/agent/recipes/*.json` template recipe files, run state under `~/.pi/agent/tmp/pi-actors/runs`, and `{file}` as the canonical local file path arg | Trigger: Changing registration or invocation behavior | Action: Keep README, command-template docs, template-recipe docs, async-run docs, actor-message docs, implementation, and migration notes aligned
 - `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
@@ -50,10 +50,10 @@
 - `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

@@ -9,19 +9,10 @@
 - 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.
   - 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, and branch-local inbox append/status rewrites are lock-guarded.
 - 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.
-
 ### Graceful Actor Retirement
 
 - Priority: Medium.
@@ -29,7 +20,7 @@
 - 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:

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 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.
+- `[Runtime]` Preserved the ask-first boundary and suppression for recipes already in the user recipe root, so pi-actors grows operator muscle memory without silently writing user recipe files.
+- `[Docs/Prompt]` Updated README, async-run docs, actors skill, onboarding prompt, and project context to frame `~/.pi/agent/recipes` as the everyday per-machine collection of reusable actor recipes/tools.
+- `[Tests]` Added coverage for successful external recipe suggestions, while keeping user-owned recipe suppression covered.
+- `[Package]` Bumped package metadata, lockfile metadata, and packaged skill metadata to `0.19.4` for the hotfix release.
+
 ## 0.19.3: Spawn Recipe Persistence Suggestions
 
 - `[Observability]` Added semi-active recipe persistence suggestions for successful direct `spawn` runs. Inline/ad hoc spawned actors now record `launch_source: "spawn"`, and their successful terminal follow-up asks the agent to offer saving the reusable pattern as a durable recipe/tool under `~/.pi/agent/recipes` without auto-saving.

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
 
@@ -239,7 +241,7 @@ Packaged recipes are building blocks. Copy them into `~/.pi/agent/recipes/` or r
 
 Use a foreground registered tool when the work is short, bounded, and does not need lifecycle.
 
-Use an async recipe or `spawn` when the work is long-running, service-like, parallel, agentic, artifact-producing, or needs later control. If a directly spawned inline/ad hoc actor completes successfully, pi-actors sends the launching agent a follow-up note to offer saving that pattern as a durable recipe/tool under `~/.pi/agent/recipes`; the agent should ask first and never auto-save.
+Use an async recipe or `spawn` when the work is long-running, service-like, parallel, agentic, artifact-producing, or needs later control. When a directly spawned inline/ad hoc actor or a recipe outside the user recipe root completes successfully, pi-actors sends the launching agent a follow-up note to offer saving that pattern as a durable recipe/tool under `~/.pi/agent/recipes`; the agent should ask first and never auto-save.
 
 Use `room:<run>` when multiple actors in the same run need shared context, roster discovery, or group-visible progress.
 

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

@@ -124,7 +124,7 @@ The core loop is:
    { "recipe": "music-player.json", "as": "run:music" }
    ```
 
-2. Let terminal completion, `command.done`, and script-authored follow-up messages reach the launching coordinator automatically. When a directly spawned inline/ad hoc actor completes successfully, the coordinator follow-up tells the agent to offer recipe persistence only as a question to the operator; it must not auto-save.
+2. Let terminal completion, `command.done`, and script-authored follow-up messages reach the launching coordinator automatically. When a directly spawned inline/ad hoc actor or a recipe outside `~/.pi/agent/recipes` completes successfully, the coordinator follow-up tells the agent to offer recipe persistence only as a question to the operator; it must not auto-save.
 
 3. Respond with explicit run-local messages when needed:
 
@@ -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!,
     }));
@@ -636,17 +663,17 @@ function isUserRecipeFile(file: string | undefined): boolean {
 export function shouldSuggestRecipePersistence(
   transition: RunTransition,
 ): boolean {
-  return (
-    transition.to === "done" &&
-    transition.launchSource === "spawn" &&
-    !transition.tool &&
-    !isUserRecipeFile(transition.recipeFile)
-  );
+  if (transition.to !== "done") return false;
+  if (isUserRecipeFile(transition.recipeFile)) return false;
+  return Boolean(transition.recipeFile) || transition.launchSource === "spawn";
 }
 
 function formatRecipePersistenceSuggestion(transition: RunTransition): string {
   if (!shouldSuggestRecipePersistence(transition)) return "";
-  return `\nAgent note: this actor was spawned directly and completed successfully. If this pattern looks reusable, ask the operator whether to save it as a durable recipe/tool under ~/.pi/agent/recipes with register_tool. Do not auto-save without confirmation.`;
+  if (transition.recipeFile) {
+    return `\nAgent note: this actor completed successfully from recipe ${transition.recipeFile}. If this recipe fits this machine's recurring workflow, ask the operator whether to copy or register it as a durable tool recipe under ~/.pi/agent/recipes. Do not auto-save without confirmation.`;
+  }
+  return `\nAgent note: this actor was spawned directly and completed successfully. If this pattern fits this machine's recurring workflow, ask the operator whether to save it as a durable recipe/tool under ~/.pi/agent/recipes with register_tool. Do not auto-save without confirmation.`;
 }
 
 export function formatRunTransitionMessage(transition: RunTransition): string {

package/lib/prompts.ts

@@ -29,7 +29,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Use spawn/message/inspect for actor-level start/send/observe; avoid runtime/FIFO/outbox vocabulary in public guidance.
 - Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.
-- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones; packaged recipes are lower-priority components; offer to save successful direct spawn patterns only after confirmation.
+- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
 - Foreground tools/templates fit short work; async recipes/runs fit subagents, services, fanout, media, and long pipelines.
 - Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.
 - For deeper pi-actors guidance, inspect installed extension sources/docs/recipes; README and docs are not automatically in context.`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.19.3",
+  "version": "0.19.10",
   "private": false,
   "description": "Actor runtime and orchestrator for agent-managed local processes",
   "keywords": [

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/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.3
+  version: 0.19.10
 ---
 
 # Actors (pi-actors)
@@ -63,7 +63,7 @@ Rules:
 
 - Use `file`/`recipe` for saved recipes; bare names resolve under `~/.pi/agent/recipes`.
 - Use inline `template` for one-off experiments; promote useful repeats to recipes.
-- When a directly spawned inline/ad hoc actor completes successfully and the follow-up suggests persistence, offer to save it as a recipe/tool; ask before writing `~/.pi/agent/recipes`.
+- When a successful actor follow-up suggests persistence, offer to save or register the pattern under `~/.pi/agent/recipes`; ask before writing the user recipe root.
 - Use stable `as` names when you will inspect or message the actor later.
 - `async: true` on the recipe is the detached run switch.
 
@@ -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.3
+  version: 0.19.10
 ---
 
 # Swarm