@devosurf/tesser-server 0.1.0-alpha.0

package/src/http/ingress.ts

@@ -0,0 +1,204 @@
+// Inbound trigger ingress. Generic webhooks: stable route per project+automation, latest
+// alias resolved at receive time (ADR-0013 spirit), version-pinned via @v. Connector
+// webhooks land on /ingress/c/:token and are demuxed by the trigger layer. Git pushes
+// land on /hooks/git/… and enqueue a reconcile.
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { Hono } from "hono";
+import type { Db } from "../db/db.js";
+import type { Broker } from "../broker/broker.js";
+import { createRun } from "../engine/runs.js";
+import { enqueue } from "../queue/queue.js";
+
+export interface IngressDeps {
+  db: Db;
+  broker: Broker;
+  /** Connector-trigger demux (trigger layer); 404 until a registration exists. */
+  connectorIngress?: (
+    ingressToken: string,
+    req: { headers: Record<string, string>; query: Record<string, string>; rawBody: Uint8Array },
+  ) => Promise<{ status: number; body: string; contentType?: string }>;
+}
+
+function headersToRecord(h: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  h.forEach((v, k) => {
+    out[k.toLowerCase()] = v;
+  });
+  return out;
+}
+
+function safeEqualString(a: string, b: string): boolean {
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+
+function verifyGitWebhookSignature(headers: Headers, rawBody: Uint8Array, secret: string): boolean {
+  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
+  const github = headers.get("x-hub-signature-256");
+  if (github?.startsWith("sha256=") && safeEqualString(github.slice("sha256=".length), expected)) return true;
+  const tesser = headers.get("x-tesser-signature");
+  if (tesser?.startsWith("sha256=") && safeEqualString(tesser.slice("sha256=".length), expected)) return true;
+  return false;
+}
+
+export function createIngress(deps: IngressDeps): Hono {
+  const app = new Hono();
+
+  // Generic inbound webhook trigger (onWebhook). Public by design: verification is the
+  // author's contract via ctx.request + a signing secret (ADR-0010 escape hatch).
+  app.post("/hooks/:project/:automation{[a-z0-9-]+(@v[0-9]+)?}", async (c) => {
+    const projectName = c.req.param("project");
+    const autoParam = c.req.param("automation");
+    const pinMatch = /^(?<id>[a-z0-9-]+?)(?:@v(?<v>\d+))?$/.exec(autoParam);
+    const automationId = pinMatch?.groups?.["id"] ?? autoParam;
+    const pinned = pinMatch?.groups?.["v"];
+
+    const { rows: projects } = await deps.db.query<{ id: string }>(
+      `SELECT id FROM projects WHERE name=$1`,
+      [projectName],
+    );
+    const project = projects[0];
+    if (!project) return c.json({ error: { code: "not-found", message: "unknown project" } }, 404);
+
+    let versionId: string | undefined;
+    let manifest: { trigger?: { kind?: string; respond?: string } } = {};
+    if (pinned !== undefined) {
+      const { rows } = await deps.db.query<{ id: string; manifest: typeof manifest }>(
+        `SELECT id, manifest FROM automation_versions WHERE project_id=$1 AND automation_id=$2 AND version=$3`,
+        [project.id, automationId, Number(pinned)],
+      );
+      versionId = rows[0]?.id;
+      manifest = rows[0]?.manifest ?? {};
+    } else {
+      const { rows } = await deps.db.query<{ version_id: string; manifest: typeof manifest }>(
+        `SELECT a.version_id, v.manifest FROM aliases a JOIN automation_versions v ON v.id=a.version_id
+         WHERE a.project_id=$1 AND a.automation_id=$2 AND a.env='production'`,
+        [project.id, automationId],
+      );
+      versionId = rows[0]?.version_id;
+      manifest = rows[0]?.manifest ?? {};
+    }
+    if (!versionId) return c.json({ error: { code: "not-found", message: "automation not deployed" } }, 404);
+    if (manifest.trigger?.kind !== undefined && manifest.trigger.kind !== "webhook") {
+      return c.json({ error: { code: "wrong-trigger", message: "automation is not webhook-triggered" } }, 404);
+    }
+
+    const rawBody = new Uint8Array(await c.req.arrayBuffer());
+    let input: unknown;
+    const text = new TextDecoder().decode(rawBody);
+    try {
+      input = text.length > 0 ? JSON.parse(text) : undefined;
+    } catch {
+      input = undefined; // non-JSON bodies stay reachable via ctx.request.rawBody
+    }
+    const query: Record<string, string> = {};
+    for (const [k, v] of new URL(c.req.url).searchParams) query[k] = v;
+
+    const runId = await createRun(deps.db, {
+      projectId: project.id,
+      automationId,
+      versionId,
+      trigger: {
+        kind: "webhook",
+        request: {
+          headers: headersToRecord(c.req.raw.headers),
+          query,
+          rawBodyB64: Buffer.from(rawBody).toString("base64"),
+        },
+      },
+      ...(input !== undefined ? { input } : {}),
+    });
+
+    if (manifest.trigger?.respond === "sync") {
+      const deadline = Date.now() + 30_000;
+      while (Date.now() < deadline) {
+        const { rows } = await deps.db.query<{ status: string; output: unknown; error: unknown }>(
+          `SELECT status, output, error FROM runs WHERE id=$1`,
+          [runId!],
+        );
+        const run = rows[0]!;
+        if (run.status === "completed") return c.json({ runId, output: run.output });
+        if (run.status === "failed" || run.status === "cancelled") {
+          return c.json({ runId, error: run.error }, 502);
+        }
+        await new Promise((r) => setTimeout(r, 200));
+      }
+    }
+    return c.json({ runId }, 202);
+  });
+
+  // Connector-trigger ingress (ADR-0013): stable per-registration URL.
+  app.post("/ingress/c/:token", async (c) => {
+    if (!deps.connectorIngress) {
+      return c.json({ error: { code: "not-ready", message: "trigger ingress not configured" } }, 503);
+    }
+    const rawBody = new Uint8Array(await c.req.arrayBuffer());
+    const query: Record<string, string> = {};
+    for (const [k, v] of new URL(c.req.url).searchParams) query[k] = v;
+    const result = await deps.connectorIngress(c.req.param("token"), {
+      headers: headersToRecord(c.req.raw.headers),
+      query,
+      rawBody,
+    });
+    return c.newResponse(result.body, result.status as never, {
+      "content-type": result.contentType ?? "application/json",
+    });
+  });
+
+  // Git push webhook (ADR-0006 default sync path) — project id in path, HMAC over the
+  // raw body with encrypted per-Project signing material. The secret never appears in
+  // CLI/API JSON or URL paths.
+  const enqueueReconcile = async (projectId: string): Promise<void> => {
+    await deps.db.tx((t) =>
+      enqueue(t, {
+        kind: "reconcile",
+        payload: { projectId },
+        dedupeKey: `reconcile:${projectId}:default`,
+        maxAttempts: 1,
+      }),
+    );
+  };
+
+  app.post("/hooks/git/:projectId/push", async (c) => {
+    const { rows } = await deps.db.query<{
+      id: string;
+      workspace_id: string;
+      push_webhook_secret_cipher: string | null;
+    }>(`SELECT id, workspace_id, push_webhook_secret_cipher FROM projects WHERE id=$1`, [c.req.param("projectId")]);
+    const project = rows[0];
+    if (!project?.push_webhook_secret_cipher) {
+      return c.json({ error: { code: "not-found", message: "unknown hook" } }, 404);
+    }
+    const rawBody = new Uint8Array(await c.req.arrayBuffer());
+    const secret = await deps.broker.decryptValue(
+      project.workspace_id,
+      project.push_webhook_secret_cipher,
+      "project.webhook.signing",
+    );
+    if (!verifyGitWebhookSignature(c.req.raw.headers, rawBody, secret)) {
+      return c.json({ error: { code: "unauthorized", message: "invalid hook signature" } }, 401);
+    }
+    await enqueueReconcile(project.id);
+    return c.json({ queued: true }, 202);
+  });
+
+  // Legacy v0 bootstrap route. Kept so Instances upgraded from the path-token webhook
+  // can keep receiving pushes until the self-host administrator re-runs `tesser link`
+  // and moves the git host to the HMAC `/push` route.
+  app.post("/hooks/git/:projectId/:secret", async (c) => {
+    const { rows } = await deps.db.query<{ id: string; push_webhook_secret: string | null }>(
+      `SELECT id, push_webhook_secret FROM projects WHERE id=$1`,
+      [c.req.param("projectId")],
+    );
+    const project = rows[0];
+    if (!project?.push_webhook_secret || !safeEqualString(project.push_webhook_secret, c.req.param("secret"))) {
+      return c.json({ error: { code: "not-found", message: "unknown hook" } }, 404);
+    }
+    await enqueueReconcile(project.id);
+    return c.json({ queued: true }, 202);
+  });
+
+  return app;
+}

package/src/http/status.ts

@@ -0,0 +1,171 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Db } from "../db/db.js";
+import { migrations } from "../db/migrations.js";
+import type { ServerConfig } from "../config.js";
+
+export const RUNTIME_VERSION = readRuntimeVersion();
+
+function readRuntimeVersion(): string {
+  for (const rel of ["../package.json", "../../package.json"]) {
+    try {
+      const pkg = JSON.parse(readFileSync(new URL(rel, import.meta.url), "utf8")) as { version?: unknown };
+      if (typeof pkg.version === "string") return pkg.version;
+    } catch {
+      // Try the next runtime layout: source TS vs bundled dist.
+    }
+  }
+  return "0.0.0";
+}
+
+export interface RuntimeStatusDeps {
+  db: Db;
+  baseUrl: string;
+  dataDir: string;
+  roles: ServerConfig["roles"];
+  version?: string;
+}
+
+export interface ReadinessStatus {
+  ok: boolean;
+  service: "tesser";
+  version: string;
+  checks: {
+    database: { ok: boolean; kind: Db["kind"]; reachable: boolean; message?: string };
+    migrations: { ok: boolean; current: boolean; applied: string[]; pending: string[]; message?: string };
+    dataDir: { ok: boolean; writable: boolean; message?: string };
+  };
+}
+
+export async function readinessStatus(deps: RuntimeStatusDeps): Promise<ReadinessStatus> {
+  const database: ReadinessStatus["checks"]["database"] = { ok: false, kind: deps.db.kind, reachable: false };
+  const migrationsCheck: ReadinessStatus["checks"]["migrations"] = {
+    ok: false,
+    current: false,
+    applied: [],
+    pending: migrations.map((m) => m.id),
+  };
+
+  try {
+    await deps.db.query(`SELECT 1 AS ok`);
+    database.ok = true;
+    database.reachable = true;
+  } catch {
+    database.message = "database query failed";
+  }
+
+  if (database.reachable) {
+    try {
+      const { rows } = await deps.db.query<{ id: string }>(`SELECT id FROM schema_migrations ORDER BY id`);
+      const applied = rows.map((r) => r.id);
+      const appliedSet = new Set(applied);
+      const pending = migrations.map((m) => m.id).filter((id) => !appliedSet.has(id));
+      migrationsCheck.applied = applied;
+      migrationsCheck.pending = pending;
+      migrationsCheck.current = pending.length === 0;
+      migrationsCheck.ok = migrationsCheck.current;
+    } catch {
+      migrationsCheck.message = "schema_migrations check failed";
+    }
+  }
+
+  const dataDir = checkWritableDir(deps.dataDir);
+  return {
+    ok: database.ok && migrationsCheck.ok && dataDir.ok,
+    service: "tesser",
+    version: deps.version ?? RUNTIME_VERSION,
+    checks: { database, migrations: migrationsCheck, dataDir },
+  };
+}
+
+export async function runtimeStatus(deps: RuntimeStatusDeps, workspaceId: string): Promise<Record<string, unknown>> {
+  const readiness = await readinessStatus(deps);
+  const queue = await queueStatus(deps.db);
+  const deployments = await deploymentStatus(deps.db, workspaceId);
+  const haltedCredentials = deployments.projects.filter((p) => p.status === "halted-credentials");
+  const degraded = queue.dead > 0 || (deployments.byStatus["failed"] ?? 0) > 0 || haltedCredentials.length > 0;
+
+  return {
+    ok: readiness.ok,
+    degraded,
+    service: "tesser",
+    version: deps.version ?? RUNTIME_VERSION,
+    booted: true,
+    baseUrl: deps.baseUrl,
+    roles: deps.roles,
+    readiness,
+    queue,
+    deployments,
+    haltedCredentials: {
+      count: haltedCredentials.length,
+      projects: haltedCredentials.map((p) => ({
+        name: p.name,
+        requirements: p.requirements,
+        lastSyncedAt: p.lastSyncedAt,
+      })),
+    },
+  };
+}
+
+function checkWritableDir(dataDir: string): { ok: boolean; writable: boolean; message?: string } {
+  const probe = join(dataDir, `.tesser-write-probe-${randomUUID()}`);
+  try {
+    writeFileSync(probe, "ok", { flag: "wx" });
+    rmSync(probe, { force: true });
+    return { ok: true, writable: true };
+  } catch {
+    return { ok: false, writable: false, message: "data directory is not writable" };
+  }
+}
+
+async function queueStatus(db: Db): Promise<{ ready: number; leased: number; dead: number }> {
+  const { rows } = await db.query<{ ready: string; leased: string; dead: string }>(
+    `SELECT
+       SUM(CASE WHEN status = 'ready' AND lease_until IS NULL THEN 1 ELSE 0 END)::text AS ready,
+       SUM(CASE WHEN status = 'ready' AND lease_until IS NOT NULL THEN 1 ELSE 0 END)::text AS leased,
+       SUM(CASE WHEN status = 'dead' THEN 1 ELSE 0 END)::text AS dead
+     FROM queue_jobs`,
+  );
+  const row = rows[0] ?? { ready: "0", leased: "0", dead: "0" };
+  return { ready: Number(row.ready), leased: Number(row.leased), dead: Number(row.dead) };
+}
+
+async function deploymentStatus(
+  db: Db,
+  workspaceId: string,
+): Promise<{ byStatus: Record<string, number>; projects: Array<{ name: string; status: string; lastSha: string | null; lastSyncedAt: string | null; requirements: number }> }> {
+  const { rows } = await db.query<{
+    name: string;
+    status: string | null;
+    last_sha: string | null;
+    last_synced_at: string | null;
+    report: unknown;
+  }>(
+    `SELECT p.name, r.status, r.last_sha, r.last_synced_at, r.report
+     FROM projects p LEFT JOIN repo_state r ON r.project_id = p.id
+     WHERE p.workspace_id = $1
+     ORDER BY p.name`,
+    [workspaceId],
+  );
+  const byStatus: Record<string, number> = {};
+  const projects = rows.map((row) => {
+    const status = row.status ?? "unlinked";
+    byStatus[status] = (byStatus[status] ?? 0) + 1;
+    return {
+      name: row.name,
+      status,
+      lastSha: row.last_sha,
+      lastSyncedAt: row.last_synced_at,
+      requirements: requirementCount(row.report),
+    };
+  });
+  return { byStatus, projects };
+}
+
+function requirementCount(report: unknown): number {
+  if (report && typeof report === "object" && Array.isArray((report as { requirements?: unknown }).requirements)) {
+    return (report as { requirements: unknown[] }).requirements.length;
+  }
+  return 0;
+}

package/src/http/tokens.ts

@@ -0,0 +1,46 @@
+// API tokens: sha256-at-rest, shown once at mint. The first boot prints an admin token;
+// further tokens are minted via the API (CLI: `tesser login --token` / TESSER_TOKEN env).
+
+import { createHash, randomBytes } from "node:crypto";
+import type { Db } from "../db/db.js";
+
+export function hashToken(token: string): string {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+export async function mintToken(db: Db, workspaceId: string, name: string): Promise<string> {
+  const token = `tsk_${randomBytes(24).toString("hex")}`;
+  await db.query(`INSERT INTO api_tokens (workspace_id, name, token_hash) VALUES ($1,$2,$3)`, [
+    workspaceId,
+    name,
+    hashToken(token),
+  ]);
+  return token;
+}
+
+export async function verifyToken(db: Db, token: string): Promise<{ workspaceId: string } | null> {
+  if (!token.startsWith("tsk_")) return null;
+  const { rows } = await db.query<{ workspace_id: string; id: string }>(
+    `SELECT id, workspace_id FROM api_tokens WHERE token_hash = $1`,
+    [hashToken(token)],
+  );
+  if (!rows[0]) return null;
+  void db.query(`UPDATE api_tokens SET last_used_at = now() WHERE id = $1`, [rows[0].id]).catch(() => {});
+  return { workspaceId: rows[0].workspace_id };
+}
+
+export async function ensureAdminToken(db: Db, workspaceId: string): Promise<string | null> {
+  const { rows } = await db.query(`SELECT 1 FROM api_tokens WHERE workspace_id = $1 LIMIT 1`, [workspaceId]);
+  if (rows.length > 0) return null;
+  // `tesser dev` hands its spawned instance a known token (process boundary — the
+  // Apache CLI never links this AGPL code).
+  const preset = process.env["TESSER_BOOTSTRAP_TOKEN"];
+  if (preset && preset.startsWith("tsk_")) {
+    await db.query(`INSERT INTO api_tokens (workspace_id, name, token_hash) VALUES ($1,'bootstrap',$2)`, [
+      workspaceId,
+      hashToken(preset),
+    ]);
+    return preset;
+  }
+  return mintToken(db, workspaceId, "admin (first boot)");
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// @devosurf/tesser-server — AGPL-3.0. Programmatic surface (the binary is bin/tesser-server.mjs).
+
+export { createTesserServer, type TesserServer } from "./server.js";
+export { loadConfig, type ServerConfig } from "./config.js";
+export { createDb, type Db, type DbClient } from "./db/db.js";
+export { migrate } from "./db/migrate.js";
+export { executeRun } from "./engine/executor.js";
+export { createRun, deliverSignal, cancelRun } from "./engine/runs.js";
+export type { EngineDeps, RunOutcome } from "./engine/types.js";
+export { Worker } from "./queue/worker.js";
+export { enqueue, claim } from "./queue/queue.js";
+export { schedulerTick, syncSchedules, startScheduler } from "./scheduler/cron.js";
+export { fanoutEvent, syncSubscriptions } from "./events/fanout.js";
+export { Broker } from "./broker/broker.js";
+export { Masker } from "./broker/masking.js";
+export { makeEngineBindings } from "./broker/connections.js";
+export { reconcileProject, deployStatus } from "./gitsync/reconciler.js";
+export { ArtifactLoader } from "./registry/loader.js";
+export { mintToken, verifyToken } from "./http/tokens.js";
+export { createApp } from "./http/app.js";

package/src/main.ts

@@ -0,0 +1,26 @@
+// tesser-server entrypoint.
+
+import { createTesserServer } from "./server.js";
+
+const server = await createTesserServer();
+await server.start();
+
+console.error(`[tesser] instance up on ${server.config.baseUrl} (db: ${server.db.kind})`);
+console.error(
+  `[tesser] roles: ${Object.entries(server.config.roles)
+    .filter(([, on]) => on)
+    .map(([r]) => r)
+    .join(", ")}`,
+);
+if (server.adminToken) {
+  console.error(`[tesser] FIRST BOOT — admin API token (store it now, it is not shown again):`);
+  console.error(`[tesser]   ${server.adminToken}`);
+}
+
+const shutdown = async (signal: string) => {
+  console.error(`[tesser] ${signal} — draining`);
+  await server.stop();
+  process.exit(0);
+};
+process.on("SIGINT", () => void shutdown("SIGINT"));
+process.on("SIGTERM", () => void shutdown("SIGTERM"));

package/src/queue/queue.ts

@@ -0,0 +1,133 @@
+// Postgres-as-queue (ADR-0003): SELECT … FOR UPDATE SKIP LOCKED claims, leases with
+// heartbeat, durable re-enqueue, dedupe-keyed upserts (one pending wake job per run).
+
+import type { Db, DbClient } from "../db/db.js";
+
+export interface EnqueueOpts {
+  kind: string;
+  payload: Record<string, unknown>;
+  runAtMs?: number | undefined;
+  priority?: number | undefined;
+  tag?: string | undefined;
+  /** Upsert key: an existing ready job with this key has its run_at moved EARLIER. */
+  dedupeKey?: string | undefined;
+  maxAttempts?: number | undefined;
+}
+
+export async function enqueue(client: DbClient, opts: EnqueueOpts): Promise<void> {
+  const runAt = opts.runAtMs !== undefined ? new Date(opts.runAtMs).toISOString() : new Date().toISOString();
+  if (opts.dedupeKey !== undefined) {
+    await client.query(
+      `INSERT INTO queue_jobs (kind, payload, run_at, priority, tag, dedupe_key, max_attempts)
+       VALUES ($1, $2::jsonb, $3, $4, $5, $6, $7)
+       ON CONFLICT (dedupe_key) WHERE dedupe_key IS NOT NULL DO UPDATE
+         SET run_at = LEAST(queue_jobs.run_at, EXCLUDED.run_at),
+             status = 'ready',
+             payload = EXCLUDED.payload`,
+      [
+        opts.kind,
+        JSON.stringify(opts.payload),
+        runAt,
+        opts.priority ?? 0,
+        opts.tag ?? null,
+        opts.dedupeKey,
+        opts.maxAttempts ?? 10,
+      ],
+    );
+  } else {
+    await client.query(
+      `INSERT INTO queue_jobs (kind, payload, run_at, priority, tag, max_attempts)
+       VALUES ($1, $2::jsonb, $3, $4, $5, $6)`,
+      [opts.kind, JSON.stringify(opts.payload), runAt, opts.priority ?? 0, opts.tag ?? null, opts.maxAttempts ?? 10],
+    );
+  }
+}
+
+export interface ClaimedJob {
+  id: string;
+  kind: string;
+  payload: Record<string, unknown>;
+  attempts: number;
+  maxAttempts: number;
+}
+
+const LEASE_SECONDS = 60;
+
+/** Claim one due job (tag/kind-routed when filters are given). Expired leases are reclaimable. */
+export async function claim(
+  db: Db,
+  tags?: string[] | undefined,
+  kinds?: string[] | undefined,
+): Promise<ClaimedJob | null> {
+  return db.tx(async (c) => {
+    const params: unknown[] = [];
+    const tagFilter = tags && tags.length > 0 ? `AND (tag IS NULL OR tag = ANY($${params.push(tags)}))` : "";
+    const kindFilter = kinds && kinds.length > 0 ? `AND kind = ANY($${params.push(kinds)})` : "";
+    const { rows } = await c.query<{
+      id: string;
+      kind: string;
+      payload: Record<string, unknown>;
+      attempts: number;
+      max_attempts: number;
+    }>(
+      `SELECT id, kind, payload, attempts, max_attempts FROM queue_jobs
+       WHERE status = 'ready'
+         AND run_at <= now()
+         AND (lease_until IS NULL OR lease_until < now())
+         ${tagFilter}
+         ${kindFilter}
+       ORDER BY priority DESC, run_at
+       FOR UPDATE SKIP LOCKED
+       LIMIT 1`,
+      params,
+    );
+    const job = rows[0];
+    if (!job) return null;
+    // dedupe_key is cleared on claim: a suspension that re-arms the same logical wake
+    // must insert a FRESH row, not collide with the job currently being executed.
+    await c.query(
+      `UPDATE queue_jobs
+       SET lease_until = now() + interval '${LEASE_SECONDS} seconds',
+           attempts = attempts + 1,
+           dedupe_key = NULL
+       WHERE id = $1`,
+      [job.id],
+    );
+    return {
+      id: job.id,
+      kind: job.kind,
+      payload: job.payload,
+      attempts: job.attempts + 1,
+      maxAttempts: job.max_attempts,
+    };
+  });
+}
+
+export async function heartbeat(db: Db, jobId: string): Promise<void> {
+  await db.query(
+    `UPDATE queue_jobs SET lease_until = now() + interval '${LEASE_SECONDS} seconds' WHERE id = $1`,
+    [jobId],
+  );
+}
+
+export async function complete(db: Db, jobId: string): Promise<void> {
+  await db.query(`DELETE FROM queue_jobs WHERE id = $1`, [jobId]);
+}
+
+/** Release after failure: retry with backoff until attempts exhaust → dead. */
+export async function fail(db: Db, job: ClaimedJob, error: string): Promise<void> {
+  if (job.attempts >= job.maxAttempts) {
+    await db.query(
+      `UPDATE queue_jobs SET status = 'dead', lease_until = NULL, last_error = $2 WHERE id = $1`,
+      [job.id, error.slice(0, 2000)],
+    );
+    return;
+  }
+  const delaySeconds = Math.min(60 * 15, 2 ** job.attempts);
+  await db.query(
+    `UPDATE queue_jobs
+     SET lease_until = NULL, last_error = $2, run_at = now() + ($3 || ' seconds')::interval
+     WHERE id = $1`,
+    [job.id, error.slice(0, 2000), String(delaySeconds)],
+  );
+}

package/src/queue/worker.ts

@@ -0,0 +1,85 @@
+// The worker loop: long-poll claim → dispatch by job kind → complete/fail. Leases are
+// heartbeat-extended; a crashed worker's jobs are reclaimed on lease expiry (the
+// journal-of-results executor makes re-execution safe).
+
+import type { Db } from "../db/db.js";
+import { claim, complete, fail, heartbeat, type ClaimedJob } from "./queue.js";
+
+export type JobHandler = (job: ClaimedJob) => Promise<void>;
+
+export interface WorkerOpts {
+  tags?: string[] | undefined;
+  /** Job kinds this worker duty is allowed to claim. Omitted means all kinds. */
+  kinds?: string[] | undefined;
+  pollIntervalMs?: number;
+  onError?: (err: unknown, job?: ClaimedJob) => void;
+}
+
+export class Worker {
+  private running = false;
+  private loopPromise: Promise<void> | null = null;
+
+  constructor(
+    private readonly db: Db,
+    private readonly handlers: Record<string, JobHandler>,
+    private readonly opts: WorkerOpts = {},
+  ) {}
+
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+    this.loopPromise = this.loop();
+  }
+
+  async stop(): Promise<void> {
+    this.running = false;
+    await this.loopPromise;
+  }
+
+  /** Process every due job right now (test + reconcile-now convenience). */
+  async drain(maxJobs = 1000): Promise<number> {
+    let n = 0;
+    while (n < maxJobs) {
+      const job = await claim(this.db, this.opts.tags, this.opts.kinds);
+      if (!job) break;
+      await this.dispatch(job);
+      n++;
+    }
+    return n;
+  }
+
+  private async loop(): Promise<void> {
+    const pollMs = this.opts.pollIntervalMs ?? 250;
+    while (this.running) {
+      let job: ClaimedJob | null = null;
+      try {
+        job = await claim(this.db, this.opts.tags, this.opts.kinds);
+      } catch (err) {
+        this.opts.onError?.(err);
+      }
+      if (!job) {
+        await new Promise((r) => setTimeout(r, pollMs));
+        continue;
+      }
+      await this.dispatch(job);
+    }
+  }
+
+  private async dispatch(job: ClaimedJob): Promise<void> {
+    const handler = this.handlers[job.kind];
+    const beat = setInterval(() => {
+      void heartbeat(this.db, job.id).catch(() => {});
+    }, 20_000);
+    beat.unref?.();
+    try {
+      if (!handler) throw new Error(`no handler for job kind "${job.kind}"`);
+      await handler(job);
+      await complete(this.db, job.id);
+    } catch (err) {
+      this.opts.onError?.(err, job);
+      await fail(this.db, job, (err as Error)?.stack ?? String(err)).catch(() => {});
+    } finally {
+      clearInterval(beat);
+    }
+  }
+}