@llblab/pi-actors 0.42.3 → 0.43.1

package/AGENTS.md

@@ -2,191 +2,143 @@
 
 ## Meta-Protocol Principles
 
-- `Constraint-Driven Evolution`: Add structure when real project constraints justify it.
-- `Single Source of Truth`: Keep durable protocol, open work, completed delivery, and docs in separate files.
-- `Context Hygiene`: Compress stale context before it becomes coordination drag.
-- `Boundary Clarity`: README is the human entrypoint, `AGENTS.md` is durable protocol, `BACKLOG.md` is open work, and `CHANGELOG.md` is delivery history.
+- `README.md`: human product entrypoint.
+- `AGENTS.md`: durable implementation protocol.
+- `BACKLOG.md`: canonical future-only work.
+- `CHANGELOG.md`: completed delivery history.
+- `docs/README.md`: documentation index.
+
+Keep these surfaces distinct and reconcile them after meaningful changes. Every release section, historical or new, keeps at most 8 outcome records of at most 512 characters.
 
 ## Concept
 
-`pi-actors` is a local-first actor runtime and orchestrator for Pi. It wraps trusted local programs, scripts, services, pipelines, and recipes as addressable actors that agents can `spawn`, control with typed `message` envelopes, and observe with `inspect`. It also persists user/agent-registered actor-control tools as recipe files under `~/.pi/agent/recipes`, giving agents durable operational muscle memory for launching and managing the local actor zoo.
+`pi-actors` is a local Run kernel and persistent capability registry for Pi:
+
+```text
+Recipe --spawn--> Run
+Run = Recipe + Trace + Control
+```
+
+An actor is any runnable local capability, including a script, tool, service, pipeline, or subagent. Recipes define actors' reusable execution. Runs are concrete actor instances and own one generation of execution and evidence. Trace owns observations. Control owns actor-local inputs for services that actually consume them. `register_tool` persists capabilities separately.
 
-Treat this extension as an experimental self-evolution membrane for the agent harness: a way for agents that are not pretrained on local workflows to acquire, preserve, inspect, and refine operational capabilities through explicit local actors, recipes, fixtures, skills, and state rather than hidden assumptions. Keep that potential grounded in small, testable, operator-visible protocol slices.
+Public Run verbs remain `spawn`, `message`, and `inspect`.
 
-## Topology
+## Core Structure
 
 ```text
 Pi host
-  -> index.ts composition root
-     -> lib/tools*.ts / prompts.ts      public tool + injected prompt surface
-     -> lib/runtime.ts / registry.ts     active user recipe tools
-     -> lib/recipes-*.ts                 packaged/user/draft recipe discovery
-     -> lib/async-runs.ts                spawn lifecycle and run state
-     -> lib/rooms.ts               room, roster, mailbox, communication log
-     -> scripts/*.mjs                    self-contained process entrypoints
-     -> recipes/*.json                   packaged actor components
-     -> skills/* + docs/*                agent guidance and transportable specs
+  -> index.ts                         composition root
+     -> lib/tools*.ts                 public tool adapters
+     -> lib/runtime.ts / registry.ts  active user Recipe tools
+     -> lib/recipes-*.ts              Recipe resolution/evolution
+     -> lib/async-runs.ts             Run lifecycle facade
+     -> lib/runs-*.ts                 focused lifecycle/evidence domains
+     -> lib/observability.ts          terminal + Trace-attention observation
+     -> lib/inspector*.ts             owner-filtered actor-instance inspection
+     -> scripts/*.mjs                 process/service entrypoints
+     -> recipes/*.json                packaged Recipe library
+     -> skills/* + docs/*             agent and human guidance
 ```
 
-- `/index.ts`: Minimal extension coordinator/composition root. It wires live pi ports and should avoid owning domain behavior.
-
-## Domain Modules
-
-- `/lib/*.ts`: Flat Domain DAG modules for cohesive reusable behavior.
-  - `command-templates.ts`: portable command-template execution graph.
-  - `tools-access.ts`: shared public tool access/session ownership guards and normalized mismatch diagnostics.
-  - `tools-mailbox.ts`: mailbox contract normalization and accepted/emitted message type helpers for public tool responses.
-  - `schema.ts`: tool arg declarations and placeholder-derived schemas.
-  - `identity.ts`, `paths.ts`, `config.ts`: names, paths, and persistence.
-  - `registry.ts`, `runtime.ts`: register/update/delete, load/conflict/registration coordination.
-  - `execution.ts`, `execution-output.ts`, `limits.ts`: registered-tool execution and bounded output.
-  - `recipes-references.ts`, `recipes-discovery.ts`, `recipes-usage.ts`, `draft-review.ts`, `draft-sleep.ts`, `tool-review.ts`, `tool-review-scheduler.ts`, `tool-review-transaction.ts`, `tool-review-lineage.ts`, `tool-review-lineage-transaction.ts`, `review-projection.ts`, `review-diagnostics.ts`, `review-control.ts`, `draft-consolidation.ts`, `draft-consolidation-transaction.ts`: recipe graph/discovery, automatic review admission, journaled filesystem and lineage execution/recovery, and bounded diagnostics.
-  - `async-runs.ts`: detached run lifecycle facade; `runs-*` subdomains own artifacts, start guards, status, indexes, inbox/outbox, delivery, process control, and retention internals.
-  - `runtime-notifier.ts`, `mailbox-loop.ts`: wake notifications and reusable run/branch mailbox worker loops.
-  - `messages.ts`, `rooms.ts`, `recipes-context.ts`, `session-evidence.ts`, `inspector.ts`, `inspector-overlay.ts`, `observability.ts`: addressed message protocol, rooms, recipe prompt context, bounded/redacted child-session turns, inspector evidence/navigation, keyboard-driven overlay UI, and ambient run status.
-  - `prompts.ts`, `temp.ts`: LLM-facing copy and temp cleanup.
-  - `automatic-review-runtime.ts`, `run-ui-runtime.ts`, `inspector-command.ts`: session-bound review composition, ambient run-observability lifecycle, and Inspector host-command adapters kept outside the entrypoint.
-  - `tools.ts`: public tool family composition and reserved tool names.
-  - `tools-message.ts`: public `message` tool behavior, including run controls, branch/room routing, tool actor invocation, and delivery feedback.
-  - `tools-inspect.ts`: public `inspect` tool behavior, including recipe registry, room/session/tool/run views, and observation formatting.
-  - `tools-spawn.ts`: public `spawn` tool behavior, including actor launch, draft recipe capture, and launch diagnostics.
-  - `tools-local.ts`: saved local capability execution, generated schemas, value normalization, and async recipe launch.
-  - `tools-register.ts`: public `register_tool` behavior and schema for persisted local capability registration.
-  - `tools-response.ts`: compact model-facing responses and next-action rendering shared by public tool execution paths.
-
-## Repo Surfaces
-
-- `/scripts/*.mjs`: Stable executables for detached/helper processes. Prefer self-contained script ownership; do not preemptively move script logic into `lib/` just to make scripts thin.
-- `/lib/*.ts`: Compiled reusable domains for the extension/runtime. Move script behavior into `lib/` only when it has real non-script consumers or belongs to an existing reusable domain. Packaged JS-only execution, tests, or shim neatness alone do not justify a new `lib/` domain.
-- `/recipes/*.json`: Packaged standard recipe library. Keep recipes optional, composable, policy-light, and caller-configurable.
-- `/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.
-- `/tests/*.test.ts`: Focused regression tests for pure domains.
-- `/README.md`: Human-facing install, usage, and runtime semantics. Keep it as a product/onboarding entrypoint rather than an implementation dump: identity → why it exists → core verbs → install → first run → address/message model → feature showcase → golden path → recipe memory → platform/safety/docs. Preserve both layers: strong local-actor-kernel positioning plus compact practical capability catalog.
-- `/BACKLOG.md`: Canonical open work; only completable future work.
-- `/CHANGELOG.md`: Completed delivery history.
-- `/docs/README.md`: Documentation index.
+`index.ts` wires Pi ports and must not own domain behavior. Keep the local TypeScript import graph acyclic.
+
+## Key Domains
+
+- `command-templates.ts`: portable synchronous execution graph.
+- `recipes-references.ts`, `recipes-discovery.ts`, `recipe-control.ts`: Recipe resolution, imports, shadowing, and Control declarations.
+- `async-runs.ts`: lifecycle facade.
+- `runs-start.ts`, `runs-status.ts`, `runs-control.ts`, `runs-control-delivery.ts`, `runs-controls.ts`, `runs-trace.ts`, `runs-process.ts`, `runs-retention.ts`, `runs-parent-teardown.ts`: focused Run internals.
+- `execution-sessions.ts`, `trace-projection.ts`, `control-projection.ts`, `session-evidence.ts`: bounded/redacted execution and inspection evidence.
+- `tools-message.ts`: exact Control facade.
+- `tools-inspect.ts`: exact `run:<id>`, `runtime`, `recipes`, and `tool:<name>` inspection.
+- `runtime-identity.ts`, `runtime-triage.ts`: immutable package/schema identity and pure pending/stale Control classification.
+- `tools-spawn.ts`, `tools-register.ts`, `tools-local.ts`, `tools-response.ts`: Run creation, persistent capabilities, Recipe-backed tools, and compact results.
+- `inspector.ts`, `inspector-overlay.ts`, `inspector-command.ts`, `inspector-actions.ts`: actor-instance Recipe/Trace/Control projection, navigation, command wiring, and fenced actions. **Actor Inspector** remains the product and command name, not a separate domain.
+- `observability.ts`, `runtime-notifier.ts`, `run-ui-runtime.ts`: Trace attention, terminal reconciliation, and Pi follow-up delivery.
+- automatic draft/tool review domains: structurally redacted model review, journaled mutation, lineage, recovery, and explicit retry/reset safety.
+
+Scripts remain self-contained when no non-script consumer justifies a TypeScript domain. Command-template script leaves infer `.js`/`.mjs` in order through Node, Bun, or `deno run` and `.sh` through Bash without shell evaluation. Helper-backed packaged Recipes self-locate their installed package root while explicit caller values remain authoritative. Recipes stay optional, composable, policy-light, and caller-configurable.
 
 ## Operating Principles
 
-- Automatic recipe evolution remains silent but mechanically fenced: no-tools reviewers select lifecycle/name operations from value-free structural projections without receiving recipe bodies, template/default values, authored prose, canonical names, draft basenames, raw content hashes, or filesystem paths; batch-local opaque occurrence IDs and equality-only content groups preserve decision correlation and deduplication, while sensitive active recipes stay outside model review as defense in depth, deterministic executors derive unchanged recipes from separate trusted captures, and safe-session activation separates approval from live registry mutation. `PI_ACTORS_AUTOMATIC_REVIEW=off` is the explicit startup opt-out and must disable both scheduling and safe-boundary activation while remaining visible in runtime status. Automatic portfolio review may keep, demote, rename, or deduplicate canonically identical recipes; replacement, split, and executable contract changes require explicit operator authoring. Transactions must hold canonical source/target locks, enforce compare-and-swap preconditions, preserve complete recipes, quarantine before commit, journal process-crash recovery phases, validate recovery CAS/hashes, and derive evidence from runtime outcomes. Prefer `register_tool draft=...` for a fenced manual single-draft override; deliberate filesystem promotion remains valid but may invalidate and defer an already captured batch.
-- Keep published documentation portable: use `~`, `<repo>`, or relative paths instead of machine-local absolute paths.
-- Preserve runtime output discipline because tool output flows directly into agent context. Tool result/error text contributes exactly one leading line break; Pi's renderer contributes the other break after the call header, producing one empty separator row without doubled gaps.
-- Optimize every actor-facing surface for signal over volume: prefer compact state-backed hints and fewer concepts over broad explanatory prose or speculative guidance.
-- Split broad domains proactively when the current name becomes a generic bucket. Prefer concise domain names that match actual ownership. `tools.ts` is the public tool family owner; decomposed tool subdomains use `tools-<part>.ts` (`tools-message.ts`, `tools-inspect.ts`, `tools-spawn.ts`) under that family. Keep only genuinely cross-family domains unprefixed (`schema.ts`); tool-only helpers stay under `tools-*`. If a `tools-*` helper becomes reused by non-tools domains, remove the `tools-` prefix in the same slice and update ownership comments/imports so the name matches its broader responsibility. Avoid redundant internal `actor-` file prefixes in this actor-scoped package unless the file is deliberately tied to a public actor-named recipe/script/docs surface.
-- Until a stable release greater than `1.x.x`, favor context compression over compatibility shims: do not preserve legacy actor-facing names, aliases, fields, env vars, paths, or docs solely for backward compatibility when a clearer current term exists. Remove compatibility layers in the same slice that renames a concept, and record the break in `CHANGELOG.md`.
-- Keep the project lens local-first and cybernetic: agents wrap durable local capabilities as actors, then use semantic tools and messages instead of repeatedly reconstructing shell commands.
-- Design recipes as agent-callable tools: make prompts, scopes, paths, models, and policy knobs public args/defaults when the caller should decide them at invocation time.
-- Decompose oversized bullets into sublists or hierarchy; long flat list items are a context-smell.
-
-## Knowledge Surfaces
-
-- Injected prompt: tiny bootstrap/reminder, never full docs.
-- Skill header: routing metadata that tells agents when to load a bundled skill.
-- Skill body: dense agent-facing operating manual for the matched concern.
-- README: public face of the project. Keep it current, focused, pruned, and limited to highest-signal scenarios.
-- `actors` skill: runtime/tooling manual for operating the extension and navigating high-value bundled recipes.
-- `swarm` skill: multi-agent methodology, strategies, standards, and portable examples.
-- `/docs`: detailed transportable standards read on demand.
-- `AGENTS.md`: durable project protocol for agents changing this repo.
-- Skill evolution is passive-active: when implementation yields durable mechanics, invariants, warnings, or orchestration lessons, update `skills/actors/SKILL.md` or `skills/swarm/SKILL.md` immediately instead of carrying evergreen skill-upkeep items in `BACKLOG.md`.
-
-## Public Actor Model
-
-- Preserve the public verbs: `spawn`, `message`, `inspect`.
-- Keep the model-facing concept ladder minimal: core is run actors, typed messages, intentional inspection, artifacts, and recipe/tool memory; group messaging, roster, branches, sessions, and diagnostics are advanced surfaces.
-- Prefer one typed actor-message envelope for upward, downward, lateral, parent/branch, and branch/parent messages.
-- Prefer actor addresses and inspect views over exposing FIFO, outbox, or status mechanics as public concepts.
-- Keep route and semantic type separate: delivery behavior comes from `to`, while `type` describes intent.
-- Treat dotted message types as the minimal action surface: `channel.action` should often be enough for script-backed actors, with `body` reserved for extra context or free-form prompts to LLM-backed actors.
-
-## Runtime Contract
-
-- Register trusted command templates with placeholder-derived args, progressive typed arg declarations, inline/default/`??`/ternary fallback, and split-first command argv construction.
-- Serialize extension-authored recipe mutations with canonical-path locks across each complete check/read/write/runtime-update window; keep usage and lineage evidence in the locked `.usage/recipes/<recipe-name>.json` ledger plus path index so metadata cannot overwrite authored recipes, and do not replace keyed recipe locking with a broad registry lock. Launch accounting is the narrow exception: it briefly shares the portfolio transaction’s canonical recipe-root fence before taking index/ledger locks, so quarantine cannot make an already-authorized launch disappear; a source that changed before that fence rejects the stale launch and asks for reload.
-- Keep command templates synchronous and portable; `async: true` is the detached run switch.
-- Preserve node controls: `when`, positive `timeout`, `delay`, bounded `retry`, `failure`, and `recover` cleanup.
-- Persist every async command's complete byte-exact stdout/stderr under command- and retry-specific run-state paths while keeping returned tails bounded and pipeline stdin complete.
-- Keep async run state under `~/.pi/agent/tmp/pi-actors/runs` with injected `{run_id}` and `{state_dir}` values.
-- Preserve event-driven observability with bounded reconciliation: file watchers accelerate durable retrying terminal follow-up notifications, while a conservative terminal-only interval recovers missed watcher activity, rearms degraded watchers, and never replays outbox traffic. Queue compact terminal coordinator notices through Pi follow-up delivery rather than steering so current work finishes before async results arrive and host follow-up batching policy can combine concurrent completions; LLM content contains only run id, status, one base path, and relative artifact names, while semantic output/error/correlation stays in non-LLM details and run state. Terminal delivery is at-least-once across the unavoidable send/handled-marker crash window; watch-triggered and periodic delivery share one live-runtime in-flight guard.
-- When a deferred actor result gates the next step, wait for its terminal follow-up. Do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs; inspect early only on operator request, meaningful actor event, or diagnosis of an overdue/stuck run.
-- Do not restore busy-polling examples, duplicate terminal notifications, or duplicate notifications for handled `cancel`, `kill`, or control-stop actions.
-
-## Recipes And Registry
-
-- `~/.pi/agent/recipes/*.json` is executable muscle memory: recipes there become persistent tools by location.
-- Preserve filename identity, atomic writes, explicit operator-gated changes, and local transportability. Extension-authored draft creation must take the same canonical per-path mutation lock used by consolidation so source compare-and-swap and quarantine cannot race a writer.
-- Recipe live reload must watch the parent when the user recipe root is absent, switch to the root watcher when it appears, and rearm after deletion/rename without polling or duplicate watcher ownership. Every callback must compare its exact watcher instance before closing, replacing, notifying, or scheduling so delayed callbacks from closed generations cannot affect the current watcher.
-- Packaged/ad hoc recipes outside the agent root are components, not user tools.
-- Register existing recipes by importing them from the user-root wrapper and using a `{ "name": "alias" }` template node; do not duplicate a ready recipe's script command, defaults, mailbox, or artifact contract in the wrapper.
-- Skill-owned scripts must be exposed through skill-owned recipes first. If a local tool needs that capability, import the skill recipe via `{agent}/skills/<skill>/recipes/<recipe>.json` instead of calling `{agent}/skills/<skill>/scripts/*` directly.
-- Tool definitions use `template`, not `script`, and built-in/core tool names must not be shadowed.
-- Host registrations may remain visible because Pi cannot unregister dynamic definitions, but extension-local `message` and `inspect` lookup must consult the current runtime recipe registry before returning or executing a cached definition.
-- Packaged recipe growth is demand-driven: prefer reusable components over speculative scenario catalogs.
-- Recipe templates may point directly at executable helper scripts when the recipe owns that script boundary; keep script executable bits and avoid unnecessary `node` prefixes.
-
-## Command And Recipe Layers
-
-- Keep command-template semantics in `docs/command-templates.md`.
-- Keep recipe storage/import/default/reference behavior in `docs/template-recipes.md`.
-- Keep detached lifecycle/state/IPC behavior in `docs/async-runs.md`.
-- Imported recipes are command-template-shaped definitions, not async-run instances.
-- Valid chain: `tool → template → recipe → run → template`; reject cyclic shortcuts.
-- Typed args support `string`, `path`, `int`, `number`, `bool`, `array`, and `enum(...)`.
-- Preserve both metadata-first args and inline-first placeholder style.
-
-## State, IO, And Safety
-
-- Tool stdout and temp state must stay bounded and local; preserve complete high-volume streams in spill files with byte/truncation metadata, and never feed a truncated capture tail into pipeline stdin.
-- Feedback hints must be evidence-backed, bounded, and action-shaped; prefer `next_actions` pointing to existing verbs over prose, and avoid hints when no concrete next step is justified.
-- Keep tail truncation, full-output temp files, failure formatting, and centralized limits intact.
-- Published docs must not include machine-local absolute paths.
-- Any view scanning run directories must apply coordinator/session ownership filters before exposing summaries or previews.
-- Actor Inspector remains evidence-first; its `Kill` action is available only for a focused owned running run, requires in-overlay confirmation, revalidates exact ownership/status at action time, routes through canonical `control.kill`, and renders bounded success/failure feedback without direct process signaling. Keep active key hints in the bottom border as one blue-key/border-accent-description rail joined by border-accent `─`, never as a dedicated body row or bullet-separated footer.
-- Direct branch messages are active inbox queues; guard branch-local append/status rewrites with the branch inbox lock and keep claim/handled/failed transitions tested.
-- Run-state launch and destructive retention require the runtime ownership marker bound to the canonical directory and run id; reject non-run directories, missing/mismatched markers, and symlink aliases rather than trusting `run.json`.
-- Runner lifecycle and destructive process controls require the persisted cross-platform process identity proof (start time, command, and cwd where available), revalidated at authorization and immediately before signaling; dead, mismatched, or unsupported proofs stay distinct and fail closed rather than degrading to pid liveness. On Unix, only process-group `ESRCH` followed by another matching identity proof permits exact-pid fallback. Keep the residual post-read OS PID/PGID reuse window explicit because Node lacks one portable identity-stable group handle.
-- Automatic draft review may schedule one silent review after ordinary `agent_end` only when twelve drafts exist and no actor is running; it must snapshot an exact batch, leave newer drafts for later, suppress routine terminal/outbox delivery, and never mutate recipes from the reviewer process.
-- Automatic tool review seeds zero-call lineage without fabricating launches, admits only current non-sensitive revisions lacking a review fingerprint, captures exactly thirty-six oldest eligible active user tools, and uses the same silent post-turn/active-actor boundary. Completed output becomes a size-bounded immutable approval only after result validation plus source and target CAS; approval must not mutate the live registry. Approved filesystem mutation uses intent-before-mutation journaling and source quarantine, composition invokes it only during `session_start` before runtime tool loading, persists `lineage_pending`, and must finalize lineage before quarantine cleanup. Failed cycles persist bounded stage/error/remediation evidence; explicit `review.retry`/`review.reset` messages to `tool:pi-actors` may reset counters or disposable state, but reset must reject approved/transaction/lineage evidence that requires roll-forward recovery. Draft retry must preserve the original reviewer run once a transaction journal exists and derive lineage/evidence from that authenticated journal plan, never from later reviewer output.
-- Parent-session teardown runs on every Pi `session_shutdown`, never ordinary `agent_end`: select discovered readable persisted `running` runs with the exact retiring session `ownerId`, carry immutable `run_instance_id` through canonical `control.kill`, serialize control against same-directory restart, fence teardown evidence to that generation, continue across partial failures, and leave terminal, ambiguous, changed-generation, or other-session runs untouched. Use unbounded teardown discovery, count unreadable/corrupt state as failures, and persist one bounded shutdown summary outside individual runs. Descendant Pi sessions remain separate exact owners and rely on their own shutdown hooks; hard termination keeps OS/manual orphan recovery as an honest boundary.
-- Room/branch provenance checks should validate that accepted `from` addresses belong to the addressed run.
-
-## Coordination And Lifecycle
-
-- Persistent implementer workflows are recipe composition, not one-off scripts.
-- Compose cells such as `coordinator-locker`, subagent launchers, actor-message utilities, and mailbox-loop helpers.
-- Preserve JSON envelope object shape across handoffs.
-- Keep locker state generic and thin; orchestration strategy belongs in the coordinator.
-- Graceful actor retirement is opt-in through recipe/run metadata and must not infer retirement for persistent services or backlog implementers.
-- Script helpers that spawn long-lived child processes should keep those children inside the async run's owned process group unless they also provide an explicit termination bridge; `control.kill` must not leave detached playback/service descendants alive.
-- True daemon recipes are allowed, but daemon ownership belongs to the recipe/script contract: persist a pid or service handle, verify ownership before signaling, expose status/stop semantics, and bridge `control.kill` to daemon cleanup instead of relying on the generic runner to discover detached services.
-
-## Context And Planning Hygiene
-
-- `BACKLOG.md` is planning, not history: only completable future work with current scope and exit criteria.
-- Completed delivery belongs in `CHANGELOG.md`.
-- Durable/evergreen behavior belongs in `AGENTS.md`, README, docs, or skills.
-- Changelog bullets describe meaningful user/operator/developer changes, not release bookkeeping.
-- PR/release summaries are temporary artifacts; keep durable release evidence in `CHANGELOG.md` and gates in `BACKLOG.md`.
-- Meaningful implementation or docs changes must reconcile `BACKLOG.md`, `CHANGELOG.md`, README, and docs navigation.
-
-## Validation
-
-- `npm run check`: Lightweight extension-load sanity check.
-- `npm test`: Focused regression tests for extracted pure domains.
-- `npm run pack:dry`: Verify package contents and npm metadata.
-- `npm run conformance`: Compact protocol conformance runner for actor/recipe behavior.
-
-## Pre-Task Preparation
-
-1. Read this file, `BACKLOG.md`, and `README.md`.
-2. Inspect `index.ts` around the touched tool/runtime path.
-3. Prefer targeted edits over broad rewrites.
-4. Run the smallest validation set that covers the touched scope.
-
-## Task Completion Protocol
-
-1. Reconcile backlog state with reality: close, narrow, split, defer, or gate items explicitly.
-2. Update README/docs when public behavior, setup, package contents, or navigation changes.
-3. Record meaningful delivered slices in `CHANGELOG.md`.
-4. Run relevant validation and report exact commands.
+### Recipe
+
+- Recipe files may define args/defaults, imports, artifacts, command-template flags, and `control`.
+- Declare actor-local actions only when a long-lived process implements them.
+- Actions are lowercase, unique, and cannot use runtime-reserved lifecycle names.
+- Removed communication-plane metadata fails explicitly; never translate it.
+- User Recipes shadow packaged definitions; invalid shadowing blocks fallback.
+- Files over 1 MiB, import depth over 32, and import cycles fail closed.
+
+### Trace
+
+Canonical event:
+
+```json
+{"id":"…","ts":"…","kind":"…","summary":"…","data":{},"level":"info","attention":"notify"}
+```
+
+Keep events bounded and free of addressing/routing fields. Every first-party writer must call `appendRunTraceEvent`; it validates and size-checks inside the canonical token-owned mutation lock, then performs one append-only JSONL write. Never append `trace.jsonl` directly from scripts. Use artifacts or execution captures for large evidence. `attention: "followup"` must remain rare and semantically justified.
+
+### Control
+
+Public shape:
+
+```json
+{"target":"run:<id>","action":"…","input":{},"verbose":false}
+```
+
+Admit only lowercase ASCII actions of at most 64 characters, serialized JSON input of at most 380 bytes, and complete newline-terminated wire records of at most 512 bytes on both FIFO and named pipe. Invalid envelopes remain outside the journal; persist every admitted Control before transport. Put larger data in a declared artifact/path and send only a bounded reference or instruction through Control. Fence every record and endpoint with immutable `run_instance_id`; controlled services capture that generation at startup. Serialize atomic journal replacement through token-owned dead-process-reclaiming locks, and keep status transitions expected-state-fenced and monotonic when consumers complete before producer delivery evidence. FIFO and named pipe are transport details, not public concepts; reject partial writes and keep FIFO readers gap-free across writers. Revalidate owner, generation, state, and process identity under the lifecycle lock immediately before delivery.
+
+Keep `controls.jsonl` raw and local for execution fidelity. Every model-facing and Actor Inspector Control surface must use the shared bounded `control-projection.ts` redaction before exposure; never attach a second raw copy in tool details.
+
+Runtime lifecycle and review actions remain runtime-owned.
+
+### Inspect
+
+Run views are exactly `recipe`, `trace`, and `control`. Non-Run management targets are `runtime`, `recipes`, and `tool:<name>`. Apply owner filtering and redaction before projecting evidence.
+
+## Retained Safety Invariants
+
+Never weaken:
+
+- owner filtering;
+- immutable generation fencing;
+- cross-platform process identity checks;
+- canonical lifecycle locks and same-directory restart serialization;
+- shutdown and parent-teardown kill;
+- terminal notification reconciliation and handled/failure evidence;
+- bounded logs, complete captures, and tool output;
+- owned Pi session provenance;
+- path containment, canonical ownership markers, and symlink rejection;
+- redaction of secrets and machine-local paths;
+- automatic review admission, CAS, journaling, quarantine, lineage, retry, and reset safety.
+
+Lifecycle operations fail closed when identity, ownership, or generation cannot be proven. Do not directly signal processes from UI code or edit active Run state to force outcomes.
+
+## Registry and Evolution
+
+`~/.pi/agent/recipes/*.json` is executable capability memory. Preserve filename identity, atomic writes, canonical per-path locks with atomic owner publication and non-blocking abandoned staging, explicit operator-gated changes, and transportability.
+
+Automatic review receives value-free structural projections, not executable content, paths, prose, canonical names, or secrets. Deterministic executors derive unchanged Recipes from trusted captures. Approved mutation must journal intent before mutation and roll forward safely after crashes.
+
+`PI_ACTORS_AUTOMATIC_REVIEW=off` disables scheduling and safe-boundary activation while remaining visible in runtime status.
+
+## Output and Observability
+
+Tool result/error text contributes exactly one leading line break. Keep model-facing responses compact and state-backed. Preserve complete byte-exact command streams in bounded spill files while returning bounded tails; never feed truncated tails into pipeline stdin.
+
+File watchers accelerate reconciliation; a bounded terminal-only interval recovers missed events. Terminal follow-ups contain only Run id, status, one base path, and relative artifact names in visible content; semantic details remain structured. Delivery remains honestly at-least-once across the send/handled-marker crash window.
+
+When a deferred Run result gates the next step, wait for its terminal follow-up. Inspect early only for operator request, meaningful attention, or diagnosis of an overdue Run.
+
+## Documentation and Release Discipline
+
+- Keep published text portable: use `~`, `<repo>`, or relative paths.
+- Update `skills/actors/SKILL.md` when durable operating mechanics change.
+- Keep `skills/swarm/SKILL.md` focused on multi-agent methodology rather than kernel internals.
+- Recipe `description` is optional because discovery supplies stable fallback tool copy; packaged Recipe QA must report zero diagnostics and zero release-blocking warnings without component boilerplate.
+- Before release run build, full tests, preservation tests, Recipe QA, Domain DAG validation, ABCd context validation, line-count gates, and release gates.
+- `.github/workflows/release.yml` owns the immutable sequence reusable validation → npm Trusted Publisher publication/verification → GitHub Release convergence; follow [docs/releasing.md](docs/releasing.md).
+- Keep npm publication tokenless: use the exact npm Trusted Publisher binding and job-scoped OIDC permission, never a long-lived npm token or token fallback.
+- Until a stable version beyond `1.x`, prefer clean breaking simplification over compatibility aliases or renamed legacy abstractions.

package/BACKLOG.md

@@ -1,3 +1,191 @@
 # Project Backlog
 
-No open items.
+## 0.43.1 — Contract Closure
+
+**Base:** `0.43.0` at `0d6db30cd2e070c1d03ed1e60bef70538a3083c1`
+**Release type:** patch-level assurance and distribution closure
+**Release sentence:** the Run kernel is published, portable, redacted, and mechanically self-consistent.
+
+## Mission
+
+Close the concrete gaps exposed after the `0.43.0` Run-kernel migration without adding another orchestration layer or expanding the public model.
+
+The canonical model remains unchanged:
+
+```text
+Recipe --spawn--> Run
+Run = Recipe + Trace + Control
+```
+
+The public lifecycle remains:
+
+```text
+spawn   create a Run
+message apply Control
+inspect read Recipe, Trace, or Control
+```
+
+`register_tool` remains the separate capability-memory surface.
+
+`0.43.1` succeeds when the same contract is true in source mode, installed-package mode, documentation, diagnostics, first-party controlled services, CI, GitHub Release, and npm distribution.
+
+## Hard Boundaries
+
+The release must preserve:
+
+- exactly the existing public Run nouns: `Recipe`, `Run`, `Trace`, and `Control`;
+- exactly the existing Run views: `recipe`, `trace`, and `control`;
+- exactly the existing management targets: `runtime`, `recipes`, and `tool:<name>`;
+- the stable public tool names `spawn`, `message`, `inspect`, and `register_tool`;
+- owner filtering, immutable `run_instance_id` fencing, canonical lifecycle locking, and process-identity verification;
+- shutdown and parent-teardown behavior;
+- terminal reconciliation and bounded follow-up context;
+- complete command captures, owned Pi-session evidence, redaction, path containment, and symlink rejection;
+- automatic Recipe review, immutable capture, CAS, journaled mutation, lineage, retry, reset, and recovery safety;
+- shell-free command-template execution;
+- the strict Domain DAG and removed-communication-surface gates.
+
+The release must not add:
+
+- actor chat, rooms, branches, peers, routing, mailboxes, inboxes, outboxes, or addressed envelopes under any name;
+- a task tree, planner hierarchy, decision registry, swarm scheduler, model router, or model-economics subsystem to the kernel;
+- new public targets, views, request fields, Trace fields, Control states, or Recipe keys;
+- a remote protocol, broker, workflow DSL, or general event bus;
+- compatibility aliases for removed `0.42` surfaces;
+- a long-lived npm token or third-party publish action;
+- new runtime dependencies unless an existing retained invariant cannot be closed otherwise.
+
+## Deferred Beyond This Release
+
+Do not absorb these future lines into `0.43.1`:
+
+- total Trace retention, rotation, or semantic compaction;
+- pending-Control admission backpressure and queue quotas;
+- outcome/cost aggregation for Recipe fitness;
+- automatic model selection or planner/worker economics;
+- task-tree or decision-ownership orchestration;
+- a generalized acknowledgement protocol for arbitrary controlled services.
+
+Those require separate evidence and belong to later releases.
+
+## Known Closure Gaps
+
+The executor must verify this observation against the current checkout before changing code:
+
+1. The repository-side Trusted Publisher path is prepared, but npm account binding and tagged publication proof remain external release preconditions.
+
+If the observation no longer holds, preserve the already-closed behavior and remove only the corresponding obsolete task. Do not reimplement solved work.
+
+---
+
+## P0 — Release and Contract Closure
+
+### CCL-02 — Activate npm Trusted Publisher and prove registry convergence
+
+**Goal:** make `pi install npm:@llblab/pi-actors` install the released Run kernel through the prepared tokenless, provenance-bearing path.
+
+**Status:** repository preparation is complete; npm account configuration and one tagged release proof remain externally gated.
+
+**External operator precondition:**
+
+- Configure the npm Trusted Publisher for package `@llblab/pi-actors` with owner `llblab`, repository `pi-actors`, workflow filename `release.yml`, and no environment unless both sides adopt the same reviewed environment name.
+- Do not add `NPM_TOKEN`, `NODE_AUTH_TOKEN`, or another long-lived token fallback.
+- Remove any obsolete account-level automation tokens only after one Trusted Publisher release succeeds.
+
+**Release-time closure:**
+
+- The tagged workflow passes reusable validation, publishes or safely recognizes the exact npm version, verifies matching `gitHead` and packed Pi runtime manifests, then converges the GitHub Release.
+- `npm view @llblab/pi-actors@0.43.1 version` and npm `latest` resolve to `0.43.1`.
+- The GitHub Release and npm package identify the same tag commit.
+- The Pi package index may update asynchronously; observe it without unbounded polling or repository mutation.
+- If Trusted Publisher remains unconfigured or mismatched, report that exact external blocker and keep publication failed closed.
+
+**Dependencies:** npm account configuration and the final tagged release.
+
+---
+
+## P1 — Signal, Compression, and Integration Closure
+
+### CCL-12 — Close release evidence and publish `0.43.1`
+
+**Goal:** leave one internally consistent source tree, package, release, and empty future-work file.
+
+**Work:**
+
+- Reconcile implementation comments, README, `AGENTS.md`, `docs/`, Actors skill, fixtures, schemas, tests, and release notes.
+- Keep Swarm skill changes limited to kernel-interface corrections; do not expand orchestration methodology in this release.
+- Update package version and packaged skill metadata to `0.43.1` only after all implementation tasks close.
+- Move completed work into one concise `CHANGELOG.md` section with externally meaningful behavior and impact.
+- Reset `BACKLOG.md` to:
+
+  ```text
+  # Project Backlog
+
+  No open items.
+  ```
+
+- Run the final local boundary:
+
+  ```bash
+  npm ci
+  npm run test:preservation
+  npm run release:validate
+  npm run audit:dependencies
+  ```
+
+- Create tag `v0.43.1` only from the validated release commit.
+- Observe the gated workflow through successful validation, npm publication, npm verification, and GitHub Release publication.
+- Verify the final public package through npm, not only `npm pack --dry-run`.
+
+**Release closure:**
+
+- Ubuntu, macOS, Windows, and dependency-audit jobs succeed.
+- GitHub Release is published only after validation and npm verification.
+- npm exact version and `latest` both resolve to `0.43.1`.
+- The installed package reports `0.43.1`, exposes the same schemas as source, and contains no removed communication surface.
+- Recipe QA has zero diagnostics and zero baseline warnings.
+- Shipped lines remain below `28,853`.
+- No unresolved P0/P1 finding remains.
+- `BACKLOG.md` contains no completed work.
+
+**Dependencies:** all prior tasks and the npm Trusted Publisher external precondition.
+
+---
+
+## Dependency Order
+
+```text
+Released 0.43.0 baseline
+  └── CCL-02 → CCL-12
+```
+
+`CCL-02` may proceed in parallel with kernel fixes after the frozen released baseline, but no tag may be created until the complete graph closes.
+
+## Required Test Matrix
+
+At minimum, retain or add direct evidence for:
+
+| Boundary               | Required evidence                                                                         |
+| ---------------------- | ----------------------------------------------------------------------------------------- |
+| Public Control request | exact fields, action length, serialized-input bound, removed-field rejection              |
+| Recipe Control         | same action grammar/length, duplicate and runtime-reserved rejection                      |
+| Control journal        | generation fencing, monotonic transitions, compaction, stale-lock recovery                |
+| Control projection     | recursive redaction in tool content/details, triage, and Actor Inspector                  |
+| Control transport      | exact complete-wire bound, FIFO atomicity, named-pipe parity, partial-write failure       |
+| Runtime status         | exact version in source and packed/dist modes                                             |
+| Runtime triage         | pending/stale distinction, delivered inclusion, age boundaries, owner/lifecycle filtering |
+| Trace append           | canonical validation, cross-process serialization, no malformed/lost/duplicate records    |
+| First-party services   | canonical Trace only, canonical Control claim/finalization, endpoint generation           |
+| Documentation          | canonical examples accepted by current schemas/dispatchers                                |
+| Recipe QA              | zero diagnostics and zero normalized warnings                                             |
+| Release                | validation-before-publication, OIDC-only npm publishing, rerun convergence                |
+| Compression            | strict shipped-line ratchet from `0.43.0`                                                 |
+| Installed package      | compiled entrypoint, skills, version, schemas, no stale files/source imports              |
+
+## Final Decision Rule
+
+Do not release because the code compiles or because the new abstractions look cleaner.
+
+Release only when this statement is supported end to end:
+
+> A user installing `@llblab/pi-actors@0.43.1` receives the same validated Run kernel described by the repository: every Run exposes one captured Recipe, one redacted causal Trace, and one portable generation-fenced Control boundary—without a communication plane and without distribution ambiguity.