gsd-pi 2.78.1-dev.e9d88a536 → 2.78.1-dev.eccf86e27

package/src/resources/extensions/gsd/db/auto-workers.ts

@@ -0,0 +1,273 @@
+// gsd-2 + Auto-mode worker process registry (DB-backed coordination, Phase B)
+//
+// IMPORTANT — naming clarification (codex review LOW N1):
+// This module is the AUTO-MODE PROCESS REGISTRY. It tracks long-running
+// `gsd auto` worker processes for cross-process coordination via the shared
+// SQLite WAL. It is NOT the in-process subagent registry, which lives at
+// `src/resources/extensions/subagent/worker-registry.ts` and tracks dispatched
+// subagent threads within a single process.
+//
+// Both modules use the word "worker" but they are unrelated:
+//   - subagent/worker-registry.ts → ephemeral in-process subagent threads
+//   - db/auto-workers.ts          → durable cross-process auto-mode sessions
+//
+// Single-host invariant: SQLite WAL coordination only works on local disk.
+// NFS / network filesystems break heartbeat semantics. Multi-host execution
+// needs a real coordinator (etcd, Postgres) — out of scope for Phase B.
+
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+
+import {
+  _getAdapter,
+  isDbAvailable,
+  transaction,
+  insertAuditEvent,
+} from "../gsd-db.js";
+import { normalizeRealPath } from "../paths.js";
+
+const HEARTBEAT_TTL_SECONDS = 60;
+// Version label is for diagnostics only — embedded in audit_events and
+// workers.version. Bumping this manually on protocol changes is fine; we
+// don't pull it from package.json to avoid module-load filesystem I/O.
+const WORKER_REGISTRY_VERSION = "1";
+
+export type WorkerStatus = "active" | "stopping" | "crashed";
+
+export interface AutoWorkerRow {
+  worker_id: string;
+  host: string;
+  pid: number;
+  started_at: string;
+  version: string;
+  last_heartbeat_at: string;
+  status: WorkerStatus;
+  project_root_realpath: string;
+}
+
+/**
+ * Register a new auto-mode worker process. Returns the generated worker_id
+ * for the session to store on its AutoSession.
+ *
+ * The worker is created with `status='active'` and an initial heartbeat
+ * stamp; callers must invoke heartbeatAutoWorker() periodically (e.g. once
+ * per loop iteration) to refresh the TTL.
+ */
+export function registerAutoWorker(opts: {
+  projectRootRealpath: string;
+}): string {
+  if (!isDbAvailable()) {
+    throw new Error("registerAutoWorker: DB unavailable");
+  }
+  const workerId = `auto-${hostname()}-${process.pid}-${randomUUID().slice(0, 8)}`;
+  const now = new Date().toISOString();
+
+  transaction(() => {
+    const db = _getAdapter()!;
+    db.prepare(
+      `INSERT INTO workers (
+        worker_id, host, pid, started_at, version,
+        last_heartbeat_at, status, project_root_realpath
+      ) VALUES (
+        :worker_id, :host, :pid, :started_at, :version,
+        :last_heartbeat_at, 'active', :project_root_realpath
+      )`,
+    ).run({
+      ":worker_id": workerId,
+      ":host": hostname(),
+      ":pid": process.pid,
+      ":started_at": now,
+      ":version": WORKER_REGISTRY_VERSION,
+      ":last_heartbeat_at": now,
+      ":project_root_realpath": opts.projectRootRealpath,
+    });
+  });
+
+  insertAuditEvent({
+    eventId: randomUUID(),
+    traceId: workerId,
+    category: "orchestration",
+    type: "worker-registered",
+    ts: now,
+    payload: {
+      workerId,
+      host: hostname(),
+      pid: process.pid,
+      version: WORKER_REGISTRY_VERSION,
+      projectRootRealpath: opts.projectRootRealpath,
+    },
+  });
+
+  return workerId;
+}
+
+/**
+ * Refresh the worker's heartbeat. Call once per auto-loop iteration.
+ * Idempotent — silently no-ops if the worker no longer exists (e.g. row was
+ * cleaned up by a janitor).
+ */
+export function heartbeatAutoWorker(workerId: string): void {
+  if (!isDbAvailable()) return;
+  const now = new Date().toISOString();
+  const db = _getAdapter()!;
+  db.prepare(
+    `UPDATE workers SET last_heartbeat_at = :now WHERE worker_id = :worker_id AND status = 'active'`,
+  ).run({ ":now": now, ":worker_id": workerId });
+}
+
+/**
+ * Mark the worker as crashed. Used by janitors / doctor commands when a
+ * worker's heartbeat has expired beyond the TTL window.
+ */
+export function markWorkerCrashed(workerId: string): void {
+  if (!isDbAvailable()) return;
+  const db = _getAdapter()!;
+  let changes = 0;
+  transaction(() => {
+    const result = db.prepare(
+      `UPDATE workers SET status = 'crashed' WHERE worker_id = :worker_id AND status = 'active'`,
+    ).run({ ":worker_id": workerId });
+    changes =
+      typeof (result as { changes?: unknown }).changes === "number"
+        ? (result as { changes: number }).changes
+        : 0;
+  });
+  if (changes < 1) return;
+  insertAuditEvent({
+    eventId: randomUUID(),
+    traceId: workerId,
+    category: "orchestration",
+    type: "worker-crashed",
+    ts: new Date().toISOString(),
+    payload: { workerId },
+  });
+}
+
+/**
+ * Mark the worker as stopping. Called from the stopAuto path when the user
+ * cleanly shuts down auto-mode.
+ */
+export function markWorkerStopping(workerId: string): void {
+  if (!isDbAvailable()) return;
+  const db = _getAdapter()!;
+  transaction(() => {
+    db.prepare(
+      `UPDATE workers SET status = 'stopping' WHERE worker_id = :worker_id`,
+    ).run({ ":worker_id": workerId });
+  });
+}
+
+/**
+ * Return all workers whose status is 'active' AND whose heartbeat is within
+ * the TTL window. Workers older than the TTL are NOT auto-marked crashed
+ * here — that's a separate janitor responsibility — but they are filtered
+ * out of the active set so callers see a fresh view.
+ */
+export function getActiveAutoWorkers(): readonly AutoWorkerRow[] {
+  if (!isDbAvailable()) return [];
+  const db = _getAdapter()!;
+  const cutoffMs = Date.now() - HEARTBEAT_TTL_SECONDS * 1000;
+  const cutoffIso = new Date(cutoffMs).toISOString();
+  const rows = db.prepare(
+    `SELECT worker_id, host, pid, started_at, version,
+            last_heartbeat_at, status, project_root_realpath
+     FROM workers
+     WHERE status = 'active' AND last_heartbeat_at >= :cutoff
+     ORDER BY started_at`,
+  ).all({ ":cutoff": cutoffIso }) as unknown as AutoWorkerRow[];
+  return rows;
+}
+
+/** Return all worker rows regardless of status or TTL. */
+export function getAllAutoWorkers(): readonly AutoWorkerRow[] {
+  if (!isDbAvailable()) return [];
+  const db = _getAdapter()!;
+  const rows = db.prepare(
+    `SELECT worker_id, host, pid, started_at, version,
+            last_heartbeat_at, status, project_root_realpath
+     FROM workers
+     ORDER BY started_at`,
+  ).all() as unknown as AutoWorkerRow[];
+  return rows;
+}
+
+/**
+ * Look up a single worker row. Returns null if no row exists.
+ */
+export function getAutoWorker(workerId: string): AutoWorkerRow | null {
+  if (!isDbAvailable()) return null;
+  const db = _getAdapter()!;
+  const row = db.prepare(
+    `SELECT worker_id, host, pid, started_at, version,
+            last_heartbeat_at, status, project_root_realpath
+     FROM workers WHERE worker_id = :worker_id`,
+  ).get({ ":worker_id": workerId }) as AutoWorkerRow | undefined;
+  return row ?? null;
+}
+
+/** Test/janitor helper: TTL constant exported for callers to compute expirations. */
+export function autoWorkerHeartbeatTtlSeconds(): number {
+  return HEARTBEAT_TTL_SECONDS;
+}
+
+function isWorkerProcessAlive(candidate: Pick<AutoWorkerRow, "host" | "pid">): boolean {
+  const pid = candidate.pid;
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  if (candidate.host !== hostname()) return false;
+  if (pid === process.pid) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "EPERM") return true;
+    return false;
+  }
+}
+
+/**
+ * Phase C pt 2 — find the most recently active worker for a project root
+ * whose heartbeat has lapsed (the "previous crashed session" indicator).
+ *
+ * Used by crash-recovery.ts:readCrashLock to detect when a prior auto-mode
+ * session ended without cleanup. Workers are only treated as stale after
+ * their heartbeat has lapsed and the OS PID liveness check says the process
+ * is no longer alive.
+ *
+ * Returns null if no stale worker exists for this project root.
+ */
+export function findStaleWorkerForProject(
+  projectRootRealpath: string,
+): AutoWorkerRow | null {
+  if (!isDbAvailable()) return null;
+  const db = _getAdapter()!;
+  const cutoffMs = Date.now() - HEARTBEAT_TTL_SECONDS * 1000;
+  const cutoffIso = new Date(cutoffMs).toISOString();
+  const row = db.prepare(
+    `SELECT worker_id, host, pid, started_at, version,
+            last_heartbeat_at, status, project_root_realpath
+     FROM workers
+     WHERE project_root_realpath = :project_root
+       AND status = 'active'
+       AND last_heartbeat_at < :cutoff
+     ORDER BY started_at DESC
+     LIMIT 1`,
+  ).get({ ":project_root": projectRootRealpath, ":cutoff": cutoffIso }) as AutoWorkerRow | undefined;
+  if (row && !isWorkerProcessAlive(row)) return row;
+
+  // Older rows and external fixtures may have captured a non-realpath spelling
+  // of the same project root, e.g. /var/... vs /private/var/... on macOS.
+  const canonicalProjectRoot = normalizeRealPath(projectRootRealpath);
+  const staleRows = db.prepare(
+    `SELECT worker_id, host, pid, started_at, version,
+            last_heartbeat_at, status, project_root_realpath
+     FROM workers
+     WHERE status = 'active'
+       AND last_heartbeat_at < :cutoff
+     ORDER BY started_at DESC`,
+  ).all({ ":cutoff": cutoffIso }) as unknown as AutoWorkerRow[];
+  return staleRows.find(
+    (candidate) =>
+      normalizeRealPath(candidate.project_root_realpath) === canonicalProjectRoot
+      && !isWorkerProcessAlive(candidate),
+  ) ?? null;
+}

package/src/resources/extensions/gsd/db/command-queue.ts

@@ -0,0 +1,149 @@
+// gsd-2 + Worker IPC command queue (DB-backed coordination, Phase B)
+//
+// New infrastructure for dispatcher-to-worker IPC (cancel signals, pause
+// requests, etc.). NOT a replacement for any existing on-disk queue and
+// NOT related to startAutoCommandPolling() in auto.ts (which polls a
+// remote channel like Telegram, not a local file queue).
+//
+// Broadcast semantics (codex review LOW B4):
+// SQLite indexes NULLs in B-trees, so the single index
+// idx_command_queue_pending(target_worker, claimed_at) serves both:
+//   - targeted queries: WHERE target_worker = ?
+//   - broadcast queries: WHERE target_worker IS NULL
+// Workers should poll for both forms (their own ID + broadcasts) on each
+// claim cycle.
+
+import {
+  _getAdapter,
+  isDbAvailable,
+  transaction,
+} from "../gsd-db.js";
+
+export interface CommandQueueRow {
+  id: number;
+  target_worker: string | null;
+  command: string;
+  args_json: string;
+  enqueued_at: string;
+  claimed_at: string | null;
+  claimed_by: string | null;
+  completed_at: string | null;
+  result_json: string | null;
+}
+
+export interface EnqueueInput {
+  /** null = broadcast to all workers; string = target a specific worker_id */
+  targetWorker: string | null;
+  command: string;
+  args?: Record<string, unknown>;
+}
+
+/**
+ * Enqueue a command. Returns the new row id. Broadcast commands
+ * (targetWorker=null) will be claimed by exactly one worker — the IPC
+ * model is "single delivery to whoever claims first", not pub-sub.
+ */
+export function enqueueCommand(input: EnqueueInput): number {
+  if (!isDbAvailable()) {
+    throw new Error("enqueueCommand: DB unavailable");
+  }
+  const now = new Date().toISOString();
+  const db = _getAdapter()!;
+  const result = transaction(() => {
+    return db.prepare(
+      `INSERT INTO command_queue (target_worker, command, args_json, enqueued_at)
+       VALUES (:target_worker, :command, :args_json, :enqueued_at)`,
+    ).run({
+      ":target_worker": input.targetWorker,
+      ":command": input.command,
+      ":args_json": JSON.stringify(input.args ?? {}),
+      ":enqueued_at": now,
+    });
+  });
+  return Number((result as { lastInsertRowid?: number | bigint }).lastInsertRowid ?? 0);
+}
+
+/**
+ * Atomically claim the next pending command for the given worker. Returns
+ * the claimed row, or null if nothing to claim.
+ *
+ * Polls both targeted (target_worker = workerId) and broadcast
+ * (target_worker IS NULL) queues, oldest-first.
+ */
+export function claimNextCommand(workerId: string): CommandQueueRow | null {
+  if (!isDbAvailable()) return null;
+  const now = new Date().toISOString();
+  const db = _getAdapter()!;
+
+  return transaction((): CommandQueueRow | null => {
+    // Find the oldest unclaimed command targeted at this worker OR
+    // broadcast. The partial index covers both via NULL-in-B-tree.
+    const row = db.prepare(
+      `SELECT id, target_worker, command, args_json, enqueued_at,
+              claimed_at, claimed_by, completed_at, result_json
+       FROM command_queue
+       WHERE claimed_at IS NULL
+         AND completed_at IS NULL
+         AND (target_worker = :worker_id OR target_worker IS NULL)
+       ORDER BY enqueued_at ASC, id ASC
+       LIMIT 1`,
+    ).get({ ":worker_id": workerId }) as CommandQueueRow | undefined;
+
+    if (!row) return null;
+
+    // Conditional UPDATE — only succeeds if still unclaimed (guards against
+    // races between two workers polling simultaneously).
+    const result = db.prepare(
+      `UPDATE command_queue
+       SET claimed_at = :now, claimed_by = :worker_id
+       WHERE id = :id AND claimed_at IS NULL AND completed_at IS NULL`,
+    ).run({ ":now": now, ":worker_id": workerId, ":id": row.id });
+
+    const changes =
+      typeof (result as { changes?: unknown }).changes === "number"
+        ? (result as { changes: number }).changes
+        : 0;
+
+    if (changes !== 1) return null; // lost the race
+
+    return { ...row, claimed_at: now, claimed_by: workerId };
+  });
+}
+
+/**
+ * Mark a command complete with optional result payload. Idempotent — if
+ * the command is already completed, the second call is a no-op.
+ */
+export function completeCommand(
+  id: number,
+  workerId: string,
+  result?: Record<string, unknown>,
+): void {
+  if (!isDbAvailable()) return;
+  const now = new Date().toISOString();
+  const db = _getAdapter()!;
+  db.prepare(
+    `UPDATE command_queue
+     SET completed_at = :now, result_json = :result_json
+     WHERE id = :id
+       AND claimed_by = :worker_id
+       AND completed_at IS NULL`,
+  ).run({
+    ":id": id,
+    ":worker_id": workerId,
+    ":now": now,
+    ":result_json": result ? JSON.stringify(result) : null,
+  });
+}
+
+/** Diagnostic helper: read a single row by id. */
+export function getCommand(id: number): CommandQueueRow | null {
+  if (!isDbAvailable()) return null;
+  const db = _getAdapter()!;
+  const row = db.prepare(
+    `SELECT id, target_worker, command, args_json, enqueued_at,
+            claimed_at, claimed_by, completed_at, result_json
+     FROM command_queue WHERE id = :id`,
+  ).get({ ":id": id }) as CommandQueueRow | undefined;
+  return row ?? null;
+}

package/src/resources/extensions/gsd/db/milestone-leases.ts

@@ -0,0 +1,274 @@
+// gsd-2 + Milestone leases with fencing tokens (DB-backed coordination, Phase B)
+//
+// One worker at a time may hold a lease on a given milestone. Leases carry a
+// monotonic fencing token that increments on every successful takeover, so
+// stale workers can be cheaply detected and rejected at write time
+// (unit_dispatches.milestone_lease_token).
+//
+// Codex review BLOCKING B1: claim semantics must atomically handle two
+// distinct cases inside one transaction:
+//   1. First claim (no row exists)         → INSERT with fencing_token=1
+//   2. Takeover (row exists, expired/released) → UPDATE w/ fencing_token+1
+// `INSERT OR ABORT` alone is wrong because the row already exists for any
+// takeover and a plain INSERT cannot succeed.
+
+import { randomUUID } from "node:crypto";
+
+import {
+  _getAdapter,
+  isDbAvailable,
+  transaction,
+  insertAuditEvent,
+} from "../gsd-db.js";
+
+const LEASE_TTL_SECONDS = 60;
+
+export type LeaseStatus = "held" | "released" | "expired";
+
+export interface MilestoneLeaseRow {
+  milestone_id: string;
+  worker_id: string;
+  fencing_token: number;
+  acquired_at: string;
+  expires_at: string;
+  status: LeaseStatus;
+}
+
+export type ClaimResult =
+  | { ok: true; token: number; expiresAt: string }
+  | { ok: false; error: "held_by"; byWorker: string; expiresAt: string };
+
+function isDuplicateLeaseInsertError(err: unknown): boolean {
+  const code =
+    err && typeof err === "object" && "code" in err
+      ? String((err as { code?: unknown }).code ?? "")
+      : "";
+  const msg = err instanceof Error ? err.message : String(err);
+  if (/\bFOREIGN KEY\b/i.test(msg)) {
+    return false;
+  }
+
+  if (code === "SQLITE_CONSTRAINT" || code === "SQLITE_CONSTRAINT_PRIMARYKEY" || code === "SQLITE_CONSTRAINT_UNIQUE") {
+    return true;
+  }
+
+  return /\bUNIQUE\b|\bPRIMARY KEY\b|\bconstraint failed\b/i.test(msg);
+}
+
+function ttlExpiry(now: Date): string {
+  return new Date(now.getTime() + LEASE_TTL_SECONDS * 1000).toISOString();
+}
+
+/**
+ * Acquire (or take over an expired) milestone lease for the given worker.
+ *
+ * Atomicity: the entire claim runs inside a single transaction so the
+ * INSERT-vs-UPDATE branch decision can never tear under concurrent claims.
+ * Fencing token is computed by SQL (`fencing_token + 1`), never supplied
+ * by the client. Initial value is 1.
+ *
+ * datetime('now') uses local wall-clock time, so this remains single-host
+ * SQLite WAL coordination only. Cross-host coordination would need a real
+ * coordinator; out of scope for Phase B.
+ */
+export function claimMilestoneLease(
+  workerId: string,
+  milestoneId: string,
+): ClaimResult {
+  if (!isDbAvailable()) {
+    throw new Error("claimMilestoneLease: DB unavailable");
+  }
+  const now = new Date();
+  const nowIso = now.toISOString();
+  const expiresIso = ttlExpiry(now);
+
+  return transaction((): ClaimResult => {
+    const db = _getAdapter()!;
+
+    // Step 1: try a fresh INSERT. If it fails because the row already
+    // exists, fall through to the takeover branch below.
+    let inserted = false;
+    try {
+      db.prepare(
+        `INSERT INTO milestone_leases (
+          milestone_id, worker_id, fencing_token,
+          acquired_at, expires_at, status
+        ) VALUES (
+          :milestone_id, :worker_id, 1,
+          :acquired_at, :expires_at, 'held'
+        )`,
+      ).run({
+        ":milestone_id": milestoneId,
+        ":worker_id": workerId,
+        ":acquired_at": nowIso,
+        ":expires_at": expiresIso,
+      });
+      inserted = true;
+    } catch (err) {
+      // SQLite raises a constraint error on duplicate PK — catch and fall
+      // through to UPDATE. Any other error is a bug; rethrow.
+      if (!isDuplicateLeaseInsertError(err)) throw err;
+    }
+
+    if (inserted) {
+      insertAuditEvent({
+        eventId: randomUUID(),
+        traceId: workerId,
+        category: "orchestration",
+        type: "lease-acquired",
+        ts: nowIso,
+        payload: { workerId, milestoneId, token: 1, mode: "fresh" },
+      });
+      return { ok: true, token: 1, expiresAt: expiresIso };
+    }
+
+    // Step 2: takeover. Conditional UPDATE — only succeeds if the existing
+    // lease is expired or explicitly released. Fencing token is incremented
+    // by SQL (`fencing_token + 1`) so the new holder's token monotonically
+    // exceeds the prior holder's. db.changes() === 1 confirms the takeover
+    // actually happened (vs. losing the race to another worker).
+    const updateResult = db.prepare(
+      `UPDATE milestone_leases
+       SET worker_id = :worker_id,
+           fencing_token = fencing_token + 1,
+           acquired_at = :acquired_at,
+           expires_at = :expires_at,
+           status = 'held'
+       WHERE milestone_id = :milestone_id
+         AND (status IN ('expired','released')
+              OR datetime(expires_at) < datetime('now'))`,
+    ).run({
+      ":milestone_id": milestoneId,
+      ":worker_id": workerId,
+      ":acquired_at": nowIso,
+      ":expires_at": expiresIso,
+    });
+
+    const changes =
+      typeof (updateResult as { changes?: unknown }).changes === "number"
+        ? (updateResult as { changes: number }).changes
+        : 0;
+
+    if (changes === 1) {
+      // Read back to obtain the new token value.
+      const row = db.prepare(
+        `SELECT worker_id, fencing_token, expires_at FROM milestone_leases WHERE milestone_id = :milestone_id`,
+      ).get({ ":milestone_id": milestoneId }) as Pick<MilestoneLeaseRow, "worker_id" | "fencing_token" | "expires_at"> | undefined;
+      const token = row?.fencing_token ?? 1;
+      insertAuditEvent({
+        eventId: randomUUID(),
+        traceId: workerId,
+        category: "orchestration",
+        type: "lease-acquired",
+        ts: nowIso,
+        payload: { workerId, milestoneId, token, mode: "takeover" },
+      });
+      return { ok: true, token, expiresAt: expiresIso };
+    }
+
+    // Lease still held by someone else — read current holder for the error.
+    const holder = db.prepare(
+      `SELECT worker_id, expires_at FROM milestone_leases WHERE milestone_id = :milestone_id`,
+    ).get({ ":milestone_id": milestoneId }) as { worker_id: string; expires_at: string } | undefined;
+
+    return {
+      ok: false,
+      error: "held_by",
+      byWorker: holder?.worker_id ?? "unknown",
+      expiresAt: holder?.expires_at ?? "",
+    };
+  });
+}
+
+/**
+ * Refresh the lease's expires_at when the worker heartbeats. Idempotent —
+ * silently no-ops if the lease was already taken over or released.
+ */
+export function refreshMilestoneLease(
+  workerId: string,
+  milestoneId: string,
+  fencingToken: number,
+): boolean {
+  if (!isDbAvailable()) return false;
+  const now = new Date();
+  const expiresIso = ttlExpiry(now);
+  const db = _getAdapter()!;
+  const result = db.prepare(
+    `UPDATE milestone_leases
+     SET expires_at = :expires_at
+     WHERE milestone_id = :milestone_id
+       AND worker_id = :worker_id
+       AND fencing_token = :token
+       AND status = 'held'`,
+  ).run({
+    ":expires_at": expiresIso,
+    ":milestone_id": milestoneId,
+    ":worker_id": workerId,
+    ":token": fencingToken,
+  });
+  const changes =
+    typeof (result as { changes?: unknown }).changes === "number"
+      ? (result as { changes: number }).changes
+      : 0;
+  return changes === 1;
+}
+
+/**
+ * Voluntarily release the lease (e.g. clean shutdown). Future claims may
+ * proceed without waiting for TTL expiry.
+ */
+export function releaseMilestoneLease(
+  workerId: string,
+  milestoneId: string,
+  fencingToken: number,
+): boolean {
+  if (!isDbAvailable()) return false;
+  const db = _getAdapter()!;
+  return transaction(() => {
+    const result = db.prepare(
+      `UPDATE milestone_leases
+       SET status = 'released'
+       WHERE milestone_id = :milestone_id
+         AND worker_id = :worker_id
+         AND fencing_token = :token
+         AND status = 'held'`,
+    ).run({
+      ":milestone_id": milestoneId,
+      ":worker_id": workerId,
+      ":token": fencingToken,
+    });
+    const changes =
+      typeof (result as { changes?: unknown }).changes === "number"
+        ? (result as { changes: number }).changes
+        : 0;
+    if (changes === 1) {
+      insertAuditEvent({
+        eventId: randomUUID(),
+        traceId: workerId,
+        category: "orchestration",
+        type: "lease-released",
+        ts: new Date().toISOString(),
+        payload: { workerId, milestoneId, token: fencingToken },
+      });
+    }
+    return changes === 1;
+  });
+}
+
+/**
+ * Read current lease row for diagnostics. Returns null if no row exists.
+ */
+export function getMilestoneLease(milestoneId: string): MilestoneLeaseRow | null {
+  if (!isDbAvailable()) return null;
+  const db = _getAdapter()!;
+  const row = db.prepare(
+    `SELECT milestone_id, worker_id, fencing_token, acquired_at, expires_at, status
+     FROM milestone_leases WHERE milestone_id = :milestone_id`,
+  ).get({ ":milestone_id": milestoneId }) as MilestoneLeaseRow | undefined;
+  return row ?? null;
+}
+
+/** TTL exported so callers (e.g. tests / janitors) can compute expirations. */
+export function milestoneLeaseTtlSeconds(): number {
+  return LEASE_TTL_SECONDS;
+}