@kontextmind/kxm 0.7.50 → 0.7.52

package/plugins/kxm/dist/runtime-supervisor.js

@@ -17645,12 +17645,76 @@ function openDatabase(file, description, spec) {
   }
 }
 var activeTransactions = /* @__PURE__ */ new WeakSet();
-function withDatabaseTransaction(database, work, mode = "IMMEDIATE") {
+var TRANSACTION_BUSY_BACKOFF_MS = 1e3;
+function monotonicNowMs() {
+  return Number(process.hrtime.bigint() / 1000000n);
+}
+var transactionThrottles = /* @__PURE__ */ new WeakMap();
+function finiteNow(clock, label) {
+  const now = clock();
+  if (typeof now !== "number" || !Number.isFinite(now)) {
+    throw databaseError(
+      "runtime_transaction_clock_invalid",
+      "transaction",
+      `${label} must return a finite monotonic number; got ${String(now)}`
+    );
+  }
+  return now;
+}
+var CONTENTION_PRIMARY_CODES = [5, 6, 15];
+var CONTENTION_SYMBOLIC_NAMES = /^SQLITE_(?:BUSY|LOCKED|PROTOCOL)(?:_[A-Z0-9]+)?$/;
+var SQLITE_RESULT_NAMES = /^SQLITE_[A-Z][A-Z0-9_]*$/;
+var CONTENTION_MESSAGES = /^(?:database is locked|database table is locked|locking protocol|SQLITE_BUSY|SQLITE_LOCKED|SQLITE_PROTOCOL)(?:$|[\s.:])/i;
+function isTransactionContention(error) {
+  const carrier = error;
+  for (const value of [carrier?.errcode, carrier?.errCode, carrier?.errno]) {
+    if (typeof value === "number" && Number.isInteger(value)) return CONTENTION_PRIMARY_CODES.includes(value & 255);
+  }
+  for (const value of [carrier?.code, carrier?.name]) {
+    if (typeof value === "string" && SQLITE_RESULT_NAMES.test(value)) {
+      return CONTENTION_SYMBOLIC_NAMES.test(value);
+    }
+  }
+  return CONTENTION_MESSAGES.test(error instanceof Error ? error.message : String(error));
+}
+function withDatabaseTransaction(database, work, mode = "IMMEDIATE", clock = monotonicNowMs) {
   if (activeTransactions.has(database)) {
     throw databaseError("runtime_transaction_nested", "transaction", "nested transactions are not allowed");
   }
+  if (mode !== "DEFERRED") {
+    const deadlines = transactionThrottles.get(database);
+    const until = deadlines?.get(clock);
+    if (until !== void 0) {
+      const remaining = until - finiteNow(clock, "the transaction clock");
+      if (remaining > 0) {
+        throw databaseError(
+          "runtime_transaction_busy",
+          "transaction",
+          `a previous BEGIN was blocked on this database; retry deferred ${String(remaining)}ms`
+        );
+      }
+      deadlines?.delete(clock);
+    }
+  }
+  try {
+    database.exec(`BEGIN ${mode}`);
+  } catch (error) {
+    if (!isTransactionContention(error)) throw error;
+    const now = finiteNow(clock, "the transaction clock");
+    let deadlines = transactionThrottles.get(database);
+    if (deadlines === void 0) {
+      deadlines = /* @__PURE__ */ new WeakMap();
+      transactionThrottles.set(database, deadlines);
+    }
+    deadlines.set(clock, now + TRANSACTION_BUSY_BACKOFF_MS);
+    throw databaseError(
+      "runtime_transaction_busy",
+      "transaction",
+      `BEGIN ${mode} blocked by another transaction: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
   activeTransactions.add(database);
-  database.exec(`BEGIN ${mode}`);
+  if (mode !== "DEFERRED") transactionThrottles.get(database)?.delete(clock);
   try {
     const result = work();
     database.exec("COMMIT");
@@ -18558,7 +18622,14 @@ var KxmRunEventStore = class {
     `).get(projectId, coordinatorId, idempotencyKey);
     return row ? intakeFromRow(row) : void 0;
   }
-  /** Intake rows in the given dispatch states, in arrival order (replay-safe). */
+  /**
+   * Intake rows in the given dispatch states, in arrival order (replay-safe).
+   *
+   * `rowid` gives same-store arrival order, which is what queue priority needs
+   * here. It is **not** a durable sequence: this repository backs stores up with
+   * `VACUUM INTO`, and a vacuum may renumber implicit rowids. An explicit
+   * immutable arrival sequence is tracked in the plan's schema-v6 follow-ups.
+   */
   intakeInStates(projectId, states, limit = 100) {
     if (states.length === 0) return [];
     const placeholders = states.map(() => "?").join(", ");

package/plugins/kxm/dist/runtime.js

@@ -17816,12 +17816,76 @@ function openDatabase(file, description, spec) {
   }
 }
 var activeTransactions = /* @__PURE__ */ new WeakSet();
-function withDatabaseTransaction(database, work, mode = "IMMEDIATE") {
+var TRANSACTION_BUSY_BACKOFF_MS = 1e3;
+function monotonicNowMs() {
+  return Number(process.hrtime.bigint() / 1000000n);
+}
+var transactionThrottles = /* @__PURE__ */ new WeakMap();
+function finiteNow(clock, label) {
+  const now = clock();
+  if (typeof now !== "number" || !Number.isFinite(now)) {
+    throw databaseError(
+      "runtime_transaction_clock_invalid",
+      "transaction",
+      `${label} must return a finite monotonic number; got ${String(now)}`
+    );
+  }
+  return now;
+}
+var CONTENTION_PRIMARY_CODES = [5, 6, 15];
+var CONTENTION_SYMBOLIC_NAMES = /^SQLITE_(?:BUSY|LOCKED|PROTOCOL)(?:_[A-Z0-9]+)?$/;
+var SQLITE_RESULT_NAMES = /^SQLITE_[A-Z][A-Z0-9_]*$/;
+var CONTENTION_MESSAGES = /^(?:database is locked|database table is locked|locking protocol|SQLITE_BUSY|SQLITE_LOCKED|SQLITE_PROTOCOL)(?:$|[\s.:])/i;
+function isTransactionContention(error) {
+  const carrier = error;
+  for (const value of [carrier?.errcode, carrier?.errCode, carrier?.errno]) {
+    if (typeof value === "number" && Number.isInteger(value)) return CONTENTION_PRIMARY_CODES.includes(value & 255);
+  }
+  for (const value of [carrier?.code, carrier?.name]) {
+    if (typeof value === "string" && SQLITE_RESULT_NAMES.test(value)) {
+      return CONTENTION_SYMBOLIC_NAMES.test(value);
+    }
+  }
+  return CONTENTION_MESSAGES.test(error instanceof Error ? error.message : String(error));
+}
+function withDatabaseTransaction(database, work, mode = "IMMEDIATE", clock = monotonicNowMs) {
   if (activeTransactions.has(database)) {
     throw databaseError("runtime_transaction_nested", "transaction", "nested transactions are not allowed");
   }
+  if (mode !== "DEFERRED") {
+    const deadlines = transactionThrottles.get(database);
+    const until = deadlines?.get(clock);
+    if (until !== void 0) {
+      const remaining = until - finiteNow(clock, "the transaction clock");
+      if (remaining > 0) {
+        throw databaseError(
+          "runtime_transaction_busy",
+          "transaction",
+          `a previous BEGIN was blocked on this database; retry deferred ${String(remaining)}ms`
+        );
+      }
+      deadlines?.delete(clock);
+    }
+  }
+  try {
+    database.exec(`BEGIN ${mode}`);
+  } catch (error) {
+    if (!isTransactionContention(error)) throw error;
+    const now = finiteNow(clock, "the transaction clock");
+    let deadlines = transactionThrottles.get(database);
+    if (deadlines === void 0) {
+      deadlines = /* @__PURE__ */ new WeakMap();
+      transactionThrottles.set(database, deadlines);
+    }
+    deadlines.set(clock, now + TRANSACTION_BUSY_BACKOFF_MS);
+    throw databaseError(
+      "runtime_transaction_busy",
+      "transaction",
+      `BEGIN ${mode} blocked by another transaction: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
   activeTransactions.add(database);
-  database.exec(`BEGIN ${mode}`);
+  if (mode !== "DEFERRED") transactionThrottles.get(database)?.delete(clock);
   try {
     const result = work();
     database.exec("COMMIT");
@@ -18998,7 +19062,14 @@ var KxmRunEventStore = class {
     `).get(projectId, coordinatorId, idempotencyKey);
     return row ? intakeFromRow(row) : void 0;
   }
-  /** Intake rows in the given dispatch states, in arrival order (replay-safe). */
+  /**
+   * Intake rows in the given dispatch states, in arrival order (replay-safe).
+   *
+   * `rowid` gives same-store arrival order, which is what queue priority needs
+   * here. It is **not** a durable sequence: this repository backs stores up with
+   * `VACUUM INTO`, and a vacuum may renumber implicit rowids. An explicit
+   * immutable arrival sequence is tracked in the plan's schema-v6 follow-ups.
+   */
   intakeInStates(projectId, states, limit = 100) {
     if (states.length === 0) return [];
     const placeholders = states.map(() => "?").join(", ");
@@ -30289,6 +30360,7 @@ export {
   SUBAGENT_TYPES,
   SteelClient,
   SubagentManager,
+  TRANSACTION_BUSY_BACKOFF_MS,
   VIEWPORT_PRESETS,
   WIN_NPM_INNER_EXE,
   acceptKxmRun,
@@ -30344,6 +30416,7 @@ export {
   hashKxmTokenProof,
   isKnownHarnessId,
   isKxmRuntimeContextClosed,
+  isTransactionContention,
   isWindowsHarnessShim,
   kxmDeclaredExecutorIds,
   kxmDeclaredRepositoryIds,

package/plugins/kxm/dist/server.js

@@ -11537,12 +11537,76 @@ function openDatabase(file, description, spec) {
   }
 }
 var activeTransactions = /* @__PURE__ */ new WeakSet();
-function withDatabaseTransaction(database, work, mode = "IMMEDIATE") {
+var TRANSACTION_BUSY_BACKOFF_MS = 1e3;
+function monotonicNowMs() {
+  return Number(process.hrtime.bigint() / 1000000n);
+}
+var transactionThrottles = /* @__PURE__ */ new WeakMap();
+function finiteNow(clock, label) {
+  const now = clock();
+  if (typeof now !== "number" || !Number.isFinite(now)) {
+    throw databaseError(
+      "runtime_transaction_clock_invalid",
+      "transaction",
+      `${label} must return a finite monotonic number; got ${String(now)}`
+    );
+  }
+  return now;
+}
+var CONTENTION_PRIMARY_CODES = [5, 6, 15];
+var CONTENTION_SYMBOLIC_NAMES = /^SQLITE_(?:BUSY|LOCKED|PROTOCOL)(?:_[A-Z0-9]+)?$/;
+var SQLITE_RESULT_NAMES = /^SQLITE_[A-Z][A-Z0-9_]*$/;
+var CONTENTION_MESSAGES = /^(?:database is locked|database table is locked|locking protocol|SQLITE_BUSY|SQLITE_LOCKED|SQLITE_PROTOCOL)(?:$|[\s.:])/i;
+function isTransactionContention(error) {
+  const carrier = error;
+  for (const value of [carrier?.errcode, carrier?.errCode, carrier?.errno]) {
+    if (typeof value === "number" && Number.isInteger(value)) return CONTENTION_PRIMARY_CODES.includes(value & 255);
+  }
+  for (const value of [carrier?.code, carrier?.name]) {
+    if (typeof value === "string" && SQLITE_RESULT_NAMES.test(value)) {
+      return CONTENTION_SYMBOLIC_NAMES.test(value);
+    }
+  }
+  return CONTENTION_MESSAGES.test(error instanceof Error ? error.message : String(error));
+}
+function withDatabaseTransaction(database, work, mode = "IMMEDIATE", clock = monotonicNowMs) {
   if (activeTransactions.has(database)) {
     throw databaseError("runtime_transaction_nested", "transaction", "nested transactions are not allowed");
   }
+  if (mode !== "DEFERRED") {
+    const deadlines = transactionThrottles.get(database);
+    const until = deadlines?.get(clock);
+    if (until !== void 0) {
+      const remaining = until - finiteNow(clock, "the transaction clock");
+      if (remaining > 0) {
+        throw databaseError(
+          "runtime_transaction_busy",
+          "transaction",
+          `a previous BEGIN was blocked on this database; retry deferred ${String(remaining)}ms`
+        );
+      }
+      deadlines?.delete(clock);
+    }
+  }
+  try {
+    database.exec(`BEGIN ${mode}`);
+  } catch (error) {
+    if (!isTransactionContention(error)) throw error;
+    const now = finiteNow(clock, "the transaction clock");
+    let deadlines = transactionThrottles.get(database);
+    if (deadlines === void 0) {
+      deadlines = /* @__PURE__ */ new WeakMap();
+      transactionThrottles.set(database, deadlines);
+    }
+    deadlines.set(clock, now + TRANSACTION_BUSY_BACKOFF_MS);
+    throw databaseError(
+      "runtime_transaction_busy",
+      "transaction",
+      `BEGIN ${mode} blocked by another transaction: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
   activeTransactions.add(database);
-  database.exec(`BEGIN ${mode}`);
+  if (mode !== "DEFERRED") transactionThrottles.get(database)?.delete(clock);
   try {
     const result = work();
     database.exec("COMMIT");

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.50",
+  "version": "0.7.52",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/src/cli/hub.ts

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync
 import { join, resolve } from "node:path";
 import { redactSecrets } from "../redact.ts";
 import { defaultProjectName } from "../project-name.ts";
-import { resolveClientHubAuthToken } from "../hub-env.ts";
+import { hasClientHubCredential, resolveClientHubAuthToken } from "../hub-env.ts";
 import { agentWorker, type Worker } from "../envelope.ts";
 import { MESH_TUI_PANELS, runMeshTui, type MeshTuiPanel } from "../tui.ts";
 import { formatSessionBriefText, loadSessionBriefAsync, type SessionHubStatus } from "../session-work.ts";
@@ -12,6 +12,7 @@ import {
   HubBindingError,
   hubBindingFile,
   probeHubHealth,
+  hubBindingScope,
   readHubBinding,
   removeHubBinding,
   validateHubUrl,
@@ -104,8 +105,22 @@ export async function refreshKxmUpdateNotice(runtime: Runtime, config?: KxmUpdat
 export async function cmdStatus(runtime: Runtime): Promise<number> {
   const health = await hubGet(`${runtime.serverUrl}/health`, runtime.fetchImpl);
   const ready = await hubGet(`${runtime.serverUrl}/ready`, runtime.fetchImpl);
-  const payload = { ok: health.ok && ready.ok, command: "hub view", health: health.body, ready: ready.body };
-  print(runtime.io, runtime.json, payload, `hub health=${health.ok} ready=${ready.ok}`);
+  // Scope on the status line deliberately: "attached across a network" and "attached on
+  // this box" are otherwise indistinguishable, and only one of them ships a token.
+  // Scope is a property of the URL actually contacted, not of whichever file the
+  // binding came from: KXM_SERVER_URL overrides the binding, and labelling the binding
+  // while probing an override would report "loopback" about a remote request.
+  const effectiveScope = hubBindingScope(runtime.serverUrl);
+  const overridden = Boolean(runtime.boundHubUrl && runtime.boundHubUrl !== runtime.serverUrl);
+  const payload = {
+    ok: health.ok && ready.ok,
+    command: "hub view",
+    target: { url: runtime.serverUrl, scope: effectiveScope, ...(overridden ? { source: "env" } : {}) },
+    health: health.body,
+    ready: ready.body,
+  };
+  print(runtime.io, runtime.json, payload,
+    `hub health=${health.ok} ready=${ready.ok} · ${effectiveScope} hub${overridden ? " (KXM_SERVER_URL)" : ""}`);
   return payload.ok ? 0 : 1;
 }
 
@@ -191,6 +206,10 @@ export function formatHubBindHealth(health: HubHealth): string {
   return "health=unknown (no reply within 300 ms)";
 }
 
+/** Kept in one place so the JSON payload and the prose line cannot drift apart. */
+const HUB_BIND_UNAUTHENTICATED_HINT =
+  "export KXM_AUTH_TOKEN (or point KXM_STATE_HOME at the hub-env record that already holds one), then re-run; the hub itself requires a token beyond loopback";
+
 export async function cmdHubBind(runtime: Runtime, rawUrl: string): Promise<number> {
   let url: string;
   try {
@@ -207,14 +226,73 @@ export async function cmdHubBind(runtime: Runtime, rawUrl: string): Promise<numb
     }
     throw error;
   }
+  const scope = hubBindingScope(url);
+  // Scope-scoped on purpose, and only for **this command**. A remote binding puts a
+  // bearer on a network path, so it is refused when nothing can authenticate it; a
+  // stored-but-unusable URL otherwise reads later like a network fault and gets debugged
+  // as one. Loopback is not consulted here because a loopback URL puts nothing on a wire —
+  // not because credentials are never resolved locally: other client paths still call
+  // `resolveClientHubAuthToken` regardless of scope, so a damaged host record can still
+  // fail `kxm peer list` on loopback. Narrowing the claim is the point; the first version
+  // of this guard checked the record *before* the scope and refused loopback binds that had
+  // always worked, which is a regression against behaviour predating this slice.
+  if (scope === "remote") {
+    // The project that will actually authenticate: a record holding only another
+    // project's token cannot authorise this one.
+    const bindProject = defaultProjectName(runtime.dirs.workdir, runtime.env) || "project";
+    let credentialReady = false;
+    try {
+      credentialReady = hasClientHubCredential(runtime.env, bindProject);
+    } catch (error) {
+      // A malformed record is a readable configuration failure, not an uncaught throw
+      // past a user-facing entry point.
+      print(
+        runtime.io,
+        runtime.json,
+        {
+          ok: false,
+          command: "hub bind",
+          error: "hub_credential_unreadable",
+          url,
+          scope,
+          nextAction: "repair_hub_env_record",
+          hint: `${error instanceof Error ? error.message : String(error)}; no binding was written`,
+        },
+        `cannot read the hub credential: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return 2;
+    }
+    if (!credentialReady) {
+      print(
+        runtime.io,
+        runtime.json,
+        {
+          ok: false,
+          command: "hub bind",
+          error: "hub_bind_unauthenticated",
+          url,
+          scope,
+          project: bindProject,
+          // The hint belongs in the payload, not only the prose line: under --json the
+          // prose is suppressed, and a refusal that names no next step gets debugged by
+          // reading source.
+          nextAction: "export_kxm_auth_token",
+          hint: `${HUB_BIND_UNAUTHENTICATED_HINT} (needs a token for project ${bindProject})`,
+        },
+        `refusing to bind remote hub ${url} with no credential for project ${bindProject}; ${HUB_BIND_UNAUTHENTICATED_HINT}`,
+      );
+      return 2;
+    }
+  }
   const file = hubBindingFile(runtime.env);
   if (runtime.dryRun) {
-    print(runtime.io, runtime.json, { ok: true, command: "hub bind", dryRun: true, url, file }, `would bind hub ${url}`);
+    print(runtime.io, runtime.json, { ok: true, command: "hub bind", dryRun: true, url, scope, file }, `would bind hub ${url} (${scope})`);
     return 0;
   }
   writeHubBinding({ schema: HUB_BINDING_SCHEMA, url, boundAt: new Date().toISOString() }, runtime.env);
   const { health, probeMs } = await probeHubHealth(url, runtime.fetchImpl);
-  print(runtime.io, runtime.json, { ok: true, command: "hub bind", url, file, health, probeMs }, `bound hub ${url} · ${formatHubBindHealth(health)}`);
+  print(runtime.io, runtime.json, { ok: true, command: "hub bind", url, scope, file, health, probeMs },
+    `bound hub ${url} · ${scope} · ${formatHubBindHealth(health)}${scope === "remote" ? " · token leaves this machine" : ""}`);
   return 0;
 }
 
@@ -540,6 +618,7 @@ export async function cmdSessionBrief(runtime: Runtime, options: { status?: bool
       evidence: health === "unknown" ? "timeout" : "probed",
       online: health === "on",
       url: targetUrl,
+      scope: hubBindingScope(targetUrl),
     };
   } else {
     hub = { state: "off", evidence: "unconfigured", online: false };

package/plugins/kxm/src/database.ts

@@ -213,21 +213,226 @@ export function openDatabase(file: string, description: string, spec: DatabaseSc
 
 const activeTransactions = new WeakSet<DatabaseSync>();
 
+/**
+ * How long a connection refuses to retry a `BEGIN` that lost the write race.
+ *
+ * SQLite's busy timeout is per connection, so a `BEGIN` against a locked
+ * database waits the full timeout before failing. Callers that recover from a
+ * lost write open several transactions in a row; without this window each of
+ * them pays the timeout, and a suite run showed that turning one 4-second test
+ * into 17 minutes. The old code got that speed by accident — it left the
+ * connection permanently marked as in-transaction after a failed `BEGIN`, which
+ * is the defect fixed below — so the backoff replaces the fast-fail without
+ * re-introducing the poison.
+ *
+ * Two limits, both deliberate:
+ * - It is a **throttle, not a queue**. A caller whose lock cleared 1 ms later is
+ *   still refused for the rest of the window; the refusal is explicit
+ *   (`runtime_transaction_busy`, message says `retry deferred`) and bounded by
+ *   this constant. A retry after the window may pay the busy timeout again.
+ * - It is **per connection object, in this process**. It is not a cross-process
+ *   backoff and does not leak to another connection to the same file.
+ */
+export const TRANSACTION_BUSY_BACKOFF_MS = 1_000;
+
+/**
+ * Monotonic elapsed time, deliberately not `Date.now()`.
+ *
+ * A wall-clock step backwards would otherwise keep a long-gone write lock
+ * refusing transactions until real time caught up, and a step forward would end
+ * the throttle early. `hrtime.bigint()` is relative to an arbitrary past origin
+ * and never moves backwards, so the window is bounded by
+ * {@link TRANSACTION_BUSY_BACKOFF_MS} no matter what the system clock does.
+ *
+ * Injectable: production callers never pass it, and a test drives it directly so
+ * the window is stepped rather than raced or slept through.
+ */
+export type MonotonicClock = () => number;
+
+function monotonicNowMs(): number {
+  return Number(process.hrtime.bigint() / 1_000_000n);
+}
+
+/**
+ * Pending throttle per connection, **keyed by the clock that armed it**.
+ *
+ * The nesting is the fix, not tidiness. A deadline is a number from *some* clock,
+ * and the injectable `clock` exists only so a test can step the window; comparing
+ * a deadline armed by one clock against a reading taken from another is how an
+ * injected "one hour from now" throttles a production caller that never passed a
+ * clock at all — and how that same caller could clear a deadline it never armed.
+ * Each clock domain therefore gets its own deadline and can only read, expire or
+ * replace its own. The inner map is **weak in the clock**: it keeps no otherwise
+ * unreachable clock function alive, so an attempt that builds a fresh closure per
+ * call leaves nothing behind once that closure is collected. A clock that *is*
+ * retained keeps its entry until it expires or is replaced — collection is neither
+ * immediate nor size-bounded, and no committed test measures any of this, because no
+ * production caller passes a clock.
+ */
+const transactionThrottles = new WeakMap<DatabaseSync, WeakMap<MonotonicClock, number>>();
+
+/**
+ * A clock reading this helper can reason about.
+ *
+ * Scope, stated as measured rather than as a slogan. The clock is read at **two call
+ * sites**: checking an existing deadline on a non-`DEFERRED` attempt, and arming after a
+ * contended `BEGIN` failure. Reads per call, each reproduced by an assertion in
+ * `test/core/intake.test.ts`: clean success with no pending entry 0; successful
+ * `DEFERRED`, pending entry present or not, 0; fresh contention 1; refusal inside a window
+ * 1; an expired deadline followed by renewed contention 2 in that call; a permanent
+ * `BEGIN` failure with no pending entry 0; a nested-transaction rejection 0.
+ *
+ * Which means it is wrong in both directions to say either "every `BEGIN` validates the
+ * clock" or "the *only* transaction that skips it is a clean uncontended success" — the
+ * second was mine, twice, and the second correction to it was still a slogan. The tests
+ * count; the prose only points at them. Production cannot reach the guard at all, because
+ * the default is `hrtime`; it exists so the injectable seam cannot become a silent
+ * bypass.
+ */
+function finiteNow(clock: MonotonicClock, label: string): number {
+  const now = clock();
+  if (typeof now !== "number" || !Number.isFinite(now)) {
+    throw databaseError(
+      "runtime_transaction_clock_invalid",
+      "transaction",
+      `${label} must return a finite monotonic number; got ${String(now)}`,
+    );
+  }
+  return now;
+}
+
+/**
+ * Is this `BEGIN` failure contention for the write lock, as opposed to a
+ * programming or environment error?
+ *
+ * Only contention may be retried, and only contention earns the throttle window.
+ * Anything else — "cannot start a transaction within a transaction", a closed
+ * connection, a miscompiled statement — must surface unchanged, or a permanent
+ * bug looks like a transient one and the caller retries forever.
+ *
+ * SQLite's **numeric result code decides** where one exists, because it is stable
+ * across versions while message text is not: the primary code is `code & 0xff`, so
+ * extended forms land on their primaries — `SQLITE_BUSY_RECOVERY` (261) and
+ * `SQLITE_BUSY_SNAPSHOT` (517) on `SQLITE_BUSY` (5), `SQLITE_LOCKED_SHAREDCACHE`
+ * (262) on `SQLITE_LOCKED` (6). `SQLITE_PROTOCOL` (15) is included deliberately:
+ * SQLite raises it when repeated attempts to start a transaction under WAL exhaust
+ * the retry count, which is a lock-acquisition retry condition, not a broken
+ * database.
+ *
+ * Where both runtimes expose one, **the number wins over the text**: Node spells it
+ * `errcode`, `bun:sqlite` spells it `errno` (verified on Bun 1.3.14, where a shared-
+ * cache `BEGIN` arrives as `errno: 262`, `code: "SQLITE_LOCKED_SHAREDCACHE"`,
+ * message "database schema is locked: shared"). A symbolic `code`/`name` of the form
+ * `SQLITE_BUSY*`/`SQLITE_LOCKED*`/`SQLITE_PROTOCOL*` is accepted next, and bare
+ * message matching is the last resort — applied only when neither exists, so a
+ * wrapper that merely quotes "database is locked" alongside a permanent code is not
+ * mistaken for contention.
+ *
+ * Deliberately **not** contention: `SQLITE_FULL` / "database or disk is full",
+ * "unable to open database file", and WAL shared-memory I/O failures. Those stay
+ * broken until something outside this connection changes.
+ */
+/** Node: `errcode`. Bun: `errno`. Both spell the extended code as a number. */
+const CONTENTION_PRIMARY_CODES: readonly number[] = [5, 6, 15];
+/** `bun:sqlite` puts the symbolic name in `code`; Node puts its own kind there. */
+const CONTENTION_SYMBOLIC_NAMES = /^SQLITE_(?:BUSY|LOCKED|PROTOCOL)(?:_[A-Z0-9]+)?$/;
+/** Any SQLite result name. If one is present it decides, so text cannot argue. */
+const SQLITE_RESULT_NAMES = /^SQLITE_[A-Z][A-Z0-9_]*$/;
+const CONTENTION_MESSAGES =
+  /^(?:database is locked|database table is locked|locking protocol|SQLITE_BUSY|SQLITE_LOCKED|SQLITE_PROTOCOL)(?:$|[\s.:])/i;
+
+export function isTransactionContention(error: unknown): boolean {
+  const carrier = error as { errcode?: unknown; errCode?: unknown; errno?: unknown; code?: unknown; name?: unknown }
+    | undefined;
+  // A numeric code wins first, then a symbolic result name, and both win **over the
+  // message**: `errno` is what `bun:sqlite` exposes for the extended result code while
+  // its `code` field holds the symbolic name, and Node spells the number `errcode`.
+  // All three properties are read; what the list orders is which **integer value
+  // decides** — a present `errcode` outranks `errCode`, which outranks `errno`, and a
+  // later number is never consulted. Text is consulted only when the error carries
+  // neither a number nor a SQLite result name, so no wrapper quoting an older
+  // "database is locked" can outvote a code on either runtime.
+  for (const value of [carrier?.errcode, carrier?.errCode, carrier?.errno]) {
+    if (typeof value === "number" && Number.isInteger(value)) return CONTENTION_PRIMARY_CODES.includes(value & 0xff);
+  }
+  for (const value of [carrier?.code, carrier?.name]) {
+    // A result **name** is as authoritative as a number, and in both directions:
+    // `SQLITE_FULL` wearing a "database is locked" message is not contention. Node
+    // spells its own error kind `ERR_SQLITE_ERROR`, which is deliberately not a
+    // SQLite result name and so never reaches a verdict here.
+    if (typeof value === "string" && SQLITE_RESULT_NAMES.test(value)) {
+      return CONTENTION_SYMBOLIC_NAMES.test(value);
+    }
+  }
+  return CONTENTION_MESSAGES.test(error instanceof Error ? error.message : String(error));
+}
+
 export function withDatabaseTransaction<T>(
   database: DatabaseSync,
   work: () => T,
   mode: "IMMEDIATE" | "DEFERRED" | "EXCLUSIVE" = "IMMEDIATE",
+  clock: MonotonicClock = monotonicNowMs,
 ): T {
   if (activeTransactions.has(database)) {
     throw databaseError("runtime_transaction_nested", "transaction", "nested transactions are not allowed");
   }
+  // A DEFERRED BEGIN takes no write lock, so it is exempt from the *check*: refusing
+  // it would deny legitimate work over a contention it did not ask for. Exempt from
+  // the check only — shared-cache schema locks can still make a deferred `BEGIN`
+  // fail, and that failure arms a deadline like any other, because the next attempt
+  // would stall the same way.
+  if (mode !== "DEFERRED") {
+    const deadlines = transactionThrottles.get(database);
+    const until = deadlines?.get(clock);
+    if (until !== undefined) {
+      const remaining = until - finiteNow(clock, "the transaction clock");
+      if (remaining > 0) {
+        throw databaseError(
+          "runtime_transaction_busy",
+          "transaction",
+          `a previous BEGIN was blocked on this database; retry deferred ${String(remaining)}ms`,
+        );
+      }
+      deadlines?.delete(clock);
+    }
+  }
+  // Claim the marker only once BEGIN has succeeded. If BEGIN throws — another
+  // writer held the database past the busy timeout — a connection that never
+  // entered a transaction must not be left permanently marked as inside one,
+  // which would fail every later transaction on it with a misleading
+  // "nested" error. `finally` cannot cover this: it only runs after the try.
+  try {
+    database.exec(`BEGIN ${mode}`);
+  } catch (error) {
+    if (!isTransactionContention(error)) throw error;
+    const now = finiteNow(clock, "the transaction clock");
+    let deadlines = transactionThrottles.get(database);
+    if (deadlines === undefined) {
+      deadlines = new WeakMap<MonotonicClock, number>();
+      transactionThrottles.set(database, deadlines);
+    }
+    deadlines.set(clock, now + TRANSACTION_BUSY_BACKOFF_MS);
+    throw databaseError(
+      "runtime_transaction_busy",
+      "transaction",
+      `BEGIN ${mode} blocked by another transaction: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
   activeTransactions.add(database);
-  database.exec(`BEGIN ${mode}`);
+  // A successful write-mode BEGIN means this connection is holding the slot, so any
+  // earlier contention is over. A DEFERRED success proves nothing about the write
+  // lock and must not clear a throttle that another caller's contention armed.
+  if (mode !== "DEFERRED") transactionThrottles.get(database)?.delete(clock);
   try {
     const result = work();
     database.exec("COMMIT");
     return result;
   } catch (error) {
+    // A failed ROLLBACK usually means the connection is gone. Clearing the marker
+    // is bookkeeping, not proof: it does **not** show SQLite exited the
+    // transaction, and nothing here invalidates a handle whose rollback failed.
+    // Pre-existing, named rather than papered over — the caller receives the
+    // original error.
     try { database.exec("ROLLBACK"); } catch { /* ignore rollback error if connection dead */ }
     throw error;
   } finally {