# 0.2.0 — Public host APIs, scoped management and runtime SQLite

## Compatibility

- Node.js **22.19.0 or newer**; Node 22.19 and 24 are the CI matrix.
- PI WEB **`^1.202610.9`**, browser and server API **v5**, including `catalog@1`.
- Pi coding agent **`^1.4.0`**.
- Older hosts are unsupported. The minor version reflects the raised baseline and removal of the old management protocol. The SQLite schema remains version 1.

## Changes

- Browser and chat mutations use one workspace-authorized management implementation, retaining expected-revision checks, exact cancellation identities, machine attribution and successful-test-before-enable.
- Chat uses the public host companion backend transport per invocation. No browser-established binding, heartbeat, open tab or custom management request/reply plumbing remains. Execution messaging is deliberately separate and retained.
- Registered project/workspace discovery includes empty workspaces. New drafts can select an exact catalog target; saved definitions keep their original target. Chat lists exact IDs and requires them when the current cwd has no unique catalog match. Discovery never grants execution authority: the backend re-resolves targets before reads and mutations.
- The chat tool is deferred and discoverable with concise tool-search guidance.
- Node's built-in `node:sqlite` replaces `better-sqlite3`. Croner is the only direct runtime dependency. Existing schema-v1 definitions, history, revisions, fixed policies, partial usage and unknown-work blocking remain usable without export/import.
- Public host helpers are bundled in server/companion/chat-tool output. Managed production-only installs still work without separately installing the host peers.
- GitHub Actions verifies a matching stable tag on main history, runs the Windows/Linux and Node 22.19/24 CI matrix, and publishes a checksummed verified tarball with OIDC and provenance. See [publishing setup](../publishing.md).

## Execution contract retained

The published `sessions.run()` contract lacks run-attributed cancellation, partial usage/cost totals and a preparation-before-prompt hook. Automations therefore retains its correlated `sessions.create()` runner and companion protocol rather than dropping safeguards. See the [assessment](../migration.md#host-runner-decision).

Drafts start disabled. Edits pause schedules and require retesting. Same-automation overlap is prevented; unconfirmed work persistently blocks the definition, including after edits/restart. Fixed model/thinking requests never silently fall back. Cancellation and timeout are cooperative and task-attributed, not force-stop guarantees. History remains retained; usage is partial assistant-message accounting. User-owned sessions are not exclusive execution leases.

## Upgrade safely

1. Verify compatible Node, PI WEB and Pi installations on gateway and execution targets. Mixed host revisions are unsupported.
2. Inspect active work. Back up SQLite safely (including WAL considerations) before an operator-controlled upgrade. Do not copy/replace a live database or run two schedulers against copied enabled definitions.
3. Install `@compn3rd/pi-web-automations@0.2.0` as a **Pi package**, trust/enable the bundled companion and enable the Automations plugin.
4. Apply server changes only at a safe, operator-controlled daemon restart, then reload the browser. Restarting interrupts sessions and terminals. No restart or live-state migration is performed by build/release checks.
5. Inspect retained definitions/history, save a disabled test draft, test successfully, then enable its exact revision. Inspect unknown work in Sessions rather than attempting to bypass its block.

Schema-v1 state stays in the supplied plugin `dataDirectory`. Fork-era directory relocation remains a separate operator-managed procedure; see [migration guidance](../migration.md#existing-state-staged-migration-only).

## Verification and limits

Local verification on Windows / Node 24.20.0 against published PI WEB 1.202610.9 and Pi 1.4.0 passed typecheck, lint, **125 tests across 14 files**, build, public-import validation, real tarball allowlist validation and a clean production-only install without host peers or native SQLite. The same 125 tests, emitted import validation and production-only tarball install/store smoke passed on minimum Node 22.19.0. A real synthetic better-sqlite3-created 0.1.2 fixture covers retained state. Node may emit an experimental SQLite warning.

Tests cover empty catalog targets, target authorization, ambiguous defaults, stale discovery fencing, editor target selection, shared mutation revisions/cancellation IDs, explicit failures and retained execution safeguards. These are isolated checks, not a hosted end-to-end or federation test of this host pair. Historical hosted checks in the migration report must not be read as new release evidence. Consult the tagged workflow for hosted CI and publication results; release preparation alone does not establish publication.