@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/build/executor/worker-database.js

@@ -0,0 +1,908 @@
+/**
+ * Disposable worker database lifecycle (BAPI-1479).
+ *
+ * The single owner of every lifecycle stage of an executor-owned worker
+ * database: provisioning (verify role + boundary, create, comment, migrate),
+ * teardown, orphan sweeping, and read-only inspection for doctor. All database
+ * work runs in the EXECUTOR process, never in a worker.
+ *
+ * The exported names and types are the contract `job-runner.ts`, `runner.ts`,
+ * and `doctor.ts` consume.
+ *
+ * Client posture: every executor-side statement is one `psql` subprocess with an
+ * explicit loopback target (`-h 127.0.0.1 -p 5432 -U bridge_epic_worker -d ...`),
+ * `-X -w`, and a REPLACING environment (`buildPsqlEnv`), so no ambient database
+ * URL, password, service, `.pgpass`, or `.psqlrc` is ever used. Every
+ * destructive statement passes through one guarded function that re-validates
+ * the worker database name immediately before it runs.
+ */
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { access, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { parseAlembicRevisions, resolveRepositoryAlembicCommand } from "../plane/alembic-head.js";
+import { CI_WORKER_ENV_CONSTANTS } from "./env.js";
+import { POSTGRES_IDENTIFIER_MAX_LENGTH, WORKER_DATABASE_HOST, WORKER_DATABASE_PORT, WORKER_DATABASE_PREFIX, WORKER_DATABASE_ROLE, buildWorkerDatabaseEnv, isValidWorkerDatabaseName, validateWorkerDatabaseName, } from "./worker-database-target.js";
+/** Runbook section every worker-database diagnostic points the host operator to. */
+export const WORKER_DATABASE_RUNBOOK_SECTION = "docs/claude/runbooks/local-db-safety.md#worker-databases";
+export const WORKER_DATABASE_PROVISION_BUDGET_MS = 120_000;
+export const WORKER_DATABASE_DROP_BUDGET_MS = 20_000;
+export const WORKER_DATABASE_SWEEP_BUDGET_MS = 60_000;
+/** Per-statement cap for one executor-side `psql` command (inside the stage budget). */
+export const WORKER_DATABASE_PSQL_STEP_TIMEOUT_MS = 15_000;
+/** `PGCONNECT_TIMEOUT` (seconds) for every executor-side `psql` command. */
+export const WORKER_DATABASE_CONNECT_TIMEOUT_SECONDS = "5";
+/**
+ * Directory (under the executor state directory) used as `HOME` for PostgreSQL
+ * client and Alembic subprocesses. It holds nothing; it does not even need to
+ * exist, because every credential and service-file lookup is pointed at a
+ * nonexistent file explicitly (see {@link buildPsqlEnv}).
+ */
+export const WORKER_DATABASE_CLIENT_HOME_DIR = "pg-client-home";
+/** Version of the ownership comment written on every worker database. */
+export const WORKER_DATABASE_METADATA_VERSION = 1;
+/** The maintenance database every executor-side statement connects to. */
+const MAINTENANCE_DATABASE = "postgres";
+/** The operational database the worker role must be refused on. */
+const OPERATIONAL_DATABASE = "bridgeapi";
+/** The Python harness prefix; counted for doctor only, never a lifecycle candidate. */
+const HARNESS_DATABASE_PREFIX = "conductor_harness_";
+/** Bounded subprocess output captured by the default runner, per stream. */
+const MAX_CAPTURED_OUTPUT_CHARS = 64 * 1024;
+/** Grace between SIGTERM and SIGKILL when the default runner stops a subprocess. */
+const KILL_GRACE_MS = 2_000;
+/** Upper bound on worker-prefixed databases one listing will consider. */
+const MAX_LISTED_DATABASES = 512;
+/** Comments longer than this are not ours and are not parsed. */
+const MAX_COMMENT_CHARS = 512;
+/** Sweep stops (incomplete) rather than start a drop with less time than this. */
+const MIN_SWEEP_DROP_MS = 1_000;
+const HOST_DIGEST_PATTERN = /^[0-9a-f]{64}$/;
+const RANDOM_SUFFIX_PATTERN = /^[0-9a-f]{4,16}$/;
+const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+const SAFE_JOB_ID_FOR_LOG = /^[A-Za-z0-9_-]{1,64}$/;
+const HEX_PATTERN = /^(?:[0-9a-f]{2})*$/;
+const UNAVAILABLE_CATEGORIES = new Set([
+    "client_missing",
+    "postgres_unavailable",
+    "role_missing",
+    "role_misconfigured",
+    "bridgeapi_reachable",
+    "boundary_unknown",
+    "alembic_missing",
+    "create_failed",
+    "migration_failed",
+    "timeout",
+    "cancelled",
+]);
+// ---------------------------------------------------------------------------
+// Production seams
+// ---------------------------------------------------------------------------
+/**
+ * Production `WorkerDatabaseDeps`. `env` is the EXECUTOR's environment; only its
+ * `PATH` is read (to locate `psql`). Nothing else from it ever reaches a child.
+ */
+export function createDefaultWorkerDatabaseDeps(overrides) {
+    const { stateDir, env, ...rest } = overrides;
+    return {
+        runProcess: runWorkerDatabaseProcess,
+        now: Date.now,
+        isPidAlive: defaultIsPidAlive,
+        isExecutable: defaultIsExecutable,
+        randomSuffix: () => randomBytes(4).toString("hex"),
+        platform: process.platform,
+        clientHome: path.join(stateDir, WORKER_DATABASE_CLIENT_HOME_DIR),
+        clientPath: typeof env.PATH === "string" && env.PATH.length > 0 ? env.PATH : "/usr/bin:/bin",
+        ...rest,
+    };
+}
+/**
+ * Create the executor-owned client home (0700) if it is missing. Optional: the
+ * client settings never depend on its contents. Never called by the read-only
+ * doctor inspection.
+ */
+export async function ensureWorkerDatabaseClientHome(clientHome) {
+    await mkdir(clientHome, { recursive: true, mode: 0o700 });
+}
+function defaultIsPidAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ESRCH")
+            return false;
+        if (code === "EPERM")
+            return true;
+        return null;
+    }
+}
+async function defaultIsExecutable(filePath) {
+    try {
+        await access(filePath, fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function appendBounded(current, chunk) {
+    if (current.length >= MAX_CAPTURED_OUTPUT_CHARS)
+        return current;
+    return (current + chunk.toString("utf8")).slice(0, MAX_CAPTURED_OUTPUT_CHARS);
+}
+/**
+ * The production process runner: argument array, `shell: false`, the request's
+ * env as the child's COMPLETE environment, bounded capture, and SIGTERM then
+ * SIGKILL on timeout or abort. It resolves only after the child has CLOSED, so a
+ * caller that awaits it never races a still-running subprocess.
+ */
+export function runWorkerDatabaseProcess(request) {
+    if (request.signal?.aborted) {
+        return Promise.resolve({
+            exitCode: null, stdout: "", stderr: "", timedOut: false, aborted: true, spawnFailed: false,
+        });
+    }
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let aborted = false;
+        let settled = false;
+        let killTimer;
+        let child;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeoutTimer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            request.signal?.removeEventListener("abort", onAbort);
+            resolve(result);
+        };
+        const stop = () => {
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                // already gone
+            }
+            if (!killTimer) {
+                killTimer = setTimeout(() => {
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch {
+                        // already gone
+                    }
+                }, KILL_GRACE_MS);
+            }
+        };
+        const onAbort = () => {
+            aborted = true;
+            stop();
+        };
+        try {
+            child = spawn(request.file, [...request.args], {
+                shell: false,
+                env: { ...request.env },
+                cwd: request.cwd,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch {
+            resolve({ exitCode: null, stdout: "", stderr: "", timedOut: false, aborted: false, spawnFailed: true });
+            return;
+        }
+        const timeoutTimer = setTimeout(() => {
+            timedOut = true;
+            stop();
+        }, Math.max(1, request.timeoutMs));
+        request.signal?.addEventListener("abort", onAbort, { once: true });
+        child.stdout?.on("data", (chunk) => {
+            stdout = appendBounded(stdout, chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr = appendBounded(stderr, chunk);
+        });
+        child.on("error", () => {
+            // A start failure (ENOENT, EACCES) never produces a pid and may not close.
+            if (child.pid === undefined) {
+                finish({ exitCode: null, stdout, stderr, timedOut, aborted, spawnFailed: true });
+            }
+        });
+        child.on("close", (code) => {
+            finish({
+                exitCode: timedOut || aborted ? null : code,
+                stdout,
+                stderr,
+                timedOut,
+                aborted,
+                spawnFailed: false,
+            });
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Client invocation
+// ---------------------------------------------------------------------------
+/**
+ * The COMPLETE environment for every executor-side `psql`. Nothing is copied from
+ * `process.env`, so an ambient `DATABASE_URL`, `PGPASSWORD`, `PGSERVICE`,
+ * `PGHOST`, or `PGUSER` can never reach the client. `PGPASSFILE`,
+ * `PGSERVICEFILE`, and `PGSYSCONFDIR` point at paths under the controlled home
+ * that do not exist, so no `.pgpass` or service file is ever read; `-X` skips
+ * `.psqlrc`. `LC_ALL`/`LC_MESSAGES=C` keep client-side messages in English.
+ */
+export function buildPsqlEnv(deps) {
+    return {
+        PATH: deps.clientPath,
+        HOME: deps.clientHome,
+        PGCONNECT_TIMEOUT: WORKER_DATABASE_CONNECT_TIMEOUT_SECONDS,
+        LC_ALL: "C",
+        LC_MESSAGES: "C",
+        PGPASSFILE: path.join(deps.clientHome, "nonexistent.pgpass"),
+        PGSERVICEFILE: path.join(deps.clientHome, "nonexistent.pg_service.conf"),
+        PGSYSCONFDIR: path.join(deps.clientHome, "nonexistent-sysconf"),
+    };
+}
+/** The `psql` argument array: explicit loopback target, no psqlrc, never prompt. */
+export function buildPsqlArgs(database, sql) {
+    return [
+        "-X",
+        "-w",
+        "-q",
+        "-A",
+        "-t",
+        "-v",
+        "ON_ERROR_STOP=1",
+        "-h",
+        WORKER_DATABASE_HOST,
+        "-p",
+        WORKER_DATABASE_PORT,
+        "-U",
+        WORKER_DATABASE_ROLE,
+        "-d",
+        database,
+        "-c",
+        sql,
+    ];
+}
+function runPsql(deps, database, sql, timeoutMs, signal) {
+    return deps.runProcess({
+        file: "psql",
+        args: buildPsqlArgs(database, sql),
+        env: buildPsqlEnv(deps),
+        timeoutMs: Math.max(1, timeoutMs),
+        signal,
+    });
+}
+/** Double-quote a VALIDATED worker database name. Throws for anything else. */
+function quoteWorkerIdentifier(name) {
+    return `"${validateWorkerDatabaseName(name)}"`;
+}
+/** Single-quoted SQL literal. Callers pass only validated content; quotes are still escaped. */
+function sqlLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+const succeeded = (r) => r.exitCode === 0 && !r.timedOut && !r.aborted && !r.spawnFailed;
+// ---------------------------------------------------------------------------
+// Role and boundary inspection (read-only)
+// ---------------------------------------------------------------------------
+/**
+ * One row about the worker role: login, createdb, the four forbidden attributes,
+ * and the number of roles it is a MEMBER of. Running it as the role against
+ * `postgres` is also the maintenance-connectivity proof.
+ */
+const ROLE_INSPECTION_SQL = "SELECT r.rolcanlogin, r.rolcreatedb, r.rolsuper, r.rolcreaterole, r.rolreplication, r.rolbypassrls, " +
+    "(SELECT count(*) FROM pg_auth_members m WHERE m.member = r.oid) " +
+    `FROM pg_roles r WHERE r.rolname = ${sqlLiteral(WORKER_DATABASE_ROLE)}`;
+function remaining(ctx) {
+    return ctx.deadline - ctx.deps.now();
+}
+function stepTimeout(ctx, cap) {
+    return Math.max(1, Math.min(cap, remaining(ctx)));
+}
+/** Map an interrupted subprocess to `cancelled`/`timeout`, or null when it was not interrupted. */
+function interruption(ctx, r) {
+    if (r.aborted || ctx.signal?.aborted)
+        return "cancelled";
+    if (r.timedOut && remaining(ctx) <= 0)
+        return "timeout";
+    return null;
+}
+/**
+ * Classify a failed connection to the MAINTENANCE database. Only the client's
+ * own fixed messages and the server's startup messages are matched; nothing here
+ * is ever logged.
+ */
+function classifyMaintenanceFailure(r) {
+    if (r.spawnFailed)
+        return "client_missing";
+    const text = r.stderr;
+    if (new RegExp(`role "${WORKER_DATABASE_ROLE}" does not exist`).test(text))
+        return "role_missing";
+    if (/password authentication failed|no password supplied|authentication failed|pg_hba\.conf|permission denied for database "postgres"|is not permitted to log in/.test(text)) {
+        return "role_misconfigured";
+    }
+    return "postgres_unavailable";
+}
+/**
+ * Parse the role row. Membership rule (conservative): ANY membership at all is a
+ * misconfiguration. The worker role needs none, and enumerating which roles
+ * elevate (directly, via SET ROLE, via INHERIT chains, or through predefined
+ * roles such as `pg_read_server_files`, `pg_write_server_files`,
+ * `pg_execute_server_program`, `pg_signal_backend`) is exactly the kind of list
+ * that silently goes stale across PostgreSQL versions.
+ */
+export function evaluateWorkerRoleRow(stdout) {
+    const lines = stdout.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0);
+    if (lines.length === 0)
+        return { kind: "unsafe", category: "role_missing" };
+    if (lines.length !== 1)
+        return { kind: "unknown", category: "postgres_unavailable" };
+    const fields = lines[0].split("|");
+    if (fields.length !== 7)
+        return { kind: "unknown", category: "postgres_unavailable" };
+    const flags = fields.slice(0, 6);
+    if (!flags.every((f) => f === "t" || f === "f"))
+        return { kind: "unknown", category: "postgres_unavailable" };
+    if (!/^\d+$/.test(fields[6]))
+        return { kind: "unknown", category: "postgres_unavailable" };
+    const [login, createdb, superuser, createrole, replication, bypassrls] = flags.map((f) => f === "t");
+    const memberships = Number(fields[6]);
+    if (!login || !createdb || superuser || createrole || replication || bypassrls || memberships !== 0) {
+        return { kind: "unsafe", category: "role_misconfigured" };
+    }
+    return { kind: "ok" };
+}
+async function checkWorkerRole(ctx) {
+    const r = await runPsql(ctx.deps, MAINTENANCE_DATABASE, ROLE_INSPECTION_SQL, stepTimeout(ctx, WORKER_DATABASE_PSQL_STEP_TIMEOUT_MS), ctx.signal);
+    const interrupted = interruption(ctx, r);
+    if (interrupted)
+        return { kind: "unknown", category: interrupted };
+    if (r.timedOut)
+        return { kind: "unknown", category: "postgres_unavailable" };
+    if (!succeeded(r)) {
+        const category = classifyMaintenanceFailure(r);
+        return category === "role_missing" || category === "role_misconfigured"
+            ? { kind: "unsafe", category }
+            : { kind: "unknown", category };
+    }
+    return evaluateWorkerRoleRow(r.stdout);
+}
+/**
+ * The recognized `bridgeapi` authorization denials, as `psql` prints them with
+ * `LC_ALL=C`. A connection-startup failure carries no SQLSTATE in psql's output
+ * (VERBOSITY does not apply before a session exists), so the message text is the
+ * only representation available; the English text assumes the server's default
+ * `lc_messages`. A localized server simply fails to match, which classifies as
+ * `boundary_unknown` — the safe direction.
+ *  - 42501 insufficient_privilege: `FATAL:  permission denied for database "bridgeapi"`
+ *  - 28000 an explicit pg_hba `reject` naming this host, role, AND `bridgeapi`.
+ */
+const BRIDGEAPI_DENIAL_PATTERNS = [
+    /FATAL:\s+permission denied for database "bridgeapi"(?=$|[\s.])/m,
+    new RegExp(`FATAL:\\s+pg_hba\\.conf rejects connection for host "127\\.0\\.0\\.1", user "${WORKER_DATABASE_ROLE}", database "bridgeapi"(?=$|[\\s,.])`, "m"),
+];
+/** Classify one `bridgeapi` probe. Only a recognized denial is proof of safety. */
+export function classifyBridgeapiProbe(r) {
+    if (r.spawnFailed || r.timedOut || r.aborted)
+        return "unknown";
+    if (r.exitCode === 0)
+        return "reachable";
+    if (r.exitCode === null)
+        return "unknown";
+    return BRIDGEAPI_DENIAL_PATTERNS.some((p) => p.test(r.stderr)) ? "denied" : "unknown";
+}
+async function probeBridgeapi(ctx) {
+    const r = await runPsql(ctx.deps, OPERATIONAL_DATABASE, "SELECT 1", stepTimeout(ctx, WORKER_DATABASE_PSQL_STEP_TIMEOUT_MS), ctx.signal);
+    const interrupted = interruption(ctx, r);
+    if (interrupted)
+        return { kind: "unknown", category: interrupted };
+    const verdict = classifyBridgeapiProbe(r);
+    if (verdict === "denied")
+        return { kind: "ok" };
+    if (verdict === "reachable")
+        return { kind: "unsafe", category: "bridgeapi_reachable" };
+    return { kind: "unknown", category: "boundary_unknown" };
+}
+// ---------------------------------------------------------------------------
+// Names and ownership metadata
+// ---------------------------------------------------------------------------
+/** Lowercase `[a-z0-9_]` form of a job id, or `job` when nothing survives. */
+export function sanitizeJobIdForDatabaseName(jobId, maxLength) {
+    const cleaned = String(jobId).toLowerCase().replace(/[^a-z0-9_]/g, "_").slice(0, Math.max(0, maxLength));
+    return cleaned.length > 0 ? cleaned : "job".slice(0, Math.max(1, maxLength));
+}
+/**
+ * `bridge_worker_job_<sanitized job id>_<random hex>`, at most 63 characters, or
+ * null when the random suffix is not lowercase hex.
+ */
+export function buildWorkerDatabaseName(jobId, suffix) {
+    if (!RANDOM_SUFFIX_PATTERN.test(suffix))
+        return null;
+    const budget = POSTGRES_IDENTIFIER_MAX_LENGTH - WORKER_DATABASE_PREFIX.length - 1 - suffix.length;
+    if (budget < 1)
+        return null;
+    const name = `${WORKER_DATABASE_PREFIX}${sanitizeJobIdForDatabaseName(jobId, budget)}_${suffix}`;
+    return isValidWorkerDatabaseName(name) ? name : null;
+}
+const isPositivePid = (v) => typeof v === "number" && Number.isSafeInteger(v) && v > 0;
+/** The exact comment text: `{"v":1,"executorPid":<int>,"hostDigest":"<sha256 hex>","createdAt":"<ISO>"}`. */
+export function encodeWorkerDatabaseMetadata(metadata) {
+    return JSON.stringify({
+        v: metadata.v,
+        executorPid: metadata.executorPid,
+        hostDigest: metadata.hostDigest,
+        createdAt: metadata.createdAt,
+    });
+}
+/**
+ * Strict parser: exactly the four keys, version 1, a positive safe-integer pid, a
+ * 64-character lowercase hex host digest (the `hostIdentityDigest` shape), and a
+ * canonical ISO-8601 UTC timestamp. Anything else is null — never a guess.
+ */
+export function parseWorkerDatabaseMetadata(comment) {
+    if (typeof comment !== "string" || comment.length === 0 || comment.length > MAX_COMMENT_CHARS)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(comment);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const record = value;
+    const keys = Object.keys(record).sort();
+    if (keys.join(",") !== "createdAt,executorPid,hostDigest,v")
+        return null;
+    if (record.v !== WORKER_DATABASE_METADATA_VERSION)
+        return null;
+    if (!isPositivePid(record.executorPid))
+        return null;
+    if (typeof record.hostDigest !== "string" || !HOST_DIGEST_PATTERN.test(record.hostDigest))
+        return null;
+    const createdAt = record.createdAt;
+    if (typeof createdAt !== "string" || !ISO_TIMESTAMP_PATTERN.test(createdAt))
+        return null;
+    const parsed = new Date(createdAt);
+    if (Number.isNaN(parsed.getTime()) || parsed.toISOString() !== createdAt)
+        return null;
+    return { v: 1, executorPid: record.executorPid, hostDigest: record.hostDigest, createdAt };
+}
+// ---------------------------------------------------------------------------
+// Inventory (read-only)
+// ---------------------------------------------------------------------------
+function exactPrefixPredicate(prefix) {
+    // `left(...) = '...'` is an exact comparison; an unescaped LIKE would treat
+    // every `_` in the prefix as a wildcard.
+    return `left(datname::text, ${prefix.length}) = ${sqlLiteral(prefix)}`;
+}
+/** Name and comment, both hex-encoded so no separator or newline in either can split a row. */
+const LISTING_COLUMNS = "encode(convert_to(datname::text, 'UTF8'), 'hex'), " +
+    "CASE WHEN shobj_description(oid, 'pg_database') IS NULL THEN 'f' ELSE 't' END, " +
+    "encode(convert_to(coalesce(shobj_description(oid, 'pg_database'), ''), 'UTF8'), 'hex')";
+const WORKER_LISTING_SQL = `SELECT ${LISTING_COLUMNS} FROM pg_database WHERE ${exactPrefixPredicate(WORKER_DATABASE_PREFIX)} ` +
+    `ORDER BY datname LIMIT ${MAX_LISTED_DATABASES}`;
+const HARNESS_COUNT_SQL = `SELECT count(*) FROM pg_database WHERE ${exactPrefixPredicate(HARNESS_DATABASE_PREFIX)}`;
+function singleDatabaseListingSql(name) {
+    return `SELECT ${LISTING_COLUMNS} FROM pg_database WHERE datname = ${sqlLiteral(validateWorkerDatabaseName(name))}`;
+}
+/**
+ * Parse listing rows. Rows whose name is not a VALID worker database name (for
+ * example a hand-made `bridge_worker_job_X`) are skipped: executor-generated
+ * names are always valid, so such a database is not ours and is never a
+ * candidate. Returns null on any unparseable row.
+ */
+function parseListing(stdout) {
+    const rows = [];
+    for (const raw of stdout.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        const fields = line.split("|");
+        if (fields.length !== 3)
+            return null;
+        const [nameHex, hasComment, commentHex] = fields;
+        if (!HEX_PATTERN.test(nameHex) || !HEX_PATTERN.test(commentHex))
+            return null;
+        if (hasComment !== "t" && hasComment !== "f")
+            return null;
+        const name = Buffer.from(nameHex, "hex").toString("utf8");
+        if (!isValidWorkerDatabaseName(name))
+            continue;
+        rows.push({ name, comment: hasComment === "t" ? Buffer.from(commentHex, "hex").toString("utf8") : null });
+    }
+    return rows;
+}
+function classifyOwnership(entry, hostDigest) {
+    if (entry.comment === null || entry.comment.length === 0)
+        return { kind: "retain", reason: "no_comment" };
+    const metadata = parseWorkerDatabaseMetadata(entry.comment);
+    if (!metadata)
+        return { kind: "retain", reason: "malformed_comment" };
+    if (metadata.hostDigest !== hostDigest)
+        return { kind: "retain", reason: "foreign_host" };
+    return { kind: "same_host", metadata };
+}
+async function listWorkerDatabases(ctx) {
+    const r = await runPsql(ctx.deps, MAINTENANCE_DATABASE, WORKER_LISTING_SQL, stepTimeout(ctx, WORKER_DATABASE_PSQL_STEP_TIMEOUT_MS), ctx.signal);
+    const interrupted = interruption(ctx, r);
+    if (interrupted)
+        return { kind: "unavailable", category: interrupted };
+    if (!succeeded(r)) {
+        return { kind: "unavailable", category: r.timedOut ? "postgres_unavailable" : classifyMaintenanceFailure(r) };
+    }
+    const rows = parseListing(r.stdout);
+    return rows ? { kind: "ok", rows } : { kind: "unavailable", category: "postgres_unavailable" };
+}
+function dropFailureCategory(r, signal) {
+    if (r.aborted || signal?.aborted)
+        return "cancelled";
+    if (r.timedOut)
+        return "timeout";
+    if (r.spawnFailed)
+        return "postgres_unavailable";
+    // psql exits 2 when the connection itself failed.
+    if (r.exitCode === 2)
+        return "postgres_unavailable";
+    return "drop_failed";
+}
+/**
+ * Every destructive statement in this module goes through here: normal
+ * teardown, provisioning rollback, comment-failure rollback, and orphan sweep.
+ * The throwing name guard runs immediately before EACH statement. Sessions are
+ * terminated only where `datname` exactly equals the validated name, excluding
+ * this connection and the server's own (superuser) workers, which a
+ * least-privilege role may not signal (see `conductor_harness/db.py`). No retry.
+ */
+async function guardedDropWorkerDatabase(name, deps, budgetMs, signal) {
+    const validated = validateWorkerDatabaseName(name);
+    const deadline = deps.now() + Math.max(1, budgetMs);
+    const timeout = () => Math.max(1, deadline - deps.now());
+    const terminateSql = "SELECT count(pg_terminate_backend(pid)) FROM pg_stat_activity " +
+        `WHERE datname = ${sqlLiteral(validateWorkerDatabaseName(validated))} ` +
+        "AND pid <> pg_backend_pid() AND backend_type = 'client backend'";
+    const terminated = await runPsql(deps, MAINTENANCE_DATABASE, terminateSql, timeout(), signal);
+    if (!succeeded(terminated))
+        return { kind: "failed", category: dropFailureCategory(terminated, signal) };
+    const dropSql = `DROP DATABASE IF EXISTS ${quoteWorkerIdentifier(validated)}`;
+    const dropped = await runPsql(deps, MAINTENANCE_DATABASE, dropSql, timeout(), signal);
+    if (!succeeded(dropped))
+        return { kind: "failed", category: dropFailureCategory(dropped, signal) };
+    return { kind: "dropped" };
+}
+// ---------------------------------------------------------------------------
+// Provisioning
+// ---------------------------------------------------------------------------
+/** An Alembic step's timeout is the remaining stage budget, so a timeout is a budget timeout. */
+function alembicFailureCategory(ctx, r) {
+    return interruption(ctx, r) ?? (r.timedOut ? "timeout" : "migration_failed");
+}
+function buildAlembicEnv(name, deps) {
+    return {
+        ...CI_WORKER_ENV_CONSTANTS,
+        ...buildWorkerDatabaseEnv({ name }),
+        PATH: deps.clientPath,
+        HOME: deps.clientHome,
+    };
+}
+/**
+ * Verify the worker role and the `bridgeapi` boundary, create and comment a
+ * per-job database, and migrate it to the job worktree's head with the operator
+ * checkout's Alembic. Every failure after creation drops what was created; a
+ * failed rollback reports `retainedName`. Emits exactly one bounded line through
+ * `deps.diagnostic` on an unavailable result (plus the drop-failed line when a
+ * database is retained), so callers must not log the same line again.
+ *
+ * Budget: rollback time is RESERVED out of `budgetMs`, so a timed-out stage still
+ * leaves room to clean up. Rollback deliberately runs WITHOUT `signal`: a
+ * cancelled provisioning must still remove what it created. Every subprocess is
+ * awaited (the runner resolves only after exit) before rollback starts.
+ */
+export async function provisionWorkerDatabase(options, deps) {
+    const budgetMs = Math.max(1, options.budgetMs ?? WORKER_DATABASE_PROVISION_BUDGET_MS);
+    const start = deps.now();
+    const reserve = Math.min(WORKER_DATABASE_DROP_BUDGET_MS, Math.floor(budgetMs / 4));
+    const finalDeadline = start + budgetMs;
+    const ctx = { deps, signal: options.signal, deadline: finalDeadline - reserve };
+    const unavailable = (category, retainedName) => {
+        deps.diagnostic?.(formatWorkerDatabaseUnavailableLine(options.jobId, category));
+        if (retainedName) {
+            deps.diagnostic?.(formatWorkerDatabaseDropFailedLine(options.jobId, retainedName));
+            return { kind: "unavailable", category, retainedName };
+        }
+        return { kind: "unavailable", category };
+    };
+    const rollback = async (name, category) => {
+        // A small floor keeps a rollback possible even when a runner overshot its timeout.
+        const rollbackBudget = Math.max(Math.min(reserve, 5_000), finalDeadline - deps.now(), 1);
+        const outcome = await guardedDropWorkerDatabase(name, deps, rollbackBudget);
+        return outcome.kind === "dropped" ? unavailable(category) : unavailable(category, name);
+    };
+    if (options.signal?.aborted)
+        return unavailable("cancelled");
+    if (!isPositivePid(options.executorPid) || !HOST_DIGEST_PATTERN.test(options.hostDigest)) {
+        return unavailable("create_failed");
+    }
+    // (a) role attributes and memberships — also the maintenance-connect proof.
+    const role = await checkWorkerRole(ctx);
+    if (role.kind !== "ok")
+        return unavailable(role.category);
+    // (b) the operational boundary.
+    const boundary = await probeBridgeapi(ctx);
+    if (boundary.kind !== "ok")
+        return unavailable(boundary.category);
+    // Alembic must exist before anything is created.
+    const alembic = resolveRepositoryAlembicCommand(options.operatorRepositoryRoot, deps.platform);
+    let alembicPresent = false;
+    try {
+        alembicPresent = await deps.isExecutable(alembic);
+    }
+    catch {
+        alembicPresent = false;
+    }
+    if (!alembicPresent)
+        return unavailable("alembic_missing");
+    // (c) create, then comment immediately.
+    const name = buildWorkerDatabaseName(options.jobId, deps.randomSuffix());
+    if (!name)
+        return unavailable("create_failed");
+    if (remaining(ctx) <= 0)
+        return unavailable("timeout");
+    const created = await runPsql(deps, MAINTENANCE_DATABASE, `CREATE DATABASE ${quoteWorkerIdentifier(name)}`, stepTimeout(ctx, WORKER_DATABASE_PSQL_STEP_TIMEOUT_MS), options.signal);
+    if (!succeeded(created)) {
+        const interrupted = interruption(ctx, created);
+        // exit 1 = the server rejected the statement (ON_ERROR_STOP): nothing exists.
+        // Anything else leaves creation uncertain, so the unique name is dropped.
+        if (created.exitCode === 1 && !interrupted)
+            return unavailable("create_failed");
+        if (created.spawnFailed)
+            return unavailable("client_missing");
+        return rollback(name, interrupted ?? "create_failed");
+    }
+    const metadata = encodeWorkerDatabaseMetadata({
+        v: 1,
+        executorPid: options.executorPid,
+        hostDigest: options.hostDigest,
+        createdAt: new Date(deps.now()).toISOString(),
+    });
+    const commented = await runPsql(deps, MAINTENANCE_DATABASE, `COMMENT ON DATABASE ${quoteWorkerIdentifier(name)} IS ${sqlLiteral(metadata)}`, stepTimeout(ctx, WORKER_DATABASE_PSQL_STEP_TIMEOUT_MS), options.signal);
+    if (!succeeded(commented))
+        return rollback(name, interruption(ctx, commented) ?? "create_failed");
+    // (d) migrate with the job worktree's migrations, then verify the head.
+    const env = buildAlembicEnv(name, deps);
+    const runAlembic = (args) => deps.runProcess({
+        file: alembic,
+        args,
+        cwd: options.worktreePath,
+        env,
+        timeoutMs: stepTimeout(ctx, Number.MAX_SAFE_INTEGER),
+        signal: options.signal,
+    });
+    if (remaining(ctx) <= 0)
+        return rollback(name, "timeout");
+    const upgraded = await runAlembic(["-c", "alembic.ini", "upgrade", "head"]);
+    if (!succeeded(upgraded))
+        return rollback(name, alembicFailureCategory(ctx, upgraded));
+    const outputs = [];
+    for (const args of [["-c", "alembic.ini", "heads"], ["-c", "alembic.ini", "current"]]) {
+        if (remaining(ctx) <= 0)
+            return rollback(name, "timeout");
+        const r = await runAlembic(args);
+        if (!succeeded(r))
+            return rollback(name, alembicFailureCategory(ctx, r));
+        outputs.push(r.stdout);
+    }
+    const heads = parseAlembicRevisions(outputs[0]);
+    const current = parseAlembicRevisions(outputs[1]);
+    if (!heads || heads.length !== 1 || !current || current.length !== 1 || heads[0] !== current[0]) {
+        return rollback(name, "migration_failed");
+    }
+    if (options.signal?.aborted)
+        return rollback(name, "cancelled");
+    return { kind: "provisioned", target: { name } };
+}
+// ---------------------------------------------------------------------------
+// Teardown
+// ---------------------------------------------------------------------------
+/**
+ * Drop one validated worker database: terminate its client sessions, then drop
+ * it. Throws {@link WorkerDatabaseNameError} for any name that is not a worker
+ * database name, before any subprocess. Bounded, never retried; a failure leaves
+ * the ownership comment in place for the next sweep or the operator, and emits
+ * one bounded line through `deps.diagnostic`.
+ */
+export async function dropWorkerDatabase(target, deps, options = {}) {
+    const name = validateWorkerDatabaseName(target?.name);
+    const outcome = await guardedDropWorkerDatabase(name, deps, options.budgetMs ?? WORKER_DATABASE_DROP_BUDGET_MS, options.signal);
+    if (outcome.kind === "dropped")
+        return { kind: "dropped" };
+    deps.diagnostic?.(formatWorkerDatabaseDropFailedLine(options.jobId ?? "unknown", name));
+    return { kind: "failed", category: outcome.category };
+}
+// ---------------------------------------------------------------------------
+// Orphan sweep
+// ---------------------------------------------------------------------------
+/**
+ * Drop worker databases whose recorded owner is a DEAD executor on THIS host.
+ * Never uses age. Retains everything it cannot prove: live or unknown owners,
+ * foreign hosts, missing or malformed comments, and any record whose comment
+ * changed between listing and the re-read immediately before the drop. Emits no
+ * diagnostics: an unavailable sweep is routine on a host without the role.
+ */
+export async function sweepOrphanedWorkerDatabases(options, deps) {
+    const ctx = {
+        deps,
+        signal: options.signal,
+        deadline: deps.now() + Math.max(1, options.budgetMs ?? WORKER_DATABASE_SWEEP_BUDGET_MS),
+    };
+    if (options.signal?.aborted)
+        return { kind: "unavailable", category: "cancelled" };
+    const listing = await listWorkerDatabases(ctx);
+    if (listing.kind !== "ok")
+        return { kind: "unavailable", category: listing.category };
+    const dropped = [];
+    const retained = [];
+    let incomplete = false;
+    for (const entry of listing.rows) {
+        const ownership = classifyOwnership(entry, options.hostDigest);
+        if (ownership.kind === "retain") {
+            retained.push({ name: entry.name, reason: ownership.reason });
+            continue;
+        }
+        const pid = ownership.metadata.executorPid;
+        if (pid === options.executorPid) {
+            retained.push({ name: entry.name, reason: "owner_alive" });
+            continue;
+        }
+        const alive = deps.isPidAlive(pid);
+        if (alive === true) {
+            retained.push({ name: entry.name, reason: "owner_alive" });
+            continue;
+        }
+        if (alive !== false) {
+            retained.push({ name: entry.name, reason: "owner_unknown" });
+            continue;
+        }
+        if (options.signal?.aborted || remaining(ctx) < MIN_SWEEP_DROP_MS) {
+            incomplete = true;
+            break;
+        }
+        // Re-read the comment immediately before the destructive step.
+        const reread = await runPsql(deps, MAINTENANCE_DATABASE, singleDatabaseListingSql(entry.name), stepTimeout(ctx, WORKER_DATABASE_PSQL_STEP_TIMEOUT_MS), options.signal);
+        if (!succeeded(reread)) {
+            incomplete = true;
+            break;
+        }
+        const current = parseListing(reread.stdout);
+        if (!current || current.length !== 1 || current[0].name !== entry.name || current[0].comment !== entry.comment) {
+            retained.push({ name: entry.name, reason: "ownership_changed" });
+            continue;
+        }
+        if (options.signal?.aborted || remaining(ctx) < MIN_SWEEP_DROP_MS) {
+            incomplete = true;
+            break;
+        }
+        const outcome = await guardedDropWorkerDatabase(entry.name, deps, Math.min(WORKER_DATABASE_DROP_BUDGET_MS, remaining(ctx)), options.signal);
+        if (outcome.kind === "dropped") {
+            dropped.push(entry.name);
+        }
+        else {
+            retained.push({ name: entry.name, reason: "drop_failed" });
+            if (outcome.category !== "drop_failed") {
+                incomplete = true;
+                break;
+            }
+        }
+    }
+    return { kind: incomplete ? "incomplete" : "completed", dropped, retained };
+}
+// ---------------------------------------------------------------------------
+// Read-only inspection for doctor
+// ---------------------------------------------------------------------------
+/**
+ * Doctor's worker-database rows. STRICTLY read-only: only SELECT statements and a
+ * `bridgeapi` connection attempt — no CREATE, DROP, COMMENT, or session
+ * termination, and no directory creation.
+ */
+export async function inspectWorkerDatabaseReadiness(options, deps) {
+    const ctx = {
+        deps,
+        signal: options.signal,
+        deadline: deps.now() + Math.max(1, options.budgetMs ?? WORKER_DATABASE_SWEEP_BUDGET_MS),
+    };
+    const roleOutcome = await checkWorkerRole(ctx);
+    const role = roleOutcome.kind === "ok"
+        ? { state: "healthy" }
+        : { state: roleOutcome.kind === "unsafe" ? "unsafe" : "unknown", category: roleOutcome.category };
+    // The boundary probe is meaningful only once the maintenance connection worked
+    // (a role row came back, healthy or not).
+    const maintenanceConnected = roleOutcome.kind === "ok" || (roleOutcome.kind === "unsafe" && roleOutcome.category === "role_misconfigured");
+    let boundary;
+    if (!maintenanceConnected) {
+        boundary = { state: "unknown", category: "boundary_unknown" };
+    }
+    else {
+        const b = await probeBridgeapi(ctx);
+        boundary =
+            b.kind === "ok"
+                ? { state: "healthy" }
+                : { state: b.kind === "unsafe" ? "unsafe" : "unknown", category: b.category };
+    }
+    let alembic;
+    try {
+        const exists = await deps.isExecutable(resolveRepositoryAlembicCommand(options.operatorRepositoryRoot, deps.platform));
+        alembic = { state: exists ? "healthy" : "unsafe" };
+    }
+    catch {
+        alembic = { state: "unknown" };
+    }
+    let inventory = { state: "unknown" };
+    const listing = await listWorkerDatabases(ctx);
+    if (listing.kind === "ok") {
+        const harness = await runPsql(deps, MAINTENANCE_DATABASE, HARNESS_COUNT_SQL, stepTimeout(ctx, WORKER_DATABASE_PSQL_STEP_TIMEOUT_MS), options.signal);
+        const harnessText = harness.stdout.trim();
+        if (succeeded(harness) && /^\d+$/.test(harnessText)) {
+            const value = {
+                active: [],
+                leftovers: [],
+                unverifiable: [],
+                harnessCount: Number(harnessText),
+            };
+            for (const entry of listing.rows) {
+                const ownership = classifyOwnership(entry, options.hostDigest);
+                if (ownership.kind === "retain") {
+                    value.unverifiable.push({ name: entry.name, reason: ownership.reason });
+                    continue;
+                }
+                const alive = deps.isPidAlive(ownership.metadata.executorPid);
+                if (alive === true)
+                    value.active.push(entry.name);
+                else if (alive === false)
+                    value.leftovers.push(entry.name);
+                else
+                    value.unverifiable.push({ name: entry.name, reason: "owner_unknown" });
+            }
+            inventory = { state: "known", value };
+        }
+    }
+    return { role, boundary, alembic, inventory };
+}
+// ---------------------------------------------------------------------------
+// Diagnostics
+// ---------------------------------------------------------------------------
+function safeJobIdForLog(jobId) {
+    const s = String(jobId);
+    return SAFE_JOB_ID_FOR_LOG.test(s) ? s : "unknown";
+}
+/**
+ * The ONE bounded, non-fatal job-log line for a provisioning failure. Names the
+ * host operator and the runbook section; `bridgeapi_reachable` gets distinct
+ * wording because it is an unsafe boundary, not a missing prerequisite.
+ */
+export function formatWorkerDatabaseUnavailableLine(jobId, category) {
+    const id = safeJobIdForLog(jobId);
+    if (category === "bridgeapi_reachable") {
+        return (`[executor] job ${id}: UNSAFE worker database boundary: the worker role can connect to bridgeapi; ` +
+            `no worker database was created; continuing with the sentinel database — host operator: see ${WORKER_DATABASE_RUNBOOK_SECTION}`);
+    }
+    const safeCategory = UNAVAILABLE_CATEGORIES.has(category) ? category : "unknown";
+    return (`[executor] job ${id}: worker database unavailable (non-fatal): ${safeCategory}; ` +
+        `continuing with the sentinel database — host operator: see ${WORKER_DATABASE_RUNBOOK_SECTION}`);
+}
+/** The ONE bounded, non-fatal line for a teardown failure. */
+export function formatWorkerDatabaseDropFailedLine(jobId, name) {
+    const id = safeJobIdForLog(jobId);
+    const subject = isValidWorkerDatabaseName(name) ? `worker database ${name}` : "a worker database";
+    return (`[executor] job ${id}: ${subject} could not be dropped (non-fatal); its ownership comment is kept ` +
+        `for review — host operator: see ${WORKER_DATABASE_RUNBOOK_SECTION}`);
+}