@elpapi42/pi-fleet 0.1.0-beta.1 → 0.1.0-beta.10

package/CHANGELOG.md

@@ -1,5 +1,155 @@
 # Changelog
 
+## Unreleased
+
+## 0.1.0-beta.10 — 2026-07-26
+
+Corrects pi-fleet's execution-ownership boundary: pi-fleet now orchestrates the user's separately installed Pi executable instead of distributing a second managed Pi runtime.
+
+### Changed
+
+- pi-fleet now requires a separately installed Pi and launches the exact Pi executable and Node interpreter selected by the invoking environment. It does not install, bundle, copy, or silently substitute Pi.
+- A runtime whose persisted Pi is unavailable still serves passive inspection, response retrieval, watching, and cleanup; `create`, `send`, and `compact` fail before dispatch.
+- Changed existing service Pi/Node selections fail closed as `runtime_upgrade_deferred` until users finish work and explicitly transition supervision. The beta.9 managed-Pi service follows the same manual transition: uninstall only pi-fleet supervision, then install from the intended Pi environment; state and native sessions remain.
+
+### Added
+
+- Added `pifleet compact NAME [--human]`, backed by Pi's typed native compaction RPC. It restores an absent idle agent when capacity allows, checks authoritative state immediately before invocation, returns bounded token metrics, emits native compaction activity through raw RPC watchers, and never replays ambiguous compaction after a crash. Pi does not currently provide an atomic idle-only compact primitive, so a narrow trusted-extension activity race remains documented.
+
+### Changed
+
+- Replaced `watch` session-file tailing with a live, unfiltered, byte-exact stream of one Pi RPC process incarnation's stdout. Stdout carries only Pi bytes; stderr reports subscription readiness and typed stream failures. Watching remains passive, bounded, and live-only, and never silently concatenates restored process streams.
+
+### Documentation
+
+- Reframed pi-fleet as Pi-native, machine-first execution infrastructure for agent systems operating beyond terminal scale rather than a human-facing background terminal tool.
+- Reworked the README and operator skill around programmatic lifecycle control, exact latest-response retrieval, live Pi RPC JSONL, orchestration boundaries, and user-owned sessions.
+- Clarified that `create` creates an agent whose local name is its stable programmatic address, while its process residency and user-controlled native session remain separate concerns.
+- Removed superseded internal implementation, testing, and release-planning documents to keep repository documentation focused on the README, operator skill, and changelog.
+
+### Reliability
+
+- Added deterministic fault-injection coverage for receive timeout/cancellation, delivery recovery, runtime crashes, Pi RPC failures, SQLite worker/storage failures, protocol framing, command races, raw RPC byte boundaries, and public-error redaction.
+- Serialized create, send, and destroy transitions per agent so cross-command races cannot orphan or resurrect an agent generation.
+- Made SQLite-worker failures terminal for current and future calls and made send recovery safe when an operation exists but no send record was committed.
+- Redacted Pi stderr and unexpected internal exceptions from public errors while retaining stable typed error codes.
+- Contained asynchronous coordinator event/store failures by stopping the affected Pi process and rejecting waiters instead of producing unhandled promise rejections.
+- Added a nightly reliability workflow and an isolated soak suite covering 500 concurrent ordered sends and 100 name lifecycle cycles.
+- Reject invalid UTF-8 in stdin and Pi RPC stdout instead of silently replacing bytes at either protocol boundary.
+- Keep idle agents `idle + absent` after pi-fleet-initiated orderly shutdown even when Pi reports a nonzero exit; active work remains `failed/runtime_interrupted`.
+- Align explicit stdin input with the runtime's 512 KiB message limit and document credential-environment and receive-timeout behavior before the quick start.
+- Install native services without forcing the default persistent state directory into `PIFLEET_STATE_ROOT`, preserving the default split between durable SQLite state and the private runtime socket.
+- Validated systemd user lingering, idle reboot restoration, active reboot interruption without replay, single-writer restoration, and session preservation in a disposable privileged systemd container.
+- Removed Pi from pi-fleet's production dependency and immutable runtime closure, restored a zero-exception production audit for what pi-fleet distributes, and moved real/process/package/CI validation to a separately installed Pi `0.82.1`. The audit does not certify the user's external Pi installation.
+
+## 0.1.0-beta.9 — 2026-07-20
+
+Core product and Linux supervision validation after beta.8.
+
+### Fixed
+
+- An orderly pi-fleet shutdown now leaves idle agents `idle + absent` even if Pi reports a nonzero exit; active interrupted work still becomes `failed/runtime_interrupted` without replay.
+- A clean native-service install no longer forces the default persistent state directory into `PIFLEET_STATE_ROOT`, so the service and ordinary CLI agree on the private runtime socket while SQLite remains in durable state storage.
+- Explicit stdin now uses the runtime's default 512 KiB message boundary instead of accepting a larger payload that the runtime later rejects.
+- Onboarding now explains persistent credential environments before the first operational command and uses explicit receive timeout units.
+
+### Validated
+
+- Reused one real Pi session through the same pi-fleet entry across a service restart and related follow-up assignment with less re-explanation.
+- Proved user lingering, idle PID-1 restart without eager restoration, single-writer session restoration, active restart interruption without replay, explicit recovery, and session preservation in a disposable systemd container.
+
+### Security
+
+- The production audit remains fail-closed except for one deliberate exact exception: managed Pi `0.80.10` currently pins `brace-expansion@5.0.6` affected by local glob-input denial-of-service advisory `GHSA-3jxr-9vmj-r5cp`. The policy verifies the advisory, package versions, and installed path and rejects every additional or changed vulnerability. Upstream tracking is `earendil-works/pi#6882`.
+
+## 0.1.0-beta.8 — 2026-07-20
+
+Publishes the beta.7 manual-testing fixes after its immutable tag failed before npm publication.
+
+### Changed
+
+- The process-tree fixture now waits for both parent and child SIGTERM handlers through an IPC readiness handshake before exposing their PIDs, removing a CI scheduling race while preserving the real escalation assertion.
+- Includes the beta.7 `watch` EPIPE and pre-dispatch restoration-failure fixes; beta.7 itself was never published to npm.
+
+## 0.1.0-beta.7 — 2026-07-20
+
+Continued direct CLI edge-case testing. No intentional command-surface change.
+
+### Fixed
+
+- `watch` now treats downstream `EPIPE` as normal client disconnection, exiting successfully without misreporting a closed output pipe as `invalid_arguments`.
+- A restoration failure proven to occur before prompt dispatch now returns `pi_start_failed`, marks the send definitively failed, leaves the agent `failed + absent`, and releases process capacity instead of claiming `delivery_uncertain` and leaving `restoring + starting` state.
+- Restoration cleanup uncertainty remains fail-closed as `incarnation_cleanup_uncertain` with its process slot retained when pi-fleet cannot prove the spawned process is gone.
+
+### Manual validation
+
+- Exercised active runtime death with held clients, hanging/HTTP-error/malformed providers, 19 MB watch backpressure, stdin limits, Unicode paths, extension UI cancellation, oversized session records, watch pipe closure, and missing-cwd restoration in isolated environments.
+
+## 0.1.0-beta.6 — 2026-07-20
+
+Manual interruption-semantics correction. No intentional command-surface change.
+
+### Fixed
+
+- `receive` now returns the agent's stored failure code when the agent is failed instead of returning an older assistant response as successful completion of interrupted work.
+- Added regression coverage for the exact state observed during manual testing: a previous response exists, later work is interrupted, the Pi process is absent, and immediate receive reports `runtime_interrupted`.
+
+## 0.1.0-beta.5 — 2026-07-20
+
+Release-pipeline reliability follow-up; includes the beta.4 receive and argument-validation fixes.
+
+### Fixed
+
+- On Linux, process-group cleanup now treats zombie processes as exited by inspecting procfs instead of relying only on signal probes. This prevents conservative cleanup waits and CI failures when an orphaned descendant is awaiting reaping.
+- Pi shutdown now waits for the child-process exit callback and coordinator transition before reporting completion, preventing a status read from briefly retaining `resident` after an idle release.
+- Repeated the process-tree and real-Pi process suites five times locally before tagging after beta.4's publish workflow exposed the runner-specific zombie behavior.
+
+## 0.1.0-beta.4 — 2026-07-20
+
+Manual edge-case testing fix. No intentional CLI contract change.
+
+### Fixed
+
+- Prevented `receive --timeout 0` from rejecting an idle waiter before a handler was attached and terminating the runtime with an unhandled `Receive cancelled` rejection.
+- Added explicit coordinator work tracking so promptless/repeated idle polling returns `no_response` or the latest response immediately, while managed work still waits for Pi settlement.
+- Closed the abort-listener registration race and added regression coverage for timeout, disconnect, repeated receive, and settlement ordering.
+- Return durable `invalid_arguments` errors for rejected Pi startup/positional arguments instead of a generic `internal_error`.
+
+### Manual validation
+
+- Direct isolated lifecycle, timeout, repeated receive, raw watch, session mutation, concurrent startup/send, Pi/runtime crash recovery, capacity, and session-preservation scenarios passed against the beta.4 source build.
+- Fresh-registry operational validation remains enforced by the tag workflow after publication.
+
+## 0.1.0-beta.3 — 2026-07-20
+
+Reliability fix for fresh global npm installations. No intentional CLI or agent-lifecycle contract change.
+
+### Fixed
+
+- Replaced the invalid assumption that npm recreates CI's byte-identical `node_modules` tree. Schema-3 runtime manifests retain exact hashes for pi-fleet-owned files, validate direct dependency name/version, derive the observed dependency-closure hash at materialization, and prove source-before, staged, and source-after closure equality before activation.
+- Made immutable runtime release paths closure-specific, so different legitimate npm dependency layouts do not collide.
+- Strengthened package testing to mutate a fresh installed dependency tree, require an operational `list`, remove the npm installation, stop the runtime, and restart through the materialized release.
+
+### Installation scope
+
+- The documented global npm installation layout, where dependencies are package-local, is supported. Arbitrarily hoisted local-prefix, pnpm, and unusual `npx` dependency layouts are not yet supported.
+- The tag workflow now performs a fresh registry-install operational `list` smoke after publishing. That smoke is a release gate and has not yet run for beta.3.
+
+## 0.1.0-beta.2 — 2026-07-20
+
+Reliability-focused beta maintenance release. No intentional product-contract changes.
+
+### Reliability
+
+- Added deterministic fault coverage and reproducible randomized lifecycle-race soak testing.
+- Fixed timeout/cancellation classification, ambiguous-delivery recovery, no-replay behavior, and coordinator/store failure containment.
+- Validated inbound protocol majors, strict and concurrent runtime materialization, and released beta.0/beta.1 CLI-runtime compatibility.
+- Added unclean SQLite `quick_check` validation, redacted error handling, fatal UTF-8 checks, process cleanup coverage, and nightly resource-stability checks.
+
+### Validation limits
+
+- Real disk exhaustion, host logout/reboot, macOS launchd/containment, and multi-hour platform resource soak remain unvalidated.
+
 ## 0.1.0-beta.1 — 2026-07-20
 
 Release-pipeline validation beta. No product-contract changes from `0.1.0-beta.0`.
@@ -11,13 +161,13 @@ Release-pipeline validation beta. No product-contract changes from `0.1.0-beta.0
 
 ## 0.1.0-beta.0 — 2026-07-20
 
-First public beta of Pi Fleet.
+First public beta of pi-fleet.
 
 ### Included
 
 - Seven-command JSON-first CLI: `create`, `send`, `receive`, `status`, `list`, `watch`, and `destroy`.
-- Named resident Pi processes with restore-on-address from native Pi sessions.
-- Exact compatible Pi argument passthrough after `--` and Fleet-owned `--cwd`.
+- Resident Pi processes with stable pi-fleet addresses and restore-on-address from native Pi sessions.
+- Exact compatible Pi argument passthrough after `--` and pi-fleet-owned `--cwd`.
 - Ordered repeated steering input and idle-based latest-assistant response retrieval.
 - Raw live Pi session JSONL watching.
 - SQLite-backed names, latest responses, operation idempotency, and conservative crash recovery.

package/README.md

@@ -1,61 +1,143 @@
-# Pi Fleet
+# pi-fleet
 
-Pi Fleet is a local runtime and machine-first CLI for named, long-lived Pi agents.
+**Pi orchestration beyond terminal scale.**
 
-```text
-create · send · receive · status · list · watch · destroy
+pi-fleet is a local, machine-first runtime for software that orchestrates Pi agents and their native sessions. It provides precise lifecycle control, exact latest-response retrieval, and live raw Pi RPC JSONL without scraping terminals.
+
+**Control execution. Own the session. Build the orchestration above it.**
+
+## Why pi-fleet exists
+
+A terminal pane is useful observability for one Pi agent. It is not an observability model for dozens or hundreds of them.
+
+Terminal multiplexers such as tmux, cmux, and Herdr expose processes, panes, and rendered output. Agent software needs Pi-aware state: whether an agent is working or idle, whether input was accepted, which native session it is using, what its exact latest settled assistant response was, and whether interrupted work can be retried safely.
+
+| Terminal multiplexers (tmux, cmux, Herdr)  | pi-fleet                                   |
+| ------------------------------------------ | ------------------------------------------ |
+| Human-facing panes                         | Machine-readable lifecycle control         |
+| Rendered stdout and scrollback             | Live raw Pi RPC JSONL                      |
+| Last _n_ terminal lines                    | Exact latest settled assistant response    |
+| Generic terminal input                     | Pi-native prompt and steering semantics    |
+| Caller-defined recovery                    | Explicit restoration and failure state     |
+| Human attention as the observability layer | Data for custom observability and analysis |
+
+pi-fleet is specialized for Pi. It gives up bundled terminal UX in exchange for semantic control and data that higher-level systems can reliably consume.
+
+## Infrastructure for orchestration
+
+```mermaid
+flowchart TB
+  callers["Pi extensions · calling agents · orchestrators · AI software factories"]
+  cli["pifleet CLI"]
+  runtime["local pi-fleet runtime"]
+  agent1["Pi agent"]
+  agent2["Pi agent"]
+  agent3["Pi agent"]
+  session1["native user-controlled session"]
+  session2["native user-controlled session"]
+  session3["native user-controlled session"]
+
+  callers --> cli --> runtime
+  runtime --> agent1 --> session1
+  runtime --> agent2 --> session2
+  runtime --> agent3 --> session3
 ```
 
-Fleet keeps a Pi process resident when possible, restores it from the same native Pi session when absent, accepts repeated steering input, and returns the latest assistant message after Pi becomes idle. Pi sessions remain under your control: Fleet references them but never copies or deletes them.
+pi-fleet is infrastructure **for orchestration**, not an orchestration framework. It owns execution lifecycle, process availability, ordered communication, restoration references, exact result retrieval, and explicit failure state.
+
+Callers own roles, task decomposition, scheduling, semantic retries, approval, aggregation, dashboards, notifications, knowledge mining, and autonomy.
 
-> **Beta:** `0.1.0-beta.0` is release-validated on Linux x64 with Pi `0.80.10`. macOS, actual logout/reboot recovery, automatic upgrades, and public service-management UX are not yet release-validated.
+Typical callers include:
 
-## Install
+- an existing agent delegating through the [pi-fleet operator skill](./SKILL.md);
+- a Pi extension coordinating specialized agents;
+- a local service collecting exact results from many Pi agents;
+- an AI software factory implementing its own scheduling and quality gates;
+- observability, audit, or knowledge systems consuming native Pi sessions.
 
-Requirements:
+If your primary requirement is watching one or two agents in terminal panes, a terminal multiplexer such as tmux, cmux, or Herdr will probably fit better. pi-fleet is for builders ready to move control and observability into software.
 
-- Linux x64
-- Node.js `^22.19.0 || ^24.0.0`
-- normal Pi provider credentials and configuration
+## Installation
 
-Install the beta globally:
+pi-fleet currently supports Linux x64 with Node.js `^22.19.0 || ^24.0.0` and a separately installed, compatibility-tested Pi executable. pi-fleet does not install, bundle, copy, or substitute Pi.
 
 ```bash
+command -v pi
+pi --version
 npm install --global @elpapi42/pi-fleet@beta
 pifleet --version
-pifleet list
 ```
 
-`npx @elpapi42/pi-fleet@beta` is suitable for evaluation, but a global installation is recommended for continued use. Fleet materializes a verified runtime independently of the npm installation/cache, and evaluation can leave that runtime and Fleet state behind intentionally.
-
-Pi Fleet includes the tested Pi coding-agent package. It uses your normal Pi configuration, provider credentials, extensions, skills, and project resources. **Do not put API keys or other secrets in CLI arguments:** Fleet persists accepted Pi arguments so it can restore the agent. Use Pi's credential configuration or provider environment variables instead.
+pi-fleet selects the executable `pi` found on the invoking command's `PATH`, together with the `node` selected from that same PATH for Pi shims using `#!/usr/bin/env node`. Use `PIFLEET_PI_EXECUTABLE=/absolute/path/to/pi` only to select an explicit absolute executable; aliases and shell functions are not supported. A registered service persists the selected Pi and Node paths, so switching NVM, fnm, Volta, or a global Pi installation requires an explicit supervision transition rather than silently changing a live runtime.
 
-## Quick start
+Configure normal Pi provider credentials before the first operational command. pi-fleet commands start or reuse a persistent runtime, so environment variables added only to later invocations do not change that runtime's environment. Use normal Pi credential configuration or configure the persistent runtime/service environment.
 
-Create a promptless named agent in the current project:
+## Programmatic quick start
 
 ```bash
-pifleet create reviewer --cwd "$PWD"
+# Create an agent with the stable programmatic address "reviewer".
+pifleet create reviewer --cwd "$PWD" > created.json
+
+# Submit work. While Pi is active, later sends use Pi steering semantics.
+pifleet send reviewer "Review the authentication changes" > accepted.json
+
+# Inspect the agent without restoring an absent Pi process.
+pifleet status reviewer > status.json
+
+# Wait for idle and retrieve the exact latest assistant response.
+pifleet receive reviewer --timeout 10m > result.json
+
+# Stream Pi's live RPC stdout to your own tooling.
+pifleet watch reviewer > pi-rpc.jsonl 2> watch-control.jsonl
 ```
 
-Send work and retrieve the latest assistant message after Pi becomes idle:
+Finite commands emit one compact JSON object on stdout. Expected failures emit one structured JSON error object on stderr. Exit status `0` means success, `1` means error, and receive timeout uses `124`. `watch` reserves stdout exclusively for Pi's raw RPC byte stream and writes pi-fleet readiness or errors to stderr.
+
+`--human` exists as a debugging convenience for the seven finite commands; programmatic callers should use the default JSON output.
+
+## Your sessions are the data layer
+
+**pi-fleet controls execution. You control the session.**
+
+`create` creates an agent: a durable logical resource with a stable local name, a native Pi session, and a managed process lifecycle. Its Pi process may be resident or absent, but the agent remains addressable until `destroy`.
+
+The agent's session is not opaque pi-fleet data. It remains a native, user-controlled resource that can support independent observability, auditing, provenance, search, evaluation, and knowledge mining.
+
+- Use Pi's normal session storage or provide exact paths, IDs, directories, forks, and continuation selectors.
+- pi-fleet records the concrete session selected by Pi only so it can restore and observe execution.
+- pi-fleet never copies, relocates, normalizes, wraps, or deletes session files.
+- `destroy` removes pi-fleet management and its process; it never removes the Pi session.
+- External tools may read or analyze the same session without a pi-fleet-specific data format.
+- Deliberate concurrent writers remain under user control, but they can invalidate restoration guarantees. pi-fleet fails visibly rather than silently taking ownership or substituting a copy.
+
+Pass compatible native Pi selectors after the first literal `--`:
 
 ```bash
-pifleet send reviewer "Review the authentication changes"
-pifleet receive reviewer --human
+# Existing session file
+pifleet create reviewer --cwd /workspace/project -- --session /absolute/session.jsonl
+
+# Exact Pi session ID
+pifleet create reviewer -- --session-id SESSION_ID
+
+# Native first-launch selection
+pifleet create reviewer -- --fork /absolute/source.jsonl
+pifleet create reviewer -- --continue
 ```
 
-Inspect and remove Fleet management:
+`--cwd` is a pi-fleet option and belongs before `--`. Native Pi options belong after it and preserve their token order:
 
 ```bash
-pifleet status reviewer
-pifleet list
-pifleet destroy reviewer
+pifleet create reviewer \
+  --cwd /workspace/project \
+  -- \
+  --session /absolute/session.jsonl \
+  --model anthropic/claude-sonnet-4 \
+  --thinking high
 ```
 
-`destroy` stops Fleet's managed process and removes the Fleet name. It **never deletes the Pi session**.
+Headless `--resume` is unsupported because it requires interactive selection before RPC mode. Positional Pi prompts and `@file` inputs after `--` are rejected; use optional create instructions or `send` so pi-fleet can preserve ordered delivery.
 
-## Commands
+## Pi-aware control primitives
 
 ```text
 pifleet create NAME [INITIAL_INSTRUCTIONS] [--cwd PATH] [--human] [-- PI_OPTIONS...]
@@ -64,138 +146,122 @@ pifleet receive NAME [--timeout DURATION] [--human]
 pifleet status NAME [--human]
 pifleet list [--human]
 pifleet watch NAME
+pifleet compact NAME [--human]
 pifleet destroy NAME [--human]
 ```
 
-Finite commands emit JSON by default. Add `--human` for concise human output. `watch` has no human mode: stdout is only raw, complete records appended to the selected Pi session JSONL.
+| Purpose                | Commands         | Semantics                                                                 |
+| ---------------------- | ---------------- | ------------------------------------------------------------------------- |
+| Create an agent        | `create`         | Assign a stable local name and start Pi, optionally with initial input    |
+| Communicate            | `send`           | Start ordinary work while idle or steer active work at Pi's next decision |
+| Retrieve exact results | `receive`        | Wait for idle and return Pi's latest assistant text                       |
+| Inspect lifecycle      | `status`, `list` | Observe logical and process state without restoring Pi                    |
+| Observe live Pi RPC    | `watch`          | Stream one Pi process incarnation's unfiltered RPC stdout                 |
+| Compact context        | `compact`        | Compact an idle agent with Pi's native compaction RPC                     |
+| Release execution      | `destroy`        | Stop pi-fleet management without deleting the Pi session                  |
 
-Messages can be read explicitly from stdin with `-`:
+Every agent has a local name of 1–63 lowercase letters, digits, or interior hyphens. The name is its stable programmatic address—not a persona, role, or second source of truth.
 
-```bash
-git diff | pifleet send reviewer -
-pifleet create researcher - < instructions.md
-```
+### Send and receive
 
-### Native Pi arguments
+A successful `send` means pi-fleet accepted and ordered the input. It does not mean work completed or guarantee a distinct response. Repeated sends may steer the same active run.
 
-Fleet owns only its small command surface. `--cwd` belongs before the first literal `--`; native Pi options belong after it and retain their token order:
+`receive` waits for Pi to become idle and returns the exact latest assistant text known to pi-fleet. It is non-consuming and intentionally not correlated one-to-one with a particular send. This is semantic result retrieval, not terminal scrollback.
 
-```bash
-pifleet create reviewer \
-  --cwd /workspace/project \
-  -- \
-  --session /absolute/path/to/session.jsonl \
-  --model anthropic/claude-sonnet-4 \
-  --thinking high
-```
+`--timeout 0` polls immediately. Use explicit durations such as `30s`, `5m`, or `1h`; unitless values are milliseconds. Timeout never cancels Pi work, and canceling a held receive affects only that client.
 
-Supported native session selection includes:
+Use explicit stdin for large or shell-sensitive input. pi-fleet never consumes piped stdin implicitly. Input must be valid, nonempty UTF-8 and is limited to 512 KiB by default.
 
 ```bash
-pifleet create existing -- --session /path/to/session.jsonl
-pifleet create exact-id -- --session-id SESSION_ID
-pifleet create forked -- --fork /path/to/source.jsonl
-pifleet create latest -- --continue
+git diff | pifleet send reviewer -
+pifleet create researcher - --cwd "$PWD" < instructions.md
 ```
 
-Pi interprets these options directly. An existing or missing `--session` path follows native Pi behavior, and an exact `--session-id` remains exact. Fleet records the concrete selected session only so later process restoration reopens the same conversation. Headless `--resume` is not supported because it requires interactive selection before RPC mode.
+### Lifecycle and recovery
 
-Positional Pi prompts and `@file` inputs after `--` are rejected; use Fleet's optional create instructions or `send` so input remains ordered.
+`compact` is an explicit process-starting action for an idle absent agent. It restores the exact native session when capacity allows, then uses Pi's typed compaction RPC and returns bounded token metrics. It checks authoritative Pi state immediately before invocation and refuses observed active, queued, restoring, or already-compacting work. Pi does not provide an atomic idle-only compact operation, so trusted extension activity beginning in the narrow interval after that check can still encounter Pi's native abort-first compaction behavior. During compaction the agent is not idle; `receive` waits, and `watch` streams Pi's native `compaction_start`, `compaction_end`, command response, and any other RPC stdout unchanged. Treat `compaction_uncertain` as potentially applied and never retry it automatically.
 
-## Communication semantics
+An idle agent's Pi process normally remains resident. If the process is absent, a later `send` restores the agent from its concrete native session when safe. `status`, `list`, `watch`, and retrieval of an already settled response do not restore the process.
 
-`send` uses Pi's normal context-sensitive prompt operation with steering behavior:
+Inspect failed state before deciding what the orchestrator should do:
 
-- while Pi is active, input is queued as steering;
-- while Pi is idle, input begins normal work;
-- repeated sends are accepted in order;
-- acknowledgement means Pi accepted/queued the input, not that it completed or produced a distinct response.
+- `runtime_interrupted` means active work stopped and was not silently replayed.
+- `delivery_uncertain` means Pi may have received the input; replay could duplicate tool side effects.
+- `incarnation_cleanup_uncertain` means pi-fleet cannot prove an old process writer is gone.
+- `session_unavailable` or `session_ambiguous` means continuity cannot safely be claimed.
 
-`receive` deliberately has no per-send response correlation:
+A new explicit send is new work, not evidence that uncertain earlier work did nothing. Semantic retry policy belongs to the calling orchestrator.
 
-- while Pi is busy or restoring, it waits for Pi to become idle;
-- once idle, it returns Pi's latest assistant message;
-- when already idle, it returns immediately;
-- with no assistant message, it returns `no_response`;
-- `--timeout 0` performs an immediate poll;
-- timing out does not cancel or change Pi.
+### Live raw Pi RPC stream
 
-## Sessions and `watch`
+`watch` is a live, byte-faithful copy of one Pi RPC process incarnation's stdout from attachment until that process exits. It forwards every byte without parsing, filtering, aggregation, normalization, or reserialization. That includes command responses, text and thinking deltas, tool-call deltas, tool execution, lifecycle, queue, retry, compaction, extension UI, unknown future records, and even malformed or partial output exactly as Pi emitted it.
 
-Pi and you own session files, IDs, locations, creation, migration, and deletion. Fleet never copies, relocates, or deletes them.
+The stream is live-only: it has no history or replay. A resident agent attaches immediately to future bytes. An absent idle agent remains unwoken and the watcher waits for its next incarnation, binding before startup RPC traffic. Once bound, the watcher ends with that incarnation and never silently concatenates a restored process.
 
-```bash
-pifleet watch reviewer > live-session.jsonl
-```
+Stdout contains only Pi bytes. Stderr emits one `watch.ready` JSON record after atomic subscription registration and carries any later pi-fleet error. Private transport may split or coalesce chunks, so clients must treat concatenated bytes as authoritative and buffer through LF themselves when parsing JSONL. A lagging watcher fails with `watcher_lagged` without blocking Pi or healthy watchers.
 
-`watch` is live-only. For an existing file it begins at the current EOF; for a not-yet-materialized file it waits and begins at byte zero. It does not emit Fleet wrappers, history, or transient RPC events. Concurrent external rewrites can invalidate tailing; detectable replacement, truncation, lag, or runtime loss is reported on stderr.
+## Runtime, data, and maintenance
 
-## Runtime and local data
-
-The short-lived CLI connects to one private per-user runtime. On first operational use, Fleet verifies and materializes an immutable runtime release, then starts it in the background. A registered native service is preferred when present; service management is experimental and is not part of the seven-command beta interface.
+The short-lived CLI connects to one private per-user runtime. On first operational use, pi-fleet verifies and materializes an immutable runtime release, then starts it in the background. A registered native service is preferred when present; service management remains experimental and outside the public beta command interface.
 
 Linux defaults:
 
 ```text
-Fleet state:       ~/.local/state/pi-fleet/
-Materialized code: ~/.local/share/pi-fleet/releases/
-Runtime socket:    $XDG_RUNTIME_DIR/pifleet-$UID/control.sock
-                   (or the system temporary directory when XDG_RUNTIME_DIR is absent)
-Pi sessions:       Pi's normal ~/.pi storage or the exact path you selected
+pi-fleet state:  ~/.local/state/pi-fleet/
+Materialized:    ~/.local/share/pi-fleet/releases/
+Runtime socket:  $XDG_RUNTIME_DIR/pifleet-$UID/control.sock
+                 (or the system temporary directory without XDG_RUNTIME_DIR)
+Pi sessions:     Pi's normal ~/.pi storage or the exact selected path
 ```
 
-`PIFLEET_STATE_ROOT` and `PIFLEET_APPLICATION_ROOT` can override Fleet-owned locations. A CLI invocation whose state root differs from an installed service fails immediately with repair guidance instead of connecting to the wrong database.
+`PIFLEET_STATE_ROOT` and `PIFLEET_APPLICATION_ROOT` override pi-fleet-owned locations. A CLI whose state root differs from an installed service fails with repair guidance rather than connecting to the wrong database. If a persisted Pi later disappears or becomes incompatible, the runtime still serves passive `status`, `list`, stored `receive`, `watch`, and `destroy`; only `create`, `send`, and `compact` fail before Pi dispatch.
+
+A service whose persisted Pi or Node selection differs from the terminal selection rejects new work with `pi_service_mismatch`. Automatic replacement is deliberately fail-closed as `runtime_upgrade_deferred`: finish work, stop/remove only pi-fleet supervision with the installer `uninstall`, then run installer `install` from the environment selecting the intended Pi. This preserves pi-fleet state and every native Pi session. The beta.9 managed-Pi service requires this same explicit transition; pi-fleet never kills or replaces it automatically.
 
-## Uninstall and recovery
+`npx @elpapi42/pi-fleet@beta` is suitable for evaluation; global installation is recommended for continued use. pi-fleet materializes its runtime independently of the npm cache or installation, so evaluation can leave runtime and state behind.
 
-Before uninstalling, destroy agents you no longer want Fleet to manage:
+Before uninstalling, destroy agents you no longer want pi-fleet to manage:
 
 ```bash
-pifleet list --human
-pifleet destroy AGENT_NAME
+pifleet list
+pifleet destroy NAME
 npm uninstall --global @elpapi42/pi-fleet
 ```
 
-Removing the npm package does not delete Pi sessions, Fleet's SQLite state, materialized runtime releases, or an already-running runtime/service. This protects durable agents from package-manager changes. Reinstalling the same or a compatible version reconnects to the preserved state.
+Removing the npm package does not delete Pi sessions, pi-fleet SQLite state, materialized releases, or an already-running runtime/service. Reinstalling a compatible version reconnects to preserved state. There is no automatic self-update, telemetry, remote transport, or npm `postinstall` service registration. Database migrations are forward-only; reinstalling an older binary is not database rollback.
 
-There is intentionally no automatic self-update, telemetry, remote transport, or npm `postinstall` service registration. Database migrations are forward-only; installing an older binary after a newer schema migration is not a supported rollback strategy.
+## Beta status
 
-For support, include:
+Beta.9 historically shipped a managed Pi `0.80.10`. Current source has removed Pi from pi-fleet's package and immutable runtime, and has compatibility evidence for the terminal-selected Pi `0.82.1`; this correction is not published until its supervised-runtime and fresh-registry gates pass.
 
-```bash
-node --version
-pifleet --version
-pifleet list
-pifleet status AGENT_NAME
-```
-
-Do not include API keys, message contents, session contents, or private paths unnecessarily. Report reproducible issues at <https://github.com/elpapi42/pi-fleet/issues>.
+Known limits:
 
-## Beta limitations
+- Linux x64 is the only validated support target. Arbitrarily hoisted local-prefix, pnpm, and unusual `npx` dependency layouts are unsupported.
+- Disposable systemd/PID-1 restart and user-lingering recovery are validated; a full host logout and kernel reboot are not.
+- macOS launchd and descendant containment, real disk exhaustion, and multi-hour resource growth remain unvalidated.
+- Runtime upgrades are not automatic, and active runtimes are not silently replaced.
+- Raw RPC watch is live-only: it provides no replay and ends with its Pi process incarnation.
+- A promptless missing session path can remain unmaterialized until Pi writes conversation content, following native Pi behavior.
+- Existing beta.9 releases include managed Pi `0.80.10` and its historical audit exception. Current source requires zero known vulnerabilities in pi-fleet's own production closure. That audit does not certify the separately installed Pi's dependency posture.
 
-- Release validation currently covers Linux x64 only.
-- Actual logout and host reboot recovery remain unvalidated.
-- launchd and macOS descendant containment remain unvalidated.
-- Native service install/repair/uninstall exists internally but has no supported public UX yet.
-- Runtime upgrades are not automatic; active runtimes are not silently replaced.
-- Session tails cannot promise exactly-once behavior under arbitrary external mutation.
-- A promptless missing session path may remain physically unmaterialized until Pi writes conversation content, following native Pi behavior.
+For support, include `node --version`, `pifleet --version`, `pifleet list`, and `pifleet status NAME`. Never include API keys, message contents, session contents, or private paths unnecessarily. Report reproducible issues at <https://github.com/elpapi42/pi-fleet/issues>.
 
 ## Development
 
 ```bash
 npm ci
+npm run audit:production
 npm run typecheck
 npm run lint
 npm run format:check
 npm test
+npm run test:faults
 npm run build
 npm run test:package
 npm run test:platform
+npm run test:soak
 ```
 
-See [`IMPLEMENTATION_PLAN.md`](./IMPLEMENTATION_PLAN.md) for architecture, completed evidence, and remaining release gates.
-
 ## License
 
 MIT © elpapi42

package/bin/pifleet-runtime.mjs

@@ -6,7 +6,7 @@ const isSupported = (major === 22 && minor >= minimumNode22Minor) || major === 2
 
 if (!isSupported) {
   process.stderr.write(
-    `Pi Fleet runtime requires Node ^22.19.0 or ^24.0.0; found ${process.versions.node}. Run the installer repair operation with a supported Node executable.\n`,
+    `pi-fleet runtime requires Node ^22.19.0 or ^24.0.0; found ${process.versions.node}. Run the installer repair operation with a supported Node executable.\n`,
   );
   process.exitCode = 1;
 } else {