@llblab/pi-actors 0.14.2 → 0.15.0

package/AGENTS.md

@@ -17,7 +17,9 @@
 - `/lib/*.ts`: Flat Domain DAG modules for cohesive reusable behavior; `command-templates.ts` mirrors the shared portable command-template standard, `schema.ts` owns tool arg declarations and placeholder-derived tool schemas, `identity.ts` owns names, `config.ts` owns config persistence, `registry.ts` owns registry register/update/delete use-cases, `output.ts` owns result formatting/truncation, `execution.ts` owns registered-tool execution, `recipe-references.ts` owns template recipe reference detection and path resolution, `async-runs.ts` owns async run state, `observability.ts` owns ambient run summaries, `temp.ts` owns pi-agent temp cleanup, `prompts.ts` owns LLM-facing copy, `tools.ts` owns pi-facing tool definitions for both `register_tool`, async run primitives, and generated runtime tools, `runtime.ts` owns load/conflict/registration coordination, and `paths.ts` owns config/tmp path resolution
 - `index.ts` should import local domains as namespaces (`import * as CommandTemplates from "./lib/command-templates.ts"`) so orchestration reads through domain names instead of flat helper imports
 - `/scripts/*.mjs`: Thin helper processes for detached async run execution; keep policy in registered tool config and reusable logic in `/lib`
-- `/recipes/*.json`: Packaged standard recipe library; keep recipes optional, composable, and policy-light; prefer public args/defaults for operator/agent decisions instead of baking project-specific prompts or file names into reusable recipes
+- `/recipes/*.json`: Packaged standard recipe library; keep recipes optional, composable, and policy-light; prefer public args for operator/agent decisions instead of baking project-specific prompts, file names, or concrete model-version defaults into reusable recipes
+- `/skills/actors/SKILL.md`: Dense practical reference for operating pi-actors itself
+- `/skills/swarm/SKILL.md`: Bundled methodology skill for multi-agent standards, strategies, and portable examples; keep it theory/strategy-oriented while pi-actors recipes/scripts provide the local execution engine
 - `/scripts/music-player.mjs`: Standard helper script for the packaged music-player recipe; keep it executable and avoid restoring parallel shell-wrapper variants unless a concrete portability need appears
 - `/tests/*.test.ts`: Focused regression tests for pure domains
 - `/README.md`: Human-facing install, usage, and runtime semantics
@@ -35,6 +37,7 @@
 
 ## Durable Conventions
 
+- `Knowledge surface separation`: pi-actors has distinct knowledge surfaces with different context-entry behavior: injected prompt is always present and should stay a tiny bootstrap/reminder; packaged `actors` skill is auto-matched by name/description and should signal that its body is the highest-density practical guide for operating the extension plus the shortest navigator to bundled recipes; packaged `swarm` skill is auto-matched for multi-agent methodology, strategies, standards, and portable examples; README is the human entrypoint explaining concept, rhythm, benefits, and scenarios but is not automatically in context; `/docs` are detailed transportable standards read on demand; `AGENTS.md` is project context and architectural constraints for agents changing the repo | Trigger: Editing prompt copy, README, docs, skills, or project context | Action: Keep each surface on its own wave, avoid duplicating prompt and skill headers, keep the actors skill recipe navigator compact and concrete, avoid duplicating scenario catalogs or changelog narratives in the actors skill, avoid turning the prompt into docs, keep multi-agent methodology in swarm-oriented guidance rather than the actors skill, keep packaged extension skill metadata versions synchronized with `package.json` version, and avoid extra colons in skill frontmatter scalar lines because skill formatters treat them poorly
 - `Tool registry source`: `~/.pi/agent/actors-tools.json` is the persistent user config | Trigger: Any runtime registration or migration work | Action: Preserve atomic writes and avoid hidden format changes without an explicit migration path
 - `Current runtime contract`: Register trusted command templates with tool names from registry keys, placeholder-derived args, progressive typed arg declarations, inline/default/`??`/ternary config fallback, placeholder-derived numeric node controls, split-first command-arg construction, sequential or `parallel: true` composition, direct no-shell execution, optional per-node `when`, optional per-node positive `timeout` disabled by default, lightweight warnings for obvious trusted-executable risk shapes, per-node `delay`, bounded leaf/node `retry`, `failure: "continue|branch|root"` propagation, `recover` cleanup between retry attempts, template recipes with explicit `async: true` detached mode, actor-oriented `spawn`/`message`/`inspect` tools with run-local JSONL outbox messages, Unix FIFO send, graceful cancel, and force kill, generic detached run primitives with process-group cancellation, injected async `{run_id}` and `{state_dir}` values, coordinator-scoped event-driven observability with at least one triangle per active async run and extra triangles for active parallel branches, runtime-inferred `command.done` bubbling for packaged multi-agent fanout, named recipe `artifacts`, recipe `mailbox` metadata, terminal follow-ups for `done`/`failed`/unhandled `killed`/`exited` states, `template` recipe references, recipe-layer `imports`, co-located recipe entries, `~/.pi/agent/recipes/*.json` template recipe files, run state under `~/.pi/agent/tmp/pi-actors/runs`, and `{file}` as the canonical local file path arg | Trigger: Changing registration or invocation behavior | Action: Keep README, command-template docs, template-recipe docs, async-run docs, actor-message docs, implementation, and migration notes aligned
 - `Typed arg authoring`: Typed args support `string`, `path`, `int`, `number`, `bool`, and `enum(...)` plus two equivalent readability styles: metadata-first (`args` + `defaults` + simple `{name}` placeholders) for long command lines, and inline-first (`{name:type=default}` placeholders) for compact one-property templates | Trigger: Changing arg parsing, docs, schema generation, or registry serialization | Action: Preserve both styles, keep explicit `args` type declarations higher priority than inline placeholder types, and make breaking cleanup explicit when removing old arg shapes
@@ -47,6 +50,7 @@
 - `Communication direction`: The design target is an organic universal message layer across sync tasks, async runs, branches, tools, and coordinators. Breaking changes are allowed to compress concepts, remove accidental duplication, and make duplex communication symmetric where the domain is symmetric. | Trigger: Designing APIs or recipes that communicate | Action: Prefer a concentrated actor/message protocol (`spawn`, `message`, `inspect`, addressed endpoints, typed message envelopes, mailbox accepts/emits) over exposing FIFO/outbox/status mechanics directly; use one envelope for upward, downward, lateral, parent/branch, and branch/parent messages; absorb runtime async primitives into actor API instead of preserving parallel public concepts.
 - `Output discipline`: Tool stdout is returned with bounded context impact | Trigger: Changing execution or formatting | Action: Keep tail truncation, full-output temp files, and failure formatting intact
 - `Extension temp directory`: Temporary runtime files belong under `~/.pi/agent/tmp/pi-actors`; session start prepares the directory and prunes stale entries | Trigger: Adding temp files, run state, logs, or artifacts | Action: Do not use system tmp for extension-owned state unless the operator explicitly overrides a path
+- `Backlog is planning, not history`: `BACKLOG.md` should contain current/future work, blockers, gates, and next leverage points; completed delivery history belongs in `CHANGELOG.md`, and durable behavior belongs in README/docs | Trigger: Editing backlog or reconciling completed slices | Action: Remove historical progress narratives, keep current task/scope/exit criteria, and prefer an 80/20 focus list when many remaining tasks compete for attention
 - `Context sync`: Meaningful implementation or docs changes must reconcile `BACKLOG.md`, `CHANGELOG.md`, README, and docs navigation | Trigger: Closing, narrowing, or discovering work | Action: Run the context validator before final status when practical
 - `Public path hygiene`: Published docs must not include machine-local absolute paths | Trigger: Adding validation commands, examples, or local instructions to README/AGENTS/docs/changelog | Action: Use `~/.pi/...`, `<repo>/...`, `${SKILL_DIR}/...`, or relative paths
 

package/BACKLOG.md

@@ -2,38 +2,24 @@
 
 ## Open Work
 
-Continue progressive component/pipeline expansion in small validated slices; real smoke runs remain gated. Prefer task-first design for new high-level recipe families: start from operator/coordinator work patterns, then derive missing component cells.
-
-- 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` 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 uses actor-native `control.stop`/`control.cancel`/`control.kill` without runtime-prefixed control aliases, async command events preserve full argv details while keeping coordinator summaries bounded, async-run operations recommendations now emit structured `message`/`inspect` objects instead of shell-like suggestion strings, `inspect view=messages` exposes run actor messages and `inspect view=events` has been removed as a compatibility alias, async-run operations recipes now expose `message_file`/`messages` terminology instead of public event-file args, and operator-facing docs now describe coordination with actor-message terminology before transport details, async-run docs separate public actor behavior from storage/transport mechanics more clearly, public actor-message/template guidance avoids transport-specific wording, and async-run operations recipes now use only `message_file` for actor-message inputs, interactive recipe mailboxes now advertise actor-native termination controls where the runtime already supports them, task-first/library docs now describe operations snapshots in terms of actor-message tails instead of event tails, and `inspect view=events` has been removed from the public inspect surface in favor of `inspect view=messages`. 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.
-  - Exit: The project exposes documented high-level universal communication primitives for starting work, sending messages, and inspecting state; packaged recipes/examples use the organic interface; async send/outbox behavior is intentionally migrated into actor-message coverage; all recipes validate and docs describe the actor/message model clearly.
-
-- 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`, `pipeline-media-library`, and `pipeline-artifact-bundle` landed. `pipeline-release-readiness` now includes package-summary evidence before validation/review. `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; `utility-run-ops-snapshot` landed for async-run summaries, actor-message 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.
+No open release-blocking work remains for `0.15.0`.
+
+The former active tracks are now release-ready:
+
+- Universal actor communication: public guidance centers `spawn`, `message`, `inspect`, actor messages, mailbox contracts, and artifacts; low-level lifecycle/storage wording is confined to implementation/diagnostic docs.
+- Component parameterization and composition: packaged recipes are policy-light, require caller-provided model/model-pool policy, expose reusable knobs, validate imports/mailboxes, and are covered by the actors Recipe Navigator.
+- Structured utility transforms: current utility surface is sufficient for shipped pipelines; add future utilities only when a repeated packaged-pipeline need appears.
+
+## Future Work
+
+- Add new utilities or pipelines only when a concrete repeated task pattern justifies them.
+- Continue opportunistic actor-vocabulary cleanup when touching implementation docs or diagnostics.
 
 ## Blocked Work
 
-- Validate branch-local checkpoint semantics with collaborative-runner experiments.
-  - Priority: Low.
-  - Blocked by: At least one real collaborative branch-runner async-run experiment.
-  - Scope: Use real collaborative branch-runner async runs to validate whether `failure: "branch"`, node-level `retry`, and `recover` cleanup are sufficient for branch-local validation and bounded reattempts.
-  - Exit: Decision recorded as sufficient, documentation-only refinement needed, or propose a further minimal command-template extension with tests.
+### Branch-Local Checkpoint Semantics
+
+- Priority: Low.
+- Blocked by: At least one real collaborative branch-runner async-run experiment.
+- Scope: Validate whether `failure: "branch"`, node-level `retry`, and `recover` cleanup are enough for branch-local validation and bounded reattempts.
+- Exit: Record one decision: sufficient, documentation-only refinement needed, or propose one minimal command-template extension with tests.

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.15.0: Packaged Actors Skill And Actor Vocabulary Cleanup
+
+- `[Skill]` Reworked the packaged `actors` skill as a dense self-contained extension reference rather than a scenario catalog or changelog narrative, bundled the `swarm` methodology skill alongside it, synchronized packaged skill metadata versions with the package version, included `skills/` in the npm package contents, registered both skills in package metadata, and linked them from the README start points. Impact: fresh agents get compact practical coverage of pi-actors operation plus complementary multi-agent methodology without duplicating the two roles.
+- `[Prompts]` Tightened the injected onboarding prompt into a shorter runtime bootstrap/reminder that avoids duplicating the skill and notes that README/docs are not automatically in context. Impact: session context stays compact while preserving operational lookup paths.
+- `[Context]` Added a durable knowledge-surface separation convention for prompt, skill header/body, README, docs, and `AGENTS.md`. Impact: future edits have a clear role model for where each kind of pi-actors knowledge belongs and how it reaches the agent context.
+- `[Backlog]` Reconciled task-first pipeline notes with the release-summary/review pipeline candidate in abstract terms. Impact: future pi-actors work can explore evidence preparation without tying the backlog to one completed release pass.
+- `[Actor Tools]` Changed compact `inspect view=messages` and `message` tool output to use actor-message wording instead of public `event`/`delivery`/`outbox` labels. Impact: default tool output now reinforces the actor vocabulary while verbose JSON still exposes implementation details for diagnostics.
+- `[Skill]` Reworded the packaged skill description to avoid extra frontmatter colons and replaced the compact two-branch Core Nouns sketch with an explicit two-path flow. Impact: skill metadata stays formatter-safe and the template→recipe→run versus template/recipe→tool relationship is easier to read.
+- `[Recipe Library]` Added `utility-skill-summary` and routed `pipeline-release-readiness` through packaged skill evidence between package summary and validation. Impact: release readiness reports can verify skill metadata/package-version alignment, formatter-safe frontmatter, body size, and heading shape alongside changelog/package/validation evidence.
+- `[Recipe Library]` Changed async-run operations recipes from public `message_file` inputs to `run_id` inputs, with the helper resolving implementation storage internally. Impact: packaged recipes no longer expose outbox paths as part of their public actor-operations surface.
+- `[Recipe Library]` Added `coordinator-locker`, a long-lived actor recipe backed by `scripts/coordinator-locker.mjs` that manages a FIFO work queue, acquire/renew/release resource lease locks, a journal, and coordinator-directed actor messages, plus `utility-coordinator-lock-snapshot` for state inspection. Impact: future coordinated fanout recipes have a small local coordination cell instead of baking ad hoc queue/lock mechanics into each pipeline.
+- `[Skill]` Clarified the actors skill's relationship to methodology skills and expanded it with a linked Recipe Navigator covering bundled coordination/service recipes, subagent atoms, pipelines, and utilities. Impact: the actors skill is now both the extension operation reference and the shortest agent-facing path to concrete packaged recipe files.
+- `[Recipe Library]` Standardized all packaged async recipes to advertise `control.stop`, `control.cancel`, and `control.kill` in mailbox accepts. Impact: `inspect view=mailbox` now exposes the actor-native termination contract consistently across subagent atoms, coordinator cells, music, and pipelines.
+- `[Recipe Library]` Removed concrete model-version defaults from packaged recipes, removed stale concrete model aliases from operator/docs examples, and added regressions that reject model-like defaults or provider/version aliases in recipe defaults and stale concrete model aliases in public guidance. Impact: reusable components stay policy-light and force the caller/agent to choose current model policy at launch instead of inheriting stale packaged aliases.
+- `[Context]` Recompressed `BACKLOG.md` around current/future work only, added an 80/20 focus section for the remaining actor-vocabulary, recipe-policy, release-evidence pipeline, and utility-growth work, and promoted the backlog-is-planning rule into `AGENTS.md`. Impact: completed history stays in the changelog/docs while the backlog remains an actionable planning surface.
+- `[Recipe Library]` Added `pipeline-release-summary`, an evidence-only release preparation pipeline that composes changelog, package, skill, and validation evidence into a release summary, risk checklist, and PR body draft artifact without commit, PR, merge, tag, publish, or other external release side effects. Impact: release-prep artifacts can be produced under pi-actors while gated release actions remain owned by release workflows.
+- `[Docs]` Reworded remaining public README examples and the async-run operations pipeline prompt toward run-actor vocabulary instead of presenting async-run lifecycle wording as the primary operator concept. Impact: public guidance continues converging on `spawn`, `message`, `inspect`, and actor runs while low-level lifecycle language stays in implementation docs.
+- `[Context]` Closed the active `0.15.0` backlog by moving completed actor-communication, component-policy, and utility-surface work out of open planning, leaving only future opportunistic work and the blocked branch-runner experiment. Impact: the release backlog now reflects no open release-blocking work.
+- `[Skill]` Consolidated the bundled `swarm` methodology skill boundary by removing concrete pi-actors adapter examples and duplicate adapter/component docs from Swarm, keeping detailed MAWP mechanics in the dedicated reference instead of duplicating them in the general skill, and adding regressions that packaged Swarm markdown must not mention pi-actors runtime identifiers, package metadata must register every packaged skill, packaged skill markdown links must resolve, and the actors Recipe Navigator must link every bundled recipe file. Impact: Swarm can live inside this package while remaining portable methodology, and actors remains the shortest concrete path to packaged recipes.
+
+## 0.14.3: Pipeline Termination Mailbox Consistency
+
+- `[Recipe Library]` Added `control.cancel` and `control.kill` mailbox accepts to packaged async pipeline recipes that previously advertised only `control.stop`. Impact: `inspect view=mailbox` now exposes the full actor-native termination set consistently across high-level pipeline actors.
+- `[Tests]` Expanded packaged recipe coverage so all async `pipeline-*` recipes must expose `control.stop`, `control.cancel`, and `control.kill`. Impact: future pipeline recipes cannot silently regress to partial termination mailbox contracts.
+
 ## 0.14.2: Release Readiness Package Evidence
 
 - `[Recipe Library]` Added `utility-package-summary` evidence to `pipeline-release-readiness` between changelog extraction and validation. Impact: release readiness reports can consider package metadata and package contents summary without adding publish automation.

package/README.md

@@ -12,6 +12,9 @@ The persistent tool registry is still useful: it lets agents keep durable operat
 - [Open Backlog](./BACKLOG.md)
 - [Changelog](./CHANGELOG.md)
 - [Documentation](./docs/README.md)
+- [Actors skill](./skills/actors/SKILL.md) — dense agent-facing reference for operating the extension
+- [Swarm skill](./skills/swarm/SKILL.md) — multi-agent methodology, strategies, standards, and portable examples for actor-backed swarms
+- [Swarm MAWP notes](./skills/swarm/references/development-swarm.md) — optional small-team development swarm reference
 
 ## What It Is
 
@@ -129,9 +132,7 @@ Move to actor recipes when work is long-running, parallel, service-like, or agen
   "name": "docs-review",
   "async": true,
   "args": ["scope:path", "model:string"],
-  "defaults": {
-    "model": "openai-codex/gpt-5.5"
-  },
+  "defaults": {},
   "mailbox": {
     "accepts": ["control.stop"],
     "emits": ["review.completed", "run.failed"]
@@ -143,14 +144,14 @@ Move to actor recipes when work is long-running, parallel, service-like, or agen
 Expose a reusable actor recipe as a normal capability:
 
 ```text
-register_tool name=docs_review description="Start an async docs review actor" template="docs-review.json" args="scope:path,model:string=openai-codex/gpt-5.5"
+register_tool name=docs_review description="Start an async docs review actor" template="docs-review.json" args="scope:path,model:string"
 ```
 
 `Task` is the user's work item. `Template` is the execution graph. `Actor recipe` is saved JSON. `Run` is one actor instance with status, logs, messages, cancellation, artifacts, and ambient triangles.
 
 ## Compose Recipes With Imports
 
-Recipes can import other recipe files and reuse them as named nodes. This keeps reusable steps small while letting a parent recipe decide whether the combined graph runs foreground or as one async run.
+Recipes can import other recipe files and reuse them as named nodes. This keeps reusable steps small while letting a parent recipe decide whether the combined graph runs foreground or as one detached run actor.
 
 `review-one.json`:
 
@@ -158,7 +159,7 @@ Recipes can import other recipe files and reuse them as named nodes. This keeps
 {
   "name": "review-one",
   "args": ["scope:string", "model:string"],
-  "defaults": { "model": "openai-codex/gpt-5.5" },
+  "defaults": {},
   "template": "pi -p --model {model} --no-tools \"Review {scope}\""
 }
 ```
@@ -189,7 +190,7 @@ register_tool name=review_pair \
   template="review-pair.json"
 ```
 
-Imported recipes are recipe definitions, not nested async runs. The parent recipe's `async: true` creates one run with one state dir; imported recipes contribute command-template graph, args, defaults, and values.
+Imported recipes are recipe definitions, not nested run actors. The parent recipe's `async: true` creates one run actor with one state dir; imported recipes contribute command-template graph, args, defaults, and values.
 
 ## Register Actor-Control Tools
 
@@ -213,7 +214,7 @@ For reusable actor workflows, keep the large template and mailbox contract in a
 register_tool name=docs_review \
   description="Start an async docs review actor" \
   template="docs-review.json" \
-  args="scope:path,model:string=openai-codex/gpt-5.5"
+  args="scope:path,model:string"
 ```
 
 If the recipe file contains `async: true`, calling `docs_review` starts a detached run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
@@ -226,7 +227,8 @@ A recipe can also be co-located in `actors-tools.json` when keeping metadata and
     "description": "Start an async docs review",
     "name": "review-docs",
     "async": true,
-    "template": "pi -p --model openai-codex/gpt-5.5 --tools read,bash \"Review {scope}\""
+    "args": ["scope:path", "model:string"],
+    "template": "pi -p --model {model} --tools read,bash \"Review {scope}\""
   }
 }
 ```
@@ -238,7 +240,7 @@ A co-located recipe entry still cannot define `tool`; it must own `template` dir
 ```text
 register_tool name=call_subagent \
   description="Run pi as a non-interactive sub-agent" \
-  template="pi -p --model {model=openai-codex/gpt-5.5} --no-tools {prompt}"
+  template="pi -p --model {model} --no-tools {prompt}" args="prompt:string,model:string"
 ```
 
 Use `update=true` to overwrite an existing tool. Omit `template` during update to keep the previous template:
@@ -267,11 +269,12 @@ The commands above persist entries like this in `~/.pi/agent/actors-tools.json`;
   },
   "call_subagent": {
     "description": "Run pi as a non-interactive sub-agent",
-    "template": "pi -p --model {model=openai-codex/gpt-5.5} --no-tools {prompt}"
+    "args": ["prompt:string", "model:string"],
+    "template": "pi -p --model {model} --no-tools {prompt}"
   },
   "docs_review": {
     "description": "Start an async docs review actor",
-    "args": ["scope:path", "model:string=openai-codex/gpt-5.5"],
+    "args": ["scope:path", "model:string"],
     "template": "docs-review.json"
   }
 }
@@ -288,9 +291,10 @@ Start from an inline template as an addressable run actor:
 ```json
 {
   "as": "run:docs-review",
-  "template": "pi -p --model openai-codex/gpt-5.5 --no-tools {prompt}",
+  "template": "pi -p --model {model} --no-tools {prompt}",
   "values": {
-    "prompt": "Review docs/spec.md for contradictions."
+    "prompt": "Review docs/spec.md for contradictions.",
+    "model": "current-review-model"
   }
 }
 ```
@@ -313,7 +317,7 @@ Reusable local recipes live in `~/.pi/agent/recipes/*.json`; recipe tools honor
 
 Packaged standard recipes live under root `recipes/` with helper scripts under root `scripts/`. They are reusable library definitions, not automatically installed operator policy.
 
-The subagent component recipes start non-interactive pi subagents as async runs or compose component recipes into higher-level coordinator pipelines. Use the no-tools recipe for the safest default, the explicit-tool variant when a bounded tool allowlist is needed, or the prompts fanout parent recipe to see imported subagent recipe nodes composed into one async run:
+The subagent component recipes start non-interactive pi subagents as detached run actors or compose component recipes into higher-level coordinator pipelines. Use the no-tools recipe for the safest default, the explicit-tool variant when a bounded tool allowlist is needed, or the prompts fanout parent recipe to see imported subagent recipe nodes composed into one run actor:
 
 ```text
 register_tool name=subagent_prompt \
@@ -325,7 +329,7 @@ register_tool name=subagent_tools \
   template="subagent-tools.json"
 
 register_tool name=subagents_prompts \
-  description="Start parallel no-tools subagents from a prompt array as one async run" \
+  description="Start parallel no-tools subagents from a prompt array as one run actor" \
   template="subagents-prompts.json"
 
 subagent_prompt prompt="Review docs/async-runs.md for unclear wording." run_id=docs-review
@@ -336,7 +340,7 @@ subagents_prompts \
 inspect target=run:review-prompts view=tail
 ```
 
-The music player recipe starts a local file, URL, directory, or playlist as an async run, keeps the agent unblocked, shows the ambient triangle indicator in the launching coordinator, and can be controlled with addressed `message` calls. The standard library ships one Node.js wrapper recipe:
+The music player recipe starts a local file, URL, directory, or playlist as a run actor, keeps the agent unblocked, shows the ambient triangle indicator in the launching coordinator, and can be controlled with addressed `message` calls. The standard library ships one Node.js wrapper recipe:
 
 ```text
 register_tool name=music_player \
@@ -374,8 +378,8 @@ See [`docs/recipe-library.md`](./docs/recipe-library.md) for install notes and r
 - `recover` runs a cleanup command template between failed retry attempts and stops retries if cleanup fails.
 - Commands execute directly without shell evaluation, but trusted executables still run with the same permissions as pi.
 - 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.
+- `async: true` on a recipe selects detached run-actor lifecycle; omitted or false 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`; run actors 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 coordinator/session attention paths, and `inspect` intentionally reads `run:<id>` status/tail/messages/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/messages/list belongs to `inspect`. Use `inspect view=messages` for actor-envelope streams. Use `control.stop`, `control.cancel`, and `control.kill` for run termination; runtime-prefixed control aliases are no longer part of the public surface.
 - Actor management returns compact text by default; pass `verbose: true` to `inspect` when full JSON state is needed.
@@ -384,7 +388,7 @@ See [`docs/recipe-library.md`](./docs/recipe-library.md) for install notes and r
 - Native Windows should use WSL or a recipe-specific transport for run-local message-controlled recipes; Linux uses stricter `/proc` runner ownership checks for stale PID protection.
 - Registered tools may set `template` to a recipe JSON path/name; calling them follows that recipe's `async` mode.
 - File-backed recipes may declare `imports` and embed imported recipes with `{ "name": "alias" }` nodes, or read `{alias.defaults.key}`, `{alias.defaults.key=fallback}`, and `{alias.values.key?yes:no}` references before command-template execution.
-- Interactive sessions show ambient async activity as stable `▷` triangles aggregated across runs started by the current agent session. Each running async run contributes at least one triangle; parallel active branches can contribute more. One `▶` wave moves over the active set; terminal `done`/`failed`/unhandled `killed`/`exited` messages are delivered as compact follow-up context only to the launching coordinator agent, while intentional `cancel`, `kill`, and `stop` actions stay silent because the action already reports synchronously. Failed commands and in-flight parallel branch completions can bubble through `command.done`; successful final leaf completions remain diagnostic to avoid sequential pipeline noise.
+- Interactive sessions show ambient actor activity as stable `▷` triangles aggregated across runs started by the current agent session. Each running run actor contributes at least one triangle; parallel active branches can contribute more. One `▶` wave moves over the active set; terminal `done`/`failed`/unhandled `killed`/`exited` messages are delivered as compact follow-up context only to the launching coordinator agent, while intentional `cancel`, `kill`, and `stop` actions stay silent because the action already reports synchronously. Failed commands and in-flight parallel branch completions can bubble through `command.done`; successful final leaf completions remain diagnostic to avoid sequential pipeline noise.
 - Use `{file}` as the canonical local file path arg.
 - Stored `script` entries are rejected with migration guidance.
 

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. When a coordinator session is known, addressed run/branch/control messages fail closed before controlling or emitting from runs owned by another session.
+- 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.

package/docs/async-runs.md

@@ -139,10 +139,10 @@ The actor-level surface is:
 
 Low-level async actions map into the actor surface instead of forming a second public model:
 
-- start → `spawn`
-- send/control → `message`
-- status/tail/messages/list → `inspect`
-- stop/kill → `message` with `control.stop` or `control.kill`, with synchronous results
+- Start → `spawn`
+- Send/control → `message`
+- Status/tail/messages/list → `inspect`
+- 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.
 

package/docs/command-templates.md

@@ -79,13 +79,13 @@ Implementations may expand `~` in command position and may resolve relative comm
 
 Supported forms:
 
-| Form                | Meaning                                          |
-| ------------------- | ------------------------------------------------ |
-| `{name}`            | Required value from runtime values or `defaults` |
-| `{name=default}`    | Inline default when no value is provided         |
-| `{name??fallback}`  | Fallback when value is missing, null, or empty   |
-| `{name?yes:no}`     | Ternary string selected by truthiness of `name`  |
-| `{items[index]}`    | Array item selected by literal or repeat index   |
+| Form               | Meaning                                          |
+| ------------------ | ------------------------------------------------ |
+| `{name}`           | Required value from runtime values or `defaults` |
+| `{name=default}`   | Inline default when no value is provided         |
+| `{name??fallback}` | Fallback when value is missing, null, or empty   |
+| `{name?yes:no}`    | Ternary string selected by truthiness of `name`  |
+| `{items[index]}`   | Array item selected by literal or repeat index   |
 
 Resolution order is runtime values → `defaults` → inline default → error. Nullish coalescing and ternary conditions treat missing, empty, `false`, `0`, and `no` as false. Use `??` for value fallback and ternaries for small string selection such as optional CLI flags; larger policy branches should stay in recipes, scripts, or separate template nodes. Default values that are themselves a single placeholder, such as `{prompt}` resolving to `{prompts[index]}`, are resolved recursively with a small depth guard. A repeat node may set `repeat` to `{items.length}` when an array arg should determine fanout width.
 
@@ -248,12 +248,12 @@ Parallel nodes use the same object shape. Flags come first and `template` stays
       "parallel": true,
       "template": [
         {
-          "label": "gpt-5.5",
+          "label": "reviewer-a",
           "timeout": 300000,
           "template": "review-gpt {scope}"
         },
         {
-          "label": "deepseek-pro",
+          "label": "reviewer-b",
           "timeout": 300000,
           "template": "review-deepseek {scope}"
         },
@@ -272,9 +272,9 @@ Parallel nodes use the same object shape. Flags come first and `template` stays
 A degraded parallel join is still usable when at least one branch succeeds:
 
 ```text
---- branch: gpt-5.5 status: done ---
+--- branch: reviewer-a status: done ---
 review text
---- branch: deepseek-pro status: failed ---
+--- branch: reviewer-b status: failed ---
 exit: 1
 stderr: provider balance exhausted
 ```

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. 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.
+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: callers must pass current model policy at launch, which keeps reusable recipe components from aging around old provider aliases. 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:
 
@@ -68,8 +68,10 @@ inspect target=run:docs-review view=tail
 
 Pipeline recipes demonstrate second-order composition:
 
+- `recipes/coordinator-locker.json`: Long-lived coordinator cell with queue, acquire/renew/release lease locks, journal, and actor messages for worker coordination.
 - `recipes/subagent-review-coordinator.json`: Lens reviewers → verifier → merger → judge → normalizer.
-- `recipes/pipeline-release-readiness.json`: Task-first release cell: changelog section → package summary → validation → release review → artifact report.
+- `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.
@@ -96,16 +98,18 @@ Utility recipes cover local operator workflows that do not need subagents:
 - `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, actor-message JSONL tails, and stale/terminal recommendations into one structured operations snapshot.
+- `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`.
 
 These recipes are intentionally small. Register them only for trusted local commands and prefer narrow scopes. The helper-backed utilities share `scripts/recipe-utils.mjs` so repeated parsing/listing logic stays out of recipe strings.

package/docs/task-first-recipes.md

@@ -30,13 +30,13 @@ scope snapshot → changelog/package check → release lens reviews → risk ver
 
 Likely needed cells:
 
-- package metadata reader
-- changelog section extractor
-- package contents summarizer
-- validation command wrapper
-- release-risk reviewer
-- readiness merger/judge
-- release checklist artifact writer
+- Package metadata reader
+- Changelog section extractor
+- Package contents summarizer
+- Validation command wrapper
+- Release-risk reviewer
+- Readiness merger/judge
+- Release checklist artifact writer
 
 Existing seeds:
 
@@ -49,7 +49,7 @@ Existing seeds:
 
 Implemented seed:
 
-- `pipeline-release-readiness`: changelog section → package summary → validation wrapper → release review coordinator → artifact report.
+- `pipeline-release-readiness`: changelog section → package summary → packaged skill summary → validation wrapper → release review coordinator → artifact report.
 
 ### Repository Health Cell
 
@@ -63,12 +63,12 @@ git status/log → package/docs/backlog snapshot → validation summary → heal
 
 Likely needed cells:
 
-- git status/log utility
-- package version reader
-- backlog open/blocked extractor
-- docs index checker
-- validation summary normalizer
-- next-action recommender
+- Git status/log utility
+- Package version reader
+- Backlog open/blocked extractor
+- Docs index checker
+- Validation summary normalizer
+- Next-action recommender
 
 Existing seeds:
 
@@ -93,11 +93,11 @@ run-state summary → actor-message tail → stale/active classification → rec
 
 Likely needed cells:
 
-- run summary helper
+- Run summary helper
 - JSONL actor-message tailer
-- stale-run classifier
-- control-message recommender
-- run report artifact
+- Stale-run classifier
+- Control-message recommender
+- Run report artifact
 
 Existing seeds:
 
@@ -122,13 +122,13 @@ question framing → evidence map → contradiction map → claim verification
 
 Likely needed cells:
 
-- question framer
-- source inventory utility
-- evidence mapper
-- contradiction mapper
-- verifier
-- synthesis merger
-- limitations normalizer
+- Question framer
+- Source inventory utility
+- Evidence mapper
+- Contradiction mapper
+- Verifier
+- Synthesis merger
+- Limitations normalizer
 
 Existing seeds:
 
@@ -149,11 +149,11 @@ goal → mutation zones → task cards → validation gates → conflict risks
 
 Likely needed cells:
 
-- mutation-zone planner
-- task-card generator
-- ownership/conflict checker
-- validation-gate normalizer
-- integrator handoff artifact
+- Mutation-zone planner
+- Task-card generator
+- Ownership/conflict checker
+- Validation-gate normalizer
+- Integrator handoff artifact
 
 Existing seeds:
 
@@ -173,11 +173,11 @@ doc file inventory → index diff → stale link/routing review → rewrite sugg
 
 Likely needed cells:
 
-- markdown index utility
-- link checker wrapper
-- docs consistency reviewer
-- docs update planner
-- docs artifact writer
+- Markdown index utility
+- Link checker wrapper
+- Docs consistency reviewer
+- Docs update planner
+- Docs artifact writer
 
 Existing seeds:
 
@@ -202,10 +202,10 @@ media scan → playlist build → playback start → message summary → control
 
 Likely needed cells:
 
-- playlist builder
-- music player
-- run/message summary
-- control recommender
+- Playlist builder
+- Music player
+- Run/message summary
+- Control recommender
 
 Existing seeds:
 
@@ -226,8 +226,9 @@ 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: implemented in `pipeline-release-readiness` by adding `utility-package-summary` between changelog extraction and validation, making release-readiness reports more evidence-rich without adding publish automation.
-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.
+1. Package/release metadata enrichment: implemented in `pipeline-release-readiness` by adding `utility-package-summary` and `utility-skill-summary` between changelog extraction and validation, making release-readiness reports more evidence-rich without adding publish automation.
+2. Evidence-only release summary: implemented as `pipeline-release-summary`, which composes changelog/package/skill/validation evidence into a release summary, risk checklist, and PR body draft artifact while leaving commit, PR, merge, tag, and publish actions to explicit release gates.
+3. 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.
+4. 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`, `pipeline-media-library`, and `pipeline-artifact-bundle`.
+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-release-summary`, `pipeline-repo-health`, `pipeline-async-run-ops`, `pipeline-docs-maintenance`, `pipeline-media-library`, and `pipeline-artifact-bundle`.

package/docs/template-recipes.md

@@ -95,7 +95,12 @@ Use recipe-level `mailbox` to document the semantic messages a recipe actor acce
 ```json
 {
   "mailbox": {
-    "accepts": ["control.continue", "control.revise", "control.approve", "control.stop"],
+    "accepts": [
+      "control.continue",
+      "control.revise",
+      "control.approve",
+      "control.stop"
+    ],
     "emits": ["checkpoint.needs_scope", "branch.done", "run.done"]
   }
 }
@@ -172,7 +177,7 @@ A registered tool can point at an actor recipe by storing the recipe path or nam
 {
   "docs_review": {
     "description": "Start an async docs review actor",
-    "args": ["scope:path", "model:string=openai-codex/gpt-5.5"],
+    "args": ["scope:path", "model:string"],
     "template": "docs-review.json"
   }
 }