@maolon/pi-watcher 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/). Before 1.0, minor versions may break.
+
+## [0.1.0] - Unreleased
+
+First public release.
+
+### Added
+- `watcher` tool with `watch-file`, `watch-check`, `register`, `list`, `inspect`, `check`, `pause` and `close`.
+- `/watcher` command: status panel and local episode acknowledgement.
+- Deterministic hard rules: explicit terminal states, business deadlines (raised once per checkpoint), silence detection and result cards.
+- Optional semantic review via Jev (`semanticMode: shadow | active`). Credentials come from Pi's model registry (`/login` → TypeSafe, `TYPESAFE_API_KEY`, or another Jev provider) or `JEV_API_KEY`. Egress needs separate user consent: `/watcher jev consent on` or `JEV_CONSENT=1`.
+- `/watcher jev` status command.
+- Relay-delivered wakes through `@maolon/pi-relay` managed delivery: one scope per watch, durable control outbox, withdraw on pause/close with per-route results, and an idempotent host-response pump.
+- `pi-watcher` CLI: `doctor`, `qualify`, `relay-setup`, plus `producer`/`demo` fixtures.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maolon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,256 @@
-# Temporary Holding Version
+# pi-watcher
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Watch long-running work from [Pi](https://pi.dev) without babysitting it. pi-watcher tracks builds, test runs,
+training jobs, CI pipelines and deadlines from durable evidence. It keeps the session quiet while things progress
+and wakes the session (through [pi-relay](https://github.com/Maolon/pi-relay)) only when a fact needs a decision.
+
+```bash
+pi install npm:@maolon/pi-relay      # wake transport (recommended, see "pi-relay" below)
+pi install npm:@maolon/pi-watcher
+```
+
+## Why
+
+An agent that waits on a long task usually polls: `sleep`, re-run a status command, repeat. Each check spends a
+model turn and grows the context just to learn "still running". pi-watcher moves that loop out of the model:
+
+- **Facts first.** Explicit terminal states, exit markers, deadlines and silence are decided by code, not by a model.
+- **Quiet by default.** Routine progress only updates a status widget. Nothing enters the conversation.
+- **Wake on decisions.** Failure, a crossed deadline, a ready dependency or (optionally) a semantic blocker
+  becomes one episode and one wake. The host then inspects the fresh facts and responds.
+- **Honest state.** Unknown stays unknown. Delivery, withdrawal and completion are reported only with evidence.
+
+## How it works
+
+```
+ exec log / build output / CI status          Pi session
+            │                                      ▲
+   watch-file │ watch-check                         │ wake (managed delivery)
+            ▼                                      │
+   pi-watcher engine ──► SQLite truth store ──► pi-relay ──► relay_respond ──► watcher applies the response
+   hard rules, deadlines, silence,
+   optional Jev semantic review
+```
+
+Each Pi session runs its own watcher runtime with state under `<cwd>/.pi-watcher/sessions/<session-id>/`.
+The watcher never runs, retries, kills or fixes the task it watches.
+
+## Requirements
+
+- Pi 1.0 or newer (`@earendil-works/pi-coding-agent`); Jev through Pi's `/login` needs Pi 1.1+
+- Node.js 22.16 or newer
+- macOS or Linux. Windows is not supported.
+- A native build toolchain for `fs-ext` (Python 3, `make`, a C++ compiler; on macOS the Xcode Command Line
+  Tools). `better-sqlite3` ships prebuilt binaries for common platforms. pi-relay has the same requirements.
+
+## Install
+
+```bash
+pi install npm:@maolon/pi-relay
+pi install npm:@maolon/pi-watcher
+```
+
+Use `-l` to install into the current project (`.pi/settings.json`) instead of your personal settings, or try it
+for one run with `pi -e npm:@maolon/pi-watcher`. Pin versions with `npm:@maolon/pi-watcher@0.1.0`.
+
+Add the watcher's state directories to your project's `.gitignore`:
+
+```gitignore
+.pi-watcher/
+.pi-watcher-sources/
+```
+
+## pi-relay
+
+pi-watcher uses [`@maolon/pi-relay`](https://www.npmjs.com/package/@maolon/pi-relay) in two different roles:
+
+| Role | What it is | How you get it |
+|---|---|---|
+| **Library** | The watcher publishes attentions, withdraws them on pause/close and reads host responses through pi-relay's managed-delivery source API (`@maolon/pi-relay/source`, `/consumer`, `/protocol`). | A regular npm dependency of pi-watcher, installed automatically. |
+| **Pi extension** | Runs inside your Pi session as the delivery target: receives the wake, injects it when the session is idle, and gives the model the `relay_respond` tool. | Install it yourself: `pi install npm:@maolon/pi-relay`. |
+
+**Compatibility.** pi-watcher 0.1.x requires pi-relay **0.2.x**: the `^0.2.0` dependency for the library, and
+0.2.x for the extension you install. Both sides share the relay home on disk (`~/.pi/relay`, or `PI_RELAY_HOME`),
+so keep them on the same minor version.
+
+**Without the pi-relay extension**, the watcher still works, but in *local display* mode:
+
+| | with pi-relay | without pi-relay |
+|---|---|---|
+| Watches, hard rules, deadlines, silence | yes | yes |
+| Status widget and toasts in the session | yes | yes |
+| Result cards, `inspect`, `/watcher` panel | yes | yes |
+| Wake an idle session when a fact needs a decision | **yes** | no: you or the model must look |
+| Host response loop (`relay_respond` → applied) | yes | no (`ack` returns `NO_DELIVERY`; use `/watcher ack`) |
+| Withdraw pending wakes on `pause`/`close` | yes (per-route result) | nothing is in flight |
+
+**Setup is automatic.** When the relay home exists, the watcher enables relay delivery. On session start it asks the
+pi-relay extension in the same session for a local binding over Pi's event bus, then provisions its audience and
+scope. No invite or manual step is needed. The binding is *local trust*: same machine, same OS user, no interactive
+consent prompt. To opt out:
+
+- `PI_WATCHER_RELAY=0`: never use relay (local display only).
+- `PI_WATCHER_AUTO_BIND=0`: keep relay, but do not bind automatically. Use `pi-watcher relay-setup` instead.
+
+**When a wake arrives**, the model is instructed to run `watcher inspect` for that watch first, act on the fresh
+facts, and then answer with `relay_respond` (`received`, `investigating`, `defer`, `resolved` or `dismiss`). The
+watcher applies the response to the episode, confirms the application back to the relay, and closes finished
+watches shortly afterwards.
+
+## Usage
+
+You normally just ask: *"run the test suite and tell me when it's done"*, *"watch the training run"*, *"keep an eye
+on the CI for this PR"*. The tool guidelines steer the model to the `watcher` tool instead of polling.
+
+### Watch a file
+
+Typical use: the log of a long `exec_command` session.
+
+```json
+{ "action": "watch-file", "path": "/tmp/build.log",
+  "okPattern": "__EXEC_EXIT__:0", "failPattern": "__EXEC_EXIT__:-?[1-9]",
+  "objective": "release build", "deadlineAt": "2026-10-08T18:00:00Z" }
+```
+
+A terminal state is decided only by the declared patterns (fail is checked first). End of file, a quiet log or a
+line that merely says "done" never counts as completion.
+
+### Watch a command
+
+Use this for state you cannot tail: CI, cloud resources, remote health.
+
+```json
+{ "action": "watch-check", "cmd": "gh run view 123456 --json conclusion -q .conclusion",
+  "okPattern": "^success$", "failPattern": "^(failure|cancelled)$", "intervalMs": 60000 }
+```
+
+The command runs on a fixed interval with a timeout (1–30 s). Exit codes 126/127 and timeouts mark the *monitor* as
+degraded; they never mark the task as failed. The command text is stored as evidence, so never put secrets in it.
+
+### Other actions
+
+| Action | Purpose |
+|---|---|
+| `list` | Active and paused watches (`includeClosed: true` for history) |
+| `inspect` | Authoritative facts for one watch: state, episodes, health, delivery |
+| `check` | Schedule one bounded refresh now (needs `expectedControlRevision`) |
+| `pause` / `close` | Stop watching. Pending wakes are withdrawn; the result is reported per route. |
+| `register` | Full spec: `run`, `group` (up to 16 members) and `obligation` targets |
+
+`/watcher` shows the panel; `/watcher ack <episodeId> <received|investigating|defer|resolved|dismiss> [until]`
+handles an episode locally; `/watcher jev` manages the optional semantic review (see below).
+
+### Exit markers for `exec_command`
+
+To make shell-session outcomes decidable, the watcher appends `echo __EXEC_EXIT__:$?` to every `exec_command`
+call. It creates no watch on its own. Disable it with `PI_WATCHER_EXEC_MARKER=0`. To have every long-running exec
+session watched automatically, set `PI_WATCHER_AUTO_EXEC=1` (off by default).
+
+## Semantic review (Jev, optional)
+
+**Optional and off by default.** pi-watcher works fully without it: every watch is decided by facts (patterns,
+exit markers, deadlines, silence). Semantic review is an extra layer you opt into per watch.
+
+Some tasks cannot be judged by patterns alone: a training run that stalls, a fix loop that keeps repeating, a log
+that claims success while showing errors. With `semanticMode` set on a watch, the watcher asks
+[Jev](https://typesafe.ai), TypeSafe's fast discriminative classifier (not a chat model), six bounded questions
+about a sanitized evidence window: progress, unresolved blocker, needs host decision, repeating without new
+information, claim vs evidence conflict, and context sufficiency.
+
+- `off` (default): facts only.
+- `shadow`: record judgments and show them as toasts and widget hints; never wake.
+- `active`: a confident blocker, decision request, repeating loop or claim conflict opens an episode and can wake the session.
+
+Enabling it takes two separate steps, because authentication and permission to send data are different decisions.
+
+**1. Authenticate Jev through Pi** (Pi 1.1+ ships Jev as a classifier model). Use any one of these:
+
+- In Pi, run `/login`, choose **Sign in with an API key**, then pick **TypeSafe** (or another provider that serves
+  Jev, such as OpenRouter or OpenCode). The credential lands in Pi's `auth.json` and the watcher picks it up,
+  even mid-session.
+- `export TYPESAFE_API_KEY=...` (Pi's standard variable for TypeSafe).
+- `export JEV_API_KEY=...` uses the watcher's own direct client, pinned to `jev-1.13.0`. It takes precedence over Pi's registry.
+
+When several Jev providers are configured, the watcher prefers TypeSafe direct, then OpenRouter, OpenCode,
+Cloudflare Workers AI and Vercel AI Gateway. Force one with `PI_WATCHER_JEV_MODEL=<provider>/<model>`, for example
+`openrouter/typesafe/jev-1.13`. The model that actually answered is recorded with every judgment.
+
+**2. Grant egress consent** (user only; the model cannot grant it):
+
+```
+/watcher jev consent on      # stored in ~/.pi/agent/pi-watcher.json; `off` revokes it
+/watcher jev                 # shows the active Jev source and the consent state
+```
+
+Alternatively set `JEV_CONSENT=1` (or `0` to force it off); the environment overrides the stored setting.
+
+Without credentials, a watch with `semanticMode` shows "semantic review unavailable" with the reason, and the facts
+keep working. Before anything is sent, credentials and tokens are redacted. Requests are budgeted per watch and
+per day, and hard facts always win over model scores. Redaction is best effort: for sensitive repositories, leave
+`semanticMode` off.
+
+## Configuration
+
+| Variable | Default | Effect |
+|---|---|---|
+| `PI_RELAY_HOME` | `~/.pi/relay` | Relay home shared with the pi-relay extension |
+| `PI_WATCHER_RELAY` | auto | `0` disables relay delivery |
+| `PI_WATCHER_AUTO_BIND` | on | `0` disables automatic local binding |
+| `PI_WATCHER_EXEC_MARKER` | on | `0` disables `__EXEC_EXIT__` injection |
+| `PI_WATCHER_AUTO_EXEC` | off | `1` auto-watches long-running exec sessions |
+| `TYPESAFE_API_KEY` | unset | Pi's TypeSafe credential; enables Jev through Pi (same as `/login` → TypeSafe) |
+| `JEV_API_KEY` | unset | Watcher's direct Jev client (`jev-1.13.0`); takes precedence over Pi's registry |
+| `PI_WATCHER_JEV_MODEL` | auto | Force a Pi Jev model, e.g. `openrouter/typesafe/jev-1.13` |
+| `JEV_CONSENT` | unset | `1`/`0` overrides the stored `/watcher jev consent` setting |
+| `PI_WATCHER_CONFIG` | `~/.pi/agent/pi-watcher.json` | Where `/watcher jev consent` is stored |
+| `JEV_BASE_URL` | `https://api.typesafe.ai` | Endpoint for the direct client |
+| `JEV_TIMEOUT_MS` | `10000` | Per-request timeout for the direct client |
+
+## Data and privacy
+
+- All watcher state stays on your machine: SQLite (WAL, `synchronous=FULL`) under `<cwd>/.pi-watcher/`.
+- Wakes travel through pi-relay's store under the relay home on the same machine.
+- Shadow-mode judgments are shown as session toasts and widget hints, never as conversation messages.
+- Only with Jev credentials **and** egress consent (`/watcher jev consent on` or `JEV_CONSENT=1`) does a sanitized,
+  size-bounded evidence window leave the machine, and only for watches with `semanticMode` set.
+- `watch-file` reads the paths you or the model declare. `watch-check` runs the declared command as your user.
+  Both are as powerful as the session itself; review what the model registers.
+
+## CLI
+
+The package also installs `pi-watcher`:
+
+```bash
+pi-watcher doctor --root .pi-watcher       # local diagnostics
+pi-watcher relay-setup [--finalize]        # manual relay owner setup (when auto-bind is off)
+pi-watcher qualify                         # native dependency / storage qualification report
+```
+
+## Status
+
+0.1 is an early release. What is solid and what is not:
+
+- **Solid:** fact-driven watches (`watch-file`, `watch-check`, task-status), deadlines, silence, result cards,
+  per-session isolation, relay wakes with withdraw-on-pause, idempotent host-response handling. Covered by the
+  offline suite, including end-to-end tests against the real pi-relay libraries.
+- **Experimental:** semantic review thresholds are initial values, not calibrated results. Use `shadow` before `active`.
+- **Not yet:** a standalone watcher service (the watcher runs inside the Pi session), an interactive consent prompt
+  for relay binding (it is local trust today), fork/tree-navigation holds, artifact-digest binding for checks,
+  evidence retention limits, and the `update` action.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run test:unit        # offline suite
+npm run build            # dist/
+npm run test:package     # pack + leak scan + install + load with plain Node
+```
+
+To load your working copy in Pi: `pi -e ./` from this directory after `npm run build`. See [AGENTS.md](AGENTS.md)
+for conventions.
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+/**
+ * pi-watcher CLI (design 11.2 shell entry point).
+ * - qualify: V0 qualification check, produces qualification.json (distinguishes candidate platforms from measured platforms)
+ * - doctor: local diagnostics (lock/DB/relay negotiation/panel summary)
+ * - producer: runs a real async task-status-v1 fixture producer
+ * - demo: V1 display-only end-to-end demo
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+/**
+ * pi-watcher CLI (design 11.2 shell entry point).
+ * - qualify: V0 qualification check, produces qualification.json (distinguishes candidate platforms from measured platforms)
+ * - doctor: local diagnostics (lock/DB/relay negotiation/panel summary)
+ * - producer: runs a real async task-status-v1 fixture producer
+ * - demo: V1 display-only end-to-end demo
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { spawn, execSync } from 'node:child_process';
+import { startRuntime } from './runtime.js';
+import { runScenario, scenarioSteps } from './source/task-status-v1/producer.js';
+import { negotiateRelay } from './relay/negotiate.js';
+function parseArgs(argv) {
+    const [cmd, ...rest] = argv;
+    const flags = new Map();
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i].startsWith('--')) {
+            const key = rest[i].slice(2);
+            const next = rest[i + 1];
+            if (next && !next.startsWith('--')) {
+                flags.set(key, next);
+                i += 1;
+            }
+            else {
+                flags.set(key, 'true');
+            }
+        }
+    }
+    return { cmd: cmd ?? '', flags };
+}
+async function main() {
+    const { cmd, flags } = parseArgs(process.argv.slice(2));
+    switch (cmd) {
+        case 'qualify':
+            await cmdQualify(flags);
+            break;
+        case 'doctor':
+            await cmdDoctor(flags);
+            break;
+        case 'producer':
+            await cmdProducer(flags);
+            break;
+        case 'demo':
+            await cmdDemo(flags);
+            break;
+        case 'relay-setup':
+            await cmdRelaySetup(flags);
+            break;
+        default:
+            console.log('usage: pi-watcher <qualify|doctor|producer|demo|relay-setup> [options]');
+            console.log('  qualify  [--out qualification.json]       V0 qualification check, writes evidence file');
+            console.log('  doctor   [--root DIR]                     local diagnostics');
+            console.log('  producer --dir D --scenario build-success|build-failure [--interval 200] [--run-id run-1]');
+            console.log('  demo                                       V1 display-only end-to-end demo');
+            console.log('  relay-setup [--root DIR] [--relay-home DIR] [--finalize]  relay consumer-side owner setup');
+            process.exit(cmd ? 2 : 0);
+    }
+}
+async function cmdQualify(flags) {
+    const checks = [];
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pw-qual-'));
+    // 1. SQLite WAL/FULL/FK (measured with native better-sqlite3)
+    try {
+        const Database = (await import('better-sqlite3')).default;
+        const db = new Database(path.join(tmp, 'qual.db'));
+        const jm = db.pragma('journal_mode = WAL', { simple: true });
+        db.pragma('synchronous = FULL');
+        db.pragma('foreign_keys = ON');
+        const sync = db.pragma('synchronous', { simple: true });
+        const fk = db.pragma('foreign_keys', { simple: true });
+        db.close();
+        checks.push({
+            check: 'sqlite-native-wal-full-fk',
+            passed: jm === 'wal' && sync === 2 && fk === 1,
+            detail: `journal_mode=${jm}, synchronous=${sync} (2=FULL), foreign_keys=${fk}`
+        });
+    }
+    catch (e) {
+        checks.push({ check: 'sqlite-native-wal-full-fk', passed: false, detail: String(e) });
+    }
+    // 2. flock fixed-inode mutual exclusion (child process holds the lock)
+    try {
+        const lockPath = path.join(tmp, 'watcher.lock');
+        fs.writeFileSync(lockPath, '', 'utf8');
+        const holder = `
+      const fs = require('node:fs');
+      const { flock } = require('fs-ext');
+      const fd = fs.openSync(${JSON.stringify(lockPath)}, 'a');
+      flock(fd, 'ex', () => {
+        console.log('held');
+        setTimeout(() => process.exit(0), 4000);
+      });
+    `;
+        const child = spawnNode(['-e', holder]);
+        await waitStdout(child, 'held');
+        const fsExt = await import('fs-ext');
+        const fsMod = await import('node:fs');
+        const fd2 = fsMod.openSync(lockPath, 'a');
+        const rejected = await new Promise(resolve => {
+            fsExt.flock(fd2, 'exnb', (err) => {
+                resolve(!!err);
+            });
+        });
+        fsMod.closeSync(fd2);
+        child.kill('SIGKILL');
+        checks.push({
+            check: 'root-flock-exclusive-contention',
+            passed: rejected,
+            detail: rejected ? 'second exclusive non-blocking flock rejected (EAGAIN)' : 'second flock unexpectedly acquired'
+        });
+    }
+    catch (e) {
+        checks.push({ check: 'root-flock-exclusive-contention', passed: false, detail: String(e) });
+    }
+    // 3. storage.sql schema constraints (triggers + uniqueness + partial unique indexes)
+    try {
+        const { WatchStore } = await import('./storage/store.js');
+        const store = await WatchStore.open(path.join(tmp, 'root3'), { mode: 'embedded' });
+        const violations = [];
+        // outbox identity immutable
+        try {
+            store.transaction(tx => {
+                tx.insertWatch({
+                    watchId: 'wq', generation: 1, missionRevision: 1, controlRevision: 1,
+                    lifecycle: 'active', health: 'healthy', ownerSession: 's', ownerBindingEpoch: 1,
+                    spec: { schemaVersion: 1, watchId: 'wq', generation: 1, missionRevision: 1, controlRevision: 1, mode: 'embedded',
+                        owner: { sessionId: 's', originAnchor: null, bindingEpoch: 1, profileId: 'p' },
+                        target: { kind: 'run', sourceId: 'src', taskId: 't', runId: 'r', attemptId: 'a' },
+                        mission: { objective: 'o', scope: 's', checkpointId: 'c', requiredArtifacts: [], requiresChecks: false, businessAcceptance: 'not_required' },
+                        policy: { transport: 'local-display', semanticMode: 'off', notificationOwner: 'watcher', requestKinds: [], maxRequestsPerEpisode: 1, episodeCooldownMs: 60000, attentionTtlMs: 120000 },
+                        limits: { pollMinMs: 1000, pollMaxMs: 30000, maxSilenceMs: 60000, maxProbesPerEpisode: 2, maxJudgeRequestsPerDay: 10, expiresAt: new Date(Date.now() + 3600_000).toISOString() } },
+                    snapshot: { taskState: 'unknown', coverage: { truncated: false, sourceGap: false }, scopeRevision: 0, backoffMs: 0 },
+                    nextDueAt: Date.now(), now: Date.now()
+                });
+                tx.insertOutbox({
+                    eventId: 'ev1', watchId: 'wq', episodeId: null, generation: 1, eventType: 'watcher.result.v1',
+                    eventBytes: Buffer.from('{}'), eventDigest: 'd', validUntil: Date.now() + 1000, now: Date.now()
+                });
+            });
+            let immutableRejected = false;
+            try {
+                store.transaction(tx => {
+                    tx.setOutboxAdmission('ev1', 'pending', {}, Date.now());
+                    tx.mutateOutbox?.();
+                });
+            }
+            catch {
+                immutableRejected = true;
+            }
+            if (!immutableRejected) {
+                // Verify triggers directly with SQL
+                const Database = (await import('better-sqlite3')).default;
+                const db = new Database(path.join(tmp, 'root3', 'watcher.db'));
+                try {
+                    db.prepare("UPDATE outbox SET event_bytes = ? WHERE event_id = ?").run(Buffer.from('{"x":1}'), 'ev1');
+                }
+                catch {
+                    immutableRejected = true;
+                }
+                db.close();
+            }
+            if (!immutableRejected)
+                violations.push('outbox identity trigger did not reject mutation');
+        }
+        catch (e) {
+            violations.push(`setup: ${String(e)}`);
+        }
+        store.close();
+        checks.push({
+            check: 'storage-schema-constraints',
+            passed: violations.length === 0,
+            detail: violations.length === 0 ? 'outbox identity immutability enforced by trigger' : violations.join('; ')
+        });
+    }
+    catch (e) {
+        checks.push({ check: 'storage-schema-constraints', passed: false, detail: String(e) });
+    }
+    // 4. relay 1.2 feature negotiation
+    const negotiation = await negotiateRelay();
+    checks.push({
+        check: 'relay-1-2-feature-negotiation',
+        passed: negotiation.status === 'unavailable' || negotiation.status === 'managed-1-2',
+        detail: `status=${negotiation.status}; transport=${negotiation.transport}; ${negotiation.detail}`
+    });
+    // 5. runtime versions
+    checks.push({
+        check: 'runtime-versions',
+        passed: true,
+        detail: `node=${process.versions.node}, platform=${os.platform()}/${os.arch()}`
+    });
+    fs.rmSync(tmp, { recursive: true, force: true });
+    const out = {
+        kind: 'V0_QUALIFICATION',
+        date: new Date().toISOString(),
+        commit: gitHead(),
+        machine: `${os.platform()}/${os.arch()} node ${process.versions.node}`,
+        candidatePlatform: 'POSIX (darwin) local',
+        testedPlatform: `${os.platform()} local`,
+        checks,
+        passed: checks.every(c => c.passed),
+        note: 'V0 qualification only; not product acceptance (see design 14).'
+    };
+    const outPath = flags.get('out') ?? 'qualification/qualification.json';
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, JSON.stringify(out, null, 2), 'utf8');
+    console.log(JSON.stringify(out, null, 2));
+    process.exit(out.passed ? 0 : 5);
+}
+function gitHead() {
+    try {
+        return execSync('git rev-parse HEAD', { cwd: process.cwd(), encoding: 'utf8' }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function spawnNode(args) {
+    return spawn(process.execPath, args, { stdio: ['ignore', 'pipe', 'inherit'] });
+}
+async function waitStdout(child, needle, timeoutMs = 5000) {
+    await new Promise((resolve, reject) => {
+        let buf = '';
+        const timer = setTimeout(() => reject(new Error('timeout waiting for holder lock')), timeoutMs);
+        child.stdout?.on('data', (chunk) => {
+            buf += chunk.toString('utf8');
+            if (buf.includes(needle)) {
+                clearTimeout(timer);
+                resolve();
+            }
+        });
+        child.on('exit', code => {
+            clearTimeout(timer);
+            reject(new Error(`holder exited early: ${code}`));
+        });
+    });
+}
+// --- doctor ---
+async function cmdDoctor(flags) {
+    const root = path.resolve(flags.get('root') ?? './.pi-watcher');
+    const negotiation = await negotiateRelay();
+    const report = {
+        root,
+        lockFile: fs.existsSync(path.join(root, 'watcher.lock')),
+        dbFile: fs.existsSync(path.join(root, 'watcher.db')),
+        relay: negotiation,
+        versions: { node: process.versions.node }
+    };
+    console.log(JSON.stringify(report, null, 2));
+}
+// --- producer ---
+async function cmdProducer(flags) {
+    const dir = flags.get('dir');
+    const scenario = (flags.get('scenario') ?? 'build-success');
+    const interval = parseInt(flags.get('interval') ?? '200', 10);
+    const runId = flags.get('run-id') ?? `run-${Date.now()}`;
+    if (!dir) {
+        console.error('--dir required');
+        process.exit(2);
+    }
+    const producer = await runScenario(dir, { sourceId: 'executor-local', taskId: 'build', runId, attemptId: 'attempt-1' }, scenarioSteps(scenario, interval));
+    console.log(JSON.stringify({ done: true, scenario, dir, runId, lastSnapshot: producer.lastSnapshot }, null, 2));
+}
+// --- demo (V1 display-only) ---
+async function cmdDemo(_flags) {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pw-demo-'));
+    const sourceRoot = path.join(tmp, 'sources');
+    const rootDir = path.join(tmp, 'state');
+    const runtime = await startRuntime({
+        rootDir,
+        sourceRoots: new Map([['executor-local', sourceRoot]]),
+        requiredCheckIds: new Map([['executor-local', ['unit-tests']]]),
+        pollTickMs: 100
+    });
+    runtime.startLoop();
+    const scenarioP = runScenario(sourceRoot, { sourceId: 'executor-local', taskId: 'build', runId: 'run-demo-1', attemptId: 'attempt-1' }, scenarioSteps('build-failure', 150));
+    await scenarioP;
+    await new Promise(r => setTimeout(r, 700));
+    const actor = {
+        actorId: 'demo',
+        owner: { sessionId: 'demo-session', originAnchor: null, bindingEpoch: 1, profileId: 'demo' },
+        profileRevision: 1,
+        permitted: new Set()
+    };
+    const spec = await runtime.service.register(`req-${Date.now()}`, {
+        schemaVersion: 1,
+        mode: 'embedded',
+        target: { kind: 'run', sourceId: 'executor-local', taskId: 'build', runId: 'run-demo-1', attemptId: 'attempt-1' },
+        mission: {
+            objective: 'Run the existing async build task; observe status and report on failure or deliverable results.',
+            scope: 'Observe run-demo-1 only; do not modify, retry, or terminate the build.',
+            checkpointId: 'compile-and-test',
+            requiredArtifacts: ['artifact-app'],
+            requiresChecks: true,
+            businessAcceptance: 'host'
+        },
+        policy: {
+            transport: 'local-display',
+            semanticMode: 'off',
+            notificationOwner: 'watcher',
+            requestKinds: ['task.failed', 'task.terminal'],
+            maxRequestsPerEpisode: 1,
+            episodeCooldownMs: 60000,
+            attentionTtlMs: 120000
+        },
+        limits: {
+            pollMinMs: 1000,
+            pollMaxMs: 5000,
+            maxSilenceMs: 60000,
+            maxProbesPerEpisode: 2,
+            maxJudgeRequestsPerDay: 10,
+            expiresAt: new Date(Date.now() + 3600_000).toISOString()
+        }
+    }, actor);
+    await new Promise(r => setTimeout(r, 1200));
+    const listed = await runtime.service.list(undefined, 50, actor);
+    const inspected = await runtime.service.inspect(spec.watchId, actor);
+    console.log('=== demo register ===');
+    console.log(JSON.stringify({ watchId: spec.watchId }, null, 2));
+    console.log('=== list ===');
+    console.log(JSON.stringify(listed, null, 2));
+    console.log('=== inspect ===');
+    console.log(JSON.stringify(inspected, null, 2));
+    runtime.close();
+    fs.rmSync(tmp, { recursive: true, force: true });
+}
+main().catch(e => {
+    console.error(e);
+    process.exit(5);
+});
+// --- relay-setup (owner side: consumer declaration + invite + audience/scope configuration) ---
+async function cmdRelaySetup(flags) {
+    const { WatcherRelaySource } = await import('./relay/managed.js');
+    const cwd = process.cwd();
+    const rootDir = path.resolve(flags.get('root') ?? path.join(cwd, '.pi-watcher', 'relay'));
+    const relayHome = path.resolve(flags.get('relay-home') ?? process.env.PI_RELAY_HOME ?? path.join(os.homedir(), '.pi', 'relay'));
+    const finalize = flags.get('finalize') === 'true';
+    const relay = await WatcherRelaySource.open(rootDir, { relayHome });
+    const decl = relay.ensureConsumerDeclaration();
+    console.log(JSON.stringify({
+        step: 'consumer-declaration',
+        file: decl.file,
+        note: 'Pi sessions (with the relay extension) scan <relay-home>/consumers at startup and register the guard'
+    }, null, 2));
+    if (!finalize) {
+        const invite = relay.createInvite();
+        console.log(JSON.stringify({
+            step: 'invite',
+            inviteFile: invite.inviteFile,
+            note: 'Have the host-session model call the relay_bindings tool: action=bind, invitePath=<file above> (single-use), then run relay-setup --finalize'
+        }, null, 2));
+        await relay.close();
+        return;
+    }
+    if (!relay.hasActiveMembership()) {
+        console.log(JSON.stringify({
+            step: 'finalize-blocked',
+            reason: 'no membership yet — run bind first (see invite step), then retry --finalize',
+            status: relay.statusJson()
+        }, null, 2));
+        await relay.close();
+        return;
+    }
+    const prov = relay.provision();
+    console.log(JSON.stringify({ step: 'provisioned', ...prov, transportAfter: 'relay' }, null, 2));
+    await relay.close();
+}