From cdaa2db1f70949d745e281322184487ec9914534 Mon Sep 17 00:00:00 2001
From: johnnyfish <jonathanfishner11@gmail.com>
Date: Tue, 28 Jul 2026 00:12:25 -0700
Subject: [PATCH] feat(run): govern registered Postgres databases via the
 gateway pg proxy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

onecli run now scans the process env and project .env files for
postgres:// URLs, matches them by host against the project's registered
database connections (GET /v1/pg/connections — host/port only, never
credentials), mints a proxy session per matched connection
(POST /v1/pg/sessions), and swaps the matched env vars for gateway proxy
URLs (aoc_pg_<token> username, dummy password) that shadow .env for
default-precedence loaders. Real credentials never enter the agent env;
every statement lands in the OneCLI activity log.

Unmatched database hosts warn ('connect it in the dashboard') and are
left untouched. A detached sidecar (hidden __pg-sidecar mode, forked
before exec so TTY semantics are preserved) heartbeats the sessions and
reaps them when the agent exits; if the sidecar dies the gateway expires
sessions by TTL. Opt out with --no-pg-proxy.
---
 cmd/onecli/hook_gateway_detect.sh    |   2 +-
 cmd/onecli/main.go                   |  16 +-
 cmd/onecli/pg.go                     | 173 +++++++++
 cmd/onecli/pg_test.go                |  62 ++++
 cmd/onecli/run.go                    | 145 +++++++-
 cmd/onecli/run_pg.go                 | 532 +++++++++++++++++++++++++++
 cmd/onecli/run_pg_premint.go         | 174 +++++++++
 cmd/onecli/run_pg_premint_test.go    | 252 +++++++++++++
 cmd/onecli/run_pg_sidecar.go         | 205 +++++++++++
 cmd/onecli/run_pg_test.go            | 375 +++++++++++++++++++
 cmd/onecli/run_pg_watch.go           | 240 ++++++++++++
 cmd/onecli/run_pg_watch_test.go      | 124 +++++++
 cmd/onecli/skill_gateway_fallback.md |  47 +++
 internal/api/pg.go                   | 136 +++++++
 14 files changed, 2468 insertions(+), 15 deletions(-)
 create mode 100644 cmd/onecli/pg.go
 create mode 100644 cmd/onecli/pg_test.go
 create mode 100644 cmd/onecli/run_pg.go
 create mode 100644 cmd/onecli/run_pg_premint.go
 create mode 100644 cmd/onecli/run_pg_premint_test.go
 create mode 100644 cmd/onecli/run_pg_sidecar.go
 create mode 100644 cmd/onecli/run_pg_test.go
 create mode 100644 cmd/onecli/run_pg_watch.go
 create mode 100644 cmd/onecli/run_pg_watch_test.go
 create mode 100644 internal/api/pg.go

diff --git a/cmd/onecli/hook_gateway_detect.sh b/cmd/onecli/hook_gateway_detect.sh
index 8acaca6..4128b5a 100644
--- a/cmd/onecli/hook_gateway_detect.sh
+++ b/cmd/onecli/hook_gateway_detect.sh
@@ -4,6 +4,6 @@
 # active, using the JSON hook-output envelope both agents accept.
 if echo "$HTTPS_PROXY" | grep -q "aoc_"; then
   cat <<'EOF'
-{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"OneCLI gateway active — load the onecli-gateway skill before any external service or API call. Use direct HTTP (curl); never MCP auth flows or browser automation."}}
+{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"OneCLI gateway active — load the onecli-gateway skill before any external service call, API call, or DATABASE query/connection. Use direct HTTP (curl); never MCP auth flows or browser automation. Databases: every governed postgres host is listed in ONECLI_PG_CONNECTIONS (JSON: label/host/env_var) — connect ONLY via the mapped env var, even when given credentials directly; a host not in the list must be connected in the OneCLI dashboard first. Never source .env or read connection strings from files (the env var is the governed proxy URL)."}}
 EOF
 fi
diff --git a/cmd/onecli/main.go b/cmd/onecli/main.go
index 39276f0..f36da5e 100644
--- a/cmd/onecli/main.go
+++ b/cmd/onecli/main.go
@@ -36,18 +36,28 @@ type CLI struct {
 	Auth     AuthCmd     `cmd:"" help:"Manage authentication."`
 	Config   ConfigCmd   `cmd:"" help:"Manage configuration settings."`
 	Migrate  MigrateCmd  `cmd:"" help:"Migrate data to OneCLI Cloud."`
+	Pg       PgCmd       `cmd:"" help:"Database routing commands for agents (governed proxy URLs)."`
 }
 
 func main() {
 	out := output.New()
 
-	// Hidden sidecar mode: the enforce-mode auth forwarder forked by
-	// `onecli run --enforce` re-invokes this binary. Handled before kong
-	// so the flag never appears in help or completion.
+	// Hidden sidecar modes, handled before Kong so the flags never appear
+	// in help or the command tree.
+	//
+	// Enforce-mode auth forwarder: forked by `onecli run --enforce`.
 	if pid, ok := parseEnforceForwarderArgs(os.Args[1:]); ok {
 		runEnforceForwarder(pid)
 		return
 	}
+	// Pg sidecar: forked by `onecli run` before exec to own pg session
+	// heartbeats/cleanup.
+	if len(os.Args) > 1 && os.Args[1] == pgSidecarFlag {
+		if args, ok := parsePgSidecarArgs(os.Args[2:]); ok {
+			runPgSidecar(args)
+		}
+		return
+	}
 
 	// When invoked with no args, --help, or -h, output structured JSON
 	// so agents always get machine-readable output.
diff --git a/cmd/onecli/pg.go b/cmd/onecli/pg.go
new file mode 100644
index 0000000..e47d27a
--- /dev/null
+++ b/cmd/onecli/pg.go
@@ -0,0 +1,173 @@
+package main
+
+// `onecli pg` — agent-first database routing commands, designed to be run
+// BY the agent inside an `onecli run` session (the gateway origin and
+// agent token are recovered from the session's own HTTPS_PROXY value).
+//
+// `onecli pg url <label|host[:port]|connection-id>` prints the governed
+// proxy URL for a registered database as JSON. It is the escape hatch for
+// databases registered in the dashboard AFTER the agent started (or past
+// the placeholder cap): the agent gets a fresh governed route without
+// restarting the run. The skill documents it as the fallback when a host
+// is missing from ONECLI_PG_CONNECTIONS.
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"net/url"
+	"os"
+	"strings"
+
+	"github.com/onecli/onecli-cli/internal/api"
+	"github.com/onecli/onecli-cli/pkg/output"
+)
+
+type PgCmd struct {
+	URL PgURLCmd `cmd:"" help:"Print the governed proxy URL for a registered database (run inside an 'onecli run' session)."`
+}
+
+type PgURLCmd struct {
+	Target string `arg:"" name:"database" help:"Connection label, host[:port], or connection id."`
+}
+
+// PgURLResponse is the JSON contract of `onecli pg url`. Deliberately
+// protocol-generic (a future `onecli mysql url` mirrors it): the agent
+// consumes url/expires_in_seconds and treats everything else as metadata.
+type PgURLResponse struct {
+	URL              string `json:"url"`
+	Label            string `json:"label"`
+	Host             string `json:"host"`
+	ExpiresInSeconds uint64 `json:"expires_in_seconds"`
+}
+
+func (c *PgURLCmd) Run(out *output.Writer) error {
+	client, gatewayHost, caPath, err := pgClientFromSession()
+	if err != nil {
+		return out.Error("no_gateway_session", err.Error())
+	}
+
+	resp, err := client.ListPgConnections(context.Background())
+	if err != nil {
+		return out.Error("gateway_unreachable", fmt.Sprintf("could not list registered databases: %v", err))
+	}
+
+	conn, err := resolvePgTarget(c.Target, resp.Connections)
+	if err != nil {
+		return out.ErrorWithAction("not_registered", err.Error(),
+			"Ask the user to connect this database in the OneCLI dashboard, then retry.")
+	}
+
+	session, err := client.MintPgSession(context.Background(), conn.ID)
+	if err != nil {
+		return out.Error("session_mint_failed", fmt.Sprintf("could not open a proxy session: %v", err))
+	}
+
+	label := conn.ID
+	if conn.Label != nil && *conn.Label != "" {
+		label = *conn.Label
+	}
+	return out.Write(PgURLResponse{
+		URL:              placeholderPgURL(session, gatewayHost, caPath),
+		Label:            label,
+		Host:             normalizeHostPort(conn.Host, fmt.Sprintf("%d", conn.Port)),
+		ExpiresInSeconds: session.TTLSeconds,
+	})
+}
+
+// pgClientFromSession recovers the gateway client from the calling
+// session's environment: HTTPS_PROXY carries the origin + agent token
+// (exactly what `onecli run` exported for the agent), and the CA bundle
+// path is where `onecli run` writes it. Errors are agent-actionable.
+func pgClientFromSession() (*api.PgGatewayClient, string, string, error) {
+	proxyURL := ""
+	for _, key := range []string{"HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"} {
+		if v := os.Getenv(key); v != "" && strings.Contains(v, "aoc_") {
+			proxyURL = v
+			break
+		}
+	}
+	if proxyURL == "" {
+		return nil, "", "", fmt.Errorf("no OneCLI gateway session found in the environment; this command runs inside an 'onecli run' session")
+	}
+	gwURL, agentToken, ok := gatewayOriginAndToken(proxyURL)
+	if !ok {
+		return nil, "", "", fmt.Errorf("the proxy URL in the environment carries no usable agent token")
+	}
+	// The pg listener lives on the same host as the gateway HTTP origin.
+	gatewayHost := gwURL
+	if u, err := url.Parse(gwURL); err == nil && u.Hostname() != "" {
+		gatewayHost = u.Hostname()
+	}
+	caPath := ""
+	if home, err := os.UserHomeDir(); err == nil {
+		p := home + "/.onecli/ca-bundle.pem"
+		if _, err := os.Stat(p); err == nil {
+			caPath = p
+		}
+	}
+	return &api.PgGatewayClient{BaseURL: gwURL, AgentToken: agentToken}, gatewayHost, caPath, nil
+}
+
+// resolvePgTarget matches the user-supplied target against the granted
+// connections: exact connection id, exact label (case-insensitive), or
+// host[:port] (normalized; a bare host matches any port when unambiguous).
+func resolvePgTarget(target string, conns []api.PgConnection) (*api.PgConnection, error) {
+	t := strings.TrimSpace(target)
+	if t == "" {
+		return nil, fmt.Errorf("empty database target")
+	}
+
+	var matches []*api.PgConnection
+	add := func(c *api.PgConnection) {
+		for _, m := range matches {
+			if m.ID == c.ID {
+				return
+			}
+		}
+		matches = append(matches, c)
+	}
+
+	tLower := strings.ToLower(t)
+	for i := range conns {
+		c := &conns[i]
+		if c.ID == t {
+			return c, nil // an id is exact by construction
+		}
+		if c.Label != nil && strings.ToLower(*c.Label) == tLower {
+			add(c)
+		}
+		hostPort := normalizeHostPort(c.Host, fmt.Sprintf("%d", c.Port))
+		bareHost := strings.ToLower(strings.TrimSuffix(c.Host, "."))
+		if hostPort == normalizeTargetHostPort(t) || bareHost == tLower {
+			add(c)
+		}
+	}
+
+	switch len(matches) {
+	case 1:
+		return matches[0], nil
+	case 0:
+		return nil, fmt.Errorf("no registered database matches %q", t)
+	default:
+		var names []string
+		for _, m := range matches {
+			label := m.ID
+			if m.Label != nil && *m.Label != "" {
+				label = *m.Label
+			}
+			names = append(names, fmt.Sprintf("%s (%s)", label, normalizeHostPort(m.Host, fmt.Sprintf("%d", m.Port))))
+		}
+		return nil, fmt.Errorf("%q is ambiguous — matches: %s; use the connection id or host:port", t, strings.Join(names, ", "))
+	}
+}
+
+// normalizeTargetHostPort normalizes a host[:port] target for comparison,
+// defaulting the port to 5432 like the scan side does.
+func normalizeTargetHostPort(t string) string {
+	host, port, err := net.SplitHostPort(t)
+	if err != nil {
+		host, port = t, "5432"
+	}
+	return normalizeHostPort(host, port)
+}
diff --git a/cmd/onecli/pg_test.go b/cmd/onecli/pg_test.go
new file mode 100644
index 0000000..b986a64
--- /dev/null
+++ b/cmd/onecli/pg_test.go
@@ -0,0 +1,62 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/onecli/onecli-cli/internal/api"
+)
+
+func TestResolvePgTarget(t *testing.T) {
+	conns := []api.PgConnection{
+		{ID: "conn-1", Label: strPtr("main-db"), Host: "db.example.com", Port: 5432},
+		{ID: "conn-2", Label: strPtr("analytics"), Host: "warehouse.example.com", Port: 6543},
+		{ID: "conn-3", Label: strPtr("replica"), Host: "db.example.com", Port: 5433},
+	}
+
+	cases := []struct {
+		name    string
+		target  string
+		wantID  string
+		wantErr bool
+	}{
+		{"by id", "conn-2", "conn-2", false},
+		{"by label", "main-db", "conn-1", false},
+		{"label case-insensitive", "ANALYTICS", "conn-2", false},
+		{"by host:port", "db.example.com:5433", "conn-3", false},
+		{"host:port default 5432", "warehouse.example.com:6543", "conn-2", false},
+		{"host normalized case+dot", "DB.Example.COM.:5432", "conn-1", false},
+		{"bare host ambiguous (two ports)", "db.example.com", "", true},
+		{"bare host unique", "warehouse.example.com", "conn-2", false},
+		{"unknown", "nope.example.com", "", true},
+		{"empty", "  ", "", true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := resolvePgTarget(tc.target, conns)
+			if tc.wantErr {
+				if err == nil {
+					t.Errorf("want error, got %+v", got)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatal(err)
+			}
+			if got.ID != tc.wantID {
+				t.Errorf("got %s, want %s", got.ID, tc.wantID)
+			}
+		})
+	}
+}
+
+func TestNormalizeTargetHostPort(t *testing.T) {
+	if got := normalizeTargetHostPort("db.example.com"); got != "db.example.com:5432" {
+		t.Errorf("default port: %q", got)
+	}
+	if got := normalizeTargetHostPort("DB.example.com:6543"); got != "db.example.com:6543" {
+		t.Errorf("explicit port: %q", got)
+	}
+	if got := normalizeTargetHostPort("[::1]:5432"); got != "[::1]:5432" {
+		t.Errorf("ipv6: %q", got)
+	}
+}
diff --git a/cmd/onecli/run.go b/cmd/onecli/run.go
index 0d0f8f2..33c12cb 100644
--- a/cmd/onecli/run.go
+++ b/cmd/onecli/run.go
@@ -42,13 +42,15 @@ var caShimSource string
 
 // RunCmd is `onecli run -- <command> [args...]`.
 type RunCmd struct {
-	Project string   `optional:"" short:"p" help:"Project slug."`
-	Agent   string   `optional:"" name:"agent" help:"OneCLI agent identifier (uses default agent if omitted)."`
-	Gateway string   `optional:"" name:"gateway" help:"Gateway host:port override (default: derived from API host)."`
-	NoCA    bool     `optional:"" name:"no-ca" help:"Skip writing the CA cert and CA trust env injection."`
-	Enforce bool     `optional:"" name:"enforce" help:"OS-enforced governance: route the agent's sandboxed egress through the gateway so it cannot be bypassed (Claude Code only)."`
-	DryRun  bool     `optional:"" name:"dry-run" help:"Print resolved env and command without executing."`
-	Args    []string `arg:"" optional:"" name:"command" help:"Command and arguments to execute (after --)."`
+	Project   string   `optional:"" short:"p" help:"Project slug."`
+	Agent     string   `optional:"" name:"agent" help:"OneCLI agent identifier (uses default agent if omitted)."`
+	Gateway   string   `optional:"" name:"gateway" help:"Gateway host:port override (default: derived from API host)."`
+	NoCA      bool     `optional:"" name:"no-ca" help:"Skip writing the CA cert and CA trust env injection."`
+	Enforce   bool     `optional:"" name:"enforce" help:"OS-enforced governance: route the agent's sandboxed egress through the gateway so it cannot be bypassed (Claude Code only)."`
+	NoPgProxy bool     `optional:"" name:"no-pg-proxy" help:"Skip Postgres URL interception (registered databases will not be governed)."`
+	PgProxy   string   `optional:"" name:"pg-proxy" help:"Postgres governance mode: 'required' aborts the run if a registered database cannot be routed through the gateway (default: best-effort)."`
+	DryRun    bool     `optional:"" name:"dry-run" help:"Print resolved env and command without executing."`
+	Args      []string `arg:"" optional:"" name:"command" help:"Command and arguments to execute (after --)."`
 }
 
 func (c *RunCmd) Run(out *output.Writer) error {
@@ -109,7 +111,7 @@ func (c *RunCmd) Run(out *output.Writer) error {
 	}
 
 	// Dry-run: print resolved config without side effects (no CA write,
-	// no skill install, no exec).
+	// no skill install, no pg session mint, no exec).
 	if c.DryRun {
 		injected := make([]string, 0, len(cfg.Env)+len(caTrustKeys))
 		for k := range cfg.Env {
@@ -118,11 +120,31 @@ func (c *RunCmd) Run(out *output.Writer) error {
 		if !c.NoCA && cfg.CACertificate != "" {
 			injected = append(injected, caTrustKeys...)
 		}
-		return out.WriteDryRun("Would exec command with OneCLI gateway", map[string]any{
+		payload := map[string]any{
 			"binary":       binary,
 			"args":         c.Args,
 			"env_injected": injected,
-		})
+		}
+		// Read-only pg preview: which vars WOULD be swapped / warned on.
+		// No sessions are minted (that is a side effect).
+		if !c.NoPgProxy {
+			if proxyURL := firstProxyURL(cfg.Env); proxyURL != "" {
+				if gwURL, agentToken, ok := gatewayOriginAndToken(proxyURL); ok {
+					cwd, _ := os.Getwd()
+					swap, unmatched := previewPgSwap(
+						&api.PgGatewayClient{BaseURL: gwURL, AgentToken: agentToken},
+						os.Environ(), cwd,
+					)
+					if len(swap) > 0 {
+						payload["pg_env_swapped"] = swap
+					}
+					if len(unmatched) > 0 {
+						payload["pg_unregistered_hosts"] = unmatched
+					}
+				}
+			}
+		}
+		return out.WriteDryRun("Would exec command with OneCLI gateway", payload)
 	}
 
 	// Write CA cert to disk (unless --no-ca).
@@ -198,10 +220,76 @@ func (c *RunCmd) Run(out *output.Writer) error {
 		out.Stderr(fmt.Sprintf("onecli: warning: %s", w))
 	}
 
+	// Postgres governance (design: pg-interception): scan env + .env for
+	// postgres URLs (and the libpq PG* group), swap registered ones for
+	// gateway proxy sessions, and fork the heartbeat/cleanup sidecar.
+	// Best-effort by default; with --pg-proxy=required a failure to govern a
+	// matched database aborts the run. (Unreachable in --dry-run: that path
+	// returns above, so required is intentionally a no-op there.)
+	if !c.NoPgProxy {
+		pgRequired := strings.EqualFold(c.PgProxy, "required")
+		sandbox := false
+		if spec, ok := agentSkillDir(c.Args[0]); ok {
+			sandbox = spec.dockerSandbox
+		}
+		if sandbox {
+			// Docker-sandbox agents (e.g. Hermes) run tools in a container
+			// that does not inherit this env, so a swapped DATABASE_URL never
+			// reaches the tool making the DB call. Routing that path is a
+			// phase-3 concern; surface the gap (only when the agent actually
+			// carries a database in its env) rather than pretend the host-env
+			// swap covers it.
+			cwd, _ := os.Getwd()
+			if len(scanPgURLs(env, cwd)) > 0 {
+				out.Stderr("onecli: note: database access from sandboxed tools is not yet routed through OneCLI (phase 3); direct connections bypass governance.")
+			}
+		} else {
+			gwURL, agentToken, ok := "", "", false
+			if proxyURL := firstProxyURL(cfg.Env); proxyURL != "" {
+				gwURL, agentToken, ok = gatewayOriginAndToken(proxyURL)
+			}
+			if !ok {
+				if pgRequired {
+					return fmt.Errorf("--pg-proxy=required but the gateway proxy is unavailable (no usable proxy URL); cannot govern database access")
+				}
+			} else {
+				pgClient := &api.PgGatewayClient{BaseURL: gwURL, AgentToken: agentToken}
+				cwd, _ := os.Getwd()
+				outcome, err := setupPgProxy(out, pgClient, gatewayHost, caPath, env, cwd, pgRequired)
+				if err != nil {
+					return err
+				}
+				if outcome != nil {
+					for name, value := range outcome.Swapped {
+						// Append AFTER the inherited env: POSIX getenv returns
+						// the first match, but Go child processes and libc both
+						// honor later duplicates via exec env ordering — so
+						// strip the original first, matching buildChildEnv.
+						env = removeEnvKey(env, name)
+						env = append(env, name+"="+value)
+					}
+					// Placeholder vars for granted databases the scan did
+					// not cover, plus the index the skill points the agent
+					// at (ONECLI_PG_CONNECTIONS).
+					for name, value := range outcome.Placeholders {
+						env = removeEnvKey(env, name)
+						env = append(env, name+"="+value)
+					}
+					if outcome.IndexJSON != "" {
+						env = removeEnvKey(env, pgIndexVar)
+						env = append(env, pgIndexVar+"="+outcome.IndexJSON)
+					}
+					spawnPgSidecar(gwURL, agentToken, outcome.SessionIDs, outcome.TTLSeconds, outcome.WatchHosts, outcome.GatewayPgAddr)
+				}
+			}
+		}
+	}
+
 	// Enforce mode: fork the loopback auth forwarder, write the sandbox
 	// settings, and extend the agent argv. Fails closed — a broken
 	// forwarder would leave the sandbox with no route to the gateway,
-	// which is worse than an explicit error.
+	// which is worse than an explicit error. Runs AFTER the pg swap so
+	// sandboxed DB clients read the already-governed env.
 	args := c.Args
 	if c.Enforce {
 		a, ok := agentSkillDir(c.Args[0])
@@ -979,6 +1067,41 @@ func firstProxyURL(env map[string]string) string {
 	return ""
 }
 
+// gatewayOriginAndToken splits a proxy URL (http://x:aoc_...@host:port)
+// into the gateway HTTP origin and the embedded agent token. The pg
+// session surface lives on the same listener as the HTTP proxy.
+func gatewayOriginAndToken(proxyURL string) (origin, token string, ok bool) {
+	u, err := url.Parse(proxyURL)
+	if err != nil || u.Host == "" || u.User == nil {
+		return "", "", false
+	}
+	password, _ := u.User.Password()
+	// The token rides either the username or the password position
+	// depending on the server's URL shape; take whichever has the prefix.
+	for _, cand := range []string{password, u.User.Username()} {
+		if strings.HasPrefix(cand, "aoc_") {
+			token = cand
+			break
+		}
+	}
+	if token == "" {
+		return "", "", false
+	}
+	return "http://" + u.Host, token, true
+}
+
+// removeEnvKey strips every entry for key from an environ-style slice.
+func removeEnvKey(env []string, key string) []string {
+	out := env[:0]
+	prefix := key + "="
+	for _, kv := range env {
+		if !strings.HasPrefix(kv, prefix) {
+			out = append(out, kv)
+		}
+	}
+	return out
+}
+
 // proxyURLWithHost rewrites the host of a proxy URL, preserving scheme,
 // credentials, and port. Returns "" for empty input.
 func proxyURLWithHost(raw, host string) string {
diff --git a/cmd/onecli/run_pg.go b/cmd/onecli/run_pg.go
new file mode 100644
index 0000000..e8eaa3e
--- /dev/null
+++ b/cmd/onecli/run_pg.go
@@ -0,0 +1,532 @@
+package main
+
+// Postgres URL interception for `onecli run` — phase 1 of
+// docs/design/pg-interception.md (cloud repo): scan the environment and
+// project .env* files for postgres:// URLs, match them BY HOST against the
+// dashboard-registered connections available to this agent, mint a proxy
+// session per matched connection, and swap the matched env values for
+// proxy URLs (aoc_pg_<token> as the username, dummy password). Unmatched
+// database URLs are left untouched and produce a warning naming the fix.
+//
+// The files are never modified: swapped values are injected into the
+// CHILD env under the same variable names, which shadows .env for
+// default-precedence loaders (dotenv, python-dotenv, Prisma).
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"net"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/onecli/onecli-cli/internal/api"
+	"github.com/onecli/onecli-cli/pkg/output"
+)
+
+// pgURLPrefixes match postgres connection strings in env values.
+var pgURLPrefixes = []string{"postgres://", "postgresql://"}
+
+// dotenvFiles are the project files scanned (read-only) for database URLs.
+var dotenvFiles = []string{".env", ".env.local", ".env.development", ".env.development.local"}
+
+// pgScanResult is one discovered postgres URL and where it came from.
+type pgScanResult struct {
+	// VarName is the environment variable carrying the URL. For a libpq
+	// group scan this is "PGHOST" (the group's anchor).
+	VarName string
+	// URL is the parsed original connection URL. For a libpq group scan
+	// it is a synthetic URL assembled from the PG* vars (host/port/db).
+	URL *url.URL
+	// FromEnvFile is true when the value came from a .env file rather
+	// than the process environment (env wins on conflicts).
+	FromEnvFile bool
+	// Libpq is true when this scan represents the libpq PG* variable group
+	// (PGHOST/PGPORT/...) rather than a single URL-valued variable; the
+	// rewrite then emits the whole group, not one URL.
+	Libpq bool
+}
+
+// libpqVars are the connection vars of the libpq environment group. PGHOST
+// anchors the group; the rest refine it.
+var libpqVars = []string{"PGHOST", "PGPORT", "PGUSER", "PGPASSWORD", "PGDATABASE"}
+
+// pgSwapOutcome reports what setupPgProxy did, for messaging + tests.
+type pgSwapOutcome struct {
+	// Swapped maps env var name → proxy URL.
+	Swapped map[string]string
+	// Placeholders maps ONECLI_PG_<LABEL>_URL → proxy URL for granted
+	// connections the env scan did not cover (pre-minted).
+	Placeholders map[string]string
+	// IndexJSON is the ONECLI_PG_CONNECTIONS value: every governed
+	// database with the env var that reaches it. Empty when none.
+	IndexJSON string
+	// SessionIDs to reap on exit (one per matched connection).
+	SessionIDs []string
+	// TTLSeconds is the shortest session TTL minted, so the sidecar can
+	// heartbeat fast enough to keep every session alive (0 = none minted).
+	TTLSeconds uint64
+	// UnmatchedHosts are postgres hosts found in the env/.env that have
+	// no registered connection — surfaced, never silently proxied.
+	UnmatchedHosts []string
+	// WatchHosts is the encoded registered host→connection-id map for the
+	// sidecar's direct-connection watcher.
+	WatchHosts string
+	// GatewayPgAddr is the pg listener host:port the watcher must never
+	// report (it IS the governed route).
+	GatewayPgAddr string
+}
+
+// setupPgProxy discovers postgres URLs (and the libpq PG* group), matches them
+// against registered connections, mints sessions, and returns the env entries
+// to append (shadowing the originals). Granted connections the scan did NOT
+// cover are pre-minted and exported as ONECLI_PG_<LABEL>_URL placeholders,
+// with the full map advertised in ONECLI_PG_CONNECTIONS — so a governed
+// route exists for every granted database, not just those already in the
+// env. Returns (nil, nil) when there is nothing to do.
+//
+// Fail-open by default: a gateway error degrades to a warning and the URLs are
+// left untouched, matching the CA-write degradation in the main run path. When
+// `required` is set (`--pg-proxy=required`), a gateway failure that would leave
+// a MATCHED database ungoverned instead returns an error so the caller aborts;
+// degrade-open silently forfeits the governance the user asked for. Unregistered
+// databases stay warnings in both modes (they are out of scope by design), and
+// pre-mint failures also stay warnings: a database the agent's env never
+// referenced losing its placeholder does not forfeit asked-for governance.
+func setupPgProxy(out *output.Writer, client *api.PgGatewayClient, gatewayHost, caPath string, environ []string, cwd string, required bool) (*pgSwapOutcome, error) {
+	scans := scanPgURLs(environ, cwd)
+
+	resp, err := client.ListPgConnections(context.Background())
+	if err != nil {
+		if len(scans) == 0 {
+			// Nothing scanned and nothing listable: quietly do nothing.
+			return nil, nil
+		}
+		if required {
+			return nil, fmt.Errorf("postgres governance is required (--pg-proxy=required) but the gateway could not list registered databases: %w", err)
+		}
+		out.Stderr(fmt.Sprintf("onecli: warning: could not list registered databases (%v); postgres URLs left untouched", err))
+		return nil, nil
+	}
+	if len(resp.Connections) == 0 {
+		hosts := uniqueHosts(scans)
+		if len(hosts) > 0 {
+			out.Stderr(fmt.Sprintf("onecli: unregistered database detected (%s) — connect it in the dashboard to govern agent access", strings.Join(hosts, ", ")))
+		}
+		return nil, nil
+	}
+
+	// Index registered connections by host:port and pair each scan.
+	outcome := &pgSwapOutcome{Swapped: map[string]string{}}
+	// One session per matched connection id, shared across vars that
+	// point at the same upstream (DATABASE_URL + DIRECT_URL collapse).
+	sessions := map[string]*api.PgSession{}
+	seenUnmatched := map[string]bool{}
+	// Which env var reaches each scan-covered connection, for the index.
+	swappedVarByConnID := map[string]string{}
+
+	for _, m := range matchPgScans(scans, resp.Connections) {
+		if m.Conn == nil {
+			if !seenUnmatched[m.HostPort] {
+				seenUnmatched[m.HostPort] = true
+				outcome.UnmatchedHosts = append(outcome.UnmatchedHosts, m.HostPort)
+			}
+			continue
+		}
+
+		session, ok := sessions[m.Conn.ID]
+		if !ok {
+			minted, err := client.MintPgSession(context.Background(), m.Conn.ID)
+			if err != nil {
+				if required {
+					return nil, fmt.Errorf("postgres governance is required (--pg-proxy=required) but a proxy session for %s could not be opened: %w", m.HostPort, err)
+				}
+				out.Stderr(fmt.Sprintf("onecli: warning: could not open a proxy session for %s (%v); leaving %s untouched", m.HostPort, err, m.Scan.VarName))
+				continue
+			}
+			session = minted
+			sessions[m.Conn.ID] = session
+			outcome.SessionIDs = append(outcome.SessionIDs, session.SessionID)
+			if outcome.TTLSeconds == 0 || session.TTLSeconds < outcome.TTLSeconds {
+				outcome.TTLSeconds = session.TTLSeconds
+			}
+		}
+
+		if m.Scan.Libpq {
+			// The libpq group rewrites to several PG* vars, not one URL.
+			for k, v := range buildLibpqEnv(session.User, gatewayHost, caPath, session.ListenPort) {
+				outcome.Swapped[k] = v
+			}
+			swappedVarByConnID[m.Conn.ID] = "PGHOST"
+		} else {
+			outcome.Swapped[m.Scan.VarName] = buildPgProxyURL(m.Scan.URL, session.User, gatewayHost, caPath, session.ListenPort)
+			if _, seen := swappedVarByConnID[m.Conn.ID]; !seen {
+				swappedVarByConnID[m.Conn.ID] = m.Scan.VarName
+			}
+		}
+	}
+
+	// Pre-mint placeholders for granted connections the scan left
+	// uncovered, so the agent has a governed route to EVERY database it
+	// may reach — not just those already named in the env.
+	pre := preMintPlaceholders(
+		resp.Connections, sessions, swappedVarByConnID,
+		func(connectionID string) (*api.PgSession, error) {
+			return client.MintPgSession(context.Background(), connectionID)
+		},
+		gatewayHost, caPath,
+	)
+	for _, w := range pre.Warnings {
+		out.Stderr("onecli: warning: " + w)
+	}
+	outcome.Placeholders = pre.Placeholders
+	outcome.IndexJSON = encodePgIndex(pre.Index)
+	outcome.WatchHosts = encodePgWatchHosts(resp.Connections)
+	outcome.GatewayPgAddr = normalizeHostPort(gatewayHost, fmt.Sprintf("%d", resp.ListenPort))
+	// Pre-minted sessions ride the same sidecar heartbeat/reaping as the
+	// scan-covered ones.
+	for _, s := range pre.NewSessions {
+		outcome.SessionIDs = append(outcome.SessionIDs, s.SessionID)
+		if outcome.TTLSeconds == 0 || s.TTLSeconds < outcome.TTLSeconds {
+			outcome.TTLSeconds = s.TTLSeconds
+		}
+	}
+
+	reportPgOutcome(out, outcome)
+	if len(outcome.Swapped) == 0 && len(outcome.Placeholders) == 0 && len(outcome.SessionIDs) == 0 {
+		return nil, nil
+	}
+	return outcome, nil
+}
+
+// reportPgOutcome prints the user-facing summary of what governance was
+// established: swapped vars, exported placeholders, unregistered hosts.
+func reportPgOutcome(out *output.Writer, outcome *pgSwapOutcome) {
+	for _, hostPort := range outcome.UnmatchedHosts {
+		out.Stderr(fmt.Sprintf("onecli: unregistered database detected (%s) — connect it in the dashboard to govern agent access", hostPort))
+	}
+	if len(outcome.Swapped) > 0 {
+		names := make([]string, 0, len(outcome.Swapped))
+		for name := range outcome.Swapped {
+			names = append(names, name)
+		}
+		out.Stderr(fmt.Sprintf("onecli: postgres governed via gateway proxy: %s", strings.Join(names, ", ")))
+	}
+	if len(outcome.Placeholders) > 0 {
+		names := make([]string, 0, len(outcome.Placeholders))
+		for name := range outcome.Placeholders {
+			names = append(names, name)
+		}
+		out.Stderr(fmt.Sprintf("onecli: postgres available via gateway proxy: %s", strings.Join(names, ", ")))
+	}
+}
+
+// pgMatch pairs one scanned URL with its registered connection (nil when
+// unmatched).
+type pgMatch struct {
+	Scan     pgScanResult
+	HostPort string
+	Conn     *api.PgConnection
+}
+
+// matchPgScans indexes registered connections by host:port and pairs each
+// scan with its match. Ports default to 5432 on the scan side.
+func matchPgScans(scans []pgScanResult, conns []api.PgConnection) []pgMatch {
+	byHostPort := map[string]api.PgConnection{}
+	for _, conn := range conns {
+		byHostPort[normalizeHostPort(conn.Host, fmt.Sprintf("%d", conn.Port))] = conn
+	}
+	out := make([]pgMatch, 0, len(scans))
+	for _, scan := range scans {
+		port := scan.URL.Port()
+		if port == "" {
+			port = "5432"
+		}
+		key := normalizeHostPort(scan.URL.Hostname(), port)
+		m := pgMatch{Scan: scan, HostPort: key}
+		if conn, ok := byHostPort[key]; ok {
+			connCopy := conn
+			m.Conn = &connCopy
+		}
+		out = append(out, m)
+	}
+	return out
+}
+
+// normalizeHostPort builds a comparable host:port key: the host is lowercased
+// and a single trailing dot (the FQDN root) stripped, so DNS-equivalent forms
+// (DB.Example.COM, db.example.com.) match the registered host. net.JoinHostPort
+// brackets IPv6 consistently on both the scan and registered sides.
+func normalizeHostPort(host, port string) string {
+	h := strings.ToLower(strings.TrimSuffix(host, "."))
+	return net.JoinHostPort(h, port)
+}
+
+// previewPgSwap is the read-only dry-run variant of setupPgProxy: it
+// scans and matches but mints nothing. Returns var → registered
+// connection host that would be proxied (including the placeholder vars
+// that pre-mint would export), and the unmatched hosts.
+func previewPgSwap(client *api.PgGatewayClient, environ []string, cwd string) (map[string]string, []string) {
+	scans := scanPgURLs(environ, cwd)
+	resp, err := client.ListPgConnections(context.Background())
+	if err != nil {
+		return nil, uniqueHosts(scans)
+	}
+	swap := map[string]string{}
+	seenUnmatched := map[string]bool{}
+	var unmatched []string
+	covered := map[string]bool{}
+	for _, m := range matchPgScans(scans, resp.Connections) {
+		if m.Conn != nil {
+			swap[m.Scan.VarName] = m.HostPort
+			covered[m.Conn.ID] = true
+		} else if !seenUnmatched[m.HostPort] {
+			seenUnmatched[m.HostPort] = true
+			unmatched = append(unmatched, m.HostPort)
+		}
+	}
+	// Placeholder vars pre-mint WOULD export (no sessions in dry-run).
+	taken := map[string]bool{}
+	preview := 0
+	for _, conn := range resp.Connections {
+		if covered[conn.ID] || preview >= pgPreMintMax {
+			continue
+		}
+		preview++
+		swap[placeholderVarName(conn, taken)] = normalizeHostPort(conn.Host, fmt.Sprintf("%d", conn.Port))
+	}
+	return swap, unmatched
+}
+
+// scanPgURLs finds postgres URLs in the process env and project .env
+// files. Process env wins for a variable defined in both (matching
+// loader precedence — the swap then shadows the file either way).
+func scanPgURLs(environ []string, cwd string) []pgScanResult {
+	found := map[string]pgScanResult{}
+
+	// .env files first so real env overwrites on collision.
+	for _, name := range dotenvFiles {
+		entries := parseDotenvFile(filepath.Join(cwd, name))
+		for key, val := range entries {
+			if u := parsePgURL(val); u != nil {
+				found[key] = pgScanResult{VarName: key, URL: u, FromEnvFile: true}
+			}
+		}
+	}
+	for _, kv := range environ {
+		i := strings.IndexByte(kv, '=')
+		if i <= 0 {
+			continue
+		}
+		key, val := kv[:i], kv[i+1:]
+		if u := parsePgURL(val); u != nil {
+			found[key] = pgScanResult{VarName: key, URL: u}
+		}
+	}
+
+	out := make([]pgScanResult, 0, len(found)+1)
+	for _, r := range found {
+		out = append(out, r)
+	}
+	// The libpq PG* var group is a second, non-URL way agents name a
+	// database (psql, many drivers). Collect it with the same .env-then-env
+	// precedence and, when PGHOST names a TCP host, add one synthetic scan.
+	if scan := scanLibpqGroup(environ, cwd); scan != nil {
+		out = append(out, *scan)
+	}
+	return out
+}
+
+// scanLibpqGroup collects the libpq PG* vars from the project .env files and
+// the process env (env wins per var) and assembles them into one synthetic
+// scan. Returns nil unless PGHOST names a TCP host.
+func scanLibpqGroup(environ []string, cwd string) *pgScanResult {
+	vars := map[string]string{}
+	for _, name := range dotenvFiles {
+		for key, val := range parseDotenvFile(filepath.Join(cwd, name)) {
+			if isLibpqVar(key) {
+				vars[key] = val
+			}
+		}
+	}
+	for _, kv := range environ {
+		i := strings.IndexByte(kv, '=')
+		if i <= 0 {
+			continue
+		}
+		if key := kv[:i]; isLibpqVar(key) {
+			vars[key] = kv[i+1:]
+		}
+	}
+	return libpqScan(vars)
+}
+
+func isLibpqVar(key string) bool {
+	for _, v := range libpqVars {
+		if key == v {
+			return true
+		}
+	}
+	return false
+}
+
+// libpqScan assembles the libpq PG* vars into one synthetic scan when PGHOST
+// names a TCP host. Path-style PGHOST (a Unix-socket directory, e.g.
+// /var/run/postgresql) is deliberately skipped: out of scope, like the
+// host-less socket URLs parsePgURL rejects. The synthetic URL only carries
+// host/port (and db) so matchPgScans can pair it by host:port; credentials are
+// never used (the gateway injects vault creds). Returns nil without a TCP host.
+func libpqScan(vars map[string]string) *pgScanResult {
+	host := strings.TrimSpace(vars["PGHOST"])
+	if host == "" || strings.HasPrefix(host, "/") {
+		return nil
+	}
+	port := strings.TrimSpace(vars["PGPORT"])
+	if port == "" {
+		port = "5432"
+	}
+	u := &url.URL{Scheme: "postgresql", Host: net.JoinHostPort(host, port)}
+	if db := strings.TrimSpace(vars["PGDATABASE"]); db != "" {
+		u.Path = "/" + db
+	}
+	return &pgScanResult{VarName: "PGHOST", URL: u, Libpq: true}
+}
+
+// parsePgURL returns the parsed URL when the value is a postgres
+// connection URL with a TCP host; nil otherwise. Unix-socket URLs
+// (host-less) are recognized and deliberately skipped.
+func parsePgURL(value string) *url.URL {
+	v := strings.TrimSpace(value)
+	// Strip optional surrounding quotes (common in .env files).
+	v = strings.Trim(v, `"'`)
+	matched := false
+	for _, p := range pgURLPrefixes {
+		if strings.HasPrefix(v, p) {
+			matched = true
+			break
+		}
+	}
+	if !matched {
+		return nil
+	}
+	u, err := url.Parse(v)
+	if err != nil || u.Hostname() == "" {
+		return nil
+	}
+	return u
+}
+
+// parseDotenvFile reads KEY=VALUE pairs from a dotenv file. Deliberately
+// MINIMAL — enough to find database URLs, not a general dotenv parser:
+// no multiline values, no escape sequences, no variable interpolation.
+// Ignores comments, blank lines, and `export ` prefixes. Returns an
+// empty map when the file does not exist or cannot be read.
+func parseDotenvFile(path string) map[string]string {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil
+	}
+	defer func() { _ = f.Close() }()
+
+	out := map[string]string{}
+	scanner := bufio.NewScanner(f)
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		line = strings.TrimPrefix(line, "export ")
+		i := strings.IndexByte(line, '=')
+		if i <= 0 {
+			continue
+		}
+		key := strings.TrimSpace(line[:i])
+		val := strings.TrimSpace(line[i+1:])
+		// Trim trailing inline comment only for unquoted values.
+		if !strings.HasPrefix(val, `"`) && !strings.HasPrefix(val, `'`) {
+			if j := strings.Index(val, " #"); j >= 0 {
+				val = strings.TrimSpace(val[:j])
+			}
+		}
+		out[key] = val
+	}
+	return out
+}
+
+// buildPgProxyURL rewrites an original postgres URL to point at the
+// gateway pg listener, preserving the path (database) and every query
+// parameter EXCEPT the overridden connection fields. TLS mode is
+// host-aware:
+//   - loopback gateway ⇒ sslmode=disable (plaintext localhost leg);
+//   - remote gateway with the installed CA ⇒ sslmode=verify-full +
+//     sslrootcert=<gateway CA>, so the client-leg TLS is authenticated
+//     against the gateway's own CA (defeats a MITM on that leg, not just
+//     passive sniffing);
+//   - remote gateway without a CA path ⇒ sslmode=require (encrypted,
+//     unverified) as a safe fallback.
+func buildPgProxyURL(original *url.URL, user, gatewayHost, caPath string, listenPort uint16) string {
+	q := original.Query()
+	q.Del("sslmode")
+	q.Del("sslrootcert")
+	q.Del("sslcert")
+	q.Del("sslkey")
+	if isLoopbackHost(gatewayHost) {
+		q.Set("sslmode", "disable")
+	} else if caPath != "" {
+		q.Set("sslmode", "verify-full")
+		q.Set("sslrootcert", caPath)
+	} else {
+		q.Set("sslmode", "require")
+	}
+
+	proxy := url.URL{
+		Scheme:   "postgresql",
+		User:     url.UserPassword(user, "x"),
+		Host:     net.JoinHostPort(gatewayHost, fmt.Sprintf("%d", listenPort)),
+		Path:     original.Path,
+		RawQuery: q.Encode(),
+	}
+	return proxy.String()
+}
+
+// buildLibpqEnv rewrites the libpq PG* connection vars to point at the gateway
+// pg listener, mirroring buildPgProxyURL's host-aware TLS selection. PGDATABASE
+// is intentionally NOT emitted — the client's chosen database passes through to
+// the real upstream. PGPASSWORD is the dummy "x"; the real credential is never
+// carried (the gateway injects vault creds upstream).
+func buildLibpqEnv(user, gatewayHost, caPath string, listenPort uint16) map[string]string {
+	env := map[string]string{
+		"PGHOST":     gatewayHost,
+		"PGPORT":     fmt.Sprintf("%d", listenPort),
+		"PGUSER":     user,
+		"PGPASSWORD": "x",
+	}
+	if isLoopbackHost(gatewayHost) {
+		env["PGSSLMODE"] = "disable"
+	} else if caPath != "" {
+		env["PGSSLMODE"] = "verify-full"
+		env["PGSSLROOTCERT"] = caPath
+	} else {
+		env["PGSSLMODE"] = "require"
+	}
+	return env
+}
+
+func uniqueHosts(scans []pgScanResult) []string {
+	seen := map[string]bool{}
+	var out []string
+	for _, s := range scans {
+		port := s.URL.Port()
+		if port == "" {
+			port = "5432"
+		}
+		hp := normalizeHostPort(s.URL.Hostname(), port)
+		if !seen[hp] {
+			seen[hp] = true
+			out = append(out, hp)
+		}
+	}
+	return out
+}
diff --git a/cmd/onecli/run_pg_premint.go b/cmd/onecli/run_pg_premint.go
new file mode 100644
index 0000000..281b024
--- /dev/null
+++ b/cmd/onecli/run_pg_premint.go
@@ -0,0 +1,174 @@
+package main
+
+// Pre-mint + advertise: alongside swapping URLs the agent's env already
+// carries, `onecli run` mints a proxy session for EVERY registered
+// connection the agent is granted and exports one placeholder variable
+// per connection (ONECLI_PG_<LABEL>_URL) plus a machine-readable index
+// (ONECLI_PG_CONNECTIONS). The gateway skill instructs the agent: any
+// postgres host in the index is reached ONLY via its mapped variable —
+// even when the user pastes credentials — because a governed route always
+// exists for every granted database. This closes the "registered but not
+// in the env at spawn" gap where the agent had no proxy URL to use and
+// dialed the real host directly.
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"regexp"
+	"strings"
+
+	"github.com/onecli/onecli-cli/internal/api"
+)
+
+// pgPreMintMax bounds how many un-scanned granted connections are
+// pre-minted per run. Guards against a project with a huge connection
+// inventory turning every spawn into a mint storm; past the cap the
+// remaining databases are still governed when their URL appears in the
+// env (the scan path), they just get no placeholder.
+const pgPreMintMax = 16
+
+// pgIndexVar is the env var carrying the JSON index of governed databases.
+const pgIndexVar = "ONECLI_PG_CONNECTIONS"
+
+// pgIndexEntry is one row of the ONECLI_PG_CONNECTIONS JSON index. EnvVar
+// names the variable holding the proxy URL — a NAME, not a $reference:
+// env values do not interpolate, so the agent reads the named var itself.
+type pgIndexEntry struct {
+	Label  string `json:"label"`
+	Host   string `json:"host"`
+	EnvVar string `json:"env_var"`
+}
+
+var pgLabelSanitizer = regexp.MustCompile(`[^A-Z0-9]+`)
+
+// placeholderVarName derives ONECLI_PG_<LABEL>_URL from a connection's
+// label (falling back to the connection id), sanitized to env-var-safe
+// characters. `taken` de-duplicates collisions ("main db" vs "main-db")
+// with a numeric suffix; the caller passes the same map across calls.
+func placeholderVarName(conn api.PgConnection, taken map[string]bool) string {
+	base := ""
+	if conn.Label != nil {
+		base = strings.ToUpper(*conn.Label)
+	}
+	base = strings.Trim(pgLabelSanitizer.ReplaceAllString(base, "_"), "_")
+	if base == "" {
+		// No usable label: an id prefix is stable and unique enough.
+		id := strings.ToUpper(conn.ID)
+		id = strings.Trim(pgLabelSanitizer.ReplaceAllString(id, "_"), "_")
+		if len(id) > 8 {
+			id = id[:8]
+		}
+		base = id
+	}
+	name := "ONECLI_PG_" + base + "_URL"
+	for i := 2; taken[name]; i++ {
+		name = fmt.Sprintf("ONECLI_PG_%s_%d_URL", base, i)
+	}
+	taken[name] = true
+	return name
+}
+
+// placeholderPgURL builds the proxy URL for a pre-minted connection with
+// no client-supplied URL to preserve. The database path is the pinned
+// database from the mint response, else "postgres" — NEVER empty, because
+// libpq defaults a missing database to the username (aoc_pg_...), which
+// does not exist upstream. TLS parameters come from buildPgProxyURL so
+// the two paths cannot drift.
+func placeholderPgURL(session *api.PgSession, gatewayHost, caPath string) string {
+	db := "postgres"
+	if session.Database != nil && strings.TrimSpace(*session.Database) != "" {
+		db = strings.TrimSpace(*session.Database)
+	}
+	synthetic := &url.URL{Scheme: "postgresql", Path: "/" + db}
+	return buildPgProxyURL(synthetic, session.User, gatewayHost, caPath, session.ListenPort)
+}
+
+// preMintResult is what preMintPlaceholders produced, separated from the
+// caller's own bookkeeping: NewSessions holds only the sessions THIS call
+// minted (the caller registers them with the sidecar); Placeholders and
+// Index are the env surface to export.
+type preMintResult struct {
+	// Placeholders maps ONECLI_PG_<LABEL>_URL → proxy URL.
+	Placeholders map[string]string
+	// Index lists every governed database (scan-covered and pre-minted)
+	// with the env var that reaches it.
+	Index []pgIndexEntry
+	// NewSessions are the sessions minted by this call, in mint order.
+	NewSessions []*api.PgSession
+	// Warnings are user-facing degradation notices (mint failures, cap).
+	Warnings []string
+}
+
+// preMintPlaceholders mints sessions for granted connections that the env
+// scan did NOT already cover and returns the placeholder env entries plus
+// the full index (which also lists scan-covered connections, mapped to
+// their swapped var). minted is read for reuse and updated with every new
+// session; newly minted sessions are also reported in the result so the
+// caller can register exactly those with the sidecar.
+//
+// Best-effort by design, even under --pg-proxy=required: a pre-mint
+// failure means a database the agent's env never referenced lacks a
+// placeholder — governance of the databases the agent was actually
+// launched to use is unaffected, so aborting the run would be wrong.
+func preMintPlaceholders(
+	conns []api.PgConnection,
+	minted map[string]*api.PgSession,
+	swappedVarByConnID map[string]string,
+	mint func(connectionID string) (*api.PgSession, error),
+	gatewayHost, caPath string,
+) preMintResult {
+	res := preMintResult{Placeholders: map[string]string{}}
+	taken := map[string]bool{}
+
+	for _, conn := range conns {
+		hostPort := normalizeHostPort(conn.Host, fmt.Sprintf("%d", conn.Port))
+		label := conn.ID
+		if conn.Label != nil && *conn.Label != "" {
+			label = *conn.Label
+		}
+
+		// Scan-covered connection: the index points at the swapped var.
+		if varName, ok := swappedVarByConnID[conn.ID]; ok {
+			res.Index = append(res.Index, pgIndexEntry{Label: label, Host: hostPort, EnvVar: varName})
+			continue
+		}
+
+		if len(res.NewSessions) >= pgPreMintMax {
+			res.Warnings = append(res.Warnings, fmt.Sprintf(
+				"placeholder cap reached (%d); %s has no ONECLI_PG_* variable — its URL in the env is still governed", pgPreMintMax, hostPort))
+			continue
+		}
+
+		session, ok := minted[conn.ID]
+		if !ok {
+			s, err := mint(conn.ID)
+			if err != nil {
+				res.Warnings = append(res.Warnings, fmt.Sprintf(
+					"could not open a proxy session for %s (%v); no placeholder exported", hostPort, err))
+				continue
+			}
+			session = s
+			minted[conn.ID] = session
+			res.NewSessions = append(res.NewSessions, session)
+		}
+
+		varName := placeholderVarName(conn, taken)
+		res.Placeholders[varName] = placeholderPgURL(session, gatewayHost, caPath)
+		res.Index = append(res.Index, pgIndexEntry{Label: label, Host: hostPort, EnvVar: varName})
+	}
+	return res
+}
+
+// encodePgIndex renders the ONECLI_PG_CONNECTIONS value. Empty index →
+// empty string (the variable is then not exported at all).
+func encodePgIndex(index []pgIndexEntry) string {
+	if len(index) == 0 {
+		return ""
+	}
+	b, err := json.Marshal(index)
+	if err != nil {
+		return ""
+	}
+	return string(b)
+}
diff --git a/cmd/onecli/run_pg_premint_test.go b/cmd/onecli/run_pg_premint_test.go
new file mode 100644
index 0000000..651fc24
--- /dev/null
+++ b/cmd/onecli/run_pg_premint_test.go
@@ -0,0 +1,252 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+
+	"io"
+
+	"github.com/onecli/onecli-cli/internal/api"
+	"github.com/onecli/onecli-cli/pkg/output"
+)
+
+func strPtr(s string) *string { return &s }
+
+func TestPlaceholderVarName(t *testing.T) {
+	cases := []struct {
+		name  string
+		label *string
+		id    string
+		want  string
+	}{
+		{"simple label", strPtr("main-db"), "id1", "ONECLI_PG_MAIN_DB_URL"},
+		{"spaces and case", strPtr("Analytics Prod"), "id2", "ONECLI_PG_ANALYTICS_PROD_URL"},
+		{"symbols collapse", strPtr("a--b__c!!d"), "id3", "ONECLI_PG_A_B_C_D_URL"},
+		{"leading trailing trim", strPtr("--x--"), "id4", "ONECLI_PG_X_URL"},
+		{"no label uses id prefix", nil, "abcdef1234567890", "ONECLI_PG_ABCDEF12_URL"},
+		{"unicode stripped", strPtr("caf\u00e9"), "zz11xx22", "ONECLI_PG_CAF_URL"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := placeholderVarName(api.PgConnection{ID: tc.id, Label: tc.label}, map[string]bool{})
+			if got != tc.want {
+				t.Errorf("got %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestPlaceholderVarNameCollisions(t *testing.T) {
+	taken := map[string]bool{}
+	a := placeholderVarName(api.PgConnection{ID: "1", Label: strPtr("main db")}, taken)
+	b := placeholderVarName(api.PgConnection{ID: "2", Label: strPtr("main-db")}, taken)
+	c := placeholderVarName(api.PgConnection{ID: "3", Label: strPtr("MAIN_DB")}, taken)
+	if a != "ONECLI_PG_MAIN_DB_URL" {
+		t.Errorf("first = %q", a)
+	}
+	if b != "ONECLI_PG_MAIN_DB_2_URL" || c != "ONECLI_PG_MAIN_DB_3_URL" {
+		t.Errorf("collisions = %q, %q; want _2/_3 suffixes", b, c)
+	}
+}
+
+func TestPlaceholderPgURL(t *testing.T) {
+	session := &api.PgSession{User: "aoc_pg_tok", ListenPort: 6432}
+
+	t.Run("pinned database rides the path", func(t *testing.T) {
+		s := *session
+		s.Database = strPtr("appdb")
+		u, err := url.Parse(placeholderPgURL(&s, "gw.example.com", "/ca.pem"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if u.Path != "/appdb" {
+			t.Errorf("path = %q, want /appdb", u.Path)
+		}
+		if u.Query().Get("sslmode") != "verify-full" {
+			t.Errorf("sslmode = %q", u.Query().Get("sslmode"))
+		}
+	})
+
+	t.Run("no pin falls back to postgres, never the aoc user", func(t *testing.T) {
+		u, err := url.Parse(placeholderPgURL(session, "127.0.0.1", ""))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if u.Path != "/postgres" {
+			t.Errorf("path = %q, want /postgres (libpq would default to the aoc_pg_ username)", u.Path)
+		}
+		if u.Query().Get("sslmode") != "disable" {
+			t.Errorf("loopback sslmode = %q", u.Query().Get("sslmode"))
+		}
+	})
+}
+
+func TestPreMintPlaceholders(t *testing.T) {
+	conns := []api.PgConnection{
+		{ID: "covered", Label: strPtr("covered-db"), Host: "a.example.com", Port: 5432},
+		{ID: "extra", Label: strPtr("extra-db"), Host: "b.example.com", Port: 5432},
+		{ID: "failing", Label: strPtr("bad-db"), Host: "c.example.com", Port: 5432},
+	}
+	minted := map[string]*api.PgSession{
+		"covered": {SessionID: "s1", User: "aoc_pg_a", ListenPort: 6432, TTLSeconds: 900},
+	}
+	mint := func(id string) (*api.PgSession, error) {
+		if id == "failing" {
+			return nil, fmt.Errorf("boom")
+		}
+		return &api.PgSession{SessionID: "s-" + id, User: "aoc_pg_" + id, ListenPort: 6432, TTLSeconds: 900}, nil
+	}
+
+	res := preMintPlaceholders(
+		conns, minted, map[string]string{"covered": "DATABASE_URL"}, mint, "127.0.0.1", "")
+	placeholders, index, warnings := res.Placeholders, res.Index, res.Warnings
+
+	if len(placeholders) != 1 {
+		t.Fatalf("placeholders = %v, want exactly the extra connection", placeholders)
+	}
+	if _, ok := placeholders["ONECLI_PG_EXTRA_DB_URL"]; !ok {
+		t.Errorf("missing ONECLI_PG_EXTRA_DB_URL: %v", placeholders)
+	}
+	// Failing mint warns, never aborts.
+	if len(warnings) != 1 || !strings.Contains(warnings[0], "c.example.com") {
+		t.Errorf("warnings = %v", warnings)
+	}
+	// The index lists BOTH governed routes: swapped var + placeholder.
+	byLabel := map[string]pgIndexEntry{}
+	for _, e := range index {
+		byLabel[e.Label] = e
+	}
+	if byLabel["covered-db"].EnvVar != "DATABASE_URL" {
+		t.Errorf("covered entry = %+v", byLabel["covered-db"])
+	}
+	if byLabel["extra-db"].EnvVar != "ONECLI_PG_EXTRA_DB_URL" {
+		t.Errorf("extra entry = %+v", byLabel["extra-db"])
+	}
+	if _, listed := byLabel["bad-db"]; listed {
+		t.Error("a connection without a working route must not be advertised")
+	}
+	// The extra session landed in the shared mint map for reuse AND is
+	// reported as newly minted (the caller's sidecar registration set).
+	if minted["extra"] == nil || minted["extra"].SessionID != "s-extra" {
+		t.Errorf("minted map = %v", minted)
+	}
+	if len(res.NewSessions) != 1 || res.NewSessions[0].SessionID != "s-extra" {
+		t.Errorf("NewSessions = %v, want exactly the extra session", res.NewSessions)
+	}
+}
+
+func TestPreMintPlaceholdersCap(t *testing.T) {
+	var conns []api.PgConnection
+	for i := 0; i < pgPreMintMax+3; i++ {
+		conns = append(conns, api.PgConnection{
+			ID: fmt.Sprintf("c%d", i), Label: strPtr(fmt.Sprintf("db%d", i)),
+			Host: fmt.Sprintf("h%d.example.com", i), Port: 5432,
+		})
+	}
+	mint := func(id string) (*api.PgSession, error) {
+		return &api.PgSession{SessionID: "s-" + id, User: "aoc_pg_x", ListenPort: 6432, TTLSeconds: 900}, nil
+	}
+	res := preMintPlaceholders(conns, map[string]*api.PgSession{}, map[string]string{}, mint, "127.0.0.1", "")
+	if len(res.Placeholders) != pgPreMintMax {
+		t.Errorf("placeholders = %d, want cap %d", len(res.Placeholders), pgPreMintMax)
+	}
+	if len(res.Warnings) != 3 {
+		t.Errorf("warnings = %d, want 3 over-cap notices", len(res.Warnings))
+	}
+}
+
+func TestEncodePgIndex(t *testing.T) {
+	if encodePgIndex(nil) != "" {
+		t.Error("empty index must encode to empty string")
+	}
+	got := encodePgIndex([]pgIndexEntry{{Label: "main", Host: "db.example.com:5432", EnvVar: "ONECLI_PG_MAIN_URL"}})
+	var back []pgIndexEntry
+	if err := json.Unmarshal([]byte(got), &back); err != nil || len(back) != 1 || back[0].EnvVar != "ONECLI_PG_MAIN_URL" {
+		t.Errorf("round-trip failed: %q (%v)", got, err)
+	}
+	if strings.Contains(got, "$") {
+		t.Error("index must carry var NAMES, not $references (env values do not interpolate)")
+	}
+}
+
+// End-to-end through setupPgProxy: an empty env still yields placeholders
+// for every granted connection, and the sidecar gets their sessions.
+func TestSetupPgProxyPreMintsWithEmptyEnv(t *testing.T) {
+	var mintCalls int
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodGet {
+			_ = json.NewEncoder(w).Encode(api.PgConnectionsResponse{
+				Connections: []api.PgConnection{
+					{ID: "c1", Label: strPtr("main"), Host: "db.example.com", Port: 5432},
+				},
+				ListenPort: 6432,
+			})
+			return
+		}
+		mintCalls++
+		_ = json.NewEncoder(w).Encode(api.PgSession{
+			SessionID: "s1", Token: "tok", User: "aoc_pg_tok", ListenPort: 6432, TTLSeconds: 900,
+		})
+	}))
+	defer srv.Close()
+
+	client := &api.PgGatewayClient{BaseURL: srv.URL, AgentToken: "aoc_x"}
+	out := output.NewWithWriters(io.Discard, io.Discard)
+	outcome, err := setupPgProxy(out, client, "127.0.0.1", "", nil, t.TempDir(), false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if outcome == nil {
+		t.Fatal("outcome must not be nil when granted connections exist")
+	}
+	if mintCalls != 1 {
+		t.Errorf("mint calls = %d, want 1", mintCalls)
+	}
+	if len(outcome.Placeholders) != 1 || outcome.Placeholders["ONECLI_PG_MAIN_URL"] == "" {
+		t.Errorf("placeholders = %v", outcome.Placeholders)
+	}
+	if len(outcome.SessionIDs) != 1 || outcome.SessionIDs[0] != "s1" {
+		t.Errorf("sessions for sidecar = %v", outcome.SessionIDs)
+	}
+	if outcome.TTLSeconds != 900 {
+		t.Errorf("ttl = %d", outcome.TTLSeconds)
+	}
+	if outcome.IndexJSON == "" || !strings.Contains(outcome.IndexJSON, "ONECLI_PG_MAIN_URL") {
+		t.Errorf("index = %q", outcome.IndexJSON)
+	}
+}
+
+// Pre-mint failures must not abort even under --pg-proxy=required: only
+// databases the env actually references are covered by required.
+func TestSetupPgProxyRequiredIgnoresPreMintFailure(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodGet {
+			_ = json.NewEncoder(w).Encode(api.PgConnectionsResponse{
+				Connections: []api.PgConnection{
+					{ID: "c1", Label: strPtr("unused"), Host: "other.example.com", Port: 5432},
+				},
+				ListenPort: 6432,
+			})
+			return
+		}
+		w.WriteHeader(http.StatusInternalServerError) // every mint fails
+	}))
+	defer srv.Close()
+
+	client := &api.PgGatewayClient{BaseURL: srv.URL, AgentToken: "aoc_x"}
+	out := output.NewWithWriters(io.Discard, io.Discard)
+	// Env has NO postgres URL: nothing matched, so required has nothing
+	// to enforce; the pre-mint failure stays a warning.
+	outcome, err := setupPgProxy(out, client, "127.0.0.1", "", nil, t.TempDir(), true)
+	if err != nil {
+		t.Errorf("pre-mint failure aborted a required run: %v", err)
+	}
+	if outcome != nil {
+		t.Errorf("no governed route established, outcome should be nil, got %+v", outcome)
+	}
+}
diff --git a/cmd/onecli/run_pg_sidecar.go b/cmd/onecli/run_pg_sidecar.go
new file mode 100644
index 0000000..cc0c363
--- /dev/null
+++ b/cmd/onecli/run_pg_sidecar.go
@@ -0,0 +1,205 @@
+package main
+
+// The pg session sidecar: a small detached child process that outlives
+// `onecli run`'s exec. run.go execs the agent binary in-place (preserving
+// PID and TTY semantics), so nothing in the main path can heartbeat pg
+// sessions or reap them when the agent exits. The sidecar is forked
+// FIRST, watches its parent PID (which becomes the agent after exec), and:
+//   - heartbeats each session on an interval while the parent lives,
+//   - deletes the sessions when the parent exits,
+//   - exits on its own if the gateway reports every session gone.
+//
+// Failure is safe by construction: if the sidecar dies, heartbeats stop
+// and the gateway expires the sessions at TTL.
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+	"time"
+
+	"github.com/onecli/onecli-cli/internal/api"
+)
+
+const (
+	pgSidecarFlag = "__pg-sidecar"
+	// Heartbeat fallback when the session TTL is unknown; normally the
+	// interval is derived from the minted TTL (see heartbeatInterval).
+	pgHeartbeatDefault = 5 * time.Minute
+	pgHeartbeatFloor   = 15 * time.Second
+	pgParentPollEvery  = 2 * time.Second
+	// Watcher pass interval: frequent enough to catch short-lived direct
+	// connections without measurable overhead (one lsof + ps exec).
+	pgWatchEvery = 15 * time.Second
+)
+
+// heartbeatInterval keeps a session alive with margin: a third of its TTL, so
+// two heartbeats can be missed before expiry. Falls back to a fixed interval
+// when the TTL is unknown, and never drops below a floor.
+func heartbeatInterval(ttlSeconds uint64) time.Duration {
+	if ttlSeconds == 0 {
+		return pgHeartbeatDefault
+	}
+	d := time.Duration(ttlSeconds/3) * time.Second
+	if d < pgHeartbeatFloor {
+		return pgHeartbeatFloor
+	}
+	return d
+}
+
+// spawnPgSidecar forks a detached copy of this binary in sidecar mode.
+// Must be called BEFORE syscall.Exec. Best-effort: a spawn failure only
+// means sessions expire by TTL instead of promptly (and no watcher runs).
+// watchHosts is the encoded registered host→connection map for the
+// direct-connection watcher; gatewayPgAddr the pg listener host:port the
+// watcher must never report (the governed route itself).
+func spawnPgSidecar(gatewayURL, agentToken string, sessionIDs []string, ttlSeconds uint64, watchHosts, gatewayPgAddr string) {
+	if len(sessionIDs) == 0 && watchHosts == "" {
+		return
+	}
+	self, err := os.Executable()
+	if err != nil {
+		return
+	}
+	cmd := exec.Command(self, pgSidecarFlag,
+		"--parent", fmt.Sprintf("%d", os.Getpid()),
+		"--gateway", gatewayURL,
+		"--sessions", strings.Join(sessionIDs, ","),
+		"--ttl", fmt.Sprintf("%d", ttlSeconds),
+	)
+	// The token rides the environment, not argv — argv is visible to
+	// every process on the machine via ps. The watch config rides env
+	// for symmetry (it is not secret, but argv length is bounded).
+	cmd.Env = append(os.Environ(),
+		"ONECLI_PG_SIDECAR_TOKEN="+agentToken,
+		"ONECLI_PG_WATCH_HOSTS="+watchHosts,
+		"ONECLI_PG_GATEWAY_ADDR="+gatewayPgAddr,
+	)
+	cmd.Stdout = nil
+	cmd.Stderr = nil
+	cmd.Stdin = nil
+	cmd.SysProcAttr = detachedSysProcAttr()
+	_ = cmd.Start()
+	// Deliberately not Wait()ed: Setsid detaches it from our session, and
+	// exec replaces this process image momentarily anyway.
+}
+
+// parsePgSidecarArgs parses the hidden-mode argv:
+// __pg-sidecar --parent <pid> --gateway <url> --sessions <id,id,...>
+// The agent token rides ONECLI_PG_SIDECAR_TOKEN (not argv — ps-visible);
+// the watcher's host map rides ONECLI_PG_WATCH_HOSTS + _GATEWAY_ADDR.
+func parsePgSidecarArgs(argv []string) (pgSidecarArgs, bool) {
+	args := pgSidecarArgs{
+		agentToken:    os.Getenv("ONECLI_PG_SIDECAR_TOKEN"),
+		watchHosts:    os.Getenv("ONECLI_PG_WATCH_HOSTS"),
+		gatewayPgAddr: os.Getenv("ONECLI_PG_GATEWAY_ADDR"),
+	}
+	for i := 0; i+1 < len(argv); i += 2 {
+		switch argv[i] {
+		case "--parent":
+			if _, err := fmt.Sscanf(argv[i+1], "%d", &args.parentPID); err != nil {
+				return args, false
+			}
+		case "--gateway":
+			args.gatewayURL = argv[i+1]
+		case "--sessions":
+			for _, id := range strings.Split(argv[i+1], ",") {
+				if id = strings.TrimSpace(id); id != "" {
+					args.sessionIDs = append(args.sessionIDs, id)
+				}
+			}
+		case "--ttl":
+			// Optional: absent for older callers → 0 → default interval.
+			_, _ = fmt.Sscanf(argv[i+1], "%d", &args.ttlSeconds)
+		}
+	}
+	ok := args.parentPID > 0 && args.gatewayURL != "" && (len(args.sessionIDs) > 0 || args.watchHosts != "") && args.agentToken != ""
+	return args, ok
+}
+
+// runPgSidecar is the sidecar entry point (invoked via the hidden flag).
+type pgSidecarArgs struct {
+	parentPID  int
+	gatewayURL string
+	sessionIDs []string
+	agentToken string
+	ttlSeconds uint64
+	// watchHosts is the encoded registered host→connection-id map for
+	// the direct-connection watcher (empty disables watching).
+	watchHosts string
+	// gatewayPgAddr is the pg listener host:port never reported.
+	gatewayPgAddr string
+}
+
+func runPgSidecar(args pgSidecarArgs) {
+	client := &api.PgGatewayClient{BaseURL: args.gatewayURL, AgentToken: args.agentToken}
+
+	heartbeat := time.NewTicker(heartbeatInterval(args.ttlSeconds))
+	defer heartbeat.Stop()
+	parentPoll := time.NewTicker(pgParentPollEvery)
+	defer parentPoll.Stop()
+
+	// The direct-connection watcher (layer 3): enabled only when the
+	// parent passed a registered-host map.
+	var watch *pgWatchState
+	watchTick := time.NewTicker(pgWatchEvery)
+	defer watchTick.Stop()
+	if hosts := parsePgWatchHosts(args.watchHosts); len(hosts) > 0 {
+		watch = &pgWatchState{
+			registeredHosts: hosts,
+			gatewayAddrs:    map[string]bool{args.gatewayPgAddr: true},
+			lastReport:      map[string]time.Time{},
+		}
+	}
+
+	for {
+		select {
+		case <-parentPoll.C:
+			if !processAlive(args.parentPID) {
+				reapSessions(client, args.sessionIDs)
+				return
+			}
+		case <-watchTick.C:
+			if watch != nil {
+				watchOnce(client, watch, agentTreePids(args.parentPID))
+			}
+		case <-heartbeat.C:
+			if len(args.sessionIDs) == 0 {
+				continue
+			}
+			alive := false
+			for _, id := range args.sessionIDs {
+				ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+				if err := client.HeartbeatPgSession(ctx, id); err == nil {
+					alive = true
+				}
+				cancel()
+			}
+			// Every session gone (expired or deleted elsewhere): keep
+			// running only for the watcher; exit when it is off too.
+			if !alive && watch == nil {
+				return
+			}
+			if !alive {
+				args.sessionIDs = nil
+			}
+		}
+	}
+}
+
+func reapSessions(client *api.PgGatewayClient, sessionIDs []string) {
+	for _, id := range sessionIDs {
+		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		_ = client.DeletePgSession(ctx, id)
+		cancel()
+	}
+}
+
+// processAlive reports whether pid is still running. After exec the PID
+// belongs to the agent, which is exactly the process whose lifetime
+// gates the sessions.
+func processAlive(pid int) bool {
+	return processAliveByPID(pid)
+}
diff --git a/cmd/onecli/run_pg_test.go b/cmd/onecli/run_pg_test.go
new file mode 100644
index 0000000..b73dc50
--- /dev/null
+++ b/cmd/onecli/run_pg_test.go
@@ -0,0 +1,375 @@
+package main
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/onecli/onecli-cli/internal/api"
+	"github.com/onecli/onecli-cli/pkg/output"
+)
+
+func TestParsePgURL(t *testing.T) {
+	cases := []struct {
+		name  string
+		value string
+		want  bool
+	}{
+		{"postgres scheme", "postgres://u:p@db.example.com:5432/app", true},
+		{"postgresql scheme", "postgresql://u:p@db.example.com/app", true},
+		{"quoted value", `"postgresql://u:p@db.example.com/app"`, true},
+		{"not a db url", "https://example.com", false},
+		{"empty", "", false},
+		{"unix socket (no host)", "postgresql:///dbname?host=/var/run/postgresql", false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := parsePgURL(tc.value)
+			if (got != nil) != tc.want {
+				t.Errorf("parsePgURL(%q) = %v, want match=%v", tc.value, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestScanPgURLsEnvWinsOverDotenv(t *testing.T) {
+	dir := t.TempDir()
+	dotenv := filepath.Join(dir, ".env")
+	if err := os.WriteFile(dotenv, []byte(
+		"# comment\n"+
+			"DATABASE_URL=postgresql://file:pw@file-host:5432/app\n"+
+			"ONLY_IN_FILE=postgres://only:pw@file-only-host/db\n"+
+			"NOT_A_DB=hello\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	environ := []string{
+		"DATABASE_URL=postgresql://env:pw@env-host:5433/app",
+		"PATH=/usr/bin",
+	}
+	scans := scanPgURLs(environ, dir)
+
+	byName := map[string]pgScanResult{}
+	for _, s := range scans {
+		byName[s.VarName] = s
+	}
+	if len(byName) != 2 {
+		t.Fatalf("expected 2 results, got %d: %v", len(byName), byName)
+	}
+	if got := byName["DATABASE_URL"].URL.Hostname(); got != "env-host" {
+		t.Errorf("env should win over .env, got host %q", got)
+	}
+	if byName["DATABASE_URL"].FromEnvFile {
+		t.Error("DATABASE_URL should be marked as from the process env")
+	}
+	if got := byName["ONLY_IN_FILE"].URL.Hostname(); got != "file-only-host" {
+		t.Errorf("file-only var missing, got %q", got)
+	}
+}
+
+func TestParseDotenvFile(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, ".env")
+	content := "export EXPORTED=postgres://a:b@h/db\n" +
+		"QUOTED='postgresql://q:w@qh/db'\n" +
+		"WITH_COMMENT=postgres://c:d@ch/db # prod!\n" +
+		"BROKEN\n"
+	if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	got := parseDotenvFile(path)
+	if got["EXPORTED"] != "postgres://a:b@h/db" {
+		t.Errorf("export prefix not stripped: %q", got["EXPORTED"])
+	}
+	if got["QUOTED"] != "'postgresql://q:w@qh/db'" {
+		t.Errorf("quoted value mangled: %q", got["QUOTED"])
+	}
+	if got["WITH_COMMENT"] != "postgres://c:d@ch/db" {
+		t.Errorf("inline comment not trimmed: %q", got["WITH_COMMENT"])
+	}
+	if _, ok := got["BROKEN"]; ok {
+		t.Error("malformed line should be skipped")
+	}
+	if parseDotenvFile(filepath.Join(dir, "missing")) != nil {
+		t.Error("missing file should return nil")
+	}
+}
+
+func TestBuildPgProxyURL(t *testing.T) {
+	orig, _ := url.Parse("postgresql://real:secret@db.example.com:5432/app?schema=public&sslmode=require&connect_timeout=5")
+
+	got := buildPgProxyURL(orig, "aoc_pg_tok", "127.0.0.1", "", 6432)
+	u, err := url.Parse(got)
+	if err != nil {
+		t.Fatalf("proxy URL does not parse: %v", err)
+	}
+	if u.Hostname() != "127.0.0.1" || u.Port() != "6432" {
+		t.Errorf("wrong proxy host: %s", u.Host)
+	}
+	if u.User.Username() != "aoc_pg_tok" {
+		t.Errorf("token not in username: %s", u.User.Username())
+	}
+	if pw, _ := u.User.Password(); pw != "x" {
+		t.Errorf("expected dummy password, got %q", pw)
+	}
+	if u.Path != "/app" {
+		t.Errorf("database path not preserved: %q", u.Path)
+	}
+	q := u.Query()
+	if q.Get("schema") != "public" || q.Get("connect_timeout") != "5" {
+		t.Errorf("client-semantic params dropped: %v", q)
+	}
+	if q.Get("sslmode") != "disable" {
+		t.Errorf("loopback leg should pin sslmode=disable, got %q", q.Get("sslmode"))
+	}
+	// The real password must never appear anywhere in the proxy URL.
+	if containsSubstring(got, "secret") {
+		t.Errorf("real credential leaked into proxy URL: %s", got)
+	}
+
+	// Remote gateway WITH the installed CA ⇒ verify-full + sslrootcert.
+	remote := buildPgProxyURL(orig, "aoc_pg_tok", "gw.example.com", "/home/u/.onecli/ca-bundle.pem", 6432)
+	ru, _ := url.Parse(remote)
+	if ru.Query().Get("sslmode") != "verify-full" {
+		t.Errorf("remote+CA leg should verify-full, got %q", ru.Query().Get("sslmode"))
+	}
+	if ru.Query().Get("sslrootcert") != "/home/u/.onecli/ca-bundle.pem" {
+		t.Errorf("remote+CA leg should set sslrootcert, got %q", ru.Query().Get("sslrootcert"))
+	}
+
+	// Remote gateway WITHOUT a CA path ⇒ require (encrypted, unverified).
+	remoteNoCA := buildPgProxyURL(orig, "aoc_pg_tok", "gw.example.com", "", 6432)
+	rnu, _ := url.Parse(remoteNoCA)
+	if rnu.Query().Get("sslmode") != "require" {
+		t.Errorf("remote-without-CA leg should require TLS, got %q", rnu.Query().Get("sslmode"))
+	}
+}
+
+func TestGatewayOriginAndToken(t *testing.T) {
+	origin, token, ok := gatewayOriginAndToken("http://x:aoc_abc123@127.0.0.1:10254")
+	if !ok || origin != "http://127.0.0.1:10254" || token != "aoc_abc123" {
+		t.Errorf("got (%q,%q,%v)", origin, token, ok)
+	}
+	// Username-position token.
+	origin, token, ok = gatewayOriginAndToken("http://aoc_zzz@gw:1")
+	if !ok || origin != "http://gw:1" || token != "aoc_zzz" {
+		t.Errorf("got (%q,%q,%v)", origin, token, ok)
+	}
+	if _, _, ok := gatewayOriginAndToken("http://user:pw@host:1"); ok {
+		t.Error("non-aoc credentials must not be treated as a token")
+	}
+	if _, _, ok := gatewayOriginAndToken("not a url"); ok {
+		t.Error("garbage must not parse")
+	}
+}
+
+func TestRemoveEnvKey(t *testing.T) {
+	env := []string{"A=1", "DATABASE_URL=x", "B=2", "DATABASE_URL=y"}
+	got := removeEnvKey(env, "DATABASE_URL")
+	if len(got) != 2 || got[0] != "A=1" || got[1] != "B=2" {
+		t.Errorf("got %v", got)
+	}
+}
+
+func TestParsePgSidecarArgs(t *testing.T) {
+	t.Setenv("ONECLI_PG_SIDECAR_TOKEN", "aoc_tok")
+	args, ok := parsePgSidecarArgs([]string{
+		"--parent", "1234",
+		"--gateway", "http://127.0.0.1:10254",
+		"--sessions", "s1,s2",
+		"--ttl", "900",
+	})
+	if !ok {
+		t.Fatal("expected ok")
+	}
+	if args.parentPID != 1234 || args.gatewayURL != "http://127.0.0.1:10254" || len(args.sessionIDs) != 2 {
+		t.Errorf("got %+v", args)
+	}
+	if args.ttlSeconds != 900 {
+		t.Errorf("ttl not parsed: got %d", args.ttlSeconds)
+	}
+
+	t.Setenv("ONECLI_PG_SIDECAR_TOKEN", "")
+	if _, ok := parsePgSidecarArgs([]string{"--parent", "1", "--gateway", "g", "--sessions", "s"}); ok {
+		t.Error("missing token must fail")
+	}
+}
+
+func TestMatchPgScans(t *testing.T) {
+	mk := func(raw string) pgScanResult {
+		u, err := url.Parse(raw)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return pgScanResult{VarName: "V", URL: u}
+	}
+	conns := []api.PgConnection{
+		{ID: "c1", Host: "db.example.com", Port: 5432},
+		{ID: "c2", Host: "other.example.com", Port: 6543},
+	}
+
+	matches := matchPgScans([]pgScanResult{
+		mk("postgres://u:p@db.example.com/app"),         // default port matches c1
+		mk("postgres://u:p@db.example.com:6543/app"),    // wrong port — no match
+		mk("postgres://u:p@other.example.com:6543/x"),   // matches c2
+		mk("postgres://u:p@unknown.example.com:5432/y"), // unregistered
+	}, conns)
+
+	if matches[0].Conn == nil || matches[0].Conn.ID != "c1" {
+		t.Errorf("default-port match failed: %+v", matches[0])
+	}
+	if matches[1].Conn != nil {
+		t.Error("port mismatch must not match")
+	}
+	if matches[2].Conn == nil || matches[2].Conn.ID != "c2" {
+		t.Errorf("nonstandard-port match failed: %+v", matches[2])
+	}
+	if matches[3].Conn != nil {
+		t.Error("unregistered host must not match")
+	}
+}
+
+func TestLibpqScan(t *testing.T) {
+	s := libpqScan(map[string]string{
+		"PGHOST": "db.example.com", "PGPORT": "5433",
+		"PGUSER": "app", "PGPASSWORD": "secret", "PGDATABASE": "mydb",
+	})
+	if s == nil || !s.Libpq {
+		t.Fatalf("expected a libpq scan, got %+v", s)
+	}
+	if s.URL.Hostname() != "db.example.com" || s.URL.Port() != "5433" {
+		t.Errorf("wrong host:port: %s", s.URL.Host)
+	}
+	if s.URL.Path != "/mydb" {
+		t.Errorf("database not carried into synthetic URL: %q", s.URL.Path)
+	}
+	// Path-style PGHOST (unix socket) is deliberately skipped.
+	if libpqScan(map[string]string{"PGHOST": "/var/run/postgresql"}) != nil {
+		t.Error("unix-socket PGHOST must be skipped")
+	}
+	// No PGHOST → no scan.
+	if libpqScan(map[string]string{"PGUSER": "x"}) != nil {
+		t.Error("missing PGHOST must produce no scan")
+	}
+	// PGPORT unset defaults to 5432.
+	d := libpqScan(map[string]string{"PGHOST": "h"})
+	if d == nil || d.URL.Port() != "5432" {
+		t.Errorf("expected default port 5432, got %+v", d)
+	}
+}
+
+func TestScanPgURLsLibpqGroup(t *testing.T) {
+	environ := []string{"PGHOST=env-host", "PGPORT=5432", "PGUSER=app", "PATH=/usr/bin"}
+	scans := scanPgURLs(environ, t.TempDir())
+	var lib *pgScanResult
+	for i := range scans {
+		if scans[i].Libpq {
+			lib = &scans[i]
+		}
+	}
+	if lib == nil {
+		t.Fatal("libpq group not scanned")
+	}
+	if lib.URL.Hostname() != "env-host" {
+		t.Errorf("wrong libpq host: %s", lib.URL.Hostname())
+	}
+}
+
+func TestBuildLibpqEnv(t *testing.T) {
+	loop := buildLibpqEnv("aoc_pg_tok", "127.0.0.1", "", 6432)
+	if loop["PGHOST"] != "127.0.0.1" || loop["PGPORT"] != "6432" {
+		t.Errorf("wrong host/port: %v", loop)
+	}
+	if loop["PGUSER"] != "aoc_pg_tok" || loop["PGPASSWORD"] != "x" {
+		t.Errorf("wrong user/password: %v", loop)
+	}
+	if loop["PGSSLMODE"] != "disable" {
+		t.Errorf("loopback should disable TLS, got %q", loop["PGSSLMODE"])
+	}
+	if _, ok := loop["PGDATABASE"]; ok {
+		t.Error("PGDATABASE must pass through, never be emitted")
+	}
+	rem := buildLibpqEnv("aoc_pg_tok", "gw.example.com", "/ca.pem", 6432)
+	if rem["PGSSLMODE"] != "verify-full" || rem["PGSSLROOTCERT"] != "/ca.pem" {
+		t.Errorf("remote+CA wrong TLS: %v", rem)
+	}
+	rn := buildLibpqEnv("aoc_pg_tok", "gw.example.com", "", 6432)
+	if rn["PGSSLMODE"] != "require" {
+		t.Errorf("remote no-CA should require TLS, got %q", rn["PGSSLMODE"])
+	}
+}
+
+func TestMatchPgScansHostNormalization(t *testing.T) {
+	u, _ := url.Parse("postgres://u:p@db.example.com./app") // lowercase + trailing dot
+	conns := []api.PgConnection{{ID: "c1", Host: "DB.Example.COM", Port: 5432}}
+	matches := matchPgScans([]pgScanResult{{VarName: "V", URL: u}}, conns)
+	if matches[0].Conn == nil || matches[0].Conn.ID != "c1" {
+		t.Errorf("case/trailing-dot host should match: %+v", matches[0])
+	}
+}
+
+func TestHeartbeatInterval(t *testing.T) {
+	if got := heartbeatInterval(0); got != pgHeartbeatDefault {
+		t.Errorf("ttl=0 should use default, got %v", got)
+	}
+	if got := heartbeatInterval(900); got != 300*time.Second {
+		t.Errorf("ttl=900 should be 300s, got %v", got)
+	}
+	if got := heartbeatInterval(30); got != pgHeartbeatFloor {
+		t.Errorf("ttl=30 should clamp to floor, got %v", got)
+	}
+}
+
+func TestSetupPgProxyRequiredListFailure(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer srv.Close()
+	client := &api.PgGatewayClient{BaseURL: srv.URL, AgentToken: "aoc_x"}
+	environ := []string{"DATABASE_URL=postgres://u:p@db.example.com:5432/app"}
+	out := output.NewWithWriters(io.Discard, io.Discard)
+
+	if _, err := setupPgProxy(out, client, "127.0.0.1", "", environ, t.TempDir(), true); err == nil {
+		t.Error("required mode must error when the gateway list fails")
+	}
+	outcome, err := setupPgProxy(out, client, "127.0.0.1", "", environ, t.TempDir(), false)
+	if err != nil || outcome != nil {
+		t.Errorf("default mode must fail open, got (%v, %v)", outcome, err)
+	}
+}
+
+func TestSetupPgProxyRequiredMintFailure(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodGet {
+			_ = json.NewEncoder(w).Encode(api.PgConnectionsResponse{
+				Connections: []api.PgConnection{{ID: "c1", Host: "db.example.com", Port: 5432}},
+				ListenPort:  6432,
+			})
+			return
+		}
+		w.WriteHeader(http.StatusInternalServerError) // mint fails
+	}))
+	defer srv.Close()
+	client := &api.PgGatewayClient{BaseURL: srv.URL, AgentToken: "aoc_x"}
+	environ := []string{"DATABASE_URL=postgres://u:p@db.example.com:5432/app"}
+	out := output.NewWithWriters(io.Discard, io.Discard)
+
+	if _, err := setupPgProxy(out, client, "127.0.0.1", "", environ, t.TempDir(), true); err == nil {
+		t.Error("required mode must error when session mint fails for a matched db")
+	}
+}
+
+func containsSubstring(s, sub string) bool {
+	for i := 0; i+len(sub) <= len(s); i++ {
+		if s[i:i+len(sub)] == sub {
+			return true
+		}
+	}
+	return false
+}
diff --git a/cmd/onecli/run_pg_watch.go b/cmd/onecli/run_pg_watch.go
new file mode 100644
index 0000000..4aca200
--- /dev/null
+++ b/cmd/onecli/run_pg_watch.go
@@ -0,0 +1,240 @@
+package main
+
+// The direct-connection watcher: layer 3 of the pg governance model
+// (design doc "Guidance loop for direct-connection attempts"). While the
+// agent runs, the sidecar periodically enumerates the agent process
+// tree's ESTABLISHED TCP connections to common postgres ports. A peer
+// that is NOT the gateway pg listener is reported to the gateway:
+//   - peer matches a REGISTERED database host → pg_direct_connection
+//     (the dashboard shows "agent connected directly, bypassing
+//     governance"),
+//   - otherwise → pg_unregistered_connection (the "connect it in the
+//     dashboard" nudge).
+//
+// Detection is after-the-fact by nature; the PRIMARY corrective stays
+// the skill/hook guidance and the swap. Failure is inert: watcher errors
+// never affect the agent, and reporting is debounced per peer.
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"os/exec"
+	"runtime"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/onecli/onecli-cli/internal/api"
+)
+
+// pgWatchPorts are the TCP ports treated as postgres-ish. 6543 because
+// Supabase's transaction pooler is a common agent-encountered endpoint.
+var pgWatchPorts = map[uint16]bool{5432: true, 5433: true, 5439: true, 6432: true, 6543: true}
+
+// pgWatchDebounce suppresses repeat reports for the same peer.
+const pgWatchDebounce = 10 * time.Minute
+
+// pgWatchState carries the watcher's config + debounce memory.
+type pgWatchState struct {
+	// registeredHosts maps host:port → connection id (normalized like
+	// matchPgScans keys). Passed from the parent via env at spawn.
+	registeredHosts map[string]string
+	// gatewayAddrs are listener addresses never reported (the proxy
+	// itself): the pg listener host:port forms.
+	gatewayAddrs map[string]bool
+	lastReport   map[string]time.Time
+}
+
+// pgObservedConn is one ESTABLISHED TCP connection of the agent tree.
+type pgObservedConn struct {
+	PeerHost string
+	PeerPort uint16
+}
+
+// classifyObserved decides what (if anything) to report for one observed
+// connection. Pure: takes the clock for debounce testing.
+func (w *pgWatchState) classifyObserved(conn pgObservedConn, now time.Time) (kind string, connectionID string, report bool) {
+	if !pgWatchPorts[conn.PeerPort] {
+		return "", "", false
+	}
+	key := normalizeHostPort(conn.PeerHost, fmt.Sprintf("%d", conn.PeerPort))
+	if w.gatewayAddrs[key] {
+		return "", "", false
+	}
+	if last, seen := w.lastReport[key]; seen && now.Sub(last) < pgWatchDebounce {
+		return "", "", false
+	}
+	w.lastReport[key] = now
+	if id, ok := w.registeredHosts[key]; ok {
+		return "pg_direct_connection", id, true
+	}
+	return "pg_unregistered_connection", "", true
+}
+
+// watchOnce runs one detection pass: enumerate + classify + report. Both
+// the registered-host map AND the gateway's own listener address are
+// DNS-expanded per pass (lsof reports IP peers, config uses hostnames) —
+// without expanding gatewayAddrs, the agent's own governed connections to
+// a REMOTE gateway (hostname config, IP peer, port 6432 in the watch
+// list) would be false-positive reported. The state's own maps stay
+// hostname-keyed.
+func watchOnce(client *api.PgGatewayClient, w *pgWatchState, pids []int) {
+	lookup := func(host string) ([]string, error) { return net.LookupHost(host) }
+	gatewayExpanded := map[string]bool{}
+	gatewayAsMap := map[string]string{}
+	for addr := range w.gatewayAddrs {
+		gatewayAsMap[addr] = ""
+	}
+	for addr := range expandWatchHostsDNS(gatewayAsMap, lookup) {
+		gatewayExpanded[addr] = true
+	}
+	pass := &pgWatchState{
+		registeredHosts: expandWatchHostsDNS(w.registeredHosts, lookup),
+		gatewayAddrs:    gatewayExpanded,
+		lastReport:      w.lastReport, // shared: debounce survives passes
+	}
+	for _, conn := range observedPgConns(pids) {
+		kind, connID, report := pass.classifyObserved(conn, time.Now())
+		if !report {
+			continue
+		}
+		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		_ = client.ReportPgWatchEvent(ctx, kind, conn.PeerHost, conn.PeerPort, connID)
+		cancel()
+	}
+}
+
+// observedPgConns enumerates ESTABLISHED TCP peers of the given pids.
+// macOS: lsof (in the default PATH on every macOS). Linux: procfs would
+// be cheaper, but lsof is present on the distros agents actually run and
+// keeps one code path; a procfs fast path can come later.
+func observedPgConns(pids []int) []pgObservedConn {
+	if len(pids) == 0 {
+		return nil
+	}
+	if runtime.GOOS != "darwin" && runtime.GOOS != "linux" {
+		return nil
+	}
+	pidList := make([]string, 0, len(pids))
+	for _, p := range pids {
+		pidList = append(pidList, strconv.Itoa(p))
+	}
+	// -a: AND the filters; -p: pids; -iTCP -sTCP:ESTABLISHED: established
+	// TCP only; -n/-P: numeric hosts/ports (no DNS stalls); -F n: parse-
+	// friendly output (peer address lines start with 'n').
+	out, err := exec.Command("lsof", "-a", "-p", strings.Join(pidList, ","),
+		"-iTCP", "-sTCP:ESTABLISHED", "-n", "-P", "-F", "n").Output()
+	if err != nil {
+		// lsof exits 1 when nothing matches — that is the common case.
+		return nil
+	}
+	return parseLsofConns(string(out))
+}
+
+// parseLsofConns extracts peer host:port pairs from `lsof -F n` output.
+// Connection lines look like "nlocal->peer:port"; only the peer side
+// matters here.
+func parseLsofConns(out string) []pgObservedConn {
+	var conns []pgObservedConn
+	seen := map[string]bool{}
+	for _, line := range strings.Split(out, "\n") {
+		if !strings.HasPrefix(line, "n") || !strings.Contains(line, "->") {
+			continue
+		}
+		peer := line[strings.Index(line, "->")+2:]
+		host, portStr, err := net.SplitHostPort(strings.TrimSpace(peer))
+		if err != nil {
+			continue
+		}
+		port, err := strconv.ParseUint(portStr, 10, 16)
+		if err != nil {
+			continue
+		}
+		key := host + ":" + portStr
+		if seen[key] {
+			continue
+		}
+		seen[key] = true
+		conns = append(conns, pgObservedConn{PeerHost: host, PeerPort: uint16(port)})
+	}
+	return conns
+}
+
+// agentTreePids returns the parent pid plus its descendants (best-effort:
+// one `ps` pass, direct + transitive children).
+func agentTreePids(parent int) []int {
+	out, err := exec.Command("ps", "-axo", "pid=,ppid=").Output()
+	if err != nil {
+		return []int{parent}
+	}
+	children := map[int][]int{}
+	for _, line := range strings.Split(string(out), "\n") {
+		fields := strings.Fields(line)
+		if len(fields) != 2 {
+			continue
+		}
+		pid, err1 := strconv.Atoi(fields[0])
+		ppid, err2 := strconv.Atoi(fields[1])
+		if err1 != nil || err2 != nil {
+			continue
+		}
+		children[ppid] = append(children[ppid], pid)
+	}
+	pids := []int{parent}
+	for i := 0; i < len(pids); i++ {
+		pids = append(pids, children[pids[i]]...)
+	}
+	return pids
+}
+
+// parsePgWatchHosts decodes the ONECLI_PG_WATCH_HOSTS env value:
+// comma-separated host:port=connection-id entries.
+func parsePgWatchHosts(raw string) map[string]string {
+	out := map[string]string{}
+	for _, entry := range strings.Split(raw, ",") {
+		entry = strings.TrimSpace(entry)
+		i := strings.LastIndexByte(entry, '=')
+		if i <= 0 || i == len(entry)-1 {
+			continue
+		}
+		out[entry[:i]] = entry[i+1:]
+	}
+	return out
+}
+
+// expandWatchHostsDNS adds IP-keyed entries for every hostname-keyed
+// entry: lsof reports peers as IP literals (-n, no DNS stalls), while
+// databases are registered by hostname — without the expansion a direct
+// connection would never match. Resolution happens in the sidecar, off
+// the agent's critical path, and is refreshed per call so DNS changes
+// are picked up across watch passes. Lookup failures leave the original
+// entry: an unresolvable host cannot be dialed directly either.
+func expandWatchHostsDNS(hosts map[string]string, lookup func(host string) ([]string, error)) map[string]string {
+	out := make(map[string]string, len(hosts)*2)
+	for key, id := range hosts {
+		out[key] = id
+		host, port, err := net.SplitHostPort(key)
+		if err != nil || net.ParseIP(host) != nil {
+			continue // already an IP literal (or malformed)
+		}
+		addrs, err := lookup(host)
+		if err != nil {
+			continue
+		}
+		for _, addr := range addrs {
+			out[normalizeHostPort(addr, port)] = id
+		}
+	}
+	return out
+}
+
+// encodePgWatchHosts is the inverse of parsePgWatchHosts, built from the
+// registered connection list at spawn.
+func encodePgWatchHosts(conns []api.PgConnection) string {
+	var entries []string
+	for _, c := range conns {
+		entries = append(entries, normalizeHostPort(c.Host, fmt.Sprintf("%d", c.Port))+"="+c.ID)
+	}
+	return strings.Join(entries, ",")
+}
diff --git a/cmd/onecli/run_pg_watch_test.go b/cmd/onecli/run_pg_watch_test.go
new file mode 100644
index 0000000..96bb87e
--- /dev/null
+++ b/cmd/onecli/run_pg_watch_test.go
@@ -0,0 +1,124 @@
+package main
+
+import (
+	"fmt"
+	"testing"
+	"time"
+)
+
+func newTestWatch() *pgWatchState {
+	return &pgWatchState{
+		registeredHosts: map[string]string{
+			"db.example.com:5432": "conn-1",
+			"[2001:db8::1]:5432":  "conn-6",
+		},
+		gatewayAddrs: map[string]bool{"127.0.0.1:6432": true},
+		lastReport:   map[string]time.Time{},
+	}
+}
+
+func TestClassifyObserved(t *testing.T) {
+	now := time.Now()
+
+	t.Run("registered peer is a direct connection", func(t *testing.T) {
+		w := newTestWatch()
+		kind, id, report := w.classifyObserved(pgObservedConn{PeerHost: "db.example.com", PeerPort: 5432}, now)
+		if !report || kind != "pg_direct_connection" || id != "conn-1" {
+			t.Errorf("got (%q,%q,%v)", kind, id, report)
+		}
+	})
+
+	t.Run("unknown peer on a pg port is unregistered", func(t *testing.T) {
+		w := newTestWatch()
+		kind, id, report := w.classifyObserved(pgObservedConn{PeerHost: "other.example.com", PeerPort: 6543}, now)
+		if !report || kind != "pg_unregistered_connection" || id != "" {
+			t.Errorf("got (%q,%q,%v)", kind, id, report)
+		}
+	})
+
+	t.Run("gateway listener is never reported", func(t *testing.T) {
+		w := newTestWatch()
+		if _, _, report := w.classifyObserved(pgObservedConn{PeerHost: "127.0.0.1", PeerPort: 6432}, now); report {
+			t.Error("the proxy itself must not be reported")
+		}
+	})
+
+	t.Run("non-pg port ignored", func(t *testing.T) {
+		w := newTestWatch()
+		if _, _, report := w.classifyObserved(pgObservedConn{PeerHost: "db.example.com", PeerPort: 443}, now); report {
+			t.Error("port 443 is not a pg port")
+		}
+	})
+
+	t.Run("debounce suppresses repeats inside the window", func(t *testing.T) {
+		w := newTestWatch()
+		c := pgObservedConn{PeerHost: "db.example.com", PeerPort: 5432}
+		if _, _, r := w.classifyObserved(c, now); !r {
+			t.Fatal("first must report")
+		}
+		if _, _, r := w.classifyObserved(c, now.Add(time.Minute)); r {
+			t.Error("repeat inside the window must be suppressed")
+		}
+		if _, _, r := w.classifyObserved(c, now.Add(pgWatchDebounce+time.Second)); !r {
+			t.Error("past the window it must report again")
+		}
+	})
+}
+
+func TestParseLsofConns(t *testing.T) {
+	out := "p123\nf12\nn127.0.0.1:54321->10.0.0.5:5432\nf13\nn[::1]:9999->[2001:db8::1]:6543\nnno-arrow-line\nn127.0.0.1:1->10.0.0.5:5432\n"
+	conns := parseLsofConns(out)
+	if len(conns) != 2 {
+		t.Fatalf("conns = %+v, want 2 (deduped)", conns)
+	}
+	if conns[0].PeerHost != "10.0.0.5" || conns[0].PeerPort != 5432 {
+		t.Errorf("first = %+v", conns[0])
+	}
+	if conns[1].PeerHost != "2001:db8::1" || conns[1].PeerPort != 6543 {
+		t.Errorf("second = %+v", conns[1])
+	}
+}
+
+func TestPgWatchHostsRoundTrip(t *testing.T) {
+	raw := "db.example.com:5432=conn-1,warehouse.example.com:6543=conn-2"
+	m := parsePgWatchHosts(raw)
+	if len(m) != 2 || m["db.example.com:5432"] != "conn-1" || m["warehouse.example.com:6543"] != "conn-2" {
+		t.Errorf("parsed = %v", m)
+	}
+	if parsePgWatchHosts("")["x"] != "" || len(parsePgWatchHosts("")) != 0 {
+		t.Error("empty input must parse to empty map")
+	}
+	if len(parsePgWatchHosts("garbage,also=,=x")) != 0 {
+		t.Errorf("malformed entries must be dropped: %v", parsePgWatchHosts("garbage,also=,=x"))
+	}
+}
+
+func TestExpandWatchHostsDNS(t *testing.T) {
+	hosts := map[string]string{
+		"db.example.com:5432": "conn-1",
+		"10.0.0.9:5432":       "conn-2", // IP literal: no lookup
+	}
+	var lookedUp []string
+	expanded := expandWatchHostsDNS(hosts, func(host string) ([]string, error) {
+		lookedUp = append(lookedUp, host)
+		return []string{"10.0.0.5", "2001:db8::1"}, nil
+	})
+	if len(lookedUp) != 1 || lookedUp[0] != "db.example.com" {
+		t.Errorf("lookups = %v, want only the hostname entry", lookedUp)
+	}
+	for _, key := range []string{"db.example.com:5432", "10.0.0.5:5432", "[2001:db8::1]:5432"} {
+		if expanded[key] != "conn-1" {
+			t.Errorf("missing expanded key %q: %v", key, expanded)
+		}
+	}
+	if expanded["10.0.0.9:5432"] != "conn-2" {
+		t.Error("IP-literal entry must survive unchanged")
+	}
+	// Lookup failure keeps the original entry.
+	failed := expandWatchHostsDNS(map[string]string{"gone.example.com:5432": "c"}, func(string) ([]string, error) {
+		return nil, fmt.Errorf("nxdomain")
+	})
+	if failed["gone.example.com:5432"] != "c" || len(failed) != 1 {
+		t.Errorf("failure case = %v", failed)
+	}
+}
diff --git a/cmd/onecli/skill_gateway_fallback.md b/cmd/onecli/skill_gateway_fallback.md
index 778a2e0..286f796 100644
--- a/cmd/onecli/skill_gateway_fallback.md
+++ b/cmd/onecli/skill_gateway_fallback.md
@@ -163,8 +163,55 @@ use the server's native OAuth flow or ask for API keys — use
 config fields. The same error-handling rules apply: if auth fails, show
 the `connect_url` so the user can connect the service in OneCLI.
 
+## Databases (Postgres)
+
+Registered databases are governed the same way as HTTP APIs: a governed
+route ALWAYS exists in your environment for every database you may reach.
+`onecli run` swaps database URLs already in your ENVIRONMENT for OneCLI
+proxy URLs (`postgresql://aoc_pg_...:x@<gateway>:<port>/<db>`) and
+additionally exports one `ONECLI_PG_<NAME>_URL` variable per registered
+database, indexed in `ONECLI_PG_CONNECTIONS` (JSON:
+`[{"label", "host", "env_var"}]`). The proxy holds the real credentials
+and logs every statement for the user.
+
+To connect to any postgres host:
+
+1. Check `ONECLI_PG_CONNECTIONS` for the host. If listed, connect via the
+   variable named in its `env_var` — ALWAYS, even if you were given
+   credentials directly (pasted or found in a file). The gateway injects
+   the real credentials; supplied ones are ignored on the proxy route.
+2. If the host is not listed, run `onecli pg url <host>` — it prints
+   `{url, label, host, expires_in_seconds}` when the database was
+   registered after your session started. Connect via that `url`.
+3. If it errors with "not_registered", do NOT connect directly — tell the
+   user to connect that database in the OneCLI dashboard, then retry.
+
+- **Always use the environment variable** (`$DATABASE_URL`, the mapped
+  `ONECLI_PG_*_URL`, and friends) to connect — via `psql`, an ORM, or any
+  client. You may change the database path segment of a mapped URL to
+  reach another database on the same server.
+- **Do NOT read connection strings out of `.env` or config files, and
+  do NOT `source .env` (or use dotenv-style overrides) before connecting.**
+  Sourcing the file overwrites the governed environment variable with a
+  stale, ungoverned URL. The variable is ALREADY set in your environment —
+  use it as-is. If the env var and a file disagree, the env var wins.
+- A username starting with `aoc_pg_` is expected — that is the proxy
+  session. Do not treat it as a misconfiguration and do not swap it for
+  credentials found elsewhere.
+- If a database connection fails with "session expired or unknown", run
+  `onecli pg url <host>` for a fresh governed URL (or tell the user to
+  re-run `onecli run`). If it fails with "unregistered database", tell
+  the user to connect that database in the OneCLI dashboard.
+
 ## Rules
 
+- **Never** connect to a database host directly when it appears in
+  `ONECLI_PG_CONNECTIONS` — use its mapped environment variable. Direct
+  connections bypass the user's governance and logging.
+- **Never** connect to a database using a URL read from a file when the
+  same variable exists in the environment. The environment holds the
+  governed proxy URL.
+
 - **Never** say "I don't have access to X" without first making the HTTP
   request through the proxy.
 - **Never** use browser extensions, gcloud, or manual auth flows. The
diff --git a/internal/api/pg.go b/internal/api/pg.go
new file mode 100644
index 0000000..d7538c8
--- /dev/null
+++ b/internal/api/pg.go
@@ -0,0 +1,136 @@
+package api
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+)
+
+// PgGatewayClient talks to the GATEWAY's pg-session surface (not the API
+// server): the same host:port that serves the HTTP proxy also mounts
+// /v1/pg/*. Auth is the agent's aoc_ token.
+type PgGatewayClient struct {
+	// BaseURL is the gateway origin, e.g. "http://127.0.0.1:10254".
+	BaseURL string
+	// AgentToken is the aoc_ bearer extracted from the proxy URL.
+	AgentToken string
+	HTTP       *http.Client
+}
+
+// PgConnection is one dashboard-registered postgres connection available
+// to the agent (host/port/label only — never credentials).
+type PgConnection struct {
+	ID       string  `json:"id"`
+	Label    *string `json:"label"`
+	Host     string  `json:"host"`
+	Port     uint16  `json:"port"`
+	Database *string `json:"database"`
+}
+
+// PgConnectionsResponse is GET /v1/pg/connections.
+type PgConnectionsResponse struct {
+	Connections []PgConnection `json:"connections"`
+	ListenPort  uint16         `json:"listen_port"`
+}
+
+// PgSession is the mint response from POST /v1/pg/sessions.
+type PgSession struct {
+	SessionID  string `json:"session_id"`
+	Token      string `json:"token"`
+	User       string `json:"user"`
+	ListenPort uint16 `json:"listen_port"`
+	TTLSeconds uint64 `json:"ttl_seconds"`
+	// Database is the dashboard-pinned database, when the connection sets
+	// one — used for placeholder URLs where no client URL supplies a path.
+	Database *string `json:"database"`
+}
+
+func (c *PgGatewayClient) httpClient() *http.Client {
+	if c.HTTP != nil {
+		return c.HTTP
+	}
+	return &http.Client{Timeout: 10 * time.Second}
+}
+
+func (c *PgGatewayClient) do(ctx context.Context, method, path string, body any, out any) error {
+	var reqBody io.Reader
+	if body != nil {
+		b, err := json.Marshal(body)
+		if err != nil {
+			return fmt.Errorf("encoding request: %w", err)
+		}
+		reqBody = bytes.NewReader(b)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, c.BaseURL+path, reqBody)
+	if err != nil {
+		return fmt.Errorf("building request: %w", err)
+	}
+	req.Header.Set("Authorization", "Bearer "+c.AgentToken)
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := c.httpClient().Do(req)
+	if err != nil {
+		return fmt.Errorf("calling gateway: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		data, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+		return fmt.Errorf("gateway %s %s: HTTP %d: %s", method, path, resp.StatusCode, string(data))
+	}
+	if out == nil {
+		return nil
+	}
+	if err := json.NewDecoder(resp.Body).Decode(out); err != nil {
+		return fmt.Errorf("decoding response: %w", err)
+	}
+	return nil
+}
+
+// ListPgConnections returns the registered postgres connections for the
+// authenticated agent, plus the gateway's pg listener port.
+func (c *PgGatewayClient) ListPgConnections(ctx context.Context) (*PgConnectionsResponse, error) {
+	var out PgConnectionsResponse
+	if err := c.do(ctx, http.MethodGet, "/v1/pg/connections", nil, &out); err != nil {
+		return nil, err
+	}
+	return &out, nil
+}
+
+// MintPgSession opens a proxy session for one registered connection.
+func (c *PgGatewayClient) MintPgSession(ctx context.Context, connectionID string) (*PgSession, error) {
+	var out PgSession
+	body := map[string]string{"connection_id": connectionID}
+	if err := c.do(ctx, http.MethodPost, "/v1/pg/sessions", body, &out); err != nil {
+		return nil, err
+	}
+	return &out, nil
+}
+
+// HeartbeatPgSession refreshes a session's TTL.
+func (c *PgGatewayClient) HeartbeatPgSession(ctx context.Context, sessionID string) error {
+	return c.do(ctx, http.MethodPost, "/v1/pg/sessions/"+sessionID+"/heartbeat", nil, nil)
+}
+
+// DeletePgSession ends a session.
+func (c *PgGatewayClient) DeletePgSession(ctx context.Context, sessionID string) error {
+	return c.do(ctx, http.MethodDelete, "/v1/pg/sessions/"+sessionID, nil, nil)
+}
+
+// ReportPgWatchEvent reports an observed direct/unregistered database
+// connection to the gateway (watcher sidecar detection, best-effort).
+func (c *PgGatewayClient) ReportPgWatchEvent(ctx context.Context, kind, peerHost string, peerPort uint16, connectionID string) error {
+	body := map[string]any{
+		"kind":      kind,
+		"peer_host": peerHost,
+		"peer_port": peerPort,
+	}
+	if connectionID != "" {
+		body["connection_id"] = connectionID
+	}
+	return c.do(ctx, http.MethodPost, "/v1/pg/events", body, nil)
+}