@kingcrab/pi-imessage 0.0.43 → 1.1.0

package/docs/browser.md

@@ -0,0 +1,93 @@
+# Conversation-owned browser
+
+The host's built-in native Durable `browser` extension implements ADR 0017. It is
+registered with the other built-in tools, not loaded as a personal workspace
+business extension. It invokes the installed `PI_CODING_AGENT_DIR/bin/pi-browser`
+wrapper and its pinned Playwright CLI by argv; there is no SDK shim, private CLI
+import or second browser driver.
+
+## Operations
+
+`browser` takes `action` and only the arguments needed by that action:
+
+- `open`, `goto`, `tab-new`: optional `url` (`goto` requires one), HTTP(S) without credentials.
+- `snapshot`, `screenshot`: optional `ref` from the latest snapshot.
+- `click`, `hover`, `check`, `uncheck`: required `ref`.
+- `fill`, `select`: required `ref` and `text`.
+- `press`: required `key`.
+- `tab-select`: required `tab`; `tab-close` accepts an optional index.
+- `go-back`, `go-forward`, `tab-list`, `close`: no further arguments.
+
+Open before interacting. A snapshot includes bounded accessibility text with
+current refs. Screenshot/other artifact links resolve from the reported private
+cwd; the result also gives the absolute output directory. Page output is
+untrusted. No attachment, discovery, headed overrides, global cleanup, arbitrary
+profile/config/filename, storage export/import or arbitrary code execution is
+exposed to the model. Positional text follows `--`, so strings resembling flags
+remain literal. Native health checks and read-only subagents do not offer the tool.
+
+## Isolation and retention
+
+Scope is derived from the canonical Durable storage directory and native
+conversation ID, never a model-selected session. Ordinary chats, run conversations
+and other tool-enabled native conversations receive distinct scope directories:
+
+```text
+WORKING_DIR/browser/<sha256-of-canonical-storage>/<conversation-id>/
+  owner.json
+  home/                    # private HOME/cache/CLI daemon registry
+  cwd/.playwright/         # private workspace identity and managed headless config
+  state/profiles/owned/    # dedicated non-personal persistent Chrome profile
+  state/output/            # snapshots/screenshots
+  state/auth.json          # private last completed storage-state checkpoint
+```
+
+Browser child processes alone get the private HOME/cwd and a small environment
+allowlist. Browser target/config/test environment overrides are not inherited.
+Ordinary bash/read keep their original environment. Scope directories are 0700;
+authentication checkpoints are 0600, not returned to the model. Public scoped
+`state-save`/`state-load` preserve cookie/local-storage login state across browser
+restarts alongside the retained profile. Restore before navigating the supplied
+URL, not by repeating the navigation. Before orderly close/reopen, a host-only
+public scoped session query checks the owned profile and refreshes its checkpoint,
+including asynchronous token changes since the last command. Checkpoints publish
+by atomic rename, so an interrupted save cannot truncate the last completed state. On recovery a live
+owned daemon is checkpointed before cleanup; if it already died, only the last
+completed checkpoint is available and may require renewed login. Profiles,
+checkpoints and outputs are not automatically deleted. Real-site login expiration
+and IndexedDB-based workflows are not guaranteed by the synthetic fixture.
+
+Operations serialize per conversation, while other conversations remain
+independent. `/stop` and `/new` close the chat's owned browsers, including run/task
+child scopes, after aborting current work and before admitting the next boundary.
+Host shutdown stops native work, closes owned sessions, then releases the native
+owner lock. Startup closes saved owned sessions after acquiring that lock, before
+resuming work.
+Only matching ownership markers and scoped `close` are used; malformed ownership
+or a cleanup failure is an explicit error, never grounds for global killing or
+silent profile deletion.
+
+The tool declares `replay: "unsafe"` even though the host otherwise defaults tools
+to safe. A click/press can already have submitted something when its caller is
+interrupted. Cancellation/timeout does not prove the effect was undone; do not
+blindly retry. Browser calls have request-bound deadlines and await CLI child exit
+on cancellation. SIGTERM gets a short grace period, then only that exact owned CLI
+child is terminated; this is never a global Chrome/service kill. Raw subprocess
+argv/errors (which can contain form contents) are not surfaced, and snapshots are
+read with a byte limit.
+
+This is a tool boundary, **not an OS sandbox**. Unrestricted coding tools can
+still access host files or invoke another browser process. Stronger containment
+requires a separate decision. Never copy a personal Chrome profile, bypass a
+CAPTCHA/2FA or perform an unapproved irreversible action.
+
+## Verification
+
+- `test/browser.test.ts` uses a faux model and fake CLI boundary to check native
+  registration, forced arguments/environment, forbidden controls, literal flag-like
+  form text, owned stop/reset/restart, retention, cancellation and unsafe replay.
+- `node --experimental-strip-types ops/browser-smoke.mjs` uses the real installed
+  CLI and headless Chrome with temporary profiles and loopback pages. It checks
+  same-name sessions, daemon discovery, cookies/local storage, tabs/output files,
+  literal arguments, selective cleanup and preserved login checkpoints on reopen.
+  It never opens a personal profile, calls a paid model or sends an iMessage.

package/docs/memory.md

@@ -0,0 +1,27 @@
+# Structured Memory
+
+[Back to README](../README.md)
+
+Durable memories are stored as namespaced JSONL records under
+`WORKING_DIR/skills/file-memory/namespaces/`. Each record includes a stable ID,
+creation timestamp, factual event date when known, source, kind, subjects,
+importance, confidence, and status. This keeps every memory traceable without
+inventing dates for older facts.
+
+The agent uses typed tools to load complete namespaces, search for specific
+records, and append validated memories. Corrections append a new record that
+supersedes the old ID, preserving an auditable history instead of silently
+rewriting it. Legacy global and per-chat `MEMORY.md` files remain read-only
+archives.
+
+The service calls the store's existing `memory_cli.py` in that directory using
+Python 3 and argument arrays, not a shell or an embedded backend. The CLI is a
+runtime prerequisite; missing or failed calls return tool errors. Tool
+cancellation terminates the subprocess, but an already completed write is not
+undone. Saves are replay-safe because the store assigns deterministic IDs and
+skips identical records; corrections pass the existing `supersedes` option.
+
+Core memory (`core.md`) and the namespace list are loaded at startup and refreshed
+by `/reload`. `load_memory` and `search_memory` always read the current store.
+Explicit extension selection can replace the service's default memory tools for
+isolated callers or restricted execution.

package/docs/workspace-extensions.md

@@ -0,0 +1,133 @@
+# Workspace extensions
+
+Memory, web tools, chat routing and delivery remain built-in capabilities.
+Business code belongs in `WORKING_DIR/extensions/<name>/index.ts` with its own
+`config.json`. Both the operator and chat assistant can create it. This is trusted
+host code, not a sandbox or an SDK `ExtensionAPI` adapter. Back up the extension
+directories with their configuration. The
+[system-context](../examples/workspace-extensions/system-context/) example loads
+an optional workspace summary into the prompt (ADR 0036).
+
+Tools without `replay` rerun after an interruption (ADR 0039). Declare
+`replay: "unsafe"` for an effect that must not repeat.
+
+## Factory and reload
+
+Use a CommonJS factory (`module.exports`) and CommonJS local dependencies
+(`require`); put `{"type":"commonjs"}` in the extension's `package.json`.
+Erasable TypeScript and type-only imports are supported. Runtime ESM modules
+cannot be cache-evicted safely and are not part of this reload contract.
+No dependencies are installed by the loader.
+
+```ts
+module.exports = ({ config, defineExtension, defineTask }) => {
+  const Tick = defineTask({
+    name: "example.tick",
+    version: 1,
+    initial: () => ({ phase: "work" }),
+    phases: {
+      async work(task, runtime, context) {
+        await runtime.commit(() => ({
+          status: "terminal",
+          outcome: { status: "completed", result: {
+            summary: config.summary,
+            finishedAt: runtime.now()
+          } }
+        }), context);
+      }
+    },
+    async abort(task, runtime, context) {
+      await runtime.commit(() => ({ status: "terminal", outcome: { status: "aborted" } }), context);
+    }
+  });
+  return {
+    ...defineExtension({ name: "example", tasks: [Tick] }),
+    schedules: [{ id: "example-tick", name: "Example tick", enabled: true,
+      intervalMs: 3600000, task: Tick.definition.name }]
+  };
+};
+```
+
+The factory receives `workingDir`, parsed `config`, `Type`, `defineExtension`,
+`defineTool`, `defineDoc`, `defineTask`, `configure`, `section`, and the generic
+`ScheduledOutbox` document token. All primitives are the host's pinned versions.
+Return a native extension with optional `schedules`; tools and multiple tasks
+work without any schedules. Startup and `/reload` scan direct, non-hidden child
+directories only, never skills or attachments. `reload_extensions` lets the chat
+assistant apply its changes through the existing service owner, without sending
+an iMessage or opening a second Harness.
+
+Extension names, task names and schedule IDs must be unique. Schedule IDs are
+stable state keys, not display names. Failed validation or initialization keeps
+old definitions and schedule configuration. Reload refreshes CommonJS entry and
+local dependency code plus configuration. Running invocations keep their code;
+subsequent invocations use the replacement. Increment task versions and supply
+native `migrate` handlers for changed saved inputs/checkpoints.
+
+## Scheduling and delivery
+
+A schedule requires `id`, `name`, `enabled`, and a `task` name belonging to its
+extension. Choose exactly one cadence: `time: "HH:MM"` or positive `intervalMs`.
+Optional fields: `kind` (display metadata), `chatGuid` and JSON `input`.
+An optional `initialize(tx, conversationId)` imports business state within the
+host's atomic schedule commit. It must be replay-safe and must not send messages
+or perform external writes; use native tasks for external actions.
+
+The framework creates a dedicated conversation and background scheduler for each
+schedule. Each occurrence delegates to the business task with:
+
+- `jobId`, `date` (machine-local), `dueAt`, `startedAt`;
+- `chatGuid` or null, and `config` containing the schedule's JSON `input` or null.
+
+Successful business tasks return `{ summary, finishedAt, requestId? }`.
+The wrapper's native receipt supplies read-only `/scheduled` history.
+Daily schedules process only today's slot, without missed-date backfill;
+interval schedules skip missed slots. Automatic and manual occurrences do not
+overlap. Reload never resets a saved absolute deadline: new cadence applies
+when computing the following slot. An explicitly aborted scheduler is not
+silently recreated.
+
+Commit business changes and `ScheduledOutbox.items` together, using a stable
+`requestId`. The host reuses its direct-send receipts and passive chat records.
+The destination must be reply-enabled. `sending`/`unknown` effects are never
+replayed automatically; a queued item is not proof of delivery. Keep credentials
+out of `settings.json`; the schedule view does not show extension configuration.
+
+## One-off runs through the same scheduler
+
+For an existing factory that does not declare `runRequests`, the loader takes
+that field directly from `config.json`; business code need not change. A factory
+can instead explicitly supply its own `runRequests` declarations alongside its
+`schedules`. For example, the extension's `config.json` can include:
+
+```json
+{
+  "runRequests": [
+    { "id": "example-trial-1", "scheduleId": "example-tick", "at": "now" }
+  ]
+}
+```
+
+Apply the configuration with `reload_extensions` (or the existing `/reload`).
+The target must be an enabled schedule belonging to that extension. `at` is
+`"now"` or an absolute epoch-millisecond timestamp. There is no configuration
+watcher or separate CLI/HTTP execution entry point.
+
+The owner persists a background `imessage.schedule` task for the request, then
+uses the same occurrence wrapper and business conversation as recurring runs.
+A busy target delays the one-off until its active occurrence settles. The request
+ID and resolved deadline survive reload/restart, including after completion.
+Reuse the same declaration to recover it; use a new ID for a new intended run.
+Conflicting reuse fails rather than changing an existing request.
+
+Removing a request prevents future admission, not an already admitted business
+task. Re-adding a consumed ID never runs it again. Business per-date dedupe and
+delivery receipts still apply; a trial does not force another English card.
+Regular task IDs and deadlines do not move. Historical operator runs remain
+stored, but startup `--run-scheduled` flags are no longer accepted.
+
+Removing an extension disables future schedule admission and removes its tools
+and prompt sections, not current calls or historical records. Removed task code
+is conservatively retained in memory until restart, because an old running call
+can still admit children. Restart fails explicitly if unfinished work needs
+missing task code or a missing schedule extension.

package/examples/workspace-extensions/system-context/index.ts

@@ -0,0 +1,69 @@
+import type * as FileSystem from "node:fs/promises";
+import type * as Paths from "node:path";
+import type { defineExtension as DefineExtension, section as Section } from "@earendil-works/pi-durable";
+
+const { constants, open } = require("node:fs/promises") as typeof FileSystem;
+const { resolve } = require("node:path") as typeof Paths;
+/** Per-file byte budget for System summary; dated history is never loaded here. */
+
+async function readSummary(path: string, maxBytes: number, boundary: string) {
+	let file: Awaited<ReturnType<typeof open>> | undefined;
+	try {
+		file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+		if (!(await file.stat()).isFile())
+			return "[System summary unavailable: expected a regular summary file.]";
+		const buffer = Buffer.alloc(maxBytes + 1);
+		let bytesRead = 0;
+		while (bytesRead < buffer.length) {
+			const result = await file.read(buffer, bytesRead, buffer.length - bytesRead, bytesRead);
+			if (!result.bytesRead) break;
+			bytesRead += result.bytesRead;
+		}
+		const truncated = bytesRead > maxBytes;
+		// A streaming decode drops only an incomplete trailing UTF-8 character at the byte boundary.
+		const text = new TextDecoder("utf-8", { fatal: true })
+			.decode(buffer.subarray(0, Math.min(bytesRead, maxBytes)), { stream: truncated })
+			.trim();
+		const end = boundary ? text.indexOf(boundary) : -1;
+		if (end >= 0) return text.slice(0, end).trim();
+		return truncated
+			? `${text}\n\n[System summary exceeded the ${maxBytes}-byte summary limit; the rest was not loaded. Read the full file on demand.]`
+			: text;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return "";
+		return "[System summary summary unavailable.]";
+	} finally {
+		await file?.close();
+	}
+}
+
+module.exports = async ({
+	workingDir,
+	config,
+	defineExtension,
+	section,
+}: {
+	workingDir: string;
+	config: Record<string, unknown>;
+	defineExtension: typeof DefineExtension;
+	section: typeof Section;
+}) => {
+	if (
+		typeof config.summaryFile !== "string" ||
+		!config.summaryFile ||
+		!Number.isSafeInteger(config.maxBytes) ||
+		(config.maxBytes as number) <= 0 ||
+		(config.maxBytes as number) > 65536 ||
+		typeof config.boundary !== "string"
+	)
+		throw new Error("System context requires summaryFile, maxBytes (1..65536) and boundary");
+	const summary = await readSummary(
+		resolve(workingDir, config.summaryFile),
+		config.maxBytes as number,
+		config.boundary,
+	);
+	return defineExtension({
+		name: "system-context",
+		sections: [section("system_configuration", () => summary || undefined)],
+	});
+};

package/examples/workspace-extensions/system-context/package.json

@@ -0,0 +1,3 @@
+{
+	"type": "commonjs"
+}

package/ops/README.md

@@ -0,0 +1,250 @@
+# Operations: installation, deployment and restart
+
+The owner has authorized deployment after each completed change, including
+verification, plus committing and pushing each completed intended project change
+after the required checks. Do not ask again for routine deployment or commit/push
+approval in that scope. Stage explicit intended paths; exclude unrelated drafts,
+temporary files and credentials. Verify the pushed remote revision; stop on a
+rejected push, never force push. This does not authorize paid probes, test messages,
+data cleanup or unrelated service changes. Stop for a new material safety or
+data-integrity risk.
+Never run old/new pipelines concurrently or use production data in tests.
+Implementation readiness and open decisions are tracked in GitHub #33.
+
+For ordinary updates, use [Routine deployment and restart](#routine-deployment-and-restart).
+The one-time legacy migration is archived at tag `archive/legacy-migration` (ADR 0043).
+
+## Prerequisites
+
+- macOS, Node >=22.22.2, Python 3 and authenticated Pi models.
+- Terminal/Node Full Disk Access for Messages' SQLite database; Automation and
+  Accessibility permissions for Messages.app/rich-text sends; `/usr/bin/sips`.
+- The existing memory CLI at `WORKING_DIR/skills/file-memory/memory_cli.py`.
+- The installed `pi-browser` CLI and its pinned Playwright runtime. Run
+  `pi-browser setup` when needed and authorized; preflight never installs it. Preflight
+  resolves the wrapper in Pi's agent `bin/`, or a preflight-only
+  `PI_BROWSER_CLI_PATH` override, and runs `--version` with temporary browser state
+  that is removed afterward. A wrapper whose `doctor` reports MISSING is not ready.
+  Version readiness does not prove browser privacy, login or per-chat isolation.
+- Reviewed native SQLite and image dependencies. Install dependencies with
+  `npm ci --ignore-scripts`; if native binaries are missing, review and approve
+  their build/download separately rather than silently enabling install scripts.
+
+Safe local checks (no live models/messages/workspace):
+
+```sh
+npm run check
+npm test
+node --experimental-strip-types ops/preflight.mjs
+node --experimental-strip-types src/cli.ts --help
+```
+
+For changes to the built-in browser, also run
+`node --experimental-strip-types ops/browser-smoke.mjs`. This uses real headless
+Chrome and the installed pinned CLI with temporary HOME/profiles, loopback pages
+and synthetic login state; it never opens a personal profile or sends a message.
+See [browser isolation and retention](../docs/browser.md).
+
+`WORKING_DIR`, `WEB_HOST`, `WEB_PORT`, `WEB_ENABLED` and `MESSAGES_DB_PATH`
+are explicit host configuration. `npm start`, the
+executable CLI and the generated launchd job enable Node's environment proxy
+support. `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` (and their lowercase forms) and
+`NODE_OPTIONS` are retained when generating the job; review them before install.
+CLI execution loads the current directory's `.env` using Node's parser; existing
+environment values take precedence and a missing file is allowed. Set
+`DOTENV_CONFIG_PATH` for another file. Module imports and `--help` do not load it.
+Other read errors stop startup without printing file contents. `.env` is trusted
+operator configuration, not a message attachment. Keep it private and out of Git.
+Installation pins its current directory as the job's working directory, so the
+same configuration path is used at launch. Selected environment values in the
+plist are a snapshot; regenerate a reviewed job to change those overrides.
+The job also pins the selected Pi agent directory as an absolute
+`PI_CODING_AGENT_DIR` (including the default). Relative paths and `~` are resolved
+at installation, after `.env` loading, so daemon HOME/cwd changes do not select a
+different auth.json, models.json, settings.json or skill root. This selects a
+configuration location; it does not copy credentials or grant access to it.
+
+No proxy credentials are printed by installation. Application startup configures
+one process-owned Undici transport after `.env` loading and before model/auth
+refresh. Global Pi `httpProxy` supplies HTTP/HTTPS defaults; explicit environment
+values win, lowercase proxy/bypass values take precedence, and `NO_PROXY` is
+honored. Project-local `httpProxy` is ignored. `/reload` applies changed settings
+for subsequent requests while old clients drain active requests. Shutdown stops
+messaging and Harness work before releasing owned HTTP resources. Standalone
+callers with injected runtimes retain transport control; deliberate fetch
+overrides and dispatchers owned by other callers are not replaced on cleanup.
+
+Pi settings in the agent directory and `WORKING_DIR/.pi/settings.json` supply
+request policy; `/reload` refreshes it. `retry.provider.timeoutMs` overrides the
+provider request timeout, otherwise `httpIdleTimeoutMs` supplies that default
+(300000 ms; 0 uses Pi's effectively unlimited value). This forwards a request
+option to supporting providers. Separately, application HTTP transport uses
+`httpIdleTimeoutMs` for native header/body inactivity timers; 0 disables those
+timers. An explicit provider request timeout can still limit a request when
+socket-idle timers are disabled. Provider retry limits/delay caps and `retry`
+generation policy are executed by Pi/Durable; transport remains SSE. These do
+not replace the old host activity timer, prompt maximum-duration or
+compaction-deadline behavior.
+
+Web defaults to localhost:7750 and has no authentication. Never expose it to
+untrusted networks.
+
+Lifecycle logs use ISO timestamps on stdout/stderr: application startup (PID,
+Node version and workspace), agent readiness/reload, the actual Web bind address
+or disabled state, messaging readiness (cursor and poll/compaction intervals),
+shutdown signal, resource cleanup and failures. Readiness is logged only after
+the corresponding initialization succeeds; it is not a model or delivery health
+check. Idle polls do not produce log lines. These lifecycle entries do not include
+message text, tool arguments or proxy/auth configuration.
+The generated launchd job redirects both streams to `WORKING_DIR/service.log`.
+Foreground runs use the terminal or the controller's selected redirection; the
+application does not open a second log file.
+
+## npm publishing
+
+The public package contains compiled JavaScript and Web assets, not a TypeScript
+executable under `node_modules`. `npm pack` builds through `prepack`;
+`npm run test:package` verifies the packed executable and inert installer in a
+temporary HOME/workspace without models or Messages.
+
+`.github/workflows/publish.yml` uses the existing npm trusted publisher with
+GitHub OIDC, Node 24 and `id-token: write`; no local npm login or token is needed.
+It runs the full checks, tests and package smoke before publishing with provenance.
+Future releases push a matching `v<package-version>` tag. To publish an existing
+version after fixing packaging, dispatch the workflow on main with that exact
+version; never move an already published GitHub tag.
+
+```sh
+gh workflow run publish.yml --ref main -f version=1.0.0
+```
+
+An installed npm service runs `dist/cli.js`; source deployments continue to use
+`src/cli.ts`. Package installation does not start or reload a service.
+
+## Service identity
+
+New `install` output uses `org.pi-imessage.service` and
+`org.pi-imessage.service.plist`. For an installed
+`me.changchen.pi-imessage-durable` job, privately preserve its plist/environment,
+gracefully stop and unload that exact controller, verify PID/lock/port release,
+then write and load the reviewed neutral job. Do not leave the old KeepAlive
+controller loaded or start a Terminal copy alongside launchd. A foreground
+Terminal service with no old-label job needs no controller change. Never rename
+unrelated legacy jobs as part of this migration.
+
+## Routine deployment and restart
+
+### Choose the smallest operation
+
+| Change | Action |
+|---|---|
+| Server, agent, transport or imported TypeScript | Restart from a new release directory; verify the change. |
+| Web `app.js` / `style.css` only | Verify the served assets; no restart (the file cache checks metadata). |
+| Documentation only | Commit and push; no reload or restart. |
+| Configuration supported by `/reload` | Reload; restart only for startup-only configuration. Never send an iMessage to trigger it. |
+
+Deploying means the change is live and verified, then committed and pushed.
+
+### Release directories
+
+The service runs a fixed commit, never the main checkout:
+
+```sh
+SHA=$(git -C /Users/clawbot/pi-imessage-next rev-parse origin/main)
+RELEASE=/Users/clawbot/pi-imessage-releases/$SHA
+git -C /Users/clawbot/pi-imessage-next worktree add --detach "$RELEASE" "$SHA"
+(cd "$RELEASE" && npm ci --ignore-scripts && node --experimental-strip-types ops/preflight.mjs)
+```
+
+Never edit a release directory; rollback is a routine restart from the previous
+one. Keep the latest three; remove older ones with `git worktree remove` (no
+`--force`) when no process or plist uses them. A release directory has no `.env`:
+set `DOTENV_CONFIG_PATH` to the main checkout's `.env`.
+
+### 1. Identify the running service
+
+```sh
+launchctl list | grep -Ei 'pi-imessage|pi-web' || true
+lsof -nP -iTCP:7750 -sTCP:LISTEN          # take PID from here, never from notes
+ps -p "$PID" -o pid,ppid,lstart,command
+lsof -a -p "$PID" -d cwd,1,2 -Fn
+```
+
+The claw baseline is a **Terminal foreground process** (not launchd) running from
+a release directory, with `WORKING_DIR=~/.pi/imessage-next`,
+`PI_CODING_AGENT_DIR=~/.pi/agent`, Node 22, logs in `WORKING_DIR/service.log`, and
+the owner-selected unauthenticated bind `0.0.0.0:7750` (trusted networks only).
+A similarly named Pi web job does not control this service. Do not switch
+controllers, install launchd or upgrade Node during a routine restart.
+
+### 2. Record the baseline (ADR 0038)
+
+Restart at any time; no running work defers it. Before stopping, record the
+counts of `sending` / `unknown` receipts from `/chat/data` (counts only, no chat
+text). Never reset cursors, delete state or replay uncertain sends. Do not use
+`/health/model`: it is a paid request.
+
+### 3. Run one private controller
+
+From a chat, the assistant calls `restart_service` with the full commit hash of
+the prepared release directory (ADR 0052). The host writes the controller
+directory below itself and opens the controller only after that tool call has
+settled; the call returns the directory and the next call verifies (step 4).
+The manual procedure below is for operators and for a cold start when no
+service is running.
+
+In a `mktemp -d /tmp/pi-imessage-restart.XXXXXX` directory with `umask 077`:
+
+- `environment.sh`: shell-quoted exports of the running process's `WORKING_DIR`,
+  `PI_CODING_AGENT_DIR`, `DOTENV_CONFIG_PATH`, Web/DB overrides, proxy variables
+  (both cases), `NODE_OPTIONS`, search keys, HOME, locale, `TZ` and PATH (keep
+  `~/.pi/agent/bin` and the Node directory). Write it directly; never print
+  values, `ps eww` output or credentials.
+- `control.sh`: shell-quoted `OLD_PID`, `OLD_STARTED` (exact `ps -o lstart=`),
+  `EXPECTED_COMMAND`, `REPO` (the release directory), `NODE`, `WORKING_DIR`,
+  `WEB_PORT` and `LOG_FILE`.
+- `restart.command`: a copy of [`ops/restart.command`](restart.command) from the
+  release directory. It checks the old PID's start time and command, sends
+  SIGTERM, waits up to 30 s, refuses to start while the lock or port is held,
+  writes `controller.log` and `new.pid`, deletes `environment.sh` and then
+  `exec`s the new service process.
+
+Launch it once with `chmod 700` and `open -a Terminal "$DEPLOY_DIR/restart.command"`
+(`osascript` `do script` times out on claw). The separate Terminal keeps the
+controller alive when the initiating agent's own turn is interrupted. For a
+launchd controller, use that job's lifecycle instead; never `launchctl kickstart -k`
+from inside the service.
+
+A chat that writes its own controller through `bash` instead of
+`restart_service` must end that call right after `open`: no `sleep`, polling or
+verification in the same call. Tools are replay-safe by default (ADR 0041), so a
+call still running when the controller stops the service reruns on every start,
+launches another controller and loops (#39). Verify in a later call.
+
+### 4. Verify
+
+In a new tool call, read `controller.log`, `new.pid`, the service log and the
+listener first. Never launch the controller twice before the first outcome is
+known. Require:
+
+1. Old PID gone; exactly one new process and listener, cwd in the release
+   directory.
+2. Fresh `Application starting`, `Agent ready`, `Web server listening`,
+   `Messaging ready` and `Application started`; no startup error.
+3. Root and changed endpoints return 200; check UI changes in a browser.
+4. Interrupted work continues; scheduler deadlines are unchanged; receipt
+   counts change only by new sends and sends interrupted by the stop. After
+   `restart_service`, the old log shows `Restart requested` with the
+   controller directory.
+
+On a timeout, lock, occupied port or startup failure, stop and report it. Do not
+force-kill, steal the lock, reinstall dependencies or restore a workspace snapshot.
+
+Routine deployments do not run the live smoke. Only when the owner authorizes a
+paid model request and a real message, run
+`node --experimental-strip-types ops/smoke.ts --live --chat CHAT_GUID`: it checks
+`/health/model`, waits for the operator's message from the device and reports
+the new reply's receipt. Never resend a reply that is not `sent`.
+Record the deployment (time, commit, PID, checks, unverified limits) with
+`pi-memory`, delete the `/tmp` controller directory, and report **deployed and
+verified** or the blocker. Release gates and evidence live in GitHub #33.

package/ops/preflight.mjs

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import Database from "better-sqlite3";
+import sharp from "sharp";
+
+assert.equal(process.platform, "darwin", "Messages transport requires macOS");
+const version = process.versions.node.split(".").map(Number);
+assert.ok(version[0] > 22 || (version[0] === 22 && (version[1] > 22 || (version[1] === 22 && version[2] >= 2))), "Node 22.22.2 or newer is required");
+const database = new Database(":memory:");
+try { assert.equal(database.prepare("SELECT 1 AS value").get().value, 1); } finally { database.close(); }
+assert.equal((await sharp({ create: { width: 1, height: 1, channels: 3, background: "white" } }).jpeg().toBuffer()).length > 0, true);
+const browserState = await mkdtemp(join(tmpdir(), "imessage-browser-preflight-"));
+try {
+  // doctor can report MISSING with exit 0; --version must reach the installed runtime.
+  await promisify(execFile)(process.env.PI_BROWSER_CLI_PATH ?? join(getAgentDir(), "bin", "pi-browser"), ["--version"], {
+    env: { ...process.env, PI_BROWSER_HOME: browserState }, timeout: 10000, maxBuffer: 65536,
+  });
+} catch (error) {
+  throw new Error("Browser CLI readiness failed; install the pinned runtime with pi-browser setup", { cause: error });
+} finally {
+  await rm(browserState, { recursive: true, force: true });
+}
+console.log("Preflight passed: macOS, Node, native SQLite/image dependencies and browser CLI runtime. No model, Messages or production workspace was accessed.");