@oar-sh/oar 0.9.21 → 0.9.23

package/server/services/cloudflared-tunnel-service.mjs

@@ -211,6 +211,9 @@ export function createCloudflaredTunnelManager({
   io = null,
   logger = console,
   runtimeShutdownRef = () => false,
+  // The tunnel stopped blocking queue delivery (it connected): the relay
+  // hands out what waited for it.
+  onBlockingLifted = () => {},
   platform = process.platform,
   spawnImpl = spawn,
   nowIso = () => new Date().toISOString(),
@@ -267,7 +270,11 @@ export function createCloudflaredTunnelManager({
   };
 
   const updateBlockingState = () => {
+    const wasBlocking = state.blocking;
     state.blocking = state.required && state.mode === 'managed' && !state.connected;
+    if (wasBlocking && !state.blocking) {
+      try { onBlockingLifted(); } catch {}
+    }
   };
 
   const scheduleReconnect = (spawnTunnel, { slowest = false } = {}) => {

package/server/services/earlier-database-service.mjs

@@ -12,7 +12,7 @@ import { resolveStateLayout } from './oar-state-layout.mjs';
 import { defaultIsProcessAlive, lockHolderMayRun, processStartedAt as defaultProcessStartedAt } from './relay-singleton-guard.mjs';
 
 const SHA256_NAME = /^[a-f0-9]{64}$/;
-// The install-time rescue's copies (package-data-rescue.mjs), in the data folder.
+// The copies the install-time rescue of 0.9.14 to 0.9.22 made, in the data folder.
 export const RESCUE_DIR_NAME = 'rescued-package-data';
 // What was looked at already: never offered again unless it changed.
 export const CHECKED_FILE = 'earlier-databases.json';

package/server/services/file-serving.mjs

@@ -60,6 +60,19 @@ export function withFileVersion(url, version) {
   return appendUrlParam(String(url || ''), 'v', String(version || ''));
 }
 
+/**
+ * One of the relay's own files (sw.js, the socket.io client) through
+ * res.sendFile, rooted at its folder. Given a bare absolute path, express 5's
+ * send refuses any path with a dot folder in it (dotfiles 'ignore' looks at
+ * every segment without a root): a 404 for an install under ~/.oar, nvm or
+ * ~/.npm-global. With the folder as root only the file name is looked at.
+ */
+export function sendOwnFile(res, absolutePath, next) {
+  res.sendFile(path.basename(absolutePath), { root: path.dirname(absolutePath) }, (error) => {
+    if (error) next(error);
+  });
+}
+
 /**
  * `cacheControl` replaces the no-store default for content whose URL names
  * its bytes (an upload addressed by its hash): such an answer may be kept.

package/server/services/idle-timers.mjs

@@ -0,0 +1,184 @@
+'use strict';
+
+// Timers a relay keeps only while there is something to time: the CLI
+// presence deadline and the intervals armed by work and disarmed by their own
+// tick. An idle relay runs neither.
+
+// ─── CLI presence ──────────────────────────────────────────────────────────────
+
+// Whether "the CLI" (the relay's workers) has been heard from recently, kept
+// without a polling timer. Every touch moves the last-seen time; one one-shot
+// deadline timer, armed only while something was seen, notices when the
+// window ran out. A deadline that fires early (a touch moved last-seen) arms
+// again for the remainder, so an online relay wakes about once per window and
+// an offline one not at all.
+//
+// The window depends on the worker sockets: an idle worker beats only every
+// 30 s (shared/worker-runtime/worker-keepalive.mjs), so while a worker socket
+// is open the window is wide enough for one lost beat. With no socket left a
+// relay whose workers are all gone still reads offline within the short
+// window, as before.
+
+export const CLI_ONLINE_WINDOW_MS = 10_000;
+export const CLI_ONLINE_WINDOW_WITH_WORKER_SOCKETS_MS = 45_000;
+
+export function createCliPresence({
+  windowMs = CLI_ONLINE_WINDOW_MS,
+  socketWindowMs = CLI_ONLINE_WINDOW_WITH_WORKER_SOCKETS_MS,
+  // Called once when the window ran out after a touch (the deadline timer, or
+  // the last worker socket closing). The presence is cleared before the call.
+  onExpired = () => {},
+  now = () => Date.now(),
+  setTimeoutImpl = setTimeout,
+  clearTimeoutImpl = clearTimeout,
+} = {}) {
+  let lastSeenMs = null;
+  let workerSocketCount = 0;
+  let deadlineTimer = null;
+
+  function currentWindowMs() {
+    return workerSocketCount > 0 ? socketWindowMs : windowMs;
+  }
+
+  function remainingMs() {
+    if (lastSeenMs === null) return 0;
+    return lastSeenMs + currentWindowMs() - now();
+  }
+
+  function disarm() {
+    if (!deadlineTimer) return;
+    clearTimeoutImpl(deadlineTimer);
+    deadlineTimer = null;
+  }
+
+  function arm(delayMs) {
+    disarm();
+    deadlineTimer = setTimeoutImpl(onDeadline, Math.max(1, delayMs));
+    deadlineTimer?.unref?.();
+  }
+
+  function expire() {
+    disarm();
+    lastSeenMs = null;
+    try { onExpired(); } catch {}
+  }
+
+  function onDeadline() {
+    deadlineTimer = null;
+    if (lastSeenMs === null) return;
+    const left = remainingMs();
+    if (left > 0) {
+      arm(left);
+      return;
+    }
+    expire();
+  }
+
+  function touch() {
+    lastSeenMs = now();
+    // An armed deadline is left alone: when it fires it finds the newer
+    // touch and arms again for what is left.
+    if (!deadlineTimer) arm(currentWindowMs());
+  }
+
+  /** The worker socket count changed: the window may have shrunk. */
+  function noteWorkerSocketCount(count) {
+    workerSocketCount = Math.max(0, Number(count) || 0);
+    if (lastSeenMs === null) return;
+    const left = remainingMs();
+    if (left <= 0) {
+      expire();
+      return;
+    }
+    arm(left);
+  }
+
+  /** Forget the last touch without calling onExpired (an explicit offline). */
+  function clear() {
+    disarm();
+    lastSeenMs = null;
+  }
+
+  function isFresh() {
+    return remainingMs() > 0;
+  }
+
+  return {
+    touch,
+    clear,
+    isFresh,
+    noteWorkerSocketCount,
+    status: () => ({
+      lastSeenMs,
+      workerSocketCount,
+      windowMs: currentWindowMs(),
+      armed: deadlineTimer !== null,
+    }),
+  };
+}
+
+// ─── Armable interval ──────────────────────────────────────────────────────────
+
+// An interval that runs only while there is something for it to do: armed by
+// whoever creates that work (a share viewer arriving, a pending row waiting
+// for its worker), disarmed by its own tick once the work is gone. An idle
+// relay then has no such timer at all. The timer is unref'd, and stop() (the
+// runtime's shutdown) disarms it for good.
+
+export function createArmableInterval({
+  intervalMs,
+  // One tick. Returns (or resolves to) `false` to disarm: nothing is left to
+  // do. Anything else keeps the interval running. An arm that lands while a
+  // tick is still running (the tick awaits) keeps the interval running even
+  // if that tick returns false: the work it was armed for may be newer than
+  // what the tick looked at.
+  tick,
+  onError = () => {},
+  setIntervalImpl = setInterval,
+  clearIntervalImpl = clearInterval,
+} = {}) {
+  if (typeof tick !== 'function') throw new Error('createArmableInterval requires tick');
+  const periodMs = Math.max(1, Number(intervalMs) || 1);
+  let timer = null;
+  let stopped = false;
+  let generation = 0;
+
+  function disarm() {
+    if (!timer) return;
+    clearIntervalImpl(timer);
+    timer = null;
+  }
+
+  async function runTick() {
+    const armedAt = generation;
+    let keep;
+    try {
+      keep = await tick();
+    } catch (error) {
+      try { onError(error); } catch {}
+      return;
+    }
+    if (keep === false && generation === armedAt) disarm();
+  }
+
+  function arm() {
+    if (stopped) return false;
+    generation += 1;
+    if (timer) return false;
+    timer = setIntervalImpl(() => { void runTick(); }, periodMs);
+    timer?.unref?.();
+    return true;
+  }
+
+  function stop() {
+    stopped = true;
+    disarm();
+  }
+
+  return {
+    arm,
+    disarm,
+    stop,
+    isArmed: () => timer !== null,
+  };
+}

package/server/services/native-addon-build-service.mjs

@@ -0,0 +1,224 @@
+/**
+ * better-sqlite3 13 ships its binary for linux (glibc and musl), darwin and
+ * win32 on x64 and arm64, and runs no install script. Anywhere else (Android
+ * under Termux, 32-bit ARM, FreeBSD) the first database open finds no binary
+ * and throws: the binding has to be compiled from the sources the package
+ * ships. OAR runs that build itself, after an update (the Update button,
+ * `oar update`) and as `oar build-native`, never as an install script of its
+ * own package: one would bring back the install-script warning every package
+ * scanner shows for OAR, and npm 12 skips it unless the user allows it.
+ *
+ * The build is node-gyp's, the one npm bundles (npx's as the fallback), in the
+ * package's own folder with `--force_build=1`, as the package's
+ * `build-release` script runs it. It needs Python 3, make and a C++ compiler.
+ */
+import { spawn as defaultSpawn } from 'child_process';
+import fs from 'fs';
+import { createRequire } from 'module';
+import path from 'path';
+
+import { killTree, runToCompletion, tailOf } from './cli-process-runner.mjs';
+
+export const BETTER_SQLITE3_PREBUILD_PLATFORMS = Object.freeze(['linux', 'darwin', 'win32']);
+export const BETTER_SQLITE3_PREBUILD_ARCHS = Object.freeze(['x64', 'arm64']);
+export const NATIVE_BUILD_COMMAND = 'oar build-native';
+// sqlite3.c is one large file: a phone takes minutes for it.
+export const NATIVE_BUILD_TIMEOUT_MS = 30 * 60_000;
+export const TERMUX_BUILD_TOOLS = 'pkg install python clang make';
+
+const BINDING_FILE = path.join('build', 'Release', 'better_sqlite3.node');
+
+/** True where better-sqlite3 has no prebuilt binary and must be compiled. */
+export function needsSourceBuild({ platform = process.platform, arch = process.arch } = {}) {
+  return !(BETTER_SQLITE3_PREBUILD_PLATFORMS.includes(platform) && BETTER_SQLITE3_PREBUILD_ARCHS.includes(arch));
+}
+
+/** The folder of the better-sqlite3 this package loads, or null. */
+export function resolveBetterSqlite3Dir({ packageRoot, requireFrom = createRequire } = {}) {
+  try {
+    const require = requireFrom(path.join(path.resolve(String(packageRoot || '.')), 'package.json'));
+    return path.dirname(require.resolve('better-sqlite3/package.json'));
+  } catch {
+    return null;
+  }
+}
+
+/** The error better-sqlite3 throws when it finds neither a prebuilt nor a built binary. */
+export function isMissingSqliteBindingError(error) {
+  const code = String(error?.code || '');
+  return (code === 'MODULE_NOT_FOUND' || code === 'ERR_DLOPEN_FAILED')
+    && /better_sqlite3\.node|better-sqlite3[\\/]prebuilds[\\/][^\\/]+\.node/.test(String(error?.message || ''));
+}
+
+/**
+ * The lines a relay prints, instead of a stack trace, when it cannot open a
+ * database because the binding is missing.
+ */
+export function missingSqliteBindingLines({ platform = process.platform, arch = process.arch, error = null } = {}) {
+  const target = `${platform}-${arch}`;
+  if (!needsSourceBuild({ platform, arch })) {
+    // There, but not loadable on this system. better-sqlite3 loads its
+    // prebuilt binding before a built one, so no build here would be used.
+    if (String(error?.code || '') === 'ERR_DLOPEN_FAILED') {
+      return [
+        `The SQLite binding that better-sqlite3 ships for ${target} does not load on this system (${String(error?.message || '').split('\n')[0]}).`,
+        'Its C library is too old for it, or the system is not one the binding supports.',
+        'Update the operating system, or run the relay on a supported one.',
+      ];
+    }
+    return [
+      `The SQLite binding of better-sqlite3 for ${target} is missing from the installed package (${String(error?.message || '').split('\n')[0]}).`,
+      'Reinstall OAR: npm install -g @oar-sh/oar',
+    ];
+  }
+  return [
+    `better-sqlite3 has no prebuilt SQLite binding for ${target}, and it has not been built here yet.`,
+    `Build it with: ${NATIVE_BUILD_COMMAND}`,
+    platform === 'android'
+      ? `It needs Python 3, make and a C++ compiler: ${TERMUX_BUILD_TOOLS}`
+      : 'It needs Python 3, make and a C++ compiler.',
+  ];
+}
+
+// The node-gyp that ships inside npm, beside this Node; null when there is none.
+function bundledNodeGyp({ execPath, platform, existsImpl, realpathImpl }) {
+  const pathImpl = platform === 'win32' ? path.win32 : path.posix;
+  const nodeDir = pathImpl.dirname(String(execPath || ''));
+  const npmRoots = [];
+  if (platform !== 'win32') {
+    // <prefix>/bin/npm is a link to <prefix>/lib/node_modules/npm/bin/npm-cli.js.
+    try { npmRoots.push(pathImpl.dirname(pathImpl.dirname(realpathImpl(pathImpl.join(nodeDir, 'npm'))))); } catch {}
+    npmRoots.push(pathImpl.join(nodeDir, '..', 'lib', 'node_modules', 'npm'));
+  } else {
+    npmRoots.push(pathImpl.join(nodeDir, 'node_modules', 'npm'));
+  }
+  for (const root of npmRoots) {
+    const file = pathImpl.join(root, 'node_modules', 'node-gyp', 'bin', 'node-gyp.js');
+    if (existsImpl(file)) return file;
+  }
+  return null;
+}
+
+/**
+ * How to run node-gyp: npm's own (npm_config_node_gyp when npm set it), else
+ * `npx --yes node-gyp`. Returns { command, args, env }.
+ */
+export function resolveNodeGypInvocation({
+  execPath = process.execPath,
+  platform = process.platform,
+  env = process.env,
+  existsImpl = fs.existsSync,
+  realpathImpl = fs.realpathSync,
+} = {}) {
+  const pathImpl = platform === 'win32' ? path.win32 : path.posix;
+  const nodeDir = pathImpl.dirname(String(execPath || ''));
+  const separator = platform === 'win32' ? ';' : ':';
+  const pathKey = Object.keys(env || {}).find((key) => key.toUpperCase() === 'PATH') || 'PATH';
+  // node-gyp runs `node` from the gyp files: this Node first on its PATH.
+  const childEnv = { ...env, [pathKey]: [nodeDir, String(env?.[pathKey] || '')].filter(Boolean).join(separator) };
+  // Node for Termux has no android_ndk_path in its common.gypi, which gyp
+  // then refuses as undefined; an empty one builds with Termux's own clang.
+  if (platform === 'android' && !/\bandroid_ndk_path=/.test(String(env?.GYP_DEFINES || ''))) {
+    childEnv.GYP_DEFINES = [String(env?.GYP_DEFINES || '').trim(), "android_ndk_path=''"].filter(Boolean).join(' ');
+  }
+  const fromNpm = String(env?.npm_config_node_gyp || '').trim();
+  const gyp = (fromNpm && existsImpl(fromNpm) ? fromNpm : null) || bundledNodeGyp({ execPath, platform, existsImpl, realpathImpl });
+  if (gyp) return { command: execPath, args: [gyp], env: childEnv };
+  if (platform === 'win32') {
+    // npx.cmd runs through a shell, which splits a path with a space in it
+    // (C:\Program Files): this Node with npm's npx-cli.js, else npx.cmd by name.
+    const npxCli = pathImpl.join(nodeDir, 'node_modules', 'npm', 'bin', 'npx-cli.js');
+    if (existsImpl(npxCli)) return { command: execPath, args: [npxCli, '--yes', 'node-gyp'], env: childEnv };
+    return { command: 'npx.cmd', args: ['--yes', 'node-gyp'], env: childEnv };
+  }
+  const npx = pathImpl.join(nodeDir, 'npx');
+  return { command: existsImpl(npx) ? npx : 'npx', args: ['--yes', 'node-gyp'], env: childEnv };
+}
+
+// What a failed build's output says is missing, as one line to act on.
+function missingToolHint(output, platform) {
+  const text = String(output || '');
+  const missing = /find Python|Could not find any Python|python3?: (?:not found|command not found)/i.test(text)
+    || /make: (?:not found|command not found)|not found: make|spawn make ENOENT/i.test(text)
+    || /(?:c\+\+|g\+\+|clang\+\+|cc|clang): (?:not found|command not found)|No such file or directory.*(?:c\+\+|g\+\+|clang)/i.test(text);
+  if (!missing) return null;
+  return platform === 'android'
+    ? `Install the build tools first: ${TERMUX_BUILD_TOOLS}, then run ${NATIVE_BUILD_COMMAND} again.`
+    : `Install Python 3, make and a C++ compiler (build-essential on Debian and Ubuntu), then run ${NATIVE_BUILD_COMMAND} again.`;
+}
+
+// Opens a database in a child Node with the binding just built, named by its
+// path: the default loader would take a prebuilt one first where one ships.
+function bindingLoads({ dir, execPath, spawnImpl, env }) {
+  const binding = path.join(dir, BINDING_FILE);
+  const script = `const Database = require(${JSON.stringify(dir)}); new Database(':memory:', { nativeBinding: ${JSON.stringify(binding)} }).close();`;
+  return runToCompletion(
+    () => spawnImpl(execPath, ['-e', script], { stdio: ['ignore', 'pipe', 'pipe'], env, windowsHide: true }),
+    { timeoutMs: 60_000 },
+  );
+}
+
+/**
+ * Builds the binding when this platform has no prebuilt one. `force` builds
+ * where one ships too, to check the toolchain; better-sqlite3 still loads its
+ * prebuilt binding first there. Resolves (never rejects) with { ok, status, error?, hint? }:
+ * status 'prebuilt' (nothing to do), 'built', 'failed'. Every line of the
+ * build goes to `onOutput`; what it says about itself goes to `logger.log`.
+ */
+export async function buildBetterSqlite3({
+  packageRoot,
+  force = false,
+  platform = process.platform,
+  arch = process.arch,
+  execPath = process.execPath,
+  env = process.env,
+  spawnImpl = defaultSpawn,
+  existsImpl = fs.existsSync,
+  realpathImpl = fs.realpathSync,
+  requireFrom = createRequire,
+  timeoutMs = NATIVE_BUILD_TIMEOUT_MS,
+  onOutput = null,
+  onChild = null,
+  logger = console,
+} = {}) {
+  if (!force && !needsSourceBuild({ platform, arch })) return { ok: true, status: 'prebuilt' };
+  const dir = resolveBetterSqlite3Dir({ packageRoot, requireFrom });
+  if (!dir) {
+    const error = `better-sqlite3 is not installed under ${packageRoot}`;
+    logger.error?.(`[oar] ${error}.`);
+    return { ok: false, status: 'failed', error };
+  }
+  const gyp = resolveNodeGypInvocation({ execPath, platform, env, existsImpl, realpathImpl });
+  const args = [...gyp.args, 'rebuild', '--release', '--force_build=1'];
+  logger.log?.(`[oar] Building the SQLite binding of better-sqlite3 for ${platform}-${arch} in ${dir}; this takes a few minutes.`);
+  const result = await runToCompletion(
+    () => spawnImpl(gyp.command, args, {
+      cwd: dir,
+      env: gyp.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...(platform === 'win32' ? { windowsHide: true, shell: /\.cmd$/i.test(gyp.command) } : { detached: true }),
+    }),
+    {
+      timeoutMs,
+      killChild: (child, signal) => killTree(child, signal, { platform }),
+      onChild,
+      onOutput,
+    },
+  );
+  if (!result.ok || !existsImpl(path.join(dir, BINDING_FILE))) {
+    const error = result.error || `node-gyp exited with code ${result.code}`;
+    const hint = missingToolHint(result.output, platform);
+    logger.error?.(`[oar] The build of the SQLite binding failed: ${error}.`);
+    if (hint) logger.error?.(`[oar] ${hint}`);
+    else logger.error?.(`[oar] The end of its output:\n${tailOf(result.output, 2_000)}`);
+    return { ok: false, status: 'failed', error, ...(hint ? { hint } : {}) };
+  }
+  const check = await bindingLoads({ dir, execPath, spawnImpl, env: gyp.env });
+  if (!check.ok) {
+    const error = `the built binding does not load: ${tailOf(check.output || check.error || '', 500).trim()}`;
+    logger.error?.(`[oar] ${error}`);
+    return { ok: false, status: 'failed', error };
+  }
+  logger.log?.('[oar] The SQLite binding is built.');
+  return { ok: true, status: 'built' };
+}

package/server/services/oar-cli-helpers.mjs

@@ -86,6 +86,7 @@ const CLI_COMMANDS = {
   autostart: { words: ['signin', 'boot', 'off', 'status'], flags: ['--replace'] },
   uninstall: { flags: ['--purge'] },
   update: { flags: ['--beta'], values: ['--to'] },
+  'build-native': { flags: ['--force'] },
   copilot: { flags: ['--install-extension', '--no-install-extension'], values: ['--port', '--migrate-from'], forwards: true },
 };
 
@@ -116,6 +117,9 @@ export function usageText() {
     '  oar backup [--reason <text>]',
     '                         A copy of the database into the backup folder (safe while the relay runs)',
     '  oar update [--beta] [--to <version>]',
+    '  oar build-native [--force]',
+    '                         Build the SQLite binding where no prebuilt one ships (Termux, 32-bit ARM);',
+    '                         --force builds where one ships too, which only tests the build tools',
     '  oar help               This text',
     '  oar --version',
   ].join('\n');
@@ -401,11 +405,10 @@ export function buildServicePath({ nodeBin, envPath = '', homeDir = '' } = {}) {
  * native binary). npm 12 runs no install script it was not told to allow, and
  * a global install has no package.json of its own to say so; npm 10 and 11
  * accept the flag and run the scripts as before. `npm-install-scripts.test.mjs`
- * holds this list to the lockfile.
+ * holds this list to the lockfile. better-sqlite3 13 has no install script:
+ * where it ships no binary, OAR builds it (native-addon-build-service.mjs).
  */
-// @oar-sh/oar itself: its preinstall copies the data an earlier version
-// kept inside the package before npm deletes it (package-data-rescue.mjs).
-export const NPM_INSTALL_SCRIPT_PACKAGES = Object.freeze(['@oar-sh/oar', 'better-sqlite3', 'koffi']);
+export const NPM_INSTALL_SCRIPT_PACKAGES = Object.freeze(['koffi']);
 export const NPM_ALLOW_SCRIPTS_ARG = `--allow-scripts=${NPM_INSTALL_SCRIPT_PACKAGES.join(',')}`;
 
 /**

package/server/services/queue-wake-hook.mjs

@@ -0,0 +1,145 @@
+'use strict';
+
+// Wakes the relay's queue delivery from the database itself. Every write
+// that can make a queue row deliverable (a new pending row, a requeue, a
+// retry time or owner or provider changed, a turn ending, a pending row
+// cancelled or deleted) fires a TEMP trigger on this connection, which calls
+// a JS function that only notes the reason and schedules one wake for after
+// the current tick, so after the write's transaction. The function never
+// touches the database and never throws.
+//
+// No row path has to remember to wake the queue, and none added later can
+// forget: without it, a path that wrote a row and did not wake waited for
+// the next poll. The triggers are TEMP (this connection only, nothing in the
+// schema or the migrations). Their conditions name only the columns the
+// queue table has, a self-test compiles every trigger inside a rolled-back
+// savepoint, and on any error the triggers are dropped again and the caller
+// falls back to polling: a broken trigger would fail every write to the
+// queue.
+
+export const QUEUE_WAKE_FUNCTION = 'oar_queue_wake';
+const TRIGGER_PREFIX = 'oar_queue_wake_';
+const TRIGGER_NAMES = ['insert', 'pending', 'settle', 'leave_pending', 'delete'].map((name) => `${TRIGGER_PREFIX}${name}`);
+// A bulk statement calls the function once per row: the reasons of one tick
+// are kept as a small set.
+const MAX_REASONS = 8;
+
+function queueColumns(db) {
+  return new Set(db.prepare('PRAGMA table_info(queue)').all().map((column) => String(column.name)));
+}
+
+/** The CREATE TEMP TRIGGER statements, their conditions built from the columns there are. */
+export function buildQueueWakeTriggerSql(columns) {
+  const has = (name) => columns.has(name);
+  if (!has('status')) throw new Error('queue has no status column');
+  const changed = ["OLD.status IS NOT 'pending'"];
+  for (const column of ['next_attempt_at', 'owner_sdk_session_id', 'provider']) {
+    if (has(column)) changed.push(`OLD.${column} IS NOT NEW.${column}`);
+  }
+  const call = (reason) => `BEGIN SELECT ${QUEUE_WAKE_FUNCTION}('${reason}'); END`;
+  return [
+    // A new pending row.
+    `CREATE TEMP TRIGGER ${TRIGGER_PREFIX}insert AFTER INSERT ON main.queue
+      WHEN NEW.status = 'pending' ${call('insert')}`,
+    // A row that became pending, or a pending row whose retry time, owner or
+    // provider changed (a requeue, a hold released, a row moved to another
+    // worker). A claim leaves pending and a lease refresh stays processing:
+    // neither wakes.
+    `CREATE TEMP TRIGGER ${TRIGGER_PREFIX}pending AFTER UPDATE ON main.queue
+      WHEN NEW.status = 'pending' AND (${changed.join(' OR ')}) ${call('requeue')}`,
+    // A turn ended: its session's next row, or one held behind it by the plan
+    // boundary, may go now.
+    `CREATE TEMP TRIGGER ${TRIGGER_PREFIX}settle AFTER UPDATE ON main.queue
+      WHEN OLD.status = 'processing' AND NEW.status IS NOT 'processing' ${call('settle')}`,
+    // A pending row cancelled, failed or parked: a row held behind it may go.
+    `CREATE TEMP TRIGGER ${TRIGGER_PREFIX}leave_pending AFTER UPDATE ON main.queue
+      WHEN OLD.status = 'pending' AND NEW.status NOT IN ('pending', 'processing') ${call('cancel')}`,
+    // A pending or running row deleted (the cancel routes): the same.
+    `CREATE TEMP TRIGGER ${TRIGGER_PREFIX}delete AFTER DELETE ON main.queue
+      WHEN OLD.status IN ('pending', 'processing') ${call('delete')}`,
+  ];
+}
+
+function dropTriggers(db) {
+  for (const name of TRIGGER_NAMES) {
+    try { db.exec(`DROP TRIGGER IF EXISTS temp.${name}`); } catch {}
+  }
+}
+
+/**
+ * Compiles every trigger by preparing a write of each kind, and runs one real
+ * update, inside a savepoint that is rolled back: a condition naming a column
+ * the table lacks fails here instead of on the first real write.
+ */
+function selfTestTriggers(db) {
+  db.exec('SAVEPOINT oar_queue_wake_self_test');
+  try {
+    db.prepare('UPDATE queue SET status = status WHERE rowid = (SELECT rowid FROM queue LIMIT 1)').run();
+    db.prepare('UPDATE queue SET status = status WHERE 0').run();
+    db.prepare('DELETE FROM queue WHERE 0').run();
+    db.prepare('INSERT INTO queue SELECT * FROM queue WHERE 0').run();
+  } finally {
+    db.exec('ROLLBACK TO oar_queue_wake_self_test');
+    db.exec('RELEASE oar_queue_wake_self_test');
+  }
+}
+
+/**
+ * Installs the triggers on `db`. `onWake(reason)` runs once per tick in which
+ * queue writes fired them, with the reasons joined. Returns `{ installed }`;
+ * when false the triggers are gone again and the caller must poll.
+ */
+export function installQueueWakeHook(db, {
+  onWake = () => {},
+  log = () => {},
+  schedule = setImmediate,
+  selfTest = selfTestTriggers,
+} = {}) {
+  const reasons = new Set();
+  let scheduled = false;
+  let muted = false;
+
+  function flush() {
+    scheduled = false;
+    const reason = [...reasons].join(',') || 'queue-write';
+    reasons.clear();
+    try {
+      onWake(reason);
+    } catch (error) {
+      log(`queue wake failed: ${error?.message || error}`);
+    }
+  }
+
+  // Called by SQLite from inside a write: no database access, no throw.
+  function wakeFromTrigger(reason) {
+    try {
+      if (muted) return null;
+      if (reasons.size < MAX_REASONS) reasons.add(String(reason || 'queue-write'));
+      if (!scheduled) {
+        scheduled = true;
+        schedule(flush);
+      }
+    } catch {}
+    return null;
+  }
+
+  try {
+    const sql = buildQueueWakeTriggerSql(queueColumns(db));
+    // The function first: a trigger calling a function that does not exist
+    // yet would fail the write.
+    db.function(QUEUE_WAKE_FUNCTION, { deterministic: false }, wakeFromTrigger);
+    dropTriggers(db);
+    for (const statement of sql) db.exec(statement);
+    muted = true;
+    try {
+      selfTest(db);
+    } finally {
+      muted = false;
+    }
+    return { installed: true, triggers: [...TRIGGER_NAMES] };
+  } catch (error) {
+    dropTriggers(db);
+    log(`queue wake triggers not installed, the queue is polled instead: ${error?.message || error}`);
+    return { installed: false, error };
+  }
+}