pgserve 1.1.10 → 2.0.0

package/.github/workflows/release.yml

@@ -1,138 +1,253 @@
-name: Unified Release
+name: Release
+
+# Single-branch release pipeline modeled on khal-os/desktop.
+#
+# Two trigger paths into the same workflow:
+#
+#   1. push to main with a hand-bumped package.json (no [skip ci] marker)
+#      -> auto-detect path: prepare reads package.json, checks if v${version}
+#         tag exists, builds + publishes + creates GitHub Release if not.
+#
+#   2. workflow_dispatch with bump=patch|minor|major
+#      -> bump job runs `npm version`, commits with [skip ci], tags, pushes.
+#         prepare/build/release continue inline in the same workflow run.
+#
+# Bot-loop guard: bump commits carry [skip ci]. Push of those commits is
+# filtered out by the prepare gate, so the bot's own push does not retrigger.
+#
+# Auth: npm OIDC Trusted Publishing (configured via build-all-platforms.yml).
 
 on:
-  pull_request:
-    types: [closed]
+  push:
     branches: [main]
   workflow_dispatch:
     inputs:
-      action:
-        description: 'Release action'
+      bump:
+        description: "Version bump type"
         required: true
         type: choice
         options:
-          - bump-rc
-          - promote
+          - patch
+          - minor
+          - major
 
 concurrency:
-  group: unified-release
+  group: release-${{ github.ref }}
   cancel-in-progress: false
 
 permissions:
   contents: write
-  pull-requests: read
-  id-token: write
+  id-token: write   # required so the reusable `version.yml` workflow can mint
+                    # the OIDC token for npm Trusted Publishing — without this,
+                    # GH rejects the workflow at parse time (startup_failure)
+                    # because the called job's `id-token: write` permission
+                    # exceeds what the caller has granted.
 
 jobs:
-  # Gate: Skip bot commits, detect action from PR labels
-  gate:
-    name: Release Gate
-    runs-on: ubuntu-latest
-    if: |
-      github.event_name == 'workflow_dispatch' ||
-      (github.event.pull_request.merged == true &&
-       (contains(github.event.pull_request.labels.*.name, 'rc') ||
-        contains(github.event.pull_request.labels.*.name, 'stable')))
-    outputs:
-      should_run: ${{ steps.check.outputs.should_run }}
-      action: ${{ steps.detect.outputs.action }}
-
-    steps:
-      - name: Check for bot commits
-        id: check
-        run: |
-          # Skip if this is a bot commit (prevents infinite loops)
-          if [[ "${{ github.actor }}" == "github-actions[bot]" ]]; then
-            echo "Skipping: bot commit detected"
-            echo "should_run=false" >> $GITHUB_OUTPUT
-          else
-            echo "should_run=true" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Detect action
-        id: detect
-        if: steps.check.outputs.should_run == 'true'
-        run: |
-          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
-            echo "action=${{ inputs.action }}" >> $GITHUB_OUTPUT
-            echo "Action from dispatch: ${{ inputs.action }}"
-          elif [[ "${{ contains(github.event.pull_request.labels.*.name, 'stable') }}" == "true" ]]; then
-            echo "action=promote" >> $GITHUB_OUTPUT
-            echo "Action from label: promote (stable)"
-          elif [[ "${{ contains(github.event.pull_request.labels.*.name, 'rc') }}" == "true" ]]; then
-            echo "action=bump-rc" >> $GITHUB_OUTPUT
-            echo "Action from label: bump-rc"
-          else
-            echo "No release label found"
-            echo "action=" >> $GITHUB_OUTPUT
-          fi
-
-  # Version: Bump version and create tag
-  version:
-    name: Bump Version
-    needs: gate
-    if: needs.gate.outputs.should_run == 'true' && needs.gate.outputs.action != ''
+  # ---------------------------------------------------------------------------
+  # Bump (workflow_dispatch only): npm version, commit [skip ci], tag, push.
+  # ---------------------------------------------------------------------------
+  bump:
+    name: Bump version
+    if: github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     outputs:
       version: ${{ steps.bump.outputs.version }}
       tag: ${{ steps.bump.outputs.tag }}
-      npm_tag: ${{ steps.bump.outputs.npm_tag }}
-      is_promote: ${{ steps.bump.outputs.is_promote }}
-
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
         with:
+          ref: main
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
+      - uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: "22"
 
-      - name: Configure Git
+      - name: Configure git
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
-      - name: Run release script
+      - name: Bump version
         id: bump
-        run: node scripts/release.cjs --action ${{ needs.gate.outputs.action }}
+        run: |
+          npm version "${{ inputs.bump }}" --no-git-tag-version
+          VERSION=$(node -p "require('./package.json').version")
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "tag=v${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Bumped to ${VERSION}"
+
+      - name: Commit, tag, push
+        run: |
+          VERSION="${{ steps.bump.outputs.version }}"
+          TAG="${{ steps.bump.outputs.tag }}"
+          git add package.json
+          git commit -m "[skip ci] release ${TAG}"
+          git tag "${TAG}"
+          git push origin HEAD --follow-tags
+
+  # ---------------------------------------------------------------------------
+  # Prepare: resolve version, skip if tag already exists, build changelog.
+  #
+  # Gate handles both event types:
+  #   - push:    bump is skipped; the !cancelled() && !failure() guard lets
+  #              this job run regardless. The [skip ci] check filters the
+  #              bot's own bump-commit push so it does not retrigger.
+  #   - dispatch: bump succeeded; the workflow_dispatch branch of the OR
+  #              short-circuits the [skip ci] check (the dispatch event
+  #              itself does not carry the bump's commit message).
+  # ---------------------------------------------------------------------------
+  prepare:
+    name: Prepare release
+    needs: bump
+    if: |
+      !cancelled() && !failure() &&
+      (github.event_name == 'workflow_dispatch' ||
+       (github.event_name == 'push' &&
+        !startsWith(github.event.head_commit.message, '[skip ci]')))
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      version: ${{ steps.ver.outputs.version }}
+      tag: ${{ steps.ver.outputs.tag }}
+      skip: ${{ steps.ver.outputs.skip }}
+      changelog: ${{ steps.changelog.outputs.notes }}
+      # Surface the resolved checkout-ref so downstream jobs (build, release)
+      # can use it. They cannot reference `needs.bump.outputs.*` directly
+      # because they only have `needs: prepare` (or [prepare, build]) — not
+      # `bump` — in their needs context.
+      ref: ${{ needs.bump.outputs.tag || github.sha }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # On dispatch, check out the freshly-pushed tag; on push, the
+          # triggering SHA already has the bumped package.json.
+          # (Prepare cannot reference its own `outputs.ref` here — that's
+          # only available to downstream jobs.)
+          ref: ${{ needs.bump.outputs.tag || github.sha }}
+          fetch-depth: 0
+
+      - name: Resolve version
+        id: ver
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          TAG="v${VERSION}"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+
+          if gh release view "${TAG}" > /dev/null 2>&1; then
+            echo "Release ${TAG} already exists — skipping"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Find previous release tag
+        id: prev
+        if: steps.ver.outputs.skip == 'false'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="${{ steps.ver.outputs.tag }}"
+          PREV=$(gh release list --limit 50 --json tagName -q '.[].tagName' | grep -v "^${TAG}$" | head -1)
+          if [ -n "$PREV" ] && git merge-base --is-ancestor "$PREV" HEAD 2>/dev/null; then
+            echo "tag=${PREV}" >> "$GITHUB_OUTPUT"
+            echo "Previous tag: ${PREV}"
+          else
+            echo "tag=" >> "$GITHUB_OUTPUT"
+            echo "No previous tag reachable from HEAD"
+          fi
+
+      - name: Generate changelog
+        id: changelog
+        if: steps.ver.outputs.skip == 'false' && steps.prev.outputs.tag != ''
+        run: |
+          PREV="${{ steps.prev.outputs.tag }}"
+          NOTES=$(git log --oneline "${PREV}..HEAD" --pretty="- %s" | head -50)
+          {
+            echo "notes<<EOF"
+            echo "$NOTES"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
 
-      - name: Push changes
+      # Echo the resolved outputs so downstream skip/no-skip decisions are
+      # debuggable from the run log without re-running with step debug.
+      - name: Debug resolved outputs
         run: |
-          git push origin HEAD:${{ github.ref_name }}
-          git push origin --tags
+          echo "version=${{ steps.ver.outputs.version }}"
+          echo "tag=${{ steps.ver.outputs.tag }}"
+          echo "skip=${{ steps.ver.outputs.skip }}"
+          echo "prev=${{ steps.prev.outputs.tag }}"
 
-  # Build & Publish: Always build and publish (npm_tag comes from version job)
+  # ---------------------------------------------------------------------------
+  # Build & Publish: matrix build of platform binaries + npm publish via OIDC.
+  #
+  # The reusable workflow filename is `version.yml` because npm Trusted
+  # Publisher is configured against that exact path. Renaming requires
+  # updating the npmjs.com Trusted Publisher entry first.
+  #
+  # The `if:` uses `always() && needs.prepare.result == 'success' &&
+  # needs.prepare.outputs.skip != 'true'`. This is the bulletproof pattern
+  # for reusable-workflow callers when any upstream job in the `needs:`
+  # chain was SKIPPED. With the simpler `needs.prepare.outputs.skip != 'true'`
+  # alone, GH Actions silently evaluated the gate as false even though the
+  # debug step in `prepare` proved the output was actually `'false'` — a
+  # known GH Actions quirk: when a job's transitive `needs:` chain includes
+  # a skipped job (here, `bump` is skipped on push events), the reusable-
+  # workflow caller's expression evaluator treats `needs.<job>.outputs.<x>`
+  # as null/missing regardless of the actual value.
+  #
+  # `always()` opts out of the implicit success() filter; the explicit
+  # `result == 'success'` reinstates it correctly; the outputs check then
+  # works as intended.
+  # ---------------------------------------------------------------------------
   build:
     name: Build & Publish
-    needs: version
-    uses: ./.github/workflows/build-all-platforms.yml
+    needs: prepare
+    if: |
+      always() &&
+      needs.prepare.result == 'success' &&
+      needs.prepare.outputs.skip != 'true'
+    uses: ./.github/workflows/version.yml
     with:
-      version: ${{ needs.version.outputs.version }}
-      npm_tag: ${{ needs.version.outputs.npm_tag }}
-      ref: ${{ needs.version.outputs.tag }}
+      version: ${{ needs.prepare.outputs.version }}
+      npm_tag: latest
+      # Use prepare.outputs.ref (which resolves to the bump-job tag on
+      # dispatch, or `github.sha` on push). Build cannot reference
+      # `needs.bump.*` directly — only `prepare` is in its `needs:` chain.
+      # On the push path nobody creates the tag before this runs; the
+      # SHA-based checkout works because the merge commit already has the
+      # bumped package.json. The release job creates the tag at the end
+      # via `gh release create`.
+      ref: ${{ needs.prepare.outputs.ref }}
     secrets: inherit
 
-  # GitHub Release: Create release with changelog
-  github-release:
+  # ---------------------------------------------------------------------------
+  # Release: download artifacts, create GitHub Release with cliff-free notes.
+  # ---------------------------------------------------------------------------
+  release:
     name: Create GitHub Release
-    needs: [version, build]
-    if: always() && needs.version.result == 'success' && needs.build.result == 'success'
+    needs: [prepare, build]
+    if: |
+      always() &&
+      needs.prepare.result == 'success' &&
+      needs.build.result == 'success' &&
+      needs.prepare.outputs.skip != 'true'
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
-
+    timeout-minutes: 10
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
         with:
-          ref: ${{ needs.version.outputs.tag }}
+          # Same as the build job: prefer the bump job's tag (dispatch
+          # path) but fall back to the SHA (push path, no tag exists yet).
+          ref: ${{ needs.prepare.outputs.ref }}
 
-      - name: Download artifacts
-        if: needs.build.result == 'success'
+      - name: Download binaries
         uses: actions/download-artifact@v4
         with:
           path: dist/
@@ -140,28 +255,35 @@ jobs:
           merge-multiple: true
 
       - name: List artifacts
+        run: ls -la dist/
+
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_NOTES: ${{ needs.prepare.outputs.changelog }}
         run: |
-          if [ -d "dist" ]; then
-            echo "Release artifacts:"
-            ls -la dist/
-          else
-            echo "No artifacts (promote release)"
+          TAG="${{ needs.prepare.outputs.tag }}"
+          VERSION="${{ needs.prepare.outputs.version }}"
+
+          if [ -z "$RELEASE_NOTES" ]; then
+            RELEASE_NOTES="Release ${TAG}"
           fi
 
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
-        with:
-          tag_name: ${{ needs.version.outputs.tag }}
-          name: ${{ needs.version.outputs.tag }}
-          generate_release_notes: true
-          body: |
-            ## Install
-
-            ```bash
-            npm install pgserve@${{ needs.version.outputs.npm_tag }}
-            bunx pgserve@${{ needs.version.outputs.npm_tag }}
-            ```
-          prerelease: ${{ contains(needs.version.outputs.version, '-rc.') }}
-          files: |
+          {
+            echo "$RELEASE_NOTES"
+            echo ""
+            echo "## Install"
+            echo ""
+            echo '```bash'
+            echo "npm install pgserve@${VERSION}"
+            echo "bunx pgserve@${VERSION}"
+            echo '```'
+          } > /tmp/release-notes.md
+
+          # The tag already exists (created by bump job on dispatch, or by the
+          # human commit on push). gh release create resolves --target via the
+          # tag automatically when omitted.
+          gh release create "${TAG}" \
+            --title "${TAG}" \
+            --notes-file /tmp/release-notes.md \
             dist/*
-          fail_on_unmatched_files: false

package/.github/workflows/{build-all-platforms.yml → version.yml}

@@ -65,7 +65,7 @@ jobs:
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
-          bun-version: latest
+          bun-version: 1.3.11
 
       - name: Install dependencies
         run: bun install
@@ -112,7 +112,12 @@ jobs:
     needs: build
     runs-on: ubuntu-latest
     if: inputs.version != ''
-    environment: npm-publish
+    # Note: `environment: npm-publish` was removed because the npmjs.com
+    # Trusted Publisher entry for `pgserve` does not declare an environment
+    # name. With the env gate present here, the OIDC token's environment
+    # claim did not match the registry's expectation and `npm publish`
+    # returned 404. Re-add this line if/when the Trusted Publisher entry
+    # has its Environment Name field set to `npm-publish`.
     permissions:
       id-token: write
       contents: read
@@ -123,20 +128,34 @@ jobs:
         with:
           ref: ${{ inputs.ref || github.ref }}
 
+      # Node 24 ships npm 11.5+ which has built-in OIDC trusted-publisher
+      # support. Avoids the `npm install -g npm@latest` self-upgrade bug
+      # (Arborist clobbering its own promise-retry dep mid-install) that
+      # broke rlmx's OIDC publish on Node 22.
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '24'
           registry-url: 'https://registry.npmjs.org'
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
-          bun-version: latest
+          bun-version: 1.3.11
 
       - name: Install dependencies
         run: bun install
 
+      - name: Verify npm version supports OIDC trusted publishing
+        run: |
+          NPM_VERSION=$(npm --version)
+          echo "npm version: ${NPM_VERSION}"
+          MAJOR=$(echo "${NPM_VERSION}" | cut -d. -f1)
+          if [ "${MAJOR}" -lt 11 ]; then
+            echo "::error::npm ${NPM_VERSION} too old — OIDC requires >= 11.5.1. Bump node-version above."
+            exit 1
+          fi
+
       - name: Download all artifacts
         uses: actions/download-artifact@v4
         with:
@@ -179,13 +198,18 @@ jobs:
             echo "published=false" >> $GITHUB_OUTPUT
           fi
 
-      - name: Publish to npm
+      - name: Publish to npm via OIDC
         if: steps.check.outputs.published == 'false'
+        env:
+          HUSKY: "0"
+          # npm auto-enables provenance in any CI env with `id-token: write`,
+          # regardless of the --provenance CLI flag. On some runners the
+          # server-side sigstore check fails with 422; disable explicitly.
+          # OIDC token exchange still happens.
+          NPM_CONFIG_PROVENANCE: "false"
         run: |
-          echo "Publishing version ${{ inputs.version }} with tag ${{ inputs.npm_tag }}"
+          echo "Publishing version ${{ inputs.version }} with tag ${{ inputs.npm_tag }} via OIDC"
           npm publish --access public --tag ${{ inputs.npm_tag }}
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
       - name: Verify publish
         if: steps.check.outputs.published == 'false'

package/AGENTS.md

@@ -190,16 +190,18 @@ Before editing ANY implementation file, Base Genie must check:
 
 **Protocol:** `@.genie/spells/orchestration-boundary-protocol.md`
 
-**Release Workflow Protocol:**
-- ❌ Never manually trigger `workflow_dispatch` for releases
-- ❌ Never manually bump version in package.json
-- ✅ Always use PR with `rc` or `stable` label - release.yml auto-triggers on merge
-- ✅ Version bumping is automated by scripts/release.cjs
-
-**Documented Violations:**
+**Release Workflow Protocol (push-to-main, single tier):**
+- ✅ Manual path: bump locally with `npm version patch|minor|major`, commit, PR to main. Merge → `release.yml` fires automatically.
+- ✅ Bot path: `gh workflow run release.yml -f bump=patch` (or `minor`/`major`). Bot bumps, tags, builds binaries, publishes to npm via OIDC.
+- ✅ Skip: any commit message starting with `[skip ci]` is filtered by the prepare gate.
+- ❌ No `rc`/`stable` PR labels (legacy — removed). No `scripts/release.cjs` (deleted).
+- ❌ Don't edit `package.json` `version` directly on `main` outside the `npm version` flow above.
+- ⚙️ npm publish runs from `.github/workflows/version.yml` (the file npmjs.com Trusted Publisher is bound to).
+
+**Documented Violations (history):**
 - Bug #168, task b51db539, 2025-10-21 (duplicate implementation)
 - 2025-10-26 (claimed release implementation steps without investigating automation)
-- 2025-12-08 (manually set version to 1.1.0 + triggered workflow_dispatch → version jumped to 1.1.1-rc.1)
+- 2025-12-08 (manually set version to 1.1.0 + triggered workflow_dispatch → version jumped to 1.1.1-rc.1; this class of error is no longer possible — the bump path goes through `gh workflow run`, not direct package.json edits)
 
 ### 4. Task State Optimization - Live State, Not Documentation 🔴 CRITICAL
 **Rule:** Task state is ephemeral runtime data, not permanent documentation

package/CHANGELOG.md

@@ -0,0 +1,150 @@
+# Changelog
+
+All notable changes to `pgserve` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 2.0.0 — Unreleased
+
+> The release date will replace "Unreleased" when the v2.0.0 release workflow
+> fires. The CHANGELOG is committed ahead of the release trigger so consumers
+> can review the migration plan before the artifact lands on npm.
+
+### Pin guidance (read this first)
+
+Existing v1 consumers should pin `pgserve@^1.x` in their `package.json` until
+they have completed the migration described below. v2 changes the default
+transport (Unix socket, no TCP), the identity model (kernel-rooted
+fingerprint), the database layout (one DB per fingerprint), and the daemon
+process model (singleton). A blind upgrade will break v1 connection strings.
+
+```jsonc
+// package.json — keep v1 until you migrate
+{
+  "dependencies": {
+    "pgserve": "^1.2.0"
+  }
+}
+```
+
+### Breaking changes
+
+- **TCP is no longer the default.** v1 bound `127.0.0.1:8432` for every
+  consumer. v2 binds a Unix control socket at
+  `${XDG_RUNTIME_DIR:-/tmp}/pgserve/control.sock` (mode `0600`, dir mode
+  `0700`) plus a `.s.PGSQL.5432` symlink so libpq clients connect with no
+  host/port/user/password. To keep a TCP listener, opt in explicitly with
+  `--listen <port>` (see "Compat TCP via --listen" in the README).
+- **Fingerprint enforcement is default-ON.** Each connecting peer is
+  identified via `SO_PEERCRED` + the resolved `package.json` `name`,
+  collapsed to a 12-hex fingerprint. The daemon refuses to route a peer
+  into a database that does not match its fingerprint with SQLSTATE
+  `28P01 invalid_authorization — database fingerprint mismatch`. The
+  emergency kill switch is `PGSERVE_DISABLE_FINGERPRINT_ENFORCEMENT=1`
+  (deprecated; the daemon emits a stderr warning at boot when the env var
+  is observed).
+- **Database-per-fingerprint isolation.** v1 served arbitrary database
+  names freely. v2 auto-creates `app_<sanitized-name>_<12hex>` for each
+  unique fingerprint on first connect; cross-fingerprint reads are denied.
+  `psql -l` will show one row per consumer rather than the shared pool
+  v1 produced. Monorepo rule: the root `package.json` `name` wins for all
+  packages under it.
+- **Singleton daemon via control socket.** v1 spun up a server per
+  invocation, leaving consumers to coordinate ports themselves. v2
+  enforces one daemon per host: a second `pgserve daemon` exits with
+  `already running, pid N`. Run it under PM2 or systemd (snippets in the
+  README) — there is no PM-managed multi-process mode anymore.
+- **GC sweep emits `db_reaped_ttl` and `db_reaped_liveness` audit events.**
+  Default lifecycle is now ephemeral: a database whose `liveness_pid` is
+  dead AND whose `last_connection_at` is older than 24h is dropped on the
+  next sweep (boot, hourly, sampled on-connect). To opt out, add
+  `pgserve.persist: true` to the consumer's `package.json` — flagged
+  databases are never reaped.
+
+### Migration guide
+
+1. **Connection strings** — drop credentials and the port; switch to the
+   socket form.
+
+   ```diff
+   - postgres://user:pass@localhost:5432/db
+   + postgres:///db?host=${XDG_RUNTIME_DIR:-/tmp}/pgserve
+   ```
+
+   Equivalently, for `psql`:
+
+   ```bash
+   psql -h "${XDG_RUNTIME_DIR:-/tmp}/pgserve" -d myapp
+   ```
+
+2. **Long-lived apps** — anything whose data needs to outlive a 24h idle
+   window (genie state stores, dashboards, anything with state worth
+   keeping) must declare persistence in its `package.json`:
+
+   ```jsonc
+   {
+     "name": "my-long-lived-app",
+     "pgserve": { "persist": true }
+   }
+   ```
+
+   Without this flag, the GC sweep will reap the database after the TTL
+   plus liveness check passes.
+
+3. **Need TCP?** Opt in with `--listen` and use issued tokens. TCP peers
+   cannot use `SO_PEERCRED`, so they must authenticate at connect time.
+
+   ```bash
+   pgserve daemon --listen :5432
+
+   # Issue a bearer token for a known fingerprint (printed once):
+   pgserve daemon issue-token --fingerprint <12hex>
+
+   # TCP clients pass the token via libpq application_name as
+   #   ?fingerprint=<hex>&token=<bearer>
+   # Revoke when done:
+   pgserve daemon revoke-token <token-id>
+   ```
+
+   Without `--listen`, no TCP port is bound — verify with
+   `ss -tlnp | grep -v pgserve` returning no pgserve rows.
+
+4. **Kill switch (emergency only).** If the fingerprint enforcement
+   denies a connection you cannot otherwise unblock, set
+   `PGSERVE_DISABLE_FINGERPRINT_ENFORCEMENT=1` for the daemon. The
+   bypassed connection emits an `enforcement_kill_switch_used` audit
+   event; the daemon logs a deprecation warning at boot whenever the
+   variable is observed. The kill switch will be removed in a future
+   major; treat it as a debugging tool, not a production setting.
+
+### New features (group references map to wish execution groups)
+
+- **Group 4 — Database-per-fingerprint + enforcement + kill switch.**
+  Auto-create `app_<name>_<12hex>` on first connect, deny
+  cross-fingerprint reads with SQLSTATE `28P01`, audit event
+  `connection_denied_fingerprint_mismatch`. Sanitizer collapses
+  non-`[a-z0-9]` runs to `_`, lowercases, truncates to 30 chars to keep
+  the resulting DB name ≤ 63 chars.
+- **Group 5 — Lifecycle + persist flag + GC sweep.** Three-layer
+  lifecycle: liveness (peer pid alive), 24h TTL since last connection,
+  and `pgserve.persist: true` override. Sweep runs at daemon boot,
+  hourly, and sampled on-connect at 1/N where N = max(1, dbCount/10).
+  Reaped databases emit `db_reaped_ttl` or `db_reaped_liveness` audit
+  events; the on-connect sweep does not block accept latency past 50 ms
+  P99.
+- **Group 6 — `--listen` opt-in TCP + token auth.** Daemon CLI accepts
+  `--listen [host:]port` (repeatable). Tokens issued via
+  `pgserve daemon issue-token --fingerprint <hex>`, hashed at rest into
+  `pgserve_meta.allowed_tokens`, verified with constant-time compare.
+  New audit events: `tcp_token_issued`, `tcp_token_used`,
+  `tcp_token_denied`. Without `--listen`, no TCP port is bound.
+
+### Compatibility
+
+- Node.js >= 18 (unchanged).
+- Linux x64, macOS ARM64/x64, Windows x64. Windows uses named pipes for
+  the control socket; PM2/systemd snippets are Linux-first.
+- `--ram` (Linux/WSL2 `/dev/shm`), `--pgvector`, `--sync-to`, and the
+  rest of the v1 runtime flags continue to work unchanged.
+
+---