@llblab/pi-actors 0.12.9 → 0.12.13

package/BACKLOG.md

@@ -6,7 +6,7 @@ Continue progressive component/pipeline expansion in small validated slices; rea
 
 - Plan organic universal communication primitives.
   - Priority: High.
-  - Status: The actor-like model is empirically useful: async runs can emit follow-up messages upward, coordinators can send run-local commands downward, multiple parallel runs can progress independently, and recipes no longer need sleep-poll coordination. The design is captured in `docs/actor-messages.md`: `spawn`, `message`, and `inspect` as concentrated verbs; addressed actors; one symmetric message envelope; mailbox `accepts`/`emits`; and adapter mappings from runtime async actions. Initial implementation landed pure actor address/message normalization plus public `spawn`, `message`, and `inspect` tools for `run:<id>` actors; `spawn` accepts state/artifact metadata, `message` routes `run:<id>` → `coordinator` envelopes into the runtime attention path, `message` can invoke `tool:<name>` actors, all packaged async recipes declare mailbox metadata, `inspect view=mailbox` exposes recipe mailbox contracts from run metadata, and recipe-authored messages now use envelope-aligned `type` fields with deterministic validated wrapping available through `utility-actor-message`. Remaining work is to absorb remaining runtime async action surfaces into the actor vocabulary instead of preserving a parallel public API.
+  - Status: The actor-like model is empirically useful: async runs can emit follow-up messages upward, coordinators can send run-local commands downward, multiple parallel runs can progress independently, and recipes no longer need sleep-poll coordination. The design is captured in `docs/actor-messages.md`: `spawn`, `message`, and `inspect` as concentrated verbs; addressed actors; one symmetric message envelope; mailbox `accepts`/`emits`; and adapter mappings from runtime async actions. Initial implementation landed pure actor address/message normalization plus public `spawn`, `message`, and `inspect` tools for `run:<id>` actors; `spawn` accepts state/artifact metadata, `message` routes `run:<id>` → `coordinator` and `run:<id>` → `session:<id>` envelopes into the runtime attention path, `message` can invoke `tool:<name>` actors, `inspect target=tool:<name>` exposes registered tool actor contracts, `inspect target=coordinator` exposes current-session run inventory, all packaged async recipes declare mailbox metadata, `inspect view=mailbox` exposes recipe mailbox contracts from run metadata, recipe-authored messages now use envelope-aligned `type` fields with deterministic validated wrapping available through `utility-actor-message`, run termination now accepts actor-native `control.stop`/`control.cancel`/`control.kill` aliases while preserving legacy `runtime.*` compatibility, async command events preserve full argv details while keeping coordinator summaries bounded, and async-run operations recommendations now emit structured `message`/`inspect` objects instead of shell-like suggestion strings. Remaining work is to absorb remaining runtime async action surfaces into the actor vocabulary instead of preserving a parallel public API.
   - Scope: Design and implement a small semantic layer around addressed messages and actors while preserving low-level primitives as adapters where useful. Candidate top-level concepts are `spawn` for creating an actor/run from a recipe or template, `message` for sending typed messages to any address, and `inspect` for intentional observation/debugging. Candidate addresses include `run:<id>`, `branch:<run>/<branch>`, `coordinator`, `session:<id>`, `tool:<name>`, and future chat/session endpoints. Candidate message fields include `to`, `from`, `type`, `summary`, `body`, `reply_to`, `correlation_id`, and `metadata`.
   - Contract direction: Unify “send down” and “messages up” as one message model. `to: run:<id>` routes to a run mailbox, `to: coordinator` routes to the coordinator attention path, and branch/tool/session addresses can be layered over the same semantic envelope. Recipes should declare mailbox capability (`accepts`, `emits`) without exposing FIFO/outbox mechanics or delivery policy as their public interface.
   - Design gates: Breaking changes are allowed in this phase, so compress concepts instead of preserving accidental surfaces. Consolidate duplicated lifecycle/message/event APIs into a concentrated protocol with the fewest durable nouns and verbs that still explain the system. Duplex communication should be symmetric where the domain is symmetric: the same message envelope should represent run→coordinator, coordinator→run, run→run, branch→parent, and parent→branch traffic, with routing/transport hidden below it. Keep command templates as the portable synchronous execution graph; keep recipe files as semantic definitions; avoid leaking transports into public args; make polling an explicit diagnostic operation, not an example path; replace runtime action names with the actor API rather than preserving parallel concepts.
@@ -14,18 +14,19 @@ Continue progressive component/pipeline expansion in small validated slices; rea
 
 - Progressively increase component parameterization and higher-level recipe composition.
   - Priority: High.
+  - Status: `subagent-tools` and `subagents-prompts` now align with the common subagent policy knobs for thinking, tools, model, and output format.
   - Scope: Iteratively strengthen atom/component recipes with public policy knobs such as model pools, stage-specific models, thinking, tool policy, output format, evidence policy, risk policy, source policy, artifact paths, mailbox contract, handoff format, resume/continuity policy, and validation gates; add higher-level component recipes that compose existing atoms into reusable coordinator patterns.
   - Exit: Each iteration adds or refines at least one atom-level parameterization surface and at least one composed recipe/pipeline, with packaged recipe import validation passing and docs/changelog updated.
 
 - Add another task-first high-level pipeline candidate from the design map.
   - Priority: Medium.
-  - Status: `pipeline-release-readiness`, `pipeline-repo-health`, `pipeline-async-run-ops`, `pipeline-docs-maintenance`, and `pipeline-media-library` landed. `pipeline-media-library` required playlist output-mode parameterization, then reused playlist and artifact-report cells.
+  - Status: `pipeline-release-readiness`, `pipeline-repo-health`, `pipeline-async-run-ops`, `pipeline-docs-maintenance`, `pipeline-media-library`, and `pipeline-artifact-bundle` landed. `pipeline-media-library` required playlist output-mode parameterization, then reused playlist and artifact-report cells. `pipeline-artifact-bundle` reused artifact-write, artifact-manifest, validation, manifest-write, and actor-message cells.
   - Scope: Reassess `docs/task-first-recipes.md` for the next high-value task cell, then implement only the minimum missing cells needed for that task.
   - Exit: Another task-first pipeline lands with docs, package validation, and a note about which missing atoms/utilities it required.
 
 - Grow the standard recipe library with safer structured utility transforms.
   - Priority: Low.
-  - Status: `utility-artifact-manifest` landed for machine-readable artifact metadata; `utility-artifact-write` landed for deterministic writes of accepted prepared artifacts; `utility-package-summary` landed for bounded package metadata used by release/repo-health flows; `utility-validate-recipe` landed with a dedicated recipe validator script.
+  - Status: `utility-artifact-manifest` landed for machine-readable artifact metadata; `utility-artifact-write` landed for deterministic writes of accepted prepared artifacts; `utility-package-summary` landed for bounded package metadata used by release/repo-health flows; `utility-validate-recipe` landed with a dedicated recipe validator script; `utility-run-ops-snapshot` landed for async-run summaries, event tails, and operator-gated cleanup recommendations.
   - Scope: Continue beyond listing/extraction utilities toward structured transforms for artifact packaging, report normalization, release prep, and machine-readable summaries. Keep helpers generic, parameterized, and justified by repeated recipe needs.
   - Exit: A future utility slice adds another structured transform only when a repeated recipe need appears; otherwise treat the current helper-backed utility surface as sufficient.
 

package/CHANGELOG.md

@@ -1,6 +1,32 @@
 # Changelog
 
-## Unreleased
+## 0.12.13: Structured Run Operations Recommendations
+
+- `[Recipe Utilities]` Changed `utility-run-ops-snapshot` recommendations from shell-like suggestion strings to structured `message` and `inspect` call objects. Impact: async-run operations reports now preserve the actor API shape directly and avoid reintroducing command-string parsing into coordinator handoffs.
+
+## 0.12.12: Async Command Summary Hygiene
+
+- `[Observability]` Kept async `command.done` summaries bounded while preserving full argv-shaped command details in event payloads. Impact: long prompted fanouts keep diagnostic fidelity without flooding coordinator follow-ups with huge command lines.
+
+## 0.12.11: Recipe Import Diagnostics Hotfix
+
+- `[Template Recipes]` Added regression coverage proving imported recipe nodes execute correctly under a repeated parallel parent (`imports` + `repeat` + object `template`). Impact: the suspected composition blocker is now guarded as supported behavior instead of relying on manual smoke interpretation.
+- `[Observability]` Expanded command details in foreground execution results and async `command.start`/`command.done` events from executable-only labels to full argv-shaped launch strings. Impact: failed fanout branches no longer appear as misleading `pi && pi && ...` summaries when the real command was `pi -p --model ...` with a long prompt.
+- `[Spawn]` Allowed the public `spawn` schema to accept inline object command-template configs, not only strings and arrays. Impact: agents can launch object-form templates with `parallel`, `repeat`, `failure`, and nested `template` directly through `spawn` as documented.
+
+## 0.12.10: Actor Ownership and Recipe Operations
+
+- `[Actor Messages]` Added actor-native `control.stop`, `control.cancel`, and `control.kill` handling for run termination while retaining `runtime.cancel` and `runtime.kill` as compatibility aliases. Impact: public examples can use the same control-message vocabulary declared by recipe mailboxes instead of preserving runtime action names.
+- `[Actor Messages]` Added `inspect target=tool:<name>` support for registered tool actor status/schema contracts. Impact: tool actors can now be intentionally observed through the same actor vocabulary used to invoke them with `message to=tool:<name>`.
+- `[Recipe Library]` Added `pipeline-artifact-bundle`, a task-first handoff pipeline that composes optional validation, deterministic artifact writing, machine-readable manifest generation, deterministic manifest writing, and an actor-message handoff. Impact: callers who explicitly want filesystem writes can produce paired artifact and manifest paths as one reusable bundle workflow.
+- `[Component Recipes]` Aligned `subagent-tools` and `subagents-prompts` with the common subagent policy knobs for `model`, `thinking`, `tools`, and `output_format`. Impact: prompt launchers and prompt fanout can be tuned through the same public controls as the richer subagent atoms.
+- `[Recipe Library]` Added `utility-run-ops-snapshot` and routed `pipeline-async-run-ops` through it so run summaries, event tails, and stale/terminal recommendations stay in one structured input. Impact: async-run operations reports no longer lose summary context before normalization and can suggest `inspect` or `control.stop` messages without executing them.
+- `[Actor Messages]` Added `inspect target=coordinator` support for current-session run inventory. Impact: the coordinator actor can now be intentionally observed without spelling out the session id.
+- `[Actor Messages]` Added `message to=session:<id>` support for run-owned session-directed follow-ups. Impact: explicit session checkpoints now use the same actor envelope as coordinator follow-ups while preserving run-owner checks.
+- `[Actor Messages]` Hardened `message to=session:<id>` routing to require an owned sender run. Impact: unowned or cross-session runs cannot synthesize session-directed follow-ups.
+- `[Actor Messages]` Applied coordinator-session ownership checks to addressed run, branch, and coordinator message routes when a session context is available. Impact: actor messages now fail closed before controlling or emitting from runs owned by another coordinator session.
+- `[Actor Messages]` Applied the same coordinator-session ownership gate to direct `inspect target=run:<id>` views. Impact: explicit run inspection no longer leaks cross-session run details when the current session is known.
+- `[Actor Messages]` Tightened `inspect target=coordinator` to require a current coordinator session instead of falling back to all runs. Impact: callers without session context must use explicit `session:<id>` or `session:all` inventory.
 
 ## 0.12.9: Actor Runtime Hotfix
 

package/README.md

@@ -307,7 +307,7 @@ Read recent events or logs only after a follow-up asks for inspection, at a real
 { "target": "run:docs-review", "view": "tail", "lines": "80" }
 ```
 
-Reusable local recipes live in `~/.pi/agent/recipes/*.json`; recipe tools honor each file's `async` flag. Use `spawn` for explicit detached starts from a file or inline template, and `inspect target=session:<id> view=runs status=running` or `inspect target=session:all view=runs` for explicit inventory/diagnosis. List output includes `tool` and `recipe` when the launcher recorded that source context.
+Reusable local recipes live in `~/.pi/agent/recipes/*.json`; recipe tools honor each file's `async` flag. Use `spawn` for explicit detached starts from a file or inline template, and `inspect target=coordinator view=runs status=running`, `inspect target=session:<id> view=runs status=running`, or `inspect target=session:all view=runs` for explicit inventory/diagnosis. List output includes `tool` and `recipe` when the launcher recorded that source context.
 
 ## Recipe Library
 
@@ -376,8 +376,8 @@ See [`docs/recipe-library.md`](./docs/recipe-library.md) for install notes and r
 - Obvious high-risk templates such as shells, interpreter eval modes, and broad filesystem mutation surface lightweight warnings without blocking existing tools.
 - `async: true` on a recipe selects detached run lifecycle; omitted or false async runs the recipe foreground through registered tools.
 - Layer boundaries stay explicit: command templates define synchronous execution graphs; template recipes add saved JSON metadata/import resolution and named `artifacts`; async runs add detached lifecycle, state, IPC, and observability.
-- `spawn`, `message`, and `inspect` are high-level actor adapters. `spawn` creates `run:<id>` actors from recipes or inline templates with optional state/artifact metadata, `message` sends one typed envelope to `run:<id>` mailboxes, `branch:<run>/<branch>` mailboxes, `tool:<name>` calls, or the coordinator attention path, and `inspect` intentionally reads `run:<id>` status/tail/events/mailbox metadata or `session:<id>` run status while the broader actor/message protocol is refined.
-- `spawn`, `message`, and `inspect` are the public async coordination vocabulary. Low-level async actions map to this actor API: start belongs to `spawn`; send/control belongs to `message`; status/tail/events/list belong to `inspect`; stop/kill are runtime control messages with synchronous results.
+- `spawn`, `message`, and `inspect` are high-level actor adapters. `spawn` creates `run:<id>` actors from recipes or inline templates with optional state/artifact metadata, `message` sends one typed envelope to `run:<id>` mailboxes, `branch:<run>/<branch>` mailboxes, `tool:<name>` calls, or coordinator/session attention paths, and `inspect` intentionally reads `run:<id>` status/tail/events/mailbox metadata, coordinator/session run status, or registered `tool:<name>` contracts while the broader actor/message protocol is refined.
+- `spawn`, `message`, and `inspect` are the public async coordination vocabulary. Low-level async actions map to this actor API: start belongs to `spawn`; send/control/stop/kill belongs to `message`; status/tail/events/list belongs to `inspect`. Prefer `control.stop` and `control.kill` for run termination; legacy `runtime.cancel` and `runtime.kill` remain compatibility aliases.
 - Actor management returns compact text by default; pass `verbose: true` to `inspect` when full JSON state is needed.
 - Detached runs inject `{run_id}` and `{state_dir}` into template values for run-local artifacts or recipe-specific control endpoints.
 - Runtime actor messages are stored in `<state_dir>/outbox.jsonl`; coordinator attention is inferred by the runtime, not exposed as recipe or message-envelope input. Follow-ups preserve bounded body previews and metadata for decision messages.

package/docs/actor-messages.md

@@ -58,7 +58,7 @@ Field rules:
 - `type`: required semantic message type.
 - `summary`: short human-facing line for notifications/follow-ups.
 - `body`: string or JSON payload.
-- routing/delivery is inferred from `to`, actor ownership, and coordinator runtime policy; recipes should not expose delivery knobs.
+- routing/delivery is inferred from `to`, actor ownership, and coordinator runtime policy; recipes should not expose delivery knobs. When a coordinator session is known, addressed run/branch/control messages fail closed before controlling or emitting from runs owned by another session.
 - `reply_to`: optional message id for conversational checkpoints.
 - `correlation_id`: optional task/run/workflow id.
 - `metadata`: optional structured routing or domain hints.
@@ -79,7 +79,7 @@ coordinator -> tool
 Transports differ, but the public contract does not:
 
 - `to: run:<id>` may route to FIFO, mailbox file, socket, or process stdin.
-- `to: coordinator` routes to outbox/watch/follow-up delivery when `from` names a run actor. Generic async-runner `command.done` events and explicit coordinator-bound messages include the actor envelope fields alongside the runtime event fields.
+- `to: coordinator` routes to outbox/watch/follow-up delivery 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` events and explicit coordinator/session-bound messages include the actor envelope fields alongside the runtime event fields.
 - `to: branch:<run>/<branch>` routes through the parent run mailbox with the full envelope preserved so the run can dispatch branch-local control.
 - `to: tool:<name>` invokes an executable pi tool by name. Object bodies become tool parameters; primitive bodies are passed as `{ "input": body }`.
 
@@ -126,7 +126,7 @@ Recipes can declare their conversational surface:
 }
 ```
 
-The implementation supports `status`, `tail`, `events`, `artifacts`, `files`, and `mailbox` for `run:<id>` actors, plus `status`/`runs` for `session:<id>` and `session:all` actors with optional status filtering. `inspect` is for decision points and diagnosis only; examples must not teach sleep-then-inspect polling.
+The implementation supports `status`, `tail`, `events`, `artifacts`, `files`, and `mailbox` for `run:<id>` actors, `status`/`runs` for `coordinator`, `session:<id>`, and `session:all` actors with optional status filtering, and `status`/`schema` for registered `tool:<name>` actors. `inspect target=coordinator` requires a current coordinator session; use `session:<id>` or `session:all` when the session is intentionally explicit. Direct `run:<id>` 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
 
@@ -135,7 +135,8 @@ Runtime operations use the actor/message vocabulary:
 ```text
 create detached work -> spawn
 run-local control    -> message to run:<id>
-coordinator signal   -> message to coordinator
+run stop/kill        -> message type control.stop/control.kill
+coordinator signal   -> message to coordinator/session
 tool execution       -> message to tool:<name>
 intentional observe  -> inspect
 ```

package/docs/async-runs.md

@@ -127,22 +127,22 @@ The core loop is:
 
 4. Do not inspect just because time passed. Inspect `status`, `tail`, or `events` only when a follow-up asks for inspection, a real decision depends on it, or a suspected stuck run needs diagnosis.
 
-Addressed `message` calls and coordinator follow-ups are the paired control plane: run-to-coordinator actor messages flow upward, while coordinator-to-run actor messages flow downward. Recipe scripts own the message vocabulary (`next`, `pause`, `approve`, `revise`, `continue`, and so on); pi-actors owns the safe run-local transport, ownership checks, and coordinator attention policy.
+Addressed `message` calls and coordinator follow-ups are the paired control plane: run-to-coordinator actor messages flow upward, while coordinator-to-run actor messages flow downward. Recipe scripts own the message vocabulary (`next`, `pause`, `approve`, `revise`, `continue`, and so on); pi-actors owns the safe run-local transport, coordinator-session ownership checks, and coordinator attention policy.
 
 ## Tool Surface
 
 The actor-level surface is:
 
 - `spawn`: start a detached `run:<id>` actor from `file`, `recipe`, or inline `template`.
-- `message`: send one typed envelope to `run:<id>`, `branch:<run>/<branch>`, `tool:<name>`, or `coordinator`.
-- `inspect`: intentionally read `run:<id>` status, tail, events, artifacts, files, or mailbox metadata; read `session:<id>` or `session:all` run inventory with optional status filtering.
+- `message`: send one typed envelope to `run:<id>`, `branch:<run>/<branch>`, `tool:<name>`, `coordinator`, or `session:<id>`.
+- `inspect`: intentionally read owned `run:<id>` status, tail, events, artifacts, files, or mailbox metadata; 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.
 
 Low-level async actions map into the actor surface instead of forming a second public model:
 
 - start → `spawn`
 - send/control → `message`
 - status/tail/events/list → `inspect`
-- stop/kill → runtime control messages with synchronous results
+- stop/kill → `message` with `control.stop` or `control.kill`, with synchronous results
 
 Compact text is returned by default so async management does not flood agent context; use verbose inspection when the full state object is needed. List output intentionally shares one state root across music, subagents, timers, and other async work; source fields such as `tool` and `recipe` distinguish run purpose when the launcher recorded them. Registered tools are the preferred user-facing surface for reusable recipes.
 
@@ -172,13 +172,13 @@ Native Windows does not support this Unix FIFO contract. Use WSL/Linux/macOS for
 
 ## Coordinator Notifications
 
-The launching coordinator should not busy-poll long-running async runs. The extension watches run state directories and delivers terminal `done`/`failed`/unhandled `killed`/`exited` transitions plus script-authored `notify`/`followup` actor messages back to the owning session. This gives the top-level async task a completion signal on the happy path while still letting recipe-local messages bubble up when scripts need finer-grained notifications. Terminal follow-ups include recipe-level named `artifacts` when declared. The generic runner also emits compact `command.done` actor messages for completed leaf commands; recipe authors declare that capability in `mailbox.emits` rather than configuring a separate delivery policy. Failures and in-flight parallel branch completions can bubble as follow-ups, while successful final leaf completions stay diagnostic to avoid flooding long sequential pipelines. Branch-level `command.done` follow-ups omit artifact manifests because the top-level terminal follow-up carries them once. Intentional `runtime.cancel`, `runtime.kill`, and control messages such as `stop` stay out of follow-up context because the initiating message already returns synchronously. If a follow-up asks for direction, answer with `message` rather than starting a polling loop. Use explicit `inspect` only when a delivered follow-up requests inspection, a real decision depends on state, or a suspected stuck run needs diagnosis — never merely because a timeout elapsed.
+The launching coordinator should not busy-poll long-running async runs. The extension watches run state directories and delivers terminal `done`/`failed`/unhandled `killed`/`exited` transitions plus script-authored `notify`/`followup` actor messages back to the owning session. This gives the top-level async task a completion signal on the happy path while still letting recipe-local messages bubble up when scripts need finer-grained notifications. Terminal follow-ups include recipe-level named `artifacts` when declared. The generic runner also emits compact `command.done` actor messages for completed leaf commands; recipe authors declare that capability in `mailbox.emits` rather than configuring a separate delivery policy. Failures and in-flight parallel branch completions can bubble as follow-ups, while successful final leaf completions stay diagnostic to avoid flooding long sequential pipelines. Branch-level `command.done` follow-ups omit artifact manifests because the top-level terminal follow-up carries them once. Intentional `control.stop`, `control.kill`, and recipe-local stop commands stay out of follow-up context because the initiating message already returns synchronously. If a follow-up asks for direction, answer with `message` rather than starting a polling loop. Use explicit `inspect` only when a delivered follow-up requests inspection, a real decision depends on state, or a suspected stuck run needs diagnosis — never merely because a timeout elapsed.
 
 Ambient status indicators may refresh while work is active, but coordinator attention is event-driven from state-file changes rather than a coordinator agent loop. This lets the coordinator continue other work after `spawn`; the run signals back through `events.jsonl`, `result.json`, and `outbox.jsonl`. The ambient triangle count represents active async work units: each running async run contributes at least one triangle, and a run with multiple active parallel command/subagent branches contributes the reported active branch count. If a coordinator starts one parent run with four active parallel branches, four triangles are shown; if the same coordinator starts five independent single-branch runs, five triangles are shown.
 
 ## Run Actor Messages
 
-A recipe or script may append coordinator-bound actor message records to:
+A recipe or script may append coordinator-bound or session-bound actor message records to:
 
 ```text
 <state_dir>/outbox.jsonl
@@ -200,7 +200,7 @@ Shape:
 
 `level` is `info`, `warning`, or `error`. The public message describes sender, receiver, type, summary, and body; it does not choose notification mechanics. Runtime attention policy infers whether a coordinator-bound message stays available for explicit `inspect`, becomes a UI notification, or re-enters the launching coordinator as compact follow-up context.
 
-Use coordinator-bound messages for completion and decision points, not for every progress tick. Packaged multi-agent branch completion is a completion message and should bubble by default. Follow-up path lists use Markdown hierarchy: a section heading, `- Base: ...`, and `- Files: ...`, so repeated run-state prefixes do not flood agent context.
+Use coordinator/session-bound messages for completion and decision points, not for every progress tick. Packaged multi-agent branch completion is a completion message and should bubble by default. Follow-up path lists use Markdown hierarchy: a section heading, `- Base: ...`, and `- Files: ...`, so repeated run-state prefixes do not flood agent context.
 
 ## Cancellation And Ownership
 

package/docs/component-recipes.md

@@ -32,7 +32,7 @@ Keep components narrow. Higher-level recipes should own composition, not hidden
 
 Start one subagent or branch with a caller-provided prompt and model. Launchers do not judge or merge output.
 
-Example: `recipes/subagent-prompt.json`.
+Examples: `recipes/subagent-prompt.json`, `recipes/subagent-tools.json`, and `recipes/subagents-prompts.json`.
 
 ### Reviewers
 

package/docs/recipe-library.md

@@ -46,7 +46,7 @@ Core subagent recipes:
 - `recipes/subagent-followup.json`: Same-context or degraded continuation.
 - `recipes/subagent-judge.json`: Post-merge/report quality judge.
 
-Most atoms expose policy knobs such as `model`, `thinking`, `tools`, `output_format`, `evidence_policy`, `risk_policy`, source policy, continuity policy, handoff format, or model pools. Interactive async atoms also declare mailbox metadata for their basic control, completion, and domain-result message surface. Higher-level recipes pass these knobs through instead of hard-coding local policy.
+Most atoms expose policy knobs such as `model`, `thinking`, `tools`, `output_format`, `evidence_policy`, `risk_policy`, source policy, continuity policy, handoff format, or model pools. The generic prompt launchers, including `subagent-tools` and `subagents-prompts`, expose the same core model/thinking/tool/output knobs so callers do not need separate recipe families for policy tuning. Interactive async atoms also declare mailbox metadata for their basic control, completion, and domain-result message surface. Higher-level recipes pass these knobs through instead of hard-coding local policy.
 
 Register one atom:
 
@@ -82,6 +82,7 @@ Pipeline recipes demonstrate second-order composition:
 - `recipes/pipeline-media-library.json`: Playlist build → media-library artifact report.
 - `recipes/pipeline-artifact-report.json`: Normalize → artifact-shaped output → actor-message-shaped record. This pipeline prepares a candidate artifact and emits `artifact.prepared`/`artifact.blocked`; the `artifact_path` is a target path, not a guarantee that the file was written.
 - `recipes/pipeline-artifact-write.json`: Normalize → artifact-shaped output → deterministic artifact write → actor-message-shaped record. Use only when the caller explicitly wants filesystem writes; `write_mode` is `create`, `overwrite`, or `append`.
+- `recipes/pipeline-artifact-bundle.json`: Optional validation → deterministic artifact write → machine-readable manifest generation → deterministic manifest write → actor-message-shaped record. Use when the caller explicitly wants a filesystem handoff bundle with both artifact and manifest paths.
 
 These are examples of library composition, not a workflow DSL. Pipeline recipes declare mailbox metadata for their high-level completion, artifact, and control message surface. The recipe layer owns imports and saved defaults; command templates own execution shape; async runs own lifecycle.
 
@@ -98,6 +99,7 @@ Utility recipes cover local operator workflows that do not need subagents:
 - `recipes/utility-changelog-head.json`: Read the top slice of a changelog for release summary prep.
 - `recipes/utility-playlist-scan.json`: List local media files as playlist-building input.
 - `recipes/utility-run-summary.json`: Use `scripts/recipe-utils.mjs` to summarize async run state files as JSON.
+- `recipes/utility-run-ops-snapshot.json`: Combine async run summaries, event-tail JSONL, and stale/terminal recommendations into one structured operations snapshot.
 - `recipes/utility-playlist-build.json`: Use `scripts/recipe-utils.mjs` to build a filtered playlist listing as newline paths, M3U, or inline `|`-separated source.
 - `recipes/utility-changelog-section.json`: Use `scripts/recipe-utils.mjs` to extract one changelog release section.
 - `recipes/utility-artifact-manifest.json`: Use `scripts/recipe-utils.mjs` to emit a machine-readable JSON manifest for an artifact path.
@@ -173,4 +175,4 @@ Message body is currently adapted to one newline-delimited command written to `<
 - Only play trusted local files or URLs.
 - Volume is clamped to `0..100` by the wrapper.
 - Prefer a stable `run_id` such as `music` when the operator expects to control the run by name.
-- Use `message type=runtime.kill` only when graceful cancellation fails.
+- Use `message type=control.kill` only when graceful `control.stop` cancellation fails.

package/docs/task-first-recipes.md

@@ -108,7 +108,7 @@ Existing seeds:
 
 Implemented seed:
 
-- `pipeline-async-run-ops`: run summary → event tail → normalized operations report → artifact report.
+- `pipeline-async-run-ops`: structured run operations snapshot → normalized operations report → artifact report. The snapshot combines run summary, event tail, and recommended inspect/control messages before the LLM normalization step.
 
 ### Research Brief Cell
 
@@ -227,7 +227,7 @@ Prefer adding a high-level recipe when at least three cells already exist and th
 Good next candidates for the standard library after the first task-first wave:
 
 1. Package/release metadata enrichment: use `utility-package-summary` with changelog and validation cells to make release-readiness reports more evidence-rich without adding publish automation.
-2. Artifact packaging and manifesting: compose `pipeline-artifact-write`, `utility-artifact-manifest`, artifact reports, and validation summaries into a machine-readable handoff bundle when the caller explicitly requests filesystem writes.
+2. Artifact packaging and manifesting: implemented as `pipeline-artifact-bundle`, which composes optional validation, `pipeline-artifact-write`, `utility-artifact-manifest`, deterministic manifest writing, and an actor-message handoff when the caller explicitly requests filesystem writes.
 3. Async run cleanup planning: extend async-run operations with stale-run classification and recommended `message`, `cancel`, or `kill` controls, keeping actual control execution operator-gated.
 
-Each candidate should land with the minimum missing cells rather than a broad one-shot framework. Already implemented task-first seeds include `pipeline-release-readiness`, `pipeline-repo-health`, `pipeline-async-run-ops`, `pipeline-docs-maintenance`, and `pipeline-media-library`.
+Each candidate should land with the minimum missing cells rather than a broad one-shot framework. Already implemented task-first seeds include `pipeline-release-readiness`, `pipeline-repo-health`, `pipeline-async-run-ops`, `pipeline-docs-maintenance`, `pipeline-media-library`, and `pipeline-artifact-bundle`.

package/index.ts

@@ -194,5 +194,9 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
       getTool: (name) => actorToolDefinitions.get(name),
     }),
   );
-  pi.registerTool(Tools.createInspectToolDefinition());
+  pi.registerTool(
+    Tools.createInspectToolDefinition<ExtensionContext>({
+      getTool: (name) => actorToolDefinitions.get(name),
+    }),
+  );
 }

package/lib/execution.ts

@@ -98,6 +98,20 @@ function createTemplateConfig(
   return { args: cfg.args, defaults: cfg.defaults, template: cfg.template };
 }
 
+function quoteCommandDetailPart(value: string): string {
+  if (value === "") return "''";
+  if (/^[A-Za-z0-9_/:=.,@%+\-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function formatInvocationDetail(
+  invocation: CommandTemplates.CommandTemplateInvocation,
+): string {
+  return [invocation.command, ...invocation.args]
+    .map(quoteCommandDetailPart)
+    .join(" ");
+}
+
 function formatCommandDetail(commands: string[]): string {
   return commands.length === 1 ? commands[0] : commands.join(" && ");
 }
@@ -494,7 +508,7 @@ async function executeTemplateConfig(
     });
     return {
       branches: [],
-      commands: [invocation.command],
+      commands: [formatInvocationDetail(invocation)],
       failures: [],
       result,
     };

package/lib/tools.ts

@@ -216,6 +216,15 @@ function compactSessionRuns(session: string, runs: Array<Record<string, unknown>
     .join("\n")}`;
 }
 
+function compactToolActor(name: string, tool: Record<string, unknown>): string {
+  const parameters = asRecord(tool.parameters);
+  const required = Array.isArray(parameters.required)
+    ? parameters.required.join(",")
+    : "";
+  const properties = asRecord(parameters.properties);
+  return `\ntool=${name} description=${String(tool.description ?? "").replaceAll(/\s+/g, "_")} args=${Object.keys(properties).join(",")} required=${required}`;
+}
+
 function compactActorMessageResult(
   message: ActorMessages.ActorMessage,
   result: Record<string, unknown>,
@@ -335,6 +344,9 @@ export function createSpawnToolDefinition<
         template: unionSchema([
           stringSchema("Inline command template string"),
           arraySchema("Inline command-template sequence or parallel tree"),
+          looseObjectSchema(
+            "Inline command-template object with flags such as parallel, repeat, retry, failure, and nested template.",
+          ),
         ]),
         values: looseObjectSchema("Runtime placeholder values passed to the actor."),
         verbose: booleanSchema("Return full JSON instead of compact text."),
@@ -379,17 +391,44 @@ export function createSpawnToolDefinition<
   };
 }
 
-export function createInspectToolDefinition(): any {
+export interface InspectToolDeps<TContext = unknown> {
+  getTool?: (name: string) => any | undefined;
+}
+
+function getContextSessionId(ctx: unknown): string | undefined {
+  return (ctx as AsyncRunToolContext | undefined)?.sessionManager?.getSessionId?.();
+}
+
+function requireContextSessionId(ctx: unknown, actor: string): string {
+  const sessionId = getContextSessionId(ctx);
+  if (!sessionId) {
+    throw new Error(`${actor} requires a current coordinator session; use session:<id> or session:all for explicit session inventory.`);
+  }
+  return sessionId;
+}
+
+function assertRunAccessibleToContext(runId: string, ctx: unknown): Record<string, unknown> {
+  const status = AsyncRuns.getRunStatus(runId);
+  const sessionId = getContextSessionId(ctx);
+  if (sessionId && status.ownerId && status.ownerId !== sessionId) {
+    throw new Error(`run:${runId} is owned by session:${status.ownerId}; current session is ${sessionId}.`);
+  }
+  return status;
+}
+
+export function createInspectToolDefinition<TContext = unknown>(
+  deps: InspectToolDeps<TContext> = {},
+): any {
   return {
     name: "inspect",
     label: "Inspect",
     description:
-      "Intentionally inspect an actor. Supports run:<id> views: status, tail, events, artifacts, files, mailbox; and session:<id> status.",
+      "Intentionally inspect an actor. Supports run:<id> views: status, tail, events, artifacts, files, mailbox; coordinator/session status; and tool:<name> status/schema.",
     parameters: objectSchema(
       {
         lines: stringSchema("Line count for tail/events views. Default 40."),
         status: stringSchema("Optional session run filter: all, running, active, terminal, done, failed, cancelled, killed, or exited."),
-        target: stringSchema("Actor address to inspect, e.g. run:<id>, session:<id>, or session:all."),
+        target: stringSchema("Actor address to inspect, e.g. run:<id>, coordinator, session:<id>, session:all, or tool:<name>."),
         verbose: booleanSchema("Return full JSON instead of compact text where available."),
         view: stringSchema("Inspection view: status, tail, events, artifacts, files, or mailbox."),
       },
@@ -400,12 +439,30 @@ export function createInspectToolDefinition(): any {
       params: unknown,
       _signal: AbortSignal | undefined,
       _onUpdate: unknown,
-      _ctx: unknown,
+      ctx: TContext,
     ) {
       const input = asRecord(params);
       const target = String(input.target ?? "");
       const address = ActorMessages.parseActorAddress(target);
       const view = String(input.view ?? "");
+      if (address.kind === "coordinator") {
+        if (view !== "status" && view !== "runs") {
+          throw new Error("inspect coordinator supports view=status or view=runs.");
+        }
+        const session = requireContextSessionId(ctx, "inspect coordinator");
+        const runs = AsyncRuns.listRuns(undefined, typeof input.status === "string" ? input.status : undefined)
+          .map((run) => AsyncRuns.getRunStatus(String(run.state_dir)))
+          .filter((run) => run.ownerId === session);
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: maybeJsonText({ session, runs }, input.verbose === true, compactSessionRuns(session, runs)),
+            },
+          ],
+          details: { session, runs },
+        };
+      }
       if (address.kind === "session") {
         if (view !== "status" && view !== "runs") {
           throw new Error("inspect session:<id> supports view=status or view=runs.");
@@ -423,11 +480,33 @@ export function createInspectToolDefinition(): any {
           details: { session: address.value, runs },
         };
       }
+      if (address.kind === "tool" && address.value) {
+        if (view !== "status" && view !== "schema") {
+          throw new Error("inspect tool:<name> supports view=status or view=schema.");
+        }
+        const tool = deps.getTool?.(address.value);
+        if (!tool) throw new Error(`tool actor not found: ${address.value}`);
+        const details = {
+          name: address.value,
+          description: tool.description,
+          parameters: tool.parameters,
+          promptSnippet: tool.promptSnippet,
+        };
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: maybeJsonText(details, input.verbose === true || view === "schema", compactToolActor(address.value, details)),
+            },
+          ],
+          details,
+        };
+      }
       const runId = address.kind === "run" ? address.value : undefined;
-      if (!runId) throw new Error("inspect target must be run:<id> or session:<id>.");
+      if (!runId) throw new Error("inspect target must be run:<id>, coordinator, session:<id>, or tool:<name>.");
       switch (view) {
         case "status": {
-          const status = AsyncRuns.getRunStatus(runId);
+          const status = assertRunAccessibleToContext(runId, ctx);
           return {
             content: [
               {
@@ -439,10 +518,12 @@ export function createInspectToolDefinition(): any {
           };
         }
         case "tail": {
+          assertRunAccessibleToContext(runId, ctx);
           const text = AsyncRuns.tailRun(runId, Number(input.lines || 40));
           return { content: [{ type: "text" as const, text: `\n${text}` }], details: {} };
         }
         case "events": {
+          assertRunAccessibleToContext(runId, ctx);
           const events = AsyncRuns.readRunEvents(runId, Number(input.lines || 40));
           return {
             content: [
@@ -456,7 +537,7 @@ export function createInspectToolDefinition(): any {
         }
         case "artifacts":
         case "files": {
-          const status = AsyncRuns.getRunStatus(runId);
+          const status = assertRunAccessibleToContext(runId, ctx);
           return {
             content: [
               {
@@ -468,7 +549,7 @@ export function createInspectToolDefinition(): any {
           };
         }
         case "mailbox": {
-          const status = AsyncRuns.getRunStatus(runId);
+          const status = assertRunAccessibleToContext(runId, ctx);
           const mailbox = asRecord(status.mailbox);
           return {
             content: [
@@ -498,7 +579,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
     name: "message",
     label: "Message",
     description:
-      "Send one typed addressed message. Routes to run:<id> mailboxes, branch:<run>/<branch> mailboxes, tool:<name> calls, and coordinator-bound run messages.",
+      "Send one typed addressed message. Routes to run:<id> mailboxes, branch:<run>/<branch> mailboxes, tool:<name> calls, and coordinator/session-bound run messages.",
     parameters: objectSchema(
       {
         body: unionSchema([
@@ -529,9 +610,10 @@ export function createActorMessageToolDefinition<TContext = unknown>(
       const address = ActorMessages.parseActorAddress(message.to);
       let result: Record<string, unknown>;
       if (address.kind === "run" && address.value) {
-        if (message.type === "runtime.cancel") {
+        assertRunAccessibleToContext(address.value, ctx);
+        if (message.type === "control.stop" || message.type === "control.cancel" || message.type === "runtime.cancel") {
           result = AsyncRuns.cancelRun(address.value);
-        } else if (message.type === "runtime.kill") {
+        } else if (message.type === "control.kill" || message.type === "runtime.kill") {
           result = AsyncRuns.killRun(address.value);
         } else {
           result = AsyncRuns.sendRunMessage(
@@ -540,6 +622,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
           );
         }
       } else if (address.kind === "branch" && address.value) {
+        assertRunAccessibleToContext(address.value, ctx);
         result = AsyncRuns.sendRunMessage(
           address.value,
           JSON.stringify(message),
@@ -562,17 +645,27 @@ export function createActorMessageToolDefinition<TContext = unknown>(
           tool: address.value,
           tool_result: toolResult,
         };
-      } else if (address.kind === "coordinator") {
+      } else if (address.kind === "coordinator" || address.kind === "session") {
         if (!message.from) {
-          throw new Error("message to coordinator requires from=run:<id>.");
+          throw new Error(`message to ${address.kind} requires from=run:<id>.`);
         }
         const sender = ActorMessages.parseActorAddress(message.from);
         if (sender.kind !== "run" || !sender.value) {
-          throw new Error("message to coordinator currently requires from=run:<id>.");
+          throw new Error(`message to ${address.kind} currently requires from=run:<id>.`);
+        }
+        const senderStatus = assertRunAccessibleToContext(sender.value, ctx);
+        if (address.kind === "session") {
+          if (!senderStatus.ownerId) {
+            throw new Error(`message to session:${address.value} requires sender run owner ${address.value}; got no owner.`);
+          }
+          if (senderStatus.ownerId !== address.value) {
+            throw new Error(`message to session:${address.value} requires sender run owner ${address.value}; got ${senderStatus.ownerId}.`);
+          }
         }
         result = AsyncRuns.appendRunOutboxEvent(sender.value, {
           body: message.body,
           correlation_id: message.correlation_id,
+          delivery: address.kind === "session" ? "followup" : undefined,
           event: message.type,
           from: message.from,
           metadata: message.metadata,
@@ -583,7 +676,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
         });
       } else {
         throw new Error(
-          `message currently supports run:<id>, branch:<run>/<branch>, tool:<name>, and coordinator destinations; unsupported destination: ${message.to}`,
+          `message currently supports run:<id>, branch:<run>/<branch>, tool:<name>, coordinator, and session:<id> destinations; unsupported destination: ${message.to}`,
         );
       }
       return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.12.9",
+  "version": "0.12.13",
   "private": false,
   "description": "Actor runtime and orchestrator for agent-managed local processes",
   "type": "module",

package/recipes/pipeline-artifact-bundle.json

@@ -0,0 +1,92 @@
+{
+  "name": "pipeline-artifact-bundle",
+  "async": true,
+  "imports": {
+    "artifactWrite": "pipeline-artifact-write.json",
+    "manifest": "utility-artifact-manifest.json",
+    "manifestWrite": "utility-artifact-write.json",
+    "validation": "utility-validation-wrapper.json",
+    "message": "utility-actor-message.json"
+  },
+  "args": [
+    "input:string",
+    "artifact_path:path",
+    "manifest_path:path",
+    "artifact_title:string",
+    "artifact_format:string",
+    "artifact_status:enum(draft,ready,blocked,accepted)",
+    "write_mode:enum(create,overwrite,append)",
+    "run_validation:bool",
+    "validation_command:string",
+    "validation_scope:string",
+    "validation_timeout_ms:int",
+    "model:string",
+    "tools:string"
+  ],
+  "defaults": {
+    "artifact_title": "Artifact Bundle",
+    "artifact_format": "Markdown sections: Summary, Findings, Evidence, Risks, Next Actions.",
+    "artifact_status": "ready",
+    "write_mode": "create",
+    "run_validation": "false",
+    "validation_command": "true",
+    "validation_scope": ".",
+    "validation_timeout_ms": "300000",
+    "model": "openai-codex/gpt-5.5",
+    "tools": ""
+  },
+  "mailbox": {
+    "accepts": ["control.stop"],
+    "emits": ["artifact.bundle_ready", "artifact.written", "artifact.blocked", "run.done", "run.failed"]
+  },
+  "artifacts": {
+    "artifact": "{artifact_path}",
+    "manifest": "{manifest_path}"
+  },
+  "template": [
+    {
+      "when": "run_validation",
+      "name": "validation",
+      "values": {
+        "command": "{validation_command}",
+        "scope": "{validation_scope}",
+        "timeout_ms": "{validation_timeout_ms}"
+      }
+    },
+    {
+      "name": "artifactWrite",
+      "values": {
+        "input": "{input}",
+        "artifact_path": "{artifact_path}",
+        "artifact_format": "{artifact_format}",
+        "write_mode": "{write_mode}",
+        "model": "{model}",
+        "tools": "{tools}"
+      }
+    },
+    {
+      "name": "manifest",
+      "values": {
+        "artifact_path": "{artifact_path}",
+        "title": "{artifact_title}",
+        "status": "{artifact_status}",
+        "summary": "Artifact bundle manifest for {artifact_path}."
+      }
+    },
+    {
+      "name": "manifestWrite",
+      "values": {
+        "artifact_path": "{manifest_path}",
+        "mode": "{write_mode}"
+      }
+    },
+    {
+      "name": "message",
+      "values": {
+        "type": "artifact.bundle_ready",
+        "summary": "Artifact bundle ready: {artifact_path} with manifest {manifest_path}.",
+        "metadata": "{\"artifact\":\"{artifact_path}\",\"manifest\":\"{manifest_path}\"}"
+      }
+    }
+  ]
+}

package/recipes/pipeline-async-run-ops.json

@@ -2,8 +2,7 @@
   "name": "pipeline-async-run-ops",
   "async": true,
   "imports": {
-    "summary": "utility-run-summary.json",
-    "events": "utility-jsonl-tail.json",
+    "snapshot": "utility-run-ops-snapshot.json",
     "normalizer": "subagent-normalize.json",
     "artifact": "pipeline-artifact-report.json"
   },
@@ -11,6 +10,7 @@
     "state_root:path",
     "event_file:path",
     "lines:int",
+    "stale_minutes:int",
     "artifact_path:path",
     "model:string",
     "tools:string"
@@ -19,6 +19,7 @@
     "state_root": "~/.pi/agent/tmp/pi-actors/runs",
     "event_file": "~/.pi/agent/tmp/pi-actors/runs/music/outbox.jsonl",
     "lines": "80",
+    "stale_minutes": "60",
     "artifact_path": "./async-run-ops.md",
     "model": "openai-codex/gpt-5.5",
     "tools": ""
@@ -29,24 +30,18 @@
   },
   "template": [
     {
-      "name": "summary",
+      "name": "snapshot",
       "values": {
-        "state_root": "{state_root}"
-      }
-    },
-    {
-      "name": "events",
-      "failure": "continue",
-      "values": {
-        "file": "{event_file}",
+        "state_root": "{state_root}",
+        "event_file": "{event_file}",
         "lines": "{lines}",
-        "mode": "raw"
+        "stale_minutes": "{stale_minutes}"
       }
     },
     {
       "name": "normalizer",
       "values": {
-        "input": "Use async run summary and event tail from stdin. State root: {state_root}. Event file: {event_file}.",
+        "input": "Use async run operations snapshot JSON from stdin. State root: {state_root}. Event file: {event_file}.",
         "format": "Markdown sections: Active Runs, Terminal Runs, Recent Events, Stale/Risky Runs, Recommended Controls, Follow-up Needed.",
         "model": "{model}",
         "thinking": "off",

package/recipes/subagent-tools.json

@@ -4,14 +4,18 @@
   "args": [
     "prompt:string",
     "tools:string",
-    "model:string"
+    "model:string",
+    "thinking:string",
+    "output_format:string"
   ],
   "defaults": {
-    "model": "openai-codex/gpt-5.5"
+    "model": "openai-codex/gpt-5.5",
+    "thinking": "off",
+    "output_format": "Concise Markdown with assumptions and next actions."
   },
   "mailbox": {
     "accepts": ["control.stop"],
     "emits": ["command.done", "run.done", "run.failed"]
   },
-  "template": "pi -p --model {model} --tools {tools} {prompt}"
+  "template": "pi -p --model {model} --thinking {thinking} --tools {tools} {prompt}. Output format: {output_format}"
 }

package/recipes/subagents-prompts.json

@@ -6,10 +6,18 @@
   },
   "args": [
     "prompts:array",
+    "model:string",
+    "thinking:string",
+    "tools:string",
+    "output_format:string",
     "report_path:path",
     "summary_path:path"
   ],
   "defaults": {
+    "model": "openai-codex/gpt-5.5",
+    "thinking": "off",
+    "tools": "",
+    "output_format": "Concise Markdown with assumptions and next actions.",
     "report_path": "{state_dir}/stdout.log",
     "summary_path": "{state_dir}/result.json"
   },
@@ -26,7 +34,11 @@
   "template": {
     "name": "subagent",
     "values": {
-      "prompt": "{prompts[index]}"
+      "prompt": "{prompts[index]}",
+      "model": "{model}",
+      "thinking": "{thinking}",
+      "tools": "{tools}",
+      "output_format": "{output_format}"
     }
   }
 }

package/recipes/utility-run-ops-snapshot.json

@@ -0,0 +1,18 @@
+{
+  "name": "utility-run-ops-snapshot",
+  "args": [
+    "repo:path",
+    "state_root:path",
+    "event_file:path",
+    "lines:int",
+    "stale_minutes:int"
+  ],
+  "defaults": {
+    "repo": "~/.pi/agent/extensions/pi-actors",
+    "state_root": "~/.pi/agent/tmp/pi-actors/runs",
+    "event_file": "~/.pi/agent/tmp/pi-actors/runs/music/outbox.jsonl",
+    "lines": "80",
+    "stale_minutes": "60"
+  },
+  "template": "{repo}/scripts/recipe-utils.mjs run-ops-snapshot {state_root} {event_file} {lines} {stale_minutes}"
+}

package/scripts/async-runner.mjs

@@ -43,6 +43,19 @@ function event(name, data = {}) {
     `${JSON.stringify({ event: name, ts: new Date().toISOString(), ...data })}\n`,
   );
 }
+function quoteCommandDetailPart(value) {
+  if (value === "") return "''";
+  if (/^[A-Za-z0-9_/:=.,@%+\-]+$/.test(value)) return value;
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+function formatCommandDetail(command, args) {
+  return [command, ...args].map(quoteCommandDetailPart).join(" ");
+}
+function summarizeCommandDetail(commandDetail) {
+  return commandDetail.length > 160
+    ? `${commandDetail.slice(0, 157)}...`
+    : commandDetail;
+}
 function getCommandDoneDelivery(result) {
   return result.code !== 0 || activeSubagents > 0 ? "followup" : "log";
 }
@@ -76,30 +89,35 @@ function progressRunning() {
   });
 }
 async function observedExec(command, args, options) {
+  const commandDetail = formatCommandDetail(command, args);
   activeSubagents += 1;
-  event("command.start", { activeSubagents, command });
+  event("command.start", { activeSubagents, command: commandDetail });
   progressRunning();
   const result = await execCommandTemplate(command, args, options);
   activeSubagents = Math.max(0, activeSubagents - 1);
   completedSubagents += 1;
   if (result.code !== 0) {
-    subagentFailures.push({ code: result.code, command, killed: result.killed });
+    subagentFailures.push({
+      code: result.code,
+      command: commandDetail,
+      killed: result.killed,
+    });
   }
   event("command.done", {
     activeSubagents,
     code: result.code,
-    command,
+    command: commandDetail,
     killed: result.killed,
   });
   outbox(
     "command.done",
-    `Command ${command} completed with code ${result.code}`,
+    `Command ${summarizeCommandDetail(commandDetail)} completed with code ${result.code}`,
     {
       activeSubagents,
       ...(meta.artifacts ? { artifacts: meta.artifacts } : {}),
       run_files: [stdoutPath, stderrPath, resultPath, eventsPath, outboxPath],
       code: result.code,
-      command,
+      command: commandDetail,
       killed: result.killed,
     },
     getCommandDoneDelivery(result),

package/scripts/recipe-utils.mjs

@@ -5,6 +5,7 @@ import { dirname, extname, join, relative, resolve } from "node:path";
 function usage() {
   console.error(`Usage:
   recipe-utils.mjs run-summary <state-root>
+  recipe-utils.mjs run-ops-snapshot <state-root> <event-file> [lines] [stale-minutes]
   recipe-utils.mjs playlist <source-dir> [extensions] [max-depth] [paths|m3u|inline]
   recipe-utils.mjs changelog-section <file> <version>
   recipe-utils.mjs artifact-manifest <artifact-path> <title> <status> [summary]
@@ -75,7 +76,7 @@ function getRunStatus(run, progress, result) {
   return run.status ?? "unknown";
 }
 
-function runSummary(rootValue) {
+function collectRunSummary(rootValue) {
   const root = resolve(
     rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"),
   );
@@ -105,7 +106,51 @@ function runSummary(rootValue) {
   rows.sort((a, b) =>
     `${a.status}:${a.run}`.localeCompare(`${b.status}:${b.run}`),
   );
-  console.log(JSON.stringify(rows, null, 2));
+  return rows;
+}
+
+function runSummary(rootValue) {
+  console.log(JSON.stringify(collectRunSummary(rootValue), null, 2));
+}
+
+function tailJsonl(fileValue, linesValue = "80") {
+  const file = resolve(fileValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+  if (!existsSync(file)) return [];
+  const lines = Number.parseInt(linesValue, 10);
+  const count = Number.isFinite(lines) && lines > 0 ? lines : 80;
+  return readFileSync(file, "utf8").trimEnd().split("\n").filter(Boolean).slice(-count).map((line) => {
+    try {
+      return JSON.parse(line);
+    } catch {
+      return { raw: line };
+    }
+  });
+}
+
+function runOpsSnapshot(rootValue, eventFileValue, linesValue = "80", staleMinutesValue = "60") {
+  const runs = collectRunSummary(rootValue);
+  const staleMs = Number(staleMinutesValue) * 60 * 1000;
+  const now = Date.now();
+  const recommendations = runs.flatMap((run) => {
+    const updatedMs = Date.parse(run.updated || "");
+    const stale = Number.isFinite(updatedMs) && Number.isFinite(staleMs) && now - updatedMs > staleMs;
+    if (run.status === "running" && stale) {
+      return [{
+        run: run.run,
+        reason: "running-stale",
+        suggested_message: { to: `run:${run.run}`, type: "control.stop", body: "stop" },
+      }];
+    }
+    if (["failed", "exited", "killed"].includes(run.status)) {
+      return [{
+        run: run.run,
+        reason: `terminal-${run.status}`,
+        suggested_inspect: { target: `run:${run.run}`, view: "tail" },
+      }];
+    }
+    return [];
+  });
+  console.log(JSON.stringify({ runs, events: tailJsonl(eventFileValue, linesValue), recommendations }, null, 2));
 }
 
 function playlist(
@@ -255,6 +300,8 @@ if (!command) {
 
 if (command === "run-summary")
   runSummary(args[0] ?? "~/.pi/agent/tmp/pi-actors/runs");
+else if (command === "run-ops-snapshot")
+  runOpsSnapshot(args[0] ?? "~/.pi/agent/tmp/pi-actors/runs", args[1] ?? "~/.pi/agent/tmp/pi-actors/runs/music/outbox.jsonl", args[2], args[3]);
 else if (command === "playlist")
   playlist(args[0] ?? "~/Music", args[1], args[2], args[3]);
 else if (command === "changelog-section")