pgserve 2.0.7 → 2.1.0

package/.genie/wishes/canonical-pgserve-pm2-supervision/WISH.md

@@ -0,0 +1,290 @@
+# Wish: Canonical pgserve + PM2 supervision across genie/omni/pgserve
+
+| Field | Value |
+|-------|-------|
+| **Status** | DRAFT |
+| **Slug** | `canonical-pgserve-pm2-supervision` |
+| **Date** | 2026-04-30 |
+| **Author** | genie-configure |
+| **Appetite** | medium-large |
+| **Repos touched** | `namastexlabs/pgserve`, `automagik-dev/omni`, `automagik-dev/genie`, `namastexlabs/genie-configure` (brain only) |
+| **Design** | _No brainstorm — direct wish from operational pain (live debugging session 2026-04-30)_ |
+
+## Summary
+
+Canonicalize **pgserve as the single, central, pm2-supervised database server** that every service in the stack connects to. Make `genie serve` and `omni-api`/`omni-nats` peer-equal pm2 services that boot under the same hardening, register via their own `*-install` commands, and consume pgserve through its CLI.
+
+**End-state pm2 list:**
+
+```
+┌──────────────────────────────────────────┐
+│  pm2 supervisor                          │
+├──────────────────────────────────────────┤
+│  1. pgserve         ← NEW (canonical PG) │
+│  2. omni-api        ← existing, reconfig │
+│  3. omni-nats       ← existing            │
+│  4. genie-serve     ← NEW                 │
+│                                           │
+│  + pm2-logrotate (module, already there) │
+└──────────────────────────────────────────┘
+```
+
+## Trigger
+
+Live debugging session, 2026-04-30:
+
+1. WhatsApp DM lands at omni-api ✅
+2. omni dispatches to NATS ✅
+3. **bridge silently dropped — `genie serve` was running in a foreground bash on `/dev/pts/24` and died when the shell closed** ❌
+4. Operator (Felipe) sent multiple test messages; nothing came back. Recovery required SSH into the server, kill the orphan, re-launch `genie serve` manually.
+
+Earlier in the same session: omni-api was hardened with pm2 + log rotation as part of `omni-lifecycle-hardening` (archived wish). Genie was supposed to follow but never did. The asymmetry is the root cause of every "the bridge is gone again" incident.
+
+Same session also revealed: **multiple pgserve instances running in parallel** (3 distinct postgres-server.js processes, each on a different port). Every service that wants Postgres spins its own embedded pgserve. No single source of truth for connection strings; data dirs scattered across `~/.omni/data/pgserve/`, `~/.genie/data/pgserve/`, and `/dev/shm/pgserve-*`.
+
+## Scope
+
+### IN
+
+1. **pgserve gets `install` + `serve` commands.** New subcommands in the pgserve CLI:
+   - `pgserve install` — idempotent pm2 registration with hardened defaults (mirror omni's `PM2_HARDENED_DEFAULTS`); creates `~/.pgserve/config.json` with canonical port + data dir.
+   - `pgserve serve` — long-lived process pm2 invokes (currently `bin/pgserve-wrapper.cjs daemon`, just renamed for clarity).
+   - `pgserve status` / `pgserve url` / `pgserve port` — discovery API for downstream installers.
+   - `pgserve uninstall` — `pm2 delete pgserve` + leave data dir intact.
+
+2. **Hardened pm2 defaults shared.** Extract `PM2_HARDENED_DEFAULTS` and `buildPm2StartArgs` from `omni/packages/cli/src/pm2.ts` into a small shared shape every installer copies. Constants stay duplicated across repos (avoids a new shared package), but the values are pinned in this wish:
+   ```
+   maxRestarts: 10
+   restartDelayMs: 5000
+   maxMemoryRestart: 2G (api/serve), 1G (nats)
+   killTimeoutMs: 20000
+   logDateFormat: YYYY-MM-DD HH:mm:ss.SSS
+   logs: ~/.<service>/logs/<name>-{out,error}.log
+   ```
+
+3. **`genie install` (NEW).** Mirror of `omni install`:
+   - Calls `pgserve install` first (no-op when already registered).
+   - Reads `pgserve url` to get the canonical connection string.
+   - Registers `genie-serve` under pm2 with hardened defaults.
+   - Writes `~/.genie/config.json` with `databaseUrl: <pgserve url>`.
+   - Idempotent; safe to re-run.
+   - Adds `--non-interactive` for CI/install.sh.
+
+4. **`omni install` reconfigured.** Stops embedding pgserve inside `omni-api`'s lifecycle:
+   - Calls `pgserve install` first.
+   - Migration: pg_dump from current `~/.omni/data/pgserve/` → restore into canonical pgserve. Stop and pm2-delete the embedded pgserve.
+   - Update `omni-api`'s `DATABASE_URL` env to point at canonical pgserve.
+   - Existing `omni doctor` already audits this; extend it to check connection-string-points-at-canonical-pgserve.
+
+5. **`install.sh` updates.** Both repos' bootstrap scripts route through the new pattern:
+   - `omni/install.sh`: install pgserve@latest globally → `pgserve install` → `omni install`.
+   - `genie/install.sh`: install pgserve@latest globally → `pgserve install` → `genie install`.
+
+6. **Brain documentation.** Add to genie-configure's brain:
+   - `Configuration & Routing/canonical-pgserve-pm2.md` — architecture map: 4 pm2 services, pgserve as central PG, install ordering.
+   - `Runbooks/recover-pm2-stack.md` — how to diagnose / restart any of the 4 services; `pm2 resurrect` after reboot.
+   - `_decisions/2026-04-30-canonical-pgserve.md` — ADR documenting why one pgserve instead of N embedded.
+
+### OUT
+
+- **No replacement of pgserve with vanilla postgres.** pgserve stays; we only canonicalize how it's deployed.
+- **No port migration tooling for third-party consumers.** If someone else's app talks to omni's old pgserve port directly, they update on their own.
+- **No automatic uninstall of legacy embedded pgserve data dirs.** Migration copies forward; the old data stays on disk until operator removes it (avoids accidental data loss).
+- **No multi-host pgserve cluster.** Single host only. Multi-host pgserve is a separate, much larger wish.
+- **No systemd / launchd path.** pm2 is the single supervisor for this iteration. Aegis-runtime wish covers a future systemd-user variant.
+
+## Decisions
+
+| # | Decision | Rationale |
+|---|---|---|
+| 1 | pgserve owns the install + serve subcommands | Other services should NOT know how to register pgserve under pm2 — that's pgserve's responsibility. Same pattern as omni owning omni-api/nats. |
+| 2 | Idempotent `*-install` everywhere | Every installer can be re-run without harm. Re-running `pgserve install` after it's already registered exits 0 with "already installed." Same for `omni install` and `genie install`. |
+| 3 | Cross-repo install dependency: pgserve → omni & genie | omni and genie shell out to `pgserve install` first. They DON'T re-implement pgserve registration. Tighter coupling, but simpler than a shared package, and avoids "two installers disagree on hardening defaults." |
+| 4 | `--interpreter none` for pm2 launches | Both genie and omni binaries use `#!/usr/bin/env bun` shebangs. `--interpreter bun` triggers pm2's ESM/require crash on top-level await. Shebang resolution side-steps the issue. **Empirically validated 2026-04-30** during the manual genie-serve pm2 registration. |
+| 5 | `genie serve start --headless --no-tui --no-interactive` for pm2 | TUI requires a real terminal; pm2 child has no tty. Headless + no-tui matches omni-api's mode. **Empirically validated 2026-04-30.** |
+| 6 | Migration via pg_dump + restore (not file-level copy) | Data file format is sensitive to PG version; pg_dump is portable. Even with same pgserve version, dump+restore is the safe path. |
+| 7 | Single config file per service, no shared "canonical config" file | `pgserve install` writes `~/.pgserve/config.json`; consumers read it via `pgserve url`. We don't introduce a `~/.canonical/` directory or similar. The CLI is the contract. |
+| 8 | pm2-logrotate stays as a module, not a pm2 service | It's a pm2 module by design; `omni install` already configures it. `pgserve install` reuses the same pm2-logrotate (no duplicate setup). |
+
+## Success Criteria
+
+- [ ] `pgserve install` registers `pgserve` as a pm2 service with hardened defaults; idempotent on second invocation.
+- [ ] `pgserve url` returns a valid connection string that other tools can use without pgserve being CLI-imported.
+- [ ] `omni install` on a clean machine results in: `pgserve` + `omni-api` + `omni-nats` all under pm2 with green status.
+- [ ] `genie install` on a clean machine results in: `pgserve` + `genie-serve` all under pm2 with green status.
+- [ ] On a machine where both omni and genie are installed, exactly **4 pm2 services** are present (pgserve, omni-api, omni-nats, genie-serve), pgserve is shared, and both `omni doctor` and `genie doctor` are green.
+- [ ] On reboot, `pm2 resurrect` brings all 4 services back online with correct env.
+- [ ] Existing omni installs migrate without data loss: pre-migration `omni events list` content matches post-migration content.
+- [ ] `genie serve` running under pm2 survives shell closure (the bug that triggered this wish stays fixed forever).
+- [ ] `omni doctor` and `genie doctor` both gain a check: "process is registered under pm2 with hardened defaults" (yes/no with one-line remediation if no).
+- [ ] Brain entries (architecture map, runbook, ADR) merged in genie-configure.
+
+## Execution Strategy
+
+Wave-based; each wave can ship independently. Three repos, four PRs total.
+
+### Wave 1 — `pgserve` foundation (BLOCKS waves 2 & 3)
+
+**Goal:** pgserve owns its pm2 lifecycle.
+
+- Group 1.1 — `pgserve install` + `pgserve serve` + `pgserve status` + `pgserve url` + `pgserve port`. Add `--non-interactive` for CI/install.sh. New file: `src/commands/install.ts` (mirror omni's structure).
+- Group 1.2 — Tests: install idempotency, status reflects pm2 state, url/port match what install registered.
+- Group 1.3 — README: document the 4 new subcommands.
+
+**Validation:**
+```bash
+bunx pgserve install              # green; pm2 list shows `pgserve`
+bunx pgserve install              # exits 0, "already installed"
+bunx pgserve url                  # postgres://localhost:8432/postgres
+bunx pgserve status --json        # { name: "pgserve", status: "online", port: 8432, dataDir: "..." }
+pm2 list | grep pgserve           # online, max-restarts=10, etc.
+```
+
+**PR:** `namastexlabs/pgserve#???` — `feat(cli): pgserve install + pm2 supervision`.
+
+### Wave 2 — `genie install` (depends on Wave 1)
+
+**Goal:** Genie has parity with omni — `genie install` registers `genie-serve` under pm2 by calling `pgserve install` first.
+
+- Group 2.1 — New `genie install` command in `src/genie-commands/install.ts`. Calls `pgserve install`, then `pm2 start` for genie-serve with the hardened args validated in this server's manual test (`--interpreter none` + `serve start --headless --no-tui --no-interactive`).
+- Group 2.2 — Update `genie serve start` to detect when genie-serve is already pm2-supervised: print "Already managed by pm2; use `pm2 restart genie-serve`" and exit. Avoid the multi-instance lockfile dance.
+- Group 2.3 — `genie doctor` adds `pm2-supervision` check.
+- Group 2.4 — Tests for install command (with PM2 stubbed).
+- Group 2.5 — `install.sh` updated to call `pgserve install` then `genie install`.
+
+**Validation:**
+```bash
+genie install                                            # green
+pm2 list                                                 # includes pgserve + genie-serve
+genie doctor                                             # all green
+genie serve stop && genie install                        # idempotent
+# kill the shell that ran install — bridge stays alive (the original incident's reproduction)
+```
+
+**PR:** `automagik-dev/genie#???` — `feat(cli): genie install + pm2 supervision`.
+
+### Wave 3 — `omni install` reconfig (depends on Wave 1)
+
+**Goal:** Omni's installer routes through canonical pgserve instead of the embedded one.
+
+- Group 3.1 — `omni install` calls `pgserve install` before `omni-api` registration.
+- Group 3.2 — Migration handler: detect existing `~/.omni/data/pgserve/` running under omni-api → pg_dump → restore into canonical pgserve → update omni-api `DATABASE_URL` env → delete embedded pgserve from pm2 → preserve old data dir on disk (operator can `rm -rf` later when satisfied).
+- Group 3.3 — `omni doctor` adds `connection-string-canonical` check.
+- Group 3.4 — Tests for migration path (start with embedded, run install, verify omni-api connects to canonical).
+- Group 3.5 — `install.sh` updated to call `pgserve install` first.
+
+**Validation:**
+```bash
+# Fresh machine
+omni install
+pm2 list                            # pgserve + omni-api + omni-nats
+omni doctor                         # all green; connection-string-canonical=ok
+
+# Existing machine (with embedded pgserve)
+omni install                        # detects legacy, runs migration
+omni events list --limit 100        # data preserved post-migration
+pm2 list                            # pgserve + omni-api + omni-nats (no embedded pgserve)
+```
+
+**PR:** `automagik-dev/omni#???` — `feat(install): canonical pgserve + migration from embedded`.
+
+### Wave 4 — Brain ingestion (depends on Waves 1–3 merging)
+
+**Goal:** Document the canonical layout so future agents inheriting any of these servers know the pattern by reading a single file.
+
+- Group 4.1 — `brain/Configuration & Routing/canonical-pgserve-pm2.md`: architecture map; 4-service ascii diagram; pgserve discovery via `pgserve url`; install ordering.
+- Group 4.2 — `brain/Runbooks/recover-pm2-stack.md`: diagnose/restart any of the 4 services; `pm2 resurrect` after reboot; rollback to embedded pgserve (if migration goes wrong).
+- Group 4.3 — `brain/_decisions/2026-04-30-canonical-pgserve.md`: ADR; alternatives considered (vanilla postgres, systemd-user, embedded-everywhere); consequences.
+
+**PR:** `namastexlabs/genie-configure#???` — `chore(brain): canonical pgserve + pm2 supervision`.
+
+## Dependencies
+
+```
+Wave 1 (pgserve)  ──┬──→ Wave 2 (genie)
+                     ├──→ Wave 3 (omni)
+                     └──→ Wave 4 (brain — also depends on Wave 2 & 3)
+```
+
+Cross-wish: closes the operator-lockout footgun the canonical-genie-omni-wiring + omni-host-fingerprint-trust wishes paved over with workarounds. Doesn't conflict with `aegis-runtime` (separate daemon, separate supervisor).
+
+## QA Criteria
+
+- [ ] On a fresh Ubuntu 24 box: `curl … omni/install.sh | bash` results in 3 pm2 services (pgserve + omni-api + omni-nats), green doctor.
+- [ ] On the same box: `curl … genie/install.sh | bash` adds genie-serve = 4 pm2 services. pgserve shared.
+- [ ] Reboot the box: `pm2 resurrect` brings all 4 back; both doctors green; bridge subscribes to NATS without manual intervention.
+- [ ] Kill any one of the 4 services with SIGKILL: pm2 restarts it within 5 s; doctor goes red briefly then green.
+- [ ] On a machine with the OLD embedded pgserve setup: `omni install` (post-Wave-3) migrates without data loss.
+- [ ] `pgserve install` followed by `pgserve install --rotate-port 8433` correctly re-registers pgserve on the new port and updates omni-api/genie-serve env (or refuses cleanly if they're using the old port).
+- [ ] `omni-host-fingerprint-trust` pipeline (the wish that closed two days before this one) keeps working — instances flagged `requireGenieSignature: true` still get gated correctly post-migration.
+
+## Assumptions / Risks
+
+| # | Item | Risk | Mitigation |
+|---|---|---|---|
+| 1 | pgserve repo accepts the new install/serve subcommands | Low — author is in the same org | If rejected, fall back to having omni and genie register pgserve directly (loses the "owned by pgserve" property but still gets us to 4 services). |
+| 2 | Migration from embedded pgserve preserves all data | Medium — pg_dump on a live system + connection-string switch is non-trivial | Stage in Wave 3 with `--dry-run` first; document rollback. Take filesystem snapshot before running on production. |
+| 3 | pm2 ESM/await crash with bun on future bun versions | Low | `--interpreter none` is robust; documented Decision 4. |
+| 4 | Operators who customized their existing pgserve port will be confused | Medium | `omni doctor` and `genie doctor` add explicit "this service points at non-canonical pgserve" check with override flag. |
+| 5 | NATS port also needs canonicalization (similar split-brain risk) | Out of scope for this wish | Park as a follow-up wish if it becomes a problem. omni-nats is single-instance today via pm2 so no urgency. |
+| 6 | genie-configure (this brain) is not in the cycle | None | Wave 4 lands the docs in this repo only; no source code changes here. |
+
+## Files to Create / Modify
+
+### `namastexlabs/pgserve` (Wave 1)
+- `src/commands/install.ts` (new)
+- `src/commands/serve.ts` (new — likely a thin wrapper around the existing wrapper)
+- `src/commands/status.ts`, `src/commands/url.ts`, `src/commands/port.ts` (new)
+- `src/lib/pm2-args.ts` (new — shared pm2 launch builder, mirror of omni's)
+- `bin/pgserve-wrapper.cjs` (modify — add subcommand routing)
+- `__tests__/install.test.ts`, `__tests__/url.test.ts` (new)
+- `README.md` (modify)
+
+### `automagik-dev/genie` (Wave 2)
+- `src/genie-commands/install.ts` (new)
+- `src/genie-commands/doctor.ts` (modify — add pm2-supervision check)
+- `src/term-commands/serve.ts` (modify — detect pm2 supervision, defer)
+- `install.sh` (modify — route through `pgserve install` + `genie install`)
+- `src/lib/pm2-args.ts` (new — copy from this wish's spec)
+- Tests for install + doctor changes.
+
+### `automagik-dev/omni` (Wave 3)
+- `packages/cli/src/commands/install.ts` (modify — call `pgserve install` first; remove embedded pgserve registration)
+- `packages/cli/src/lib/migrate-from-embedded-pgserve.ts` (new)
+- `packages/cli/src/commands/doctor.ts` (modify — add canonical-connection-string check)
+- `install.sh` (modify — `pgserve install` step)
+- Tests for migration path.
+
+### `namastexlabs/genie-configure` (Wave 4)
+- `brain/Configuration & Routing/canonical-pgserve-pm2.md` (new)
+- `brain/Runbooks/recover-pm2-stack.md` (new)
+- `brain/_decisions/2026-04-30-canonical-pgserve.md` (new)
+
+## Validated Beachhead (already shipped manually)
+
+The genie-serve part is **already running under pm2** on this server as of 2026-04-30 16:08 UTC. Manual command used:
+
+```bash
+pm2 start /home/genie/.bun/bin/genie \
+  --name genie-serve \
+  --interpreter none \
+  --max-restarts 10 \
+  --restart-delay 5000 \
+  --max-memory-restart 2G \
+  --kill-timeout 20000 \
+  --log-date-format 'YYYY-MM-DD HH:mm:ss.SSS' \
+  --output ~/.genie/logs/genie-serve-out.log \
+  --error ~/.genie/logs/genie-serve-error.log \
+  -- serve start --headless --no-tui --no-interactive
+
+pm2 save
+```
+
+Wave 2 codifies this exact invocation as `genie install`. The args are pinned in Decisions 4 & 5.
+
+## See also
+
+- `omni-lifecycle-hardening` (archived) — established the omni-api pm2 hardening pattern this wish extends.
+- `aegis-runtime` (draft) — different daemon, different supervisor (launchd/systemd-user), no conflict.
+- `invincible-genie` (draft) — orthogonal: that wish is about `genie serve` self-healing; this wish is about `genie serve` being supervised in the first place. Both can ship independently.
+- `pgserve-proxy-resilience` — sets up pgserve to exit cleanly when its child dies (so a supervisor can restart it). This wish is the supervisor side of that contract.

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `pgserve` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2.0.8
+
+### Changed
+
+- Bumped embedded postgres binaries from `18.2.0-beta.16` to
+  `18.3.0-beta.17` for all four platforms (linux-x64, darwin-arm64,
+  darwin-x64, windows-x64). Picks up upstream PostgreSQL 18.3 fixes
+  and the matching `@embedded-postgres` package revision.
+- The hardcoded `pkgVersion` in `src/postgres.js` (used when binaries
+  are not yet cached and pgserve fetches them from npm) was updated
+  in lockstep with `package.json`.
+
 ## 2.0.7
 
 ### Fixed

package/README.md

@@ -200,9 +200,45 @@ psql -h "${XDG_RUNTIME_DIR:-/tmp}/pgserve" -d myapp
 psql "postgresql:///myapp?host=${XDG_RUNTIME_DIR:-/tmp}/pgserve"
 ```
 
-### Supervised by PM2
+### Supervised by PM2 — `pgserve install` (recommended)
 
-`ecosystem.config.cjs` snippet:
+`pgserve install` registers pgserve as a hardened pm2 process in one
+command. Idempotent: re-running it is a no-op when already installed.
+
+```bash
+pgserve install                    # one-shot register + start under pm2
+pgserve install --port 8442        # custom port
+pgserve install --data /data/pg    # custom data dir
+
+pgserve url                        # postgres://localhost:8432/postgres
+pgserve port                       # 8432
+pgserve status                     # pm2 + on-disk config snapshot
+pgserve uninstall                  # remove from pm2; keep data dir
+```
+
+**Hardened defaults** (tuned for production-grade Postgres workloads,
+not toy-machine values):
+
+| Flag | Default | Why |
+|------|---------|-----|
+| `--max-memory-restart` | `4G` | Postgres realistic working set: shared_buffers + autovacuum + connection backends. 1G OOM-kills under modest load. Override with `PGSERVE_MAX_MEMORY=8G pgserve install`. |
+| `--max-restarts` | `50` | Tolerates extended outages (NATS reconnect storms, host pressure). Combined with `--min-uptime`, only RAPID failures count. |
+| `--min-uptime` | `10000` ms | Restart counts against the cap only when the process crashed within 10s of starting. Healthy long-uptime crashes don't burn the budget. |
+| `--restart-delay` | `4000` ms | Initial gap between restarts. |
+| `--exp-backoff-restart-delay` | `100` → ~60000 ms | Exponential spread on repeated failures so we don't hammer pm2 + the host on persistent issues. |
+| `--kill-timeout` | `60000` ms | Postgres needs time to flush WAL on graceful shutdown; 60s headroom. |
+| `--log-date-format` | `YYYY-MM-DD HH:mm:ss.SSS` | Operator-friendly timestamps in pm2 logs. |
+| `--output` / `--error` | `~/.pgserve/logs/pgserve-{out,error}.log` | Rotates via pm2-logrotate (install separately). |
+
+Config: `~/.pgserve/config.json` (override the directory with
+`PGSERVE_CONFIG_DIR`). Memory ceiling: env-tunable via
+`PGSERVE_MAX_MEMORY` at install time.
+
+Downstream services that need a Postgres connection can shell out to
+`pgserve install` (no-op if already running) and read the canonical URL
+from `pgserve url` instead of spinning up their own embedded pgserve.
+
+#### Manual ecosystem.config.cjs (legacy)
 
 ```javascript
 module.exports = {

package/bin/pgserve-wrapper.cjs

@@ -14,6 +14,37 @@ const { spawn, execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 
+// ────────────────────────────────────────────────────────────────────────
+// canonical-pgserve-pm2-supervision wish (PR #55, issue #56)
+//
+// `pgserve install / uninstall / status / url / port` are pure node + pm2
+// wrappers — they don't need bun at all. Route them BEFORE the bun
+// resolution + health probe so install works on a machine where bun
+// hasn't self-healed yet (the chicken-and-egg case the probe was designed
+// to detect — operators should be able to set up a fresh server even when
+// the bun-postinstall failed).
+//
+// `pgserve serve` is an alias for the existing `pgserve daemon` (the
+// long-lived process pm2 invokes); we rewrite argv so postgres-server.js
+// sees the original `daemon` token.
+// ────────────────────────────────────────────────────────────────────────
+const __subcommand = process.argv[2];
+const __installSubcommands = new Set(['install', 'uninstall', 'status', 'url', 'port']);
+if (__subcommand && __installSubcommands.has(__subcommand)) {
+  const cli = require(path.join(__dirname, '..', 'src', 'cli-install.cjs'));
+  process.exit(
+    cli.dispatch(__subcommand, process.argv.slice(3), {
+      scriptPath: path.join(__dirname, 'postgres-server.js'),
+    }),
+  );
+}
+if (__subcommand === 'serve') {
+  // Alias `serve` → `daemon` so the wish's canonical command name maps
+  // cleanly to the existing long-lived process. Replacing argv preserves
+  // any flags the operator (or pm2) passed after `serve`.
+  process.argv[2] = 'daemon';
+}
+
 // Detect platform
 const isWindows = process.platform === 'win32';
 const bunBin = isWindows ? 'bun.exe' : 'bun';
@@ -53,6 +84,8 @@ if (!bunPath) {
   process.exit(1);
 }
 
+const scriptPath = path.join(__dirname, 'postgres-server.js');
+
 // Pre-flight health check: verify bun can actually execute.
 //
 // When pgserve is installed via `bun install` (as a global or transitive dep),
@@ -67,8 +100,6 @@ if (!bunPath) {
 // If self-heal also fails, surface the real error instead of hanging later.
 ensureBunHealthy(bunPath);
 
-const scriptPath = path.join(__dirname, 'postgres-server.js');
-
 /**
  * Verify the selected bun binary can execute. If it fails with the known
  * "postinstall script was not run" signature, attempt a one-shot repair via

package/bin/postgres-server.js

@@ -310,7 +310,14 @@ pgserve - Embedded PostgreSQL Server
 True concurrent connections, zero config, auto-provision databases.
 
 USAGE:
-  pgserve [options]
+  pgserve [options]                 # foreground server
+  pgserve install [--port N]        # register under pm2 (idempotent)
+  pgserve serve                     # alias for "pgserve daemon"
+  pgserve status [--json]           # report pm2 + config state
+  pgserve url                       # print canonical postgres:// URL
+  pgserve port                      # print canonical port
+  pgserve uninstall                 # remove from pm2 (keep data)
+  pgserve daemon [stop]             # singleton daemon (Unix socket)
 
 OPTIONS:
   --port <number>    PostgreSQL port (default: 8432)

package/bun.lock

@@ -16,21 +16,21 @@
         "pg": "^8.16.3",
       },
       "optionalDependencies": {
-        "@embedded-postgres/darwin-arm64": "18.2.0-beta.16",
-        "@embedded-postgres/darwin-x64": "18.2.0-beta.16",
-        "@embedded-postgres/linux-x64": "18.2.0-beta.16",
-        "@embedded-postgres/windows-x64": "18.2.0-beta.16",
+        "@embedded-postgres/darwin-arm64": "18.3.0-beta.17",
+        "@embedded-postgres/darwin-x64": "18.3.0-beta.17",
+        "@embedded-postgres/linux-x64": "18.3.0-beta.17",
+        "@embedded-postgres/windows-x64": "18.3.0-beta.17",
       },
     },
   },
   "packages": {
-    "@embedded-postgres/darwin-arm64": ["@embedded-postgres/darwin-arm64@18.2.0-beta.16", "", { "os": "darwin", "cpu": "arm64" }, "sha512-wnswaF+uDvGeitqajJ8v8xOG4ttFrzixElwKNe2MIxBXSLWPV3xhi6tBY0Sjw8Lmiu6UG9vNLFZSjHPrIeokBg=="],
+    "@embedded-postgres/darwin-arm64": ["@embedded-postgres/darwin-arm64@18.3.0-beta.17", "", { "os": "darwin", "cpu": "arm64" }, "sha512-Pvrej3Xz5flfyVc9mchVfekrKoTJyvPtM3U0vjuXamZkRKmi+inP2zRmnmzYecIVbr7Zhu82xbsCENMXrwMp9Q=="],
 
-    "@embedded-postgres/darwin-x64": ["@embedded-postgres/darwin-x64@18.2.0-beta.16", "", { "os": "darwin", "cpu": "x64" }, "sha512-u9WtTPxRuO0uOny5IniXHSDaLmtOujwzDoExIV/jFT0Fu8SzpX7wdoPbsSPBLgyQWdr/nPA77K9QI4r6P1/fKA=="],
+    "@embedded-postgres/darwin-x64": ["@embedded-postgres/darwin-x64@18.3.0-beta.17", "", { "os": "darwin", "cpu": "x64" }, "sha512-MVWe+C47pPoMD9LlIWGQkvZ5Xsu3IBo54CYqnIps/Z1byMIUBNc7y/dZ3mfqEwiCbVDVqirG0CU462xnrSEfKA=="],
 
-    "@embedded-postgres/linux-x64": ["@embedded-postgres/linux-x64@18.2.0-beta.16", "", { "os": "linux", "cpu": "x64" }, "sha512-BIt485ioL8/AwDgw37IcdraOfRgHNDOtGM6Hh63vnNaUAG4Z0qtJd5zXS5fr2wZTEsYHyC5PC60k7zkCRZXSzg=="],
+    "@embedded-postgres/linux-x64": ["@embedded-postgres/linux-x64@18.3.0-beta.17", "", { "os": "linux", "cpu": "x64" }, "sha512-8orSD6NNopSLtjqir4dWQBrj+g8j1eJjWd9mB60A3xbWMzIBIPQpzT7XzbacW9YFSl/DejOLnRXfff+Wr13Tgw=="],
 
-    "@embedded-postgres/windows-x64": ["@embedded-postgres/windows-x64@18.2.0-beta.16", "", { "os": "win32", "cpu": "x64" }, "sha512-Sj6GhCZrvtMwchATEtWuEmexEBWpRNMHPTUHsqPuyDrHX/XgKfpIxz2/AMHa4sp7SZ0JOHGouH8AFIVsWQrQsQ=="],
+    "@embedded-postgres/windows-x64": ["@embedded-postgres/windows-x64@18.3.0-beta.17", "", { "os": "win32", "cpu": "x64" }, "sha512-kDC5aBsmhWDjeQjj2V4g+Bk+pMeDU27b7l0rBbaKgtt2gsNmCB34ULg/5cqs2kqUKSk/tiGMHKCNE+zQZ+s4rg=="],
 
     "@emnapi/core": ["@emnapi/core@1.7.1", "", { "dependencies": { "@emnapi/wasi-threads": "1.1.0", "tslib": "^2.4.0" } }, "sha512-o1uhUASyo921r2XtHYOHy7gdkGLge8ghBEQHMWmyJFoXlpU58kIrhhN3w26lpQb6dspetweapMn2CSNwQ8I4wg=="],
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "2.0.7",
+  "version": "2.1.0",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",
@@ -42,10 +42,10 @@
   },
   "homepage": "https://github.com/namastexlabs/pgserve#readme",
   "optionalDependencies": {
-    "@embedded-postgres/darwin-arm64": "18.2.0-beta.16",
-    "@embedded-postgres/darwin-x64": "18.2.0-beta.16",
-    "@embedded-postgres/linux-x64": "18.2.0-beta.16",
-    "@embedded-postgres/windows-x64": "18.2.0-beta.16"
+    "@embedded-postgres/darwin-arm64": "18.3.0-beta.17",
+    "@embedded-postgres/darwin-x64": "18.3.0-beta.17",
+    "@embedded-postgres/linux-x64": "18.3.0-beta.17",
+    "@embedded-postgres/windows-x64": "18.3.0-beta.17"
   },
   "devDependencies": {
     "eslint": "^9.39.1",

package/src/cli-install.cjs

@@ -0,0 +1,412 @@
+/**
+ * pgserve install / uninstall / status / url / port subcommands.
+ *
+ * Wave 1 of the canonical-pgserve-pm2-supervision wish (PR #55, issue #56).
+ *
+ * These subcommands let pgserve own its pm2 lifecycle. Other services that
+ * need a Postgres connection (omni, genie, future) shell out to:
+ *
+ *     pgserve install        # idempotent, registers under pm2
+ *     pgserve url            # postgres://localhost:8432/postgres
+ *
+ * instead of spinning up their own embedded pgserve. End-state: a single
+ * shared pgserve under pm2 with hardened defaults, consumed by everyone.
+ *
+ * This module intentionally lives outside `bin/postgres-server.js` because
+ * none of these subcommands need bun (or a running PG backend) — they are
+ * filesystem + pm2 wrappers. Keeping them here means `pgserve install`
+ * works even when bun isn't healthy yet (the wrapper's bun-probe would
+ * otherwise block the install path).
+ */
+
+'use strict';
+
+const { spawnSync, execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PM2_PROCESS_NAME = 'pgserve';
+const DEFAULT_PORT = 8432;
+
+/**
+ * Hardening defaults — tuned for production-grade elasticity, NOT
+ * the toy-machine values an initial draft of the wish carried.
+ *
+ * Earlier draft pinned `maxMemory: 1G` and `maxRestarts: 10`. The
+ * operator who reviewed PR #57 caught both as dangerously small for
+ * Postgres realistically:
+ *   - 1G OOM-kills pgserve under modest load (shared_buffers + autovacuum
+ *     workers + connection backends easily exceed 1G with a working set
+ *     of any size).
+ *   - 10 restart cap burns through during transient flakes (NATS reconnect
+ *     loop, parent-process restart, host pressure spikes) before pm2
+ *     gives up, leaving the operator with a stopped service in the
+ *     morning.
+ *
+ * Revised defaults:
+ *   - 4G memory ceiling — covers realistic load while still bounded so
+ *     a runaway query can't eat the host.
+ *   - 50 max restarts BUT only counted when min_uptime < 10s ("rapid"
+ *     failures). Healthy long-uptime crashes don't count against the cap.
+ *   - Exponential backoff on repeated failures (100ms → 60s) so we don't
+ *     hammer on persistent issues.
+ *   - 60s graceful shutdown window — Postgres needs time to flush WAL.
+ *
+ * Override at install time via env:
+ *   PGSERVE_MAX_MEMORY=8G  pgserve install
+ *
+ * These mirror the values omni and genie will use for their own pm2
+ * services. The constants are duplicated across repos (avoids a new
+ * shared package) but the values are pinned in the wish.
+ */
+const HARDENED_DEFAULTS = {
+  maxRestarts: 50,
+  minUptimeMs: 10_000,
+  restartDelayMs: 4000,
+  expBackoffRestartDelayMs: 100,
+  // pm2 caps `--exp-backoff-restart-delay` ramp at the current backoff
+  // doubling — practical max ~60s. Documented for operator clarity.
+  expBackoffMaxMs: 60_000,
+  maxMemory: process.env.PGSERVE_MAX_MEMORY || '4G',
+  killTimeoutMs: 60_000,
+  logDateFormat: 'YYYY-MM-DD HH:mm:ss.SSS',
+};
+
+function getConfigDir() {
+  return process.env.PGSERVE_CONFIG_DIR || path.join(os.homedir(), '.pgserve');
+}
+
+function getConfigPath() {
+  return path.join(getConfigDir(), 'config.json');
+}
+
+function getLogsDir() {
+  return path.join(getConfigDir(), 'logs');
+}
+
+function getDataDir() {
+  return path.join(getConfigDir(), 'data');
+}
+
+function readConfig() {
+  const p = getConfigPath();
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeConfig(config) {
+  const dir = getConfigDir();
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o755 });
+  const tmp = `${getConfigPath()}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o644 });
+  fs.renameSync(tmp, getConfigPath());
+}
+
+/**
+ * Run `pm2 jlist` and return the entry for our process, or null when not
+ * registered. Returns null on any failure (pm2 missing, JSON parse error,
+ * etc.) — callers should treat that as "not installed" rather than crash.
+ */
+function pm2GetProcess(name) {
+  try {
+    const out = execFileSync('pm2', ['jlist'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const list = JSON.parse(out);
+    return list.find((p) => p && p.name === name) || null;
+  } catch {
+    return null;
+  }
+}
+
+function pm2IsAvailable() {
+  try {
+    execFileSync('pm2', ['--version'], { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function buildPm2StartArgs({ scriptPath, port, dataDir }) {
+  const logs = {
+    out: path.join(getLogsDir(), `${PM2_PROCESS_NAME}-out.log`),
+    error: path.join(getLogsDir(), `${PM2_PROCESS_NAME}-error.log`),
+  };
+  return [
+    'start',
+    scriptPath,
+    '--name',
+    PM2_PROCESS_NAME,
+    '--interpreter',
+    'none',
+    '--max-restarts',
+    String(HARDENED_DEFAULTS.maxRestarts),
+    // `--min-uptime` makes `--max-restarts` count only RAPID failures
+    // (process crashed within N ms of starting). Healthy long-uptime
+    // crashes don't burn the budget.
+    '--min-uptime',
+    String(HARDENED_DEFAULTS.minUptimeMs),
+    '--restart-delay',
+    String(HARDENED_DEFAULTS.restartDelayMs),
+    // Exponential backoff between successive failures: starts at 100ms,
+    // doubles each crash, ramps to ~60s. Avoids hammering pm2 + the host
+    // when the underlying issue is persistent.
+    '--exp-backoff-restart-delay',
+    String(HARDENED_DEFAULTS.expBackoffRestartDelayMs),
+    '--max-memory-restart',
+    HARDENED_DEFAULTS.maxMemory,
+    '--kill-timeout',
+    String(HARDENED_DEFAULTS.killTimeoutMs),
+    '--log-date-format',
+    HARDENED_DEFAULTS.logDateFormat,
+    '--output',
+    logs.out,
+    '--error',
+    logs.error,
+    '--',
+    'daemon',
+    '--port',
+    String(port),
+    '--data',
+    dataDir,
+    '--log',
+    'warn',
+  ];
+}
+
+function ensureLogsDir() {
+  const dir = getLogsDir();
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o755 });
+}
+
+function fail(message) {
+  process.stderr.write(`pgserve: ${message}\n`);
+  process.exit(1);
+}
+
+function note(message) {
+  process.stderr.write(`pgserve: ${message}\n`);
+}
+
+function ok(message) {
+  process.stdout.write(`pgserve: ${message}\n`);
+}
+
+/**
+ * `pgserve install [--port N] [--data PATH]`
+ *
+ * Idempotent. When the process is already registered, prints a reuse line
+ * and exits 0 without touching anything. Otherwise: writes `~/.pgserve/
+ * config.json` (creating the dir if needed), then registers the process
+ * under pm2 with the hardened defaults.
+ *
+ * `scriptPath` is the path to `bin/postgres-server.js` resolved by the
+ * wrapper before this module is required (avoids re-resolving here).
+ */
+function cmdInstall(args, ctx) {
+  if (!pm2IsAvailable()) {
+    fail('pm2 not found in PATH. Install with: bun add -g pm2  (or npm i -g pm2)');
+  }
+
+  const port = parsePort(args) ?? readConfig()?.port ?? DEFAULT_PORT;
+  const dataDir = parseDataDir(args) ?? readConfig()?.dataDir ?? getDataDir();
+
+  // Idempotent: already-registered = no-op success.
+  const existing = pm2GetProcess(PM2_PROCESS_NAME);
+  if (existing) {
+    ok(`already installed (pm2 process "${PM2_PROCESS_NAME}", status=${existing.pm2_env?.status ?? 'unknown'})`);
+    // Refresh config in case install was re-run with new flags — but
+    // don't tear down the live process. Operators wanting a port change
+    // should `uninstall` then `install`.
+    writeConfig({ port, dataDir, registeredAt: readConfig()?.registeredAt ?? new Date().toISOString() });
+    return 0;
+  }
+
+  ensureLogsDir();
+  if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+
+  const pm2Args = buildPm2StartArgs({ scriptPath: ctx.scriptPath, port, dataDir });
+  const result = spawnSync('pm2', pm2Args, { stdio: 'inherit' });
+  if (result.status !== 0) {
+    fail(`pm2 start failed (exit ${result.status}). Logs: ${getLogsDir()}/${PM2_PROCESS_NAME}-error.log`);
+  }
+
+  writeConfig({ port, dataDir, registeredAt: new Date().toISOString() });
+  ok(`installed: pm2 process "${PM2_PROCESS_NAME}" on port ${port} (data: ${dataDir})`);
+  ok(`url: postgres://localhost:${port}/postgres`);
+  return 0;
+}
+
+/**
+ * `pgserve uninstall`
+ *
+ * Removes pgserve from pm2. Leaves the data directory and config file
+ * intact — operator can `rm -rf ~/.pgserve` after they're satisfied no
+ * downstream service still depends on the data.
+ */
+function cmdUninstall() {
+  const existing = pm2GetProcess(PM2_PROCESS_NAME);
+  if (!existing) {
+    ok(`not registered under pm2 (nothing to uninstall)`);
+    return 0;
+  }
+  const result = spawnSync('pm2', ['delete', PM2_PROCESS_NAME], { stdio: 'inherit' });
+  if (result.status !== 0) {
+    fail(`pm2 delete failed (exit ${result.status})`);
+  }
+  ok(`uninstalled (pm2 process removed; data dir preserved at ${getDataDir()})`);
+  return 0;
+}
+
+/**
+ * `pgserve status [--json]`
+ *
+ * Reports both pm2 state and on-disk config. Exits 0 with status info
+ * regardless of running/stopped — operators script around the JSON output.
+ * Non-zero only when the config is missing entirely (i.e. pgserve was
+ * never installed).
+ */
+function cmdStatus(args) {
+  const json = args.includes('--json');
+  const config = readConfig();
+  if (!config) {
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ installed: false })}\n`);
+    } else {
+      ok('not installed (run: pgserve install)');
+    }
+    return 1;
+  }
+  const proc = pm2GetProcess(PM2_PROCESS_NAME);
+  const status = proc?.pm2_env?.status ?? 'stopped';
+  const pid = proc?.pid ?? null;
+  const uptimeMs = proc?.pm2_env?.pm_uptime ? Date.now() - proc.pm2_env.pm_uptime : null;
+  const restarts = proc?.pm2_env?.restart_time ?? 0;
+
+  const payload = {
+    installed: true,
+    name: PM2_PROCESS_NAME,
+    status,
+    pid,
+    port: config.port,
+    dataDir: config.dataDir,
+    logsDir: getLogsDir(),
+    url: `postgres://localhost:${config.port}/postgres`,
+    uptimeMs,
+    restarts,
+    registeredAt: config.registeredAt,
+  };
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return 0;
+  }
+  process.stdout.write(`name        ${payload.name}\n`);
+  process.stdout.write(`status      ${payload.status}${payload.pid ? ` (pid ${payload.pid})` : ''}\n`);
+  process.stdout.write(`port        ${payload.port}\n`);
+  process.stdout.write(`url         ${payload.url}\n`);
+  process.stdout.write(`dataDir     ${payload.dataDir}\n`);
+  process.stdout.write(`logsDir     ${payload.logsDir}\n`);
+  if (payload.uptimeMs != null) {
+    const sec = Math.floor(payload.uptimeMs / 1000);
+    process.stdout.write(`uptime      ${sec}s\n`);
+  }
+  process.stdout.write(`restarts    ${payload.restarts}\n`);
+  process.stdout.write(`registered  ${payload.registeredAt}\n`);
+  return 0;
+}
+
+/**
+ * `pgserve url`
+ *
+ * Discovery API. Prints the canonical connection string. Downstream
+ * installers (genie install, omni install) call this to learn where to
+ * connect, instead of hardcoding a port.
+ */
+function cmdUrl() {
+  const config = readConfig();
+  if (!config) {
+    fail('not installed (run: pgserve install)');
+  }
+  process.stdout.write(`postgres://localhost:${config.port}/postgres\n`);
+  return 0;
+}
+
+/** `pgserve port` — print the canonical port. */
+function cmdPort() {
+  const config = readConfig();
+  if (!config) {
+    fail('not installed (run: pgserve install)');
+  }
+  process.stdout.write(`${config.port}\n`);
+  return 0;
+}
+
+function parsePort(args) {
+  const i = args.indexOf('--port');
+  if (i < 0) return null;
+  const v = args[i + 1];
+  if (!v) fail('--port requires a value');
+  const n = Number.parseInt(v, 10);
+  if (!Number.isInteger(n) || n < 1 || n > 65535) fail(`invalid --port "${v}"`);
+  return n;
+}
+
+function parseDataDir(args) {
+  const i = args.indexOf('--data');
+  if (i < 0) return null;
+  const v = args[i + 1];
+  if (!v) fail('--data requires a value');
+  return path.resolve(v);
+}
+
+/**
+ * Entry point invoked by the wrapper. Returns the exit code. Throws on
+ * unknown subcommand so the wrapper's normal flow can take over (the
+ * router treats any non-recognized subcommand as "pass through to the
+ * postgres-server.js dispatcher").
+ */
+function dispatch(subcommand, args, ctx) {
+  switch (subcommand) {
+    case 'install':
+      return cmdInstall(args, ctx);
+    case 'uninstall':
+      return cmdUninstall();
+    case 'status':
+      return cmdStatus(args);
+    case 'url':
+      return cmdUrl();
+    case 'port':
+      return cmdPort();
+    default:
+      throw new Error(`pgserve: dispatch called with unknown subcommand "${subcommand}"`);
+  }
+}
+
+module.exports = {
+  // Public API for the wrapper.
+  dispatch,
+  // Test surface.
+  _internals: {
+    HARDENED_DEFAULTS,
+    PM2_PROCESS_NAME,
+    DEFAULT_PORT,
+    getConfigDir,
+    getConfigPath,
+    getLogsDir,
+    getDataDir,
+    readConfig,
+    writeConfig,
+    buildPm2StartArgs,
+    parsePort,
+    parseDataDir,
+  },
+};

package/src/postgres.js

@@ -67,7 +67,7 @@ async function downloadPostgresBinaries() {
 
   const platformKey = getPlatformKey();
   const pkgName = `@embedded-postgres/${platformKey}`;
-  const pkgVersion = '18.2.0-beta.16';
+  const pkgVersion = '18.3.0-beta.17';
 
   console.log(`[pgserve] PostgreSQL binaries not found.`);
   console.log(`[pgserve] Downloading ${pkgName}@${pkgVersion}...`);

package/tests/cli-install.test.js

@@ -0,0 +1,301 @@
+/**
+ * Tests for src/cli-install.cjs — pgserve install/uninstall/status/url/port.
+ *
+ * Wave 1 of the canonical-pgserve-pm2-supervision wish (PR #55, issue #56).
+ *
+ * Strategy: drive the pure paths (config read/write, arg parsing, pm2-args
+ * builder) directly. The pm2-spawning paths (install / uninstall) are
+ * exercised by spawning the real pgserve binary against a temp HOME so
+ * `pm2` is invoked but with no real daemon side-effect when pm2 is
+ * either absent OR the test stubs its calls via PATH.
+ *
+ * No test in this file actually starts pgserve. We only verify the CLI
+ * surface — the daemon lifecycle is covered by daemon-control.test.js.
+ */
+
+import { test, expect, beforeEach, afterEach, describe } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const BIN = path.join(REPO_ROOT, 'bin', 'pgserve-wrapper.cjs');
+
+let tmpHome;
+let stubBin;
+let originalConfigDir;
+let originalPath;
+
+function makeStubPm2(mode = 'success') {
+  // mode: 'success' | 'failure' | 'missing'
+  // Writes a stub `pm2` script into a tempdir we prepend to PATH.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-stub-pm2-'));
+  if (mode === 'missing') {
+    // Don't create a stub; PATH still has our dir but no pm2 binary.
+    return { dir, calls: [] };
+  }
+  const callLog = path.join(dir, 'calls.log');
+  const exitCode = mode === 'failure' ? 1 : 0;
+  // jlist returns either an empty list (so install proceeds) or a fake
+  // process record (so subsequent install calls hit the idempotent
+  // path). We toggle via a sentinel file the test owns.
+  const script = `#!/usr/bin/env node
+const fs = require('node:fs');
+const args = process.argv.slice(2);
+fs.appendFileSync(${JSON.stringify(callLog)}, JSON.stringify(args) + '\\n');
+if (args[0] === '--version') { process.stdout.write('5.0.0-stub\\n'); process.exit(0); }
+if (args[0] === 'jlist') {
+  const sentinel = ${JSON.stringify(path.join(dir, 'registered'))};
+  if (fs.existsSync(sentinel)) {
+    process.stdout.write(JSON.stringify([{
+      name: 'pgserve',
+      pid: 12345,
+      pm2_env: { status: 'online', pm_uptime: Date.now() - 1000, restart_time: 0 }
+    }]) + '\\n');
+  } else {
+    process.stdout.write('[]\\n');
+  }
+  process.exit(0);
+}
+if (args[0] === 'start') {
+  fs.writeFileSync(${JSON.stringify(path.join(dir, 'registered'))}, '');
+  process.exit(${exitCode});
+}
+if (args[0] === 'delete') {
+  try { fs.unlinkSync(${JSON.stringify(path.join(dir, 'registered'))}); } catch {}
+  process.exit(${exitCode});
+}
+process.exit(0);
+`;
+  const pm2Path = path.join(dir, 'pm2');
+  fs.writeFileSync(pm2Path, script, { mode: 0o755 });
+  return { dir, calls: callLog };
+}
+
+function readCallLog(callsPath) {
+  if (!fs.existsSync(callsPath)) return [];
+  return fs.readFileSync(callsPath, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+}
+
+function runCli(args, env = {}) {
+  return spawnSync('node', [BIN, ...args], {
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      PGSERVE_CONFIG_DIR: tmpHome,
+      PATH: `${stubBin.dir}:${process.env.PATH}`,
+      ...env,
+    },
+  });
+}
+
+beforeEach(() => {
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-cfg-'));
+  stubBin = makeStubPm2('success');
+  originalConfigDir = process.env.PGSERVE_CONFIG_DIR;
+  originalPath = process.env.PATH;
+});
+
+afterEach(() => {
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+  if (stubBin?.dir) fs.rmSync(stubBin.dir, { recursive: true, force: true });
+  if (originalConfigDir === undefined) delete process.env.PGSERVE_CONFIG_DIR;
+  else process.env.PGSERVE_CONFIG_DIR = originalConfigDir;
+  process.env.PATH = originalPath;
+});
+
+describe('pgserve install', () => {
+  test('first install registers under pm2 and writes config', () => {
+    const result = runCli(['install']);
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('installed');
+    expect(result.stdout).toContain('postgres://localhost:8432');
+
+    const config = JSON.parse(fs.readFileSync(path.join(tmpHome, 'config.json'), 'utf8'));
+    expect(config.port).toBe(8432);
+    expect(config.dataDir).toBe(path.join(tmpHome, 'data'));
+    expect(config.registeredAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+
+    const calls = readCallLog(stubBin.calls);
+    const startCall = calls.find((c) => c[0] === 'start');
+    expect(startCall).toBeDefined();
+    expect(startCall).toContain('--name');
+    expect(startCall).toContain('pgserve');
+    expect(startCall).toContain('--max-restarts');
+    expect(startCall).toContain('50');
+    expect(startCall).toContain('--min-uptime');
+    expect(startCall).toContain('--exp-backoff-restart-delay');
+    expect(startCall).toContain('--max-memory-restart');
+    expect(startCall).toContain('4G');
+    expect(startCall).toContain('--kill-timeout');
+    expect(startCall).toContain('60000');
+    expect(startCall).toContain('--interpreter');
+    expect(startCall).toContain('none');
+  });
+
+  test('second install is idempotent (no second pm2 start)', () => {
+    runCli(['install']);
+    const calls1 = readCallLog(stubBin.calls);
+    const startCount1 = calls1.filter((c) => c[0] === 'start').length;
+    expect(startCount1).toBe(1);
+
+    const result2 = runCli(['install']);
+    expect(result2.status).toBe(0);
+    expect(result2.stdout).toContain('already installed');
+
+    const calls2 = readCallLog(stubBin.calls);
+    const startCount2 = calls2.filter((c) => c[0] === 'start').length;
+    expect(startCount2).toBe(1); // no second start
+  });
+
+  test('--port overrides default', () => {
+    const result = runCli(['install', '--port', '8442']);
+    expect(result.status).toBe(0);
+    const config = JSON.parse(fs.readFileSync(path.join(tmpHome, 'config.json'), 'utf8'));
+    expect(config.port).toBe(8442);
+    expect(result.stdout).toContain('postgres://localhost:8442');
+  });
+
+  test('rejects malformed --port', () => {
+    const result = runCli(['install', '--port', 'not-a-number']);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toContain('invalid --port');
+  });
+
+  test('PGSERVE_MAX_MEMORY env overrides the default memory ceiling', () => {
+    const result = runCli(['install'], { PGSERVE_MAX_MEMORY: '8G' });
+    expect(result.status).toBe(0);
+    const calls = readCallLog(stubBin.calls);
+    const startCall = calls.find((c) => c[0] === 'start');
+    // The env value flows through to pm2's --max-memory-restart flag so
+    // operators on big-iron hosts can tune up without a recompile.
+    expect(startCall).toContain('8G');
+    expect(startCall).not.toContain('4G');
+  });
+
+  test('fails clearly when pm2 is missing', () => {
+    // Build a sanitized PATH that has node (so spawnSync can resolve the
+    // interpreter) but explicitly NO directory containing pm2. Skipping
+    // /usr/bin etc. would make the test brittle on different hosts.
+    fs.rmSync(stubBin.dir, { recursive: true, force: true });
+    stubBin = makeStubPm2('missing');
+    const nodeDir = path.dirname(process.execPath);
+    const sanitizedPath = (process.env.PATH || '')
+      .split(':')
+      .filter((p) => {
+        try {
+          return !fs.existsSync(path.join(p, 'pm2'));
+        } catch {
+          return true;
+        }
+      })
+      .concat([nodeDir, stubBin.dir])
+      .join(':');
+    const result = spawnSync('node', [BIN, 'install'], {
+      encoding: 'utf8',
+      env: { ...process.env, PGSERVE_CONFIG_DIR: tmpHome, PATH: sanitizedPath },
+    });
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toContain('pm2 not found');
+  });
+});
+
+describe('pgserve url / port', () => {
+  test('url after install prints canonical connection string', () => {
+    runCli(['install']);
+    const result = runCli(['url']);
+    expect(result.status).toBe(0);
+    expect(result.stdout.trim()).toBe('postgres://localhost:8432/postgres');
+  });
+
+  test('port after install prints the registered port', () => {
+    runCli(['install', '--port', '8442']);
+    const result = runCli(['port']);
+    expect(result.status).toBe(0);
+    expect(result.stdout.trim()).toBe('8442');
+  });
+
+  test('url before install fails with helpful message', () => {
+    const result = runCli(['url']);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toContain('not installed');
+  });
+});
+
+describe('pgserve status', () => {
+  test('status before install reports installed=false (exit 1)', () => {
+    const result = runCli(['status', '--json']);
+    expect(result.status).toBe(1);
+    const out = JSON.parse(result.stdout);
+    expect(out.installed).toBe(false);
+  });
+
+  test('status after install reports running with port from config', () => {
+    runCli(['install', '--port', '8482']);
+    const result = runCli(['status', '--json']);
+    expect(result.status).toBe(0);
+    const out = JSON.parse(result.stdout);
+    expect(out.installed).toBe(true);
+    expect(out.name).toBe('pgserve');
+    expect(out.status).toBe('online');
+    expect(out.port).toBe(8482);
+    expect(out.url).toBe('postgres://localhost:8482/postgres');
+  });
+
+  test('status human-readable output includes port + url', () => {
+    runCli(['install']);
+    const result = runCli(['status']);
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('port');
+    expect(result.stdout).toContain('8432');
+    expect(result.stdout).toContain('postgres://localhost:8432/postgres');
+  });
+});
+
+describe('pgserve uninstall', () => {
+  test('uninstall removes pm2 process but preserves config', () => {
+    runCli(['install']);
+    expect(fs.existsSync(path.join(tmpHome, 'config.json'))).toBe(true);
+
+    const result = runCli(['uninstall']);
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('uninstalled');
+
+    const calls = readCallLog(stubBin.calls);
+    expect(calls.find((c) => c[0] === 'delete' && c[1] === 'pgserve')).toBeDefined();
+
+    // Config preserved so a re-install reuses port/dataDir.
+    expect(fs.existsSync(path.join(tmpHome, 'config.json'))).toBe(true);
+  });
+
+  test('uninstall when not installed is a no-op success', () => {
+    const result = runCli(['uninstall']);
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('not registered');
+  });
+});
+
+describe('serve alias', () => {
+  test('pgserve serve --help re-routes to daemon (which postgres-server.js handles)', () => {
+    // We can't fully exercise `serve` without starting a real daemon.
+    // Instead, verify the wrapper's argv-rewrite happens by passing
+    // `serve --bogus-flag` and asserting the wrapper proceeded past the
+    // install short-circuit (i.e. stderr mentions bun, not "pgserve: ...").
+    // Note: bun probe might fail in tests; we don't assert exit code.
+    const result = spawnSync('node', [BIN, 'serve', '--bogus-flag'], {
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        PGSERVE_CONFIG_DIR: tmpHome,
+        PATH: `${stubBin.dir}:${process.env.PATH}`,
+      },
+    });
+    // Must NOT have hit the install dispatcher (would print
+    // "pgserve: not installed" or similar). Because serve passes through
+    // to the bun + postgres-server.js path, we expect EITHER a bun error
+    // OR a daemon-mode error — never an install-module error.
+    expect(result.stderr).not.toContain('pgserve: not installed');
+    expect(result.stderr).not.toContain('pm2 not found');
+  });
+});