@llblab/pi-actors 0.22.5 → 0.24.0

package/BACKLOG.md

@@ -43,452 +43,137 @@ No open hotfix items.
 
 ## Minor Backlog
 
-### M-01 Internal Protocol Contract Pack
+The backlog is intentionally pruned to the 20% of work most likely to deliver 80% of value for `pi-actors` as a local actor kernel. Bias toward consolidation, smaller public surface area, and reliability over new feature breadth.
 
-- Priority: Medium.
-- Goal: Add machine-readable internal schemas and fixtures for implementation, docs, tests, and inspector consistency.
-- Files:
-  - `schemas/actor-message.schema.json`.
-  - `schemas/actor-address.schema.json`.
-  - `schemas/run-state.schema.json`.
-  - `schemas/run-inbox-message.schema.json`.
-  - `schemas/run-outbox-event.schema.json`.
-  - `schemas/room-message.schema.json`.
-  - `schemas/room-roster.schema.json`.
-  - `schemas/communication-snapshot.schema.json`.
-  - `schemas/recipe.schema.json`.
-  - `fixtures/protocol/run-minimal.json`.
-  - `fixtures/protocol/message-branch.json`.
-  - `fixtures/protocol/message-room-join.json`.
-  - `fixtures/protocol/mailbox-contract.json`.
-- Acceptance:
-  - Normalization outputs validate.
-  - Docs examples validate.
-  - Fixtures are usable by tests.
-  - Schemas are versioned with package version.
-
-### M-02 Unified Actor Event Base
-
-- Priority: Medium.
-- Goal: Add a shared base envelope for actor event-like records without forcing one storage file.
-- Target channels:
-  - `events`.
-  - `inbox`.
-  - `outbox`.
-  - `wake`.
-  - `room`.
-  - `branch`.
-- Acceptance:
-  - New append helpers generate ids consistently.
-  - Existing files remain readable.
-  - `inspect` can show id, correlation, and causation.
-  - No migration is forced.
+### M-01 State Corruption Recovery
 
-### M-03 Mailbox Contract v1
-
-- Priority: Medium.
-- Goal: Extend `mailbox.accepts` and `mailbox.emits` from string arrays to backward-compatible typed contracts.
+- Priority: High.
+- Status: Done.
+- Goal: Keep `inspect` useful when file-backed run, room, branch, or recipe state is partially corrupted.
+- Why now: The extension's core promise is local, inspectable, durable actor state. Corrupt JSON/JSONL should degrade visibility, not break the operator membrane.
 - Direction:
-  - Keep string declarations valid.
-  - Normalize typed entries for inspection.
-  - Support fields such as body schema, ack requirement, idempotency, response requirement, level, and summary.
+  - Continue migrating repeated JSON/JSONL inspect paths to `lib/state-readers.ts`.
+  - Preserve valid records and report corrupt paths/counts.
+  - Do not silently rewrite canonical state without an explicit repair action.
 - Acceptance:
-  - String declarations still work.
-  - `inspect view=mailbox` shows normalized contracts.
-  - Messages outside accepts produce advisory warnings by default, not hard blocks.
-  - Docs clarify advisory versus strict mode.
+  - Malformed JSONL lines do not kill inspect paths.
+  - Corrupt JSON files surface diagnostics with paths.
+  - Tests cover run, branch, room, and recipe-adjacent state where practical.
 
-### M-04 Actor Loop Helper SDK
+### M-02 Actor Loop Helper Minimal Core
 
-- Priority: Medium.
-- Goal: Provide reusable helpers for mailbox-consuming actors so recipe authors do not rewrite loops.
+- Priority: High.
+- Status: Done.
+- Goal: Provide one small reusable mailbox loop so recipe authors do not duplicate claim/handle/status logic.
+- Why now: Long-lived actors and worker recipes are the natural center of `pi-actors`; a minimal helper consolidates behavior without adding a broker or scheduler DSL.
 - Files:
-  - `lib/actor-loop.ts`.
-  - `scripts/actor-loop.mjs`.
-- Capabilities:
-  - Initial reconciliation.
-  - Wake subscription.
-  - Polling fallback.
-  - Run and branch inbox claiming.
-  - Handled and failed status transitions.
-  - Outbox emission.
-  - Progress updates.
-  - Graceful stop handling.
-- Acceptance:
-  - A packaged demo recipe uses a mailbox-only control endpoint.
-  - Concurrent wake and poll paths do not double-process messages.
-  - Helper supports run inbox and branch inbox.
-
-### M-05 Branch Delivery Unification
-
-- Priority: Medium.
-- Goal: Route direct branch messages and room multicast branch copies through one internal helper.
-- Target helper:
-  - `routeBranchEnvelope(stateDir, runId, message, { source })`.
-- Acceptance:
-  - Direct branch messages and room multicast produce the same durable branch inbox shape.
-  - Parent run dispatch envelope is consistent.
-  - Tests cover both paths.
-
-### M-06 Attention Semantics v1
-
-- Priority: Medium.
-- Goal: Formalize coordinator attention behavior through semantic metadata rather than transport knobs.
-- Direction:
-  - Support attention metadata such as `requires_response=true` and reason.
-  - Map response-required messages to follow-up.
-  - Keep progress/info messages inspectable or notify-only.
-  - Preserve existing internal `delivery` behavior.
-- Acceptance:
-  - `requires_response=true` becomes coordinator follow-up.
-  - Progress info stays log or notification.
-  - Explicit stop and kill controls do not create duplicate terminal follow-up.
-
-### M-07 Recipe Doctor
-
-- Priority: Medium.
-- Goal: Add intentional recipe health inspection.
-- Surface:
-  - `inspect target=recipes view=doctor`.
-  - `inspect target=recipes view=doctor verbose=true`.
-- Checks:
-  - Import graph health.
-  - Shadowing and blockers.
-  - Invalid or disabled recipes.
-  - Risky command templates.
-  - Absolute path portability.
-  - OS compatibility.
-  - Root permissions.
-  - Mailbox completeness.
-  - Artifact placeholder resolution.
-  - Stale or unused usage.
-- Acceptance:
-  - Compact output is grouped by severity.
-  - Verbose output is structured.
-  - No automatic cleanup happens.
-  - Every diagnostic has reason and suggested actions.
-
-### M-08 Artifact Manifest v1
-
-- Priority: Medium.
-- Goal: Extend recipe artifacts from string paths to backward-compatible artifact metadata.
+  - `lib/mailbox-loop.ts`.
 - Direction:
-  - Keep string artifact paths valid.
-  - Add optional object fields such as path, kind, media type, and required.
-  - Resolve manifests with existence, size, and optional hash.
+  - Support run inbox claiming, branch inbox claiming, handled/failed status transitions, bounded drains, duplicate-claim protection, and graceful stop-message detection.
+  - Defer live wake subscription and polling wrappers until the canonical worker recipe needs them.
+  - Keep policy out: no task selection, no model choice, no project prompts.
 - Acceptance:
-  - String artifacts remain valid.
-  - Runtime resolves manifest with `exists`, `size`, and optional `sha256`.
-  - Terminal follow-ups group named artifacts.
-  - Missing required artifacts are visible in result and inspect output.
-
-### M-09 Lifecycle Retention Policy
-
-- Priority: Medium.
-- Goal: Add explicit archive and prune behavior for terminal run state.
-- Messages:
-  - `control.archive`.
-  - `control.prune`.
-- Direction:
-  - Only terminal runs can be archived or pruned.
-  - Active runs fail closed.
-  - Archive moves or compresses state with a tombstone.
-  - Prune deletes terminal state after ownership checks, optionally preserving artifacts.
-- Acceptance:
-  - Terminal cleanup candidates are inspectable.
-  - Artifacts can be preserved.
-  - Active run deletion is impossible.
-
-### M-10 Inspector v2 For Unread Mentions And Needs Response
-
-- Priority: Medium.
-- Goal: Strengthen the TUI inspector as the operator membrane for multi-actor sessions.
-- Direction:
-  - Add stable event ids in previews.
-  - Add unread cursor per session, run, and room.
-  - Preserve mention filtering.
-  - Add needs-response marker from attention semantics.
-  - Distinguish room timeline rows from branch inbox rows.
-- Acceptance:
-  - `/actors-inspector-filter unread` works.
-  - `/actors-inspector-filter mention <text>` works.
-  - `/actors-inspect <number>` marks the item read for the current session.
-  - Unread state stays UI/session metadata, not protocol truth.
-
-### M-11 Run State Index
-
-- Priority: Medium.
-- Goal: Add a rebuildable run-state index to reduce recursive scans and improve observability performance.
-- Target file:
-  - `~/.pi/agent/tmp/pi-actors/runs/index.json`.
-- Contents:
-  - State dir.
-  - Run id.
-  - Owner id.
-  - Status.
-  - Updated time.
-  - Recipe or tool.
-- Acceptance:
-  - Index accelerates list and summarize.
-  - Corruption falls back to scan.
-  - Rebuild helper exists.
-  - Nested runs are represented without id collision.
-
-### M-12 Internal Conformance Runner
-
-- Priority: Medium.
-- Goal: Add a CI-ready internal conformance runner for pi-actors protocol behavior.
-- Script:
-  - `npm run conformance`.
-- Suites:
-  - Recipe discovery.
-  - Register, update, and delete.
-  - Spawn lifecycle.
-  - Message routing.
-  - Room roster.
-  - Branch inbox.
-  - Ownership checks.
-  - Artifacts.
-  - Attention semantics.
-- Acceptance:
-  - Runs without Pi UI where possible.
-  - Outputs compact report.
-  - Fixtures live in the repository.
-  - CI can run it.
+  - Helper supports run inbox and branch inbox.
+  - Claim/handle/fail transitions are covered by tests.
+  - Duplicate branch claims do not double-process one message.
+  - Bounded drains stop on standard control messages.
 
-### M-13 Packaged Actor Worker Recipe Template
+### M-03 Canonical Worker Recipe Template
 
-- Priority: Medium.
-- Goal: Add a canonical packaged recipe or template for a long-lived worker-backed branch actor.
+- Priority: High.
+- Status: Done.
+- Depends on: M-02.
+- Goal: Add one canonical packaged worker recipe/template demonstrating the intended long-lived actor pattern.
+- Why now: The extension should teach one excellent mailbox loop rather than accumulate scenario-specific scripts.
 - Direction:
-  - Worker joins room.
-  - Worker declares mailbox accepts and emits.
-  - Worker claims branch inbox messages.
+  - Worker joins the default room.
+  - Worker declares typed mailbox accepts/emits.
+  - Worker claims branch inbox work.
   - Worker posts `task.claim`, `task.result`, and `awaiting_assignment`.
   - Worker handles `control.stop`.
 - Acceptance:
-  - Recipe demonstrates correct mailbox loop semantics.
-  - It is a recipe-authoring example, not a product feature.
-
-### M-14 Recipe Usage Integrity Improvements
-
-- Priority: Medium.
-- Goal: Make recipe usage tracking more explainable.
-- Direction:
-  - Add fingerprint diff reason.
-  - Add reset reason.
-  - Consider optional last error.
-  - Split launch counts by tool, spawn, and direct recipe.
-- Acceptance:
-  - `inspect recipes view=summary verbose=true` shows whether usage refers to current recipe content.
-  - Doctor can flag unused current meaning instead of stale old recipe history.
+  - Demonstrates correct mailbox loop semantics.
+  - Stays a recipe-authoring reference, not a product workflow catalog.
+  - Actor skill links it as the canonical worker pattern.
 
-### M-15 Safer Command Warning Policy
+### M-04 Protocol Contract Fixtures
 
 - Priority: Medium.
-- Goal: Unify command-template diagnostics by severity and make warnings actionable without startup spam.
-- Severity:
-  - `info`: portability.
-  - `warning`: broad mutation, shell, or eval.
-  - `error`: impossible, invalid, or unsafe repeat.
+- Status: Done.
+- Goal: Freeze the current protocol behavior with compact internal fixtures before further surface growth.
+- Why now: `spawn`, `message`, `inspect`, mailbox contracts, artifacts, rooms, and run indexes now have enough shape to merit regression fixtures; schemas should document reality, not invent a new standard.
 - Direction:
-  - Treat legitimate `bash` wrappers as expected trusted boundaries when already packaged or explicitly registered.
-  - Keep routine shell wrapper notes out of startup warning blocks.
-  - Surface shell/eval/destructive diagnostics through register-time warnings, doctor, and verbose recipe inspection.
+  - Add fixtures for representative run state, actor message, run inbox/outbox, room message/roster, mailbox contract, artifact manifest, and recipe summary.
+  - Add lightweight schema or shape validation only where it protects existing behavior.
 - Acceptance:
-  - Command-template warnings include command label, reason, and suggested mitigation.
-  - `register_tool` shows relevant warnings.
-  - Recipe doctor aggregates warning policy.
-  - Startup no longer emits large warning blocks only because recipes wrap `bash`.
+  - Public examples and fixtures validate in tests.
+  - No migration is forced.
+  - No external transport/MCP standard is introduced.
 
-### M-16 Output And Log Size Governance
+### M-05 Follow-Up Deduplication Hardening
 
 - Priority: Medium.
-- Goal: Keep stdout, stderr, result, outbox, and actor-message previews bounded in agent context.
+- Status: Done.
+- Goal: Suppress duplicate terminal transitions and outbox follow-ups across watcher reloads, session restarts, or line-counter resets.
+- Why now: Operator-facing observability should be calm and trustworthy as actor count grows.
 - Direction:
-  - Centralize constants for body preview, outbox preview, inspector preview, and tail lines.
-  - Keep verbose output opt-in.
-  - Prefer files or artifacts for large bodies.
+  - Continue using event id and stateDir for deduplication where available.
+  - Preserve terminal handled semantics.
+  - Simulate watcher restart in tests.
 - Acceptance:
-  - Actor messages and previews share consistent caps.
-  - Verbose mode is explicit.
-  - Large bodies do not flood normal tool output.
+  - Duplicate follow-up is suppressed after reasonable watcher reset.
+  - Terminal handled state remains effective.
+  - Tests cover restart and line-counter reset scenarios.
 
-### M-17 Windows And Nix Portability Pass
+### M-06 Portability Reality Pass
 
 - Priority: Medium.
-- Goal: Strengthen current portability around FIFO, named-pipe, and mailbox-only paths without adding a new backend.
+- Status: Done.
+- Goal: Make current Linux/macOS/WSL/native-Windows behavior explicit without adding a new backend.
+- Why now: Mailbox-only paths and named-pipe support exist; operators need accurate diagnostics, not hidden platform assumptions.
 - Direction:
   - Doctor flags FIFO-only recipes on native Windows.
-  - Keep mailbox-only demo cross-platform.
-  - Document platform matrix.
+  - Keep mailbox-only worker demo cross-platform.
+  - Document a small platform matrix.
   - Cover named-pipe adapter with injected sender where practical.
 - Acceptance:
   - Native Windows limitations are visible before launch.
   - Mailbox-only recipe works cross-platform.
   - Docs and tests cover the adapter split.
 
-### M-18 State Corruption Recovery
-
-- Priority: Medium.
-- Goal: Add resilient JSON and JSONL state readers.
-- Direction:
-  - Malformed JSONL lines should not kill entire inspect paths.
-  - Corrupt JSON files should report diagnostics with paths.
-  - Consider optional `.corrupt` quarantine helper.
-- Acceptance:
-  - Inspect remains useful when partial state survives.
-  - Corrupt paths are reported clearly.
-  - Canonical state is not silently rewritten without explicit action.
-
-### M-19 Recipe Import Graph Inspector
-
-- Priority: Medium.
-- Goal: Add focused inspection for recipe import graphs.
-- Surface:
-  - `inspect target=recipes view=imports`.
-  - `inspect target=recipes view=imports verbose=true`.
-- Acceptance:
-  - Shows import graph, aliases, resolved paths, and shadowed imports.
-  - Shows cyclic and depth diagnostics.
-  - Helps debug packaged and user recipe composition.
-
-### M-20 Spawn Preflight Mode
-
-- Priority: Medium.
-- Goal: Add dry-run launch planning for `spawn` and async recipe tool invocation.
-- Direction:
-  - Resolve recipe, imports, args, artifacts, state dir, command graph, and mailbox metadata.
-  - Do not start a process.
-  - Return warnings and resolved launch plan.
-- Acceptance:
-  - `preflight=true` returns a resolved plan.
-  - No process is spawned.
-  - Missing args and risky commands are reported before launch.
-
-### M-21 Run Restart And Reattach Policy
-
-- Priority: Medium.
-- Goal: Clarify and implement safe behavior for reused `run_id` and `state_dir`.
-- Direction:
-  - Active reuse fails closed.
-  - Terminal restart with same id is allowed under explicit semantics.
-  - Record generation or restarted time.
-  - Preserve previous terminal-state policy.
-- Acceptance:
-  - Active reuse remains blocked.
-  - Terminal restart records generation or `restartedAt`.
-  - Inspect shows restart semantics.
-  - Docs are updated.
-
-### M-22 Actor Address Helper CLI And Tooling
-
-- Priority: Medium.
-- Goal: Improve address normalization and diagnostics for recipe authors and tests.
-- Direction:
-  - Add helper functions or inspect view for address validation.
-  - Improve invalid-address diagnostics.
-- Acceptance:
-  - Diagnostics include expected forms.
-  - Examples cover branch, room, run, session, and tool addresses.
-  - No new public address kinds are added.
-
-### M-23 Room Compaction Metadata Improvements
+### M-07 Compiled Script Entrypoints
 
 - Priority: Medium.
-- Goal: Record richer room compaction metadata.
+- Status: Done.
+- Goal: Bring packaged script entrypoints under the build so installed npm recipes run against compiled runtime code.
+- Why now: Recipes increasingly depend on helper scripts that import extension internals; compiling script logic closes the gap between source-tree development and installed package behavior.
 - Direction:
-  - Track dropped count.
-  - Track first and last kept timestamps.
-  - Track configured max.
+  - Keep stable executable recipe paths through thin `scripts/*.mjs` shims.
+  - Keep substantive reusable script logic in compiled `lib/*.ts` modules so scripts stay lightweight runners and `dist/lib` is the JS-only runtime surface; allow self-contained application scripts to remain standalone `.mjs` when no reuse is expected.
+  - Keep `npm run build` checking packaged script entrypoint syntax while compiled module migration proceeds.
+  - Make installed scripts prefer `dist` runtime modules and avoid importing `.ts` from `node_modules`.
+  - Preserve source-tree developer ergonomics without requiring global install.
+  - Expose compiled JS as the default Node-compatible extension entrypoint and source TS/skill paths as optional metadata for TypeScript-native runtimes.
+  - Treat `dist/` as the JS-only distributive tree: mirror runtime assets (`scripts/`, `recipes/`, `fixtures/`, and `skills/`) there during build and point default package metadata at those dist assets.
+  - Track each converted script with a compiled module existence regression so shim drift is caught before packaging.
 - Acceptance:
-  - `inspect room:<run> view=status verbose=true` shows compaction info.
-  - Compaction never corrupts JSONL.
-  - Tests cover low `PI_ACTORS_ROOM_MAX_MESSAGES`.
+  - `npm run build` covers packaged script logic, not only extension library code.
+  - Installed-script tests prove packaged recipes do not import TypeScript from `node_modules`.
+  - `npm run pack:dry` includes expected compiled/script files.
+  - Recipe paths remain stable or migrations are explicitly documented.
 
-### M-24 Coordinator Follow-Up Deduplication
+## Explicitly Deferred
 
-- Priority: Medium.
-- Goal: Suppress duplicate terminal transitions and outbox follow-ups across watcher reloads, session restarts, or line-counter resets.
-- Direction:
-  - Use event id and stateDir for deduplication where available.
-  - Preserve terminal handled semantics.
-  - Simulate watcher restart in tests.
-- Acceptance:
-  - Duplicate follow-up is suppressed after reasonable watcher reset.
-  - Terminal handled state remains effective.
-  - Tests cover restart and line-counter reset scenarios.
+These are valid ideas but not current focus. Reintroduce only with concrete evidence from real actor workflows.
 
-### M-25 Documentation Refactor Runtime Contracts First
-
-- Priority: Medium.
-- Goal: Reorganize docs so implementation agents find stable contracts before examples.
-- Target order:
-  - `docs/runtime-contracts.md`.
-  - `docs/actor-messages.md`.
-  - `docs/async-runs.md`.
-  - `docs/tool-registry.md`.
-  - `docs/template-recipes.md`.
-  - `docs/command-templates.md`.
-  - `docs/recipe-authoring.md`.
-  - `docs/troubleshooting.md`.
-- Acceptance:
-  - No polling-first examples.
-  - Every example matches fixtures.
-  - Docs distinguish protocol semantics from Pi UI commands.
-  - No external standard or MCP work is introduced.
+- Spawn preflight mode: useful later, but lower value than resilient inspect and mailbox-loop consolidation.
+- Run restart/reattach policy: risky for isolation; defer until corruption recovery and protocol fixtures are stronger.
+- Actor address helper CLI: keep diagnostics improving opportunistically inside existing parser/tests.
+- Documentation refactor: defer until the canonical mailbox loop and worker recipe exist; avoid rewriting docs twice.
+- Host-level tool unregistration: blocked on host API support.
+- Branch-local checkpoint semantics: wait for real collaborative branch-runner experiments.
+- Actor recipe feedback loop: keep advisory and operator-gated after real runs produce evidence.
 
 ## Suggested Milestone Order
 
-```text
-Patch release:
-  H-01..H-12
-
-Minor 0.23 — Contract consolidation:
-  M-01, M-02, M-03, M-12, M-25
-
-Minor 0.24 — Runtime/message reliability:
-  M-04, M-05, M-06, M-13, M-24
-
-Minor 0.25 — Operator hygiene:
-  M-07, M-08, M-09, M-14, M-15, M-16
-
-Minor 0.26 — Inspector and state scaling:
-  M-10, M-11, M-18, M-19, M-23
-
-Minor 0.27 — Portability and lifecycle polish:
-  M-17, M-20, M-21, M-22
-```
-
-## Blocked Or Opportunistic Carry-Over
-
-### Branch-Local Checkpoint Semantics
-
-- Priority: Low.
-- Blocked by: At least one real collaborative branch-runner async-run experiment.
-- Goal: Validate whether `failure: "branch"`, node-level `retry`, and `recover` cleanup are enough for branch-local validation and bounded reattempts.
-- Exit:
-  - Record one decision: sufficient, documentation-only refinement needed, or propose one minimal command-template extension with tests.
-
-### Host-Level Tool Unregistration
-
-- Priority: Low.
-- Blocked by: Host API support for custom tool unregistration.
-- Goal: Remove stale dynamically registered tool definitions completely when the host API supports it.
-- Direction:
-  - Track pi extension API support for custom tool unregistration.
-  - Replace active-tool deactivation fallback with real unregister when available.
-  - Preserve current safe behavior: deleted tools should not remain active after reload.
-- Exit:
-  - Deleting a recipe file removes the corresponding runtime tool definition and active-tool entry without session restart.
-
-### Actor Recipe Feedback Loop
-
-- Priority: Low.
-- Goal: Turn actor recipe-context awareness into a practical improvement loop for packaged recipes and operator-owned recipe memory.
-- Direction:
-  - After real multi-agent runs, capture whether child actors report that recipe/import/mailbox/role boundaries fit the task.
-  - Keep the loop advisory and operator-gated.
-  - Prefer small recipe, README, and skill refinements over scenario catalogs.
-- Exit:
-  - At least one real run produces recipe-boundary feedback that is applied or explicitly rejected with rationale.
+All milestone tasks in this backlog are currently complete. Reopen this section only with concrete follow-up work from real actor workflows, release preflight, or operator diagnostics.

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## Unreleased
 
+## 0.24.0: Reliability, Mailbox Workers, and Dist-First Packaging
+
+- `[Prompts]` Clarified that recipe registry warnings are actionable maintenance: invalid or blocking recipes should be fixed, removed, or disabled rather than ignored.
+- `[Backlog]` Pruned and refocused the backlog around reliability, mailbox-loop consolidation, protocol fixtures, follow-up deduplication, and portability reality checks.
+- `[State]` Added resilient JSON/JSONL state reader helpers and routed room, inspector, runtime wake, run inbox, and observability outbox reads through them so malformed state records degrade instead of breaking previews; room status now reports state diagnostic counts and reader degradation behavior has direct regression coverage.
+- `[Observability]` Deduplicated run outbox events by stable event id so line-counter resets do not replay already-seen follow-ups; stale dedupe state is pruned with terminal and missing runs.
+- `[Mailbox Loop]` Added initial run/branch mailbox claim-and-handle helpers plus branch inbox claiming support, failed-handler transitions, standard stop-message detection, bounded message drains, duplicate-claim coverage, and a packaged `actor-worker` demo recipe for canonical mailbox loops.
+- `[Scripts]` Added installed-package coverage proving the packaged `actor-worker` script uses compiled `dist` runtime modules instead of importing TypeScript from `node_modules`; `npm run build` now cleans stale `dist` output, mirrors packaged `scripts/`, `recipes/`, and `fixtures/` into `dist/`, and syntax-checks the built script entrypoints. The `actor-worker`, `async-runner`, `validate-recipe`, and `conformance` executables are now thin shims over compiled TypeScript entrypoint logic in `lib/actor-worker.ts`, `lib/async-runner.ts`, `lib/validate-recipe.ts`, and `lib/conformance.ts`, with build-output regressions for the compiled shim modules.
+- `[Packaging]` Exposed optional `pi.sourceExtensions` metadata pointing at the root TypeScript entrypoint while keeping Node-compatible `pi.extensions` on compiled `dist` output.
+- `[Context]` Clarified the project frame as an experimental self-evolution membrane for local agent capabilities, grounded in explicit actors, recipes, fixtures, skills, and inspectable state.
+- `[Protocol]` Clarified dotted `channel.action` message types as the minimal action surface: scripts can often dispatch from `type` alone while agents may use `body` for free-form prompts.
+- `[Recipes]` Fixed `pipeline-quorum-review` registry loading by inlining the quorum fanout over its `models` array instead of importing a nested repeated recipe with unresolved runtime values.
+- `[Recipes]` Made Markdown recipe frontmatter more forgiving: `args` can be a comma-separated scalar and `defaults` can be a list of `key: value` entries, both normalizing to the canonical JSON recipe shape.
+- `[Packaging]` Build output now mirrors packaged `skills/` into `dist/` alongside scripts, recipes, and fixtures so the JS-only distributive tree carries the project skills; package skill metadata now points at `dist/skills` with `pi.sourceSkills` preserving root TypeScript/source-tree paths, and README now documents the dist-first/source-optional package shape. The dist build pipeline now lives in `scripts/build-dist.mjs` instead of an inline package script, completing the compiled script entrypoint backlog slice.
+- `[Docs]` Added a platform support matrix for mailbox-only, FIFO, named-pipe, and process-control behavior across Linux/macOS/WSL and native Windows, with regressions proving native Windows FIFO limits remain visible and the canonical worker recipe stays mailbox-only.
+- `[Backlog]` Marked the reliability, mailbox loop, protocol fixture, portability, and compiled-entrypoint milestone set complete; future backlog additions should come from concrete actor workflow evidence.
+- `[Scripts]` Migrated `recipe-utils`, `build-dist`, `locker`, `coordinator`, and `validate-recipe` command logic behind compiled TypeScript domain modules while preserving the stable `scripts/*.mjs` shim paths; project guidance frames this as deliberate standard-library growth with clear domain boundaries while keeping self-contained application scripts such as `music-player.mjs` standalone.
+- `[Protocol]` Added compact protocol fixtures for actor messages, mailbox contracts, run inbox/outbox records, room messages/rosters, run state, recipe summaries, and artifact manifests with regression coverage.
+- `[Skills]` Documented the passive-active skill evolution discipline: `actors` tracks extension mechanics while `swarm` tracks orchestration standards and lessons.
+
+## 0.23.0: Actor Manifests, Inspection, and Runtime Hygiene
+
+- `[Tools]` Unified branch-envelope routing for direct branch messages and selected-recipient room multicast so both paths persist the same branch-local inbox shape before dispatching through the parent run mailbox.
+- `[Async Runs]` Added attention semantics for coordinator-bound actor messages: `metadata.requires_response=true` now produces a follow-up while ordinary coordinator progress messages default to notification-level delivery.
+- `[Registry]` Added `inspect target=recipes view=doctor` as an intentional recipe health surface with compact severity/action counts and structured verbose diagnostics.
+- `[Async Runs]` Added artifact manifest resolution for string and object artifact declarations, including `exists`, `size`, `sha256`, and missing required artifact visibility in artifact inspection.
+- `[Async Runs]` Added explicit terminal run retention controls via `control.archive` and `control.prune`, with active-run fail-closed behavior and optional artifact preservation during prune.
+- `[Inspector]` Added stable event ids, needs-response markers, and session-local read markers to actor inspector previews and selected-item details.
+- `[Registry]` Suppressed routine trusted `bash` wrapper diagnostics from startup warning notifications while keeping them available through recipe diagnostics surfaces.
+- `[Async Runs]` Added a rebuildable run-state index for run listing and observability discovery, with corrupt-index fallback to recursive scan and nested-run-safe state directory entries.
+- `[Testing]` Added `npm run conformance` for a compact CI-ready protocol conformance runner covering recipes, registry, spawn lifecycle, messaging, rooms, branch inboxes, ownership, artifacts, and attention semantics.
+- `[Mailbox]` Added backward-compatible typed mailbox contracts with normalized inspection and advisory warnings for undeclared run message types.
+- `[Output]` Centralized inspect, preview, and tool-output size limits so bounded output governance is shared across tools, room previews, and the actor inspector.
+- `[Registry]` Added explicit mitigation guidance to command-template trust-boundary warnings for shells, eval modes, and broad filesystem mutation.
+- `[Scripts]` Added top-of-file descriptions to packaged helper scripts so their purpose, boundaries, and policy ownership are clear when opened directly.
+- `[Rooms]` Added room compaction metadata with dropped count, configured maximum, and first/last kept timestamps exposed through room status inspection.
+- `[Recipes]` Improved usage telemetry with launch-kind counters (`tool`, `spawn`, `direct`) and explicit reset reasons when recipe content fingerprints change.
+- `[Inspect]` Added `inspect target=recipes view=imports` to summarize recipe import aliases and source references for debugging recipe composition.
+
 ## 0.22.5: CI Stability Hotfix
 
 - `[Tests]` Stabilized the Windows named-pipe control endpoint regression by keeping its synthetic run alive longer under slower full-suite CI scheduling.

package/README.md

@@ -43,6 +43,8 @@ Or from git:
 pi install git:github.com/llblab/pi-actors
 ```
 
+The npm package is dist-first for JavaScript-only runtimes: default Pi metadata points at compiled `dist/` entrypoints and mirrored runtime assets. Source TypeScript and source skills remain in the package for TypeScript-native runtimes through optional source metadata.
+
 ## Address Surface
 
 Actors and coordination endpoints are addressed with compact route strings:
@@ -161,7 +163,7 @@ The terminal actor inspector is hidden by default. When opened without an explic
 /actors-inspect 3
 ```
 
-The table is compact and optimistic by default: bounded route/type/summary/body previews, capped noisy room rows, branch-local inbox previews, and an inline roster summary in the form `name/role` that wraps only when needed. Active roster members use the target color; members that sent `actor.leave` remain visible as inactive/muted participants from the current run. Use `unread` to focus queued branch inbox work and `branch <name>` / `current-branch <name>` to focus one branch's room/direct/inbox traffic. `/actors-inspect <number>` opens the selected row as a full-message view; toggle again to return to the table or close it. Actor display names come from room `actor.join` roster metadata or branch addresses, keeping debugger output plain and name-driven.
+The table is compact and optimistic by default: bounded route/type/summary/body previews, capped noisy room rows, branch-local inbox previews, stable event ids in selected-message details, and an inline roster summary in the form `name/role` that wraps only when needed. Active roster members use the target color; members that sent `actor.leave` remain visible as inactive/muted participants from the current run. Use `unread` to focus queued branch inbox work and `branch <name>` / `current-branch <name>` to focus one branch's room/direct/inbox traffic. Rows with `metadata.requires_response=true` show a `!` attention marker. `/actors-inspect <number>` opens the selected row as a full-message view and marks it read for the current session filter; toggle again to return to the table or close it. Actor display names come from room `actor.join` roster metadata or branch addresses, keeping debugger output plain and name-driven.
 
 ## Registry Model
 
@@ -255,6 +257,17 @@ Use mailbox declarations when an actor has a stable conversational surface.
 
 Core actor state, inspection, foreground tools, and basic async runs are portable Node.js behavior. Run-local messaging and stop/kill use a platform adapter under the same `message` API: Unix-compatible recipes can use their existing local control endpoint, while native Windows recipes can expose a Windows-native endpoint in run state. Some packaged scripts still depend on Unix tools and are WSL/Linux/macOS-only until migrated; their public recipe surface should stay `spawn` / `message` / `inspect` either way.
 
+| Surface | Linux/macOS/WSL | Native Windows |
+| --- | --- | --- |
+| Foreground tools, recipe discovery, inspect | Supported | Supported |
+| Async runs and file-backed state | Supported | Supported |
+| Mailbox-only actors and worker recipe | Supported | Supported |
+| FIFO control endpoints | Supported | Not supported; use mailbox or named pipe |
+| Named-pipe control endpoints | Not needed | Supported when recipe exposes one |
+| Process cancel/kill | Process group signal with pid fallback | Windows process-tree adapter |
+
+Packaged recipes should prefer mailbox/wake behavior for portable control. Recipes that require FIFO, Unix shell tools, or platform-specific media backends should make that limitation visible in docs or diagnostics before launch.
+
 ## Safety Boundary
 
 `pi-actors` is local-first, not sandbox-first.

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

@@ -0,0 +1,13 @@
+{
+  "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/artifact-manifest.json

@@ -0,0 +1,9 @@
+{
+  "report": {
+    "path": "{state_dir}/report.md",
+    "kind": "markdown",
+    "media_type": "text/markdown",
+    "required": true
+  },
+  "journal": "{state_dir}/journal.jsonl"
+}