From 710f92ecfce5e541042c0d49ba9cffa7b8c177fa Mon Sep 17 00:00:00 2001
From: Simon Gagnon <git@simoncrypta.dev>
Date: Mon, 31 Aug 2026 00:53:06 -0400
Subject: [PATCH 1/2] fix(host): do not attach acquire to a stopped autopg port

Registered pm2 with no listener was treated as live, so cedarpg acquire
hit ECONNREFUSED on 25432. Treat status/TCP as liveness and start an
owned postmaster when local install cannot bring a host up.
---
 AGENTS.md               |  2 +-
 CHANGELOG.md            |  2 +
 README.md               | 21 +++++-----
 scripts/smoke-pg.mjs    | 27 +++++++++----
 src/providers/autopg.ts | 23 +++++++++--
 src/providers/host.ts   | 85 ++++++++++++++++++++++-------------------
 tests/autopg.test.ts    | 25 ++++++++++--
 tests/host.test.ts      | 28 +++++---------
 8 files changed, 129 insertions(+), 84 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 9d4dfb5..7efafea 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -89,7 +89,7 @@ Keep logic in the canonical layer. Prefer reuse over one-off branches in adapter
 
 **Migrate stays app-owned.** Stock `@cedarjs/pg/jest` / `vitest` only acquire/dispose. TEMPLATE adapters require `createGlobalSetup({ migrate })`; string-resolving the package entry without a migrate hook must throw.
 
-**Host bootstrap stays internal.** Callers use `acquire` (and `adminUrl`). Do not re-export `ensureHostRunning` or grow a public host-options bag; ephemeral behavior is env-driven (`CI`, `CEDAR_PG_EPHEMERAL_HOST`).
+**Host bootstrap stays internal.** Callers use `acquire` (and `adminUrl`). Do not re-export `ensureHostRunning` or grow a public host-options bag; ephemeral behavior is env-driven (`CI`, `CEDAR_PG_EPHEMERAL_HOST`). Default local acquire may start an owned postmaster after a no-op `autopg install` (stopped pm2); `CEDAR_PG_EPHEMERAL_HOST=0` disables that fallback.
 
 ## Env and policy (easy to get wrong)
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e1fa0f0..8c33ba8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@
 
 ### Fixed
 
+- Attach liveness: `parseHostStatus` reads autopg v3 `status` / `runtime.live` (a stopped pm2 registration is not live). `ensureHostRunning` requires TCP on the discovered port before attaching. `cedarpg acquire` with no listening host no longer talks to registered port 25432 (`ECONNREFUSED`); after a failed or no-op `autopg install` it starts an owned postmaster on 55432 unless `CEDAR_PG_EPHEMERAL_HOST=0`.
+- Ephemeral host: start detached `autopg postmaster` only. Do not run `install --no-pm2` (that rewrites `~/.autopg/admin.json` and fails with `supervisor mismatch` next to a local pm2 install).
 - TEMPLATE `cloneWorkerDatabase`: default clone name is unique per call (`<worker>_<pid>_<time>`) so Jest `setupFiles` (module reload per file) no longer hits `database already exists` on `_c_<workerId>`
 - Ephemeral host: prune stale `/dev/shm/cedar-pg-*` / `pgserve-*` / `PostgreSQL.*` when the recipe port is dead; append remount/cleanup hints on Disk quota / ENOSPC / 53100
 
diff --git a/README.md b/README.md
index 1799e9b..f1716a2 100644
--- a/README.md
+++ b/README.md
@@ -266,28 +266,28 @@ loadDevEnv({ overwrite: true }); // override .env DATABASE_URL from .cedarpg/dev
 
 ### Host startup (CI ephemeral)
 
-By default cedar-pg **attaches** to a live autopg host (`autopg status`). If none is live it runs bare `autopg install` (pm2) — fine for local machines, hostile to GitHub Actions (no pm2) and slower than RAM-backed CI.
+By default cedar-pg **attaches** to a live autopg host (`autopg status` plus TCP). A registered-but-stopped pm2 host is not live. If nothing is listening it tries bare `autopg install`, then an owned postmaster on 55432 — so `cedarpg acquire` works when autopg is installed but not running. GitHub Actions still skip pm2 via `CI=true`.
 
 In CI, cedar-pg starts an **opinionated ephemeral host** automatically when `CI=true` (or when forced). Callers just use `acquire` — no host options bag:
 
 ```ts
 import { acquire } from "@cedarjs/pg";
 
-// CI=true → install --no-pm2 --no-ui + detached postmaster (--ram on Linux /dev/shm)
+// CI=true → detached postmaster (--ram on Linux /dev/shm); does not rewrite ~/.autopg
 const { databaseUrl } = await acquire({ mode: "test" });
 ```
 
-| Signal                      | Effect                                                              |
-| --------------------------- | ------------------------------------------------------------------- |
-| `CEDAR_PG_EPHEMERAL_HOST=1` | Prefer ephemeral start when **no** host is live (attach still wins) |
-| `CEDAR_PG_EPHEMERAL_HOST=0` | Force local attach / pm2 install (even if `CI=true`)                |
-| unset + `CI=true`           | Prefer ephemeral when no host is live                               |
-| otherwise                   | Local: attach if live, else bare `autopg install`                   |
+| Signal                      | Effect                                                                         |
+| --------------------------- | ------------------------------------------------------------------------------ |
+| `CEDAR_PG_EPHEMERAL_HOST=1` | Prefer ephemeral start when **no** host is live (attach still wins)            |
+| `CEDAR_PG_EPHEMERAL_HOST=0` | Force local attach / pm2 install only (even if `CI=true`); no owned postmaster |
+| unset + `CI=true`           | Prefer ephemeral when no host is live                                          |
+| otherwise                   | Attach if live, else `autopg install`, else owned postmaster on 55432          |
 
 Ephemeral recipe (not configurable via cedar-pg):
 
-- `autopg install --no-pm2 --no-ui --port 55432 --data DIR`
 - detached `autopg postmaster --port 55432 --socket-dir DIR --data DIR`
+- does **not** run `autopg install` (that rewrites `~/.autopg/admin.json` and conflicts with a local pm2 host)
 - Linux when `/dev/shm` exists → also `--ram` and `DIR=/dev/shm/cedar-pg-<uid>`
 - otherwise → disk `DIR` under the OS temp dir (still owned, no pm2)
 - Ready when TCP accepts on the recipe port (not merely `autopg status` after install)
@@ -295,7 +295,7 @@ Ephemeral recipe (not configurable via cedar-pg):
   `/dev/shm/cedar-pg-*`, `pgserve-*`, and `PostgreSQL.*` (OOM-killed runs filling tmpfs).
   Safe on isolated CI VMs; on shared self-hosted runners another job’s leftovers could match those globs.
 
-If a host is already live, cedar-pg attaches and does not start another. The **CI job owns** ephemeral postmaster lifetime (runner teardown / `/dev/shm`); there is no cedar-pg host dispose API.
+If TCP already accepts on the discovered autopg port, or on the recipe port (55432) when an owned postmaster is allowed, cedar-pg attaches and does not start another. The **process/job owns** ephemeral postmaster lifetime (runner teardown / `/dev/shm`); there is no cedar-pg host dispose API.
 
 Cloud / small VMs often ship `/dev/shm` at ~64MB — too small for `--ram`. Remount before tests if needed (`sudo mount -o remount,size=6G /dev/shm`). See [Troubleshooting](#troubleshooting).
 
@@ -442,6 +442,7 @@ Worker adapters call `cloneFromTemplateIfNeeded` (shared skip policy via `runIfN
 
 | Symptom                                                                                 | Fix                                                                                                                                                                                                                                                                                                |
 | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ECONNREFUSED 127.0.0.1:25432` on `cedarpg acquire`                                     | autopg is registered (pm2) but not listening. cedar-pg no longer treats that as live; it starts an owned postmaster on 55432 unless `CEDAR_PG_EPHEMERAL_HOST=0`.                                                                                                                                   |
 | `database already exists: …_c_<workerId>` in Jest                                       | Use current `@cedarjs/pg` (unique default clone names). Prefer `setupFilesAfterEnv` + `beforeAll` (Jest globals). Both hooks run per test file — memo is per module load, not process-wide. Avoid bare `JEST_WORKER_ID` as an explicit `name`.                                                     |
 | Acquire skipped; tests hit shared / stale Postgres                                      | Real `.env` `TEST_DATABASE_URL` / `DATABASE_URL` trips the escape hatch. Set `CEDAR_PG_FORCE=1` once in `jest.config.js`, or `force: true` / `cedarpg run --force`.                                                                                                                                |
 | `Disk quota exceeded` / `No space left on device` / Postgres `53100` on ephemeral start | Enlarge `/dev/shm` (`sudo mount -o remount,size=6G /dev/shm`). On **isolated** runners only: `rm -rf /dev/shm/cedar-pg-* /dev/shm/pgserve-* /dev/shm/PostgreSQL.*`. Cold-start also prunes these when the recipe port is dead.                                                                     |
diff --git a/scripts/smoke-pg.mjs b/scripts/smoke-pg.mjs
index f6d0222..50af14e 100644
--- a/scripts/smoke-pg.mjs
+++ b/scripts/smoke-pg.mjs
@@ -1,12 +1,4 @@
 #!/usr/bin/env node
-/**
- * Adapter + real Postgres smoke: pack → install tarball in a temp consumer →
- * run Vitest and Jest through @cedarjs/pg adapters.
- *
- * Sets CI=true + CEDAR_PG_EPHEMERAL_HOST=1 so policy prefers ephemeral when no
- * host is live. Attach still wins if a host is already live — cold ephemeral
- * start is what empty CI runners exercise (workflow runs ci-install-autopg.sh).
- */
 import { cpSync } from "node:fs";
 import { join } from "node:path";
 import {
@@ -64,4 +56,23 @@ run("npx", ["jest", "--config", "jest.config.cjs", "--runInBand"], {
   env: smokeEnv,
 });
 
+console.log("==> cedarpg acquire / run / dispose");
+run("git", ["init"], { cwd: tmp, env: smokeEnv, silent: true });
+const cli = join(tmp, "node_modules", PACKAGE_NAME, "dist/cli.mjs");
+run("node", [cli, "acquire", "--mode=test", "--json"], { cwd: tmp, env: smokeEnv });
+run(
+  "node",
+  [
+    cli,
+    "run",
+    "--mode=test",
+    "--",
+    "node",
+    "-e",
+    "if (!process.env.DATABASE_URL.includes('/cpg_')) process.exit(1)",
+  ],
+  { cwd: tmp, env: smokeEnv },
+);
+run("node", [cli, "dispose", "--mode=test"], { cwd: tmp, env: smokeEnv });
+
 console.log("smoke-pg: PASS");
diff --git a/src/providers/autopg.ts b/src/providers/autopg.ts
index 040cf2d..6ab0e86 100644
--- a/src/providers/autopg.ts
+++ b/src/providers/autopg.ts
@@ -48,20 +48,35 @@ export function requireAutopgBin(): string {
   return bin;
 }
 
+function liveFlagFromRuntime(runtime: unknown): unknown {
+  if (runtime === null || typeof runtime !== "object") return undefined;
+  return "live" in runtime ? runtime.live : undefined;
+}
+
 /**
- * Parse `autopg status --json` output. Requires a numeric port and running !== false.
+ * Parse `autopg status --json`. Live means pm2 `status === "online"` (v3)
+ * and `runtime.live` is not false. `running: false` is also down.
  */
 export function parseHostStatus(json: string): { port: number } {
-  let parsed: { port?: unknown; running?: unknown };
+  let parsed: {
+    port?: unknown;
+    running?: unknown;
+    status?: unknown;
+    runtime?: unknown;
+  };
   try {
-    parsed = JSON.parse(json) as { port?: unknown; running?: unknown };
+    parsed = JSON.parse(json) as typeof parsed;
   } catch {
     throw new Error(`autopg status --json returned invalid JSON.\n${INSTALL_HINT}`);
   }
   if (typeof parsed.port !== "number") {
     throw new Error(`autopg status --json missing numeric port.\n${INSTALL_HINT}`);
   }
-  if (parsed.running === false) {
+  const down =
+    parsed.running === false ||
+    (typeof parsed.status === "string" && parsed.status !== "online") ||
+    liveFlagFromRuntime(parsed.runtime) === false;
+  if (down) {
     throw new Error(`autopg host is not running.\n${INSTALL_HINT}`);
   }
   return { port: parsed.port };
diff --git a/src/providers/host.ts b/src/providers/host.ts
index fa257ea..74e74b0 100644
--- a/src/providers/host.ts
+++ b/src/providers/host.ts
@@ -14,11 +14,9 @@ import {
 /** How cedar-pg starts an autopg host when none is already live. */
 export type HostStartPolicy = "local" | "ephemeral";
 
-/** Opinionated install + postmaster argv for CI / ephemeral runners. */
 export type EphemeralHostRecipe = {
   dataDir: string;
   port: number;
-  installArgs: string[];
   postmasterArgs: string[];
 };
 
@@ -31,7 +29,6 @@ export type EphemeralRecipeContext = {
   port?: number;
 };
 
-/** Fixed CI TCP port so install registration and postmaster listen on the same port. */
 const EPHEMERAL_PORT = 55432;
 
 const OWNED_POSTMASTER_READY_MS = 30_000;
@@ -66,10 +63,10 @@ export function resolveEphemeralHostPolicy(env: NodeJS.ProcessEnv = process.env)
   return "local";
 }
 
-/**
- * Fixed CI recipe: shared `--port` on install + postmaster, `--no-pm2 --no-ui`,
- * and `--ram` + `/dev/shm/cedar-pg-<uid>` on Linux when shm exists.
- */
+export function allowOwnedPostmasterFallback(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.CEDAR_PG_EPHEMERAL_HOST !== "0";
+}
+
 export function ephemeralHostRecipe(ctx: EphemeralRecipeContext = {}): EphemeralHostRecipe {
   const platform = ctx.platform ?? process.platform;
   const shmAvailable = ctx.shmAvailable ?? (platform === "linux" && existsSync("/dev/shm"));
@@ -80,8 +77,6 @@ export function ephemeralHostRecipe(ctx: EphemeralRecipeContext = {}): Ephemeral
     ? `/dev/shm/cedar-pg-${uid}`
     : join(ctx.tmpDir ?? tmpdir(), "cedar-pg-host");
 
-  const installArgs = ["install", "--no-pm2", "--no-ui", "--port", String(port), "--data", dataDir];
-  // Always pass --port/--data/--socket-dir so postmaster matches the install record.
   const postmasterArgs = [
     "postmaster",
     ...(useRam ? ["--ram"] : []),
@@ -93,10 +88,9 @@ export function ephemeralHostRecipe(ctx: EphemeralRecipeContext = {}): Ephemeral
     dataDir,
   ];
 
-  return { dataDir, port, installArgs, postmasterArgs };
+  return { dataDir, port, postmasterArgs };
 }
 
-/** Discovery from the recipe port — TCP readiness is the authority, not `autopg status`. */
 export function discoveryFromRecipe(bin: string, recipe: EphemeralHostRecipe): AutopgDiscovery {
   return { port: recipe.port, adminUrl: adminUrlFor(recipe.port), bin };
 }
@@ -200,7 +194,10 @@ function canConnect(port: number): Promise<boolean> {
   });
 }
 
-/** Kill a detached owned postmaster (process group when possible) and drop our handle. */
+function releaseOwnedChild(child: ChildProcess): void {
+  child.unref();
+}
+
 function killOwnedChild(child: ChildProcess): void {
   const pid = child.pid;
   if (pid != null) {
@@ -214,7 +211,7 @@ function killOwnedChild(child: ChildProcess): void {
       }
     }
   }
-  child.unref();
+  releaseOwnedChild(child);
 }
 
 export type WaitForOwnedPostmasterOptions = {
@@ -254,14 +251,6 @@ export async function waitForOwnedPostmaster(opts: WaitForOwnedPostmasterOptions
   );
 }
 
-/**
- * Install + detached postmaster with fully ignored stdio so the CI job owns lifetime
- * (caller exit must not close pipes under the daemon).
- *
- * Readiness is TCP accept on the recipe port — not `autopg status`, which succeeds
- * after `install --no-pm2` before postmaster is listening. On success, discovery is
- * recipe-derived (same port). On failure, the spawned child is killed.
- */
 async function startEphemeralHost(bin: string): Promise<AutopgDiscovery> {
   const recipe = ephemeralHostRecipe();
   const useRamShm = recipe.postmasterArgs.includes("--ram");
@@ -284,7 +273,6 @@ async function startEphemeralHost(bin: string): Promise<AutopgDiscovery> {
   }
 
   mkdirSync(recipe.dataDir, { recursive: true });
-  runInstall(bin, recipe.installArgs, useRamShm);
 
   const state: {
     exit: { code: number | null; signal: NodeJS.Signals | null } | null;
@@ -331,32 +319,49 @@ async function startEphemeralHost(bin: string): Promise<AutopgDiscovery> {
     throw err;
   }
 
-  // Success: job owns lifetime — drop our handle without killing.
-  child.unref();
+  releaseOwnedChild(child);
   return discoveryFromRecipe(bin, recipe);
 }
 
-/**
- * Ensure the host postmaster is up.
- *
- * - Attaches when `autopg status --json` shows a live host.
- * - Otherwise starts from {@link resolveEphemeralHostPolicy}: local pm2 `install`,
- *   or opinionated ephemeral (`--no-pm2 --no-ui` + detached postmaster).
- * - CI job owns ephemeral postmaster lifetime on success (no cedar-pg host dispose).
- * - Failed ephemeral start kills the spawned child so ensure is atomic for the caller.
- * - Before ephemeral cold-start, prunes stale `/dev/shm` leftovers when the recipe port is dead.
- */
-export async function ensureHostRunning(bin = requireAutopgBin()): Promise<AutopgDiscovery> {
+async function startOrReuseEphemeral(bin: string): Promise<AutopgDiscovery> {
+  const recipe = ephemeralHostRecipe();
+  if (await canConnect(recipe.port)) return discoveryFromRecipe(bin, recipe);
+  return startEphemeralHost(bin);
+}
+
+async function attachLiveDiscovery(bin: string): Promise<AutopgDiscovery | null> {
+  let discovered: AutopgDiscovery;
   try {
-    return discoverHost(bin);
+    discovered = discoverHost(bin);
   } catch {
-    // status failed — start host per policy
+    return null;
   }
+  return (await canConnect(discovered.port)) ? discovered : null;
+}
+
+export async function ensureHostRunning(bin = requireAutopgBin()): Promise<AutopgDiscovery> {
+  const attached = await attachLiveDiscovery(bin);
+  if (attached) return attached;
 
   if (resolveEphemeralHostPolicy() === "ephemeral") {
-    return startEphemeralHost(bin);
+    return startOrReuseEphemeral(bin);
   }
 
-  runInstall(bin, ["install"], false);
-  return discoverHost(bin);
+  let installError: unknown;
+  try {
+    runInstall(bin, ["install"], false);
+  } catch (err) {
+    installError = err;
+  }
+  if (installError == null) {
+    const afterInstall = await attachLiveDiscovery(bin);
+    if (afterInstall) return afterInstall;
+  }
+
+  if (!allowOwnedPostmasterFallback()) {
+    throw installError instanceof Error
+      ? installError
+      : new Error(`autopg host is not running.\n${INSTALL_HINT}`);
+  }
+  return startOrReuseEphemeral(bin);
 }
diff --git a/tests/autopg.test.ts b/tests/autopg.test.ts
index 75d0569..884a799 100644
--- a/tests/autopg.test.ts
+++ b/tests/autopg.test.ts
@@ -8,12 +8,31 @@ import {
 } from "../src/providers/autopg.ts";
 
 test("parseHostStatus requires numeric port", () => {
-  expect(parseHostStatus('{"port":5433,"running":true}')).toEqual({ port: 5433 });
-  expect(() => parseHostStatus('{"running":true}')).toThrow(/missing numeric port/);
-  expect(() => parseHostStatus('{"port":5432,"running":false}')).toThrow(/not running/);
+  expect(parseHostStatus('{"port":5433,"status":"online"}')).toEqual({ port: 5433 });
+  expect(() => parseHostStatus('{"status":"online"}')).toThrow(/missing numeric port/);
   expect(() => parseHostStatus("not-json")).toThrow(/invalid JSON/);
 });
 
+test("parseHostStatus treats autopg v3 status JSON as live only when online", () => {
+  const stopped = `{
+    "installed": true,
+    "name": "autopg-server",
+    "status": "stopped",
+    "pid": null,
+    "port": 25432,
+    "runtime": null
+  }`;
+  expect(() => parseHostStatus(stopped)).toThrow(/not running/);
+  expect(() => parseHostStatus('{"port":55432,"status":"errored"}')).toThrow(/not running/);
+  expect(() =>
+    parseHostStatus('{"port":55432,"status":"online","runtime":{"live":false}}'),
+  ).toThrow(/not running/);
+  expect(
+    parseHostStatus('{"port":55432,"status":"online","pid":1,"runtime":{"live":true}}'),
+  ).toEqual({ port: 55432 });
+  expect(() => parseHostStatus('{"port":5432,"running":false}')).toThrow(/not running/);
+});
+
 test("adminUrlFor uses autopg default credentials and AUTOPG_PG_* overrides", () => {
   expect(adminUrlFor(25432, {})).toBe("postgresql://postgres:postgres@127.0.0.1:25432/postgres");
   expect(
diff --git a/tests/host.test.ts b/tests/host.test.ts
index 2cf9890..7d8ac39 100644
--- a/tests/host.test.ts
+++ b/tests/host.test.ts
@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { adminUrlFor } from "../src/providers/autopg.ts";
 import {
+  allowOwnedPostmasterFallback,
   discoveryFromRecipe,
   ephemeralHostRecipe,
   EPHEMERAL_SHM_HINT,
@@ -22,6 +23,13 @@ test("resolveEphemeralHostPolicy from CEDAR_PG_EPHEMERAL_HOST and CI", () => {
   expect(resolveEphemeralHostPolicy({})).toBe("local");
 });
 
+test("allowOwnedPostmasterFallback is off only when CEDAR_PG_EPHEMERAL_HOST=0", () => {
+  expect(allowOwnedPostmasterFallback({})).toBe(true);
+  expect(allowOwnedPostmasterFallback({ CI: "true" })).toBe(true);
+  expect(allowOwnedPostmasterFallback({ CEDAR_PG_EPHEMERAL_HOST: "1" })).toBe(true);
+  expect(allowOwnedPostmasterFallback({ CEDAR_PG_EPHEMERAL_HOST: "0" })).toBe(false);
+});
+
 test("ephemeralHostRecipe uses RAM on Linux when /dev/shm is available", () => {
   const recipe = ephemeralHostRecipe({
     platform: "linux",
@@ -30,15 +38,7 @@ test("ephemeralHostRecipe uses RAM on Linux when /dev/shm is available", () => {
   });
   expect(recipe.dataDir).toBe("/dev/shm/cedar-pg-1000");
   expect(recipe.port).toBe(55432);
-  expect(recipe.installArgs).toEqual([
-    "install",
-    "--no-pm2",
-    "--no-ui",
-    "--port",
-    "55432",
-    "--data",
-    "/dev/shm/cedar-pg-1000",
-  ]);
+  expect(recipe).not.toHaveProperty("installArgs");
   expect(recipe.postmasterArgs).toEqual([
     "postmaster",
     "--ram",
@@ -61,15 +61,7 @@ test("ephemeralHostRecipe falls back to disk tmpdir without --ram", () => {
   });
   expect(recipe.dataDir).toBe("/tmp/cedar-test/cedar-pg-host");
   expect(recipe.port).toBe(55433);
-  expect(recipe.installArgs).toEqual([
-    "install",
-    "--no-pm2",
-    "--no-ui",
-    "--port",
-    "55433",
-    "--data",
-    "/tmp/cedar-test/cedar-pg-host",
-  ]);
+  expect(recipe).not.toHaveProperty("installArgs");
   expect(recipe.postmasterArgs).toEqual([
     "postmaster",
     "--port",

From b7d38ce0d44c3ebe3cc5583d152497dfaa12af94 Mon Sep 17 00:00:00 2001
From: Simon Gagnon <git@simoncrypta.dev>
Date: Sat, 5 Sep 2026 17:09:05 -0400
Subject: [PATCH 2/2] fix(host): revive the registered autopg host instead of a
 second Postgres

Stopped pm2 still reports a port; attach requires TCP. Local acquire runs
autopg restart then install and waits for a listener. Owned postmaster
stays CI/ephemeral-only.
---
 AGENTS.md               |   4 +-
 CHANGELOG.md            |   8 +-
 README.md               |  40 +++---
 scripts/smoke-pg.mjs    |   9 ++
 src/providers/autopg.ts |  32 ++---
 src/providers/host.ts   | 269 ++++++++++++++++++++++------------------
 tests/autopg.test.ts    |  21 ++--
 tests/host.test.ts      | 255 +++++++++++++++++++++++--------------
 8 files changed, 369 insertions(+), 269 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 7efafea..e6517c7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -80,7 +80,7 @@ Keep logic in the canonical layer. Prefer reuse over one-off branches in adapter
 | Skip policy (`CEDAR_PG=0`, external URL, force) | `src/core/policy.ts` (`resolveAcquireSkip`, `runIfNeeded`, `applyDatabaseUrlEnv`)  |
 | TEMPLATE mark / clone                           | `src/core/template.ts`                                                             |
 | Lease read/write / registry                     | `src/core/lease.ts`                                                                |
-| Host attach vs ephemeral CI start               | `src/providers/host.ts` (internal; `ensureHostRunning` is **not** a public export) |
+| Host attach / local recovery / ephemeral start  | `src/providers/host.ts` (internal; `ensureHostRunning` is **not** a public export) |
 | SQL / autopg CLI / URLs / role password         | `src/providers/autopg.ts`                                                          |
 | Shared Vite+/Nx task strings                    | `src/adapters/tasks.ts` (`cedarPgLifecycleTargets`, `cedarPgRunCommand`)           |
 | Runner TEMPLATE orchestration + migrate hook    | `src/adapters/template-mode.ts` → thin Jest/Vitest wrappers                        |
@@ -89,7 +89,7 @@ Keep logic in the canonical layer. Prefer reuse over one-off branches in adapter
 
 **Migrate stays app-owned.** Stock `@cedarjs/pg/jest` / `vitest` only acquire/dispose. TEMPLATE adapters require `createGlobalSetup({ migrate })`; string-resolving the package entry without a migrate hook must throw.
 
-**Host bootstrap stays internal.** Callers use `acquire` (and `adminUrl`). Do not re-export `ensureHostRunning` or grow a public host-options bag; ephemeral behavior is env-driven (`CI`, `CEDAR_PG_EPHEMERAL_HOST`). Default local acquire may start an owned postmaster after a no-op `autopg install` (stopped pm2); `CEDAR_PG_EPHEMERAL_HOST=0` disables that fallback.
+**Host bootstrap stays internal.** Callers use `acquire` (and `adminUrl`). Do not re-export `ensureHostRunning` or grow a public host-options bag; ephemeral behavior is env-driven (`CI`, `CEDAR_PG_EPHEMERAL_HOST`). Liveness is a TCP accept, never `autopg status` alone. Local recovery revives the **registered** host (`autopg restart`, then `autopg install`) — an owned postmaster is ephemeral/CI-only, and `CEDAR_PG_EPHEMERAL_HOST=0` disables it everywhere. Do not add a second local Postgres port/data dir.
 
 ## Env and policy (easy to get wrong)
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8c33ba8..9007f90 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,11 +4,17 @@
 
 ### Fixed
 
-- Attach liveness: `parseHostStatus` reads autopg v3 `status` / `runtime.live` (a stopped pm2 registration is not live). `ensureHostRunning` requires TCP on the discovered port before attaching. `cedarpg acquire` with no listening host no longer talks to registered port 25432 (`ECONNREFUSED`); after a failed or no-op `autopg install` it starts an owned postmaster on 55432 unless `CEDAR_PG_EPHEMERAL_HOST=0`.
+- Attach liveness is a TCP accept, never `autopg status` alone: `cedarpg acquire` no longer connects to a registered-but-stopped host (`ECONNREFUSED 127.0.0.1:25432`).
+- Local host recovery brings the **registered** autopg host back: `autopg restart`, then `autopg install` if still no listener, then attach once TCP accepts (error names the registered port and lists what was tried). `restart` exiting 0 is not treated as live. Same port and `~/.autopg/data`; cedar-pg never starts a second local Postgres.
+- `CEDAR_PG_EPHEMERAL_HOST=0` now has one meaning: never start an owned postmaster (even under `CI=true`) — local autopg host only, or fail.
 - Ephemeral host: start detached `autopg postmaster` only. Do not run `install --no-pm2` (that rewrites `~/.autopg/admin.json` and fails with `supervisor mismatch` next to a local pm2 install).
 - TEMPLATE `cloneWorkerDatabase`: default clone name is unique per call (`<worker>_<pid>_<time>`) so Jest `setupFiles` (module reload per file) no longer hits `database already exists` on `_c_<workerId>`
 - Ephemeral host: prune stale `/dev/shm/cedar-pg-*` / `pgserve-*` / `PostgreSQL.*` when the recipe port is dead; append remount/cleanup hints on Disk quota / ENOSPC / 53100
 
+### Changed
+
+- `parseHostStatus` / `discoverHost` (public) report the **registered** port and no longer throw on a stopped host — supervisor-specific `status` strings (pm2 `online` vs systemd-user / launchd) are not a liveness model. Probe TCP, or use `acquire`, before connecting.
+
 ### Docs
 
 - Nx canonical shape (`db:ready` + `cedarpg run --force`), Jest `CEDAR_PG_FORCE` + `setupFilesAfterEnv`, Yarn ignore-scripts CI recipe, `/dev/shm` troubleshooting, alpha caveat version
diff --git a/README.md b/README.md
index f1716a2..f4a75bb 100644
--- a/README.md
+++ b/README.md
@@ -264,9 +264,11 @@ await drop();
 loadDevEnv({ overwrite: true }); // override .env DATABASE_URL from .cedarpg/dev.env
 ```
 
-### Host startup (CI ephemeral)
+### Host startup (local recovery, CI ephemeral)
 
-By default cedar-pg **attaches** to a live autopg host (`autopg status` plus TCP). A registered-but-stopped pm2 host is not live. If nothing is listening it tries bare `autopg install`, then an owned postmaster on 55432 — so `cedarpg acquire` works when autopg is installed but not running. GitHub Actions still skip pm2 via `CI=true`.
+cedar-pg **attaches** to the autopg host as soon as TCP accepts on the port from `autopg status --json`. Registration is not liveness: an installed-but-stopped host still reports port 25432, and attaching to it was the `ECONNREFUSED 127.0.0.1:25432` bug.
+
+When nothing is listening, cedar-pg brings **your** autopg host up — `autopg restart` (autopg's start verb), then `autopg install` if the host was never registered — and attaches once TCP accepts. Same singleton, same port, same `~/.autopg/data`, still running after your process exits. If neither verb produces a listener, `acquire` fails with what it tried instead of connecting to a dead port. cedar-pg never runs a second local Postgres.
 
 In CI, cedar-pg starts an **opinionated ephemeral host** automatically when `CI=true` (or when forced). Callers just use `acquire` — no host options bag:
 
@@ -277,12 +279,12 @@ import { acquire } from "@cedarjs/pg";
 const { databaseUrl } = await acquire({ mode: "test" });
 ```
 
-| Signal                      | Effect                                                                         |
-| --------------------------- | ------------------------------------------------------------------------------ |
-| `CEDAR_PG_EPHEMERAL_HOST=1` | Prefer ephemeral start when **no** host is live (attach still wins)            |
-| `CEDAR_PG_EPHEMERAL_HOST=0` | Force local attach / pm2 install only (even if `CI=true`); no owned postmaster |
-| unset + `CI=true`           | Prefer ephemeral when no host is live                                          |
-| otherwise                   | Attach if live, else `autopg install`, else owned postmaster on 55432          |
+| Signal                      | Effect (attach always wins when something is listening)                       |
+| --------------------------- | ----------------------------------------------------------------------------- |
+| `CEDAR_PG_EPHEMERAL_HOST=1` | Ephemeral: owned postmaster on 55432                                          |
+| `CEDAR_PG_EPHEMERAL_HOST=0` | Never own a postmaster (even when `CI=true`): local autopg host only, or fail |
+| unset + `CI=true`           | Ephemeral                                                                     |
+| unset                       | Local: `autopg restart`, then `autopg install`, then fail                     |
 
 Ephemeral recipe (not configurable via cedar-pg):
 
@@ -295,7 +297,7 @@ Ephemeral recipe (not configurable via cedar-pg):
   `/dev/shm/cedar-pg-*`, `pgserve-*`, and `PostgreSQL.*` (OOM-killed runs filling tmpfs).
   Safe on isolated CI VMs; on shared self-hosted runners another job’s leftovers could match those globs.
 
-If TCP already accepts on the discovered autopg port, or on the recipe port (55432) when an owned postmaster is allowed, cedar-pg attaches and does not start another. The **process/job owns** ephemeral postmaster lifetime (runner teardown / `/dev/shm`); there is no cedar-pg host dispose API.
+If TCP already accepts on the discovered autopg port — or, in ephemeral mode, on the recipe port (55432) — cedar-pg attaches and does not start another. The **CI job owns** ephemeral postmaster lifetime (runner teardown / `/dev/shm`); there is no cedar-pg host dispose API.
 
 Cloud / small VMs often ship `/dev/shm` at ~64MB — too small for `--ram`. Remount before tests if needed (`sudo mount -o remount,size=6G /dev/shm`). See [Troubleshooting](#troubleshooting).
 
@@ -423,7 +425,7 @@ Worker adapters call `cloneFromTemplateIfNeeded` (shared skip policy via `runIfN
 | `CEDAR_PG=0`                   | Disable auto-acquire in adapters                                                                               |
 | `TEST_DATABASE_URL`            | Escape hatch: skip acquire for real external DBs (not `cpg_*` / `file:` / `{…}` / `<…>` template placeholders) |
 | `CEDAR_PG_FORCE=1`             | Ignore external-URL escape hatch (adapters + `cedarpg acquire --force` / `run --force`)                        |
-| `CEDAR_PG_EPHEMERAL_HOST`      | `1` force / `0` disable ephemeral host (auto when `CI=true`)                                                   |
+| `CEDAR_PG_EPHEMERAL_HOST`      | `1` owned postmaster; `0` never own one (even in CI); unset + `CI=true` → ephemeral                            |
 | `CEDAR_PG_REGISTRY_DIR`        | Override global lease registry (for `gc`)                                                                      |
 | `CEDAR_PG_SKIP_POSTINSTALL=1`  | Skip autopg install hook                                                                                       |
 | `CEDAR_PG_INSTALL_AUTOPG=1`    | Under `CI=true`, run binary-only `ci-install-autopg.sh` from postinstall                                       |
@@ -440,12 +442,12 @@ Worker adapters call `cloneFromTemplateIfNeeded` (shared skip policy via `runIfN
 
 ## Troubleshooting
 
-| Symptom                                                                                 | Fix                                                                                                                                                                                                                                                                                                |
-| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ECONNREFUSED 127.0.0.1:25432` on `cedarpg acquire`                                     | autopg is registered (pm2) but not listening. cedar-pg no longer treats that as live; it starts an owned postmaster on 55432 unless `CEDAR_PG_EPHEMERAL_HOST=0`.                                                                                                                                   |
-| `database already exists: …_c_<workerId>` in Jest                                       | Use current `@cedarjs/pg` (unique default clone names). Prefer `setupFilesAfterEnv` + `beforeAll` (Jest globals). Both hooks run per test file — memo is per module load, not process-wide. Avoid bare `JEST_WORKER_ID` as an explicit `name`.                                                     |
-| Acquire skipped; tests hit shared / stale Postgres                                      | Real `.env` `TEST_DATABASE_URL` / `DATABASE_URL` trips the escape hatch. Set `CEDAR_PG_FORCE=1` once in `jest.config.js`, or `force: true` / `cedarpg run --force`.                                                                                                                                |
-| `Disk quota exceeded` / `No space left on device` / Postgres `53100` on ephemeral start | Enlarge `/dev/shm` (`sudo mount -o remount,size=6G /dev/shm`). On **isolated** runners only: `rm -rf /dev/shm/cedar-pg-* /dev/shm/pgserve-* /dev/shm/PostgreSQL.*`. Cold-start also prunes these when the recipe port is dead.                                                                     |
-| `autopg: command not found` in CI with Yarn `YARN_ENABLE_SCRIPTS=false`                 | `CEDAR_PG_INSTALL_AUTOPG=1` is not enough when lifecycle scripts are off. With `nodeLinker: node-modules`, run `bash node_modules/@cedarjs/pg/scripts/ci-install-autopg.sh` and put `~/.local/bin` on `PATH` (or use `setup-autopg`). PnP: resolve the script path via Yarn, or prefer the Action. |
-| Nx child still uses `.env` `DATABASE_URL`                                               | `dependsOn` does not forward acquire env. Wrap with `cedarpg run --mode=dev --force -- <cmd>`, or `loadDevEnv({ overwrite: true })`.                                                                                                                                                               |
-| Role/DB errors under parallel Nx targets                                                | Do not run concurrent `acquire` / `run` on the same worktree. One `db:ready`, then `run` wrappers.                                                                                                                                                                                                 |
+| Symptom                                                                                 | Fix                                                                                                                                                                                                                                                                                                                                          |
+| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ECONNREFUSED 127.0.0.1:25432` on `cedarpg acquire`                                     | autopg is registered but not listening. cedar-pg no longer treats registration as live: it runs `autopg restart` (then `install`) and attaches once TCP accepts. `restart` exiting 0 is not proof — when pm2 is missing it still prints “respawned daemon”. If both verbs fail, install pm2 / fix the supervisor (`pm2 logs autopg-server`). |
+| `database already exists: …_c_<workerId>` in Jest                                       | Use current `@cedarjs/pg` (unique default clone names). Prefer `setupFilesAfterEnv` + `beforeAll` (Jest globals). Both hooks run per test file — memo is per module load, not process-wide. Avoid bare `JEST_WORKER_ID` as an explicit `name`.                                                                                               |
+| Acquire skipped; tests hit shared / stale Postgres                                      | Real `.env` `TEST_DATABASE_URL` / `DATABASE_URL` trips the escape hatch. Set `CEDAR_PG_FORCE=1` once in `jest.config.js`, or `force: true` / `cedarpg run --force`.                                                                                                                                                                          |
+| `Disk quota exceeded` / `No space left on device` / Postgres `53100` on ephemeral start | Enlarge `/dev/shm` (`sudo mount -o remount,size=6G /dev/shm`). On **isolated** runners only: `rm -rf /dev/shm/cedar-pg-* /dev/shm/pgserve-* /dev/shm/PostgreSQL.*`. Cold-start also prunes these when the recipe port is dead.                                                                                                               |
+| `autopg: command not found` in CI with Yarn `YARN_ENABLE_SCRIPTS=false`                 | `CEDAR_PG_INSTALL_AUTOPG=1` is not enough when lifecycle scripts are off. With `nodeLinker: node-modules`, run `bash node_modules/@cedarjs/pg/scripts/ci-install-autopg.sh` and put `~/.local/bin` on `PATH` (or use `setup-autopg`). PnP: resolve the script path via Yarn, or prefer the Action.                                           |
+| Nx child still uses `.env` `DATABASE_URL`                                               | `dependsOn` does not forward acquire env. Wrap with `cedarpg run --mode=dev --force -- <cmd>`, or `loadDevEnv({ overwrite: true })`.                                                                                                                                                                                                         |
+| Role/DB errors under parallel Nx targets                                                | Do not run concurrent `acquire` / `run` on the same worktree. One `db:ready`, then `run` wrappers.                                                                                                                                                                                                                                           |
diff --git a/scripts/smoke-pg.mjs b/scripts/smoke-pg.mjs
index 50af14e..1f2146a 100644
--- a/scripts/smoke-pg.mjs
+++ b/scripts/smoke-pg.mjs
@@ -1,4 +1,13 @@
 #!/usr/bin/env node
+/**
+ * Adapter + real Postgres smoke: pack → install tarball in a temp consumer →
+ * run Vitest, Jest, and the CLI through @cedarjs/pg.
+ *
+ * Sets CI=true + CEDAR_PG_EPHEMERAL_HOST=1 so policy starts an owned ephemeral
+ * postmaster when nothing is listening — what empty CI runners exercise (the
+ * workflow installs the binary only, via ci-install-autopg.sh). Attach still
+ * wins if a host is already live.
+ */
 import { cpSync } from "node:fs";
 import { join } from "node:path";
 import {
diff --git a/src/providers/autopg.ts b/src/providers/autopg.ts
index 6ab0e86..a09270b 100644
--- a/src/providers/autopg.ts
+++ b/src/providers/autopg.ts
@@ -48,22 +48,17 @@ export function requireAutopgBin(): string {
   return bin;
 }
 
-function liveFlagFromRuntime(runtime: unknown): unknown {
-  if (runtime === null || typeof runtime !== "object") return undefined;
-  return "live" in runtime ? runtime.live : undefined;
-}
-
 /**
- * Parse `autopg status --json`. Live means pm2 `status === "online"` (v3)
- * and `runtime.live` is not false. `running: false` is also down.
+ * Parse `autopg status --json` → the **registered** port. Throws only when the
+ * output is not autopg status JSON.
+ *
+ * Registration is not liveness: autopg reports a port for a stopped host too,
+ * and its `status` string is supervisor-specific (pm2 `online`, systemd-user /
+ * launchd differ). Liveness is a TCP accept on the port, proven by the caller —
+ * `acquire` does that before it connects.
  */
 export function parseHostStatus(json: string): { port: number } {
-  let parsed: {
-    port?: unknown;
-    running?: unknown;
-    status?: unknown;
-    runtime?: unknown;
-  };
+  let parsed: { port?: unknown };
   try {
     parsed = JSON.parse(json) as typeof parsed;
   } catch {
@@ -72,13 +67,6 @@ export function parseHostStatus(json: string): { port: number } {
   if (typeof parsed.port !== "number") {
     throw new Error(`autopg status --json missing numeric port.\n${INSTALL_HINT}`);
   }
-  const down =
-    parsed.running === false ||
-    (typeof parsed.status === "string" && parsed.status !== "online") ||
-    liveFlagFromRuntime(parsed.runtime) === false;
-  if (down) {
-    throw new Error(`autopg host is not running.\n${INSTALL_HINT}`);
-  }
   return { port: parsed.port };
 }
 
@@ -101,7 +89,9 @@ export function adminUrlFor(port: number, env: NodeJS.ProcessEnv = process.env):
 }
 
 /**
- * Discover a live autopg host via `autopg status --json`. Throws if the host is not proven live.
+ * Discover the registered autopg host (port + admin URL) via `autopg status --json`.
+ * Throws when autopg cannot be queried; does **not** prove a listener — probe TCP
+ * (or use `acquire`, which does) before connecting.
  */
 export function discoverHost(bin = requireAutopgBin()): AutopgDiscovery {
   let status: string;
diff --git a/src/providers/host.ts b/src/providers/host.ts
index 74e74b0..25fbfda 100644
--- a/src/providers/host.ts
+++ b/src/providers/host.ts
@@ -11,7 +11,7 @@ import {
   type AutopgDiscovery,
 } from "./autopg.ts";
 
-/** How cedar-pg starts an autopg host when none is already live. */
+/** How cedar-pg brings up an autopg host when nothing is listening. */
 export type HostStartPolicy = "local" | "ephemeral";
 
 export type EphemeralHostRecipe = {
@@ -31,8 +31,27 @@ export type EphemeralRecipeContext = {
 
 const EPHEMERAL_PORT = 55432;
 
-const OWNED_POSTMASTER_READY_MS = 30_000;
-const OWNED_POSTMASTER_POLL_MS = 200;
+const HOST_READY_MS = 30_000;
+const HOST_POLL_MS = 200;
+/** `pm2 restart` of an existing process is quick; 30s is only for first `install` / initdb. */
+const LOCAL_RESTART_READY_MS = 10_000;
+
+/**
+ * autopg verbs that can bring the *registered* local host up, cheapest fix first.
+ *
+ * `restart` exit 0 is not evidence of a listener: when pm2 is missing or does not
+ * list `autopg-server`, autopg still prints "respawned daemon" and returns 0.
+ * That is why every verb is followed by a TCP wait, not trusted on exit status.
+ *
+ * `install` covers a never-registered machine (postinstall ships the binary only)
+ * and a reboot whose pm2 list is empty (`pm2 start`). On an already-registered
+ * host it is a no-op for the server process but may `pm2 start` the autopg UI —
+ * so it runs only after `restart` failed to produce a listener.
+ */
+const LOCAL_START = [
+  { argv: ["restart"], readyMs: LOCAL_RESTART_READY_MS },
+  { argv: ["install"], readyMs: HOST_READY_MS },
+] as const;
 
 /** Soft minimum free bytes on /dev/shm before RAM-backed ephemeral start (warns only). */
 export const EPHEMERAL_SHM_MIN_FREE_BYTES = 512 * 1024 * 1024;
@@ -48,14 +67,14 @@ export const EPHEMERAL_SHM_HINT =
   "     rm -rf /dev/shm/cedar-pg-* /dev/shm/pgserve-* /dev/shm/PostgreSQL.*";
 
 /**
- * Resolve whether to start an owned ephemeral postmaster or use local pm2 install.
+ * Resolve how to start a host when none is listening.
  *
- * - `CEDAR_PG_EPHEMERAL_HOST=1` → ephemeral
- * - `CEDAR_PG_EPHEMERAL_HOST=0` → local (even when `CI=true`)
+ * - `CEDAR_PG_EPHEMERAL_HOST=1` → ephemeral owned postmaster
+ * - `CEDAR_PG_EPHEMERAL_HOST=0` → never own a postmaster, local autopg only (even in CI)
  * - unset + `CI=true` → ephemeral
  * - otherwise → local
  */
-export function resolveEphemeralHostPolicy(env: NodeJS.ProcessEnv = process.env): HostStartPolicy {
+export function resolveHostStartPolicy(env: NodeJS.ProcessEnv = process.env): HostStartPolicy {
   const force = env.CEDAR_PG_EPHEMERAL_HOST;
   if (force === "1") return "ephemeral";
   if (force === "0") return "local";
@@ -63,10 +82,6 @@ export function resolveEphemeralHostPolicy(env: NodeJS.ProcessEnv = process.env)
   return "local";
 }
 
-export function allowOwnedPostmasterFallback(env: NodeJS.ProcessEnv = process.env): boolean {
-  return env.CEDAR_PG_EPHEMERAL_HOST !== "0";
-}
-
 export function ephemeralHostRecipe(ctx: EphemeralRecipeContext = {}): EphemeralHostRecipe {
   const platform = ctx.platform ?? process.platform;
   const shmAvailable = ctx.shmAvailable ?? (platform === "linux" && existsSync("/dev/shm"));
@@ -104,27 +119,24 @@ export function looksLikeShmSpaceError(text: string): boolean {
   return /Disk quota exceeded|No space left on device|ENOSPC|\b53100\b/i.test(text);
 }
 
-export function formatHostStartError(detail: string, useRamShm: boolean): string {
+export function formatHostStartError(detail: string, useRamShm = false): string {
   const hint = useRamShm && looksLikeShmSpaceError(detail) ? `\n${EPHEMERAL_SHM_HINT}` : "";
   return `Failed to start autopg host.\n${detail}\n${INSTALL_HINT}${hint}`;
 }
 
 /**
- * Remove leftover ephemeral data dirs under `/dev/shm` (and the recipe dataDir)
- * when the recipe port is not live. Safe for OOM-killed CI/cloud runs that leave
- * `cedar-pg-*` / `pgserve-*` / `PostgreSQL.*` filling tmpfs.
+ * Remove leftover ephemeral data dirs under `/dev/shm` (and the recipe dataDir).
+ * Safe for OOM-killed CI/cloud runs that leave `cedar-pg-*` / `pgserve-*` /
+ * `PostgreSQL.*` filling tmpfs.
  *
- * Does nothing when `portLive` is true (another host owns the port).
+ * Only called on ephemeral cold start, i.e. when the recipe port has no listener —
+ * never while a host owns those dirs.
  */
 export function pruneStaleEphemeralDataDirs(opts: {
   dataDir: string;
   /** Parent of RAM dirs; default `/dev/shm` when it exists. */
   shmRoot?: string;
-  /** When true, skip all deletes. */
-  portLive: boolean;
 }): string[] {
-  if (opts.portLive) return [];
-
   const removed: string[] = [];
   const tryRm = (path: string) => {
     if (!existsSync(path)) return;
@@ -161,7 +173,7 @@ export function pruneStaleEphemeralDataDirs(opts: {
 }
 
 /** Free bytes on `path`, or `null` if unavailable. */
-export function freeBytesOn(path: string): number | null {
+function freeBytesOn(path: string): number | null {
   try {
     const s = statfsSync(path);
     return Number(s.bavail) * Number(s.bsize);
@@ -170,15 +182,15 @@ export function freeBytesOn(path: string): number | null {
   }
 }
 
-function runInstall(bin: string, args: string[], useRamShm: boolean): void {
-  const install = spawnSync(bin, args, {
+/** Run a one-shot autopg verb. Returns failure detail, or `null` on exit 0. */
+function runAutopg(bin: string, argv: string[]): string | null {
+  const result = spawnSync(bin, argv, {
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"],
   });
-  if (install.status !== 0) {
-    const detail = `exit ${install.status}\n${install.stderr || install.stdout || ""}`.trim();
-    throw new Error(formatHostStartError(detail, useRamShm));
-  }
+  if (result.error) return result.error.message;
+  if (result.status === 0) return null;
+  return `exit ${result.status}\n${(result.stderr || result.stdout || "").trim()}`.trim();
 }
 
 /** True when something accepts TCP on 127.0.0.1:port (postmaster live, not just admin.json). */
@@ -194,10 +206,6 @@ function canConnect(port: number): Promise<boolean> {
   });
 }
 
-function releaseOwnedChild(child: ChildProcess): void {
-  child.unref();
-}
-
 function killOwnedChild(child: ChildProcess): void {
   const pid = child.pid;
   if (pid != null) {
@@ -211,57 +219,104 @@ function killOwnedChild(child: ChildProcess): void {
       }
     }
   }
-  releaseOwnedChild(child);
+  child.unref();
 }
 
-export type WaitForOwnedPostmasterOptions = {
+export type WaitForListenerOptions = {
   port: number;
+  /** Total grace period; `0` (default) probes exactly once. */
   readyMs?: number;
   pollMs?: number;
   canConnect?: (port: number) => Promise<boolean>;
   now?: () => number;
   sleep?: (ms: number) => Promise<void>;
-  /** Return an Error to fail fast (spawn error / early exit). */
+  /** Return an Error to abort early (spawn error / child exit). */
   failure?: () => Error | null;
 };
 
 /**
- * Poll until TCP accepts on port, or throw on timeout / {@link WaitForOwnedPostmasterOptions.failure}.
- * Exported for tests — the readiness seam for owned ephemeral start.
+ * The single liveness primitive: TCP accept on 127.0.0.1:port.
+ *
+ * Resolves `true` as soon as something is listening, `false` when the grace
+ * period expires, and throws only what {@link WaitForListenerOptions.failure}
+ * returns. Used for attach (one probe), local restart, and ephemeral start.
  */
-export async function waitForOwnedPostmaster(opts: WaitForOwnedPostmasterOptions): Promise<void> {
+export async function waitForListener(opts: WaitForListenerOptions): Promise<boolean> {
   const probe = opts.canConnect ?? canConnect;
   const now = opts.now ?? Date.now;
   const pause = opts.sleep ?? sleep;
-  const readyMs = opts.readyMs ?? OWNED_POSTMASTER_READY_MS;
-  const pollMs = opts.pollMs ?? OWNED_POSTMASTER_POLL_MS;
-  const deadline = now() + readyMs;
-  let lastDetail = "TCP not accepting";
+  const pollMs = opts.pollMs ?? HOST_POLL_MS;
+  const deadline = now() + (opts.readyMs ?? 0);
 
-  while (now() < deadline) {
+  for (;;) {
     const fail = opts.failure?.();
     if (fail) throw fail;
-    if (await probe(opts.port)) return;
-    lastDetail = `127.0.0.1:${opts.port} not accepting connections`;
+    if (await probe(opts.port)) return true;
+    if (now() >= deadline) return false;
     await pause(pollMs);
   }
+}
+
+/**
+ * Attach to the registered autopg host once TCP accepts on its port.
+ *
+ * Registration is not liveness: a stopped pm2 host still reports a port, and
+ * attaching to it is the `ECONNREFUSED 127.0.0.1:25432` bug. `readyMs` > 0 is
+ * the grace period after asking autopg to start.
+ */
+async function attachLiveHost(bin: string, readyMs = 0): Promise<AutopgDiscovery | null> {
+  let discovered: AutopgDiscovery;
+  try {
+    discovered = discoverHost(bin);
+  } catch {
+    return null;
+  }
+  return (await waitForListener({ port: discovered.port, readyMs })) ? discovered : null;
+}
+
+/**
+ * Bring the user's registered autopg host up and attach to it — same port, same
+ * `~/.autopg/data`, still there after this process exits. cedar-pg never runs a
+ * second local Postgres.
+ */
+async function startLocalHost(bin: string, registeredPort?: number): Promise<AutopgDiscovery> {
+  const failures: string[] = [];
+
+  for (const { argv, readyMs } of LOCAL_START) {
+    const label = `autopg ${argv.join(" ")}`;
+    const failure = runAutopg(bin, [...argv]);
+    if (failure) {
+      failures.push(`${label}: ${failure}`);
+      continue;
+    }
+    const attached = await attachLiveHost(bin, readyMs);
+    if (attached) return attached;
+    failures.push(`${label}: no listener within ${readyMs}ms`);
+  }
 
-  throw new Error(
-    `Timed out waiting for autopg host after ${readyMs}ms.\n${lastDetail}\n${INSTALL_HINT}`,
-  );
+  const where =
+    registeredPort != null
+      ? `autopg host is registered on 127.0.0.1:${registeredPort} but nothing is listening.\n`
+      : "";
+  throw new Error(formatHostStartError(`${where}${failures.join("\n")}`));
 }
 
+/**
+ * Ephemeral host owned by this process/job: detached `autopg postmaster` with
+ * fully ignored stdio (caller exit must not close pipes under the daemon).
+ *
+ * Never runs `autopg install` — that rewrites `~/.autopg/admin.json` and fails
+ * with `supervisor mismatch` next to a local pm2 install. Reuses a listener
+ * already on the recipe port, and prunes stale RAM dirs before a cold start.
+ */
 async function startEphemeralHost(bin: string): Promise<AutopgDiscovery> {
   const recipe = ephemeralHostRecipe();
-  const useRamShm = recipe.postmasterArgs.includes("--ram");
-  const portLive = await canConnect(recipe.port);
+  if (await canConnect(recipe.port)) return discoveryFromRecipe(bin, recipe);
 
-  pruneStaleEphemeralDataDirs({
-    dataDir: recipe.dataDir,
-    portLive,
-  });
+  const useRamShm = recipe.postmasterArgs.includes("--ram");
+  pruneStaleEphemeralDataDirs({ dataDir: recipe.dataDir });
 
-  if (useRamShm && !portLive) {
+  if (useRamShm) {
     const free = freeBytesOn("/dev/shm");
     if (free != null && free < EPHEMERAL_SHM_MIN_FREE_BYTES) {
       process.stderr.write(
@@ -274,94 +329,60 @@ async function startEphemeralHost(bin: string): Promise<AutopgDiscovery> {
 
   mkdirSync(recipe.dataDir, { recursive: true });
 
-  const state: {
-    exit: { code: number | null; signal: NodeJS.Signals | null } | null;
-    spawnError: Error | null;
-  } = { exit: null, spawnError: null };
-
-  const child = spawn(bin, recipe.postmasterArgs, {
-    detached: true,
-    // Fully ignore stdio so unref'd postmaster is not tied to this process's pipes.
-    stdio: "ignore",
-  });
+  const child = spawn(bin, recipe.postmasterArgs, { detached: true, stdio: "ignore" });
+  let died: Error | null = null;
   child.on("error", (err) => {
-    state.spawnError = err;
+    died = new Error(
+      formatHostStartError(`Failed to spawn autopg postmaster.\n${err.message}`, useRamShm),
+    );
   });
   child.on("exit", (code, signal) => {
-    state.exit = { code, signal };
+    died ??= new Error(
+      formatHostStartError(
+        `autopg postmaster exited before ready (code=${code}, signal=${signal}).`,
+        useRamShm,
+      ),
+    );
   });
 
   try {
-    await waitForOwnedPostmaster({
+    const listening = await waitForListener({
       port: recipe.port,
-      failure: () => {
-        if (state.spawnError) {
-          return new Error(
-            formatHostStartError(
-              `Failed to spawn autopg postmaster.\n${state.spawnError.message}`,
-              useRamShm,
-            ),
-          );
-        }
-        if (state.exit) {
-          return new Error(
-            formatHostStartError(
-              `autopg postmaster exited before ready (code=${state.exit.code}, signal=${state.exit.signal}).`,
-              useRamShm,
-            ),
-          );
-        }
-        return null;
-      },
+      readyMs: HOST_READY_MS,
+      failure: () => died,
     });
+    if (!listening) {
+      throw new Error(
+        formatHostStartError(
+          `autopg postmaster did not accept 127.0.0.1:${recipe.port} within ${HOST_READY_MS}ms.`,
+          useRamShm,
+        ),
+      );
+    }
   } catch (err) {
     killOwnedChild(child);
     throw err;
   }
 
-  releaseOwnedChild(child);
+  // Success: the process/job owns lifetime — drop our handle without killing.
+  child.unref();
   return discoveryFromRecipe(bin, recipe);
 }
 
-async function startOrReuseEphemeral(bin: string): Promise<AutopgDiscovery> {
-  const recipe = ephemeralHostRecipe();
-  if (await canConnect(recipe.port)) return discoveryFromRecipe(bin, recipe);
-  return startEphemeralHost(bin);
-}
-
-async function attachLiveDiscovery(bin: string): Promise<AutopgDiscovery | null> {
-  let discovered: AutopgDiscovery;
-  try {
-    discovered = discoverHost(bin);
-  } catch {
-    return null;
-  }
-  return (await canConnect(discovered.port)) ? discovered : null;
-}
-
+/**
+ * Attach to a listening autopg host, else start one per
+ * {@link resolveHostStartPolicy}. Internal: callers use `acquire` / `adminUrl`.
+ */
 export async function ensureHostRunning(bin = requireAutopgBin()): Promise<AutopgDiscovery> {
-  const attached = await attachLiveDiscovery(bin);
-  if (attached) return attached;
-
-  if (resolveEphemeralHostPolicy() === "ephemeral") {
-    return startOrReuseEphemeral(bin);
-  }
-
-  let installError: unknown;
+  let registered: AutopgDiscovery | null = null;
   try {
-    runInstall(bin, ["install"], false);
-  } catch (err) {
-    installError = err;
-  }
-  if (installError == null) {
-    const afterInstall = await attachLiveDiscovery(bin);
-    if (afterInstall) return afterInstall;
+    registered = discoverHost(bin);
+  } catch {
+    // no registration — local recovery may `install`
   }
+  if (registered && (await waitForListener({ port: registered.port }))) return registered;
 
-  if (!allowOwnedPostmasterFallback()) {
-    throw installError instanceof Error
-      ? installError
-      : new Error(`autopg host is not running.\n${INSTALL_HINT}`);
-  }
-  return startOrReuseEphemeral(bin);
+  return resolveHostStartPolicy() === "ephemeral"
+    ? startEphemeralHost(bin)
+    : startLocalHost(bin, registered?.port);
 }
diff --git a/tests/autopg.test.ts b/tests/autopg.test.ts
index 884a799..3336031 100644
--- a/tests/autopg.test.ts
+++ b/tests/autopg.test.ts
@@ -13,24 +13,23 @@ test("parseHostStatus requires numeric port", () => {
   expect(() => parseHostStatus("not-json")).toThrow(/invalid JSON/);
 });
 
-test("parseHostStatus treats autopg v3 status JSON as live only when online", () => {
+test("parseHostStatus reports the registered port without judging liveness", () => {
+  // Real `autopg status --json` for an installed-but-stopped pm2 host: the port
+  // is registration, not a listener. TCP is the only liveness gate (host.ts).
   const stopped = `{
     "installed": true,
     "name": "autopg-server",
     "status": "stopped",
     "pid": null,
     "port": 25432,
-    "runtime": null
+    "runtime": null,
+    "supervisor": "pm2"
   }`;
-  expect(() => parseHostStatus(stopped)).toThrow(/not running/);
-  expect(() => parseHostStatus('{"port":55432,"status":"errored"}')).toThrow(/not running/);
-  expect(() =>
-    parseHostStatus('{"port":55432,"status":"online","runtime":{"live":false}}'),
-  ).toThrow(/not running/);
-  expect(
-    parseHostStatus('{"port":55432,"status":"online","pid":1,"runtime":{"live":true}}'),
-  ).toEqual({ port: 55432 });
-  expect(() => parseHostStatus('{"port":5432,"running":false}')).toThrow(/not running/);
+  expect(parseHostStatus(stopped)).toEqual({ port: 25432 });
+  // Supervisor-specific status strings (systemd-user / launchd tiers) never
+  // hide the port from attach.
+  expect(parseHostStatus('{"port":55432,"status":"running"}')).toEqual({ port: 55432 });
+  expect(parseHostStatus('{"port":5432,"running":false}')).toEqual({ port: 5432 });
 });
 
 test("adminUrlFor uses autopg default credentials and AUTOPG_PG_* overrides", () => {
diff --git a/tests/host.test.ts b/tests/host.test.ts
index 7d8ac39..2385fe3 100644
--- a/tests/host.test.ts
+++ b/tests/host.test.ts
@@ -1,76 +1,68 @@
 import { expect, test } from "vite-plus/test";
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createServer, type AddressInfo } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { adminUrlFor } from "../src/providers/autopg.ts";
 import {
-  allowOwnedPostmasterFallback,
   discoveryFromRecipe,
+  ensureHostRunning,
   ephemeralHostRecipe,
   EPHEMERAL_SHM_HINT,
   formatHostStartError,
   looksLikeShmSpaceError,
   pruneStaleEphemeralDataDirs,
-  resolveEphemeralHostPolicy,
-  waitForOwnedPostmaster,
+  resolveHostStartPolicy,
+  waitForListener,
 } from "../src/providers/host.ts";
 
-test("resolveEphemeralHostPolicy from CEDAR_PG_EPHEMERAL_HOST and CI", () => {
-  expect(resolveEphemeralHostPolicy({ CEDAR_PG_EPHEMERAL_HOST: "1" })).toBe("ephemeral");
-  expect(resolveEphemeralHostPolicy({ CEDAR_PG_EPHEMERAL_HOST: "0", CI: "true" })).toBe("local");
-  expect(resolveEphemeralHostPolicy({ CI: "true" })).toBe("ephemeral");
-  expect(resolveEphemeralHostPolicy({ CI: "1" })).toBe("local");
-  expect(resolveEphemeralHostPolicy({})).toBe("local");
-});
-
-test("allowOwnedPostmasterFallback is off only when CEDAR_PG_EPHEMERAL_HOST=0", () => {
-  expect(allowOwnedPostmasterFallback({})).toBe(true);
-  expect(allowOwnedPostmasterFallback({ CI: "true" })).toBe(true);
-  expect(allowOwnedPostmasterFallback({ CEDAR_PG_EPHEMERAL_HOST: "1" })).toBe(true);
-  expect(allowOwnedPostmasterFallback({ CEDAR_PG_EPHEMERAL_HOST: "0" })).toBe(false);
+test("resolveHostStartPolicy from CEDAR_PG_EPHEMERAL_HOST and CI", () => {
+  expect(resolveHostStartPolicy({ CEDAR_PG_EPHEMERAL_HOST: "1" })).toBe("ephemeral");
+  expect(resolveHostStartPolicy({ CEDAR_PG_EPHEMERAL_HOST: "0", CI: "true" })).toBe("local");
+  expect(resolveHostStartPolicy({ CI: "true" })).toBe("ephemeral");
+  expect(resolveHostStartPolicy({ CI: "1" })).toBe("local");
+  expect(resolveHostStartPolicy({})).toBe("local");
 });
 
 test("ephemeralHostRecipe uses RAM on Linux when /dev/shm is available", () => {
-  const recipe = ephemeralHostRecipe({
-    platform: "linux",
-    shmAvailable: true,
-    uid: 1000,
+  expect(ephemeralHostRecipe({ platform: "linux", shmAvailable: true, uid: 1000 })).toEqual({
+    dataDir: "/dev/shm/cedar-pg-1000",
+    port: 55432,
+    postmasterArgs: [
+      "postmaster",
+      "--ram",
+      "--port",
+      "55432",
+      "--socket-dir",
+      "/dev/shm/cedar-pg-1000",
+      "--data",
+      "/dev/shm/cedar-pg-1000",
+    ],
   });
-  expect(recipe.dataDir).toBe("/dev/shm/cedar-pg-1000");
-  expect(recipe.port).toBe(55432);
-  expect(recipe).not.toHaveProperty("installArgs");
-  expect(recipe.postmasterArgs).toEqual([
-    "postmaster",
-    "--ram",
-    "--port",
-    "55432",
-    "--socket-dir",
-    "/dev/shm/cedar-pg-1000",
-    "--data",
-    "/dev/shm/cedar-pg-1000",
-  ]);
 });
 
 test("ephemeralHostRecipe falls back to disk tmpdir without --ram", () => {
-  const recipe = ephemeralHostRecipe({
-    platform: "darwin",
-    shmAvailable: false,
-    tmpDir: "/tmp/cedar-test",
-    uid: 1,
+  expect(
+    ephemeralHostRecipe({
+      platform: "darwin",
+      shmAvailable: false,
+      tmpDir: "/tmp/cedar-test",
+      uid: 1,
+      port: 55433,
+    }),
+  ).toEqual({
+    dataDir: "/tmp/cedar-test/cedar-pg-host",
     port: 55433,
+    postmasterArgs: [
+      "postmaster",
+      "--port",
+      "55433",
+      "--socket-dir",
+      "/tmp/cedar-test/cedar-pg-host",
+      "--data",
+      "/tmp/cedar-test/cedar-pg-host",
+    ],
   });
-  expect(recipe.dataDir).toBe("/tmp/cedar-test/cedar-pg-host");
-  expect(recipe.port).toBe(55433);
-  expect(recipe).not.toHaveProperty("installArgs");
-  expect(recipe.postmasterArgs).toEqual([
-    "postmaster",
-    "--port",
-    "55433",
-    "--socket-dir",
-    "/tmp/cedar-test/cedar-pg-host",
-    "--data",
-    "/tmp/cedar-test/cedar-pg-host",
-  ]);
 });
 
 test("discoveryFromRecipe uses recipe port + adminUrlFor (no status)", () => {
@@ -87,25 +79,39 @@ test("discoveryFromRecipe uses recipe port + adminUrlFor (no status)", () => {
   });
 });
 
-test("waitForOwnedPostmaster resolves when TCP accepts", async () => {
+test("waitForListener probes once by default and polls until TCP accepts", async () => {
   let attempts = 0;
-  await waitForOwnedPostmaster({
-    port: 1,
-    readyMs: 1000,
-    pollMs: 1,
-    now: () => 0,
-    sleep: async () => {},
-    canConnect: async () => {
-      attempts += 1;
-      return attempts >= 2;
-    },
-  });
-  expect(attempts).toBe(2);
+  expect(
+    await waitForListener({
+      port: 1,
+      now: () => 0,
+      canConnect: async () => {
+        attempts += 1;
+        return false;
+      },
+    }),
+  ).toBe(false);
+  expect(attempts).toBe(1);
+
+  expect(
+    await waitForListener({
+      port: 1,
+      readyMs: 1000,
+      pollMs: 1,
+      now: () => 0,
+      sleep: async () => {},
+      canConnect: async () => {
+        attempts += 1;
+        return attempts >= 3;
+      },
+    }),
+  ).toBe(true);
+  expect(attempts).toBe(3);
 });
 
-test("waitForOwnedPostmaster throws when failure() reports spawn/exit", async () => {
+test("waitForListener throws what failure() reports (spawn error / early exit)", async () => {
   await expect(
-    waitForOwnedPostmaster({
+    waitForListener({
       port: 1,
       readyMs: 1000,
       pollMs: 1,
@@ -117,10 +123,10 @@ test("waitForOwnedPostmaster throws when failure() reports spawn/exit", async ()
   ).rejects.toThrow(/spawn blew up/);
 });
 
-test("waitForOwnedPostmaster times out when TCP never accepts", async () => {
+test("waitForListener returns false when the grace period expires", async () => {
   let t = 0;
-  await expect(
-    waitForOwnedPostmaster({
+  expect(
+    await waitForListener({
       port: 9,
       readyMs: 5,
       pollMs: 1,
@@ -130,7 +136,7 @@ test("waitForOwnedPostmaster times out when TCP never accepts", async () => {
       },
       canConnect: async () => false,
     }),
-  ).rejects.toThrow(/Timed out waiting for autopg host after 5ms/);
+  ).toBe(false);
 });
 
 test("looksLikeShmSpaceError matches quota / ENOSPC / 53100", () => {
@@ -141,15 +147,15 @@ test("looksLikeShmSpaceError matches quota / ENOSPC / 53100", () => {
   expect(looksLikeShmSpaceError("permission denied")).toBe(false);
 });
 
-test("formatHostStartError appends shm hint for RAM quota failures", () => {
+test("formatHostStartError appends shm hint only for RAM quota failures", () => {
   const msg = formatHostStartError("Disk quota exceeded during initdb", true);
   expect(msg).toContain("Disk quota exceeded");
   expect(msg).toContain(EPHEMERAL_SHM_HINT);
   expect(formatHostStartError("permission denied", true)).not.toContain("Enlarge tmpfs");
-  expect(formatHostStartError("Disk quota exceeded", false)).not.toContain("Enlarge tmpfs");
+  expect(formatHostStartError("Disk quota exceeded")).not.toContain("Enlarge tmpfs");
 });
 
-test("pruneStaleEphemeralDataDirs removes leftovers when port is dead", () => {
+test("pruneStaleEphemeralDataDirs removes cedar-pg / pgserve / PostgreSQL leftovers only", () => {
   const root = mkdtempSync(join(tmpdir(), "cedar-shm-"));
   const dataDir = join(root, "cedar-pg-host");
   const keep = join(root, "other-file");
@@ -159,11 +165,7 @@ test("pruneStaleEphemeralDataDirs removes leftovers when port is dead", () => {
   mkdirSync(join(root, "PostgreSQL.12345"));
   writeFileSync(keep, "x");
 
-  const removed = pruneStaleEphemeralDataDirs({
-    dataDir,
-    shmRoot: root,
-    portLive: false,
-  });
+  const removed = pruneStaleEphemeralDataDirs({ dataDir, shmRoot: root });
 
   expect(removed.sort()).toEqual(
     [
@@ -177,17 +179,88 @@ test("pruneStaleEphemeralDataDirs removes leftovers when port is dead", () => {
   rmSync(root, { recursive: true, force: true });
 });
 
-test("pruneStaleEphemeralDataDirs is a no-op when port is live", () => {
-  const root = mkdtempSync(join(tmpdir(), "cedar-shm-"));
-  const dataDir = join(root, "cedar-pg-host");
-  mkdirSync(dataDir);
-  expect(
-    pruneStaleEphemeralDataDirs({
-      dataDir,
-      shmRoot: root,
-      portLive: true,
-    }),
-  ).toEqual([]);
-  expect(existsSync(dataDir)).toBe(true);
-  rmSync(root, { recursive: true, force: true });
+/**
+ * Fake `autopg` that always reports an installed-but-stopped registration on
+ * `port` and fails every start verb, logging each invocation.
+ */
+function writeFakeAutopg(port: number): { bin: string; log: string; dir: string } {
+  const dir = mkdtempSync(join(tmpdir(), "cedar-fake-autopg-"));
+  const log = join(dir, "calls.log");
+  const bin = join(dir, "autopg");
+  writeFileSync(
+    bin,
+    [
+      "#!/bin/sh",
+      `echo "$@" >> ${JSON.stringify(log)}`,
+      'if [ "$1" = "status" ]; then',
+      `  echo '{"installed":true,"name":"autopg-server","status":"stopped","pid":null,"port":${port},"supervisor":"pm2"}'`,
+      "  exit 0",
+      "fi",
+      'echo "fake autopg: $1 refused" >&2',
+      "exit 1",
+      "",
+    ].join("\n"),
+    { mode: 0o755 },
+  );
+  return { bin, log, dir };
+}
+
+/** `CEDAR_PG_EPHEMERAL_HOST=0` pins local policy regardless of ambient `CI`. */
+async function withLocalPolicy(fn: () => Promise<void>): Promise<void> {
+  const previous = process.env.CEDAR_PG_EPHEMERAL_HOST;
+  process.env.CEDAR_PG_EPHEMERAL_HOST = "0";
+  try {
+    await fn();
+  } finally {
+    if (previous === undefined) delete process.env.CEDAR_PG_EPHEMERAL_HOST;
+    else process.env.CEDAR_PG_EPHEMERAL_HOST = previous;
+  }
+}
+
+function calls(log: string): string[] {
+  return readFileSync(log, "utf8").trim().split("\n");
+}
+
+test("ensureHostRunning attaches on TCP even when status JSON says stopped", async () => {
+  const server = createServer();
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address() as AddressInfo;
+  const fake = writeFakeAutopg(port);
+
+  try {
+    await withLocalPolicy(async () => {
+      expect(await ensureHostRunning(fake.bin)).toEqual({
+        port,
+        adminUrl: adminUrlFor(port),
+        bin: fake.bin,
+      });
+    });
+    expect(calls(fake.log)).toEqual(["status --json"]);
+  } finally {
+    server.close();
+    rmSync(fake.dir, { recursive: true, force: true });
+  }
+});
+
+test("ensureHostRunning refuses a dead registered port: restart, then install, then fail", async () => {
+  const probe = createServer();
+  await new Promise<void>((resolve) => probe.listen(0, "127.0.0.1", resolve));
+  const { port: deadPort } = probe.address() as AddressInfo;
+  await new Promise<void>((resolve) => probe.close(() => resolve()));
+  const fake = writeFakeAutopg(deadPort);
+
+  try {
+    await withLocalPolicy(async () => {
+      await expect(ensureHostRunning(fake.bin)).rejects.toThrow(
+        new RegExp(
+          `registered on 127\\.0\\.0\\.1:${deadPort} but nothing is listening[\\s\\S]*` +
+            "autopg restart: exit 1[\\s\\S]*autopg install: exit 1",
+        ),
+      );
+    });
+    // No `postmaster`: a second local Postgres is never a local recovery step.
+    expect(calls(fake.log)).toEqual(["status --json", "restart", "install"]);
+  } finally {
+    rmSync(fake.dir, { recursive: true, force: true });
+  }
 });