@llblab/pi-actors 0.43.0 → 0.43.1

package/dist/scripts/release-gates.mjs

@@ -145,13 +145,44 @@ try {
   }
   console.log("[release] removed-surface and legacy-fallback allowlists checked");
 
-  const baselineShippedLines = 35_077;
+  const directTraceWrite = /(?:appendFileSync|writeFileSync|writeText(?:Atomic)?)\s*\(\s*[A-Za-z0-9_.]*?(?:trace|event)(?:Path|File)/iu;
+  for (const path of files.filter((candidate) =>
+    (candidate.startsWith("lib/") && candidate.endsWith(".ts")) ||
+    (candidate.startsWith("scripts/") && candidate.endsWith(".mjs"))
+  )) {
+    if (path === "lib/runs-trace.ts") continue;
+    check(!directTraceWrite.test(stagedText(path) ?? ""), `direct Trace writer outside canonical authority: ${path}`);
+  }
+  const canonicalTrace = stagedText("lib/runs-trace.ts") ?? "";
+  check(/withFileMutationLock\(path/u.test(canonicalTrace), "canonical Trace append lacks mutation lock");
+  for (const path of [
+    "scripts/async-runner.mjs",
+    "scripts/locker.mjs",
+    "scripts/music-player.mjs",
+  ]) {
+    const text = stagedText(path) ?? "";
+    check(
+      text.includes('importRuntimeModule("runs-trace")') && text.includes("appendRunTraceEvent"),
+      `first-party Trace writer bypasses canonical runtime module: ${path}`,
+    );
+  }
+  console.log("[release] canonical Trace writer residue checked");
+
+  check(
+    (stagedText("scripts/validate-recipe.mjs") ?? "").includes(
+      "qaReport.diagnostics.length === 0 && qaReport.warnings.length === 0",
+    ),
+    "Recipe QA warnings are not release-blocking",
+  );
+  console.log("[release] zero-warning Recipe QA gate checked");
+
+  const baselineShippedLines = 28_853;
   const shippedPath = /^(?:lib\/|scripts\/|recipes\/|docs\/|skills\/)/u;
   const shippedLines = files
     .filter((path) => shippedPath.test(path))
     .reduce((total, path) => total + (((stagedText(path) ?? "").match(/\n/gu) ?? []).length + 1), 0);
   check(shippedLines < baselineShippedLines, `shipped lines ${shippedLines} are not below baseline ${baselineShippedLines}`);
-  console.log(`[release] shipped lines ${shippedLines} < frozen baseline ${baselineShippedLines}`);
+  console.log(`[release] shipped lines ${shippedLines} < released baseline ${baselineShippedLines}`);
 
   const sources = files.filter((path) => path === "index.ts" || (path.startsWith("lib/") && path.endsWith(".ts")));
   const sourceSet = new Set(sources);

package/dist/scripts/validate-recipe.mjs

@@ -29,7 +29,7 @@ export function validateRecipeUsage() {
   return `Usage:
   validate-recipe.mjs <recipe-file-or-dir> [--all] [--qa] [--summary]
 
-Validates one template recipe file, or all *.json/*.md files in a directory when --all is set. Add --qa for packaged-recipe quality checks. Add --summary for compact CLI output.`;
+Validates one template recipe file, or all *.json/*.md files in a directory when --all is set. Add --qa for packaged-recipe quality checks, where diagnostics and warnings fail validation. Add --summary for compact CLI output.`;
 }
 
 function expandPath(value) {
@@ -120,8 +120,6 @@ function validateHelperPaths(file, config) {
 function qaDiagnostics(file, config) {
   const diagnostics = [];
   const warnings = [];
-  if (typeof config.description !== "string" || !config.description.trim())
-    warnings.push("description: missing or empty");
   if (config.mailbox !== undefined)
     diagnostics.push("recipe.mailbox was removed; use control actions and Trace events");
   diagnostics.push(...validateArtifactDeclarations(config));
@@ -138,7 +136,7 @@ function qaDiagnostics(file, config) {
 }
 
 function qaOk(qaReport) {
-  return qaReport.diagnostics.length === 0;
+  return qaReport.diagnostics.length === 0 && qaReport.warnings.length === 0;
 }
 
 function validateFile(file, qa = false) {
@@ -225,6 +223,9 @@ function summarizeReport(report) {
         ...(result.qa?.diagnostics?.length
           ? { diagnostics: result.qa.diagnostics }
           : {}),
+        ...(result.qa?.warnings?.length
+          ? { warnings: result.qa.warnings }
+          : {}),
       })),
   };
 }

package/dist/skills/actors/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: actors
 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.
-metadata:
-  version: 0.43.0
 ---
 
 # Actors (pi-actors)
@@ -38,20 +36,28 @@ Prefer maintained packaged Recipes over ad hoc wrappers. Keep model, thinking, m
 Trace records bounded structured observations in `trace.jsonl`:
 
 ```json
-{"id":"…","ts":"…","kind":"progress.update","summary":"…","data":{},"level":"info","attention":"notify"}
+{
+  "id": "…",
+  "ts": "…",
+  "kind": "progress.update",
+  "summary": "…",
+  "data": {},
+  "level": "info",
+  "attention": "notify"
+}
 ```
 
-Trace never carries sender, recipient, route, reply, or message-envelope fields. 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.
+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.
 
 ## Control
 
 The public Control request is exact:
 
 ```json
-{"target":"run:<id>","action":"pause","input":{},"verbose":false}
+{ "target": "run:<id>", "action": "pause", "input": {}, "verbose": false }
 ```
 
-Controls persist in `controls.jsonl` before delivery. 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. Expected-status-fenced transitions remain monotonic when a fast consumer completes before sender delivery evidence. FIFO documents must fit the portable 512-byte atomic-write bound, partial writes fail, and controlled FIFO readers remain gap-free across writers. Delivery revalidates owner, generation, running state, and process identity under the lifecycle lock.
+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.
 
 `kill` remains a runtime lifecycle action. Use an actor-local action such as `stop` only when the Recipe declares and implements it.
 
@@ -90,7 +96,6 @@ If work may outlive the current turn, needs steering, produces artifacts, fans o
 
 ## Deep References
 
-- [Actors deep reference](../../docs/actors-deep-reference.md)
 - [Recipe library](../../docs/recipe-library.md)
 - [Async Runs](../../docs/async-runs.md)
 - [Baseline and preservation gates](../../docs/0.43-baseline.md)

package/dist/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.43.0
 ---
 
 # Swarm

package/docs/0.43-baseline.md

@@ -1,12 +1,21 @@
-# 0.43 Migration Baseline
+# Released 0.43 Baseline
 
-Release `0.43.0` uses commit `14e46931899347f08b3f1db94bc03a4f260e75a6` (`0.42.3`) as the frozen preservation and compression baseline.
+Release `0.43.0` is frozen at commit `0d6db30cd2e070c1d03ed1e60bef70538a3083c1`. Local and remote `main`, immutable tag `v0.43.0`, the GitHub Release, and `@llblab/pi-actors@0.43.0` all resolve to that commit. The npm artifact records the same `gitHead`, shasum `64b5982bc1cda5723ce2f80f4ed15476b6016d62`, and `latest` dist-tag.
 
-Commit `261297a2250711ca7f412a489cce4477ef899e89` has the same Git tree, so the two commits contain no product-code delta. The release gate may use the former as the canonical baseline while `dev` starts from the latter topology.
+The continuing `dev` line descends from release parent `f4e4e78891e0c3d570b31c35572aeaa226af6f91`, whose tree exactly matches the tagged merge tree. This preserves content equivalence without copying the content-neutral merge wrapper into `dev`.
 
-## Shipped-line ceiling
+## Reproduced Evidence
 
-The baseline contains 35,077 lines under the shipped surfaces measured by `scripts/release-gates.mjs`:
+An isolated detached `v0.43.0` worktree produced this evidence on 2026-08-11:
+
+- `npm ci` succeeded with 147 installed packages. Its generic audit summary included three peer-tree findings; the package-owned `--omit=peer` audit passed with zero vulnerabilities.
+- `npm run test:preservation` passed 91 of 91 tests.
+- `npm run release:validate` passed 525 tests with 5 platform skips, 106 conformance tests, 58 Recipe QA files, package dry-run, removed-surface checks, strict Domain DAG, and ABCd context validation.
+- GitHub reported no open issue or pull request requiring post-release scope changes.
+
+## Shipped-Line Ratchet
+
+The released tree contains exactly **28,853** lines under the surfaces measured by `scripts/release-gates.mjs`:
 
 - `lib/`
 - `scripts/`
@@ -14,31 +23,17 @@ The baseline contains 35,077 lines under the shipped surfaces measured by `scrip
 - `docs/`
 - `skills/`
 
-Release validation fails when the retained shipped tree exceeds that ceiling. The ceiling guards the breaking communication-plane deletion against replacement bloat; it does not grant deleted communication behavior preservation status.
+Release validation requires every retained post-`0.43.0` tree to remain strictly below 28,853 lines. Tests, fixtures, and workflows remain outside this existing metric. The ratchet prevents deleted communication-plane code from funding replacement bloat; it does not grant removed behavior preservation status.
 
-## Retained invariants
+## Retained Invariants
 
-The preservation suite keeps evidence for the safety properties that survive the migration:
-
-- owner-filtered Run discovery;
-- immutable `run_instance_id` fencing;
-- process identity checks and canonical lifecycle locking;
-- shutdown kill and parent teardown;
-- terminal reconciliation and bounded captures;
-- owned Pi session provenance;
-- path containment and structured redaction;
-- automatic-review retry, reset, transaction, and lineage safety;
-- generation-bound Control and canonical Trace evidence.
-
-Rooms, peer routing, messages, mailboxes, communication topology, and their tests do not belong to the retained baseline.
+The preservation suite covers owner-filtered Run discovery, immutable generation fencing, process identity, lifecycle locking, shutdown and parent teardown, terminal reconciliation, bounded complete captures, Pi session provenance, path containment, redaction, review recovery, generation-bound Control, and canonical Trace. Rooms, routing, addressed messages, mailboxes, and communication topology are not retained.
 
 ## Validation
 
-Run:
-
 ```bash
 npm run test:preservation
 npm run release:validate
 ```
 
-The release gate also rejects removed-surface residue, Domain DAG violations, ABCd context drift, stale package contents, and shipped-line growth above the frozen ceiling.
+Release gates also reject removed-surface residue, Domain DAG violations, ABCd context drift, stale package contents, and shipped-line growth at or above the released baseline.

package/docs/README.md

@@ -4,16 +4,14 @@ Living index of all documentation in the `/docs` directory.
 
 ## Documents
 
-- [0.43-baseline.md](./0.43-baseline.md) — Frozen `0.42.3` line counts and retained-invariant preservation gate
-- [actors-deep-reference.md](./actors-deep-reference.md) — Recipe navigator, operating patterns, lifecycle discipline, and pitfalls
+- [0.43-baseline.md](./0.43-baseline.md) — Released tree, strict shipped-line ratchet, and retained-invariant preservation evidence
 - [command-templates.md](./command-templates.md) — Portable synchronous command execution standard
 - [template-recipes.md](./template-recipes.md) — Saved JSON/Markdown recipe standard, imports, and reusable command-template graph composition
 - [async-runs.md](./async-runs.md) — Run lifecycle, state, Control, Trace, cancellation, and terminal reconciliation
 - [actor-inspector.md](./actor-inspector.md) — Owner-filtered actor-instance navigation through Recipe, Trace, and Control
 - [tool-registry.md](./tool-registry.md) — Local `pi-actors` registry storage and `register_tool` adaptation
 - [recipe-library.md](./recipe-library.md) — Packaged standard recipe library such as async subagents, coordinator pipelines, utilities, and music playback
-- [task-first-recipes.md](./task-first-recipes.md) — Task-first design map for deriving high-level recipes and missing component cells
-- [component-recipes.md](./component-recipes.md) — Weak component-recipe contract for composing subagent coordinator building blocks
+- [releasing.md](./releasing.md) — Guarded tag validation, npm Trusted Publisher setup, registry verification, and GitHub Release convergence
 
 ## Root Context
 

package/docs/actor-inspector.md

@@ -18,13 +18,13 @@ Shows captured execution provenance:
 - declared artifacts and actor-local actions;
 - model/thinking policy and launch source.
 
-Captured Recipe evidence belongs to the Run generation and does not change when an active Recipe file later changes.
+Captured Recipe evidence belongs to the Run generation and does not change when an active Recipe file later changes. Non-empty object values render as indented brace-delimited property lists rather than flattened inline strings.
 
 ## Trace
 
 Shows the unified bounded Trace projection. Sources include lifecycle/runtime observations, Controls, owned Pi turns, command-log tails, results, artifacts, and diagnostics. Filter by source and open a row for structured detail.
 
-Trace ordering stays deterministic and newest-first. The projection applies path containment and redaction before rendering.
+Trace ordering stays deterministic and newest-first. Row numbers still read chronologically from bottom to top: the oldest visible event is `#1` and the newest carries the highest number. The projection applies path containment and redaction before rendering.
 
 ## Control
 
@@ -35,14 +35,14 @@ Shows:
 - generation-fenced endpoint readiness;
 - recent durable Control records and outcomes.
 
-A service endpoint counts as ready only when `control-endpoint.json` matches the Run's immutable `run_instance_id`.
+A service endpoint counts as ready only when `control-endpoint.json` matches the Run's immutable `run_instance_id`. Recent Control input and errors use the same bounded structured redaction as tool inspection. The durable `controls.jsonl` journal remains raw and local; rendering never mutates it or attaches an unredacted copy.
 
 ## Keys
 
 The footer displays current bindings. Use tab navigation to switch Recipe/Trace/Control, movement keys to select rows, detail navigation to inspect evidence, refresh to reconcile disk state, and the documented kill key for lifecycle termination.
 
-Run kill revalidates owner and generation through the canonical lifecycle path. The Inspector never edits state directly and never derives authority from displayed data.
+Run kill revalidates owner and generation through the canonical lifecycle path. After success, the Run status header is the sole confirmation; the content area does not duplicate it. The Inspector never edits state directly and never derives authority from displayed data.
 
 ## Scope
 
-The Actor Inspector treats each Run as a concrete actor instance. It does not expose group conversations, peer addresses, routing, or communication topology. Use `inspect target=runtime`, `inspect target=recipes`, and `inspect target=tool:<name>` for non-Run management targets.
+The Actor Inspector treats each Run as a concrete actor instance. It does not expose group conversations, peer addresses, routing, or communication topology. Use `inspect target=runtime view=status`, `inspect target=recipes view=status`, and `inspect target=tool:<name> view=status` for non-Run management targets.

package/docs/async-runs.md

@@ -55,7 +55,7 @@ Trace records strict bounded events:
 {"id":"…","ts":"…","kind":"command.done","summary":"Command completed","data":{"code":0},"level":"info","attention":"followup"}
 ```
 
-Required fields: `id`, `ts`, `kind`. Optional fields: `summary`, `data`, `level`, `attention`. Trace rejects addressed-envelope fields and malformed or oversized data.
+Required fields: `id`, `ts`, `kind`. Optional fields: `summary`, `data`, `level`, `attention`. Trace rejects addressed-envelope fields and malformed or oversized data. All first-party writers use the canonical append authority, which validates and size-checks inside a token-owned cross-process lock before one append-only JSONL write.
 
 Runtime lifecycle, runner progress, command completion, cancellation, kill, parent teardown, and controlled-service observations use Trace. `inspect view=trace` projects these events with Controls, owned Pi turns, logs, results, artifacts, and diagnostics under a deterministic global bound.
 
@@ -82,7 +82,7 @@ The runtime:
 5. writes the exact `{id, action, input?}` wire document to FIFO or named pipe;
 6. records delivered or failed outcome.
 
-Unix services may publish a FIFO; native Windows services publish a Windows named pipe. Native Windows FIFO delivery fails before transport rather than degrading to another protocol. FIFO wire documents above the portable 512-byte atomic-write bound fail before writing; named pipes retain the general Control input bound.
+Unix services may publish a FIFO; native Windows services publish a Windows named pipe. Native Windows FIFO delivery fails before transport rather than degrading to another protocol. Both transports admit the same 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. Invalid envelopes fail before journal admission or transport. Put larger data in a declared artifact/path and send only a bounded reference or instruction through Control.
 
 A service claims queued or transport-delivered Controls and records handled/failed outcomes under the token-owned Control journal lock. Journal snapshots replace atomically, and expected-status fencing prevents delivery failure evidence from regressing a Control already claimed or completed by a fast consumer. Terminal compaction remains bounded. Services capture their startup generation, so stale-generation Controls never execute.
 

package/docs/command-templates.md

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

package/docs/recipe-library.md

@@ -37,7 +37,7 @@ Artifact pipelines terminate in files/manifests and result evidence; they do not
 - `music-player.json` — playback service with declared playback actions, `controls.jsonl`, generation-fenced endpoint readiness, state artifact, and playback Trace. Player selection is `player:enum(auto,mpv,afplay,ffplay,cvlc,play,wmp)=auto`.
 - `resource-locker.json` — optional queue/lease-lock service with explicit owner/resource input and lock Trace.
 
-These are the packaged Recipes that declare actor-local Control. Ordinary one-shot Recipes omit it.
+These are the packaged Recipes that declare actor-local Control. Ordinary one-shot Recipes omit it. Helper-backed packaged Recipes self-locate their installed package root when `repo` is omitted; an explicit caller value still wins for development or custom layouts.
 
 ## Component Recipes
 
@@ -76,12 +76,10 @@ Do not bulk-copy `recipes/*.json` into the user Recipe root. Internal `draft-rev
 npm run recipes:qa
 ```
 
-Recipe QA validates syntax, imports, Control declarations, artifact paths, helper references, and platform documentation. Removed mailbox declarations fail with the migration diagnostic rather than receiving automatic conversion.
+Recipe QA validates syntax, imports, Control declarations, artifact paths, helper references, and platform documentation. Recipe descriptions are optional because discovery supplies stable fallback tool copy; internal component Recipes do not need boilerplate. The packaged baseline requires zero diagnostics and zero warnings, and any future warning is release-blocking with its concrete file and repair. Removed mailbox declarations fail with the migration diagnostic rather than receiving automatic conversion.
 
 ## Related
 
 - [Template Recipes](./template-recipes.md)
 - [Command templates](./command-templates.md)
 - [Runs](./async-runs.md)
-- [Component Recipes](./component-recipes.md)
-- [Task-first design](./task-first-recipes.md)

package/docs/releasing.md

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

package/docs/template-recipes.md

@@ -87,7 +87,7 @@ Only a process that consumes actor-local input declares actions:
 }
 ```
 
-Actions must be lowercase, unique, and non-reserved. One-shot Recipes omit Control. Outputs belong in Trace, artifacts, execution evidence, or the command result.
+Actions must be lowercase ASCII, unique, non-reserved, and at most 64 characters. Serialized Control input is at most 380 bytes so every admitted wire record remains within 512 bytes on FIFO and named pipe. One-shot Recipes omit Control. Larger data belongs in a declared artifact/path; outputs belong in Trace, artifacts, execution evidence, or the command result.
 
 ## Artifacts
 

package/docs/tool-registry.md

@@ -27,8 +27,8 @@ User Recipes take priority over packaged Recipes. Active invalid or disabled sha
 Inspect registry state with:
 
 ```text
-inspect target=recipes
-inspect target=tool:<name>
+inspect target=recipes view=status
+inspect target=tool:<name> view=status
 ```
 
 Recipe inspection reports active, shadowed, invalid, disabled, diagnostic, risk, usage, and review evidence. Tool inspection reports the current capability definition/schema; a registered tool is not a running actor.

package/index.ts

@@ -110,7 +110,7 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
         Tools.resolveActiveRuntimeTool(name, runtime.getTools(), (activeName) =>
           actorToolDefinitions.get(activeName),
         ),
-      handleRuntimeMessage: automaticReview.handleMessage,
+      handleRuntimeControl: automaticReview.handleControl,
       registryRuntime: runtime,
       setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
     }).map(withCurrentThinkingContext),

package/lib/async-runs.ts

@@ -59,6 +59,7 @@ import {
   verifyRunProcessIdentity,
   type RunProcessIdentity,
 } from "./runs-process.ts";
+import * as RuntimeIdentity from "./runtime-identity.ts";
 import * as RunsStart from "./runs-start.ts";
 import { appendRunTraceEvent } from "./runs-trace.ts";
 import * as RunsIndex from "./runs-index.ts";
@@ -173,7 +174,7 @@ export interface AsyncRunMeta {
   run: string;
   run_instance_id: string;
   state_dir: string;
-  state_schema: "run-kernel-v1";
+  state_schema: typeof RuntimeIdentity.RUN_STATE_SCHEMA;
   status: AsyncRunStatus;
   tool?: string;
   template: CommandTemplateValue;
@@ -466,7 +467,22 @@ export function startRun(
   const resolved = resolveRunTemplate(startParams);
   const run = safeRunId(startParams.run_id);
   const stateDir = resolveStateDir(startParams, run);
+  const recipeFile = startParams.file
+    ? resolveRecipeFile(startParams.file)
+    : undefined;
+  const packagedRecipeRoot = resolve(Paths.getPackagedRecipeRoot());
+  const recipeRelation = recipeFile
+    ? relative(packagedRecipeRoot, recipeFile)
+    : undefined;
+  const packagedRepo =
+    startParams.defaults?.repo === "~/.pi/agent/extensions/pi-actors" &&
+    recipeRelation &&
+    !recipeRelation.startsWith("..") &&
+    !isAbsolute(recipeRelation)
+      ? dirname(packagedRecipeRoot)
+      : undefined;
   const values = {
+    ...(packagedRepo ? { repo: packagedRepo } : {}),
     ...(startParams.values || {}),
     run_id: run,
     state_dir: stateDir,
@@ -494,9 +510,6 @@ export function startRun(
     prepareStateDirForStart(stateDir);
     const stdout = join(stateDir, "stdout.log");
     const stderr = join(stateDir, "stderr.log");
-    const recipeFile = startParams.file
-      ? resolveRecipeFile(startParams.file)
-      : undefined;
     const recipe = startParams.name || getRunIdFromFile(recipeFile);
     const includeActorRecipeContext =
       startParams.actor_context !== false &&
@@ -545,7 +558,7 @@ export function startRun(
       run,
       run_instance_id: randomUUID(),
       state_dir: stateDir,
-      state_schema: "run-kernel-v1",
+      state_schema: RuntimeIdentity.RUN_STATE_SCHEMA,
       status: "running",
       ...(startParams.tool ? { tool: startParams.tool } : {}),
       template: resolved.template,

package/lib/automatic-review-runtime.ts

@@ -16,7 +16,7 @@ import * as ToolReviewScheduler from "./tool-review-scheduler.ts";
 
 export interface AutomaticReviewRuntime {
   close(): void;
-  handleMessage(type: string, body: unknown): Record<string, unknown>;
+  handleControl(action: string, input: unknown): Record<string, unknown>;
   schedule(): void;
   start(ctx: Pi.ExtensionContext): void;
 }
@@ -52,18 +52,18 @@ export function createAutomaticReviewRuntime(
 
   return {
     close,
-    handleMessage(type, body) {
-      if (type !== "review.retry" && type !== "review.reset") {
-        throw new Error("tool:pi-actors accepts review.retry or review.reset messages.");
+    handleControl(action, input) {
+      if (action !== "review.retry" && action !== "review.reset") {
+        throw new Error("runtime accepts review.retry or review.reset Controls.");
       }
-      if (type === "review.retry" && !Paths.isAutomaticRecipeReviewEnabled()) {
+      if (action === "review.retry" && !Paths.isAutomaticRecipeReviewEnabled()) {
         throw new Error(
           "Automatic recipe review is disabled by PI_ACTORS_AUTOMATIC_REVIEW.",
         );
       }
       return ReviewControl.controlAutomaticReview(
-        type,
-        ReviewControl.parseAutomaticReviewScope(body),
+        action,
+        ReviewControl.parseAutomaticReviewScope(input),
         {
           scheduleDraft: () => draftScheduler?.schedule(),
           scheduleTool: () => toolScheduler?.schedule(),