@everystack/cli 0.4.27 → 0.4.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.27",
+  "version": "0.4.29",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -45,6 +45,10 @@
       "types": "./src/refresh.ts",
       "default": "./src/refresh.ts"
     },
+    "./backfill": {
+      "types": "./src/backfill.ts",
+      "default": "./src/backfill.ts"
+    },
     "./audit/source": {
       "types": "./src/cli/audit-source-api.ts",
       "default": "./src/cli/audit-source-api.ts"

package/src/backfill.ts

@@ -0,0 +1,23 @@
+/**
+ * @everystack/cli/backfill — the one-shot data-job core, for the ops-Lambda lane.
+ *
+ * db:backfill runs committed, content-addressed *.sql jobs against a database and records each
+ * in everystack.backfill_log. It was direct-connection only; this barrel lets the ops `db:backfill`
+ * action (stage-write-lanes brick 4) load the same core and run it on the operator connection, so
+ * `db:backfill --stage --apply` needs no raw admin URL on the operator's machine. The CLI ships the
+ * *.sql files; this plans (by content identity), executes pending jobs in order, and records them.
+ */
+
+export {
+  planBackfills,
+  readBackfillLog,
+  executeBackfills,
+  markBackfillApplied,
+} from './cli/backfill.js';
+export type {
+  BackfillPlan,
+  BackfillRecord,
+  BackfillRunOptions,
+  BackfillRunResult,
+} from './cli/backfill.js';
+export type { SourceFile } from './cli/derived-source.js';

package/src/cli/backup.ts

@@ -49,6 +49,28 @@ export function keyForId(id: string): string | null {
   return ref ? `${backupPrefix(ref.stage)}/${ref.name}.dump.gz` : null;
 }
 
+// --- Artifact key scheme (schema-scoped exports for the hot-swap) — mirrors server/backup.ts ----
+// A backup is the whole database; an ARTIFACT is one schema, content-addressed, carrying the schema
+// fingerprint it was built against. Separate prefix so the two never collide. db:swap --stage --direct
+// resolves an artifact id (from db:export --stage) to its S3 key, presigns, and downloads it.
+
+/** The S3 prefix a schema's artifacts live under (admin-only, encrypted). */
+export function artifactPrefix(schema: string, stage: string): string {
+  return `artifacts/${schema}/${stage}`;
+}
+
+/** Parse a schema-qualified artifact id `stats/dev/20260716T120000Z-ab12cd`, or null when malformed. */
+export function parseArtifactRef(id: string): { schema: string; stage: string; name: string } | null {
+  const m = id.match(/^([A-Za-z0-9_]+)\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_.:-]+)$/);
+  return m ? { schema: m[1], stage: m[2], name: m[3] } : null;
+}
+
+/** The S3 dump key for an artifact id (inverse of the server's artifactId), or null when malformed. */
+export function keyForArtifactId(id: string): string | null {
+  const ref = parseArtifactRef(id);
+  return ref ? `${artifactPrefix(ref.schema, ref.stage)}/${ref.name}.dump.gz` : null;
+}
+
 /**
  * Format a Date as the UTC `YYYYMMDDTHHMMSSZ` stamp used in backup keys/ids. The clock is the
  * caller's — pass `new Date()` at the call site so this stays pure and unit-testable.

package/src/cli/commands/db-apply.ts

@@ -35,6 +35,9 @@ import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '
 import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction, lambdaQueryRunner } from '../aws.js';
 import { executeApplyPlan, type ApplyPlanResult } from '../apply-execute.js';
+import { estimateOpsRuntimeFit } from '../ops-fit.js';
+import { resolveOperatorUrlViaStage } from '../direct-venue.js';
+import { withMutationLease, MutationLeaseError } from '../mutation-lease.js';
 import { pgDumpPreflightError } from './db-backup.js';
 import { step, success, fail, info, warn } from '../output.js';
 
@@ -253,9 +256,32 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
     }
   }
 
+  // `--stage --direct` (lane 1): resolve the stage's OPERATOR connection from its ops
+  // Lambda, then execute CLI-side with an unbounded clock — the same ceremony as the
+  // direct path below (which is stage-aware: approver check + auto-snapshot when --stage
+  // is set), just a longer clock. The operator never holds a URL; it lives in memory only.
+  if (dbSource.kind === 'stage' && flags.direct === 'true') {
+    try {
+      step('Resolving the operator connection from the stage (--direct)...');
+      const op = await resolveOperatorUrlViaStage(flags.stage);
+      info(`operator credential resolved (${op.source}) — executing CLI-side, unbounded clock.`);
+      dbSource = { kind: 'url', url: op.url, from: 'operator' };
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+  }
+
   // Deployed stage, no direct URL: the write runs in the ops Lambda — the
   // operator never holds a database URL. --database-url stays local-only.
   if (dbSource.kind === 'stage') {
+    // Will this edge fit the ops-Lambda's 900-second clock? If not, refuse up front and
+    // name --direct (credential-free, unbounded) instead of burning 15 minutes to learn it.
+    const fit = estimateOpsRuntimeFit(plan);
+    if (!fit.fits) {
+      fail(`REFUSED (ops-Lambda runtime): ${fit.reason}`);
+      process.exit(1);
+    }
     await applyPlanViaStage(plan, flags, forceDescent);
     return;
   }
@@ -315,7 +341,13 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
       warn(`DESCENT FORCED — the fast-forward rule is bypassed for this apply. Snapshot on record: ${forceDescent}.`);
     }
     step('Verifying the target is where the plan started...');
-    const result = await executeApplyPlan(runner, plan, {
+    // The mutation lease: one operator mutates a database at a time. Acquired on this apply's
+    // own session (the max:1 createUrlRunner) before any write; a second operator is refused
+    // by name. Self-releases on disconnect.
+    const result = await withMutationLease(
+      runner,
+      { verb: 'db:apply', actor: process.env.USER ?? 'unknown' },
+      () => executeApplyPlan(runner, plan, {
       actor: process.env.USER ?? null,
       gitRef: currentGitRef() ?? plan.gitRef,
       ...(verifyAuthority ? { verifyAuthority } : {}),
@@ -340,10 +372,16 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
           }
         },
       } : {}),
-    });
+      }),
+    );
 
     reportApplyResult(result, plan);
   } catch (err: any) {
+    if (err instanceof MutationLeaseError) {
+      // Nothing was applied — the lease refused before any write. Not a rollback.
+      fail(err.message);
+      process.exit(1);
+    }
     fail(`Apply failed and rolled back: ${err.message}`);
     process.exit(1);
   } finally {

package/src/cli/commands/db-backfill.ts

@@ -28,6 +28,10 @@ import {
 } from '../backfill.js';
 import { currentGitRef } from '../state-apply.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
+import { resolveOperatorUrlViaStage } from '../direct-venue.js';
+import { withMutationLease, MutationLeaseError } from '../mutation-lease.js';
+import { resolveConfig, opsFunction } from '../config.js';
+import { invokeAction } from '../aws.js';
 import { readSqlDirIfPresent } from './db-sync.js';
 import { step, success, fail, info, warn } from '../output.js';
 
@@ -49,6 +53,71 @@ export function buildBackfillReport(plan: BackfillPlan): string[] {
   return lines;
 }
 
+/**
+ * db:backfill --stage: ship the *.sql files to the ops Lambda's db:backfill action, which
+ * plans + (under --apply) runs them on the operator connection and records them. The operator
+ * never holds a database URL. --direct is the escape for a backfill too big for the 900s clock.
+ */
+async function runBackfillViaStage(
+  files: { file: string; sql: string }[],
+  flags: Record<string, string>,
+): Promise<void> {
+  step('Resolving deployed config...');
+  const config = await resolveConfig(flags.stage);
+
+  let markApplied: string | undefined;
+  if (flags['mark-applied'] !== undefined) {
+    if (flags['mark-applied'] === 'true') {
+      fail('--mark-applied needs a file name from the backfills dir.');
+      process.exit(1);
+    }
+    markApplied = flags['mark-applied'];
+  }
+
+  const payload = {
+    files: files.map((f) => ({ file: f.file, sql: f.sql })),
+    apply: flags.apply === 'true',
+    ...(markApplied ? { markApplied } : {}),
+    actor: process.env.USER ?? null,
+    gitRef: currentGitRef(),
+  };
+
+  step('Running the backfill lane in the ops Lambda (credential-free)...');
+  const res: any = await invokeAction(config.region, opsFunction(config), 'db:backfill', payload);
+  if (res?.error) {
+    fail(`db:backfill failed: ${res.error}`);
+    if (/Unknown action/i.test(String(res.error))) {
+      info('The deployed handler predates the db:backfill ops action. Upgrade @everystack/server, or run direct: db:backfill --apply --database-url <url> (or --stage --direct).');
+    }
+    process.exit(1);
+  }
+
+  if (res?.markedApplied) {
+    success(`Recorded ${res.markedApplied} as applied WITHOUT running it (identity ${String(res.identity).slice(0, 12)}).`);
+    return;
+  }
+
+  if (res?.plan) for (const line of buildBackfillReport(res.plan)) info(line);
+  if (flags.json === 'true') console.log(JSON.stringify(res.plan ?? res, null, 2));
+
+  if (!res?.applied) {
+    if (res?.plan?.pending?.length) info('Run them: everystack db:backfill --stage ' + (flags.stage ?? '<stage>') + ' --apply');
+    if (res?.plan?.blocked?.length) process.exit(1);
+    return;
+  }
+
+  for (const ran of res.ran ?? []) info(`~ ${ran.file} applied in ${ran.durationMs}ms`);
+  if (res.failed) {
+    fail(`${res.failed.file} FAILED and rolled back (recorded; it stays pending for the retry): ${res.failed.error}`);
+    process.exit(1);
+  }
+  if (res?.plan?.blocked?.length) {
+    fail('Pending jobs ran, but blocked file(s) remain above — fix them (new file name, or --mark-applied).');
+    process.exit(1);
+  }
+  success(`${(res.ran ?? []).length} backfill(s) applied and recorded in everystack.backfill_log.`);
+}
+
 export async function dbBackfillCommand(flags: Record<string, string>): Promise<void> {
   const dir = flags.dir || DEFAULT_DIR;
   const files = await readSqlDirIfPresent(dir);
@@ -64,9 +133,28 @@ export async function dbBackfillCommand(flags: Record<string, string>): Promise<
     fail(err.message);
     process.exit(1);
   }
-  if (dbSource.kind !== 'url') {
-    fail('db:backfill needs a direct connection (--database-url or DATABASE_URL) — the lane reads and writes its per-database record.');
-    process.exit(1);
+
+  // `--stage --direct` (lane 1): a backfill too big for the ops-Lambda's 900-second clock runs
+  // CLI-side with an unbounded clock. Resolve the stage's operator connection and fall through
+  // to the direct path — credential-free, the operator never holds a URL.
+  if (dbSource.kind === 'stage' && flags.direct === 'true') {
+    try {
+      step('Resolving the operator connection from the stage (--direct)...');
+      const op = await resolveOperatorUrlViaStage(flags.stage);
+      info(`operator credential resolved (${op.source}) — running backfills CLI-side, unbounded clock.`);
+      dbSource = { kind: 'url', url: op.url, from: 'operator' };
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+  }
+
+  // `--stage` (ops path): ship the *.sql files to the ops Lambda's db:backfill action — it plans
+  // (by content identity, against everystack.backfill_log) and, under --apply, runs the pending
+  // jobs on the operator connection and records them. The operator holds no URL.
+  if (dbSource.kind === 'stage') {
+    await runBackfillViaStage(files, flags);
+    return;
   }
 
   step(connectingVia(dbSource));
@@ -110,7 +198,12 @@ export async function dbBackfillCommand(flags: Record<string, string>): Promise<
     }
 
     step(`Running ${plan.pending.length} backfill(s), each as its own transaction...`);
-    const result = await executeBackfills(runner, plan, opts);
+    // A data-write operator mutation takes the lease so a concurrent operator is refused.
+    const result = await withMutationLease(
+      runner,
+      { verb: 'db:backfill', actor: process.env.USER ?? 'unknown' },
+      () => executeBackfills(runner, plan, opts),
+    );
     for (const ran of result.ran) info(`~ ${ran.file} applied in ${ran.durationMs}ms`);
     if (result.failed) {
       fail(`${result.failed.file} FAILED and rolled back (recorded; it stays pending for the retry): ${result.failed.error}`);
@@ -121,6 +214,13 @@ export async function dbBackfillCommand(flags: Record<string, string>): Promise<
       process.exit(1);
     }
     success(`${result.ran.length} backfill(s) applied and recorded in everystack.backfill_log.`);
+  } catch (err: any) {
+    if (err instanceof MutationLeaseError) {
+      // The lease refused before any job ran — nothing was written.
+      fail(err.message);
+      process.exit(1);
+    }
+    throw err;
   } finally {
     await end?.();
   }

package/src/cli/commands/db-export.ts

@@ -215,5 +215,5 @@ export async function dbExportCommand(flags: Record<string, string>): Promise<vo
     fail(`Export failed: ${result.error}`);
     process.exit(1);
   }
-  success(`Artifact ${result.id} (${fmtBytes(result.bytes)}, fingerprint ${String(result.fingerprint).slice(0, 12)}). Deploy with: everystack db:swap --schema ${schema} --stage <target>`);
+  success(`Artifact ${result.id} (${fmtBytes(result.bytes)}, fingerprint ${String(result.fingerprint).slice(0, 12)}). Deploy with: everystack db:swap --schema ${schema} --from ${result.id} --stage <target> --direct --confirm`);
 }

package/src/cli/commands/db-reconcile.ts

@@ -46,6 +46,8 @@ import {
   ENSURE_RECONCILER_SQL,
 } from '../derived-apply.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
+import { resolveOperatorUrlViaStage } from '../direct-venue.js';
+import { withMutationLease, MutationLeaseError } from '../mutation-lease.js';
 import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, type DeclaredDerived } from '../declared-derived.js';
 import { currentGitRef } from '../state-apply.js';
 import { resolveConfig, opsFunction } from '../config.js';
@@ -380,6 +382,27 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
     process.exit(1);
   }
 
+  // `--stage --direct` (lane 1): a 54-object derived rebuild runs 15-25 minutes and blows
+  // the ops-Lambda's 900-second clock. Resolve the stage's OPERATOR connection from its ops
+  // Lambda and execute CLI-side with an unbounded clock — credential-free, the operator never
+  // holds a URL. Only meaningful under --apply (a dry-run just reads). Fall through as a url
+  // source so the local-runner branch below runs executeReconcile against it, under the lease.
+  if (dbSource.kind === 'stage' && flags.direct === 'true') {
+    if (!apply) {
+      fail('--direct is a write venue — it only applies with --apply. For a dry-run drop --direct (the stage plans read-only via the ops Lambda).');
+      process.exit(1);
+    }
+    try {
+      step('Resolving the operator connection from the stage (--direct)...');
+      const op = await resolveOperatorUrlViaStage(flags.stage);
+      info(`operator credential resolved (${op.source}) — reconciling CLI-side, unbounded clock.`);
+      dbSource = { kind: 'url', url: op.url, from: 'operator' };
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+  }
+
   // --baseline only writes under --apply (executeReconcile returns the plan and executes nothing
   // when apply=false). Passing it alone used to print "recording provenance…" and exit 0 while
   // persisting nothing — a silent no-op. Fail loudly instead; the plan already lists needsBaseline.
@@ -459,21 +482,33 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
         fail(`db:reconcile failed: ${result.error}`);
         if (/Unknown action/i.test(String(result.error))) {
           info('The deployed handler predates the db:reconcile ops action (needs @everystack/server >= 0.4.8). Upgrade the server, or apply direct: db:reconcile --apply --database-url <url>.');
+        } else if (/timed out|timeout|task timed out/i.test(String(result.error))) {
+          info('A large derived rebuild (dozens of objects) can exceed the ops-Lambda 900-second clock. Re-run credential-free with an unbounded clock: db:reconcile --apply --stage ' + (flags.stage ?? '<stage>') + ' --direct.');
         }
         process.exit(1);
       }
       run = { plan: result.plan, applied: result.applied, statements: result.statements ?? [], refusal: result.refusal ?? undefined };
     } else {
       let runner: QueryRunner;
+      // A write over a direct connection (--database-url or --direct) takes the mutation
+      // lease; a read-only stage dry-run over the ops Lambda does not (reads never lease).
+      let leased = false;
       if (dbSource.kind === 'url') {
         step(connectingVia(dbSource));
         ({ runner, end } = await createUrlRunner(dbSource.url));
+        leased = apply;
       } else {
         step('Resolving deployed config...');
         const config = await resolveConfig(flags.stage);
         runner = lambdaRunner(config.region, opsFunction(config));
       }
-      run = await executeReconcile(runner, reconcileOptions);
+      run = leased
+        ? await withMutationLease(
+            runner,
+            { verb: 'db:reconcile', actor: process.env.USER ?? 'unknown' },
+            () => executeReconcile(runner, reconcileOptions),
+          )
+        : await executeReconcile(runner, reconcileOptions);
     }
 
     if (flags.json === 'true') {
@@ -499,6 +534,13 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
 
     if (run.refusal) process.exit(1);
     if (check && checkFails(run.plan)) process.exit(1);
+  } catch (err: any) {
+    if (err instanceof MutationLeaseError) {
+      // The lease refused before any DDL — nothing was reconciled.
+      fail(err.message);
+      process.exit(1);
+    }
+    throw err;
   } finally {
     await end?.();
   }

package/src/cli/commands/db-swap.ts

@@ -14,9 +14,13 @@
  */
 
 import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createGunzip } from 'node:zlib';
 import { spawn } from 'node:child_process';
 import { Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
 import type { ModelDescriptor } from '@everystack/model';
 import { fingerprintModels } from '../schema-fingerprint.js';
 import { resolveModelsPath } from '../models-path.js';
@@ -25,7 +29,13 @@ import { loadDeclaredDerived } from '../declared-derived.js';
 import { createUrlRunner } from '../db-source.js';
 import { executeSwap, type SwapVerdict } from '../swap-execute.js';
 import { rewriteStatementLine, opensCopyData, closesCopyData } from '../schema-rewrite.js';
-import { step, success, fail, warn } from '../output.js';
+import { resolveOperatorUrlViaStage } from '../direct-venue.js';
+import { withMutationLease, MutationLeaseError } from '../mutation-lease.js';
+import { resolveConfig, opsFunction } from '../config.js';
+import { invokeAction, presignGet } from '../aws.js';
+import { keyForArtifactId, metaKey } from '../backup.js';
+import { pgEnvFromUrl } from './db.js';
+import { step, success, fail, warn, info } from '../output.js';
 
 /** A COPY-aware line transform that rewrites the schema token on statement lines only. */
 function schemaRewriteStream(from: string, to: string): Transform {
@@ -64,10 +74,17 @@ function schemaRewriteStream(from: string, to: string): Transform {
  * rewrite → psql. The archive names `<schema>`; the rewrite lands it as `<incoming>`, COPY-data-safe.
  */
 async function restoreIntoIncoming(url: string, artifactPath: string, schema: string, incoming: string): Promise<void> {
-  // psql takes the connection URL directly (credential parsed by libpq, not on the process table
-  // beyond argv-as-URL); pg_restore -f - just reads the archive file to SQL on stdout.
+  // Connect via PG* env, not `-d <url>`. libpq VALIDATES URI query params against its keyword
+  // list and REJECTS non-keywords like `search_path` ("invalid URI query parameter") — and the
+  // operator URL db:operator-url mints bakes search_path in (fine for postgres.js, fatal for a
+  // libpq client). pgEnvFromUrl extracts only libpq keywords (dropping search_path, routing
+  // sslmode→PGSSLMODE) and puts the password in PGPASSWORD, off the process argv. pg_restore -f -
+  // just reads the archive file to SQL on stdout (no connection).
   const restore = spawn('pg_restore', ['-f', '-', artifactPath], { stdio: ['ignore', 'pipe', 'pipe'] });
-  const psql = spawn('psql', ['-v', 'ON_ERROR_STOP=1', '-d', url], { stdio: ['pipe', 'ignore', 'pipe'] });
+  const psql = spawn('psql', ['-v', 'ON_ERROR_STOP=1'], {
+    stdio: ['pipe', 'ignore', 'pipe'],
+    env: { ...process.env, ...pgEnvFromUrl(url) },
+  });
   let rErr = '', pErr = '';
   restore.stderr.on('data', (d) => { rErr += d.toString(); });
   psql.stderr.on('data', (d) => { pErr += d.toString(); });
@@ -100,14 +117,115 @@ export function readArtifactFingerprint(artifactPath: string, flag?: string): st
   }
 }
 
+/** A resolved artifact ready for restore: a local plain `-Fc` .dump plus its stamped fingerprint. */
+interface ResolvedArtifact {
+  dumpPath: string;
+  fingerprint: string | null;
+  /** Remove any temp files fetched from S3 (no-op for a local artifact). */
+  cleanup: () => Promise<void>;
+}
+
+/**
+ * Fetch a schema-export artifact from S3 to a local temp `-Fc` .dump for the --direct swap.
+ * db:export --stage stores a gzipped -Fc archive + a sibling .meta.json (fingerprint). This
+ * presigns both with the CLI's own IAM, streams the dump down, gunzips it (pg_restore reads a
+ * plain archive), and reads the stamped fingerprint from the meta. The operator holds no DB
+ * credential; the artifact just transits the caller's presigned S3 read.
+ */
+async function fetchArtifactFromS3(
+  id: string,
+  stage: string | undefined,
+  fingerprintFlag: string | undefined,
+): Promise<ResolvedArtifact> {
+  const key = keyForArtifactId(id);
+  if (!key) throw new Error(`--from is neither a local file nor a valid artifact id (expected schema/stage/stamp, got ${id}).`);
+
+  const config = await resolveConfig(stage);
+  if (!config.backupsBucket) {
+    throw new Error('No backupsBucket in the deployed config — cannot fetch the S3 artifact. Add `backupsBucket` to the sst.config outputs and redeploy, or pass a local --from <file.dump>.');
+  }
+
+  const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'everystack-swap-'));
+  const dumpPath = path.join(tmpDir, 'artifact.dump');
+  const cleanup = async () => { await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {}); };
+
+  try {
+    step(`Fetching artifact ${id} from S3 (presigned, then gunzip)...`);
+    const dumpUrl = await presignGet(config.region, config.backupsBucket, key, 3600);
+    const res = await fetch(dumpUrl);
+    if (!res.ok || !res.body) throw new Error(`artifact download failed: HTTP ${res.status}`);
+    await pipeline(Readable.fromWeb(res.body as any), createGunzip(), fs.createWriteStream(dumpPath));
+
+    // The fingerprint: an explicit flag wins; otherwise read the sibling .meta.json.
+    let fingerprint = fingerprintFlag ?? null;
+    if (!fingerprint) {
+      try {
+        const metaUrl = await presignGet(config.region, config.backupsBucket, metaKey(key), 3600);
+        const metaRes = await fetch(metaUrl);
+        if (metaRes.ok) fingerprint = (await metaRes.json() as any)?.fingerprint ?? null;
+      } catch { /* fall through — the caller reports a missing fingerprint */ }
+    }
+    return { dumpPath, fingerprint, cleanup };
+  } catch (err) {
+    await cleanup();
+    throw err;
+  }
+}
+
+/** Resolve --from to a local plain -Fc dump: a local file as-is, else an S3 artifact id fetched down. */
+async function resolveSwapArtifact(
+  from: string,
+  stage: string | undefined,
+  fingerprintFlag: string | undefined,
+): Promise<ResolvedArtifact> {
+  if (fs.existsSync(from)) {
+    return { dumpPath: from, fingerprint: readArtifactFingerprint(from, fingerprintFlag), cleanup: async () => {} };
+  }
+  return fetchArtifactFromS3(from, stage, fingerprintFlag);
+}
+
 export async function dbSwapCommand(flags: Record<string, string>): Promise<void> {
   const schema = flags.schema;
-  const url = flags['database-url'] || process.env.DATABASE_URL;
   const from = flags.from;
+  const stage = flags.stage;
+  const direct = flags.direct === 'true';
   if (!schema) { fail('db:swap needs --schema <name>.'); process.exit(1); }
-  if (!from) { fail('db:swap needs --from <artifact.dump> (the schema-scoped -Fc archive to land).'); process.exit(1); }
+  if (!from) { fail('db:swap needs --from <artifact.dump | artifact-id> (the schema-scoped -Fc archive to land).'); process.exit(1); }
+
+  // Resolve the venue.
+  //  - --database-url (or DATABASE_URL): a local/direct operator connection.
+  //  - --stage --direct: resolve the stage's OPERATOR connection from its ops Lambda and execute
+  //    CLI-side with an unbounded clock (a multi-GB restore blows the 900s Lambda ceiling). The
+  //    operator never holds a URL; the swap snapshots the stage via db:backup before it lands.
+  //  - --stage alone: refuse, naming --direct — the ops-Lambda venue can't hold the restore clock.
+  let url = flags['database-url'] || process.env.DATABASE_URL;
+  let snapshotViaStage = false;
+  let region: string | undefined;
+  let opsFn: string | undefined;
+
+  if (!url && stage) {
+    if (!direct) {
+      fail('db:swap --stage needs --direct: a schema restore can exceed the ops-Lambda 900-second clock, so the swap runs CLI-side with an unbounded clock (credential-free — the operator never holds a URL). Re-run with --stage ' + stage + ' --direct.');
+      process.exit(1);
+    }
+    if (flags.confirm !== 'true') {
+      fail('db:swap --stage --direct is destructive (it drops the retiring schema after the swap). Confirm explicitly: --confirm.');
+      process.exit(1);
+    }
+    try {
+      const config = await resolveConfig(stage);
+      region = config.region;
+      opsFn = opsFunction(config);
+      step('Resolving the operator connection from the stage (--direct)...');
+      const op = await resolveOperatorUrlViaStage(stage);
+      url = op.url;
+      snapshotViaStage = true;
+      info(`operator credential resolved (${op.source}) — swapping CLI-side, unbounded clock.`);
+    } catch (err: any) { fail(err.message); process.exit(1); }
+  }
+
   if (!url) {
-    fail('db:swap v1 needs a direct --database-url (the operator connection). The credential-free --stage venue rides the stage-write-lanes bricks; a large restore needs its unbounded clock.');
+    fail('db:swap needs a target: --database-url <url> (local/direct), or --stage <name> --direct (credential-free — the operator never holds a URL).');
     process.exit(1);
   }
 
@@ -121,24 +239,41 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
     declaredFingerprint = fingerprintModels(models, { schemas: [schema], sequences: declaredDb?.sequences }).hash;
   } catch (err: any) { fail(err.message); process.exit(1); }
 
-  const artifactFingerprint = readArtifactFingerprint(from, flags.fingerprint);
-  if (!artifactFingerprint) {
-    fail(`db:swap can't find the artifact fingerprint — expected a sibling .meta.json next to ${from}, or pass --fingerprint. Without it the gate can't run, and an unchecked swap is exactly what the gate prevents.`);
+  // Resolve --from to a local plain -Fc dump (a local file, or an S3 export id fetched down).
+  let artifact: ResolvedArtifact;
+  try {
+    artifact = await resolveSwapArtifact(from, stage, flags.fingerprint);
+  } catch (err: any) { fail(err.message); process.exit(1); }
+
+  if (!artifact.fingerprint) {
+    await artifact.cleanup();
+    fail(`db:swap can't find the artifact fingerprint — expected a sibling .meta.json next to ${from} (or the artifact's S3 meta), or pass --fingerprint. Without it the gate can't run, and an unchecked swap is exactly what the gate prevents.`);
     process.exit(1);
   }
+  const artifactFingerprint = artifact.fingerprint;
 
   const { runner, end } = await createUrlRunner(url);
   try {
     step(`Swapping ${schema} — gate, land incoming, atomic swap, verify...`);
-    const res = await executeSwap(runner, {
-      models, schema,
-      artifactFingerprint,
-      declaredFingerprint,
-      applyIncoming: async () => { await restoreIntoIncoming(url, from, schema, `${schema}_incoming`); },
-      // Snapshot + verify-hook wiring land with the ops venue; a direct v1 swap warns rather than
-      // silently skipping the safety net.
-      snapshot: async () => { warn('no snapshot taken (direct v1) — take one first: everystack db:backup --database-url … before a production swap.'); },
-    });
+    // One operator mutates a database at a time — the swap is a whole-schema replacement.
+    const res = await withMutationLease(
+      runner,
+      { verb: 'db:swap', actor: process.env.USER ?? 'unknown' },
+      () => executeSwap(runner, {
+        models, schema,
+        artifactFingerprint,
+        declaredFingerprint,
+        applyIncoming: async () => { await restoreIntoIncoming(url!, artifact.dumpPath, schema, `${schema}_incoming`); },
+        snapshot: snapshotViaStage
+          ? async () => {
+              step('Snapshotting the stage before the swap (db:backup)...');
+              const r: any = await invokeAction(region!, opsFn!, 'db:backup', { stage });
+              if (r?.error) throw new Error(`pre-swap snapshot failed, so the swap was NOT applied: ${r.error}`);
+              info(`snapshot on record: ${r?.id ?? 'backup complete'} — restore with db:restore --from ${r?.id ?? '<id>'} --confirm.`);
+            }
+          : async () => { warn('no snapshot taken (direct v1) — take one first: everystack db:backup --database-url … before a production swap.'); },
+      }),
+    );
 
     if (res.status === 'swapped') {
       success(`Swapped ${schema} — the artifact is live (no refresh ran).`);
@@ -148,9 +283,11 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
       process.exit(1);
     }
   } catch (err: any) {
+    if (err instanceof MutationLeaseError) { fail(err.message); process.exit(1); }
     fail(`Swap failed: ${err.message}`);
     process.exit(1);
   } finally {
     await end?.();
+    await artifact.cleanup();
   }
 }

package/src/cli/commands/db.ts

@@ -211,7 +211,7 @@ export function buildProvisionSecretPlan(args: {
  *  same seam as pipeline-loader). */
 export interface ServerProvision {
   runProvision(
-    payload: { authPassword?: string; adminPassword?: string },
+    payload: { authPassword?: string; adminPassword?: string; searchPath?: string[] },
     deps: {
       execute: (sql: string) => Promise<unknown>;
       connection?: { host: string; port?: number | string; database: string } | null;
@@ -473,6 +473,31 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
   info('Creating the least-privilege role chain on your EXISTING database (no database is created).');
   step('Provisioning roles...');
 
+  // The declared schema set — resolved BEFORE provisioning so it can be set as the ROLE default
+  // (ALTER ROLE … SET search_path), the right layer for bare-ref resolution (search-path-ownership).
+  // Union the DERIVED-object schemas (matviews/views live in schemas the barrel never names) so the
+  // authenticator flip doesn't go dark on bare-ref matview reads. Best-effort: a modelless or
+  // all-public app sets no path (unchanged behavior).
+  let declaredSchemas: string[] = [];
+  try {
+    const { resolveModelsPath } = await import('../models-path.js');
+    const { loadModels } = await import('./db-generate.js');
+    const models = await loadModels(resolveModelsPath(flags.models));
+    let derivedObjects: Array<{ schema: string }> = [];
+    try {
+      const { loadDeclaredDerived } = await import('../declared-derived.js');
+      const declared = await loadDeclaredDerived(flags.models);
+      if (declared) derivedObjects = declared.objects;
+    } catch {
+      // No derived layer resolvable — the table schemas still resolve correctly.
+    }
+    declaredSchemas = collectDeclaredSchemas({ models, derivedObjects });
+  } catch {
+    // No models resolvable here — leave the roles schema-agnostic.
+  }
+  const searchPath = declaredSearchPath(declaredSchemas);
+  if (searchPath.length) info(`  Declared search_path (set as the role default via ALTER ROLE): ${searchPath.join(', ')}`);
+
   // Generate BOTH login passwords and keep them in memory only — they are written straight
   // into the secret store and are NEVER printed, logged, or returned to a human.
   const { randomBytes } = await import('node:crypto');
@@ -486,7 +511,7 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
     const { createUrlRunner } = await import('../db-source.js');
     const { runner, end } = await createUrlRunner(url);
     try {
-      return await runProvision({ authPassword, adminPassword }, {
+      return await runProvision({ authPassword, adminPassword, searchPath }, {
         execute: async (statement) => runner(statement),
         connection: parseUrlConnection(url),
         // Same probe as the ops-Lambda venue: a real login as the new role, DDL-capable.
@@ -519,7 +544,7 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
     conn = parseUrlConnection(directUrl);
   } else {
     try {
-      result = await invokeAction(config.region, opsFunction(config), 'db:provision', { authPassword, adminPassword });
+      result = await invokeAction(config.region, opsFunction(config), 'db:provision', { authPassword, adminPassword, searchPath });
     } catch (err: any) {
       // Auto-fallback: no Ops Lambda (Unknown action), but an ADMIN_DATABASE_URL secret exists —
       // provision directly over it. Master never crosses the CLI; the operator sets nothing new.
@@ -575,31 +600,6 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
   // wrong-database scare, and that check meant re-handling the master credential).
   success(`Target database: ${conn.database} @ ${conn.host}:${conn.port ?? 5432} — secrets for stage "${flags.stage}" will point here.`);
 
-  // Bake the app's declared schemas into the minted URLs, so a multi-schema API connects with
-  // the right search_path instead of going dark on bare refs (best-effort: a modelless app or
-  // an all-public one changes nothing).
-  let declaredSchemas: string[] = [];
-  try {
-    const { resolveModelsPath } = await import('../models-path.js');
-    const { loadModels } = await import('./db-generate.js');
-    const models = await loadModels(resolveModelsPath(flags.models));
-    // Union the DERIVED-object schemas (matviews/views live in schemas the barrel never
-    // names) so the authenticator flip doesn't go dark on bare-ref matview reads.
-    let derivedObjects: Array<{ schema: string }> = [];
-    try {
-      const { loadDeclaredDerived } = await import('../declared-derived.js');
-      const declared = await loadDeclaredDerived(flags.models);
-      if (declared) derivedObjects = declared.objects;
-    } catch {
-      // No derived layer resolvable — the table schemas still bake correctly.
-    }
-    declaredSchemas = collectDeclaredSchemas({ models, derivedObjects });
-  } catch {
-    // No models resolvable here — leave the URLs schema-agnostic.
-  }
-  const searchPath = declaredSearchPath(declaredSchemas);
-  if (searchPath.length) info(`  search_path baked into DATABASE_URL: ${searchPath.join(', ')}`);
-
   // Preserve the connection params (sslmode, …) from the URL the app already connects with — the
   // minted URL is built from bare host/port/db components, so without this a `?sslmode=require`
   // would be dropped and the new roles could fail to connect on an SSL-forced RDS. Prefer the
@@ -608,11 +608,12 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
     ?? stageSecrets.ADMIN_DATABASE_URL ?? stageSecrets.AdminDatabaseUrl
     ?? stageSecrets.DATABASE_URL ?? stageSecrets.DatabaseUrl;
 
+  // The minted secret is credentials-only: search_path now lives on the ROLE (ALTER ROLE, above),
+  // not baked into the URL. This keeps the secret a pure credential and — critically — yields a
+  // libpq-clean URL (no ?search_path=, which psql/pg_restore reject as an unknown keyword). Real
+  // connection params (sslmode, …) are still carried from the source URL.
   const mint = (role: string, password: string): string =>
-    withSearchPath(
-      preserveConnParams(`postgresql://${role}:${password}@${conn.host}:${conn.port ?? 5432}/${conn.database}`, sourceUrl),
-      declaredSchemas,
-    );
+    preserveConnParams(`postgresql://${role}:${password}@${conn.host}:${conn.port ?? 5432}/${conn.database}`, sourceUrl);
 
   const authUrl = mint(result.loginRole, authPassword);
   const adminUrl = result.adminRole ? mint(result.adminRole, adminPassword) : undefined;

package/src/cli/db-source.ts

@@ -27,7 +27,7 @@
 import type { QueryRunner } from './authz-contract.js';
 
 export type DbSource =
-  | { kind: 'url'; url: string; from: 'flag' | 'env' | 'admin-env' }
+  | { kind: 'url'; url: string; from: 'flag' | 'env' | 'admin-env' | 'operator' }
   | { kind: 'stage' };
 
 /** Decide which path serves this invocation. Pure; env injectable for tests. */
@@ -57,6 +57,9 @@ export function resolveDbSource(
 export function connectingVia(source: Extract<DbSource, { kind: 'url' }>): string {
   if (source.from === 'flag') return 'Connecting via --database-url...';
   if (source.from === 'admin-env') return 'Connecting via ADMIN_DATABASE_URL...';
+  if (source.from === 'operator') {
+    return 'Connecting --direct (operator credential resolved from the stage\'s ops Lambda, held in memory only)...';
+  }
   return 'Connecting via DATABASE_URL...';
 }
 

package/src/cli/direct-venue.ts

@@ -0,0 +1,43 @@
+/**
+ * The `--direct` venue (stage-write-lanes lane 1).
+ *
+ * A write verb run with `--stage <name> --direct` resolves the OPERATOR connection from the
+ * stage's IAM-gated ops Lambda (the `db:operator-url` action, brick 1), holds the URL in
+ * process memory only, and executes CLI-side with an unbounded clock. The ceremony is
+ * untouched — only the execution venue moves. Shared by db:apply, db:reconcile, db:backfill,
+ * and db:swap so every lane resolves the operator credential the same way.
+ *
+ * The URL travels only in the Lambda invoke response and this process's memory: never printed,
+ * never written, never exported. Callers pass it straight to createUrlRunner and drop it.
+ */
+
+import { resolveConfig, opsFunction } from './config.js';
+import { invokeAction } from './aws.js';
+
+export interface OperatorConnection {
+  /** The operator connection string — hold in memory, never print. */
+  url: string;
+  /** Which credential the stage resolved: 'admin' (migrator) or 'master'. */
+  source: string;
+}
+
+/**
+ * Resolve a stage's operator connection for the `--direct` lane via its ops Lambda.
+ * Throws a remediation-named error when no operator connection exists or the ops Lambda
+ * predates this action (an older server that does not know `db:operator-url`).
+ */
+export async function resolveOperatorUrlViaStage(
+  stage: string | undefined,
+  invoke: typeof invokeAction = invokeAction,
+): Promise<OperatorConnection> {
+  const config = await resolveConfig(stage);
+  const fn = opsFunction(config);
+  const res: any = await invoke(config.region, fn, 'db:operator-url', {});
+  if (res?.error) throw new Error(res.error);
+  if (!res?.url) {
+    throw new Error(
+      'the ops Lambda did not return an operator connection for --direct. Deploy a server build that ships the db:operator-url action, or use --database-url for a local connection.',
+    );
+  }
+  return { url: res.url, source: res.source ?? 'operator' };
+}

package/src/cli/index.ts

@@ -357,7 +357,7 @@ Usage:
   everystack db:psql           --stage <name>  Interactive ADMIN psql (IAM-gated; resolves the admin URL in-process)
   everystack db:psql           [--stage <name>] -c <command>  Run one query via Lambda (works for private RDS)
   everystack db:doctor         [--stage <name>] [--direct | --database-url <api> [--admin-database-url <ops>]]  Check the DB is least-privilege + RLS-subject (api vs operator connection). No flag = ops-Lambda venue (auto-falls to direct via the stage secrets if the handler has no dbPlugin). --direct = probe both connections from the stage's DATABASE_URL + ADMIN_DATABASE_URL secrets; --database-url = explicit local venue (a lone URL is probed as both)
-  everystack db:provision      --stage <name> [--direct | --database-url <url>]  Create the least-privilege role chain on an EXISTING database (idempotent; creates no DB). No flag = ops-Lambda venue (auto-falls to direct via the ADMIN_DATABASE_URL secret if the handler has no dbPlugin). --direct = direct connection reading that secret (master never on argv); --database-url = explicit URL. Declared schemas are baked into the minted DATABASE_URL as search_path
+  everystack db:provision      --stage <name> [--direct | --database-url <url>]  Create the least-privilege role chain on an EXISTING database (idempotent; creates no DB). No flag = ops-Lambda venue (auto-falls to direct via the ADMIN_DATABASE_URL secret if the handler has no dbPlugin). --direct = direct connection reading that secret (master never on argv); --database-url = explicit URL. Declared schemas are set as the ROLE default (ALTER ROLE … SET search_path) — the secret stays credentials-only, and the URL is libpq-clean
   everystack db:snapshot       [--stage <name>] [--instance <id>]  Take a physical RDS snapshot (instant DR point; RDS only — use db:backup for portable logical backups)
   everystack db:snapshots      [--stage <name>] [--instance <id>]  List manual RDS snapshots for the instance
   everystack db:backup:probe   [--stage <name>]  Verify the pg_dump layer is attached + version-compatible with the server

package/src/cli/mutation-lease.ts

@@ -0,0 +1,228 @@
+/**
+ * The universal mutation lease (docs/plans/mutation-lease.md).
+ *
+ * One lease per database, session-scoped, self-releasing, refuse-don't-coordinate.
+ * A PostgreSQL advisory SESSION lock with a fixed documented key, acquired on the SAME
+ * session that performs the mutation and held for the verb's whole body. Two operators
+ * cannot co-mutate one stage; the second is refused with the holder named, and re-tries
+ * nothing.
+ *
+ * This is the minimal core the stage-write-lanes `--direct` verbs need (mutation-lease
+ * brick 1). The full subsystem — the `db:lease` break-glass verb, the connection-layer
+ * enforcement of "one session, no second connection", the environment-state board — is a
+ * strict superset that converges onto this key later. Because the key is fixed, a session
+ * lock taken here contends correctly with any future acquirer (PostgreSQL advisory locks
+ * contend on the key, not on who took it).
+ *
+ * Why an advisory session lock and not a lease table: it self-releases on disconnect (a
+ * crashed CLI, a killed Lambda) with no TTL, no janitor, no stale row; `pg_try_advisory_lock`
+ * is atomic try-acquire so refuse-don't-coordinate falls out of the primitive; and the truth
+ * lives in `pg_locks`, discoverable from the catalog rather than bookkeeping that can lie.
+ */
+
+import type { QueryRunner } from './authz-contract.js';
+
+/**
+ * The fixed lease key: `('ES','TK')` as two 16-bit ints — 0x4553, 0x544B. One key covers
+ * every mutation verb (schema applies, reconciles, syncs, restores) so the cross-lane
+ * collision the lease exists to prevent (a rebuild during a refresh, a restore during a
+ * sync) cannot slip between per-lane keys. Documented, never computed.
+ */
+export const MUTATION_LEASE_KEY = { classid: 0x4553, objid: 0x544b } as const;
+
+/** PostgreSQL truncates `application_name` to NAMEDATALEN-1 = 63 bytes silently. */
+const APPLICATION_NAME_MAX_BYTES = 63;
+
+/**
+ * Build the mutation session's identity: `everystack:<verb>:<actor>+<session>`. The
+ * `<actor>` alone is not enough — two agents on the same stage this week both run as the
+ * same OS user, so a refusal that names only the actor tells the second agent nothing. The
+ * `+<session>` discriminator is what makes the refusal actionable: the second agent reads a
+ * session id that is not its own and knows it is colliding with a live peer, not staring at
+ * its own orphaned backend. Truncated to 63 bytes on a char boundary (PostgreSQL would
+ * truncate silently; we do it deterministically so the stored name is knowable).
+ */
+export function leaseApplicationName(verb: string, actor: string, session: string): string {
+  const full = `everystack:${verb}:${actor}+${session}`;
+  return truncateToBytes(full, APPLICATION_NAME_MAX_BYTES);
+}
+
+/** Truncate to at most `maxBytes` UTF-8 bytes without splitting a multibyte char. */
+function truncateToBytes(s: string, maxBytes: number): string {
+  if (Buffer.byteLength(s, 'utf8') <= maxBytes) return s;
+  let out = '';
+  let bytes = 0;
+  for (const ch of s) {
+    const chBytes = Buffer.byteLength(ch, 'utf8');
+    if (bytes + chBytes > maxBytes) break;
+    out += ch;
+    bytes += chBytes;
+  }
+  return out;
+}
+
+/** Single-quote-escape a string for inline SQL (doubles embedded quotes). */
+function sqlQuote(s: string): string {
+  return `'${s.replace(/'/g, "''")}'`;
+}
+
+/** `SET application_name` for this session, via set_config so the value is quote-safe. */
+export function setApplicationNameSql(name: string): string {
+  return `SELECT set_config('application_name', ${sqlQuote(name)}, false)`;
+}
+
+/** Try-acquire the session lease. Returns a boolean column `acquired`. Atomic, non-blocking. */
+export const TRY_ACQUIRE_LEASE_SQL =
+  `SELECT pg_try_advisory_lock(${MUTATION_LEASE_KEY.classid}, ${MUTATION_LEASE_KEY.objid}) AS acquired`;
+
+/** Release the session lease. Idempotent-safe to call in a finally. */
+export const RELEASE_LEASE_SQL =
+  `SELECT pg_advisory_unlock(${MUTATION_LEASE_KEY.classid}, ${MUTATION_LEASE_KEY.objid}) AS released`;
+
+/**
+ * Read the current holder of the lease from the catalog — the truth, not bookkeeping.
+ * Joins `pg_locks` to `pg_stat_activity` on the holding backend and returns the database,
+ * the holder's `application_name`, its pid, when the backend started, and its state.
+ */
+export const HOLDER_SQL = `
+SELECT
+  current_database()            AS database,
+  a.application_name            AS holder,
+  a.pid                         AS pid,
+  to_char(a.backend_start AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS') || ' UTC' AS since,
+  a.state                       AS state
+FROM pg_locks l
+JOIN pg_stat_activity a ON a.pid = l.pid
+WHERE l.locktype = 'advisory'
+  AND l.classid = ${MUTATION_LEASE_KEY.classid}
+  AND l.objid   = ${MUTATION_LEASE_KEY.objid}
+  AND l.granted
+LIMIT 1;
+`.trim();
+
+/** The structured holder facts the refusal sentence renders from. Pure, testable. */
+export interface LeaseHolder {
+  database: string;
+  holder: string | null;
+  pid: number | null;
+  since: string | null;
+  state: string | null;
+}
+
+/**
+ * Render the refusal sentence from the holder facts. Pure — the impure path assembles a
+ * `LeaseHolder` from `HOLDER_SQL` and hands it here, so the exact wording is unit-tested
+ * against a fixed row shape.
+ *
+ * Deliberately does NOT advertise `everystack db:lease`: that break-glass verb is a later
+ * brick and does not exist yet. Naming a command the CLI would then reject is the very
+ * paper-cut this whole effort is closing — so the hint stays true to what exists today.
+ */
+export function renderLeaseRefusal(h: LeaseHolder): string {
+  const holder = h.holder && h.holder.length > 0 ? h.holder : 'an unnamed session';
+  const parts: string[] = [];
+  if (h.pid != null) parts.push(`pid ${h.pid}`);
+  if (h.since) parts.push(`since ${h.since}`);
+  if (h.state) parts.push(`state: ${h.state}`);
+  const where = parts.length ? ` (${parts.join(', ')})` : '';
+  return (
+    `refused: ${h.database} is being mutated by ${holder}${where}. ` +
+    `One mutation at a time — wait for it to finish, or if the holder is dead-but-connected, ` +
+    `terminate that backend and retry.`
+  );
+}
+
+/** Thrown when the lease is held by another session. Carries the holder for callers. */
+export class MutationLeaseError extends Error {
+  readonly holder: LeaseHolder;
+  constructor(message: string, holder: LeaseHolder) {
+    super(message);
+    this.name = 'MutationLeaseError';
+    this.holder = holder;
+  }
+}
+
+export interface LeaseIdentity {
+  /** The verb holding the lease, e.g. `db:apply`, `db:reconcile`. */
+  verb: string;
+  /** The operator identity (OS user / STS identity). */
+  actor: string;
+  /**
+   * A short per-invocation discriminator so the two-agents-same-user refusal is actionable.
+   * Defaults to a fresh 6-hex-char nonce.
+   */
+  session?: string;
+}
+
+/** A fresh 6-hex-char session discriminator. */
+export function leaseSession(): string {
+  // Node's crypto is always present; 3 bytes -> 6 hex chars, ample for the discriminator.
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { randomBytes } = require('node:crypto');
+  return randomBytes(3).toString('hex');
+}
+
+/**
+ * Own the lease for the whole of `fn`. Stamps `application_name`, try-acquires the session
+ * lock, and on contention throws `MutationLeaseError` naming the holder. Releases in a
+ * `finally` — and because the lock is session-scoped, a crash mid-body frees it too.
+ *
+ * Must run on the mutation's OWN session — the same max:1 connection that performs every
+ * write of the verb. A verb that opens a SECOND connection mid-body has a writer the lease
+ * does not cover.
+ *
+ * HONEST LIMITATION (do not overstate): this is CONVENTIONALLY enforced, not runtime-enforced.
+ * A PostgreSQL connection carries no read/write intent the connection layer can inspect, so
+ * "reject a second connection" is unrealizable in-process. The counterexample is already in the
+ * tree: `createUrlPipelineRunner` (db-source.ts) opens a second, independent max:1 session with
+ * its own transaction, distinct from the `createUrlRunner` session this lease is handed — a verb
+ * that leases on one and writes on the other has a mutating connection the lease does not cover,
+ * and nothing rejects it. The only REAL enforcement is Postgres-side: reads connect as a
+ * read-only role that physically cannot write (redesign tracked in mutation-lease.md B1). Until
+ * that lands, treat this as a code-review convention with a named residual hole, not a guarantee.
+ */
+export async function withMutationLease<T>(
+  runner: QueryRunner,
+  identity: LeaseIdentity,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const session = identity.session ?? leaseSession();
+  const appName = leaseApplicationName(identity.verb, identity.actor, session);
+  await runner(setApplicationNameSql(appName));
+
+  const rows = await runner(TRY_ACQUIRE_LEASE_SQL);
+  const acquired = rows[0]?.acquired === true || rows[0]?.acquired === 't';
+  if (!acquired) {
+    const holder = await readHolder(runner);
+    throw new MutationLeaseError(renderLeaseRefusal(holder), holder);
+  }
+
+  try {
+    return await fn();
+  } finally {
+    // Best-effort release; the session lock also frees on disconnect, so a throw here
+    // (e.g. the connection already died) must not mask the body's outcome.
+    try {
+      await runner(RELEASE_LEASE_SQL);
+    } catch {
+      /* session gone — the lock died with it */
+    }
+  }
+}
+
+/** Assemble a `LeaseHolder` from `HOLDER_SQL`; a missing row still yields a usable sentence. */
+async function readHolder(runner: QueryRunner): Promise<LeaseHolder> {
+  let row: any;
+  try {
+    row = (await runner(HOLDER_SQL))[0];
+  } catch {
+    row = undefined;
+  }
+  return {
+    database: row?.database ?? 'the database',
+    holder: row?.holder ?? null,
+    pid: row?.pid != null ? Number(row.pid) : null,
+    since: row?.since ?? null,
+    state: row?.state ?? null,
+  };
+}

package/src/cli/ops-fit.ts

@@ -0,0 +1,78 @@
+/**
+ * Will this edge fit the ops-Lambda clock? (stage-write-lanes brick 2.)
+ *
+ * `db:apply --stage` executes the write inside the ops Lambda, which has a hard 900-second
+ * ceiling. A large brownfield edge — 1855 statements with 117 index builds, on a t4g.small —
+ * hit that ceiling in the field: the transaction rolled back clean, but the operator burned
+ * 15 minutes to learn it wouldn't fit. This estimates fit from the plan itself (at mint time,
+ * no live probe) so the ops path can REFUSE up front and name `--direct`, the credential-free
+ * escape with an unbounded clock.
+ *
+ * The heuristic is deliberately CONSERVATIVE, and that is safe by construction: a false
+ * "won't fit" routes the operator to `--direct`, which is itself credential-free and strictly
+ * more capable than the ops-Lambda path. Over-refusing costs nothing but a flag; under-refusing
+ * costs a 15-minute timeout. So we lean toward refusing.
+ *
+ * The bottleneck is the DATABASE, not the Lambda's memory/CPU — index builds scale with table
+ * size — so a raw statement count is only a proxy. Two signals: total executable statements,
+ * and the count of non-CONCURRENT index builds (the expensive class that dominated the incident).
+ */
+
+export interface OpsFitPlan {
+  statements?: string[];
+  executable?: number;
+}
+
+/**
+ * Thresholds tuned to the incident (1855 statements / 117 index builds timed out at 900s on a
+ * t4g.small) with generous headroom below it. Named so the reasoning is legible and one edit
+ * retunes the gate.
+ */
+export const OPS_FIT_LIMITS = {
+  /** Total executable statements above which the ops-Lambda clock is at risk. */
+  maxStatements: 500,
+  /** Non-CONCURRENT index builds above which a single edge likely blows the budget. */
+  maxIndexBuilds: 30,
+} as const;
+
+/** A CREATE INDEX that will hold a lock and scan the table (CONCURRENTLY is the slow-but-online form). */
+function isBlockingIndexBuild(stmt: string): boolean {
+  return /^\s*CREATE\s+(UNIQUE\s+)?INDEX\b/i.test(stmt) && !/\bCONCURRENTLY\b/i.test(stmt);
+}
+
+export interface OpsFitVerdict {
+  fits: boolean;
+  /** Present when !fits — the sentence the ops path refuses with, already naming --direct. */
+  reason?: string;
+}
+
+/**
+ * Estimate whether `plan` fits the ops-Lambda runtime. Pure; no database, no clock.
+ * `db:apply --stage` (the ops-Lambda path) calls this BEFORE invoking; `--direct` skips it
+ * (it has no Lambda ceiling).
+ */
+export function estimateOpsRuntimeFit(plan: OpsFitPlan): OpsFitVerdict {
+  const statements = plan.statements ?? [];
+  const total = plan.executable ?? statements.length;
+  const indexBuilds = statements.filter(isBlockingIndexBuild).length;
+
+  if (total > OPS_FIT_LIMITS.maxStatements) {
+    return {
+      fits: false,
+      reason:
+        `this edge is ${total} statements — past the ~${OPS_FIT_LIMITS.maxStatements}-statement ops-Lambda budget ` +
+        `(the write runs inside a 900-second Lambda; a large edge rolls back clean but wastes the wait). ` +
+        `Re-run with --direct — same ceremony, executed CLI-side with an unbounded clock, still credential-free.`,
+    };
+  }
+  if (indexBuilds > OPS_FIT_LIMITS.maxIndexBuilds) {
+    return {
+      fits: false,
+      reason:
+        `this edge builds ${indexBuilds} indexes — index builds scale with table size and dominate the ops-Lambda ` +
+        `runtime (past ~${OPS_FIT_LIMITS.maxIndexBuilds} the 900-second ceiling is at risk). ` +
+        `Re-run with --direct — same ceremony, executed CLI-side with an unbounded clock, still credential-free.`,
+    };
+  }
+  return { fits: true };
+}