@loopover/miner 0.1.0

package/lib/portfolio-queue-expiry.d.ts

@@ -0,0 +1,20 @@
+import type { QueueEntry, QueueLeaseEntry } from "./portfolio-queue.js";
+
+export declare const DEFAULT_MAX_LEASE_MS: number;
+
+export type PortfolioQueueExpiryStore = {
+  listInProgress(): QueueLeaseEntry[];
+  reclaimStuckItem(repoFullName: string, identifier: string): QueueEntry | null;
+};
+
+export function findStuckItems(
+  items: QueueLeaseEntry[],
+  nowMs: number,
+  maxLeaseMs: number,
+): QueueLeaseEntry[];
+
+export function sweepStuckItems(
+  store: PortfolioQueueExpiryStore,
+  nowMs: number,
+  maxLeaseMs?: number,
+): QueueEntry[];

package/lib/portfolio-queue-expiry.js

@@ -0,0 +1,51 @@
+/** PURE — no IO, no Date, no random (#4827). Mirror of claim-ledger-expiry.js for the portfolio-queue store: a
+ *  crashed/killed process leaves its item stuck 'in_progress' forever, so sweep leases older than a bound back to
+ *  'queued'. */
+
+// A generous default: a real attempt rarely holds a single portfolio item for long, so 30 minutes without the row
+// leaving 'in_progress' strongly implies the owning process died rather than that it is still working.
+export const DEFAULT_MAX_LEASE_MS = 30 * 60 * 1000;
+
+function leaseAgeMs(item, nowMs) {
+  const leasedAtMs = Date.parse(item.leasedAt);
+  if (!Number.isFinite(leasedAtMs)) return null;
+  return nowMs - leasedAtMs;
+}
+
+/**
+ * Return in-flight items whose lease age is strictly greater than `maxLeaseMs`. An item whose age equals
+ * `maxLeaseMs` exactly is still within the window (not stuck). Items that are not 'in_progress', or whose
+ * `leasedAt` is missing/unparseable, are never returned.
+ */
+export function findStuckItems(items, nowMs, maxLeaseMs) {
+  if (!Number.isFinite(nowMs) || nowMs < 0) throw new Error("invalid_now_ms");
+  if (!Number.isFinite(maxLeaseMs) || maxLeaseMs < 0) throw new Error("invalid_max_lease_ms");
+  if (!Array.isArray(items)) throw new Error("invalid_items");
+
+  const stuck = [];
+  for (const item of items) {
+    if (item?.status !== "in_progress") continue;
+    const ageMs = leaseAgeMs(item, nowMs);
+    if (ageMs === null) continue;
+    if (ageMs > maxLeaseMs) stuck.push(item);
+  }
+  return stuck;
+}
+
+/**
+ * Reclaim every stuck in-flight item back to 'queued', returning the reclaimed entries. `store.listInProgress()`
+ * supplies the lease-annotated rows and `store.reclaimStuckItem()` performs the atomic per-item flip — the same
+ * store/sweep split sweepExpiredClaims uses.
+ */
+export function sweepStuckItems(store, nowMs, maxLeaseMs = DEFAULT_MAX_LEASE_MS) {
+  const inProgress = store.listInProgress();
+  const stuck = findStuckItems(inProgress, nowMs, maxLeaseMs);
+  const reclaimed = [];
+  for (const item of stuck) {
+    // Echo the item's OWN apiBaseUrl back (#5563) rather than defaulting: two forge hosts can each have an
+    // in-flight item with the same owner/repo+identifier, and defaulting here would reclaim the wrong host's row.
+    const updated = store.reclaimStuckItem(item.repoFullName, item.identifier, item.apiBaseUrl);
+    if (updated) reclaimed.push(updated);
+  }
+  return reclaimed;
+}

package/lib/portfolio-queue-manager.d.ts

@@ -0,0 +1,50 @@
+import type { PortfolioCaps } from "@loopover/engine";
+import type { EnqueueItem, PortfolioQueueStore, QueueEntry } from "./portfolio-queue.js";
+
+export type PortfolioQueueClaimTarget = {
+  apiBaseUrl: string;
+  repoFullName: string;
+  identifier: string;
+};
+
+export function queueItemId(apiBaseUrl: string, repoFullName: string, identifier: string): string;
+
+export function parseQueueItemId(id: string): PortfolioQueueClaimTarget;
+
+export function normalizePortfolioCaps(caps?: Partial<PortfolioCaps>): PortfolioCaps;
+
+export function entriesToPortfolioQueue(entries: QueueEntry[]): {
+  buckets: Array<{
+    repoFullName: string;
+    items: Array<{ id: string; repoFullName: string; state: "queued" | "in_progress" }>;
+  }>;
+};
+
+export function selectEligibleBatch(
+  entries: QueueEntry[],
+  caps: PortfolioCaps,
+): PortfolioQueueClaimTarget[];
+
+export type PortfolioQueueManager = {
+  caps: PortfolioCaps;
+  store: PortfolioQueueStore;
+  dbPath: string;
+  enqueue(item: EnqueueItem): QueueEntry;
+  listQueue(repoFullName?: string | null): QueueEntry[];
+  markDone(repoFullName: string, identifier: string, apiBaseUrl?: string): QueueEntry | null;
+  markFailed(repoFullName: string, identifier: string, apiBaseUrl?: string): QueueEntry | null;
+  reclaimStuckItems(maxLeaseMs?: number): QueueEntry[];
+  claimNextBatch(): QueueEntry[];
+  close(): void;
+};
+
+export type InitPortfolioQueueManagerOptions = {
+  caps?: Partial<PortfolioCaps>;
+  store?: PortfolioQueueStore;
+  dbPath?: string;
+  staleLeaseMs?: number;
+};
+
+export function initPortfolioQueueManager(options?: InitPortfolioQueueManagerOptions): PortfolioQueueManager;
+
+export function closeDefaultPortfolioQueueManager(): void;

package/lib/portfolio-queue-manager.js

@@ -0,0 +1,134 @@
+// Stateful PortfolioQueueManager (#4285): compose the persisted SQLite portfolio/queue store
+// (portfolio-queue.js, #2292) with the pure engine selector (nextEligibleItems, queue.ts, #2326) so batch
+// claiming respects global/per-repo WIP caps and cross-repo diversification instead of a naive priority-only
+// single-row dequeue. Caps are plain constructor arguments — not wired to .gittensory-miner.yml here.
+import { nextEligibleItems } from "@loopover/engine";
+import { DEFAULT_FORGE_CONFIG } from "./forge-config.js";
+import { initPortfolioQueueStore } from "./portfolio-queue.js";
+import { DEFAULT_MAX_LEASE_MS, sweepStuckItems } from "./portfolio-queue-expiry.js";
+
+const ITEM_ID_SEPARATOR = "::";
+
+/**
+ * Stable composite id for projecting SQLite rows into the engine's PortfolioQueueItem shape. Encodes apiBaseUrl
+ * too (#5563) — the engine's own selection logic has no forge dimension, but two hosts can now enqueue an item
+ * under the same repoFullName+identifier (post-#5563 scoping), and the id is the ONLY thing selectEligibleBatch's
+ * output threads back to batchClaim; without the host baked in here, a selected item's host would be lost and
+ * batchClaim would default to github.com, potentially claiming a DIFFERENT row than the one the engine selected.
+ */
+export function queueItemId(apiBaseUrl, repoFullName, identifier) {
+  return `${apiBaseUrl}${ITEM_ID_SEPARATOR}${repoFullName}${ITEM_ID_SEPARATOR}${identifier}`;
+}
+
+/** Reverse {@link queueItemId} after engine selection so claims can target SQLite primary keys. */
+export function parseQueueItemId(id) {
+  if (typeof id !== "string") throw new Error("invalid_queue_item_id");
+  const firstSeparatorIndex = id.indexOf(ITEM_ID_SEPARATOR);
+  if (firstSeparatorIndex <= 0) throw new Error("invalid_queue_item_id");
+  const rest = id.slice(firstSeparatorIndex + ITEM_ID_SEPARATOR.length);
+  const secondSeparatorIndex = rest.indexOf(ITEM_ID_SEPARATOR);
+  if (secondSeparatorIndex <= 0 || secondSeparatorIndex === rest.length - ITEM_ID_SEPARATOR.length) {
+    throw new Error("invalid_queue_item_id");
+  }
+  return {
+    apiBaseUrl: id.slice(0, firstSeparatorIndex),
+    repoFullName: rest.slice(0, secondSeparatorIndex),
+    identifier: rest.slice(secondSeparatorIndex + ITEM_ID_SEPARATOR.length),
+  };
+}
+
+/** Coerce caps to finite non-negative integers (mirrors the engine's normalizeCaps posture). */
+export function normalizePortfolioCaps(caps = {}) {
+  const globalWipCap = Number.isFinite(caps.globalWipCap) ? Math.max(0, Math.trunc(caps.globalWipCap)) : 0;
+  const perRepoWipCap = Number.isFinite(caps.perRepoWipCap) ? Math.max(0, Math.trunc(caps.perRepoWipCap)) : 0;
+  return { globalWipCap, perRepoWipCap };
+}
+
+/** Project persisted queue rows into the engine's in-memory PortfolioQueue (done rows omitted). Pure. */
+export function entriesToPortfolioQueue(entries) {
+  const activeEntries = Array.isArray(entries) ? entries.filter((entry) => entry?.status !== "done") : [];
+  const bucketsByRepo = new Map();
+  const bucketOrder = [];
+  for (const entry of activeEntries) {
+    const repoFullName = typeof entry.repoFullName === "string" ? entry.repoFullName.trim() : "";
+    const identifier = typeof entry.identifier === "string" ? entry.identifier.trim() : "";
+    if (!repoFullName || !identifier) continue;
+    // Falls back to the github.com default (matching every store's own normalizeApiBaseUrl) so a row from
+    // before #5563 threaded apiBaseUrl through this fold still gets a valid, host-scoped id.
+    const apiBaseUrl = typeof entry.apiBaseUrl === "string" && entry.apiBaseUrl.trim() ? entry.apiBaseUrl.trim() : DEFAULT_FORGE_CONFIG.apiBaseUrl;
+    const repoKey = repoFullName.toLowerCase();
+    if (!bucketsByRepo.has(repoKey)) {
+      bucketsByRepo.set(repoKey, []);
+      bucketOrder.push(repoKey);
+    }
+    bucketsByRepo.get(repoKey).push({
+      id: queueItemId(apiBaseUrl, repoFullName, identifier),
+      repoFullName,
+      state: entry.status === "in_progress" ? "in_progress" : "queued",
+    });
+  }
+  return {
+    buckets: bucketOrder.map((repoFullName) => ({
+      repoFullName,
+      items: bucketsByRepo.get(repoFullName),
+    })),
+  };
+}
+
+/** Select the next eligible batch from active rows using the engine primitive. Pure. */
+export function selectEligibleBatch(entries, caps) {
+  const normalizedCaps = normalizePortfolioCaps(caps);
+  const queue = entriesToPortfolioQueue(entries);
+  return nextEligibleItems(queue, normalizedCaps).map((item) => parseQueueItemId(item.id));
+}
+
+/**
+ * Open a caps-aware portfolio queue manager backed by the local SQLite store. The existing single-row
+ * `dequeueNext()` CLI surface is untouched — this adds `claimNextBatch()` for fleet-style batch claiming.
+ */
+export function initPortfolioQueueManager(options = {}) {
+  const caps = normalizePortfolioCaps(options.caps ?? { globalWipCap: 1, perRepoWipCap: 1 });
+  const store = options.store ?? initPortfolioQueueStore(options.dbPath);
+  // A lease older than this means the process that claimed the item almost certainly died; the item is swept back
+  // to 'queued' so it no longer occupies WIP capacity forever (#4827).
+  const staleLeaseMs = Number.isFinite(options.staleLeaseMs) ? options.staleLeaseMs : DEFAULT_MAX_LEASE_MS;
+
+  return {
+    caps,
+    store,
+    dbPath: store.dbPath,
+    enqueue(item) {
+      return store.enqueue(item);
+    },
+    listQueue(repoFullName) {
+      return store.listQueue(repoFullName);
+    },
+    markDone(repoFullName, identifier, apiBaseUrl) {
+      return store.markDone(repoFullName, identifier, apiBaseUrl);
+    },
+    markFailed(repoFullName, identifier, apiBaseUrl) {
+      return store.markFailed(repoFullName, identifier, apiBaseUrl);
+    },
+    /** Sweep leases orphaned by a crashed/killed process back to 'queued', returning the reclaimed items (#4827). */
+    reclaimStuckItems(maxLeaseMs = staleLeaseMs) {
+      return sweepStuckItems(store, Date.now(), maxLeaseMs);
+    },
+    // The engine primitive itself (@loopover/engine's nextEligibleItems) has no apiBaseUrl concept --
+    // it only ever sees the opaque `id` string. queueItemId/parseQueueItemId (#5563) smuggle the host through
+    // that id round-trip, so selectFn's output below correctly carries each selected item's OWN apiBaseUrl into
+    // batchClaim, instead of every claim defaulting to github.com regardless of which host's row was selected.
+    claimNextBatch() {
+      // Reclaim orphaned leases first, so an item stranded 'in_progress' by a dead process becomes eligible again
+      // instead of permanently consuming a WIP slot and starving the queue.
+      sweepStuckItems(store, Date.now(), staleLeaseMs);
+      return store.batchClaim((entries) => selectEligibleBatch(entries, caps));
+    },
+    close() {
+      store.close();
+    },
+  };
+}
+
+export function closeDefaultPortfolioQueueManager() {
+  // Reserved for symmetry with other miner stores; managers are opened explicitly today.
+}

package/lib/portfolio-queue.d.ts

@@ -0,0 +1,62 @@
+export type QueueStatus = "queued" | "in_progress" | "done";
+
+export type QueueEntry = {
+  apiBaseUrl: string;
+  repoFullName: string;
+  identifier: string;
+  priority: number;
+  status: QueueStatus;
+  enqueuedAt: string;
+};
+
+export type EnqueueItem = {
+  repoFullName: string;
+  identifier: string;
+  priority?: number | null;
+  apiBaseUrl?: string;
+};
+
+/** Lease-annotated view of an in-flight row: when it was claimed, for the expiry sweep (#4827). */
+export type QueueLeaseEntry = {
+  apiBaseUrl: string;
+  repoFullName: string;
+  identifier: string;
+  status: QueueStatus;
+  leasedAt: string | null;
+};
+
+export type PortfolioQueueStore = {
+  dbPath: string;
+  enqueue(item: EnqueueItem): QueueEntry;
+  dequeueNext(): QueueEntry | null;
+  listQueue(repoFullName?: string | null): QueueEntry[];
+  listInProgress(): QueueLeaseEntry[];
+  markDone(repoFullName: string, identifier: string, apiBaseUrl?: string): QueueEntry | null;
+  markFailed(repoFullName: string, identifier: string, apiBaseUrl?: string): QueueEntry | null;
+  reclaimStuckItem(repoFullName: string, identifier: string, apiBaseUrl?: string): QueueEntry | null;
+  requeueItem(repoFullName: string, identifier: string, apiBaseUrl?: string): QueueEntry | null;
+  batchClaim(
+    selectFn: (
+      entries: QueueEntry[],
+    ) => Array<{ repoFullName: string; identifier: string; apiBaseUrl?: string }>,
+  ): QueueEntry[];
+  close(): void;
+};
+
+export const QUEUE_STATUSES: readonly QueueStatus[];
+
+export function resolvePortfolioQueueDbPath(env?: Record<string, string | undefined>): string;
+
+export function initPortfolioQueueStore(dbPath?: string): PortfolioQueueStore;
+
+export function enqueue(item: EnqueueItem): QueueEntry;
+
+export function dequeueNext(): QueueEntry | null;
+
+export function listQueue(repoFullName?: string | null): QueueEntry[];
+
+export function markDone(repoFullName: string, identifier: string, apiBaseUrl?: string): QueueEntry | null;
+
+export function markFailed(repoFullName: string, identifier: string, apiBaseUrl?: string): QueueEntry | null;
+
+export function closeDefaultPortfolioQueueStore(): void;

package/lib/portfolio-queue.js

@@ -0,0 +1,351 @@
+import { DEFAULT_FORGE_CONFIG } from "./forge-config.js";
+import { normalizeLocalStoreDbPath, openLocalStoreDb, resolveLocalStoreDbPath } from "./local-store.js";
+import { applySchemaMigrations } from "./schema-version.js";
+
+// The miner's local portfolio/queue store (#2292): a 100% client-side, prioritized backlog of candidate work
+// items across every repo the miner has been pointed at ("what should I look at next, across everything I'm
+// tracking"). The database only lives on this machine; this module never uploads, syncs, or phones home with its
+// contents. The `priority` field is a PLACEHOLDER numeric input in this foundation phase — later phases populate
+// it from the extracted reward-risk/scoring modules in `gittensory-engine`; it is not invented here.
+
+export const QUEUE_STATUSES = Object.freeze(["queued", "in_progress", "done"]);
+
+const defaultDbFileName = "portfolio-queue.sqlite3";
+let defaultPortfolioQueueStore = null;
+
+export function resolvePortfolioQueueDbPath(env = process.env) {
+  return resolveLocalStoreDbPath(defaultDbFileName, "GITTENSORY_MINER_PORTFOLIO_QUEUE_DB", env);
+}
+
+function normalizeDbPath(dbPath) {
+  return normalizeLocalStoreDbPath(dbPath, resolvePortfolioQueueDbPath(), "invalid_portfolio_queue_db_path");
+}
+
+function normalizeRepoFullName(repoFullName) {
+  if (typeof repoFullName !== "string") throw new Error("invalid_repo_full_name");
+  const trimmed = repoFullName.trim();
+  const [owner, repo, extra] = trimmed.split("/");
+  if (!owner || !repo || extra !== undefined) throw new Error("invalid_repo_full_name");
+  return `${owner}/${repo}`;
+}
+
+function normalizeIdentifier(identifier) {
+  if (typeof identifier !== "string") throw new Error("invalid_identifier");
+  const trimmed = identifier.trim();
+  if (!trimmed) throw new Error("invalid_identifier");
+  return trimmed;
+}
+
+/** Priority is a placeholder numeric input; an omitted priority defaults to 0, a non-finite or negative one is rejected. */
+function normalizePriority(priority) {
+  if (priority === undefined || priority === null) return 0;
+  if (typeof priority !== "number" || !Number.isFinite(priority) || priority < 0) {
+    throw new Error("invalid_priority");
+  }
+  return priority;
+}
+
+/** Optional forge host, scoping rows so two hosts serving the same owner/repo name never collide (#5563).
+ *  Omitted/nullish → the github.com default, so every pre-existing single-forge caller is unaffected. */
+function normalizeApiBaseUrl(apiBaseUrl) {
+  if (apiBaseUrl === undefined || apiBaseUrl === null) return DEFAULT_FORGE_CONFIG.apiBaseUrl;
+  if (typeof apiBaseUrl !== "string" || !apiBaseUrl.trim()) throw new Error("invalid_api_base_url");
+  return apiBaseUrl.trim();
+}
+
+function rowToEntry(row) {
+  return {
+    apiBaseUrl: row.api_base_url,
+    repoFullName: row.repo_full_name,
+    identifier: row.identifier,
+    priority: row.priority,
+    status: row.status,
+    enqueuedAt: row.enqueued_at,
+  };
+}
+
+/** Lease-annotated projection of an in-flight row (adds `leasedAt`), consumed by the expiry sweep. Kept separate
+ *  from `rowToEntry` so the base entry shape every existing caller relies on is unchanged. */
+function rowToLeaseEntry(row) {
+  return {
+    apiBaseUrl: row.api_base_url,
+    repoFullName: row.repo_full_name,
+    identifier: row.identifier,
+    status: row.status,
+    leasedAt: row.leased_at ?? null,
+  };
+}
+
+/**
+ * Opens the local portfolio/queue store, creating the table on first use. Rows are ordered highest-priority-first
+ * with an insertion-order tie-break: `priority DESC, enqueued_at ASC, rowid ASC` — the implicit `rowid` guarantees
+ * FIFO order even when two items share a priority AND an `enqueued_at` timestamp. (#2292)
+ */
+export function initPortfolioQueueStore(dbPath = resolvePortfolioQueueDbPath()) {
+  const resolvedPath = normalizeDbPath(dbPath);
+  // openLocalStoreDb skips mkdir/chmod for the special in-memory path (':memory:'), which has no file on disk.
+  const db = openLocalStoreDb(resolvedPath);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS miner_portfolio_queue (
+      repo_full_name TEXT NOT NULL,
+      identifier TEXT NOT NULL,
+      priority REAL NOT NULL DEFAULT 0,
+      status TEXT NOT NULL DEFAULT 'queued' CHECK (status IN ('queued', 'in_progress', 'done')),
+      enqueued_at TEXT NOT NULL,
+      leased_at TEXT,
+      PRIMARY KEY (repo_full_name, identifier)
+    )
+  `);
+  // `leased_at` records when an item was flipped to 'in_progress', so a crashed/killed process's stuck lease can be
+  // swept back to 'queued' by age (see portfolio-queue-expiry.js) instead of stranding the item forever — the same
+  // recovery the claim-ledger and worktree-allocator stores already provide for their own tables (#4827). Additive
+  // migration for stores created before this column: CREATE TABLE IF NOT EXISTS never adds a column to a pre-existing
+  // table, so add it idempotently. Expressed as the store's first schema migration (#4832): the baseline table is
+  // version 1; migration 1→2 adds `leased_at`. The migration stays defensive (checks table_info) so a version-0
+  // file that already ran the pre-convention ad-hoc ALTER is not re-altered into a duplicate-column error.
+  //
+  // v2 -> v3 (#5563): rebuild PRIMARY KEY (repo_full_name, identifier) into PRIMARY KEY (api_base_url,
+  // repo_full_name, identifier) -- two forge hosts serving a same-named owner/repo must not collide in this
+  // queue. SQLite cannot ALTER a PRIMARY KEY in place, so this rebuilds the table: create the new shape, copy
+  // every existing row with the pre-#4784 implicit single-forge default backfilled, drop the old table, rename
+  // the new one in.
+  applySchemaMigrations(db, [
+    (migrationDb) => {
+      const hasLeasedAtColumn = migrationDb
+        .prepare("PRAGMA table_info(miner_portfolio_queue)")
+        .all()
+        .some((column) => column.name === "leased_at");
+      if (!hasLeasedAtColumn) migrationDb.exec("ALTER TABLE miner_portfolio_queue ADD COLUMN leased_at TEXT");
+    },
+    (migrationDb) => {
+      migrationDb.exec(`
+        CREATE TABLE miner_portfolio_queue_v3 (
+          api_base_url TEXT NOT NULL,
+          repo_full_name TEXT NOT NULL,
+          identifier TEXT NOT NULL,
+          priority REAL NOT NULL DEFAULT 0,
+          status TEXT NOT NULL DEFAULT 'queued' CHECK (status IN ('queued', 'in_progress', 'done')),
+          enqueued_at TEXT NOT NULL,
+          leased_at TEXT,
+          PRIMARY KEY (api_base_url, repo_full_name, identifier)
+        )
+      `);
+      // ORDER BY rowid preserves the old table's FIFO insertion order in the new table's freshly-assigned rowids
+      // (the composite PRIMARY KEY above is not itself the rowid), so this rebuild doesn't reshuffle queue order.
+      // OR IGNORE: a row this store's own read path already treats as unusable garbage (an unrecognized
+      // `status`, e.g. from a hand-edited or otherwise corrupted file) would violate the CHECK constraint above
+      // and abort the whole migration. Skipping it here is consistent with that same fail-closed posture, rather
+      // than turning one bad row into a permanently unmigratable file.
+      migrationDb
+        .prepare(
+          `INSERT OR IGNORE INTO miner_portfolio_queue_v3
+             (api_base_url, repo_full_name, identifier, priority, status, enqueued_at, leased_at)
+           SELECT ?, repo_full_name, identifier, priority, status, enqueued_at, leased_at
+           FROM miner_portfolio_queue ORDER BY rowid`,
+        )
+        .run(DEFAULT_FORGE_CONFIG.apiBaseUrl);
+      migrationDb.exec("DROP TABLE miner_portfolio_queue");
+      migrationDb.exec("ALTER TABLE miner_portfolio_queue_v3 RENAME TO miner_portfolio_queue");
+    },
+  ]);
+
+  // `rowid` is a stable, unique key assigned once at first insert (re-enqueue updates in place, never re-inserts),
+  // so it is a deterministic total-order tie-break: two items sharing a priority AND an `enqueued_at` timestamp
+  // still order by insertion.
+  const ORDER = "ORDER BY priority DESC, enqueued_at ASC, rowid ASC";
+  // Re-enqueueing an already-tracked item re-activates it IN PLACE: refresh its (placeholder) priority and reset it
+  // to 'queued', but KEEP the original `enqueued_at` and `rowid` so it holds its existing FIFO position rather than
+  // jumping the queue. (Restamping `enqueued_at` would be inconsistent — the fixed `rowid` still pins the old
+  // position whenever timestamps collide — so position is deliberately preserved instead.)
+  const enqueueStatement = db.prepare(`
+    INSERT INTO miner_portfolio_queue (api_base_url, repo_full_name, identifier, priority, status, enqueued_at)
+    VALUES (?, ?, ?, ?, 'queued', ?)
+    ON CONFLICT(api_base_url, repo_full_name, identifier) DO UPDATE SET
+      priority = excluded.priority,
+      status = 'queued'
+    WHERE miner_portfolio_queue.status <> 'in_progress'
+  `);
+  const getStatement = db.prepare(
+    "SELECT * FROM miner_portfolio_queue WHERE api_base_url = ? AND repo_full_name = ? AND identifier = ?",
+  );
+  // Claim the highest-priority queued item ATOMICALLY: one UPDATE selects the ordered top row in a subquery and
+  // flips it to 'in_progress', RETURNING it — so two processes sharing the file can't both claim the same row (a
+  // separate SELECT-then-UPDATE would race). Deliberately global (no api_base_url filter): the queue is a single
+  // cross-host priority ordering, not a per-host one.
+  // Claiming stamps `leased_at` with the caller-supplied claim time; leaving 'in_progress' (done/failed/reclaim)
+  // clears it back to NULL so only genuinely in-flight rows carry a lease.
+  const dequeueStatement = db.prepare(`
+    UPDATE miner_portfolio_queue SET status = 'in_progress', leased_at = ?
+    WHERE rowid = (
+      SELECT rowid FROM miner_portfolio_queue WHERE status = 'queued' ${ORDER} LIMIT 1
+    )
+    RETURNING *
+  `);
+  // RETURNING (rather than a separate post-UPDATE SELECT) makes the "nothing to mark done" case observable
+  // directly from one atomic statement.
+  const markDoneStatement = db.prepare(`
+    UPDATE miner_portfolio_queue SET status = 'done', leased_at = NULL
+    WHERE api_base_url = ? AND repo_full_name = ? AND identifier = ? AND status <> 'done'
+    RETURNING *
+  `);
+  const markFailedStatement = db.prepare(`
+    UPDATE miner_portfolio_queue SET status = 'queued', leased_at = NULL
+    WHERE api_base_url = ? AND repo_full_name = ? AND identifier = ? AND status = 'in_progress'
+    RETURNING *
+  `);
+  const listAllStatement = db.prepare(`SELECT * FROM miner_portfolio_queue ${ORDER}`);
+  const listRepoStatement = db.prepare(
+    `SELECT * FROM miner_portfolio_queue WHERE repo_full_name = ? ${ORDER}`,
+  );
+  const listActiveStatement = db.prepare(
+    `SELECT * FROM miner_portfolio_queue WHERE status IN ('queued', 'in_progress') ${ORDER}`,
+  );
+  const listInProgressStatement = db.prepare(
+    `SELECT * FROM miner_portfolio_queue WHERE status = 'in_progress' ${ORDER}`,
+  );
+  const reclaimStatement = db.prepare(`
+    UPDATE miner_portfolio_queue SET status = 'queued', leased_at = NULL
+    WHERE api_base_url = ? AND repo_full_name = ? AND identifier = ? AND status = 'in_progress'
+    RETURNING *
+  `);
+  // Requeue only ever targets a COMPLETED ('done') row — an in-flight item is released via reclaimStatement, and
+  // an already-'queued' item is a no-op — so a caller's manual requeue can never disturb an active claim. The
+  // row keeps its rowid/enqueued_at, so it re-enters the queue at its original FIFO position, not the back.
+  const requeueStatement = db.prepare(`
+    UPDATE miner_portfolio_queue SET status = 'queued', leased_at = NULL
+    WHERE api_base_url = ? AND repo_full_name = ? AND identifier = ? AND status = 'done'
+    RETURNING *
+  `);
+  const claimTargetStatement = db.prepare(`
+    UPDATE miner_portfolio_queue SET status = 'in_progress', leased_at = ?
+    WHERE api_base_url = ? AND repo_full_name = ? AND identifier = ? AND status = 'queued'
+    RETURNING *
+  `);
+
+  return {
+    dbPath: resolvedPath,
+    enqueue(item) {
+      const apiBaseUrl = normalizeApiBaseUrl(item?.apiBaseUrl);
+      const repoFullName = normalizeRepoFullName(item?.repoFullName);
+      const identifier = normalizeIdentifier(item?.identifier);
+      const priority = normalizePriority(item?.priority);
+      const enqueuedAt = new Date().toISOString();
+      enqueueStatement.run(apiBaseUrl, repoFullName, identifier, priority, enqueuedAt);
+      return rowToEntry(getStatement.get(apiBaseUrl, repoFullName, identifier));
+    },
+    dequeueNext() {
+      const row = dequeueStatement.get(new Date().toISOString());
+      return row ? rowToEntry(row) : null;
+    },
+    /** In-flight ('in_progress') rows with their `leasedAt` claim time, for the expiry sweep (#4827). */
+    listInProgress() {
+      return listInProgressStatement.all().map(rowToLeaseEntry);
+    },
+    /** Reclaim a single stuck in-flight item back to 'queued' (clearing its lease), returning it — or null if it is
+     *  no longer 'in_progress' (already finished/reclaimed by another sweep). The sweep target of #4827. */
+    reclaimStuckItem(repoFullName, identifier, apiBaseUrl) {
+      const row = reclaimStatement.get(
+        normalizeApiBaseUrl(apiBaseUrl),
+        normalizeRepoFullName(repoFullName),
+        normalizeIdentifier(identifier),
+      );
+      return row ? rowToEntry(row) : null;
+    },
+    /** Requeue a COMPLETED ('done') item back to 'queued' so it is picked up again, keeping its FIFO position
+     *  (rowid/enqueued_at unchanged). Returns the entry, or null when there is no 'done' item to requeue — i.e.
+     *  it is already 'queued', is currently 'in_progress' (release it via {@link reclaimStuckItem} instead), or
+     *  does not exist. The manual counterpart to {@link reclaimStuckItem} for the queue CLI's escape hatch (#4828). */
+    requeueItem(repoFullName, identifier, apiBaseUrl) {
+      const row = requeueStatement.get(
+        normalizeApiBaseUrl(apiBaseUrl),
+        normalizeRepoFullName(repoFullName),
+        normalizeIdentifier(identifier),
+      );
+      return row ? rowToEntry(row) : null;
+    },
+    listQueue(repoFullName) {
+      const rows = repoFullName === undefined || repoFullName === null
+        ? listAllStatement.all()
+        : listRepoStatement.all(normalizeRepoFullName(repoFullName));
+      return rows.map(rowToEntry);
+    },
+    markDone(repoFullName, identifier, apiBaseUrl) {
+      const row = markDoneStatement.get(
+        normalizeApiBaseUrl(apiBaseUrl),
+        normalizeRepoFullName(repoFullName),
+        normalizeIdentifier(identifier),
+      );
+      return row ? rowToEntry(row) : null;
+    },
+    /** Release an in-flight item back to `queued` when a run halts (#2347). */
+    markFailed(repoFullName, identifier, apiBaseUrl) {
+      const row = markFailedStatement.get(
+        normalizeApiBaseUrl(apiBaseUrl),
+        normalizeRepoFullName(repoFullName),
+        normalizeIdentifier(identifier),
+      );
+      return row ? rowToEntry(row) : null;
+    },
+    /**
+     * Transactional caps-aware batch claim hook used by portfolio-queue-manager.js: re-read active rows under an
+     * exclusive lock, let the caller pick targets, then atomically flip each still-queued row to `in_progress`.
+     */
+    batchClaim(selectFn) {
+      if (typeof selectFn !== "function") throw new Error("invalid_batch_claim_selector");
+      db.exec("BEGIN IMMEDIATE");
+      try {
+        const entries = listActiveStatement.all().map(rowToEntry);
+        const targets = selectFn(entries);
+        if (!Array.isArray(targets)) throw new Error("invalid_batch_claim_selection");
+        const leasedAt = new Date().toISOString();
+        const claimed = [];
+        for (const target of targets) {
+          const apiBaseUrl = normalizeApiBaseUrl(target?.apiBaseUrl);
+          const repoFullName = normalizeRepoFullName(target?.repoFullName);
+          const identifier = normalizeIdentifier(target?.identifier);
+          const row = claimTargetStatement.get(leasedAt, apiBaseUrl, repoFullName, identifier);
+          if (row) claimed.push(rowToEntry(row));
+        }
+        db.exec("COMMIT");
+        return claimed;
+      } catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+      }
+    },
+    close() {
+      db.close();
+    },
+  };
+}
+
+function getDefaultPortfolioQueueStore() {
+  defaultPortfolioQueueStore ??= initPortfolioQueueStore();
+  return defaultPortfolioQueueStore;
+}
+
+export function enqueue(item) {
+  return getDefaultPortfolioQueueStore().enqueue(item);
+}
+
+export function dequeueNext() {
+  return getDefaultPortfolioQueueStore().dequeueNext();
+}
+
+export function listQueue(repoFullName) {
+  return getDefaultPortfolioQueueStore().listQueue(repoFullName);
+}
+
+export function markDone(repoFullName, identifier, apiBaseUrl) {
+  return getDefaultPortfolioQueueStore().markDone(repoFullName, identifier, apiBaseUrl);
+}
+
+export function markFailed(repoFullName, identifier, apiBaseUrl) {
+  return getDefaultPortfolioQueueStore().markFailed(repoFullName, identifier, apiBaseUrl);
+}
+
+export function closeDefaultPortfolioQueueStore() {
+  if (!defaultPortfolioQueueStore) return;
+  defaultPortfolioQueueStore.close();
+  defaultPortfolioQueueStore = null;
+}