@llblab/pi-actors 0.38.1 → 0.40.0

package/AGENTS.md

@@ -61,7 +61,7 @@ Pi host
 - `/skills/actors/SKILL.md`: Dense practical reference for operating pi-actors itself.
 - `/skills/swarm/SKILL.md`: Bundled methodology skill for multi-agent standards, strategies, and portable examples.
 - `/tests/*.test.ts`: Focused regression tests for pure domains.
-- `/README.md`: Human-facing install, usage, and runtime semantics.
+- `/README.md`: Human-facing install, usage, and runtime semantics. Keep it as a product/onboarding entrypoint rather than an implementation dump: identity → why it exists → core verbs → install → first run → address/message model → feature showcase → golden path → recipe memory → platform/safety/docs. Preserve both layers: strong local-actor-kernel positioning plus compact practical capability catalog.
 - `/BACKLOG.md`: Canonical open work; only completable future work.
 - `/CHANGELOG.md`: Completed delivery history.
 - `/docs/README.md`: Documentation index.
@@ -102,20 +102,25 @@ Pi host
 ## Runtime Contract
 
 - Register trusted command templates with placeholder-derived args, progressive typed arg declarations, inline/default/`??`/ternary fallback, and split-first command argv construction.
+- Serialize extension-authored recipe mutations with the canonical-path file lock across the complete check/read/write/runtime-update window; keep usage telemetry in locked `.usage/<recipe-filename>.json` sidecars so metadata cannot overwrite authored recipes, and do not replace keyed locking with a broad registry lock.
 - Keep command templates synchronous and portable; `async: true` is the detached run switch.
 - Preserve node controls: `when`, positive `timeout`, `delay`, bounded `retry`, `failure`, and `recover` cleanup.
+- Persist every async command's complete byte-exact stdout/stderr under command- and retry-specific run-state paths while keeping returned tails bounded and pipeline stdin complete.
 - Keep async run state under `~/.pi/agent/tmp/pi-actors/runs` with injected `{run_id}` and `{state_dir}` values.
-- Preserve event-driven observability: terminal follow-ups, coordinator-bound outbox messages, branch-aware triangles, process-tree expansion, and bounded body previews.
-- Do not restore busy-polling examples, duplicate terminal follow-ups, or duplicate follow-ups for handled `cancel`, `kill`, or control-stop actions.
+- Preserve event-driven observability: durable retrying terminal steering notifications, coordinator-bound outbox messages, branch-aware triangles, process-tree expansion, and bounded body previews. Terminal delivery is at-least-once across the unavoidable send/handled-marker crash window.
+- When a deferred actor result gates the next step, wait for its terminal steering notification. Do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs; inspect early only on operator request, meaningful actor event, or diagnosis of an overdue/stuck run.
+- Do not restore busy-polling examples, duplicate terminal notifications, or duplicate notifications for handled `cancel`, `kill`, or control-stop actions.
 
 ## Recipes And Registry
 
 - `~/.pi/agent/recipes/*.json` is executable muscle memory: recipes there become persistent tools by location.
 - Preserve filename identity, atomic writes, explicit operator-gated changes, and local transportability.
+- Recipe live reload must watch the parent when the user recipe root is absent, switch to the root watcher when it appears, and rearm after deletion/rename without polling or duplicate watcher ownership.
 - Packaged/ad hoc recipes outside the agent root are components, not user tools.
 - Register existing recipes by importing them from the user-root wrapper and using a `{ "name": "alias" }` template node; do not duplicate a ready recipe's script command, defaults, mailbox, or artifact contract in the wrapper.
 - Skill-owned scripts must be exposed through skill-owned recipes first. If a local tool needs that capability, import the skill recipe via `{agent}/skills/<skill>/recipes/<recipe>.json` instead of calling `{agent}/skills/<skill>/scripts/*` directly.
 - Tool definitions use `template`, not `script`, and built-in/core tool names must not be shadowed.
+- Host registrations may remain visible because Pi cannot unregister dynamic definitions, but extension-local `message` and `inspect` lookup must consult the current runtime recipe registry before returning or executing a cached definition.
 - Packaged recipe growth is demand-driven: prefer reusable components over speculative scenario catalogs.
 - Recipe templates may point directly at executable helper scripts when the recipe owns that script boundary; keep script executable bits and avoid unnecessary `node` prefixes.
 
@@ -131,12 +136,14 @@ Pi host
 
 ## State, IO, And Safety
 
-- Tool stdout and temp state must stay bounded and local.
+- Tool stdout and temp state must stay bounded and local; preserve complete high-volume streams in spill files with byte/truncation metadata, and never feed a truncated capture tail into pipeline stdin.
 - Feedback hints must be evidence-backed, bounded, and action-shaped; prefer `next_actions` pointing to existing verbs over prose, and avoid hints when no concrete next step is justified.
 - Keep tail truncation, full-output temp files, failure formatting, and centralized limits intact.
 - Published docs must not include machine-local absolute paths.
 - Any view scanning run directories must apply coordinator/session ownership filters before exposing summaries or previews.
 - Direct branch messages are active inbox queues; guard branch-local append/status rewrites with the branch inbox lock and keep claim/handled/failed transitions tested.
+- Run-state launch and destructive retention require the runtime ownership marker bound to the canonical directory and run id; reject non-run directories, missing/mismatched markers, and symlink aliases rather than trusting `run.json`.
+- Runner lifecycle and destructive process controls require the persisted cross-platform process identity proof (start time, command, and cwd where available); dead, mismatched, or unsupported proofs stay distinct and fail closed rather than degrading to pid liveness.
 - Room/branch provenance checks should validate that accepted `from` addresses belong to the addressed run.
 
 ## Coordination And Lifecycle

package/BACKLOG.md

@@ -37,9 +37,9 @@ Non-goals:
 - Arbitrary subrooms.
 - Heavy broker abstraction.
 
-## Hotfix Backlog
+## Open Work
 
-No open hotfix items.
+No active implementation or release-preparation work remains. The `0.40.0` release candidate is validated locally; commit, tag, merge, publish, and release actions remain operator-gated rather than backlog work.
 
 ## Backlog Curation Rules
 
@@ -49,10 +49,6 @@ No open hotfix items.
 - Prefer semantic compression before file splitting: fewer public nouns, consistent outcomes, compact diagnostics, and domain-owned constants/helpers.
 - Preserve signal/noise balance: feedback should be state-backed, compact, and action-shaped; do not add advisory prose just because a surface exists.
 
-## Minor Backlog
-
-No open minor items.
-
 The backlog is intentionally pruned to the 20% of work most likely to deliver 80% of value for `pi-actors` as a local actor kernel. Bias toward consolidation, smaller public surface area, and reliability over new feature breadth.
 
 ## Explicitly Deferred
@@ -64,11 +60,6 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 - Cross-session force kill or attach/adopt/reparent: useful later, but ownership policy should not change until observability makes current boundaries clear.
 - Actor address helper CLI: keep diagnostics improving opportunistically inside existing parser/tests.
 - Golden flow docs and flow conformance runner: useful after the diagnostic and promotion surfaces are stable.
-- Documentation refactor: defer until the canonical mailbox loop and worker recipe exist; avoid rewriting docs twice.
 - Host-level tool unregistration: blocked on host API support.
 - Branch-local checkpoint semantics: wait for real collaborative branch-runner experiments.
 - Actor recipe feedback loop: keep advisory and operator-gated after real runs produce evidence.
-
-## Suggested Milestone Order
-
-1. Re-curate after the next real packaged review-swarm dogfood run.

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 ## Unreleased
 
+## 0.40.0: Durable Review and Runtime Hardening
+
+- `[Runtime]` Collapsed every natural-language positional fragment in child `pi -p` launches into one inspectable prompt file while preserving Pi options and intentional `@file` attachments, so review stages receive one authoritative user turn and preflight diagnostics resolve the concrete stage.
+- `[Tests]` Made the packaged review-readiness dogfood fake Pi reject fragmented prompt argv, covering preflight, reviewer, verifier, merger, judge, and normalizer transport through the real detached runner.
+- `[Reviews]` Added opt-in `accept_output: review_evidence` semantics and marked packaged reviewer, verifier, merger, judge, and normalizer outputs with `ACTOR_REVIEW_RESULT`, so code-zero format acknowledgements or input requests fail closed instead of satisfying quorum or reaching later stages.
+- `[Diagnostics]` Preserved rejected parallel stdout alongside its semantic rejection reason, allowing degraded review runs to retain accepted and rejected branch evidence without counting placeholders as usable.
+- `[Breaking]` Removed public `spawn.state_dir` overrides and reject direct attempts with a retention-safety diagnostic, keeping every public `run:<id>` actor under the runtime-owned addressable run root.
+- `[Safety]` Added canonical run-state ownership markers and require them before launch reuse, archive, or prune; existing non-run directories, forged metadata, mismatched run ids, and symlink aliases now fail closed before destructive retention.
+- `[Safety]` Added and persisted Linux, macOS, and Windows process-identity proofs with start-time, command, and available cwd evidence; status, state reuse, message delivery, cancellation, kill, and retirement now distinguish dead pids, owner mismatches, unsupported proofs, and valid ownership instead of degrading to liveness alone.
+- `[Execution]` Bounded stdout and stderr tails while child commands are running, spilling complete high-volume streams independently with total byte counts, truncation flags, and diagnostic file paths instead of accumulating unbounded strings in memory.
+- `[Execution]` Propagated capture metadata through foreground results, retries, parallel branch diagnostics, and async run events; sequence and parallel pipelines now fail closed with `incomplete pipeline stdin` instead of feeding truncated tails downstream.
+- `[Registry]` Added cross-process file mutation locks keyed by canonical recipe path and wrapped register, update, delete, and draft-promotion windows; concurrent same-name registrations now have one explicit winner.
+- `[Registry]` Moved user-recipe usage telemetry into locked `.usage/<recipe-filename>.json` sidecars and merge it during discovery, so sibling-process counters remain monotonic while external recipe edits and file-watcher refreshes cannot be overwritten by metadata writes.
+- `[Routing]` Made `message to=tool:<name>` and `inspect tool:<name>` resolve definitions only when the current runtime recipe registry still marks the tool active; deleted/external-removed recipes are revoked immediately and updates route only to the newest extension-local definition despite host-level unregister limitations.
+- `[Retention]` Made pruned artifact preservation collision-safe with readable artifact-name/hash/basename targets and timestamp preservation; duplicate basenames remain distinct, missing optional artifacts stay skipped, and any copy failure aborts before source run state is deleted.
+- `[Registry]` Rearmed recipe live reload through an advisory parent watcher when `~/.pi/agent/recipes` is absent or renamed, switching back to the root watcher on creation and reloading on deletion; first-run creation, recreation, and idempotent shutdown now work without polling or session restart.
+- `[Backlog]` Rewrote the remaining packaged hardening review milestone as ordered open-checkbox tasks with decision-grade evidence, finding classification, reconciliation, and validation exit criteria.
+- `[Review]` Completed the six-lens packaged hardening pipeline above quorum. The normalized verdict was blocked by a reproduced UTF-8 capture defect; other reported concerns remained hypotheses because raw stage outputs were not retained for independent audit. Re-curated the backlog around durable per-stage review evidence before the next release-readiness run.
+- `[Execution]` Preserved raw command bytes across stream chunk boundaries and aligned bounded tails to UTF-8 code-point boundaries, preventing split multibyte output from becoming replacement characters while keeping complete spill files byte-exact.
+- `[Actors]` Added an async-patience invariant to the runtime prompt, project context, and bundled actors skill: when deferred actor output gates the next step, wait for the terminal follow-up instead of scheduling continuation loops, repeatedly inspecting, or mutating the reviewed scope.
+- `[Backlog]` Decomposed durable review provenance into nine ordered open tasks covering byte-exact stage output, evidence manifests, bounded inspection, report references, regression proof, re-review, finding classification, and final context validation.
+- `[Evidence]` Persisted complete stdout and stderr for every async command, including small streams, under collision-safe `captures/command-NNN/attempt-NNN/{stdout,stderr}.log` identities; retries remain distinct while bounded result tails and complete pipeline stdin behavior stay unchanged.
+- `[Evidence]` Added terminal `review-evidence.json` manifests mapping stable command/stage occurrences and repeated branches to prompts, byte-exact attempt files, byte counts, truncation, exit state, semantic marker acceptance, recipe context, and inherited/explicit model policy; manifests update during execution and finish with aligned `done`/`failed` status.
+- `[Inspector]` Exposed owned review-evidence manifests and referenced capture paths through existing `inspect run:<id> view=files|artifacts` responses, bounding command entries by `lines` and reporting total/truncated counts without adding a public verb or bypassing session ownership checks.
+- `[Review Evidence]` Injected stable prior-stage `ACTOR_EVIDENCE_REF` entries into verifier, merger, judge, and normalizer prompts; normalized reports now retain auditable reviewer/downstream references, terminal manifests record cited and missing sources, and a report claiming `complete` fails closed when any required reviewer, verifier, merger, or judge reference is absent.
+- `[Review Dogfood]` Expanded deterministic provenance coverage across small, spilled, UTF-8, retry, parallel, semantic-marker rejection, partial-quorum, and terminal paths; the packaged review fixture now reconstructs reviewer branch identity, accepted/rejected counts, rejected raw output, downstream source references, final degraded status, and exactly-once capture files solely from retained run state.
+- `[Review]` Completed the auditable six-lens `hardening-review-040` run with all 14 stages accepted and every required evidence reference retained. Re-curated confirmed release blockers covering canonical alias locks, live owner-mismatch reuse, symlink-cwd identity, public custom state directories, complete large-pipeline stdin, exact evidence markers, semantic notification alignment, interrupted evidence finalization, and missed terminal replay; kept the cancellation timing race and native platform gaps explicitly unconfirmed.
+- `[Locking]` Keyed mutation locks by filesystem identity: existing targets or nearest existing ancestors are resolved through native `realpath`, nonexistent suffixes are preserved, Windows identities are case-normalized, and stale lock directories are reclaimed only after their persisted owner PID is proven dead. Added a cross-process real-parent/symlink-parent serialization regression.
+- `[Run Safety]` Made live `owner_mismatch` state reuse fail closed in both preflight and state-directory preparation, including terminal-result timing windows; tampered process identity can no longer clear/reuse an occupied run directory while its original runner remains alive.
+- `[Process Identity]` Canonicalized existing launch cwd paths through native `realpath` before matching the runner's process proof, with Windows case normalization; Linux integration now proves a symlinked launch cwd retains a valid, controllable process identity while injected Darwin/Windows contracts remain intact.
+- `[Public Boundary]` Removed lifecycle `state_dir` from `register_tool`, persisted/co-located recipe normalization, generated schemas, result details, serialization, recipe-reference resolution, and prompt copy. Legacy stored values are ignored, and registered async tools now always launch under the runtime-owned run root where `run:<id>` inspection, messaging, indexing, and retention agree.
+- `[Pipeline Dataflow]` Downstream sequence commands now receive complete spilled stdout from sequential and parallel producers while model-facing output, branch reports, and diagnostics remain bounded. Missing or unreadable spill files still fail closed; exact >1 MiB consumer-count regressions cover both composition shapes.
+- `[Review Evidence]` Tightened semantic acceptance to require `ACTOR_REVIEW_RESULT` as the exact first non-whitespace line in both execution policy and persisted evidence manifests; prefixed markers such as `ACTOR_REVIEW_RESULT_BOGUS` now fail with code 65 and remain rejected evidence.
+- `[Review Notifications]` Applied semantic output acceptance before async command accounting, so rejected code-zero review output is consistently recorded as code 65 in `command.done`, terminal progress failures, evidence, and outbox summaries, with follow-up delivery and error severity instead of a false success notification.
+- `[Interrupted Evidence]` Review evidence records now exist before command launch and are finalized as `cancelled` or `killed` by lifecycle control even when the command never returns. Async captures create byte-exact stdout/stderr files at attempt start, preserving small partial streams as well as spills; manifests retain interruption status, signal-derived effective exit code, capture bytes, and semantic interruption state.
+- `[Terminal Delivery]` Terminal actor notifications now use Pi steering with `triggerTurn: true`: busy agents receive completion at the next safe tool boundary and idle agents start a normal turn without a racy manual idle check. Unhandled owned terminal runs retry during same-runtime and replacement reconciliation until `terminal-handled.json` is written after a successful send, without replaying historical outbox traffic. Delivery is honestly at-least-once: a process crash between send and marker persistence may duplicate a notification.
+- `[Cancel Race]` Authoritative terminal result/control state now short-circuits cancel/kill before process-identity probing because no signal will be sent. This removes transient `unsupported proof` classifications while preserving fail-closed identity checks for running processes and derived `exited` states; a 30-run completion/cancel stress regression consistently returns `not running`.
+- `[Release Review]` Completed the final six-lens hardening review with all branches and downstream stages successful and durable evidence under `hardening-review-040-final`. The review blocked release on five bounded correctness findings: large marked-output acceptance, cross-process registry collision state, live aged start locks, same-runtime terminal-delivery retry, and disappearing-run inspection tolerance. Per operator direction, no further reviewer runs are required before release; fixes use local regressions and validation.
+- `[Large Review Output]` Semantic marker acceptance now reads byte-complete captured stdout when the bounded tail is truncated, while returned model-facing output remains bounded. Foreground and async regressions prove valid `ACTOR_REVIEW_RESULT` output above 1 MiB succeeds and persists accepted evidence metadata.
+- `[Registry Collision]` Same-name registration now rereads authoritative recipe state while holding the canonical cross-process mutation lock instead of trusting a process-local tool map. A sibling-process regression proves exactly one create wins and the loser receives the explicit `update=true` collision error without overwriting the recipe.
+- `[Start Lock Ownership]` Run-start locks now persist the starter's process identity and aged locks are reclaimed only when the recorded PID is proven dead. Live, mismatched, unavailable, and malformed ownership proofs remain protected regardless of age; regressions cover both live-owner retention and dead-owner recovery.
+- `[Inspection TOCTOU]` Runtime triage now treats a run that disappears between inventory and status read as a skipped stale entry instead of failing the entire inspection. Injectable inventory/status ports provide a deterministic disappearance regression without weakening ownership filtering for surviving runs.
+- `[Package Entrypoint]` Added a named compiled wrapper at `dist/pi-actors/index.js` and pointed package metadata to it, preserving the compiled runtime while making Pi's extension list identify `pi-actors` instead of the anonymous parent label `dist`.
+- `[Release]` Updated package, lockfile, bundled skill metadata, compiled assets, and changelog identity for the release candidate; validation, conformance, package dry-run, diff checks, and context reconciliation are green.
+
+## 0.39.0: Actor Kernel Welcome Refresh
+
+- `[Docs]` Reworked the root README as a product/onboarding entrypoint for the local actor kernel, with clearer positioning, first-run path, feature showcase, recipe-memory model, address/message examples, and practical surface-selection guidance. Impact: new operators can understand when to use `spawn`, `message`, `inspect`, recipes, rooms, and artifacts without reading deep implementation docs first.
+- `[Context]` Added a durable README standard to `AGENTS.md` so future edits preserve the RhythmE/product entrypoint shape while keeping the practical capability catalogue visible.
+- `[Release]` Bumped package metadata to `0.39.0` for the onboarding refresh minor release.
+
 ## 0.38.1: Windows Recipe ACL Hotfix
 
 - `[Registry]` Replaced POSIX mode-bit recipe-root writability checks on Windows with ACL-aware diagnostics, avoiding false `world-writable` and `group-writable` startup warnings from Node's NTFS mode emulation while still flagging broad Windows write grants.

package/README.md

@@ -1,54 +1,48 @@
 # pi-actors
 
-> Local Actor Kernel for Pi
-
 ![Actors](./banner.jpg)
 
-`pi-actors` turns trusted local programs, scripts, recipes, services, pipelines, and sub-agents into addressable actors that agents can spawn, message, inspect, and compose.
+**Local actor kernel for Pi.**
+
+`pi-actors` turns trusted local programs, scripts, services, pipelines, recipes, and sub-agents into addressable actors that Pi can spawn, steer, inspect, and reuse. It is the bridge between one-shot shell commands and durable local capability memory.
 
-It is not just a command registry. A tool is a verb. An actor is a noun with time: address, lifecycle, state, logs, mailbox, artifacts, and an interaction contract.
+A command is a moment. An actor is a local thing with time: address, lifecycle, logs, mailbox, messages, artifacts, state, and an interaction contract.
 
 ```text
-program / process / service
+trusted local capability
 → command template
-→ actor recipe
+→ recipe
 → spawn
 → run:<id>
 → message / inspect / artifacts
+→ reusable tool memory
 ```
 
-## Core Contract
+## Why it exists
 
-`pi-actors` compresses local agent orchestration to three durable verbs:
+Agents are good at reasoning, but they should not reconstruct the same fragile background command every time a task becomes long-lived. `pi-actors` gives Pi a local-first actor layer: work can outlive the current turn, expose bounded state, receive typed instructions, produce artifacts, and graduate into persistent recipe-backed tools under `~/.pi/agent/recipes`.
 
-```text
-spawn    create an addressable actor
-message  send one typed envelope to one address
-inspect  intentionally read state, logs, messages, contracts, or artifacts
-```
+Use it when the correct shape is not "run a command and forget" but "start a local capability, keep its handle, and come back with intent."
 
-Everything else is an adapter until proven otherwise.
-
-Use `spawn` when work may outlive the current turn. Use `message` when the actor should be steered rather than restarted. Use `inspect` at decision points, after actor follow-ups, or during diagnosis. For non-trivial actor use, load the bundled `actors` skill before improvising. Do not build polling loops as the default coordination pattern.
+## The promise
 
-## When To Use Actors
+- **Spawn long-lived work without shell gymnastics.** Start services, workers, subagents, fanouts, and pipelines as named actor runs.
+- **Steer instead of restarting.** Send typed `message` envelopes to runs, tools, branches, rooms, sessions, or coordinators.
+- **Inspect intentionally.** Read status, logs, messages, mailboxes, artifacts, registry health, and room rosters at decision points.
+- **Promote what works.** Persist trusted command templates and recipes as durable local tools in `~/.pi/agent/recipes`.
+- **Keep orchestration local.** State is file-backed, inspectable, operator-owned, and designed for Pi sessions rather than a cloud broker.
 
-Use actor-mode instead of ad hoc shell backgrounding when work is:
+## Core verbs
 
-- Long-running or likely to outlive this agent turn.
-- Stateful, resumable, or something you will need to inspect later.
-- Expected to produce named artifacts or follow-up messages.
-- A service, worker, media process, fanout, subagent, or pipeline.
-- A repeatable local capability worth promoting into recipe memory.
+`pi-actors` compresses local orchestration into three public verbs:
 
-Keep ordinary foreground tools for short checks such as `rg`, `ls`, quick tests, and one-shot transforms. The golden path is:
+| Verb | Use it when | Result |
+| --- | --- | --- |
+| `spawn` | Work may outlive this turn, fan out, produce artifacts, or need later steering | A `run:<id>` actor with lifecycle and state |
+| `message` | An existing actor should be continued, stopped, approved, killed, or given scoped input | One typed envelope delivered to one address |
+| `inspect` | You need evidence before deciding the next step | Bounded views of status, logs, messages, registry, artifacts, or rooms |
 
-```text
-create actor        -> spawn
-steer actor         -> message
-read state/results  -> inspect
-repeatable pattern  -> promote to recipe/tool memory
-```
+Everything else is an adapter until proven otherwise.
 
 ## Install
 
@@ -62,28 +56,53 @@ Or from git:
 pi install git:github.com/llblab/pi-actors
 ```
 
-The npm package is dist-first for JavaScript-only runtimes: default Pi metadata points at compiled `dist/` entrypoints and mirrored runtime assets. Source TypeScript and source skills remain in the package for TypeScript-native runtimes through optional source metadata. When the source checkout is auto-discovered as an extension, it also contributes its co-located `skills/` directory during Pi resource discovery so the actors and swarm skills travel with the extension.
+The npm package is dist-first for JavaScript-only runtimes: Pi metadata points at the named compiled entrypoint `dist/pi-actors/index.js` plus mirrored runtime assets, so extension discovery identifies `pi-actors` rather than an anonymous `dist` directory. Source TypeScript and source skills remain packaged for TypeScript-native or checkout-based runtimes.
+
+## First run: actor mode in one minute
+
+Use actors instead of ad hoc shell backgrounding when work is long-running, stateful, resumable, artifact-producing, service-like, parallel, agentic, or worth saving.
+
+Start an actor:
+
+```text
+spawn template="sleep 30 && echo done" as=run:demo
+```
+
+Inspect it when you need evidence:
+
+```text
+inspect target=run:demo view=status
+inspect target=run:demo view=tail lines=40
+```
+
+Steer it with a typed message:
+
+```text
+message to=run:demo type=control.kill body=stop
+```
+
+For non-trivial actor workflows, load the bundled `actors` skill before improvising. For multi-model review or delegated audit, load the bundled `swarm` skill.
 
-## Address Surface
+## Address surface
 
-Core actor addresses stay small:
+Core addresses stay small:
 
 ```text
 run:<id>      one detached actor run
 tool:<name>   executable registered tool actor
 ```
 
-Advanced coordination/debug addresses are available when a recipe or workflow needs them:
+Advanced addresses exist for coordination and diagnostics:
 
 ```text
 branch:<run>/<branch>  branch-local worker endpoint
-room:<run>             group-message timeline plus roster for one run
-coordinator            compatibility alias for the current session coordination path
+room:<run>             run-local group timeline plus roster
+coordinator            current session coordination path
 session:               current session actor surface
-session:all            cross-session inventory surface for diagnostics
+session:all            cross-session diagnostics inventory
 ```
 
-Actor messages use one envelope shape:
+Messages use one envelope shape:
 
 ```json
 {
@@ -98,9 +117,24 @@ Actor messages use one envelope shape:
 }
 ```
 
-Routing is inferred from `to`, actor ownership, and runtime policy. Recipes should expose semantic message types, not transport knobs.
+Routing comes from `to`, actor ownership, and runtime policy. `type` describes intent. Recipes should expose semantic message types instead of transport knobs.
 
-## Golden Path
+## Feature showcase
+
+| Surface | What it gives you | Typical move |
+| --- | --- | --- |
+| Command templates | Portable command graphs with placeholders, defaults, guards, retries, parallel nodes, recovery, and timeouts | Wrap a trusted local executable without writing a bespoke tool |
+| Recipes | JSON/Markdown capability specs with metadata, args, defaults, imports, mailbox contracts, artifacts, and async mode | Save a known-good local workflow as reusable muscle memory |
+| Async runs | File-backed detached lifecycle, logs, progress, output, cancellation, artifacts, and durable terminal steering notifications | Let model work, media jobs, services, or pipelines continue after the turn |
+| Message protocol | Typed envelopes across run, tool, branch, room, coordinator, and session targets | Continue, approve, kill, or route work without restarting actors |
+| Rooms and rosters | Run-local group timeline with actor join/leave, contacts, previews, and branch-aware delivery | Coordinate multiple subagents under one visible run |
+| Registry and recipe doctor | Discovered tools, overrides, drafts, invalid recipes, and advisory risk labels | Audit local capability memory before using or promoting it |
+| Draft promotion | Captured ad hoc spawn patterns can become explicit recipes after operator approval | Turn successful improvisation into durable local tools |
+| Review/swarm recipes | Maintained packaged pipelines with preflight, marked semantic evidence, quorum knobs, model/thinking inheritance, one-turn prompt-file transport, and diagnostics | Delegate reviews without rebuilding fanout commands |
+| Actor inspector | Compact TUI/debug views for active actor coordination, unread branch inboxes, room messages, and attention markers | Watch only the actor traffic that matters right now |
+| Packaged recipe QA | Installed-package-safe checks for helper paths, mailbox contracts, platform scope, artifacts, and recipe structure | Keep shipped actor components executable and diagnosable |
+
+## Golden path: from local workflow to actor memory
 
 Create a reusable async actor recipe in the user recipe root:
 
@@ -122,15 +156,15 @@ cat > ~/.pi/agent/recipes/docs_review.json <<'JSON'
 JSON
 ```
 
-Because it lives under `~/.pi/agent/recipes/`, the file becomes a persistent agent tool by location. The filename is the tool id. `{current_model}` and `{current_thinking}` inherit the selected Pi session model/thinking level; pass `model=...` or `thinking=...` only when a run should intentionally diverge. Run status/progress and terminal follow-ups include `model_policy` provenance so inherited, explicit, and unresolved policy choices stay inspectable.
+Because it lives under `~/.pi/agent/recipes/`, the filename becomes the tool id. `{current_model}` and `{current_thinking}` inherit the active Pi session policy; pass explicit values only when a run should intentionally diverge.
 
-Start it:
+Run it:
 
 ```text
 docs_review scope="README.md" run_id=docs_review
 ```
 
-Inspect only when there is a reason:
+Inspect it:
 
 ```text
 inspect target=tool:pi-actors view=triage
@@ -140,79 +174,33 @@ inspect target=run:docs_review view=messages
 inspect target=run:docs_review view=mailbox
 ```
 
-Steer it through messages:
+Steer it:
 
 ```text
 message to=run:docs_review type=control.continue body=continue
 message to=run:docs_review type=control.kill body=stop
 ```
 
-## Group Messaging And Roster
-
-Every spawned run can have advanced group messaging at `room:<run>`. Treat this as a run-local timeline plus roster for coordinated actors, not as a core chat/broker concept.
-
-Actors can join, post, leave, and discover peers:
-
-```text
-message \
-  to=room:review \
-  from=branch:review/security \
-  type=actor.join \
-  summary="Security reviewer joined" \
-  body='{"role":"reviewer","caps":["security-review"],"claim":"Review auth boundary risks"}'
-```
-
-Inspect group messages and roster intentionally:
-
-```text
-inspect target=room:review view=status
-inspect target=room:review view=previews
-inspect target=room:review view=roster
-inspect target=room:review view=contacts
-inspect target=room:review view=messages
-```
-
-Group posts require a same-run sender, so unrelated runs do not pollute the roster. Direct messages and group messages use the same envelope; only the address changes. Direct `branch:<run>/<branch>` messages are private: they are forwarded through the parent run mailbox and recorded in the recipient branch inbox for worker protocols that consume queued branch work. For selected-recipient multicast, send to `room:<run>` with `metadata.recipients` set to same-run `branch:<run>/<branch>` addresses; this keeps one visible transcript entry while forwarding branch-targeted copies.
-
-## Actor Inspector
+## Recipe memory model
 
-The terminal actor inspector is hidden by default. When opened without an explicit size, it shows 12 log rows by default. Use it when async actors are actively coordinating:
-
-```text
-/actors-inspector-toggle
-/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, branch-local inbox previews, stable event ids in selected-message details, 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. Rows with `metadata.requires_response=true` show a `!` attention marker. `/actors-inspect <number>` opens the selected row as a full-message view and marks it read for the current session filter; 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
-
-The persistent tool surface is file-discovered:
+The persistent tool surface is location-derived:
 
 ```text
 ~/.pi/agent/recipes/*.json
 ~/.pi/agent/recipes/*.md
 ```
 
-That directory is operator-managed executable memory.
-
 Rules:
 
-- User recipes in `~/.pi/agent/recipes/` are tools by location;
-- Recipe filenames define tool ids;
-- User recipes override same-name lower-priority recipes;
-- Same-id JSON recipes shadow Markdown recipes in the same priority layer;
-- Packaged recipes are standard-library components, not automatically installed operator policy;
-- Draft recipes in `~/.pi/agent/recipes/drafts/` are replayable memory, not active tools;
+- User recipes in `~/.pi/agent/recipes/` are tools by location.
+- Recipe filenames define tool ids.
+- User recipes override same-name lower-priority recipes.
+- Same-id JSON recipes shadow Markdown recipes in the same priority layer.
+- Packaged recipes are standard-library components, not automatically installed operator policy.
+- Draft recipes in `~/.pi/agent/recipes/drafts/` are replayable memory, not active tools.
 - `register_tool` creates, updates, lists, deletes, or explicitly promotes draft recipe files through the normal agent interface.
 
-Example foreground tool:
+Register a foreground tool:
 
 ```text
 register_tool name=transcribe_audio \
@@ -220,7 +208,7 @@ register_tool name=transcribe_audio \
   template="~/bin/transcribe {file:path} {lang=ru} {model:string}"
 ```
 
-Example recipe-backed tool:
+Register a recipe-backed tool:
 
 ```text
 register_tool name=docs_review \
@@ -229,68 +217,69 @@ register_tool name=docs_review \
   args="scope:path,model:string"
 ```
 
-Promote a successful captured draft only after an explicit operator decision:
+Promote a captured draft only after explicit operator approval:
 
 ```text
 register_tool name=docs_review draft=~/.pi/agent/recipes/drafts/spawned-run.json
 ```
 
-Promotion validates the draft, writes `~/.pi/agent/recipes/<name>.json`, preserves the draft, and rejects collisions unless `update=true` is supplied.
-
-Inspect the discovered registry:
+Inspect the registry:
 
 ```text
 inspect target=recipes view=status
 inspect target=recipes view=summary verbose=true
+inspect target=tool:pi-actors view=triage
 ```
 
-## Command Templates
+## Command templates
 
-A command template is the portable launch substrate. It can be a string, a sequence, or a composed graph.
+A command template is the launch substrate. It can be a string, a sequence, or a composed graph.
 
 Templates support:
 
-- Named placeholders: `{file}`, `{model}`, `{prompt}`;
-- Compact types: `string`, `path`, `int`, `number`, `bool`, `enum(a,b)`;
-- Defaults: `{lang=ru}`, `{dry_run:bool=true}`;
+- Named placeholders such as `{file}`, `{model}`, `{prompt}`;
+- Compact types such as `string`, `path`, `int`, `number`, `bool`, `enum(a,b)`;
+- Defaults such as `{lang=ru}` and `{dry_run:bool=true}`;
 - Fallback and small ternary forms;
 - Sequences with stdin flow;
 - Parallel nodes;
-- Retries, recovery, failure policy, delays, and guarded execution;
+- Retries, recovery, failure policy, delays, guards, and timeouts;
 - Async run values such as `{run_id}`, `{state_dir}`, `{actor_address}`, `{default_room}`, and `{communication_file}`.
 
-The template owns execution shape. The recipe owns saved metadata, defaults, imports, mailbox, and artifacts. JSON is the canonical precise recipe format; Markdown recipes use frontmatter plus fenced `template`/`json recipe` blocks for literate authoring and compile into the same model. The run actor owns detached lifecycle, state, messages, cancellation, and inspection. File-backed async recipes also provide child `pi -p` actors with a bounded JSONL recipe context bundle by default, including raw entry/import recipe records and a `"you_are_here": true` marker for the recipe node that launched the child; the runner materializes child prompts under `prompts/` and invokes Pi with `@file` arguments. Set `"actor_context": false` or `"off"` in a recipe to suppress that context for minimal prompts.
+The template owns execution shape. The recipe owns saved metadata, defaults, imports, mailbox, artifacts, and async launch policy. The run actor owns detached lifecycle, state, messages, cancellation, and inspection.
 
-## Recipe Library
+## Packaged recipe library
 
 Packaged recipes live under `recipes/` and helper scripts live under `scripts/`.
 
 The library includes:
 
-- Sub-agent launchers;
+- Subagent launchers;
 - Review, critic, planner, verifier, merger, judge, normalizer, and artifact atoms;
 - Quorum and lens-style pipelines;
 - Repo-health, release-summary, research-synthesis, development-tasking, docs-maintenance, and room-swarm pipelines;
 - Coordinator-locker and actor-message utilities;
 - Local music-player actor recipe.
 
-Packaged recipes are building blocks. Copy them into `~/.pi/agent/recipes/` or register tools that point at them when they should become durable operator-facing capabilities.
-
-## When To Use What
-
-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. 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.
+Packaged recipes are building blocks. Use `spawn file=<recipe>` for maintained packaged pipelines before rebuilding equivalent shell commands. Copy or wrap them into `~/.pi/agent/recipes/` only when they should become durable operator-facing tools.
 
-Use `room:<run>` when multiple actors in the same run need shared context, roster discovery, or group-visible progress.
+## Choosing the right surface
 
-Use artifacts when outputs should survive context compression.
+| If the work is... | Prefer... |
+| --- | --- |
+| Short, bounded, and foreground | Ordinary tools or registered foreground tools |
+| Long-running, service-like, parallel, agentic, artifact-producing, or controllable | `spawn` / async recipe |
+| Already running and needs new input | `message` |
+| Unclear, failing, or ready for a decision | `inspect` |
+| A multi-actor collaboration under one run | `room:<run>` plus branch addresses |
+| A useful output that should survive context compression | Artifacts |
+| A repeated local workflow | Recipe/tool memory |
 
-Use mailbox declarations when an actor has a stable conversational surface.
+When a directly spawned inline/ad hoc actor or a recipe outside the user recipe root completes successfully, `pi-actors` may include a promotion suggestion in its terminal steering notification. The agent should ask first and never auto-save.
 
-## Platform Support
+## Platform support
 
-Core actor state, inspection, foreground tools, and basic async runs are portable Node.js behavior. Run-local messaging and stop/kill use a platform adapter under the same `message` API: Unix-compatible recipes can use their existing local control endpoint, while native Windows recipes can expose a Windows-native endpoint in run state. Some packaged scripts still depend on Unix tools and are WSL/Linux/macOS-only until migrated; their public recipe surface should stay `spawn` / `message` / `inspect` either way.
+Core actor state, inspection, foreground tools, and basic async runs are portable Node.js behavior. Run-local messaging and stop/kill use platform adapters under the same `message` API.
 
 | Surface | Linux/macOS/WSL | Native Windows |
 | --- | --- | --- |
@@ -303,13 +292,13 @@ Core actor state, inspection, foreground tools, and basic async runs are portabl
 
 Packaged recipes should prefer mailbox/wake behavior for portable control. Recipes that require FIFO, Unix shell tools, or platform-specific media backends should make that limitation visible in docs or diagnostics before launch.
 
-## Safety Boundary
+## Safety boundary
 
 `pi-actors` is local-first, not sandbox-first.
 
 Commands execute directly without shell evaluation where possible, but trusted executables still run with the same system permissions as Pi. Only register commands, scripts, recipes, and paths you trust.
 
-High-risk templates such as shells, interpreter eval modes, and broad filesystem mutation may surface warnings, but the runtime is not a security boundary. Recipe doctor also exposes advisory labels like `risk.shell`, `risk.eval`, `risk.destructive_fs`, `risk.network`, and `risk.external_side_effect` for operator review.
+High-risk templates such as shells, interpreter eval modes, network access, external side effects, and broad filesystem mutation may surface warnings, but the runtime is not a security boundary.
 
 Prefer:
 
@@ -317,17 +306,17 @@ Prefer:
 - Explicit paths;
 - Typed args;
 - Bounded timeouts for bounded work;
-- Explicit tool allowlists for sub-agents;
+- Explicit tool allowlists for subagents;
 - Deterministic utility recipes for filesystem writes;
 - Human approval for destructive or external side effects.
 
-## Non-Goals
+## Non-goals
 
-`pi-actors` is NOT:
+`pi-actors` is not:
 
 - A generic workflow DSL;
 - A remote agent interoperability protocol;
-- A heavyweight broker or chat subsystem;
+- A heavyweight broker;
 - A sandbox;
 - A facade that hides logs, artifacts, ownership, or local side effects;
 - A polling-first async runner.

package/dist/index.js

@@ -30,7 +30,7 @@ export default function toolRegistryExtension(pi) {
             sendStop: (candidate) => AsyncRuns.sendRunMessage(candidate.stateDir, "stop"),
         });
     };
-    const updateRunUi = (ctx, notify = false) => {
+    const updateRunUi = (ctx, notify = false, terminalOnly = false) => {
         const ownerId = getRunOwnerId(ctx);
         const snapshot = Observability.readRunUiSnapshot(runUi, ownerId);
         ctx.ui.setStatus("zz-pi-actors-runs", snapshot.status ? ctx.ui.theme.fg("dim", snapshot.status) : undefined);
@@ -62,7 +62,9 @@ export default function toolRegistryExtension(pi) {
         retireCandidateRuns(ctx, snapshot.summary);
         Observability.deliverRunTransitionNotifications(snapshot.transitions, notificationSink);
         Observability.pruneRunUiObservationState(runUi, snapshot);
-        Observability.deliverRunOutboxNotifications(snapshot.outboxEvents, notificationSink);
+        if (!terminalOnly) {
+            Observability.deliverRunOutboxNotifications(snapshot.outboxEvents, notificationSink);
+        }
     };
     const closeRunWatchers = () => {
         runWatcher.close();
@@ -126,7 +128,7 @@ export default function toolRegistryExtension(pi) {
         activeRunContext = ctx;
         await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
         runtime.loadTools(ctx);
-        updateRunUi(ctx);
+        updateRunUi(ctx, true, true);
         closeRunWatchers();
         recipeReload.close();
         runWatcher.refresh();
@@ -178,7 +180,7 @@ export default function toolRegistryExtension(pi) {
     Pi.registerToolDefinitions(pi, Tools.createCoreActorToolDefinitions({
         configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
         getActiveTools: () => pi.getActiveTools(),
-        getRuntimeTool: (name) => actorToolDefinitions.get(name),
+        getRuntimeTool: (name) => Tools.resolveActiveRuntimeTool(name, runtime.getTools(), (activeName) => actorToolDefinitions.get(activeName)),
         registryRuntime: runtime,
         setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
     }).map(withCurrentThinkingContext));