@llblab/pi-actors 0.42.3 → 0.43.1

package/docs/command-templates.md

@@ -10,13 +10,13 @@ Command templates are the portable integration format for deterministic local au
 
 Extensions may choose their own config files, selectors, placeholder sources, and examples, but should preserve this core contract.
 
-Layer boundary: command templates own only the synchronous execution graph. Recipe imports, import-reference expressions, recipe lookup, `async: true`, run ids, state dirs, mailbox controls, and actor-message routing are host/recipe/async-run configuration layers, not portable command-template syntax.
+Layer boundary: command templates own only the synchronous execution graph. Recipe imports, import-reference expressions, Recipe lookup, `async: true`, Run ids, state dirs, Control, and Trace are host/Recipe/Run layers, not portable command-template syntax.
 
 ## Layer Ownership
 
 Command-template standard owns:
 
-- Command string splitting and direct argv execution.
+- Command string splitting, portable script-interpreter inference, and direct argv execution.
 - Placeholder resolution, typed public args, defaults, `??`, ternary string selection, and array-index placeholders.
 - Synchronous graph shape: sequence, `parallel`, `when`, `repeat`, stdin flow, stdout joins, and output selection.
 - Per-node execution controls: `timeout`, `delay`, `retry`, `failure`, and `recover`.
@@ -25,7 +25,7 @@ Command-template standard does not own:
 
 - Where templates are stored or how they are named.
 - Recipe imports, import references, or file lookup.
-- Detached lifecycle, run ids, state dirs, logs, cancellation, mailbox controls, or actor-message routing.
+- Detached lifecycle, Run ids, state dirs, logs, cancellation, Control, or Trace.
 - Registry metadata such as tool descriptions, package install paths, or operator policy.
 
 ## Shape
@@ -72,7 +72,7 @@ A runtime must:
 
 1. Split the template into shell-like words with simple single quotes, double quotes, and backslash escapes
 2. Substitute placeholders inside each split word
-3. Execute command + args directly, without shell evaluation
+3. Infer a first-word `.js` or `.mjs` script through the first available `node`, `bun`, or `deno run` runtime, infer `.sh` through `bash`, and otherwise execute command + args directly; explicit interpreters remain unchanged and no shell evaluates the resulting argv
 4. Treat exit code `0` as success and non-zero as failure
 5. Use stdout as the default result channel and stderr only for diagnostics
 
@@ -106,35 +106,11 @@ With runtime values `{ "text": "hello" }`, argv is:
 
 Use `defaults` for visible configuration data; use inline defaults for compact local literals. Prefer flag-style examples such as `/path/to/tool --file {file} --lang {lang=ru}` for readability, but positional forms such as `/path/to/tool {file} {lang=ru}` are valid when the invoked script defines that CLI contract.
 
-Fallback values can be selected with nullish coalescing:
-
-```json
-{
-  "template": "deploy --env {env??dev} --region {region??local}"
-}
-```
-
-Optional flags can be mapped from boolean args with a ternary:
-
-```json
-{
-  "args": ["target:path", "all:bool"],
-  "defaults": { "all": "true" },
-  "template": "validate-recipe {target} {all?--all:}"
-}
-```
+Use `{env??dev}` for fallback values and `{all?--all:}` to map boolean args to optional text.
 
 Typed declarations annotate the public tool interface, not the shell command. They may live in `args` or inline placeholders such as `{request_timeout:int=60000}` and `{mode:enum(check,fix)=check}`. Use metadata-first authoring (`args` plus `defaults`) when long templates should stay visually short; use inline-first authoring when one self-contained `template` property is clearer. They do not sandbox or reinterpret the executable; they only let the host generate narrower input schemas and normalize runtime values before placeholder substitution. Untyped `args` and untyped placeholders continue to work unchanged.
 
-Node control fields can also read public args. Use distinct arg names so execution controls stay visually separate from public inputs:
-
-```json
-{
-  "args": ["timeout_ms:int"],
-  "timeout": "{timeout_ms}",
-  "template": "npm test"
-}
-```
+Node control fields can also read public args, for example `"timeout": "{timeout_ms}"`; use distinct names so execution controls stay visually separate from public inputs.
 
 ## Quoting
 
@@ -194,21 +170,6 @@ Composition rules:
 - `min_successful` adds a join header with `complete`, `degraded`, or `insufficient_data`; with `failure: "branch"` or `"root"`, an unmet threshold fails at that scope
 - Each leaf still applies its own inline defaults
 
-```json
-{
-  "template": [
-    "/path/to/tts --text {text} --lang {lang} --out {mp3}",
-    {
-      "defaults": { "codec": "libopus" },
-      "template": "ffmpeg -y -i {mp3} -c:a {codec} {ogg}"
-    }
-  ],
-  "args": ["text", "lang", "mp3", "ogg"],
-  "defaults": { "lang": "en" },
-  "output": "ogg"
-}
-```
-
 `output` selects the primary result channel. Omitted `output` means `"stdout"`, and explicitly writing `"output": "stdout"` is valid standard syntax. Artifact-producing handlers may instead name a runtime value or placeholder path, e.g. `"ogg"` or `"{ogg}"`. Do not use `artifacts` in command-template nodes; named artifact manifests belong to the template-recipe layer.
 
 ### Repeat
@@ -245,52 +206,7 @@ Repeat expressions support only integers, `index`, `prev`, `next`, `repeat`, par
 
 Repeat placeholders are local generated values. Call-time args should not use these reserved names to override the repeat index.
 
-Parallel nodes use the same object shape. Flags come first and `template` stays last:
-
-```json
-{
-  "template": [
-    "prepare {out_dir}",
-    {
-      "parallel": true,
-      "template": [
-        {
-          "label": "reviewer-a",
-          "timeout": 300000,
-          "template": "review-gpt {scope}"
-        },
-        {
-          "label": "reviewer-b",
-          "timeout": 300000,
-          "template": "review-deepseek {scope}"
-        },
-        {
-          "label": "kimi",
-          "timeout": 300000,
-          "template": "review-kimi {scope}"
-        }
-      ]
-    },
-    "merge {out_dir}"
-  ]
-}
-```
-
-A degraded parallel join is still usable when at least one branch succeeds:
-
-```text
---- branch: reviewer-a status: done ---
-review text
---- branch: reviewer-b status: failed ---
-exit: 1
-stderr: provider balance exhausted
-```
-
-Some local schemas may accept `pipe` as an alias, but the portable standard is `template: [...]`.
-
-## Fail-Open Default Policy
-
-By default, composition continues on failure: the failed step is logged and the next step executes. This is analogous to `make -k` — the user sees all failures at once and decides what to fix.
+Parallel children use the same object shape: flags come first and `template` stays last. A join remains usable when at least one branch succeeds and reports each branch label/status. Some local schemas may accept `pipe`, but the portable standard is `template: [...]`.
 
 ## Failure Propagation
 
@@ -302,33 +218,7 @@ Use `failure` when a node should stop more aggressively:
 - `"branch"`: stop the current sequence/subtree and return a failed branch to the nearest parent. In a parallel node, sibling branches keep running and the join becomes degraded. At the root, branch failure is still a tool failure.
 - `"root"`: abort the outermost composition.
 
-```json
-{
-  "parallel": true,
-  "template": [
-    {
-      "label": "agent-a",
-      "failure": "branch",
-      "template": [
-        "agent-a-work {scope}",
-        "agent-a-validate {scope}",
-        "agent-a-push {scope}"
-      ]
-    },
-    {
-      "label": "agent-b",
-      "failure": "branch",
-      "template": [
-        "agent-b-work {scope}",
-        "agent-b-validate {scope}",
-        "agent-b-push {scope}"
-      ]
-    }
-  ]
-}
-```
-
-If `agent-a-validate` fails, `agent-a-push` is skipped, `agent-b` can still finish, and the parallel join reports degraded branch coverage.
+A branch failure skips the remainder of that branch while parallel siblings can finish; their join reports degraded coverage.
 
 ## Retry
 

package/docs/recipe-library.md

@@ -1,212 +1,85 @@
-# Recipe Library
+# Packaged Recipe Library
 
-The root `recipes/` directory is the packaged standard actor recipe library for pi-actors. These recipes are reusable building blocks, not automatically installed operator policy. Copy or reference them from local tool registrations when the operator wants a durable callable tool.
+Packaged Recipes provide maintained execution graphs and service definitions. User Recipes with the same name shadow packaged definitions; invalid shadowing fails closed.
 
-Helper scripts that belong to library recipes live in root `scripts/`. The music player standard uses the executable Node.js wrapper only: `scripts/music-player.mjs`.
+## Recommended Entry Points
 
-## Layout
+### Repository and delivery
 
-- `recipes/subagent-*.json`: Atomic subagent components such as prompt launchers, reviewers, critics, planners, verifiers, mergers, checkpoints, follow-ups, judges, and normalizers.
-- `recipes/pipeline-*.json`: Higher-level composed recipes built from component imports.
-- `recipes/music-player.json`: Async local music player recipe backed by `scripts/music-player.mjs`.
-- `recipes/utility-*.json`: Small operator utility recipes that are not subagent coordinators.
+- `pipeline-repo-health.json` — repository inspection and bounded health artifact.
+- `pipeline-docs-maintenance.json` — documentation analysis and artifact preparation.
+- `pipeline-release-readiness.json` — release checks and readiness artifact.
+- `pipeline-release-summary.json` — release-summary artifact.
+- `pipeline-development-tasking.json` — task-card and implementation planning pipeline.
 
-## Install Locally
+### Review and synthesis
 
-Select only the operator-facing recipe or wrapper you intend to own locally. For example:
+- `pipeline-quorum-review.json` — parallel reviewers with quorum-oriented synthesis.
+- `pipeline-review-readiness.json` — review plus readiness stages.
+- `pipeline-research-synthesis.json` — evidence-oriented research synthesis.
+- `lens-swarm.json` — configurable repeated review lenses.
+- `subagent-review-coordinator.json` — lower-level review/verify/merge/judge composition.
 
-```bash
-mkdir -p ~/.pi/agent/recipes
-cp <repo>/recipes/pipeline-review-readiness.json ~/.pi/agent/recipes/
-```
-
-Do not bulk-copy `recipes/*.json`. The packaged library also contains internal composition stages, including `draft-review.json` and `tool-review.json`; the automatic-review runtime launches those selectors with fenced inputs and they must not become user-installed callable tools.
-
-A registered tool can instead point at one selected recipe path when a durable operator-facing name is useful. Prefer a thin wrapper for public defaults or policy rather than copying the wrapper's internal imports.
-
-## Async Subagent Components
-
-Core subagent recipes:
-
-- `recipes/subagent-prompt.json`: Start one prompt-driven subagent.
-- `recipes/subagent-tools.json`: Start a subagent with an explicit tool allowlist.
-- `recipes/subagents-prompts.json`: Run prompt fanout with one imported subagent component.
-- `recipes/subagent-preflight.json`: Tiny model/thinking/tool-policy smoke check before expensive fanout; failures surface `ACTOR_PREFLIGHT_FAILED` with stage, selected policy, provider error class, prompt file, and override args.
-- Packaged reviewer, verifier, merger, judge, and normalizer stages use `accept_output: review_evidence` and require `ACTOR_REVIEW_RESULT` as the exact first non-whitespace output line. Marker prefixes, format acknowledgements, and input requests therefore remain rejected branch diagnostics rather than usable quorum evidence.
-- `recipes/subagent-review.json`: Evidence-grounded review lens.
-- `recipes/draft-review.json`: Internal no-tools selector for one immutable automatic draft batch. It receives an attached value-free structural projection with batch-local opaque occurrence/content-group identities, counts, risk labels, and usage—not canonical names, draft basenames, raw hashes, recipe bodies, template text, defaults, authored prose, or filesystem paths—then emits one terminal `DRAFT_REVIEW_RESULT` with quota-free promote/discard decisions. The executor derives any promotion from the separate trusted captured source.
-- `recipes/tool-review.json`: Internal no-tools selector for one immutable 36-tool portfolio. It receives the same identity-opaque value-free structural projection and may recommend quota-free keep, unchanged-source rename (`evolve`), unchanged-source demote, or identical-source merge decisions. `replace`, `split`, and returned recipe content fail mechanically; deterministic executors alone read trusted captured recipes and own validated safe-boundary activation.
-- `recipes/subagent-critic.json`: Assumption and failure-mode critique.
-- `recipes/subagent-plan.json`: Bounded plan slices and validation gates.
-- `recipes/subagent-evidence-map.json`: Evidence and confidence map.
-- `recipes/subagent-contradiction-map.json`: Contradiction and missing-evidence map.
-- `recipes/subagent-verify.json`: Claim verification.
-- `recipes/subagent-merge.json`: Consensus/risk-first synthesis.
-- `recipes/subagent-normalize.json`: Stable output shaping.
-- `recipes/subagent-artifact.json`: Durable artifact-shaped output for a target path. It prepares content and write guidance; it does not write files unless the caller deliberately grants write tools or uses a deterministic writer.
-- `recipes/subagent-message.json`: Prompted actor-message-envelope-shaped coordinator message record with envelope-aligned args.
-- `recipes/subagent-quorum.json`: Same prompt across a model pool.
-- `recipes/subagent-task-card.json`: Bounded implementation task card.
-- `recipes/subagent-conflict-report.json`: Integrator-oriented conflict report.
-- `recipes/subagent-checkpoint.json`: Coordinator checkpoint artifact.
-- `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. Packaged recipes intentionally do not ship concrete model-version defaults: review-oriented subagent and lens-swarm recipes default model/thinking args through `{current_model}` and `{current_thinking}` so they inherit the selected Pi session policy, and callers can still pass explicit values when a run should diverge. Recipe inspection marks these inherited policy defaults as `current_policy`, and run status/progress records whether launch policy was inherited, explicit, mixed, or unresolved. 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.
-
-For one-off packaged subagent reviews, launch the recipe directly with `spawn file="subagent-review" values={...}` or `spawn file="pipeline-review-readiness" values={...}`. Do not copy the underlying `pi -p` command or wrap the recipe unless you are creating a durable operator tool with a narrower interface.
-
-For build-oriented swarms, prefer a consensus-first shape over parallel writers: proposer roles coordinate in a room with message/inspect tools, a named implementer owns the first artifact write, a QA reviewer inspects the result, and a finalizer applies review-grounded fixes before `run.done`. This pattern keeps creative/lens diversity while preserving one coherent artifact and gives recipes concrete artifact assertions instead of treating room discussion as success.
-
-Register one atom:
-
-```text
-register_tool name=subagent_prompt \
-  description="Start an async no-tools pi subagent" \
-  template="subagent-prompt.json"
-```
-
-Start it:
+Callers should own model, thinking, concurrency, quorum, and mission policy. Review pipelines preflight provider/model availability before expensive fanout.
 
-```text
-subagent_prompt prompt="Review docs/async-runs.md for unclear wording." run_id=docs_review
-inspect target=run:docs_review view=status
-inspect target=run:docs_review view=tail
-```
-
-## Composed Pipelines
-
-Pipeline recipes demonstrate second-order composition:
-
-- `recipes/coordinator-locker.json`: Long-lived coordinator cell with queue, acquire/renew/release lease locks, journal, actor messages for worker coordination, and platform-adapted control metadata.
-- `recipes/subagent-review-coordinator.json`: Model/tool preflight with compact provider diagnostics → quorum-aware lens reviewers → verifier → merger → judge → normalizer. Review pipelines expose `subagent_ttl_ms`, `reviewer_concurrency`, `min_successful_reviewers`, and `merge_policy` knobs; reviewer joins preserve partial evidence and mark `complete`, `degraded`, or `insufficient_data`. `npm run conformance` includes a fake-`pi` review-readiness dogfood fixture for this packaged path.
-- `recipes/pipeline-release-readiness.json`: Task-first release cell: changelog section → package summary → packaged skill summary → validation → release review → artifact report.
-- `recipes/pipeline-release-summary.json`: Evidence-only release summary cell: changelog section → package summary → packaged skill summary → validation → release summary / risks / PR body draft artifact. It does not commit, open a PR, merge, tag, publish, or perform external release side effects.
-- `recipes/pipeline-repo-health.json`: Task-first repository-health cell: git status/log → docs index → validation → normalized artifact report.
-- `recipes/pipeline-async-run-ops.json`: Task-first async-run operations cell: run summary → actor-message tail → normalized operations report → artifact report.
-- `recipes/pipeline-review-readiness.json`: Release/readiness gate over selected lenses.
-- `recipes/pipeline-quorum-review.json`: Quorum vote shape → merge → judge → normalize.
-- `recipes/pipeline-architect-coordinator.json`: Architecture lens fanout → critique → verification → synthesis → next slice.
-- `recipes/pipeline-research-synthesis.json`: Plan → evidence map → contradiction map → verification → synthesis.
-- `recipes/pipeline-checkpoint-continuation.json`: Checkpoint → follow-up → normalized handoff.
-- `recipes/pipeline-development-tasking.json`: Plan → task card → critique → integrator handoff.
-- `recipes/pipeline-docs-maintenance.json`: Docs index → documentation review → maintenance plan → artifact report.
-- `recipes/pipeline-media-library.json`: Playlist build → media-library artifact report.
-- `recipes/pipeline-room-swarm.json`: Room participants join `room:<run>`, coordinate over repeated room-visible rounds, leave cleanly, and synthesize the room transcript into a caller-provided artifact path. Supported coordinator modes are `consensus`, `pipeline`, `fanout`, and `pool`; unknown modes fail closed instead of silently running consensus. Keep model/thinking/mission policy caller-owned. Custom roles can be supplied with `roles_path` as a JSON array of `{ "name", "persona" }` objects; `name` stays ASCII-safe for `branch:<run>/<name>` addresses and debugger output remains plain and name-driven. The packaged swarm uses contacts for peer awareness but does not rely on direct branch delivery unless a caller-specific worker protocol consumes branch envelopes. Set `subagent_ttl_ms` to a positive millisecond budget when participant `pi -p` processes must be killed instead of awaited indefinitely. Set `locker=true` to compose a local `coordinator-locker` cell under `{state_dir}/locker` for artifact ownership, resource lease locks, and a decision journal without merging locker policy into the room-participant script.
-- `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.
-
-## Utility Recipes
-
-Utility recipes cover local operator workflows that do not need subagents:
-
-- `recipes/utility-markdown-index.json`: List Markdown files in a directory as input for README/docs index maintenance.
-- `recipes/utility-jsonl-tail.json`: Tail a JSONL message/log file with a configurable line count.
-- `recipes/utility-validation-wrapper.json`: Run a caller-supplied validation command in a scoped directory with a bounded timeout. This intentionally crosses a trusted shell boundary; discovery surfaces it as a diagnostic, and callers should pass explicit validation commands only.
-- `recipes/utility-git-status.json`: Read concise branch/worktree state for a repo.
-- `recipes/utility-git-log.json`: Read recent decorated commit history for a repo.
-- `recipes/utility-run-state-files.json`: List run-state files such as `run.json` under an async run state root.
-- `recipes/utility-coordinator-lock-snapshot.json`: Summarize a coordinator-locker actor state directory with queue depth, locks, and recent journal entries.
-- `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, recent actor messages for a selected `run_id`, 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.
-- `recipes/utility-artifact-write.json`: Deterministically write prepared artifact content from stdin to `artifact_path` with explicit `create`, `overwrite`, or `append` mode.
-- `recipes/utility-actor-message.json`: Deterministically wrap stdin as a validated addressed actor-message envelope with the same public names as the envelope: `to`, `from`, `type`, `summary`, `body`, optional `correlation_id`/`reply_to`, and `metadata`.
-- `recipes/utility-package-summary.json`: Use `scripts/recipe-utils.mjs` to emit bounded package metadata such as name, version, files, scripts, and dependency counts.
-- `recipes/utility-skill-summary.json`: Use `scripts/recipe-utils.mjs` to summarize packaged skill frontmatter, body shape, formatter-safe scalar lines, and package-version alignment.
-- `recipes/utility-validate-recipe.json`: Use `scripts/validate-recipe.mjs` to validate one template recipe file, or all packaged recipes in a directory with `all: true`.
-
-Packaged QA is available through the `recipes:qa` npm script. It reports description warnings and fails exact diagnostics for async mailbox contracts, termination vocabulary, artifact paths, platform scope, helper script paths, and missing helper scripts.
-
-These recipes are intentionally small. Register them only for trusted local commands and prefer narrow scopes. Discovery diagnostics flag obvious trust-boundary shapes such as shell/eval/destructive commands; those warnings are operator review aids, not a sandbox. The helper-backed utilities share `scripts/recipe-utils.mjs` so repeated parsing/listing logic stays out of recipe strings.
-
-## Actor OS Smoke Matrix
-
-The repeatable smoke surface is the normal validation suite:
-
-```text
-npm test
-```
+### Artifacts
 
-The scenario coverage is intentionally local-first and bounded: shared room coordination and roster snapshots (`rooms` / `tools` tests), direct branch delivery and claim/handle transitions (`tools` and coordinator tests), inspector navigation (`inspector` tests), recipe context injection (`recipes-context` / async-runs tests), compact terminal follow-up delivery (`observability` tests), and opt-in retirement candidate/execution smoke (`observability` / async-runs tests). These scenarios exercise public `spawn` / `message` / `inspect` behavior or the packaged script surfaces rather than relying on manual swarm demos.
+- `pipeline-artifact-report.json` — prepare one artifact body.
+- `pipeline-artifact-write.json` — prepare and deterministically write an artifact.
+- `pipeline-artifact-bundle.json` — optional validation, artifact write, manifest generation, and manifest write.
+- `utility-artifact-write.json` — deterministic create/overwrite/append helper.
+- `utility-artifact-manifest.json` — artifact manifest generation.
 
-## Music Player
+Artifact pipelines terminate in files/manifests and result evidence; they do not fabricate communication events.
 
-Files:
+### Controlled services
 
-- `recipes/music-player.json`
-- `scripts/music-player.mjs`
+- `music-player.json` — playback service with declared playback actions, `controls.jsonl`, generation-fenced endpoint readiness, state artifact, and playback Trace. Player selection is `player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)=auto`.
+- `resource-locker.json` — optional queue/lease-lock service with explicit owner/resource input and lock Trace.
 
-Purpose: start a local or URL audio source as an async run so the agent can continue working while playback runs in the background. The running script exposes a run-local mailbox, so addressed `message` calls can control playback without a second recipe.
+These are the packaged Recipes that declare actor-local Control. Ordinary one-shot Recipes omit it. Helper-backed packaged Recipes self-locate their installed package root when `repo` is omitted; an explicit caller value still wins for development or custom layouts.
 
-Requirements: Node.js and one playback backend. Supported backends are `mpv`, macOS `afplay`, `ffplay`, `cvlc`, SoX `play`, or `wmp` on native Windows through the legacy Windows Media Player COM control exposed by `powershell.exe`. The `wmp` backend validates `wmplayer.exe` under `Program Files/Windows Media Player` or `Program Files (x86)/Windows Media Player`; it does not target the newer UWP/Store Media Player. Playback format support depends on the selected player; the actor control path itself uses the portable mailbox/wake runtime layer.
+## Component Recipes
 
-The required `source` arg accepts:
+Subagent components provide reusable command-template cells for normalization, planning, evidence mapping, contradiction analysis, criticism, review, verification, merging, judging, quorum work, task cards, checkpoint prompts, and artifact generation.
 
-- A single local file or URL.
-- A directory containing audio files; the wrapper scans `.aac`, `.aif`, `.aiff`, `.flac`, `.m4a`, `.mp3`, `.ogg`, and `.wav` files.
-- An `.m3u`, `.m3u8`, or `.txt` playlist file.
-- A `|`-separated inline list of local files or URLs.
+Imports compose these definitions inside one parent Run. They are not independently addressable peers. Parent template flags control sequencing, parallelism, retries, failure scope, recovery, and repeated execution.
 
-Install locally:
-
-```bash
-mkdir -p ~/.pi/agent/recipes
-cp <repo>/recipes/music-player.json ~/.pi/agent/recipes/music-player.json
-```
+## Utility Recipes
 
-Register playback:
+Utilities wrap deterministic local capabilities such as:
 
-```text
-register_tool name=music_player \
-  description="Start async music player playback through the Node.js wrapper" \
-  template="music-player.json" \
-  args="source:string,loop:bool=true,volume:int=70,player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)=auto"
-```
+- package and skill summaries;
+- artifact writes/manifests;
+- validation commands;
+- Run operations snapshots;
+- Recipe validation.
 
-Start playback:
+Use utilities as imported cells or registered tools where their contract fits.
 
-```text
-music_player source="~/Music" volume=55 run_id=music
-```
+## Selection Guidance
 
-Control it through addressed actor messages. This is the canonical reactive pattern for long-lived recipes: the run emits actor messages upward, and the coordinator sends explicit commands downward instead of polling on a timer.
+1. Prefer the highest-level maintained pipeline matching the task.
+2. Use component Recipes when building a new stable pipeline.
+3. Use inline templates for genuinely one-off trusted work.
+4. Declare artifacts for outputs that callers must retain.
+5. Declare Control only when a service process actually consumes it.
+6. Keep large semantic evidence in artifacts or execution captures, not Trace summaries.
 
-```text
-message to=run:music type=player.pause body=pause
-message to=run:music type=player.play body=play
-message to=run:music type=player.next body=next
-message to=run:music type=player.previous body=previous
-message to=run:music type=player.stop body=stop
-```
+## Installation Safety
 
-Use `inspect target=run:music view=status` only when an actor message or operator decision requires inspection.
+Do not bulk-copy `recipes/*.json` into the user Recipe root. Internal `draft-review.json` and `tool-review.json` support fenced automatic review and must not become user-installed callable tools. Register or wrap only the specific public capability you intend to use.
 
-The wrapper also accepts control commands directly when a caller already has the run state dir:
+## Validation
 
-```text
-scripts/music-player.mjs next ~/.pi/agent/tmp/pi-actors/runs/music
+```bash
+npm run recipes:qa
 ```
 
-Message body is queued in the recipe's run-local mailbox and reconciled by the player loop. The loop treats `wake.jsonl` and `fs.watch` as advisory signals, then verifies the durable inbox signature before taking the inbox lock so unchanged mailboxes are not reread on every tick. Backend players stay inside the async run process group so `control.kill` terminates active playback with the run instead of leaving detached player children alive; player-local pause/resume/next/stop controls still signal the current backend pid or process group when available. The script writes `status.txt`, `player.json`, and track-change actor messages in the same state dir. Track-change messages stay diagnostic by default; interactive recipes should define a small command vocabulary for addressed messages, emit semantic actor messages for decision points, and let the coordinator react to messages rather than sleep-polling state.
-
-Cross-platform smoke checklist:
-
-- Linux: install one backend such as `mpv` or `ffplay`; start `music_player source="~/Music" run_id=music`, send `pause`, `play`, `next`, and `stop`, then inspect `run:music` status/mailbox.
-- macOS: verify `player=auto` selects `afplay` when no preferred CLI backend is installed, then run the same addressed message controls.
-- Native Windows: verify `player=wmp` detects `wmplayer.exe`, starts playback through Windows Media Player COM, handles `pause`/`play`/`next`/`previous`/`stop`, and leaves handled mailbox records visible through `inspect target=run:music view=mailbox`.
-- All hosts: confirm missed wake resilience by checking that queued mailbox commands are eventually claimed without relying on a transport-specific endpoint.
+Recipe QA validates syntax, imports, Control declarations, artifact paths, helper references, and platform documentation. Recipe descriptions are optional because discovery supplies stable fallback tool copy; internal component Recipes do not need boilerplate. The packaged baseline requires zero diagnostics and zero warnings, and any future warning is release-blocking with its concrete file and repair. Removed mailbox declarations fail with the migration diagnostic rather than receiving automatic conversion.
 
-## Safety Notes
+## Related
 
-- 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=control.kill` for runtime termination; `control.stop` is a player-domain pause/stop command, not a generic run-kill alias.
+- [Template Recipes](./template-recipes.md)
+- [Command templates](./command-templates.md)
+- [Runs](./async-runs.md)

package/docs/releasing.md

@@ -0,0 +1,28 @@
+# Release Operations
+
+Stable releases use one immutable tag workflow. The workflow runs the complete reusable Ubuntu, macOS, Windows, and dependency-audit boundary before any publication, publishes and verifies the exact npm package through Trusted Publisher, then creates or converges the GitHub Release from the matching changelog section.
+
+## One-time npm Trusted Publisher setup
+
+Configure the existing public package `@llblab/pi-actors` on npmjs.com with a GitHub Actions Trusted Publisher using these exact values:
+
+- **Owner:** `llblab`
+- **Repository:** `pi-actors`
+- **Workflow filename:** `release.yml`
+- **Environment:** Leave empty unless the workflow and npm configuration later adopt the same named GitHub environment in one reviewed change.
+
+The binding must target `.github/workflows/release.yml`; npm asks for the filename rather than the repository-relative path. npm does not verify this identity when the setting is saved, so the first tagged publication provides the decisive proof.
+
+Do not create `NPM_TOKEN`, `NODE_AUTH_TOKEN`, or another long-lived npm publish secret. The publication job runs on a GitHub-hosted Ubuntu runner with `id-token: write`, Node 24, npm 11.5.1 or newer, the public npm registry, and package-manager caching disabled at the credential-bearing boundary.
+
+## Release sequence
+
+1. Merge the validated release tree through the repository's guarded `dev` to `main` flow.
+2. Create one immutable `v<package.version>` tag on the verified `main` commit.
+3. Let `.github/workflows/release.yml` invoke the complete reusable validation workflow.
+4. Let the publication job verify the tag commit, package manifests, and non-empty changelog section.
+5. Publish the exact public npm package through OIDC when the version does not exist.
+6. Verify npm version, `gitHead`, Pi extension/skill metadata, and packed runtime manifests.
+7. Create or update the GitHub Release only after npm verification succeeds.
+
+A rerun skips `npm publish` only when the exact existing version reports the same tagged `gitHead`; contradictory identity fails closed because npm versions are immutable. Registry lookup retries remain bounded. A missing or mismatched Trusted Publisher usually surfaces as npm authentication or not-found failure and must be corrected in npm package settings—never by adding a token fallback.