@llblab/pi-kit 0.38.4 → 0.39.0

package/node_modules/@llblab/pi-actors/BACKLOG.md

@@ -1,6 +1,209 @@
 # Project Backlog
 
-- [ ] `Next minor — Linux MPRIS media integration`: Expose the active `music-player/playback` singleton as one optional generation-fenced MPRIS2 player so GNOME and compatible desktop shells can show current media and native controls without making D-Bus a second playback authority.
-  - [ ] Publish `PlaybackStatus`, track metadata, duration, read-time position, volume, and supported capabilities under one stable session-scoped bus identity; disappear cleanly when the Run stops or its generation is replaced, and fail soft when the user D-Bus session is unavailable.
-  - [ ] Map `Play`, `Pause`, `PlayPause`, `Next`, `Previous`, `Stop`, `Seek`, `SetPosition`, and `Volume` back into the existing generation-fenced music-player Control/helper contract rather than signaling the backend or editing Run state directly.
-  - [ ] Validate deterministic D-Bus contract behavior plus a live GNOME smoke showing the media surface, metadata, progress, volume, and controls while preserving backend independence and exact Actor ownership.
+Canonical open work: `BACKLOG.md`. Contracts and durable constraints live in `AGENTS.md` and indexed `docs/`; investigation history stays in Git and the referenced evidence, not inside open tasks.
+
+Task IDs name bounded work, not execution order. The operator authorizes autonomous selection and execution of open pi-actors work in Grow Loop: choose dependency-ready high-value cohorts across this backlog without repeated routine permission questions. Dependencies, factual acceptance and specific safety/authority boundaries remain explicit; a gated task is not completed merely because another cohort can proceed. Completing a child does not complete its checkpoint.
+
+## 1. Release 0.56.0 — external convergence
+
+Outcome: Recover the failed immutable-tag validation without silently changing release identity. [PR#137](https://github.com/llblab/pi-actors/pull/137) is merged; `v0.56.0` remains at `48cd1348730f8d4ae8b19ea52dc1fd61ae017622`, whose tree passed all eleven PR checks. The [tag-owned Release run](https://github.com/llblab/pi-actors/actions/runs/42440646237) subsequently failed Windows `owners-a` at the snapshot canonical-facts test. Passing PR checks did not replace this mandatory tag gate. The operator explicitly authorized a correction PR through `dev → main` and conditional replacement of this failed unpublished tag after fresh corrected-main CI and a complete zero-publication/consumption audit. This is not permission for an unchanged rerun, main rewrite or manual publication.
+
+### R2 — Immutable publication completion
+
+Exit: Exact intended package, immutable tag and GitHub Release converge through the existing automation. A pushed tag is not a published/verified release.
+
+- [ ] **R2.3 — Validate and deliver release recovery.** Review the controlled busy-lifetime fixture correction in `tests/run-ui-runtime.test.ts`, then obtain fresh current-head full-matrix acceptance through [PR#138](https://github.com/llblab/pi-actors/pull/138), including Windows installed compiled SDK lifecycle/numbered-history. Keep production behavior, all existing assertions, deadlines, cleanup guards, versions and workflows unchanged. Preserve the existing tag until corrected protected-main CI and the immediately refreshed complete zero-publication/consumption audit pass. Then use only the operator-authorized exact leased failed-unpublished-tag replacement protocol; never rewrite main, rerun unchanged work for luck or publish manually.
+- [ ] **R2.4 — Verify external convergence.** After owning automation succeeds, confirm exact npm version/gitHead/package, immutable tag, published stable GitHub Release/latest and successful owning workflow identities. Visibility retries verify existing state; they never republish. Remove this release checkpoint only after both R2 exit conditions pass.
+
+## Next bounded work
+
+- **Release:** Review and deliver the SDK busy-lifetime fixture correction through PR#138, obtain fresh current-head Windows/full-matrix acceptance, then finish the guarded R2 audit/tag-replacement/publication sequence. Do not move the existing tag early or compete with publication.
+- **Local implementation:** F1.3b is the next concrete projection cohort; success/list/delete/draft receipts still need migration. F1.3c, F1.3s and F1.4i remain separate attributable owners, not proof that all AX output already conforms. N1.4c also permits unrouted deterministic preparation within its reviewed contract.
+- **Explicit gates:** U1 requires authorized loaded-host observation/reload; N1.2p needs actual Windows profile evidence, N1.3 an asset-distribution decision, and N1.6 separate activation admission. Original-clock/native-scope, macOS research and composition decisions retain their own B/C/T gates. Existing release permission does not adopt them.
+- **Evidence reuse:** Reuse the accepted three-OS SOURCE/PACKED quit witnesses for B2.4; extend only the missing descendants/triggers/same-ID/crash cases. N1.9 stays a gated unresolved risk, not an instruction to repeat the completed ownership inquiry.
+
+## 2. Uniform runtime presentation — adopted, rollout pending
+
+Outcome: JSON structured inputs, block-YAML runtime-output metadata and unchanged selected authored text/Markdown, as defined by [the AX contract](docs/agent-experience.md#json-input-yaml-output-opaque-content). This includes tool/spawn receipts, not only Actor results. Rollout remains partial; this checkpoint does not imply uniform emitter conformance, native continuation, package publication or a loaded-host change. Existing machine/input/source/history contracts remain separate.
+
+### F1 — One readable output contract
+
+Exit: New owned runtime projections use YAML without pseudo-records or serialized JSON objects: bare when metadata-only, `---`-delimited headers only when a separate text body follows. Literal content, meaning, source/privacy bounds and saved messages remain intact. Service-carrier adoption has its own evidence gate; do not delete current framing to simulate completion.
+
+- [ ] **F1.3b — Migrate successful registry projections.** Convert registration/update, listing/deletion and draft-promotion receipts with their distinct selected facts, safety-warning priority and whole-value bounds. A separate selected body alone requires a delimited header. Preserve post-effect/coercion/transaction/callability truth and unchanged details. Verify: registry success/list/delete/draft owners and source/packed parity.
+- [ ] **F1.3c — Migrate registry-owned refusals.** Convert only locally authored mode/name/source/template/draft/transaction refusal projections. Keep original getter/coercion/fault order, private causes, opaque advice and whole-source limits; do not wrap host/dependency exceptions or infer no effects/retry. Verify: corresponding registry guard/failure properties and applicable packed witnesses.
+- [ ] **F1.3s — Separate synchronous tool metadata from selected output.** Migrate owned usage/guard/exit-label facts without parsing or reserializing stdout/stderr/report bodies or JSON invocation examples. Keep existing trim/tail/loss basis, exact executor failures and the pre-dispatch repair cutoff. Metadata plus selected text uses a delimited header; metadata-only output stays bare. Verify: tools-local/execution-output/spawn guards and packed dispatch-failure owners.
+- [ ] **F1.4 — Migrate inspection, Control and runtime notices.** Render selected structured/verbose metadata as YAML, including generated JSON Schema views; retain literal sources. Reconcile emitter execution/depth ceilings with actual caller budgets without narrowing public allowances. Preserve error/cause, request/delivery/handling/effects/closure distinctions and recipient fences. Verify: affected Control/inspect/runtime/notification owner properties.
+- [ ] **F1.4i — Verify remaining Inspector feedback recognition.** Check anchored feedback recognition against current AX guard/error output and correct only evidenced gaps. Preserve reviewed generic block-YAML and independent native Markdown, zero added body indentation, exact selected text and own undefined fields, source labels, native columns/wrapping, chronology/identity, chrome, frozen underlay and once-only generation actions. Verify: affected guard/modal properties and compiled parity. Loaded acceptance stays with U1.3/U1.5; no duplicate renderer migration or implicit host reload.
+- [ ] **F1.7 — Accept one rollout candidate.** Verify exactly one visual blank line between host invocation/arguments and each result/error without altering selected bodies. Independently verify no runtime-owned JSON/pseudo-record escape remains in the selected rollout, with history/literal-body invariance, source/compiled/package/Skill parity and permitted terminal/phone acceptance. Keep current capture codec facts and new target distinct; no unrun live/native claim or automatic default activation.
+
+### U1 — Loaded UI/AX acceptance
+
+Exit: Real loaded rendering is checked separately from source/headless/native proofs. This is independent follow-up, not a claim that the already merged release received loaded-host acceptance. Reload and an operator Run require their own authorization; do not start one merely to manufacture a live Kill case.
+
+- [ ] **U1.1 — Retest fresh completion packets and expansion.** After authorized reload, inspect actual singleton/multiple/omitted-row packets: index-first YAML/kind, left-edge independent Markdown, literal unfinished blocks, exact cut marker, blank separation and no routine top-level completion caption/toast. Expansion and historical fallback must preserve the saved text. Verify: actual terminal/phone observation plus existing delivery/Pi owners.
+- [ ] **U1.2 — Retest the Run dropdown.** Check shifted compact placement, independent stripes/right padding, narrow/medium/wide layout and unchanged selection/source detail. Preserve the accepted navigation and refresh behavior; do not invent a performance cause or change freshness speculatively. Verify: real Inspector plus existing overlay/Inspector properties.
+- [ ] **U1.3 — Retest notification and Kill modals.** Check complete selected notification text, no prefix/reader indirection, Esc-only dismissal and scrolling only on physical overflow; check centered compact Kill, default backgrounds/insets, frozen underlay and no key leakage. Cancel returns to the same Inspector without Notice; success relies on selected status and failures remain visible. Verify: actual permitted modal cases, without claiming Kill is scope closure.
+- [ ] **U1.4 — Retest Inspector chronology.** Check newest-higher numbering across 100→101/102, filter gaps without renumbering, scrolling/detail provenance and visible `#?` for unavailable history. Do not promise permanent lifetime ordinals or reconstruct missing offsets. Verify: [chronology contract](docs/actor-inspector.md#chronological-numbering-requested-replacement) on loaded terminal/phone.
+- [ ] **U1.5 — Retest loaded Inspector YAML documents.** After separately authorized reload, verify real block YAML in Recipe, Control, non-agent Trace detail (including process.stderr) and captured Kill fields, with actual sequence shapes, preserved log scalars and independent exact agent Markdown. Check narrow/wide wrapping, stripes, scrolling and unchanged actions on terminal/phone. Source, compiled and independent-review evidence is not already-loaded-host acceptance.
+- [ ] **U1.6 — Retest loaded read-only Control utility.** After separately authorized reload, verify recorded readiness/actions/queue diagnostics, status-first request rows and Enter→redacted YAML on terminal/phone. Check empty/partial history, the20-parsed-record suffix, narrow/low viewports, refresh selection and generation replacement without new Trace reads or actions. Preserve actual status/timestamps and existing Kill guards. Source/compiled/review acceptance is not already-loaded-host proof; no command submission, automatic replay or new protocol.
+
+## 3. Session-wide completion index — adopted, not wired by default
+
+Outcome: Consecutive indices across batches in one logical Pi session; reload/resume/replay preserves allocated numbers. The current repeated single-result `index: 0` is packet-local behavior, not completion of this requirement. This integration is separate from the selective release's currently disabled public-stream boundary; no renderer-local `index++`, silent existing-session bootstrap or historical renumbering.
+
+### S1 — Coupled session-stream activation
+
+Exit: Persistence, trusted lifecycle binding, allocation/capture/recovery and presentation agree under the [adopted stream contract](docs/coordinator-delivery.md#completion-streams-adopted-contract). Existing atomic allocator and fresh-manager bridge are foundations, not default activation.
+
+- [ ] **S1.1 — Finish bootstrap/start/status admission.** Positively establish non-connection and trusted first connection; implement the admitted session-level start/status path. Missing/corrupt state is unavailable, not off or permission to restart at zero. Verify: delivery journal and runtime admission properties.
+- [ ] **S1.2 — Admit continuation and wire the default runtime.** Resolve startup/reload/resume against the original manager/current generation; preserve pending targets, unresolved-packet barriers and `/tree`-independent counters. Establish restore versus independent-copy semantics for imports retaining an ID/reason=resume, and fork/clone isolation. Verify: run-ui/extension-runtime and real source/packed session journeys.
+- [ ] **S1.3 — Preserve immutable numbering/provenance.** Use the kernel allocator's saved whole range/member order and session+stream+index identity; retain unavailable `?`, first-stream boundary and full technical provenance. Projection never reads the mutable current counter, restyles old packets or reconstructs an unknown counter. Verify: run-delivery/Pi/native renderer and installed properties within unchanged budgets.
+- [ ] **S1.4 — Accept continuous delivery and loaded display.** Prove multiple batches advance, replay/recovery does not allocate twice, same-session reload/resume does not reset, and new fork/clone does not inherit numbering. Check actual loaded packets only after authorized reload; source success does not activate the already running host. Verify: ordinary source/packed lifecycle plus permitted UI observation.
+
+## 4. Future supervision and self-contained outcomes
+
+Outcome: Complete [A/B/C and the SUP-01–SUP-17 matrix](docs/run-supervision.md), then D. No future version/release or default activation is implied. Keep unchanged credentials, strict Linux/macOS/Windows authority and positive native-closure requirements. Removal of `inspect` remains a separately gated scope, not an implied task here. A can progress without a production scope backend; A4 needs B1's clock, real enforcement needs B and C. The N1 MI reader supplies identity observation, not protected scope/owner-loss authority.
+
+### A0 — Remaining first-layer AX and partial-failure presentation
+
+Exit: Existing owned surfaces are compact, truthful and selectively recoverable. Included loaded UI is owned by U1; session numbering by S1, not duplicate checkboxes here.
+
+- [ ] **A0.2 — Resolve recipient-bound Control enrichment.** Gate richer id/generation/drill-down on a reviewed original-recipient publication contract across tool call, normalization, hooks and final routing. Current conservative unknown-effects errors/private causes remain valid; manager equality, copied context/IDs or saved errors do not authorize publication. Reopen only on changed host-contract evidence; this optional enrichment does not block the conservative layer. Verify: [recipient-bound preparation](docs/run-supervision.md#recipient-bound-correlation-preparation).
+- [ ] **A0.3 — Integrate authoritative partial-stop facts.** Depend on B2/C/D1 for richer legacy stop receipts and finalization. No missing Trace/handled/progress record proves inaction, and no error grants automatic retry. Verify: [existing-fact reconciliation](docs/run-supervision.md#control-partial-failure-evidence-existing-facts-not-a-new-receipt-contract) and stop/control owners.
+
+### A1 — Shared snapshot/read-model integration
+
+Exit: A single admitted compositor supplies bounded manual/default/timed observations without fabricated timing, permission or native authority. Existing metadata-only default stays until gates pass.
+
+- [ ] **A1.1 — Join supported lifetime and original-origin facts.** Depend on B1.1/B1.2/B1.3; consume original time/reference capabilities, not saved DTOs, PID/wall timestamps or later replacement samples. Keep ordinary missing first-natural time unproven. Verify: snapshot/supervision/status admission properties.
+- [ ] **A1.2 — Wire shared projection routes.** After A1.1, use one compositor/renderer for default/manual/status/timed routes; preserve source/lifetime fences, null/redacted cwd/index, secret masking, metadata-only artifact observations and selective navigation. No second status implementation, source read, ACK, lifecycle or actuation side effect. Verify: snapshot/observability/inspect-security families (`SUP-05`, `SUP-14`).
+- [ ] **A1.3 — Join forced-stop projection only from authority.** Gate confirmed stop/closure display on C and B2 facts; unknown lifecycle/timing remains explicit. Verify: stop/snapshot classification, not rejection-only native support.
+
+### A3 — Source selection, recoverability and clipping
+
+Exit: Only explicitly admitted sources/retention cross evidence → projection → delivery; first result/unavailability and saved packets stay immutable. The accepted logical-session file-navigation route remains separate and already supplies ordinary location research.
+
+- [ ] **A3.1 — Decide the broader stdout predicate.** Obtain approval for final successful settled ordinary-command attempt, including a single retry wrapper, before extending the initial bare-command/one-attempt raw-source contract. Composition/parallel/repeat/recovery/policy output, stderr and Actor-session answers need their own predicates. Preserve the 4 MiB input boundary. Verify: [selection reconciliation](docs/run-supervision.md#a3-owner-reconciliation-and-unadopted-selection-proposal).
+- [ ] **A3.2 — Decide summary/diagnostic retention.** Approve source-kind/privacy/storage/replay boundaries before retaining more than fixed fields or pre-record Trace text. Resolve collector1000/display200 and failure-journal4096 UTF-16 losses without split scalars, guessed counts, raw/private disclosure, malformed repair or changed packet text. Verify: [legacy disclosure boundary](docs/run-supervision.md#legacy-completion-disclosure-boundary).
+- [ ] **A3.3 — Integrate only approved source branches.** After the corresponding decision, prove full authorized retention before formatting, exact ranges/Unicode counts, whole-row omission and immutable provenance/unavailability through existing evidence/delivery/render owners. Executor-final-response capture is bounded retained text, not expanded raw-stream permission. Verify: ordinary source/packed recovery (`SUP-11–12`, `SUP-14–16`); reuse unchanged primary/artifact/diagnostic witnesses.
+
+### A4 — Latest-only diagnostics and context
+
+Exit: Reporting uses A1, the accepted session-owned navigation and B1's admitted clock, with descendants quiet and default reporting disabled.
+
+- [ ] **A4.1 — Implement root cooldown/coalescing.** Coalesce only unadmitted observations; freeze admitted packets and honor `RUN_DIAGNOSTIC_MIN_INTERVAL_MS` at actual accepted delivery. Manual/terminal/urgent bypass stays independent. Verify: delivery/runtime clock-boundary fixtures (`SUP-06–08`, `SUP-17`).
+- [ ] **A4.2 — Fold only obsolete automatic context.** Preserve native/foreign/manual history, mixed terminal members and acceptance evidence; do not rewrite stored packets or widen source permissions. Verify: session-evidence/context-recovery fixtures (`SUP-13`).
+
+### B1 — Original clock, host lifetime and controller ownership
+
+Exit: Supported coordinator/independent-supervisor lifetimes retain original origins without new allowance; same-runtime claims do not masquerade as cross-process authority.
+
+- [ ] **B1.1 — Resolve the live-origin carrier contract.** The carrier proposal is unadopted. Establish clock-domain/epoch/platform, issuer/bootstrap/return, bounded nonblocking relay and cleanup, then obtain approval before kernel-interface work. No channel/nonce/DTO, late sample or passive historical receipt reconstructs an origin. Verify: explicit [carrier gate](docs/run-supervision.md) and first-natural semantics.
+- [ ] **B1.2 — Establish host shutdown-before-invalidation.** Resolve bare `AgentSession.dispose` coverage with trusted shutdown, not copied IDs or inferred revocation. Integrate supported original-manager lifetimes while preserving singleton clocks and existing retained capabilities. Verify: real SDK lifecycle plus replacement/revocation fixtures.
+- [ ] **B1.3 — Integrate ordinary first-natural timing and controller authority.** After B1.1/B1.2, carry the original one-shot capture into ordinary runner/supervisor lifetimes; preserve pending/failed publication and post-stop uncertainty. Resolve ownership across distinct origins/runtimes/processes, not only cooperative same-origin claims. No cross-process/model await under lifecycle admission or relocated canonical T0. Verify: supervision/time/long-workload families (`SUP-03–04`).
+- [ ] **B1.4 — Admit restart recovery without renewal.** Missing clock/origin stays unavailable; saved start/clock metadata cannot grant a fresh allowance, launched-Run fact or terminal timing. Verify: restart/overdue/provider-fault and singleton witnesses.
+
+### B2 — Existing stop protocol and parent-stop integration
+
+Exit: A request/ACK/signal is not terminal handling or whole-scope closure. Actual native actuation remains C-gated.
+
+- [ ] **B2.1 — Remove stalled-transport lock coupling safely.** Replace lifecycle admission held across awaited `sendRunControl` transport only after an equivalent generation/endpoint fencing contract exists. Do not merely remove `await` and open a replacement race. Verify: transport saturation, release faults and same-ID replacement.
+- [ ] **B2.2 — Join claims/work/captures to confirmed stop.** Keep durable first cause and natural-result precedence; replace immediate handled/progress/terminal finalization after signaling with confirmed supported scope termination. Verify: control/lifecycle/native-authority boundary families (`SUP-09–10`).
+- [ ] **B2.3 — Reconcile every terminal reader and retention path.** Keep nonterminal request ACKs, `timed_out`, pending captures and exact generation consistent across status/collector/retention. Verify: status/outcome/retirement owners without fabricated closure.
+- [ ] **B2.4 — Extend the accepted portable quit evidence.** The ordinary SOURCE/PACKED graceful-quit case already passed exact-candidate Linux/macOS/Windows CI with actual runner close, direct-workload fresh absence and a surviving foreign owner; retain that evidence rather than replaying it as missing. Remaining work is descendants, other triggers, concurrent same-ID hosts, crash/hung-host and original owner-instance lifetime. These extensions require their corresponding B/C authority; the existing case proves neither sealed membership nor full closure. Verify: native shutdown and parent-stop families for only the newly admitted cases.
+
+### B3 — Deterministic controller integration
+
+Exit: Controlled drivers prove controller behavior, not OS termination or platform support.
+
+- [ ] **B3.1 — Join admission and stop races.** Exercise canonical state/lifecycle-lock contention, deadline/manual/natural ordering, replacement and unavailable scope authority across B1/B2. Verify: explicit controller drivers (`SUP-03–04`, `SUP-08–10`).
+- [ ] **B3.2 — Preserve long-timer/provider-fault behavior.** Integrate existing wake-plan, overflow and fault witnesses without fresh allowance, fake authority or native-support claims. Verify: deterministic supervision/time properties before native integration.
+
+### C1 — Three-platform protected scope and owner-loss authority
+
+Exit: Approved native scope identity/issuer/compatibility and positive evidence for Linux/macOS/Windows under unchanged credentials. Heartbeat loss and runner PID are not owner-death authority; namespace/group-mapping variants remain parked.
+
+- [ ] **C1.1 — Review exact native bootstrap/setup contracts.** Review protected cgroup-v2/pidfd, Windows HANDLE/Job and the admitted macOS candidate with original host lifetime, session epoch and Run generation before work. Backend implementation remains gated on the macOS feasibility in C1.3/C1.4. Record concrete setup/rights/containment requirements for separate approval before performing them. No second registry, journal-reconstructed grant, privilege escalation or Linux-only substitution. Verify: [owner-loss mechanism gate](docs/run-supervision.md#owner-loss-termination-approved-outcome-and-mechanism-gate).
+- [ ] **C1.2 — Bind the separately permitted macOS inventory operation.** Select the exact approved clean GitHub commit and inventory-only envelope before using the previous single inventory-only permission; `inventory_only=true`, `execute_pilot_a=false`, empty reviewed-profile JSON/digest. Current selective-release authority does not execute this research workflow or grant pilot A. Inventory facts cannot approve a profile. Verify: [SPI/CI plan](docs/run-supervision.md#macos-spi-and-ci-feasibility-plan).
+- [ ] **C1.3 — Admit and execute macOS observational profile A.** Obtain exact v2 profile/`transport_sha256` and native-execution approval. Prove ABI, identities, fork/setsid observations and actual cleanup for macos-15/arm64 Xcode16.4 SDK15.5 under unchanged credentials; then separately review macos-26/arm64 and macos-15-intel. Local/mock/19-case C-core evidence is not native PASS_A, C1 or B authority.
+- [ ] **C1.4 — Prove macOS issuer/bootstrap and complete closure feasibility.** Establish one authenticated issuer, exclusive pre-work binding, retained lifetime, sealed membership/emptiness/recovery and supported profile/setup. Exercise real own/foreign, ingress/escape/stop, owner/controller loss and partial faults. Keep B blocked if unavailable; no guessed SPI authority, coalition/accounting requirement, registration or speculative adapter.
+- [ ] **C1.5 — Verify cross-platform compatibility and authority.** After mechanism feasibility, prove no breakaway/migration, correct original-instance authority, handle/controller loss and compatibility with existing host containment. Retain every uncertain/non-pass result. Verify: agreed native profiles, not labels, metrics, helper exit or rejection-only tests.
+
+### C2 — Authenticated live membership before work
+
+Exit: Scope membership is authoritative and generation-bound, not copied preparation data or directory ancestry.
+
+- [ ] **C2.1 — Bind the actual spawning member and parent.** Extend private intent/preparation evidence with authenticated native scope identity and live membership before work. No actor scope path, delivery environment, owner discovery or index lineage supplies that authority. Verify: admission/missing/foreign/replaced membership families (`SUP-02`, `SUP-09–10`).
+- [ ] **C2.2 — Serialize ingress with parent stop.** Cover fork/setsid and separately spawned cross-owner Runs, parent/child admission contention, migration/descriptor/namespace egress and nested scopes. Preserve independent child policies within the parent scope and original parent clock. Verify: real native ingress/escape plus controlled races.
+
+### C3 — Positive closure, recovery and retirement
+
+Exit: Only sealed complete scope identity/emptiness plus recursive exact-generation child closure permits finalization or guard release.
+
+- [ ] **C3.1 — Compose complete native/child closure.** Retain escalation policy and authoritative original-scope evidence; all recorded members settling is not complete membership or closure. Wire ordinary native/child starts only after C2 and closure integration. Verify: positive native stop/escape/descendant witnesses.
+- [ ] **C3.2 — Recover uncertain preparations without inventing work.** Handle producer loss, staged-only/incomplete records, malformed/legacy/replaced proof and runtime-local cleanup quarantine. No identity backfill, reconstructed authority, fabricated exits or metadata-to-work promotion. Verify: real crash/replacement/recovery and retirement guards (`SUP-09–10`).
+
+### D — Future integrated supervision acceptance and release
+
+Exit: One candidate supports the complete SUP-01–SUP-17 claim set. A/B readiness does not replace C, and unsupported/unproven or rejection-only behavior is not positive enforcement support. No future version is authorized yet.
+
+- [ ] **D1 — Wire admitted public ingress.** After readiness, integrate Recipe/spawn literals, delegation/async inheritance and synchronous-path refusal; keep ordinary arguments/singleton compatibility. Expose the admitted generation and require top-level kill preconditions, exact terminal ACKs, consistent readers and kill independence from actor Control saturation. Verify: Recipe/tools/Control/source-packed journeys (`SUP-01–02`, `SUP-09–10`, `SUP-13`).
+- [ ] **D2 — Prove positive deadline/manual/natural outcomes.** Join B/C through actual public launches on the agreed native platform set: membership before work, independent expiry, sealed admission, owned-scope termination and only then `timed_out`. Cover descendants, replacement, producer loss/recovery and event ordering. Reject unsupported limits before work; rejection alone is not acceptance (`SUP-03–04`, `SUP-08–10`).
+- [ ] **D3 — Validate one future candidate.** Only after A/B/C and live/native acceptance, select an eligible minor version, consolidate outcome notes and align API/Skills/package/lock/dist. Bind the complete evidence matrix, normal validation, source/packed parity, native checks, dependency audit and context checks. Equivalent-input reuse is allowed; mocks/skips do not replace native proof.
+- [ ] **D4 — Perform the separately admitted release handoff.** Follow refreshed ADMIN/fork/dev-route/remote/version/tag eligibility and sole workflow ownership. This future epic grants no reset/rebase/force-push/intermediate publish/tag reuse. Close only after immutable-tag automation and exact npm/GitHub verification; keep MPRIS separate.
+
+## 5. Future Linux MPRIS integration
+
+Outcome: One optional MPRIS2 surface for the existing `music-player/playback` singleton, not a second playback authority. No current release activation.
+
+### M1 — Generation-fenced bus surface
+
+- [ ] **M1.1 — Define bus lifetime and availability.** Use one stable session-scoped identity, withdraw it on stop/replacement and fail soft without user D-Bus. Verify: deterministic ownership/generation/bus-loss properties.
+- [ ] **M1.2 — Publish truthful media state.** Supply playback status, metadata, duration, read-time position, volume and capabilities from existing playback facts; do not edit Run truth or signal the backend. Verify: MPRIS property/position contract.
+- [ ] **M1.3 — Route controls through existing Control.** Map Play/Pause/PlayPause/Next/Previous/Stop and Seek/SetPosition/Volume into the generation-fenced helper contract. Verify: deterministic delivery/refusal and replacement races, preserving backend independence.
+- [ ] **M1.4 — Accept the live GNOME surface.** Check media presence, metadata, progress, volume and controls against the owned Actor; retain missing-environment evidence rather than claiming a smoke pass. Verify: separately authorized live session.
+
+## 6. Composition transport and optional CodeMode
+
+Outcome: Refine the [recorded design intake](docs/composition-transport.md) separately from 0.56.0. Illustrative APIs are not adoption or a new runtime requirement.
+
+### T1 — Bundle contract and resolver integration
+
+- [ ] **T1.1 — Decide the portability boundary.** Resolve recipes-only versus scripts/assets, external dependencies, export privacy, source provenance and aggregate limits before claiming self-contained portability. Keep container IDs distinct from Recipe names/global Skill identity/Run authority. Verify: contract review.
+- [ ] **T1.2 — Specify and validate JSONL grammar.** Define manifest/entry/record/local-ID/reference rules and refusal for duplicates, missing IDs, cycles, truncation and malformed input. Verify: bounded parser/preflight properties after T1.1.
+- [ ] **T1.3 — Integrate lossless pack/load.** Reuse current resolution/composition, preserving args/defaults/Control/async/artifacts/runtime origins/relative paths/source privacy. No second runtime or registry. Verify: relocation and source/packed parity after T1.2.
+
+### T2 — Agent operating patterns and interoperability
+
+- [ ] **T2.1 — Update actual owning Skills.** Teach optional preflight/conditional chains, bounded awaited fan-out, real-completion fan-in and selective result reading with omission counts. actors owns shared lifecycle mechanics; swarm owns independence/scopes/dissent/integration. Include benefit/overhead/contracts/failure/cancellation and ordinary-tool fallback; docs alone do not complete delivery.
+- [ ] **T2.2 — Validate real host interoperability.** Exercise actual spawn/active registered-tool calls through CodeMode with awaited receipt, independent outcome delivery, context/generation, cancellation before/after materialization and partial effects. Preserve failure/source/omission semantics; no polling, new wait service, abandoned Promise, raised Pi floor or implicit JS Recipe backend. Verify: source/packed host-capability journeys.
+
+## 7. Optional native acquisition and post-release package work
+
+Outcome: Prepare a separately reviewed optimized acquisition path without retroactively turning it into a 0.56.0 release blocker. The shipped reader remains PowerShell with corrected UTF-8. Inert differential success and restored SDK timing observation do not admit UTC/provider profiles, executable assets, production routing or full native SDK convergence. The owning [Windows design/evidence](docs/windows-process-observation.md) preserves those boundaries.
+
+### N1 — Reviewed fresh Windows acquisition
+
+Exit: A separately admitted optimized shipping path preserves identity/status/authority semantics and passes unchanged source-and-packed SDK/native acceptance. This future backend is not the released PowerShell UTF-8 correction. Owner: process acquisition, not supervision. Design and experiment evidence: [Windows process observation recovery](docs/windows-process-observation.md).
+
+- [ ] **N1.2p — Establish UTC-profile admission.** Record actual native environment/version facts and real PowerShell precision-boundary witnesses, then define/test the exact initial admission predicate. MI offset zero, runner labels, JavaScript timezone or expected-identity equality are insufficient. Keep unproved date/provider partitions unsupported. Verify: Windows differential and separately disclosed controlled formatter witnesses.
+- [ ] **N1.3 — Decide native executable distribution.** Obtain an explicit decision on reviewed unsigned Windows x64 repository/npm assets with manifest-bound provenance and baseline fallback. Recommendation: committed prebuilts, no install-time compilation/download. This decision does not approve default activation. Verify: source/build/artifact/architecture/dependency and execution-policy review.
+- [ ] **N1.4c — Complete asset-verified acquisition preparation.** Add the bounded complete-manifest reader, trusted exact-byte selection, fixed versioned package-relative asset verification/lookup and shell-free invocation seam under the reviewed contract. Preserve raw-null refusal and unsupported UTC admission until N1.2p; comparison/status/fences remain in their owners. No production routing or binary inventory change without their separate gates. Verify: mirrored asset/acquisition/fallback ports and source/compiled parity.
+- [ ] **N1.5 — Bind the exact candidate asset.** After N1.3, retain reviewed Windows build bytes and manifest, verify source/artifact hashes and toolchain provenance, and make offline build/prepack copy-and-verify assets for source and compiled lookup. Ordinary users need no compiler, new runtime, download or privilege. Unsupported architecture and missing/corrupt/policy-blocked assets must not bypass policy or repair a mismatch. Verify: source/packed asset parity and differential against those exact bytes.
+- [ ] **N1.6 — Review and integrate acquisition routing.** Gate on N1.2p/N1.4c/N1.5 and explicit activation admission. Change only the fresh scalar/shared acquisition seam; keep liveness, public status/error precedence, original-frame fallback, publication/Control/snapshot/teardown checks and callback fences. Never fall back through a supported identity mismatch or replacement. Verify: process/status/observability/results/Control owners and independent review.
+- [ ] **N1.7 — Close real SDK/native convergence.** Run the full source-and-packed journeys through the integrated shipping path and obtain the complete three-OS/three-shard matrix plus audit. Keep 87 planned genuine Runs/layout, nine modes, both 40-spawn cohorts, workload 300 s/10 ms, SDK watchdog 900 s Windows/300 s elsewhere, operator-admitted five-second completion-boundary ESRCH settlement after canonical work readiness and separate ten-second original-close acceptance. Other existing eight-second settlement policies remain unchanged. No extra skips, forced exits, signals, fabricated birth/absence or deadline resets/inflation.
+- [ ] **N1.9 — Gate further private-cleanup remediation on new evidence.** The intermittent post-research final-PID refusal remains causally unexplained despite a passing release-candidate run; it is not an active red check. The producer/reader inquiry found no ownership omission. Reopen implementation only for a new falsifiable actual-owner mechanism, or explicit admission plus reviewed positive original-generation/resource proof before changing cleanup. Prior absence, close0, an arbitrary mismatch or guessed PID reuse cannot replace fresh ESRCH for every captured safe PID. No repeated role-only inquiry, wait inflation, dropped captures, forced cleanup or luck reruns.
+
+Shared N1 constraints: Retain uncertain roots; fresh ESRCH immediately precedes every deletion. Missing/malformed/query failure never proves absence. Preserve fingerprint schemas/algorithms and saved historical identity bytes, existing optional normalization and `.trim()`, exact falsy/ordered causes and all source/privacy/generation/physical fences. Corrected UTF-8 acquisition must not rewrite old lossy Unicode records or accept legacy aliases; a live mismatch remains `owner_mismatch`. No TTL/cross-callback identity map, daemon, new mandatory platform prerequisite or native-check elision. A prototype pass does not activate a backend. Reuse unchanged evidence semantically; packaged docs/status changes still invalidate an earlier exact tarball.
+
+### R1 — Post-release package-surface review
+
+Exit: Any later cleanup is independently justified and validated against its own tree. The immutable 0.56.0 tag is not a cleanup branch; source/packed presentation and release-narrative acceptance are already covered by the accepted release tree.
+
+- [ ] **R1.1 — Inventory retained inactive foundations before a removal decision.** Identify packaged but unactivated supervision/stream/native-adapter owners, their actual consumers and interleaved safety guards. Produce a reachability/package inventory that distinguishes reviewed runtime dependencies from optional foundations; remove nothing merely by filename or because its default path is off. Default supervision and public completion streams remain disabled. Verify: source/compiled/default-wiring and npm-inventory audit; use existing build/package evidence where inputs are unchanged.
+- [ ] **R1.2 — Remove temporary diagnostics after native acceptance.** Gate on N1.7; remove only proven temporary/redundant instrumentation, preserve owned regressions, then refresh invalidated focused checks and final candidate-bound packaging/native evidence. A dirty status note or earlier executable result is not final-tarball proof.
+
+## Evidence and scope notes
+
+The committed baseline of the former backlog is retained in Git at `16a3417`; later operational evidence is linked from the owning design and CI runs. Old candidate logs, review hashes and investigation iterations are evidence, not additional open work. Do not infer completed functionality from a closed author/reviewer process or infer publication/activation from a prototype PASS.

package/node_modules/@llblab/pi-actors/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## Unreleased
+
+## 0.56.0: AX, File Navigation and Runtime Safety
+
+- `AX Records`: Compact spawn/async-tool receipts, full spawn metadata and fresh attention use block YAML with opaque selected content and whole reference sequences. Metadata-only replies stay bare; bodies follow closed headers without added outer indent. Ordinary attention remains unbounded; urgent complete-message fitting keeps16KiB and later-group coverage. Other surfaces retain flat records during rollout. Source/activation contracts, machine details and saved text stay unchanged.
+- `Actor Inspector`: All metadata documents use real block YAML; agent bodies remain independent native Markdown and selected undefined stays distinct. Control adds read-only readiness/queue diagnostics and a bounded request list with redacted YAML detail. Trace ranks retain #? uncertainty/selection; menus retain stripes/padding. Compact Kill/notices keep frozen backgrounds and whole selected text; cancel/success stay silent, failures/uncertainty remain visible.
+- `Immutable Completion Records`: New completions put index/run/state/kind in nested YAML without compiler HTML tails and render unindented Markdown separately. Known cuts show [N characters omitted] at the cut, not in metadata. Up to64shown/256captured members share48KiB including framing with frozen equal quotas and whole source refs. No success toast remains. Content-bound rendering and exact historical replay confer no acceptance, read or native authority.
+- `Recoverable Outcomes`: Successful completions show proven command output or executor-selected Actor responses, not launch metadata. Pi text-print (direct or SDK CLI via Node), composition and retry replies use captured privacy and immutable generation-bound sources. Counts cover retained response text; upstream clipping remains separately unknown. Diagnostic/declaration/omitted-member refs stay recoverable. Missing sources are not repaired; no full-stream or native-closure claim follows.
+- `Session File Navigation`: Launch receipts expose observed file locations and identify existing-Run reuse without promising another launch. Explicit investigation gives the owning session a root-first, generation-bound map, including resume without original producer keys; failed investigations prioritize observed failed subtrees. Whole references remain navigation metadata, not body or native authority. Catalog failures do not authorize replay.
+- `Conservative Failures`: Keeps original errors after executor/launcher handoff instead of guessing argument-repair advice. Selected request, mutation, recording and release boundaries retain ordered private causes without rollback or replay. Control separates delivery, handling and effects uncertainty; changed-owner/generation refusals withhold replacement status even in verbose output. A kill attempt is not confirmed scope termination. Nonregular Control journals stay unavailable, never healthy empty.
+- `Shutdown and Retention`: Fences graceful parent teardown to the captured current session-manager lifetime, refusing stale or reused contexts. Startup cleanup requires owned, generation-consistent state and proven PID absence; retained native/child/preparation journals stay fenced. Graceful teardown and these guards do not establish independent owner-loss supervision, same-ID host isolation or full-scope closure.
+- `Packaging and Release CI`: Omits npm banner, retaining hosted media/runtime. PR-only CI uses3shards/OS and one conformance pass. npm verification waits10min without republishing, checking version/gitHead/manifests. Missing procfs avoids scans. UI/delivery share an inventory; Windows CIM reads stay invocation-local with metadata fences and now emit strict BOM-free UTF-8. Saved fingerprints are not repaired. Animation is display-only; fixtures await readiness and retain uncertain roots.
+
 ## 0.55.0: Active Completion Overlays
 
 - `Active Completion Overlays`: Batches ready Actor trees at the next completed model-step boundary, after the full tool batch, so the running coordinator receives fresh results before idle without native steering. Preserves prior boundary entries, exact owner/generation fences, and debounced idle wakeups. Proposed entries remain pending until exact context or bounded session evidence proves acceptance; dropped proposals retry without premature handled markers or duplicate accepted reports.

package/node_modules/@llblab/pi-actors/README.md

@@ -11,12 +11,20 @@ Run = Recipe + Trace + Control
 
 An **actor** is any runnable local capability: a script, tool, service, pipeline, or subagent. A **Recipe** is its reusable executable definition. `spawn` creates a **Run**—one concrete actor instance—which captures its Recipe, appends observable **Trace**, and may consume actor-local **Control**.
 
+## Agent Experience (AX)
+
+pi-actors adopts **AX — Agent Experience** as a project-wide design standard: give the agent visible, structured context for its next decision while keeping the same facts easy for a person to read. The adopted form is typed block-YAML runtime metadata with opaque authored content, not Markdown-list pseudo-objects. Inspector, tool results/errors and agent-bound outcomes should follow that direction as their owned rollout proceeds.
+
+The [AX standard](docs/agent-experience.md) adopts JSON structured inputs → block-YAML runtime-output metadata, with Actor-authored text/Markdown preserved outside the header. This includes tool/spawn/status/Control/inspect output, not only completion results. It is an adopted direction, not a claim that current mixed-format emitters already conform; [BACKLOG.md](BACKLOG.md) tracks rollout. Machine protocols, privacy/source permissions and immutable saved messages remain separate. Current completion indices are packet-local; independent native owner-loss supervision, execution deadlines and public session completion streams are not enabled. The future contracts do not strengthen the existing stop/closure guarantees.
+
 ## Local Coordinator Model
 
 Multi-instance systems commonly put instance creation and routing in an external gateway. pi-actors supports a different topology: the current Pi instance remains the coordinator, companion extensions such as Telegram provide presence, and explicit Runs perform bounded delegated work. The coordinator receives high-level outcomes, decomposes them, stays available for decisions, and owns integration plus final validation instead of becoming another undifferentiated worker.
 
 This topology does not require every task to become a subagent. Short work with one natural validation boundary stays inline; delegation pays when clean context, asynchronous execution, independent judgement, parallel ownership, or coordinator availability exceeds its coordination cost. Bounded implementation can run with reasoning off while the coordinator selectively launches clean-context reasoning-enabled reviewers; several independent reviews can provide broader evidence than one author self-review. Boundary-delivered completion batches, durable Trace, and declared artifacts replace tight polling loops.
 
+Design notes for [portable Recipe composition bundles and CodeMode interoperability](docs/composition-transport.md) are recorded separately. JSONL bundle loading is not implemented or included in the current UX/AX release; host CodeMode, when available, calls existing tools rather than replacing the Run kernel.
+
 ## Install
 
 Requires Node.js 22.19.0 or newer and Pi 1.0.0 or newer.
@@ -151,12 +159,24 @@ String command-template leaves execute directly without shell interpretation. Us
 
 Trace fields are exact: `id`, `ts`, `kind`, and optional `summary`, `data`, `level`, `attention`. Address, sender, recipient, reply, and routing fields fail validation. Trace is a bounded retained suffix, not an audit archive: the canonical authority appends within 2,048 events and 4 MiB or atomically keeps the newest suffix plus one warning-only `runtime.trace_compacted` marker. That marker means older history was discarded; `result.json`, `execution.json`, terminal state, and declared artifacts retain their own authority. `inspect view=trace` reports whether retained history is complete. Reads are newline-safe and deterministic; first-party scripts never write this file directly.
 
-Generic command lifecycle is Trace-only: runner-owned `command.done` records preserve completion and execution evidence but never request or project attention, including malformed legacy records carrying `steer`. There is no Recipe-level command-completion delivery switch. Semantic attention is explicit: `notify` shows visible status without a model turn, `followup` supplies ordinary checkpoint context, and `steer` requests urgent delivery at Pi's next safe assistant/tool boundary. `notify` and `followup` remain retained wake hints that may compact away, so persist recovery state or an artifact first. `steer` is admitted to the bounded owner delivery journal before `deliverAs: "steer"`, acknowledged only in exact model-bound context, and never suppresses the eventual root-terminal batch. Store large evidence in artifacts or bounded execution captures.
+Generic command lifecycle is Trace-only: runner-owned `command.done` records preserve completion and execution evidence but never request or project attention, including malformed legacy records carrying `steer`. There is no Recipe-level command-completion delivery switch. Semantic attention is explicit: `notify` shows visible status without a model turn, `followup` supplies ordinary checkpoint context, and `steer` requests urgent delivery at Pi's next safe assistant/tool boundary. `notify` and `followup` remain retained wake hints that may compact away, so persist recovery state or an artifact first. `steer` is admitted to the bounded owner delivery journal before `deliverAs: "steer"`, acknowledged only in exact model-bound context, and never suppresses the eventual root-terminal batch. Store large evidence in artifacts or bounded execution captures. New urgent steers keep the canonical checkpoint and whole optional references within 16 KiB, explicitly counting omitted paths instead of cutting a path; saved envelopes retain their original text. Essential text that cannot fit remains retryable before admission, not partially delivered. Ordinary notify/followup shares exact reference spelling and explicit eight-slot coverage; its wake policy is unchanged. Legacy body and steer-diagnostic clipping explicitly marks unknown omission counts when no retained privacy context admits safe numbers; it is not a new privacy or completeness guarantee.
 
 Ordinary finite Runs project terminal results through one root-coordinator completion scheduler. Nested actors inherit durable parent-generation lineage: their own Pi sessions never emit completion turns, and their results wait for the complete containing top-level tree. While the root Pi is active, the next completed `turn_end` boundary snapshots all ready trees into one immutable bounded batch, appends one visible custom message after the full tool batch, and requests one next model step. This overlay uses boundary entries, not Pi's native steering or follow-up queue, so the model can integrate fresh results before its current run settles. Already-idle Pi retains a short debounce and one automatic follow-up wake. The operator and model receive the same parent-child tree with bounded actor outputs. Proposed boundary entries stay pending until exact model context or bounded active-session evidence proves acceptance; an idle send finalizes on successful Pi acceptance without requiring a later context callback. Sequence, parallel, repeat, and imported branches remain internal, while separately launched Runs retain exact independent generations. Silent Runs and synchronous stop acknowledgments remain non-projecting.
 
+Unreleased UX/AX subset: completions share48KiB UTF-8 including service fields, divided equally between up to64 candidate results: nearly48KiB for one,24KiB each for two,16KiB each for three. Whole admitted text fitting its share is result; otherwise preview carries the safe prefix and exact omitted count, without a fixed16KiB result/2KiB preview cap. Completions show admitted work output or the bounded executor-selected final Actor response, never command metadata. Saved packets keep their original budget/text; source-backed prefix selection occurs only at fresh admission, not replay/render. Direct Pi text-print answers and successful composition/retry responses use the original producer privacy; observed upstream clipping stays explicit and is not confused with preview loss. Ordinary completions can carry retained primary-text, artifact-declaration inventory and diagnostic-metadata references. Follow the exact reference for clipped or omitted evidence; it records capture-time identity/hash/counts, not perpetual readability. Artifact inventories list declarations only, not proof that target files exist or were produced, and do not grant body-read permission. Diagnostic excerpts identify the selected field with literal UTF-8/Unicode counts; their source contains recorded command/error/failure-reason metadata, not complete primary output. Source loss is explicit and never replaced by guessed legacy bodies or paths. See [Run supervision](docs/run-supervision.md) for implemented boundaries and remaining acceptance gates.
+
+Unreleased A2 subset: `inspect target=runtime view=runs verbose=true` now adds a bounded [root-first file map](docs/run-supervision.md#same-session-file-investigation) for the actual session's already cataloged directories. Follow selected locations with ordinary tools, without an original producer key. Source/npm-packed SDK fixtures resume the same saved session in a new process after real Run producers and their coordinator host have exited, then read the actual result and select recorded stdout via the mapped execution manifest with ordinary tools; another session gets no inherited branch. The read-only map exposes canonical starting-location coverage and expected format hints, not a full file inventory or format/completeness validation. Its published_sessions link locates the fixed role catalog physically under the owned Run root, even without a semantic index or producer key; this does not certify its body or historical publication. SDK checks select one controlled partial preview and also read an actual private-writer preview after its holder exits and the same saved session opens in another process. Exact tool-read paths and final byte/absence snapshots are checked, including selected-preview loss errors without cached/raw fallback; the private publisher uses controlled recorded-session sources, not genuine Actor conversations. A finite public spawn and later same-saved-session research also pass through real source/npm entrypoints, without replacement tools or copied lifecycle wiring. Corrupt catalogs stay unavailable without repair. Inventory filters observe current Run status, not the registration-time cache. Ordinary maps retain root-group recency with known failed children first; add status=failed to the verbose request for observed failed-subtree-first ordering across roots without filtering the full owned map or adding reads. Priority is partial observed data, not terminal authority. Launches and compatible singleton attachments now register after lifecycle release; catalog failure returns `catalog=unavailable` without failing or retrying the launched work. SDK fork/clone preserves inherited history but gives the new logical session no fresh map branch. Compact launch receipts now include exact-generation current-session starting locations without evidence-body or catalog reads, or explicit unavailability/whole-row omission. New completion batches freeze bounded same-session location rows at admission and render them after outcomes within the shared budget, alongside the optional current-session map command. Legacy absent/request-only packets retain their text; source/npm SDK verifies an explicitly requested result read from a terminal row. This closes representative navigation acceptance, not the release. Neither captured locations nor the request execute inspection automatically or grant copied/forked history fresh ownership. Legacy batches keep their original text; no full map is embedded into immutable outcomes. Compact/default inspection, curated previews and timing/work/native authority are unchanged.
+
+Compact spawn/asynchronous-tool launch receipts use bare block YAML with nested file-location data and identify an existing Run reuse instead of implying another launch. Full `spawn verbose=true` metadata remains JSON during the staged rollout; private details and input schemas keep their machine formats. When a complete direct file-location row is shown, it replaces the redundant session-wide map hint; missing, unavailable or omitted rows retain that optional investigation command. Exact references, expert details, shared bounds and saved completion-packet text are preserved.
+
+New automatic completion packets show direct `omitted:N chars` fields for positive tracked primary/diagnostic loss, counted in Unicode code points after privacy projection. Full retained references and older saved packet text stay unchanged. This does not yet cover every legacy summary/body or attention clipping path, nor grant broader output publication.
+
+Runtime argument guidance stops at the execution handoff. Failures after an executor entry or launcher handoff keep their original cause/details, even if their wording resembles a missing or invalid argument. Later-step failures can follow partial work: do not blindly repeat the invocation. This changes presentation, not retry policy or native termination guarantees.
+
 ## Control
 
+An exception does not guarantee an unapplied action: actor-local delivery can fail after handling is recorded, and retirement can fail after data has moved or been removed. Use existing owned evidence rather than replaying the action. The [partial-failure evidence map](docs/run-supervision.md#control-partial-failure-evidence-existing-facts-not-a-new-receipt-contract) distinguishes these paths from still-gated native stop receipts.
+
 Controls persist to `controls.jsonl` before transport. One token-owned lock rejects a 65th pending Control or 1 MiB rewrite before admission, fails closed on malformed or stale-generation evidence, and atomically admits one record. Canonical transitions retain a 128-terminal tail, expected-state fencing, and 4 KiB errors. Admitted nonterminal Controls never expire automatically. Every record carries immutable `run_instance_id`. `inspect view=control` reports pending capacity, saturation, stale work, journal bytes, and bounded diagnostics.
 
 Runtime-owned lifecycle and retention actions use the same `message` tool:
@@ -167,8 +187,12 @@ message target=run:<id> action=archive
 message target=run:<id> action=prune input={"preserve_artifacts":true}
 ```
 
+Compact Control replies report an understandable action stage instead of dumping status objects: queued/delivered is not handled; archive/prune success is complete; a kill attempt leaves full termination explicitly unconfirmed. Only a relevant evidence hint is shown (Control for actor delivery, Trace for a stop attempt, owned inventory after identity replacement); already-terminal refusal needs no routine follow-up. Use `verbose: true` on the original request for full JSON, not a repeated destructive action. Changed-owner/generation refusals also omit the replacement status from full/verbose replies; verbosity grants no extra scope. Same-identity receipt detail remains available. Actor-local dispatch exceptions still fail, conservatively leaving delivery, handling and effects unconfirmed; do not repeat automatically. Their optional follow-up starts at fresh owned inventory, not a copied stale Control id/generation. Raw causes remain Kernel-local even with verbose; oversized request targets are wholly omitted with explicit coverage under 16 KiB. This presentation/curation does not change the legacy stop engine or prove closure.
+
 `kill` accepts only a currently running owned generation, bypasses actor-local capacity, and creates no synthetic Control. `archive` and `prune` accept only terminal owned Runs. Archive moves the entire Run state directory and leaves a tombstone. Prune removes Run state; declared existing artifacts survive only when `preserve_artifacts` is explicitly true, in which case they are copied to retained artifact storage before removal.
 
+Startup Run cleanup and manual archive/prune share the existing `runs-retention.ts` owner. The seven-day filesystem-age threshold is unchanged; automatic cleanup additionally requires an owned generation, fresh runner ESRCH and the existing lifecycle/reuse and retained native/descendant guards. Unbound, unreadable, replaced or still-fenced state stays retained, including retention containers without Run identity. These checks are not whole-scope native closure proof. Ordinary temp cleanup does not retire Runs.
+
 Long-lived services publish `control-endpoint.json` only when ready:
 
 ```json
@@ -238,6 +262,12 @@ npm run validate
 npm run test:preservation
 ```
 
+`npm run validate` runs the full test suite once, including every conformance suite with the same preload and execution flags. `npm run conformance` remains a standalone targeted subset; aggregate validation does not repeat it after the full suite. An invariant checks cohort inclusion and profile equivalence.
+
+Tests normally mirror `lib/<module>.ts` as `tests/<module>.test.ts`, with related contract groups in that file. `tests/invariants.test.ts` checks the naming boundary and the explicit cross-domain/package exceptions; the preservation rules live in [AGENTS.md](./AGENTS.md).
+
+Standard tests, preservation and conformance preload a fresh temporary default agent directory for each test-runner process, ignoring any operator-supplied agent path. These directories are retained rather than deleted on test-runner exit alone; individual fixtures keep their own explicit cleanup evidence. For direct launcher checks, use `node --import ./tests/test-environment.mjs --experimental-strip-types --test ...`.
+
 The atomic build produces the committed JavaScript runtime used by npm and git installs; `npm run build:check` verifies that `dist/` matches source without rewriting it. Pi can load a TypeScript extension entrypoint, but standalone Node processes cannot type-strip modules under `node_modules`; keeping compiled Run modules preserves process isolation without a runtime TypeScript loader.
 
 See the [documentation index](./docs/README.md), [Run lifecycle](./docs/async-runs.md), and [Recipe library](./docs/recipe-library.md).

package/node_modules/@llblab/pi-actors/dist/index.js

@@ -11,7 +11,7 @@ export default function toolRegistryExtension(pi) {
     if (Paths.isRawExtensionCheckout(import.meta.url)) {
         pi.on("resources_discover", async () => runtime.discoverResources(import.meta.url));
     }
-    pi.on("session_start", async (_event, ctx) => runtime.onSessionStart(ctx));
+    pi.on("session_start", async (event, ctx) => runtime.onSessionStart(ctx, event));
     pi.on("turn_end", (event, ctx) => runtime.onTurnEnd(event, ctx));
     pi.on("agent_settled", async (_event, ctx) => runtime.onAgentSettled(ctx));
     pi.on("context", async (event, ctx) => ({

package/node_modules/@llblab/pi-actors/dist/lib/async-runs.d.ts

@@ -7,8 +7,13 @@ import { type CurrentPolicyProvenance } from "./model-context.ts";
 import * as RunDeliveryLineage from "./run-delivery-lineage.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import { type RunArtifactDeclaration } from "./runs-artifacts.ts";
+import { type RunDescendantLaunchIntent } from "./runs-descendant-launches.ts";
+import { RUN_OUTCOME_PROTOCOL } from "./runs-outcomes.ts";
+import { type RunResultProducer } from "./runs-results.ts";
 import { type RunProcessIdentity } from "./runs-process.ts";
 import * as RuntimeIdentity from "./runtime-identity.ts";
+import { type RunSnapshotReferenceReader } from "./runs-context-exports.ts";
+import * as RunSupervision from "./run-supervision.ts";
 import * as RunsIndex from "./runs-index.ts";
 import * as RunsParentTeardown from "./runs-parent-teardown.ts";
 import { type DeliverRunControlOptions, type DeliverRunControlRequest } from "./runs-control-delivery.ts";
@@ -71,6 +76,9 @@ export type { AsyncRunStatus } from "./runs-status.ts";
 export interface AsyncRunMeta {
     argv: string[];
     createdAt: string;
+    started_at?: string;
+    supervision?: RunSupervision.RunSupervisionState;
+    supervision_provenance?: RunSupervision.ResolvedRunSupervisionPolicy["provenance"];
     cwd: string;
     launch_kind?: AsyncRunLaunchSource;
     launch_source?: AsyncRunLaunchSource;
@@ -86,6 +94,7 @@ export interface AsyncRunMeta {
     run_instance_id: string;
     state_dir: string;
     state_schema: typeof RuntimeIdentity.RUN_STATE_SCHEMA;
+    outcome_protocol?: typeof RUN_OUTCOME_PROTOCOL;
     status: AsyncRunStatus;
     tool?: string;
     template: CommandTemplateValue;
@@ -105,15 +114,43 @@ export interface AsyncRunMeta {
     singleton_recipe_id?: string;
     singleton_values?: Record<string, unknown>;
     transport_context?: Record<string, unknown>;
+    /** Launch-return observation only; never persisted Run truth or a navigation/read capability. */
+    catalog_registration?: Readonly<{
+        state: "unavailable";
+        reason: "catalog_registration_failed";
+    }>;
+    /** Original Kernel-local cause, non-enumerable on the return object and excluded from tool details/JSON. */
+    catalog_registration_error?: unknown;
 }
 export { safeRunId } from "./runs-identity.ts";
 export { resolveArtifactManifest } from "./runs-artifacts.ts";
 export type { RunArtifactDeclaration, RunArtifactManifestEntry, } from "./runs-artifacts.ts";
+export interface AsyncRunAdmissionClock {
+    readonly kind: "run_clock_origin_captured";
+    readonly visibility: "kernel_only";
+    readonly publication: "unpublished";
+    readonly work_started: false;
+    readonly identity: Readonly<{
+        run: string;
+        run_instance_id: string;
+        ownerId?: string;
+    }>;
+    readonly state_dir: string;
+    readonly clock: Readonly<RunSupervision.RunSupervisionClock>;
+    readonly origin: Readonly<RunSupervision.RunSupervisionTimeOrigin>;
+    readonly snapshot_references?: Readonly<RunSnapshotReferenceReader>;
+}
 export interface AsyncRunStartOptions {
     skillContext?: RecipesReferences.ActiveSkillRecipeContext;
+    /** Ordinary fresh launches only: synchronously retain the exact origin; this is not a published/started Run receipt. */
+    onSupervisionClockCaptured?: (event: Readonly<AsyncRunAdmissionClock>) => void;
 }
 export declare function startRun(params: AsyncRunStartParams, cwd: string, options?: AsyncRunStartOptions): AsyncRunMeta;
+/** Kernel-only prepare path: real generation creation, but no native process, workload, launch receipt, or membership authority. */
+export declare function prepareDescendantRunGeneration(parentStateDir: string, producer: RunResultProducer, params: AsyncRunStartParams, cwd: string, options?: AsyncRunStartOptions): Readonly<RunDescendantLaunchIntent>;
 export declare function getRunStatus(runOrDir: string): Record<string, unknown>;
+/** Internal inventory acquisition; direct status and lifecycle readers remain independently scalar. */
+export declare function getRunInventoryStatuses(stateDirs: readonly string[]): (Record<string, unknown> | undefined)[];
 export type { RunStateIndexEntry } from "./runs-index.ts";
 export declare function listRunStateDirs(stateRoot?: string): string[];
 export declare function rebuildRunStateIndex(stateRoot?: string): RunsIndex.RunStateIndexEntry[];