@llblab/pi-actors 0.43.1 → 0.44.0

package/AGENTS.md

@@ -54,7 +54,7 @@ Pi host
 - `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.
+- `observability.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.
@@ -78,7 +78,7 @@ Canonical event:
 {"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.
+Trace is a bounded retained suffix, not an audit archive. Every first-party writer must call `appendRunTraceEvent`; under the canonical token-owned lock it appends within both fixed bounds or atomically retains the newest suffix plus one cumulative warning-only `runtime.trace_compacted` marker. The marker means older history was discarded; terminal/result/execution/artifact files remain authoritative independently. Reads are newline-safe and order equal timestamps by same-source ordinal, fixed source rank, then stable id without exposing ordering metadata. Never write `trace.jsonl` directly. Persist durable state or an artifact before attention; `attention: "followup"` remains rare.
 
 ### Control
 
@@ -88,15 +88,15 @@ Public shape:
 {"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.
+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 admission and every compacted atomic journal replacement through token-owned dead-process-reclaiming locks. Reject malformed, oversized, stale-generation, or 64-pending journals before admission with bounded backpressure/integrity details; bound persisted errors to 4 KiB inside the string and retain at most 128 terminal records. First-party services must exact-id claim and finalize through `runs-controls.ts`; admitted nonterminal Controls never expire automatically. Keep 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.
+Runtime lifecycle and review actions remain runtime-owned. Runtime kill is the recovery path for a stuck saturated Run; it never consumes actor-local Control capacity or appends a synthetic Control record. Trace/Control quotas do not constrain user-declared artifacts, repositories, media sources, complete captures, or actor-owned workload state.
 
 ### 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.
+Run views are exactly `recipe`, `trace`, and `control`. Trace reports retained-history completeness; Control reports capacity, saturation, stale pending work, journal bytes, and bounded diagnostics. Runtime triage aggregates backpressured Runs and incomplete Trace. Non-Run management targets remain `runtime`, `recipes`, and `tool:<name>`. Apply owner filtering and redaction before projecting evidence.
 
 ## Retained Safety Invariants
 
@@ -128,7 +128,7 @@ Automatic review receives value-free structural projections, not executable cont
 
 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.
+File watchers accelerate reconciliation; a bounded interval recovers missed terminal and retained-attention events. Canonical attention observation uses stable retained ids, primes them at startup without replay, and bounds seen memory to the current suffix across compaction; only allowlisted legacy outbox fallback uses line offsets. Attention is a wake hint, so persist durable recovery state before emitting it. 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.
 

package/BACKLOG.md

@@ -1,191 +1,3 @@
 # Project Backlog
 
-## 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.
+No open items.