pgserve 2.3.0 → 2.5.0

package/src/cli-install.cjs

@@ -27,8 +27,42 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
-const PM2_PROCESS_NAME = 'pgserve';
-const DEFAULT_PORT = 8432;
+// pgserve singleton (v2.4): the cohort-shared admin-json + socket-dir
+// helpers live in `src/lib/*.js` as ESM modules (project convention: new
+// modules ship as .js / ESM). cli-install.cjs runs under node — which
+// cannot synchronously `require()` ESM — so we cache the dynamic-import
+// promise once at module load and await it from async install paths.
+const _adminJsonModuleP = import('./lib/admin-json.js');
+const _socketDirModuleP = import('./lib/socket-dir.js');
+const _runtimeJsonModuleP = import('./lib/runtime-json.js');
+
+async function loadCohortModules() {
+  const [adminJson, socketDirMod, runtimeJson] = await Promise.all([
+    _adminJsonModuleP,
+    _socketDirModuleP,
+    _runtimeJsonModuleP,
+  ]);
+  return { adminJson, socketDirMod, runtimeJson };
+}
+
+// pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 1.
+//
+// The pm2 entry name moves from `pgserve` to `autopg-server` so the canonical
+// two-process layout matches the cohort design (`autopg-server` + `autopg-ui`).
+// Tier B operators install a systemd-user unit that ALSO claims the
+// `autopg-server` lifecycle role — `~/.autopg/admin.json` records which
+// supervisor owns the host and `pgserve install` refuses to register pm2 over
+// an existing Tier B record.
+//
+// Default postgres port moves from 8432 (the old bun-proxy listener) to 5432
+// (the postgres standard, since the postmaster now binds TCP directly).
+const PM2_PROCESS_NAME = 'autopg-server';
+// Legacy entry name (pre-v2.4). Self-healing migration in Group 6 will
+// `pm2 delete pgserve` after registering `autopg-server`; we surface the
+// constant here so cleanup tooling and tests can reference it without
+// hardcoding strings.
+const LEGACY_PM2_PROCESS_NAME = 'pgserve';
+const DEFAULT_PORT = 5432;
 
 // Console UI is auto-supervised under pm2 alongside the daemon since v2.2.3.
 // The bundled SPA (console/dist/) is served on this port; operator-facing
@@ -136,6 +170,131 @@ function readConfig() {
   }
 }
 
+// cutover G19: discovery layer used by `autopg port / url / status`.
+//
+// Order of precedence (most-authoritative first):
+//   1. `<socketDir>/runtime.json` — written by the live postmaster at greet
+//      time, removed on graceful shutdown. Carries the *current* port + pid
+//      for an actually-running daemon.
+//   2. `~/.autopg/admin.json` — supervisor record written at install time.
+//      Survives postmaster restarts; doesn't reflect runtime state.
+//   3. `~/.autopg/config.json` — legacy pre-G19 install record. Final
+//      fallback so older installs that haven't been re-installed under v2.4
+//      still discover cleanly.
+//
+// All readers swallow errors — discovery must never throw on a missing or
+// truncated file. Synchronous on purpose: `dispatch()` for status/url/port
+// is sync and the wrapper handles only `Promise OR number` return types.
+function readRuntimeJsonSync(socketDir) {
+  if (typeof socketDir !== 'string' || socketDir.length === 0) return null;
+  const file = path.join(socketDir, 'runtime.json');
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function readAdminJsonSync() {
+  const file = path.join(getConfigDir(), ADMIN_FILE_NAME);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveCanonicalSocketDir() {
+  // Mirror src/lib/socket-dir.js#resolveSocketDir — pure function, no fs
+  // touch. Inlined here so the sync discovery layer doesn't need a top-
+  // level await on the ESM module.
+  const xdg = process.env.XDG_RUNTIME_DIR;
+  const base = xdg && xdg.length > 0 ? xdg : '/tmp';
+  return path.join(base, 'pgserve');
+}
+
+function isLivePid(pid) {
+  if (!Number.isInteger(pid) || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err && err.code === 'EPERM';
+  }
+}
+
+/**
+ * Compose a discovery view from runtime.json (preferred), admin.json
+ * (fallback), and config.json (legacy fallback). Returns:
+ *   {
+ *     runtime: { socketDir, port, pid, autopgPid, schemaVersion } | null,
+ *     admin:   { supervisor, socketDir, port, installedAt, ... }    | null,
+ *     config:  { port, dataDir, registeredAt }                       | null,
+ *     // composed view — best effort merge for callers that just want
+ *     // "where do I connect right now?":
+ *     socketDir: <string|null>,
+ *     port:      <number|null>,
+ *     liveAutopg: <boolean>     // true when runtime.json names a live pid
+ *   }
+ */
+function readDiscovery() {
+  const config = readConfig();
+  const admin = readAdminJsonSync();
+  // Prefer the socket dir the supervisor recorded at install time — that's
+  // the path operators configured. Only fall back to the canonical resolver
+  // when the install record is missing (fresh-host case).
+  const socketDir = (admin && typeof admin.socketDir === 'string' && admin.socketDir.length > 0)
+    ? admin.socketDir
+    : resolveCanonicalSocketDir();
+  const runtime = readRuntimeJsonSync(socketDir);
+
+  // PR #80 P2 fix: previous logic treated ANY parsed runtime.json as
+  // authoritative — a malformed-but-JSON file (no port, no socketDir) would
+  // hide later admin.json / config fallbacks because composedPort stayed
+  // null while the precedence chain stopped early. Validate that runtime
+  // actually carries a usable port + socketDir before treating it as live.
+  // Mirrors the admin / config branches' Number.isInteger guard.
+  let composedSocketDir = null;
+  let composedPort = null;
+  const runtimeUsable = runtime
+    && Number.isInteger(runtime.port)
+    && typeof runtime.socketDir === 'string'
+    && runtime.socketDir.length > 0;
+  if (runtimeUsable) {
+    composedSocketDir = runtime.socketDir;
+    composedPort = runtime.port;
+  } else if (admin && Number.isInteger(admin.port)) {
+    composedSocketDir = admin.socketDir ?? socketDir;
+    composedPort = admin.port;
+  } else if (config && Number.isInteger(config.port)) {
+    composedPort = config.port;
+    composedSocketDir = socketDir;
+  }
+
+  return {
+    runtime,
+    admin,
+    config,
+    socketDir: composedSocketDir,
+    port: composedPort,
+    liveAutopg: !!(runtime && isLivePid(runtime.autopgPid)),
+  };
+}
+
 function writeConfig(config) {
   const dir = getConfigDir();
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o755 });
@@ -200,7 +359,7 @@ function getEffectiveSupervision() {
   }
 }
 
-function buildPm2StartArgs({ scriptPath, port, dataDir }) {
+function buildPm2StartArgs({ scriptPath, port, dataDir, socketDir }) {
   const logs = {
     out: path.join(getLogsDir(), `${PM2_PROCESS_NAME}-out.log`),
     error: path.join(getLogsDir(), `${PM2_PROCESS_NAME}-error.log`),
@@ -215,19 +374,11 @@ function buildPm2StartArgs({ scriptPath, port, dataDir }) {
     'none',
     '--max-restarts',
     String(supervision.maxRestarts),
-    // NOTE: pm2 ≥ 6.0 dropped `--min-uptime` from the CLI surface — passing
-    // it produces `error: unknown option --min-uptime` and aborts the
-    // install. The flag still works inside an ecosystem file, but per the
-    // canonical-pm2-supervision wish we keep `pgserve install` as a pure
-    // CLI flow (no extra files for operators to manage). The trade-off is
-    // that `--max-restarts` now counts every restart (rapid or not) rather
-    // than only sub-`min_uptime` ones; the budget of 50 above is sized
-    // accordingly.
+    // pm2 ≥ 6.0 dropped `--min-uptime` from the CLI surface — passing it
+    // aborts the install. Restart budget (50) is sized to absorb a few
+    // long-uptime crashes without burning through.
     '--restart-delay',
     String(supervision.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(supervision.expBackoffRestartDelayMs),
     '--max-memory-restart',
@@ -241,28 +392,19 @@ function buildPm2StartArgs({ scriptPath, port, dataDir }) {
     '--error',
     logs.error,
     '--',
-    // Foreground multi-tenant mode (`pgserve [options]`), NOT daemon mode.
-    //
-    // Daemon mode binds a unix control socket and requires libpq peers to
-    // authenticate via a fingerprint+token handshake (`pgserve daemon
-    // issue-token`). Downstream services that connect with a plain
-    // `postgres://` URL (omni, genie, anything that doesn't speak the
-    // fingerprint protocol) cannot reach a daemon-mode listener. We also
-    // observed live: `pgserve install` was passing `--port` to the daemon
-    // parser, which only accepts `--data | --ram | --log | --no-provision
-    // | --listen | --pgvector` — every install attempt crashed with
-    // `Unknown daemon option: --port` and pm2 burned its restart budget.
-    //
-    // Foreground mode (the default `pgserve [options]` invocation in
-    // postgres-server.js) accepts `--port`, auto-provisions databases on
-    // first connect, runs the cluster on multi-core hosts, and binds TCP
-    // on `127.0.0.1:<port>` with no auth dance — exactly what canonical
-    // pgserve consumers expect. Pass the same flags pgserve already
-    // documents in its own `pgserve --help` output.
+    // pgserve singleton (v2.4): pm2 supervises the postmaster directly via
+    // the `pgserve postmaster` subcommand — no router, no bun proxy, no
+    // daemon control socket. Postgres binds the canonical Unix socket
+    // under <socketDir> AND TCP <port> natively. Operators connect via
+    //   psql -h $XDG_RUNTIME_DIR/pgserve     (Unix socket, no -p)
+    //   psql -h 127.0.0.1 -p 5432            (canonical TCP)
+    'postmaster',
     '--port',
     String(port),
     '--data',
     dataDir,
+    '--socket-dir',
+    socketDir,
     '--log',
     'warn',
   ];
@@ -384,21 +526,9 @@ function cmdInstallUi(ctx, options = {}) {
   return 0;
 }
 
-function cmdUninstallUi() {
-  if (!pm2IsAvailable()) return 0;
-  // Always attempt the delete — `pm2 delete <name>` is idempotent and
-  // exits non-zero on a missing process, which is fine to swallow. This
-  // is more robust than a pre-existence check against `pm2 jlist`, which
-  // can lag the actual process state (or, in test stubs, return a
-  // partial registry).
-  const result = spawnSync('pm2', ['delete', UI_PM2_PROCESS_NAME], {
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-  if (result.status === 0) {
-    ok(`UI uninstalled (pm2 process "${UI_PM2_PROCESS_NAME}" removed)`);
-  }
-  return 0;
-}
+// `cmdUninstall` + `cmdUninstallUi` migrated to `src/commands/uninstall.js`
+// as part of canonical-pgserve-pm2-supervision Group 1. The dispatch
+// `case 'uninstall'` above dynamically imports the new module.
 
 // ─── Admin password (Basic Auth for `autopg ui`) ─────────────────────────
 
@@ -429,12 +559,19 @@ function writeAdminFile({ password, rotated = false }) {
   const hash = hashAdminPassword(password, salt);
   const file = getAdminFilePath();
   const now = new Date().toISOString();
+  // pgserve singleton (v2.4): admin.json is shared with the supervisor
+  // record (`{ supervisor, socketDir, port, installedAt }`) written by
+  // `src/lib/admin-json.js`. Merge with any existing fields so the scrypt
+  // Basic-Auth scheme can never wipe the supervisor metadata (and vice
+  // versa).
+  const existing = readAdminFile() || {};
   const payload = {
+    ...existing,
     scheme: 'scrypt',
     params: SCRYPT_PARAMS,
     salt: salt.toString('base64'),
     hash: hash.toString('base64'),
-    createdAt: rotated ? readAdminFile()?.createdAt ?? now : now,
+    createdAt: rotated ? existing.createdAt ?? now : now,
     rotatedAt: rotated ? now : null,
   };
   ensureConfigDir();
@@ -487,9 +624,14 @@ function verifyAdminPassword(candidate) {
 
 function ensureAdminPassword({ rotate = false } = {}) {
   const existing = readAdminFile();
-  if (existing && !rotate) return null;
+  // pgserve singleton (v2.4): admin.json may exist with only supervisor
+  // fields (`{ supervisor, socketDir, port, installedAt }`) and no scrypt
+  // scheme yet. Treat "no scrypt scheme" as "no password" so the install
+  // path still mints one on first run.
+  const hasScryptScheme = !!(existing && existing.scheme === 'scrypt');
+  if (hasScryptScheme && !rotate) return null;
   const password = generateAdminPassword();
-  writeAdminFile({ password, rotated: !!existing });
+  writeAdminFile({ password, rotated: !!hasScryptScheme });
   return password;
 }
 
@@ -532,14 +674,41 @@ function cmdAuthDispatch(args) {
  * `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)');
+async function cmdInstall(args, ctx) {
+  const { adminJson, socketDirMod } = await loadCohortModules();
+
+  // pgserve singleton (v2.4): refuse to install if a different supervisor
+  // (Tier B systemd-user / launchd) already owns the host. The cohort
+  // contract guarantees one and only one supervisor records itself in
+  // `~/.autopg/admin.json`. `pgserve install` is the Tier A (pm2) entry —
+  // it asserts that nothing else has already claimed the host before
+  // touching pm2.
+  const noPm2 = args.includes('--no-pm2');
+  const expectedSupervisor = noPm2 ? 'external' : 'pm2';
+  try {
+    adminJson.assertSupervisor(expectedSupervisor, { configDir: getConfigDir() });
+  } catch (err) {
+    fail(err.message);
+  }
+
+  if (!noPm2 && !pm2IsAvailable()) {
+    fail('pm2 not found in PATH. Install with: bun add -g pm2  (or npm i -g pm2). Pass --no-pm2 for CI / Tier B-bound hosts.');
   }
 
   const port = parsePort(args) ?? readConfig()?.port ?? DEFAULT_PORT;
   const dataDir = parseDataDir(args) ?? readConfig()?.dataDir ?? getDataDir();
 
+  // Set up the canonical socket directory before pm2 launches the
+  // postmaster. `ensureSocketDir` enforces mode 0700 and probes writability
+  // so failure surfaces here — not as a libpq bind error a few seconds
+  // into pm2 backoff.
+  const socketDir = parseSocketDir(args) ?? socketDirMod.resolveSocketDir();
+  try {
+    socketDirMod.ensureSocketDir(socketDir);
+  } catch (err) {
+    fail(err.message);
+  }
+
   const noUi = args.includes('--no-ui');
   const withUi = args.includes('--with-ui');
   const redeploy = args.includes('--redeploy');
@@ -559,6 +728,22 @@ function cmdInstall(args, ctx) {
     return 0;
   }
 
+  // --no-pm2: skip pm2 register entirely. Used by CI fixture provisioning
+  // (no sudo, no pm2 ambient state) and by Tier B-bound hosts that will
+  // immediately hand off to `autopg service install`. Still record the
+  // supervisor + canonical socket dir + port in admin.json so downstream
+  // tooling (pgserve doctor, omni install, genie install) can discover
+  // where to connect without an active pm2 entry.
+  if (noPm2) {
+    if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+    writeConfig({ port, dataDir, registeredAt: readConfig()?.registeredAt ?? new Date().toISOString() });
+    writeSupervisorRecord(adminJson, { supervisor: 'external', socketDir, port });
+    ok(`installed (--no-pm2): supervisor=external, socketDir=${socketDir}, port=${port}`);
+    ok(`url: postgres://localhost:${port}/postgres`);
+    note(`--no-pm2: pm2 register skipped. Start the postmaster manually with \`pgserve postmaster --port ${port} --data ${dataDir} --socket-dir ${socketDir}\` or hand off to systemd-user / launchd.`);
+    return 0;
+  }
+
   // --redeploy: full reset. Tear down both processes, then proceed with
   // a fresh install. Equivalent to `autopg uninstall && autopg install`
   // but in one verb.
@@ -581,6 +766,7 @@ function cmdInstall(args, ctx) {
     // don't tear down the live process. Operators wanting a port change
     // should `uninstall` then `install` (or pass --redeploy).
     writeConfig({ port, dataDir, registeredAt: readConfig()?.registeredAt ?? new Date().toISOString() });
+    writeSupervisorRecord(adminJson, { supervisor: 'pm2', socketDir, port });
     if (!noUi) cmdInstallUi(ctx, { uiPort, uiHost });
     return 0;
   }
@@ -588,14 +774,15 @@ function cmdInstall(args, ctx) {
   ensureLogsDir();
   if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 });
 
-  const pm2Args = buildPm2StartArgs({ scriptPath: ctx.scriptPath, port, dataDir });
+  const pm2Args = buildPm2StartArgs({ scriptPath: ctx.scriptPath, port, dataDir, socketDir });
   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})`);
+  writeSupervisorRecord(adminJson, { supervisor: 'pm2', socketDir, port });
+  ok(`installed: pm2 process "${PM2_PROCESS_NAME}" on port ${port} (socket: ${socketDir}, data: ${dataDir})`);
   ok(`url: postgres://localhost:${port}/postgres`);
 
   if (noUi) {
@@ -620,43 +807,47 @@ function cmdInstall(args, ctx) {
 }
 
 /**
- * `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.
+ * Persist the supervisor record into `~/.autopg/admin.json`. Wraps
+ * `writeAdminJson` from the cohort-shared module so the install path can
+ * pin its own ISO timestamp + log a friendly diagnostic on the
+ * supervisor-lock refusal.
  */
-function cmdUninstall() {
-  // Delete the daemon first — it's the load-bearing process and the order
-  // of "what existed at uninstall start" is determined by the daemon's
-  // pm2 registry, not the UI's. UI cleanup follows; soft-fails if absent.
-  const existing = pm2GetProcess(PM2_PROCESS_NAME);
-  if (!existing) {
-    ok(`not registered under pm2 (nothing to uninstall)`);
-    cmdUninstallUi();
-    return 0;
-  }
-  const result = spawnSync('pm2', ['delete', PM2_PROCESS_NAME], { stdio: 'inherit' });
-  if (result.status !== 0) {
-    fail(`pm2 delete failed (exit ${result.status})`);
+function writeSupervisorRecord(adminJson, { supervisor, socketDir, port }) {
+  try {
+    adminJson.writeAdminJson(
+      {
+        supervisor,
+        socketDir,
+        port,
+        installedAt: new Date().toISOString(),
+      },
+      { configDir: getConfigDir() },
+    );
+  } catch (err) {
+    // The "Tier B already owns this host" error is the contract failure
+    // we surface to operators. Other errors (EACCES, ENOSPC, etc.) just
+    // pass through with their stock message.
+    fail(err.message);
   }
-  ok(`uninstalled (pm2 process removed; data dir preserved at ${getDataDir()})`);
-  cmdUninstallUi();
-  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).
+ * Reports both pm2 state and on-disk discovery (runtime.json → admin.json
+ * → config.json fallback chain). Exits 0 with status info regardless of
+ * running/stopped — operators script around the JSON output. Non-zero
+ * only when nothing was ever installed (no admin.json AND no config.json).
+ *
+ * Cutover G19: surfaces `runtime` (live socket discovery) and `socketDir`
+ * top-level so consumers can pick UDS vs TCP without parsing pm2 jlist.
  */
 function cmdStatus(args) {
   const json = args.includes('--json');
-  const config = readConfig();
-  if (!config) {
+  const discovery = readDiscovery();
+  const { config, admin, runtime } = discovery;
+
+  if (!config && !admin) {
     if (json) {
       process.stdout.write(`${JSON.stringify({ installed: false })}\n`);
     } else {
@@ -664,24 +855,41 @@ function cmdStatus(args) {
     }
     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 port = discovery.port;
+  const socketDir = discovery.socketDir;
+  const dataDir = config?.dataDir ?? null;
+
   const payload = {
     installed: true,
     name: PM2_PROCESS_NAME,
     status,
     pid,
-    port: config.port,
-    dataDir: config.dataDir,
+    port,
+    socketDir,
+    dataDir,
     logsDir: getLogsDir(),
-    url: `postgres://localhost:${config.port}/postgres`,
+    url: port ? `postgres://localhost:${port}/postgres` : null,
     uptimeMs,
     restarts,
-    registeredAt: config.registeredAt,
+    registeredAt: config?.registeredAt ?? null,
+    supervisor: admin?.supervisor ?? null,
+    runtime: runtime
+      ? {
+          socketDir: runtime.socketDir,
+          port: runtime.port,
+          pid: runtime.pid,
+          autopgPid: runtime.autopgPid,
+          schemaVersion: runtime.schemaVersion,
+          live: discovery.liveAutopg,
+        }
+      : null,
   };
 
   if (json) {
@@ -690,42 +898,53 @@ function cmdStatus(args) {
   }
   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`);
+  if (payload.supervisor) {
+    process.stdout.write(`supervisor  ${payload.supervisor}\n`);
+  }
+  if (payload.port != null) process.stdout.write(`port        ${payload.port}\n`);
+  if (payload.url) process.stdout.write(`url         ${payload.url}\n`);
+  if (payload.socketDir) process.stdout.write(`socketDir   ${payload.socketDir}\n`);
+  if (payload.dataDir) process.stdout.write(`dataDir     ${payload.dataDir}\n`);
   process.stdout.write(`logsDir     ${payload.logsDir}\n`);
+  if (payload.runtime) {
+    process.stdout.write(`runtime     pid=${payload.runtime.pid} autopgPid=${payload.runtime.autopgPid} live=${payload.runtime.live}\n`);
+  } else {
+    process.stdout.write(`runtime     (no runtime.json — postmaster down or never started)\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`);
+  if (payload.registeredAt) process.stdout.write(`registered  ${payload.registeredAt}\n`);
   return 0;
 }
 
 /**
  * `pgserve url`
  *
- * Discovery API. Prints the canonical connection string. Downstream
+ * Discovery API. Prints the canonical TCP connection string. Downstream
  * installers (genie install, omni install) call this to learn where to
- * connect, instead of hardcoding a port.
+ * connect, instead of hardcoding a port. The TCP form is stable across
+ * Tier A / Tier B / fingerprint-disabled hosts; UDS callers should
+ * resolve `<socketDir>/.s.PGSQL.<port>` from `autopg status --json`.
  */
 function cmdUrl() {
-  const config = readConfig();
-  if (!config) {
+  const discovery = readDiscovery();
+  if (discovery.port == null) {
     fail('not installed (run: pgserve install)');
   }
-  process.stdout.write(`postgres://localhost:${config.port}/postgres\n`);
+  process.stdout.write(`postgres://localhost:${discovery.port}/postgres\n`);
   return 0;
 }
 
-/** `pgserve port` — print the canonical port. */
+/** `pgserve port` — print the canonical port from runtime.json → admin.json → config.json. */
 function cmdPort() {
-  const config = readConfig();
-  if (!config) {
+  const discovery = readDiscovery();
+  if (discovery.port == null) {
     fail('not installed (run: pgserve install)');
   }
-  process.stdout.write(`${config.port}\n`);
+  process.stdout.write(`${discovery.port}\n`);
   return 0;
 }
 
@@ -747,6 +966,14 @@ function parseDataDir(args) {
   return path.resolve(v);
 }
 
+function parseSocketDir(args) {
+  const i = args.indexOf('--socket-dir');
+  if (i < 0) return null;
+  const v = args[i + 1];
+  if (!v) fail('--socket-dir requires a value');
+  return path.resolve(v);
+}
+
 function parseUiPort(args) {
   const i = args.indexOf('--ui-port');
   if (i < 0) return null;
@@ -807,7 +1034,13 @@ function dispatch(subcommand, args, ctx) {
     case 'install':
       return cmdInstall(args, ctx);
     case 'uninstall':
-      return cmdUninstall();
+      // canonical-pgserve-pm2-supervision Group 1: the uninstall surface
+      // moved to `src/commands/uninstall.js` so the cohort baseline (pm2
+      // teardown + admin.json supervisor clear + audit-log entry) lives
+      // alongside `src/lib/pm2-args.js` instead of inside this legacy
+      // dispatcher. dispatch() returns a Promise here; the wrapper
+      // already handles both numeric and Promise returns.
+      return import('./commands/uninstall.js').then((mod) => mod.runUninstall());
     case 'status':
       return cmdStatus(args);
     case 'url':
@@ -843,6 +1076,13 @@ function dispatch(subcommand, args, ctx) {
     }
     case 'auth':
       return cmdAuthDispatch(args);
+    case 'verify': {
+      // pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 4.
+      // `pgserve verify` is a pure-node command (cosign shellout + HMAC
+      // cache token write); routes through the same async-import pattern
+      // as `uninstall` so the ESM module isn't eagerly loaded.
+      return import('./commands/verify.js').then((mod) => mod.runVerify(args));
+    }
     default:
       throw new Error(`pgserve: dispatch called with unknown subcommand "${subcommand}"`);
   }