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

package/CHANGELOG.md

@@ -1,5 +1,182 @@
 # Changelog
 
+## 0.1.0-beta.13 — 2026-07-27
+
+Makes local programs first-class pi-fleet clients: a supported TypeScript SDK plus continuous, replayable semantic receive over shared per-user agents. This beta replaces the previous receive and watch contracts and resets pi-fleet-owned state.
+
+### Added
+
+- Added the side-effect-free `@elpapi42/pi-fleet/client` TypeScript SDK inside the existing package, with direct client methods, UUID-bound agent handles, steering and follow-up input, generated declarations, stable content-safe errors, and continuity-safe receive reconnection.
+- Added durable semantic receive with initial and event cursors and exactly six lifecycle types: thinking, assistant-message, and tool-execution started/finished.
+- Added byte-faithful durable Pi stdout journaling, bounded replay, content-free storage diagnostics, passive WAL checkpointing, and bounded incremental reclamation.
+
+### Changed
+
+- Replaced idle-gated latest-response receive with a continuous passive semantic event stream. CLI `receive --until-idle` is now the explicit live one-off projection; historical replay uses `--after` or `--from-start`.
+- Added `send --follow-up`; steering remains the default. Follow-up delivery is best effort: Pi queues
+  follow-up input only for a run already in flight, so idle follow-up input is delivered as an ordinary
+  prompt, and input accepted while a turn is ending may be queued against a run that never resumes.
+- Bound every SDK handle, CLI invocation, durable operation, send, incarnation, cursor, and recovery path to the immutable agent creation UUID so same-name recreation cannot inherit stale work.
+- Made durable recording fail closed and require explicit continuation after an unclean-runtime observation gap.
+- Limited this release scope to Linux x64 with external Pi 0.82.1.
+
+### Removed
+
+- Removed the public raw `watch` command and its protocol, limits, errors, and compatibility shims.
+- Removed finite latest-assistant-response retrieval and the old latest-response storage model.
+
+### Upgrade note
+
+- This beta transition transactionally resets all prior pi-fleet-owned agents, operations, responses, and journal state without deleting native Pi session files. Stop old supervision and prove the old runtime and Pi process trees absent before activation. After the reset, older binaries are not a supported rollback path.
+
+## 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 +188,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,201 +1,199 @@
-# 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 local, Pi-native execution infrastructure for programs that coordinate long-lived Pi agents. It keeps one shared per-user pool reachable through a TypeScript SDK and a JSON-first CLI while every native Pi session remains under the user's control.
 
-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.
+**Control execution. Own the session. Build the orchestration above it.**
 
-> **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.
+## Why pi-fleet exists
 
-## Install
+Terminal multiplexers such as tmux, cmux, and Herdr are useful for human-facing panes. Programmatic orchestration needs different primitives: stable agent addresses, immutable generation identity, ordered steering or follow-up input, process and recovery state, replayable high-level activity, and explicit uncertainty after a crash.
 
-Requirements:
+pi-fleet supplies those execution primitives. It does not define roles, workflows, schedules, dashboards, semantic retries, memory policy, or autonomy. Agents act only on explicit instructions unless a higher layer implements its own bounded policy.
 
-- Linux x64
-- Node.js `^22.19.0 || ^24.0.0`
-- normal Pi provider credentials and configuration
+## Requirements and installation
 
-Install the beta globally:
+The current support target is **Linux x64**, Node.js `^22.19.0 || ^24.0.0`, and a separately installed **Pi 0.82.1** executable. pi-fleet launches the Pi selected by the invoking environment; it never bundles, copies, or substitutes Pi.
 
 ```bash
+command -v pi
+pi --version # 0.82.1
 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 resolves `pi` and `node` from the invoking `PATH` and persists their absolute selected paths for supervised startup. `PIFLEET_PI_EXECUTABLE=/absolute/path/to/pi` is an advanced override. Shell aliases and functions are unsupported.
 
-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.
+Configure provider credentials before starting the persistent runtime. Environment variables added only to later commands do not change an already-running runtime.
 
-## Quick start
+## TypeScript SDK
 
-Create a promptless named agent in the current project:
+The SDK ships in the same npm package as the CLI and runtime:
 
-```bash
-pifleet create reviewer --cwd "$PWD"
-```
+```ts
+import { connectPiFleet } from "@elpapi42/pi-fleet/client";
 
-Send work and retrieve the latest assistant message after Pi becomes idle:
+const fleet = await connectPiFleet();
+const reviewer = await fleet.create({
+  name: "reviewer",
+  cwd: process.cwd(),
+  instructions: "Review the current change.",
+});
 
-```bash
-pifleet send reviewer "Review the authentication changes"
-pifleet receive reviewer --human
-```
+const events = await reviewer.receive(); // live from attachment
+console.log("attached at", events.cursor);
 
-Inspect and remove Fleet management:
+await reviewer.send("Focus on lifecycle races."); // steering by default
+await reviewer.send("Then check documentation.", { delivery: "followUp" });
 
-```bash
-pifleet status reviewer
-pifleet list
-pifleet destroy reviewer
+for await (const event of events) {
+  if (event.type === "assistant.message.finished") {
+    console.log(event.text);
+  }
+}
 ```
 
-`destroy` stops Fleet's managed process and removes the Fleet name. It **never deletes the Pi session**.
+`connectPiFleet()` connects to the shared per-user control plane; it does not create a private pool. Agents created through one SDK client are immediately addressable by other SDK clients and the CLI. `client.close()` closes only that client's local resources and receive streams—it never stops the runtime or shared agents.
 
-## Commands
+Use `connectPiFleet({ autoStartRuntime: false })` when another process owns control-plane startup; connecting still verifies the runtime is reachable and protocol-compatible, so it fails with `runtime_unavailable` when nothing is running and `protocol_incompatible` against an older runtime, which is left untouched. Imports are inert, and passive operations remain available when Pi is missing; Pi is validated only for `create`, `send`, and `compact`.
 
-```text
-pifleet create NAME [INITIAL_INSTRUCTIONS] [--cwd PATH] [--human] [-- PI_OPTIONS...]
-pifleet send NAME MESSAGE [--human]
-pifleet receive NAME [--timeout DURATION] [--human]
-pifleet status NAME [--human]
-pifleet list [--human]
-pifleet watch NAME
-pifleet destroy NAME [--human]
-```
+### Agent handles and input
 
-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.
+`client.create()` and `client.get()` return remote `Agent` handles; `client.list()` returns lightweight summaries for discovery. A handle carries both the reusable friendly name and the immutable creation UUID, so an old handle cannot retarget a later same-name recreation.
 
-Messages can be read explicitly from stdin with `-`:
+`agent.send()` means durable acceptance and ordering, not task completion or one-send/one-response correlation.
 
-```bash
-git diff | pifleet send reviewer -
-pifleet create researcher - < instructions.md
-```
+- `delivery: "steer"` is the default and matches ordinary Pi prompt/steering behavior.
+- `delivery: "followUp"` asks Pi to queue input until it finishes current work. Pi only queues
+  follow-up input for a run that is already in flight, so pi-fleet delivers follow-up input to an
+  authoritatively idle session as an ordinary prompt instead. Follow-up delivery is therefore best
+  effort: input accepted in the narrow window while a turn is ending may be queued against a run
+  that never resumes, and no later turn will carry it. Use `steer` when delivery must be certain.
+- Cancellation stops only the caller's wait; it does not cancel accepted remote work.
 
-### Native Pi arguments
+### Continuous receive
 
-Fleet owns only its small command surface. `--cwd` belongs before the first literal `--`; native Pi options belong after it and retain their token order:
+`agent.receive()` is a passive broadcast stream and never wakes or restores Pi. Any number of consumers may attach independently.
 
-```bash
-pifleet create reviewer \
-  --cwd /workspace/project \
-  -- \
-  --session /absolute/path/to/session.jsonl \
-  --model anthropic/claude-sonnet-4 \
-  --thinking high
+```ts
+await agent.receive(); // live from invocation
+await agent.receive({ after: cursor }); // replay strictly after a cursor, then follow live
+await agent.receive({ fromStart: true });
 ```
 
-Supported native session selection includes:
+The returned stream exposes its initial opaque `cursor` before its first event. Each event has its own stable ID and cursor; lifecycle pairs share an activity ID. Delivery is at-least-once after reconnect, so consumers should checkpoint cursors and deduplicate by event ID.
 
-```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
-```
+The public event model contains exactly six types:
 
-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.
+- `assistant.thinking.started` / `assistant.thinking.finished`
+- `assistant.message.started` / `assistant.message.finished`
+- `tool.execution.started` / `tool.execution.finished`
 
-Positional Pi prompts and `@file` inputs after `--` are rejected; use Fleet's optional create instructions or `send` so input remains ordered.
+There are no public deltas, raw RPC frames, turn events, retry events, or synthetic gap events. Starts mean pi-fleet durably observed meaningful activity begin. A crash may leave a start unmatched; pi-fleet never invents a finish.
 
-## Communication semantics
+After an unclean runtime death that may have left any Pi incarnation alive—even a logically idle one—old streams stop at their last safe cursor with `observation_uncertain`. The error provides the last-safe cursor and, when available, an explicit continuation cursor. Crossing that gap is a caller decision; pi-fleet never bridges it silently.
 
-`send` uses Pi's normal context-sensitive prompt operation with steering behavior:
+## CLI
 
-- 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.
+The CLI is a shell adapter over the same shared agents and semantic client contract:
 
-`receive` deliberately has no per-send response correlation:
+```text
+pifleet create NAME [INITIAL_INSTRUCTIONS] [--cwd PATH] [--human] [-- PI_OPTIONS...]
+pifleet send NAME MESSAGE [--follow-up] [--human]
+pifleet receive NAME [--after CURSOR | --from-start] [--until-idle] [--human]
+pifleet status NAME [--human]
+pifleet list [--human]
+pifleet compact NAME [--human]
+pifleet destroy NAME [--human]
+```
+
+Finite commands emit one compact JSON object on stdout. Expected failures emit one structured JSON error on stderr. `receive` emits semantic event JSONL on stdout and one readiness record with the initial cursor on stderr. Downstream EPIPE is a successful caller disconnect.
 
-- 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.
+Normal `receive` stays open across work, idle periods, absent Pi processes, and same-agent restorations. `--until-idle` is a CLI-only live convenience: it atomically attaches, emits subsequent events through the exact durable idle boundary, and exits. If the agent is already idle at attachment it exits successfully with no historical output. Historical modes cannot be combined with `--until-idle`.
 
-## Sessions and `watch`
+The former raw `watch` command and finite latest-response receive contract were removed during the beta cutover. Use semantic `receive`; inspect native Pi sessions directly when raw session history is required.
 
-Pi and you own session files, IDs, locations, creation, migration, and deletion. Fleet never copies, relocates, or deletes them.
+## Native sessions remain yours
+
+`create` assigns a stable local address to a Pi agent and its native session. The process may be resident or absent; the logical agent remains addressable until `destroy`.
+
+- Native selectors after the first literal `--` are passed to Pi in their original order.
+- Exact `--session`, `--session-id`, `--session-dir`, `--fork`, and `--continue` choices remain authoritative.
+- pi-fleet never copies, relocates, normalizes, wraps, or deletes session files.
+- `destroy` stops execution ownership and logically deletes pi-fleet-owned control, journal, and semantic history for that agent UUID while preserving the native session; only a minimal content-free idempotency receipt may remain.
+- Deliberate concurrent native-session writers remain possible at the user's risk.
 
 ```bash
-pifleet watch reviewer > live-session.jsonl
+pifleet create reviewer --cwd /workspace/project -- --session /absolute/session.jsonl
 ```
 
-`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.
+`--cwd` is a pi-fleet option before `--`; Pi options come after it. Headless `--resume` and Pi positional prompts are unsupported.
 
-## Runtime and local data
+## Persistence, privacy, and failure
 
-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.
+pi-fleet durably stores every complete LF-terminated Pi RPC stdout record byte-for-byte before parsing it or exposing derived receive events. This private journal can contain prompts, thinking, tool input/output, paths, extension data, and secrets emitted by Pi. It is retained for the logical agent's lifetime and removed by successful `destroy` as a logical SQLite deletion. pi-fleet does not claim immediate file shrinkage or forensic erasure from WAL files, freelist pages, backups, snapshots, or physical media.
 
-Linux defaults:
+Storage failure is fail-closed: affected work stops, receive ends at the last durable cursor, committed history is preserved, and pi-fleet never bridges an unrecorded gap. Operational diagnostics contain counts, sizes, ages, health, and UUIDs—not retained payloads or paths.
 
-```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
-```
+`status` and `list` are passive. An idle agent may be `resident` or `absent`; a later work operation restores an absent process from the concrete native session when safe. Treat `delivery_uncertain`, `compaction_uncertain`, `runtime_interrupted`, `incarnation_cleanup_uncertain`, and session failures conservatively. Semantic retry policy belongs to the orchestrator.
 
-`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.
+## Destructive beta transition
 
-## Uninstall and recovery
+This release intentionally resets all prior pi-fleet-owned agent, operation, response, and journal state when upgrading the old schema. Native Pi session files are preserved. There is no compatibility alias for raw `watch` or finite receive.
 
-Before uninstalling, destroy agents you no longer want Fleet to manage:
+Before the new runtime opens the old database:
 
-```bash
-pifleet list --human
-pifleet destroy AGENT_NAME
-npm uninstall --global @elpapi42/pi-fleet
-```
+1. Finish work on the old runtime.
+2. Stop and uninstall only pi-fleet supervision with `dist/installer.mjs uninstall`.
+3. Prove the old runtime and Pi process trees are absent.
+4. Install supervision from the environment selecting the intended Pi and Node with `dist/installer.mjs install`.
+5. Start the new runtime; no old agents are restored automatically.
 
-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.
+A responsive older runtime is never killed or replaced automatically. After the destructive schema reset, reinstalling beta.10 or another older binary is **not** rollback; use a forward fix or an externally managed pre-reset state backup. User-owned native sessions remain untouched throughout.
 
-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.
+## Runtime locations and service behavior
 
-For support, include:
+Linux defaults:
 
-```bash
-node --version
-pifleet --version
-pifleet list
-pifleet status AGENT_NAME
+```text
+State:       ~/.local/state/pi-fleet/
+Releases:    ~/.local/share/pi-fleet/releases/
+Socket:      $XDG_RUNTIME_DIR/pifleet-$UID/control.sock
+Pi sessions: Pi's normal ~/.pi storage or the exact selected path
 ```
 
-Do not include API keys, message contents, session contents, or private paths unnecessarily. Report reproducible issues at <https://github.com/elpapi42/pi-fleet/issues>.
+`PIFLEET_STATE_ROOT` and `PIFLEET_APPLICATION_ROOT` override pi-fleet-owned paths. State, database, WAL, SHM, socket, and immutable-release paths are private and fail closed on unsafe ownership, type, or symlink conditions.
+
+A service whose selected Pi or Node differs from the terminal environment returns `pi_service_mismatch` or `runtime_upgrade_deferred`; it is not silently rewritten. Global installation is recommended for continued use; `npx` is suitable for evaluation only.
 
-## Beta limitations
+## Scope and known limits
 
-- 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.
+- Linux x64 is the only current release target.
+- Pi 0.82.1 is the current compatibility target.
+- macOS, host logout/reboot, real disk exhaustion, and multi-hour resource behavior require separate validation.
+- pi-fleet has no workflow engine, scheduler queue, idle-process eviction, remote transport, telemetry, automatic semantic retry, or automatic service upgrade.
+- A promptless missing session path may remain unmaterialized until Pi writes conversation content.
+
+For support, include `node --version`, `pi --version`, `pifleet --version`, `pifleet list`, and `pifleet status NAME`. Do not include credentials, messages, thinking, tool payloads, session contents, cursors, or private paths unnecessarily.
 
 ## 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:client-types
 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 {