# 0.4.0 — Optional archive of automation-created sessions

## Compatibility

- npm registry latest verified during implementation: `@jmfederico/pi-web@1.202611.0` (`npm view @jmfederico/pi-web version`). Peer/dev baseline is now `^1.202611.0`; the lockfile selects that published release. Node 22.19+ and Pi coding agent ^1.4.0 remain required.
- Server API v5 now requires and resolves public `PI_WEB_HOST_SESSION_LIFECYCLE_CAPABILITY` (`session-lifecycle@1`). Gateways and target machines must be compatible. Only public package entrypoints are used.
- No storage migration beyond existing schema v2 or execution protocol change. Installing this release does not automatically restart a live daemon.

## Behavior and safety

The Archive confirmation has an unchecked **Also archive this automation’s sessions** checkbox. Omitted/false retains sessions unchanged. Browser and companion use the same strict management input: only `archive` accepts optional boolean `archiveSessions` and a continuation cursor `archiveSessionAfter` when opted in.

The automation is archived first using existing revision, workspace authority, and active/unconfirmed-run guards. Scheduling stays paused even if session archiving fails. Session targets come only from distinct, exact non-null identities retained across **all** this automation’s scoped runs and attempts—not session titles, current browser selection, or capped UI history. No children/descendants are discovered or changed. Before each mutation the plugin rereads catalog runtime and lifecycle pin/archive state and rechecks the current archived automation revision. Sessions observed as pinned or busy are skipped; pins are never changed. Pin eligibility is snapshot-based, not atomic: a pin added after the eligibility read cannot prevent this explicit archive command. Strict atomic pin protection would require a conditional host operation. The host’s own busy checks remain authoritative against races. User-resumed sessions are not assumed idle merely because their original run completed.

Each request sequentially processes up to **50 exact sessions**, stopping before the eight-second management deadline with 500ms reply headroom. Each catalog/lifecycle call also has a 750ms ceiling. One checked confirmation automatically traverses all sessions in the browser through additional bounded requests; visible aggregate counts and per-session results are retained across batches. Chat uses the same multi-session traversal: normal fast multi-session operations finish in one invocation, not one session per click/tool call. Only exceptionally large/slow chat operations need continuation because of the real 50-session/time limit, reported with the cursor and optional `stopReason`.

Results distinguish `archived`, `already-archived`, `skipped-pinned`, `skipped-busy`, `failed`, `uncertain`, and `deferred`. `traversalComplete` means this pass reached the end, **not** that all sessions were archived. Per-session failures/uncertainty do not retry or stop other settled, eligible identities. A rejected/timed-out admitted mutation is conservatively **uncertain**, never falsely successful. Timeout, cancellation or a revision/active-work fence stops the pass; a deferred read leaves its cursor unchanged. Browser automatic continuation applies only to size/budget limits with an advancing cursor; it stops on repeated/non-advancing cursors. No infinite automatic retry loop is permitted.

**Stop session archive**, disconnecting the panel, changing machine/workspace, caller cancellation, or plugin disposal prevents new operations and requests, but cannot undo an admitted mutation. Requests are serialized per automation; if an admitted mutation ignores cancellation, retry remains blocked until it settles (or the backend restarts). No loop continues mutating behind a response. A lost response is unconfirmed, not success; previously returned aggregate results remain visible. Unconfirmed-batch warnings (including a lost first reply) survive successful snapshot polling and remain visible until an explicit reconciliation pass finishes; a definition refresh alone cannot confirm session outcomes.

After inspecting a stopped pass, **Continue remaining sessions** resumes traversal. **Archived → Archive sessions / retry** starts one new reconciliation pass for skipped/failed/uncertain sessions, with opt-in unchecked again. Chat can continue a safe partial result with `archiveSessionAfter: sessionArchive.continuationAfter` and the returned definition revision, or omit the cursor to restart/reconcile. Every retry checks current host archive state before mutation, including for already-archived automations. After timeout/cancellation/lost reply inspect first; never silently retry an ambiguous operation. There is no durable operation ledger or background completion after the initiating view/request ends. Panel aggregate results are browser memory only; reload is not a durable receipt.

Saving/restoring the definition never silently restores sessions. **Delete remains definition-only**; permanent session deletion is outside this plugin’s scope. The host supports more lifecycle operations, but this feature uses only `get` and `archive`.

## Upgrade and manual acceptance

Install `@compn3rd/pi-web-automations@0.4.0` as a Pi package, or install the built checkout locally for testing. Keep the companion trusted/enabled. Back up plugin state consistently before any operator-managed upgrade. For the host pin-storage migration, update/restart web/API **before** starting the updated session daemon, then reload the browser. Restarting sessiond interrupts active work/terminals; do it only when safe, from outside hosted sessions. This implementation does not restart anything.

Before deployment, validate on safe local and remote targets: unchecked archive preserves sessions; checked archive changes only eligible exact historical identities; busy/pinned sessions skip; partial failure can be explicitly reconciled from Archived; restore leaves sessions unchanged. Browser tests use happy-dom and host capability mocks, not a live-host visual/remote acceptance run. Historical release notes describe their original baseline and are not the current capability contract.

## Known limitations

Session enumeration currently repeats scoped history queries for each identity and admission fence. Very large histories may traverse slowly; request time limits and bounded automatic continuation still apply. Batch-prefetch optimization is deferred. Live local/remote acceptance remains outstanding; automated host mocks do not establish live deployment acceptance.

## Automated validation

`npm run verify` passed on Node **22.22.2**; release verification after `npm ci --ignore-scripts` also passed with `TMPDIR=/dev/shm` to avoid slow overlay-filesystem SQLite fixture timeouts (no test timeout or assertion changes): typecheck, lint, **273 tests across 16 files**, build, distribution validation, real tarball allowlist validation, and isolated production-only install validation. The install check verifies the new capability requirement/parser and scoped get/archive forwarding without installing host peers or a native SQLite addon. Tests cover exact all-history identities beyond 500 runs, attempt-only identities, local/remote-host mocks, unchecked/reset/checked browser controls, automatic multi-session browser/chat traversal, aggregate partial results and retry, busy/pinned/missing sessions, race rejection, stale/active/unknown guards, cancellation/shutdown, hung reads/mutations and continuation fences. SQLite’s experimental warning and Lit’s test dev-mode notice are expected.