@llblab/pi-actors 0.42.3 → 0.43.1

package/skills/actors/SKILL.md

@@ -1,311 +1,103 @@
 ---
 name: actors
-description: Required practical guide for non-trivial pi-actors use, including parallel actor launches, subagent fanout, and autonomous coordinator workflows. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
-metadata:
-  version: 0.42.3
+description: Required practical guide for non-trivial pi-actors use and Run-kernel work. Read before using or changing spawn, message, inspect, Runs, tools, Recipes, command templates, Control, Trace, artifacts, or lifecycle mechanics.
 ---
 
 # Actors (pi-actors)
 
-`pi-actors` turns trusted local capabilities into addressable actors. This skill is the required practical layer for any non-trivial pi-actors use or repo change: tools, nouns, lifecycle, message protocol, recipes, and common edge cases. It is not a multi-agent strategy guide; use a swarm skill for decomposition, quorum design, reviewer lenses, and consensus methodology.
-
-Maintain this skill as the extension's agent-facing manual. When implementation changes reveal new durable mechanics, invariants, warnings, or safer operating patterns, update this skill alongside code/docs so future agents learn the current actor model instead of rediscovering it.
-
-## Knowledge Surfaces
-
-Context arrives in layers:
-
-- **Injected prompt**: always present at extension load. It is a bootstrap/reminder of current verbs, paths, and runtime rules; it should not try to be documentation.
-- **Skill header**: automatically matched by agents from `name`/`description`. Its job is to signal: if pi-actors use is unclear, read this skill body.
-- **This skill body**: highest-density practical reference. It should explain extension operation from multiple angles and link to deeper docs without becoming a changelog or swarm-methodology guide.
-- **README**: human entrypoint. It explains what pi-actors is, why it matters, benefits, rhythm, and representative scenarios; it is not automatically in agent context.
-- **Docs**: transportable standards by domain: command templates, recipes, async runs, actor messages, registry, recipe library; read on demand.
-- **AGENTS.md**: project context for agents changing pi-actors: architecture constraints, durable conventions, do/don't rules, validation; read for repo work.
-
-## Core Nouns
+`pi-actors` treats any runnable local capability—a script, tool, service, pipeline, or subagent—as an actor. A Recipe is its reusable executable definition; a Run is one concrete actor instance:
 
 ```text
-Trusted local capability
-  -> Command template          execution graph
-  -> Recipe                    saved actor definition
-  -> spawn                     starts one run instance
-  -> run:<id>                  addressable actor
-
-Trusted local capability
-  -> Command template or recipe
-  -> register_tool             persists an agent-callable wrapper
-  -> tool:<name>               addressable tool actor
+Recipe --spawn--> Run
+Run = Recipe + Trace + Control
 ```
 
-- **Command template**: portable execution graph. String leaf, sequence array, or object node with controls.
-- **Recipe**: saved JSON definition wrapping a template with args, defaults, imports, mailbox, artifacts, metadata, and optional `async: true`.
-- **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, and artifacts.
-- **Tool actor**: registered persistent capability addressable as `tool:<name>` and callable through the generated tool or `message`. `tool:pi-actors` is reserved for runtime status and explicit automatic-review retry/reset control.
-- **Artifact**: named durable output path declared by a recipe/run.
-- **Mailbox**: interaction contract: message types the actor accepts/emits.
-- **Advanced group/coordination surfaces**: `branch:<run>/<branch>`, `room:<run>`, `coordinator`, `session:<id>`, and communication snapshots exist for multi-actor workflows and diagnostics; do not make them the default mental model.
+Use the swarm skill separately for decomposition, quorum design, reviewer lenses, and consensus methodology.
 
-## Three Verbs
+## Public Verbs
 
-Actor-mode trigger: if work may outlive this turn, needs steering/follow-up/artifacts, runs as a service, fans out, or should be resumed/inspected later, use `spawn → message → inspect` instead of ad hoc shell backgrounding. Keep short foreground checks as normal tools.
+- `spawn`: create one Run from a Recipe or inline command template.
+- `message`: send one actor-local Control to `run:<id>`, or the reserved review actions to `runtime`.
+- `inspect`: inspect `run:<id>`, `runtime`, `recipes`, or `tool:<name>`.
+- `register_tool`: persist a trusted capability; it does not address a running actor.
 
-### `spawn` — create a run actor
+A Run target exposes exactly three inspect views: `recipe`, `trace`, and `control`.
 
-Use for long work, background services, subagents, fanout, pipelines, and reusable recipes.
+## Recipe
 
-Before a parallel launch, the coordinator should verify five things once: each actor owns a disjoint mutation scope, every run has a stable id, each durable result has an artifact path, every command template respects shell-free argv execution, and completion can return through follow-up delivery without polling. For multiple delegated implementation or review actors, also load the bundled Swarm skill before choosing decomposition, locks, or quorum shape.
+A Recipe defines execution. It may declare args, defaults, imports, artifacts, command-template flags, and `control: ["action"]` when a long-lived service actually consumes actor-local inputs.
 
-```json
-{
-  "as": "run:repo-health",
-  "file": "pipeline-repo-health",
-  "values": { "path": "/repo" },
-  "artifacts": { "report": "/tmp/repo-health.md" }
-}
-```
+Do not declare Control for ordinary one-shot work. Runtime lifecycle actions such as `kill` stay runtime-owned and must not appear in Recipe Control declarations. Imported Recipes act as local definitions inside one Run; they do not create nested Runs unless execution explicitly spawns them.
 
-Rules:
+Prefer maintained packaged Recipes over ad hoc wrappers. Keep model, thinking, mission, concurrency, quorum, and timeout choices caller-owned unless a Recipe documents a stable policy.
 
-- Command-template strings execute directly without a shell. Operators such as `&&`, `||`, pipes, redirects, and `cd` remain literal argv unless an explicit trusted shell is the executable. Prefer absolute paths or template arrays for sequencing; put non-trivial shell behavior in a reviewed script.
-- Use `file`/`recipe` for saved recipes; bare names resolve under `~/.pi/agent/recipes`.
-- Use inline `template` for one-off experiments; promote useful repeats to recipes.
-- Terminal follow-up context contains only run id, status, one base path, and relative artifact names. Inspect the run for contents; semantic output and correlation remain in non-LLM details and state. Decide whether a successful pattern deserves durable tool memory only after inspection, and ask before writing the user recipe root.
-- Use stable `as` names when you will inspect or message the actor later.
-- Public run state is runtime-owned; do not pass custom `state_dir` paths. This keeps `run:<id>` addressability and retention on one boundary.
-- `async: true` on the recipe is the detached run switch.
+## Trace
 
-### `message` — send a typed envelope
+Trace records bounded structured observations in `trace.jsonl`:
 
 ```json
 {
-  "to": "run:repo-health",
-  "type": "control.cancel",
-  "summary": "Cancel stale repo-health run",
-  "body": {}
+  "id": "…",
+  "ts": "…",
+  "kind": "progress.update",
+  "summary": "…",
+  "data": {},
+  "level": "info",
+  "attention": "notify"
 }
 ```
 
-Envelope fields:
-
-- Required: `to`, `type`.
-- Useful: `summary`, `body`, `from`, `reply_to`, `correlation_id`, `metadata`.
-- Core addresses: `run:<id>`, `tool:<name>`.
-- Advanced addresses: `branch:<run>/<branch>`, `room:<run>` for group timeline/roster, `coordinator`, `session:<id>`.
-- Group posts to `room:<run>` require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
-- Runtime termination message: `control.kill` is the only documented actor message that kills a run. `control.stop` and `control.cancel` are actor-local mailbox vocabulary only when a recipe declares and handles them. Terminal retention messages: `control.archive`, `control.prune`.
-- Long-lived child processes should remain in the run-owned process group unless the recipe implements an explicit daemon termination bridge; do not leave unowned detached services behind `control.kill`.
-- Run controls revalidate a persisted cross-platform process identity proof at authorization and again immediately before signaling. Treat `dead pid`, `owner mismatch`, and `unsupported proof` as distinct fail-closed states; on Unix, only process-group `ESRCH` plus one more matching identity check permits exact-pid fallback, while permission/authorization errors remain terminal. Node exposes no portable pidfd/process-group handle, so retain the documented residual exit/reuse window instead of claiming atomic signaling or bypassing control with direct pid signals.
-- Detached actors survive ordinary agent turns. On `session_shutdown` (quit, reload, or session replacement), pi-actors attempts canonical `control.kill` for each discovered readable still-running exact-owner run. Control compares immutable run generation inside the canonical boundary and serializes against same-directory restart; terminal, ambiguous, changed-generation, and other-session runs remain untouched. Teardown scans without the ordinary index depth cap, reports unreadable/corrupt state as failures, and persists a bounded summary under the run root. Descendant Pi sessions remain separate owners and rely on their own shutdown hooks; hard host termination can still leave an orphan requiring summary-guided OS/manual recovery, so never describe teardown as an absolute no-survivor guarantee.
+Trace never carries sender, recipient, route, reply, or message-envelope fields. First-party writers use the canonical append authority, which validates and size-checks under a token-owned cross-process lock before one append-only JSONL write. Use `attention: "notify"` for visible notification and `attention: "followup"` only when the coordinator must receive semantic follow-up context. Prefer artifacts or complete execution captures for large evidence.
 
-Check `inspect view=mailbox` before domain-specific messages.
+## Control
 
-### `inspect` — observe intentionally
+The public Control request is exact:
 
 ```json
-{ "target": "run:repo-health", "view": "status" }
-{ "target": "run:repo-health", "view": "tail", "lines": "80" }
-{ "target": "run:repo-health", "view": "messages" }
-{ "target": "run:repo-health", "view": "artifacts" }
-{ "target": "tool:pi-actors", "view": "status" }
-{ "target": "tool:music_player", "view": "status" }
-{ "target": "recipes", "view": "status" }
-{ "target": "coordinator", "view": "status" }
+{ "target": "run:<id>", "action": "pause", "input": {}, "verbose": false }
 ```
 
-Views:
-
-- `status`: lifecycle, pid, values, progress, result, compact summary.
-- `tail`: recent stdout/stderr/log tail.
-- `messages`: actor messages emitted by the run, or room timeline entries for `room:*`.
-- Advanced `communication`: run/branch group-coordination snapshot with self/root/default-room/member/contact hints.
-- Advanced `roster`: room member list with address, role, parent, caps, claim, status, and last seen.
-- Advanced `contacts`: roster-derived direct-message targets without full roster metadata.
-- Advanced `previews`: TUI-ready bounded group-message previews with timestamp/from/to/type/summary/body_preview.
-- `mailbox`: declared accepts/emits contract for runs; queued direct branch inbox messages for `branch:<run>/<branch>` with `id`, status, route/type, and queue/handling timestamps.
-- `files`: run state file summary plus a `lines`-bounded `review-evidence.json` manifest when present, including total/truncated command counts and stage capture paths.
-- `artifacts`: declared artifact paths/status plus the same bounded owned review-evidence manifest when present.
-- `recipes` target: registry summary for active, shadowed, invalid, disabled, and diagnostic recipe entries.
-
-Let terminal notifications arrive. They queue through Pi's follow-up delivery mode, so a busy coordinator finishes its current work before receiving concurrently completed actor results; the host's `followUpMode` controls whether queued results arrive together or one at a time. Pi injects these notifications invisibly into LLM context while waking an idle coordinator, avoiding a duplicate custom-message copy in the transcript. Their LLM context content stays limited to run id, status, one base path, and relative artifact names; inspect state for raw output while correlation and semantic details remain outside LLM context. File watching accelerates delivery, while a bounded ten-second terminal-only reconciliation pass recovers missed or failed watcher activity without replaying outbox traffic; watcher degradation and rearm remain visible diagnostics. When a deferred actor result gates the next step, wait for that terminal follow-up instead of scheduling continuation loops, repeatedly inspecting, or mutating the actor's reviewed scope. Idle coordinators still start a normal turn through `triggerTurn: true`. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue or stuck run.
-
-## Runtime Communication Rules
-
-- Keep one public communication model: `spawn` creates actors, `message` sends typed envelopes, and `inspect` observes. Avoid adding public side channels or storage nouns when a normal actor address/view can express the operation.
-- Keep route and semantic type separate. Direct, room, coordinator, and session messages may share `type`; delivery behavior comes from `to`.
-- Treat persisted communication logs as recipe evidence. Use `inspect room:<run> view=messages|previews` and `inspect run:<id> view=communication` to improve mailbox/artifact conventions after real runs.
-- Any UI, summary, or aggregate view that scans run directories must apply coordinator/session ownership filters before exposing summaries or body previews.
-- Treat `communication.json` as visible actor context, not a global mutable truth table. Run-level snapshots should identify the run actor; branch-local snapshots should identify the branch actor.
-- Prefer same-run provenance checks on lateral actor routes. If `from` is accepted for room or branch routes, validate that it belongs to the addressed run.
-
-## Command Template Standard
-
-Forms:
-
-```json
-"npm test -- {file}"
-["npm run typecheck", "npm test"]
-{ "parallel": true, "template": ["job-a", "job-b"] }
-```
-
-Controls:
-
-- `args`, `defaults`: public placeholder declarations and defaults.
-- `parallel: true`: fanout child nodes.
-- `when`: conditional execution.
-- `accept_output: review_evidence`: fail closed unless the exact first non-whitespace stdout line is `ACTOR_REVIEW_RESULT`; marker prefixes are rejected and rejected stdout remains diagnostic evidence.
-- `timeout`, `delay`, `retry`: timing and retry controls; string placeholders are allowed where supported.
-- `failure`: `continue`, `branch`, or `root` propagation.
-- `recover`: cleanup between retry attempts.
-- `repeat`: repeated node expansion.
-- `output`: output behavior selection.
-- Command stdout/stderr use bounded tails plus complete spill files; tool/run diagnostics expose byte counts, truncation, and spill paths, while pipelines fail with `incomplete pipeline stdin` rather than consuming a partial tail.
-- Detached child `pi -p` commands receive isolated session storage under `sessions/command-NNN` in their owned run state, and command evidence records any resulting JSONL files. Coordinator-managed room/swarm participants use role/phase-scoped directories under the same run-local `sessions/` root so their turns remain discoverable too. Explicit `--no-session`, `--session`, `--session-id`, `--session-dir`, or `--fork` policy remains caller-owned and is never replaced.
-- Persisted child-session inspection follows the latest JSONL entry branch, correlates tool results by call id, bounds previews, and redacts common secret-bearing fields/text. Thinking content is evidence only when Pi persisted an explicit `thinking` block; never infer or advertise hidden reasoning.
-
-Placeholders:
-
-- `{name}` required value.
-- `{name=default}` inline default.
-- `{name:type=default}` typed inline arg.
-- `{value??fallback}` nullish fallback.
-- `{flag?yes:no}` ternary fallback.
-
-Templates are synchronous and portable. Recipes give them identity and lifecycle.
-
-## Recipe Standard
-
-Minimal actor recipe:
-
-```json
-{
-  "async": true,
-  "args": ["path:path", "model:string"],
-  "defaults": {},
-  "mailbox": {
-    "accepts": ["control.kill"],
-    "emits": ["command.done", "run.done", "run.failed"]
-  },
-  "artifacts": { "report": "{path}/report.md" },
-  "template": "some-command {path} --model {model}"
-}
-```
+Valid Controls persist in `controls.jsonl` before delivery; invalid envelopes remain outside the journal. Token-owned locks serialize atomic journal replacements. Service endpoints publish readiness in `control-endpoint.json` with the immutable startup `run_instance_id`; only FIFO and named-pipe endpoints transport Controls. Both transports share one portable envelope: action is at most 64 lowercase ASCII characters, serialized JSON input is at most 380 bytes, and the newline-terminated wire record is at most 512 bytes. Partial writes fail, and controlled FIFO readers remain gap-free across writers. Put larger data in a declared artifact/path and send only its bounded reference or instruction through Control. Delivery revalidates owner, generation, running state, and process identity under the lifecycle lock.
 
-Rules:
+`kill` remains a runtime lifecycle action. Use an actor-local action such as `stop` only when the Recipe declares and implements it.
 
-1. Every recipe owns `template` directly.
-2. `async: true` makes spawned work a detached actor run.
-3. Public knobs belong in `args`/`defaults`; hidden launch mechanics stay inside `template`.
-4. Use `imports` to compose recipes; imported recipes are definitions, not nested async runs.
-5. Direct recipe delegation is the thin-wrapper case: when a `template` value is just a ready recipe name/path, the intended behavior is to delegate to that recipe rather than execute the recipe file as a program. Use this for simple handoffs and wrapper tools; use `imports` + `{ "name": "alias" }` when you need rich composition, multiple nodes, or import-specific values/defaults.
-6. When exposing an already-authored recipe as a user tool before direct delegation is available or when composition is needed, make a small wrapper recipe in `~/.pi/agent/recipes` that imports the source recipe and uses a `{ "name": "alias" }` node. Do not copy the ready recipe's script command, defaults, mailbox, or artifacts into a second template.
-7. Declare `mailbox` for actors that accept or emit meaningful messages.
-8. Declare `artifacts` for durable outputs the coordinator should inspect.
-9. File-backed recipe identity comes from the filename basename; legacy top-level `name` fields are ignored by loaders.
-10. File-backed async recipes pass child `pi -p` actors a bounded JSONL recipe context bundle by default: raw entry/import recipe records, derived `name`, import path/alias, and `"you_are_here": true` on the launching recipe node. The runner collapses all natural-language positional fragments into one prompt under `prompts/command-NNN.md`, keeps intentional `@file` attachments separate, and invokes Pi with one authoritative prompt-file arg so large prompts and recipe context stay inspectable and argv-safe. Set `"actor_context": false` or `"off"` to suppress recipe context for minimal prompts.
-11. Keep packaged recipes generic: no machine-local paths, no private companion identities, no project-specific defaults unless the recipe is explicitly project-specific.
-12. Do not ship concrete model-version defaults in packaged recipes. For review-oriented subagent/lens recipes, default model/thinking args through `{current_model}` and `{current_thinking}` so they inherit the selected Pi session policy; keep `model`, `models`, `thinking`, and stage-specific model args explicit so callers can override policy at launch.
+## Run State and Safety
 
-Priority for same-id recipes:
+Run state lives under `~/.pi/agent/tmp/pi-actors/runs/<run>/`. Important evidence includes:
 
-1. No recipe: no capability.
-2. Packaged pi-actors recipe: standard-library declarative actor component.
-3. Explicit ad hoc user recipe file outside `~/.pi/agent/recipes`.
-4. User recipe in `~/.pi/agent/recipes/*.json` or `*.md`: highest-priority operator tool surface.
+- `run.json`: captured Run identity, Recipe, owner, generation, process identity, and policy.
+- `trace.jsonl`: structured observations.
+- `controls.jsonl`: durable actor-local inputs and outcomes.
+- `control-endpoint.json`: generation-fenced service readiness.
+- `execution.json`: command/session provenance and bounded complete-capture references.
+- `result.json`, logs, and declared artifacts.
 
-Only matching filename ids compete. Higher priority shadows lower priority; within one priority layer, same-id JSON shadows Markdown. Same-id overrides are normal composition/delegation behavior, not startup-warning material. An invalid or `disabled: true` higher-priority recipe blocks fallback so the agent does not silently run standard-library behavior when a user override is broken or intentionally disabled.
+Never bypass owner filtering, immutable generation fencing, process-identity verification, path containment, redaction, terminal reconciliation, or shutdown kill behavior. Do not edit active Run state to force a result.
 
-Muscle-memory lens: pi-actors has two durable executable-memory layers.
+## Operating Pattern
 
-1. `~/.pi/agent/recipes/*.json` and `*.md` are the agent's active capability memory. Every recipe in that directory becomes an easy-to-call tool automatically and survives into later sessions. Descriptions matter here because they become the tool's operator-facing title/context.
-2. `~/.pi/agent/recipes/drafts/*.json` is draft memory captured from successful inline `spawn template=...` runs. Drafts do not enter the injected tool surface and remain reusable by explicit path, e.g. `spawn file="~/.pi/agent/recipes/drafts/<name>.json"`.
+1. Inspect the Recipe before launch when its contract or policy matters.
+2. Spawn with explicit values and retain the returned `run:<id>`.
+3. Let short Runs finish; avoid polling.
+4. Inspect Trace when evidence or attention requires it.
+5. Send only declared actor-local Controls.
+6. Use runtime kill/cancel behavior for lifecycle termination.
+7. Inspect artifacts and execution evidence for final validation.
 
-Agents grow draft memory by trying ad hoc actors successfully. Active memory grows through explicit `register_tool`, deliberate operator recipe edits, or the bounded automatic review cycle. Treat drafts as the workbench and root recipes as active muscle memory.
-
-Usage lens: user recipe launches update an extension-maintained canonical name-and-priority lineage ledger under `.usage/recipes/<recipe-name>.json`; authored recipe files are not rewritten for telemetry. Accounting briefly shares the portfolio mutation fence so source quarantine cannot erase an authorized launch; if another session already changed the source, the stale invocation rejects and requests reload rather than executing without evidence. Lifetime calls survive rename, revision, promotion, and demotion, while revision-local calls restart when executable content changes. The bounded unversioned ledger retains former names/paths, revision ancestry, transition events, and review epochs. Discovery merges lineage usage into inspection. Agents should not hand-edit counters; usage remains evidence rather than a sufficient usefulness verdict.
-
-Automatic review lens: successful transient/ad hoc actor runs leave replayable drafts rather than active tools. At twelve eligible drafts, pi-actors captures one exact trusted batch and attaches only its identity-opaque value-free structural projection to a silent no-tools reviewer after the foreground turn and active actors finish. Its complete quota-free `promote`/`discard` result contains no recipe content: the deterministic executor derives promotions from exact captured sources and revalidates source/target CAS, complete recipes, root identity, quarantine hashes, and recovery state before commit. Newer drafts remain for a later batch; malformed, stale, unsafe, or incomplete decisions fail closed. Unchanged automatic demotions remain in cooldown until their executable fingerprint changes. Prefer fenced `register_tool draft=...` for an explicit single-draft promotion. A deliberate move/copy into the recipe root also remains valid, but may invalidate and defer an already captured batch; do not reconstruct removed batch commands or ask the operator to drive an automatic batch.
-
-Portfolio lens: thirty-six eligible non-sensitive active revisions trigger a no-tools review of an attached value-free structural projection; canonical names, draft basenames, raw hashes, recipe bodies, template/default values, authored prose, and filesystem paths remain in the separate trusted capture; batch-local occurrence IDs and equality-only content groups preserve correlation and deduplication. Set `PI_ACTORS_AUTOMATIC_REVIEW=off` before Pi starts to disable both reviewer scheduling and safe-boundary portfolio activation; verify the effective value with `inspect target=tool:pi-actors view=status`. The reviewer may select keep, unchanged-source rename, unchanged-source demotion, or deduplication of canonically identical captured recipes; it cannot return recipe content. Replacement, split, and executable contract changes require explicit operator authoring. Approval remains immutable until the next safe session boundary, where journaled filesystem and lineage executors apply only the captured recipe bytes. Use `inspect target=recipes view=reviews` for bounded evidence including failed stage/error/next action. Recover a failed cycle through `message to=tool:pi-actors type=review.retry body={"scope":"draft"|"tool"}`. Draft retry resumes an existing authenticated transaction plan and original reviewer run rather than generating decisions after filesystem commit; `review.reset` clears only disposable terminal admission state and rejects tool recovery evidence that must roll forward.
-
-## Registered Tools
-
-`register_tool` persists trusted local capabilities as recipe files in `~/.pi/agent/recipes/*.json`; hand-authored Markdown recipes in the same directory are also discovered as tools.
-
-Use it when a command/template/recipe should become durable agent muscle memory. Prefer typed args or placeholder-derived args; use `update=true` for replacement and `template=null` or `template=""` for deletion. `register_tool` should create/update/delete simple recipe files in the user recipe root; direct recipe-file editing is the right path when the wrapper needs `imports` or other top-level recipe metadata not exposed by the interactive mutation API.
-
-Ready-recipe registration patterns:
-
-Thin delegation target shape:
-
-```json
-{
-  "description": "Run a ready recipe through a local tool name.",
-  "args": ["source:path", "volume:int=70"],
-  "template": "/path/to/ready-recipe.json"
-}
-```
-
-Delegation is for one-to-one handoff: expose or call a maintained recipe directly, preserving that recipe as the source of truth. If the runtime does not yet support direct recipe references in `template`, or if you need composition, use the import-node wrapper below.
-
-Composition/import wrapper:
-
-```json
-{
-  "description": "Run the ABCd context validator through its skill recipe.",
-  "imports": {
-    "validate_context": "{agent}/skills/abcd-context/recipes/validate-context.json"
-  },
-  "args": ["path:path=."],
-  "template": { "name": "validate_context" }
-}
-```
-
-Use delegation or this import pattern whenever a reusable recipe already exists: packaged pi-actors components, project-local recipes, ad hoc reviewed recipe files, and especially skill-owned recipes that wrap skill scripts. The wrapper owns only the public tool name, description, optional narrowed args/defaults, and local usage metadata. The delegated/imported recipe remains the source of truth for the script path, default values, mailbox contract, artifacts, and future fixes.
-
-Tool-registration lenses are open-ended prompts for deciding what deserves durable tool status:
-
-1. **Reliability lens**: register wrappers for operations where agents commonly omit checks, run steps out of order, pass ambiguous inputs, or recover poorly from partial failure.
-2. **Safety lens**: prefer read-only diagnostics, dry-runs, preflights, confirmations, or bounded adapters around high-impact operations before registering direct action tools.
-3. **Context-affordance lens**: register tools whose mere presence in the injected capability list should steer agents toward the right operational habit.
-4. **Existing-recipe lens**: scan already-authored recipes before inventing a new tool. Packaged recipes, ad hoc project recipes, and recipes co-located under skill directories are the first candidates to delegate to or import from a user-root wrapper when they match a recurring local workflow.
-5. **Skill-recipe lens**: when a skill ships a recipe for its script, local tools must delegate to or import that recipe instead of calling the skill script directly. This preserves the skill's maintained interface and keeps future script/default changes centralized.
-6. **Composition lens**: register small semantic entrypoints over reusable recipe components instead of baking one large scenario-specific shell command into a tool; prefer direct delegation for one recipe, imports for composed graphs.
-7. **Portability lens**: keep recipe files transportable; make tool exposure a consequence of placement in `~/.pi/agent/recipes`, not recipe-owned markers or machine-local assumptions.
-
-Default bias: register diagnostic/preflight tools before action tools, and promote existing recipes before writing new orchestration. A good persistent tool shrinks the chance of a subtle operational mistake, not just the number of keystrokes.
-
-Tool templates may be:
-
-- A foreground command template.
-- A file-backed recipe name/path for thin delegation.
-- A complete recipe body, optionally `async: true`.
-
-The user recipe root is the default tool set by location. It accepts canonical JSON recipes and literate Markdown recipes with frontmatter plus fenced `template`/`json recipe` blocks; same-id JSON shadows Markdown in the same priority layer. Packaged recipes are lower-priority standard-library components and are not tools unless copied or registered into the agent recipe root. Ideal runtime behavior is reactive: create/edit/delete recipe files, validate them, then connect valid tools or surface diagnostics without requiring agents to hand-maintain a separate registry.
+If work may outlive the current turn, needs steering, produces artifacts, fans out, or must remain inspectable, use a Run rather than shell backgrounding.
 
 ## Top Recipes
 
-Use packaged recipes by name with `spawn file=<name>` for async actors, or register/call them as tools when repeated use deserves a stable shortcut.
-
-Packaged review recipes are directly spawnable. Use `spawn file="pipeline-review-readiness" values={...}` for readiness review or `spawn file="subagent-review" values={...}` for one reviewer; pass model/thinking/tool policy through values, then inspect the run. Review coordinators preflight stage models before fanout; `ACTOR_PREFLIGHT_FAILED` diagnostics identify the failed stage, selected policy, provider error class, prompt file, and override args. Review stages require the `ACTOR_REVIEW_RESULT` evidence marker, so format acknowledgements and input requests fail closed before satisfying quorum or flowing downstream; rejected stdout remains in branch diagnostics. Quorum-aware review fanout exposes `subagent_ttl_ms`, `reviewer_concurrency`, `min_successful_reviewers`, and `merge_policy`; partial reviewer evidence is preserved and marked `complete`, `degraded`, or `insufficient_data`. Run status/progress exposes `model_policy` so inherited vs explicit model/thinking choices remain visible. Do not recreate their script commands, call packaged scripts directly, or create wrapper recipes just to launch the maintained recipe.
-
-- [`pipeline-room-swarm`](../../recipes/pipeline-room-swarm.json): room-visible swarm coordination with roles, rounds, optional locker, artifact synthesis, and `subagent_ttl_ms` for hard participant budgets.
-- [`pipeline-repo-health`](../../recipes/pipeline-repo-health.json): git/doc/validation evidence → normalized repository health report.
-- [`pipeline-release-readiness`](../../recipes/pipeline-release-readiness.json): changelog/package/skill/validation evidence → release review → artifact report.
-- [`actor-worker`](../../recipes/actor-worker.json): canonical mailbox-backed branch worker reference for claim/handle/status/artifact patterns.
-- [`coordinator-locker`](../../recipes/coordinator-locker.json): queue + lease locks + journaled coordinator messages for multi-actor ownership.
+- [Repository health](../../recipes/pipeline-repo-health.json)
+- [Quorum review](../../recipes/pipeline-quorum-review.json)
+- [Artifact bundle](../../recipes/pipeline-artifact-bundle.json)
+- [Music player service](../../recipes/music-player.json)
+- [Resource locker service](../../recipes/resource-locker.json)
 
 ## Deep References
 
-- `docs/actors-deep-reference.md` — recipe navigator, operating patterns, lifecycle discipline, pitfalls.
-- `docs/command-templates.md` — execution graph semantics.
-- `docs/template-recipes.md` — recipe storage, imports, defaults, references.
-- `docs/async-runs.md` — detached lifecycle, state, cancellation, observability.
-- `docs/actor-messages.md` — addressed envelope protocol and mailbox model.
-- `docs/tool-registry.md` — persistent tool registry and generated tools.
-- `docs/recipe-library.md` — packaged recipes.
-- `docs/task-first-recipes.md` — deriving reusable pipelines from operator tasks.
-- `docs/component-recipes.md` — reusable coordinator/subagent building blocks.
-
-## One-Sentence Contract
+- [Recipe library](../../docs/recipe-library.md)
+- [Async Runs](../../docs/async-runs.md)
+- [Baseline and preservation gates](../../docs/0.43-baseline.md)
 
-Use pi-actors to wrap local capabilities as addressable actors: define launch with templates, preserve semantics in recipes/tools, start with `spawn`, communicate with `message`, observe with `inspect`, and hand off durable results through messages and artifacts.
+Read repository source and tests for exact contracts when changing pi-actors itself. Update this skill whenever durable Run mechanics change.

package/skills/swarm/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: swarm
 description: Subagent and actor orchestration with scoped locks, fanout, and quorum consensus. Use before launching multiple parallel actors or subagents for independent implementation, artifact generation, review, delegated audit, coordinated execution, or any workflow that needs autonomous coordinator decomposition and integration.
-metadata:
-  version: 0.42.3
 ---
 
 # Swarm
@@ -263,48 +261,26 @@ Use the local review protocol if available.
 Report white spots, contradictions, evidence, and risks.
 ```
 
-## Async Run Adapter
+## Run Adapter
 
-Async run management is an adapter concern, not a portable Swarm script requirement. For non-trivial asynchronous agentic work, use an async-run flow when the local runtime supports it: command-template execution plus a thin detached lifecycle envelope.
+Detached execution is an adapter concern, not a portable Swarm-script requirement. When the host offers Runs, launch the composed Recipe, return its id, and rely on terminal follow-up rather than blocking or polling.
 
-- `start`: Launch a swarm run in the background and return run metadata.
-- `status`: Report whether the run is running, done, degraded, or failed.
-- `tail`: Show recent structured run events or raw logs.
-- `list`: Show known runs.
-- `cancel`: Stop an owned active run when the adapter can prove pid ownership.
+`Progress contract`: expose bounded structured Trace, logs, artifacts, status, timestamps, and final result evidence. Read these through Run inspection rather than scraping process output.
 
-`Purpose`: Keep the user interface responsive while reviewers, merger, and post-merge reviewer run. Generic run state belongs to a local async lifecycle runtime; swarm-specific execution stays in atomic utilities or command-template composition. The orchestrator should start the run, return metadata, then inspect status/tail after terminal events instead of blocking on sleeps or foreground waits.
+`Resumable checkpoint goal`: a controlled agent-backed Run may preserve context and accept a declared Control. When the host cannot preserve context, write a handoff artifact and launch a clean-context Run while marking the context loss explicitly.
 
-`Resumable checkpoint goal`: Advanced adapters should strive to support a paused subagent that can ask the orchestrator for input and then resume in the same subagent context. The portable contract is a structured coordinator checkpoint plus a coordinator reply; the mechanism may be a TTY session, persistent model session, message queue, or runtime-specific resume token. If the runtime cannot preserve context, degrade to a handoff artifact and a new subagent, and mark the context loss explicitly.
-
-`Progress contract`: async runs should expose structured state such as `progress.json`, `events.jsonl`, logs, and final result metadata. Local tools should read these files through async-run verbs instead of scraping process output.
-
-`Minimum state`: an adapter should expose `run_id`, `status`, timestamps, state directory or output directory, recent events, stdout/stderr logs, and final result metadata.
-
-`Terminal statuses`: `done`, `failed`, `timeout`, and `cancelled` are terminal. `running` and `degraded` are observable non-terminal states.
-
-`Cancellation boundary`: cancel only an owned active run when pid ownership or runtime ownership can be verified. Stale pid reuse must fail closed.
-
-`Reference binding`: Use a local generic async-run runtime or tool registry adapter. If the local runtime exposes a single action tool, bind these verbs as actions rather than adding more Swarm scripts. Swarm scripts themselves should stay atomic and narrowly specialized.
+`Cancellation boundary`: terminate only an owned active generation whose process identity the runtime can prove. Stale pid reuse must fail closed.
 
 ## Stable Multi-Agent Review Rules
 
-- Prefer independent read-only reviewers for review swarms. Use shared room messages for coordination signals and observability, not for letting reviewers converge early, unless the task explicitly asks for collaborative discussion.
-- Treat communication logs as recipe-quality evidence. Timelines show whether agents coordinate clearly, emit useful summaries, over-chat, miss handoffs, choose poor message types, or need better mailbox/artifact conventions.
-- Smoke-test provider/model availability before launching expensive fanout, or choose a provider known to be configured in the environment. A failed provider fanout creates noisy run transitions without useful review signal.
-- Keep methodology and runtime split: Swarm chooses decomposition, quorum, lenses, lock discipline, and merge shape; the local runtime supplies actors, messages, files, locks, artifacts, and cancellation.
+- Prefer independent read-only reviewers so they do not converge before synthesis.
+- Treat Trace, artifacts, and immutable reviewer results as methodology evidence.
+- Smoke-test provider/model availability before expensive fanout.
+- Keep methodology and runtime split: Swarm chooses decomposition, quorum, lenses, lock discipline, and merge shape; the Run kernel supplies execution, Trace, Control, artifacts, and lifecycle safety.
 
 ## Persistent Implementer Pattern
 
-Use this pattern only when the work benefits from long-lived workers rather than one-shot subagents. Keep task selection with the coordinator and use reusable adapter cells for queues, locks, messages, and mailbox loops.
-
-1. Coordinator assigns a concrete task with `task.assign` or an adapter-equivalent envelope.
-2. Actor claims before editing or mutating shared state.
-3. Actor executes and validates the slice.
-4. Actor posts a result plus an explicit availability/blocked status.
-5. Actor stays alive until another assignment or an explicit runtime/domain stop.
-
-Use opposite-end or lens-specific implementers only to reduce overlap, not as a default. If a host adapter cannot express this scenario from reusable cells, add missing generic cells before packaging a broad workflow.
+Use long-lived controlled services only when repeated assignments justify them. Keep task selection with the orchestrator and use explicit artifacts or task cards for claims/results. Resource exclusion may use the optional `resource-locker`; it does not become swarm authority. Prefer multiple scoped Runs over a peer protocol.
 
 ## `swarm_quorum`
 

package/dist/fixtures/protocol/actor-message-branch.json

@@ -1,13 +0,0 @@
-{
-  "to": "branch:demo/reviewer",
-  "from": "run:demo",
-  "type": "task.assign",
-  "summary": "Review the current slice",
-  "body": {
-    "task": "Check mailbox loop semantics"
-  },
-  "correlation_id": "task-001",
-  "metadata": {
-    "requires_response": true
-  }
-}

package/dist/fixtures/protocol/mailbox-contract.json

@@ -1,15 +0,0 @@
-{
-  "accepts": [
-    "task.assign",
-    {
-      "type": "control.stop",
-      "description": "Request graceful worker shutdown"
-    }
-  ],
-  "emits": [
-    "task.claim",
-    "task.result",
-    "awaiting_assignment",
-    "actor.leave"
-  ]
-}

package/dist/fixtures/protocol/room-message.json

@@ -1,11 +0,0 @@
-{
-  "to": "room:demo",
-  "from": "branch:demo/worker",
-  "type": "task.result",
-  "summary": "Worker completed task",
-  "body": {
-    "id": "inbox-001",
-    "result": "ok"
-  },
-  "received_at": "2026-05-26T00:00:00.000Z"
-}

package/dist/fixtures/protocol/room-roster.json

@@ -1,11 +0,0 @@
-{
-  "room": "main",
-  "members": {
-    "branch:demo/worker": {
-      "display": "worker",
-      "role": "worker",
-      "status": "present",
-      "last_seen": "2026-05-26T00:00:00.000Z"
-    }
-  }
-}

package/dist/fixtures/protocol/run-inbox-message.json

@@ -1,9 +0,0 @@
-{
-  "id": "inbox-001",
-  "status": "queued",
-  "queued_at": "2026-05-26T00:00:00.000Z",
-  "to": "run:demo",
-  "from": "coordinator",
-  "type": "control.continue",
-  "body": "continue"
-}

package/dist/fixtures/protocol/run-outbox-event.json

@@ -1,9 +0,0 @@
-{
-  "id": "event-001",
-  "type": "task.result",
-  "summary": "Worker completed task",
-  "body": {
-    "result": "ok"
-  },
-  "created_at": "2026-05-26T00:00:00.000Z"
-}

package/dist/lib/mailbox-loop.d.ts

@@ -1,41 +0,0 @@
-/**
- * Mailbox worker loop primitives.
- * Zones: mailbox-consuming actors, run/branch inbox claiming, handler status transitions
- * Owns reusable claim/handle/drain behavior across run and branch inboxes; scheduling and task policy stay outside.
- */
-import { type BranchInboxRecord } from "./rooms.ts";
-import { type RunInboxMessage } from "./async-runs.ts";
-export type MailboxLoopMessage = RunInboxMessage | BranchInboxRecord;
-export type MailboxLoopTarget = {
-    kind: "run";
-    runOrDir: string;
-} | {
-    address: string;
-    kind: "branch";
-    run: string;
-    stateDir: string;
-};
-export interface MailboxLoopClaimOptions {
-    owner?: string;
-    statuses?: string[];
-}
-export interface MailboxLoopHandleResult {
-    handled: boolean;
-    id?: string;
-    message?: MailboxLoopMessage;
-    target: MailboxLoopTarget;
-}
-export interface MailboxLoopDrainOptions extends MailboxLoopClaimOptions {
-    maxMessages?: number;
-    stopOnControl?: boolean;
-}
-export interface MailboxLoopDrainResult {
-    handled: number;
-    stopped: boolean;
-    target: MailboxLoopTarget;
-}
-export declare function isMailboxLoopStopMessage(message: unknown): boolean;
-export declare function claimMailboxLoopMessage(target: MailboxLoopTarget, options?: MailboxLoopClaimOptions): MailboxLoopMessage | undefined;
-export declare function updateMailboxLoopMessageStatus(target: MailboxLoopTarget, id: string, status: "claimed" | "handled" | "failed", metadata?: Record<string, unknown>): boolean;
-export declare function handleMailboxLoopOnce(target: MailboxLoopTarget, handler: (message: MailboxLoopMessage) => Promise<void> | void, options?: MailboxLoopClaimOptions): Promise<MailboxLoopHandleResult>;
-export declare function drainMailboxLoopMessages(target: MailboxLoopTarget, handler: (message: MailboxLoopMessage) => Promise<void> | void, options?: MailboxLoopDrainOptions): Promise<MailboxLoopDrainResult>;