@llblab/pi-actors 0.17.0 → 0.18.0

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-communication-tui.ts` owns compact terminal previews 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, `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
 - `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
@@ -45,12 +45,14 @@
 - `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
 - `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: each running async run contributes at least one triangle, and its reported active parallel command/subagent branches contribute the visible branch count when greater than one. 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, terminal notifications as event-driven behavior, and docs/examples that teach reactive run→coordinator→message loops before sleep-polling patterns.
+- `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 current/future work, blockers, gates, and next leverage points; completed delivery history belongs in `CHANGELOG.md`, and durable behavior belongs in README/docs | Trigger: Editing backlog or reconciling completed slices | Action: Remove historical progress narratives, keep current task/scope/exit criteria, and prefer an 80/20 focus list when many remaining tasks compete for attention
+- `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
 - `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
+- `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

@@ -2,6 +2,19 @@
 
 ## Open Work
 
+### Direct Actor Inbox Queue Semantics
+
+- Priority: High.
+- Goal: Make direct actor-to-actor messages initiating work items, not passive files that the receiving actor may or may not inspect.
+- Direction:
+  - Deliver direct messages into the recipient actor's next prompt/context as soon as the branch runner can accept work.
+  - Keep the model simple: FIFO direct messages, no priority tiers unless real usage proves they are needed.
+  - Keep room messages as shared transcript only; a direct message may ask the recipient to inspect room history when broader context is needed.
+  - Wire branch runner protocols to claim/handle/fail messages from the current inspectable per-branch inbox files (`branches/<branch>/inbox.jsonl`, surfaced through `inspect branch:<run>/<branch> view=mailbox`); internal helpers can already transition queued messages to claimed/handled/failed for retries.
+- Exit:
+  - A direct branch message can wake or continue a long-lived branch runner without waiting for that runner to poll room files.
+  - Room transcript semantics remain unchanged and compatible with `room:<run>` inspection.
+
 ### Actor Rooms, Roster, and Cross-Branch Messaging
 
 - Priority: High.
@@ -9,22 +22,47 @@
 - 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.
-  - Add selected-recipient multicast for a subset of actors without creating subrooms.
+  - Avoid full roster rewrite amplification during bursty room activity; branch communication snapshot writes are already debounced while root snapshots stay current.
 - Exit:
   - Any backend/storage change preserves existing `spawn` / `message` / `inspect` semantics and room address compatibility.
-  - Selected-recipient multicast remains route-based and does not introduce named subrooms.
 
 ### Actor Communication TUI Preview
 
-- Priority: Medium.
+- Priority: High.
 - Goal: Make actor-to-actor communication more navigable in the terminal UI without exposing large payloads by default.
 - Direction:
-  - Add explicit filters for current branch, room, direct messages, unread messages, and mentions.
-  - Add a roster panel for current run/room participants with address, role, caps, status, and last seen.
-  - Collapse long bodies by default and respect sensitive/redacted metadata.
-  - Rate-limit noisy rooms and keep full body inspection intentional.
+  - 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.
+- Goal: Automatically retire coordinator/helper actors that were launched only to supervise a bounded worker tree once their dependent workers have finished.
+- 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.
+  - 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.
+
+### Consensus-First Build Recipe
+
+- Priority: Medium.
+- Goal: Promote the proven proposer → implementer → QA → finalizer pattern into a generic packaged workflow instead of demo-specific scripts; pi-actors should grow its standard recipe/script library for recurring actor OS scenarios.
+- Direction:
+  - Public inputs: mission, artifact paths/assertions, proposer role JSON, implementer prompt, QA prompt, model/thinking/tool knobs, and optional room/locker settings.
+  - Proposers should coordinate through room messages with no write tools.
+  - The implementer owns the first artifact write after inspecting room consensus.
+  - QA inspects artifacts and room evidence without mutating files.
+  - The finalizer applies QA-grounded fixes and emits `run.done` only after artifact assertions pass.
+  - Reuse packaged subagent/message/artifact components where practical; if a script is needed, make it a generic packaged helper in the extension, not a task-local demo script.
 - Exit:
-  - Operators can answer “what are the actors saying?” from the TUI at a glance, then intentionally inspect full room or direct-message bodies when needed.
+  - 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.
 
 ### Persistent Backlog Implementer Workflow
 
@@ -40,15 +78,14 @@
   - A packaged workflow, if added, is described by recipes and existing helper cells; no one-off backlog-implementer scripts are required.
   - The actors skill documents the supported launch scenarios and the concrete packaged recipes for each.
 
-### Recipe Schema Simplification
 
-- Priority: Medium.
-- Goal: Remove recipe metadata that duplicates storage context.
-- Direction:
-  - Remove `name` from the recipe standard. Recipe identity should come from the recipe filename/id rather than a redundant JSON property. Keep migration/backward compatibility explicit for existing packaged and user recipes.
-  - Finish hardening validators/discovery against recipe-owned tool exposure: tool status should be determined by location under `~/.pi/agent/recipes/*.json`, while packaged/ad hoc/component recipes are not tools by default. Repository recipes and docs no longer author `tool`.
+### Branch-Local Checkpoint Semantics
+
+- Priority: Low.
+- Blocked by: At least one real collaborative branch-runner async-run experiment.
+- Goal: Validate whether `failure: "branch"`, node-level `retry`, and `recover` cleanup are enough for branch-local validation and bounded reattempts.
 - Exit:
-  - Docs, validators, packaged recipes, discovery, and migration behavior all agree on filename-derived identity and location-derived tool exposure.
+  - Record one decision: sufficient, documentation-only refinement needed, or propose one minimal command-template extension with tests.
 
 ### Host-Level Tool Unregistration
 
@@ -65,6 +102,7 @@
 ### Recipe Discovery Expansion
 
 - Priority: Low.
+- Goal: Support larger recipe libraries without confusing recipe identity or priority.
 - Direction:
   - 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.
@@ -72,21 +110,8 @@
 ### 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.
   - Do not add failure counters as primary usefulness evidence unless there is a strong operator-facing need.
 
-### Opportunistic Recipe Library Growth
-
-- Priority: Low.
-- Direction:
-  - Add new utilities or pipelines only when a concrete repeated task pattern justifies them.
-
-## Blocked Work
-
-### Branch-Local Checkpoint Semantics
-
-- Priority: Low.
-- Blocked by: At least one real collaborative branch-runner async-run experiment.
-- Scope: Validate whether `failure: "branch"`, node-level `retry`, and `recover` cleanup are enough for branch-local validation and bounded reattempts.
-- Exit: Record one decision: sufficient, documentation-only refinement needed, or propose one minimal command-template extension with tests.

package/CHANGELOG.md

@@ -1,11 +1,27 @@
 # Changelog
 
-## Unreleased
+## 0.18.0: Actor Runtime Hardening And Recipe Guardrails
+
+- `[Async Runs]` Made actor starts safer under concurrency and stale state. Duplicate active `run_id` / `state_dir` launches now fail before state is cleared, concurrent starts are serialized by a start lock, stale terminal run directories are cleaned automatically, and atomic JSON writes use collision-resistant temp names. Impact: restarts and concurrent launches no longer orphan active processes or overwrite logs, messages, progress, and control metadata.
+- `[Command Templates]` Added a default parallel fanout cap of 64 branches, configurable with `PI_ACTORS_MAX_PARALLEL_BRANCHES`. Impact: accidental huge repeat/parallel expansions fail early instead of spawning unbounded child processes.
+- `[Rooms & Messages]` Hardened room communication while preserving the single public actor-message model. Room timeline/roster/snapshot writes are serialized, branch direct messages are also persisted as queued per-branch inbox entries with IDs and internal claimed/handled/failed state transitions, bursty branch communication snapshot rewrites are debounced while root snapshots stay current, room reads use bounded tails, room timelines compact to a bounded retained tail, and `room:<run>` supports selected-recipient multicast via `metadata.recipients` while keeping one room-visible transcript entry. Impact: long-lived swarms can address subsets of same-run branches without subrooms, lost concurrent writes, unbounded room logs, repeated burst branch-snapshot rewrites, or expensive full-log reads.
+- `[Actor Inspector]` Turned the inspector into a compact operator view for active actor coordination. It now has channel/mention filters, bounded body previews, default noisy-room row caps, an inline wrapping `role/name` roster summary with inactive departed participants muted, stable narrow-row rendering, plain name-driven actor identity, and bounded wide-character layout. Impact: operators can follow busy rooms, distinguish current and completed participants, and inspect selected messages without flooding the terminal, expanding roster dashboards, or adding extra preview-mode commands.
+- `[Observability]` Reduced long-session overhead by pruning stale run observation state, caching active-subagent process scans, and expanding ambient run triangles with descendant `pi -p` workers launched by coordinators. Impact: terminal status remains useful during long actor sessions without retaining completed-run bookkeeping, repeatedly scanning `/proc` on every refresh, or showing one coordinator triangle when a visible worker tree is still running.
+- `[Recipes]` Strengthened the recipe registry as a local capability surface. Recipe loading now rejects oversized files and excessive import depth, reports risky executable shapes and unsafe recipe-root permissions, exposes an integrity manifest, warns when the recipe-root watcher fails, derives recipe identity from filenames, resolves bare import names by recipe-root priority, and makes tool exposure location-derived: user recipe-root files are tools, packaged/ad hoc recipes are components. Impact: recipes are easier to audit, easier to compose from the standard library, harder to misuse accidentally, and no longer depend on redundant `name` / `tool` JSON fields for identity or exposure.
+- `[Docs/Skills/Context]` Updated the README, actor-message/template-recipe/command-template docs, recipe-library/task-first docs, actors/swarm skills, onboarding prompt, and project context to reflect the hardened runtime, room/inspector controls, filename-derived recipes, location-derived tools, consensus-first build orchestration, shell-placeholder boundaries, and the rule that recurring multi-agent scenarios should grow packaged recipes/pipelines instead of task-local orchestration scripts. `BACKLOG.md` now stays focused on completable future work while durable operating principles live in project context.
+- `[Package]` Bumped package and packaged skill metadata to `0.18.0`; promoted the release from a hotfix to a minor release because the scope now includes actor runtime hardening, room/TUI behavior, recipe guardrails, observability cleanup, and agent-facing guidance updates.
+
+## 0.17.1: Inspector Hotfix And Room Swarm Hardening
+
+- `[TUI]` Fixed actor inspector line bounding to use `visibleWidth()` for direction/type/summary/body width math, replaced the verbose two-line preview with a hidden-by-default numbered table, made bare `/actors-inspector-toggle` open 12 rows from closed state, removed the verbosity toggle, made `/actors-inspector-toggle <rows>` update the live row count, upgraded `/actors-inspect <number>` to show a separated two-column header plus all preview-object properties as aligned two-space key/value columns, and added a styled wide-character regression. Impact: room previews with wide text no longer crash Pi, actor logs stay dense while preserving message type visibility, operators can tune visible row count without persistent inspector settings, and they can drill into one visible row then toggle back to the table.
+- `[Recipe Library]` Added `pipeline-room-swarm` backed by `scripts/room-swarm.mjs`: repeated room-aware participants join `room:<run>`, coordinate over multiple room-visible rounds, leave cleanly, and synthesize the room transcript into a Markdown artifact. Roles can be supplied via `roles_path` to avoid raw JSON placeholders, default roles use plain actor names, room rosters preserve display metadata, and `locker=true` composes a local coordinator-locker cell for artifact locks and decision journaling with regression coverage. Direct branch delivery remains available for worker protocols that consume parent-run branch envelopes, but the packaged swarm no longer relies on it for peer coordination. Impact: the DeepSeek room-swarm experiment is now represented as a policy-light packaged scenario while concrete model choice remains caller/operator policy.
+- `[Docs]` Reconciled `BACKLOG.md` back to future-only open work, removing completed hotfix implementation notes and version-scoped backlog language now captured in this changelog. Refreshed README and project context around the packaged room-swarm/coordinator-locker library surface and actor-inspector TUI ownership.
+- `[Package]` Bumped package and packaged skill metadata to `0.17.1` for the hotfix release.
 
 ## 0.17.0: Actor Rooms And Inspector
 
 - `[Actor Messages]` Added the 0.17 actor-room communication slice: `room:<run>` task rooms, append-only room timelines, room rosters, join/leave handling, same-run room/direct provenance checks, branch/run communication snapshots, `inspect room:<run> view=status|messages|previews|roster|contacts`, and `inspect run:<id> view=communication`. Impact: run actors and contacted branches can discover peers, post shared task messages, and inspect communication state through the same `spawn` / `message` / `inspect` actor model.
-- `[TUI]` Added the hidden-by-default actor inspector widget with `/actors-inspector-toggle` and `/actors-inspector-verbosity-toggle`, compact and verbose layouts, current-run scoping, chronological sequence numbers, owner filtering, JSONL-tolerant preview reads, mobile-width and wide-glyph-aware truncation, and transparent/dark row striping. Impact: operators can see the current actor conversation at a glance without flooding the prompt or leaking unrelated session previews.
+- `[TUI]` Added the hidden-by-default actor inspector widget with `/actors-inspector-toggle` and `/actors-inspector-verbosity-toggle`, compact and verbose layouts, current-run scoping, chronological sequence numbers, owner filtering, JSONL-tolerant preview reads, mobile-width and wide-character-aware truncation, and transparent/dark row striping. Impact: operators can see the current actor conversation at a glance without flooding the prompt or leaking unrelated session previews.
 - `[Registry]` Added usage metadata and operator-gated cleanup recommendations to recipe registry summaries, removed stale public references to the old tool config filename, removed recipe-owned `tool` properties from repository recipes/docs/fixtures, and fixed the 0.17 registry model around location-derived tool exposure: every recipe in `~/.pi/agent/recipes/*.json` is an agent tool, `register_tool` creates recipe files there under the hood, and packaged/ad hoc recipes outside that root are components. Impact: the sticky agent tool surface is explicit executable muscle memory, maintained like capability state rather than configured through per-recipe tool flags.
 - `[Docs]` Updated README, actor-message docs, async-run docs, recipe-library docs, actors skill, backlog, and project context around the room/roster protocol, inspector behavior, release-artifact hygiene, and the persistent-backlog-implementer protocol. The implementer workflow remains future recipe-composition work around reusable cells such as `coordinator-locker`, not bespoke release scripts.
 - `[Package]` Bumped package and packaged skill metadata to `0.17.0`; validated with `npm run validate` and context validation. PR #42 tracks the squashed `actor-rooms-017` branch as one release commit against `main` with green checks.