champollion-mcp-server 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.1.1 (2026-08-27)
+
+Fixes the queue-tool timeouts found by live testing of the 0.1.0 npm release:
+with the queue at 211k+ open items, `list_queue`, `estimate_cost`,
+`get_project_info`, and `run_benchmark` all exceeded MCP clients' default 60s
+request timeout, because the DB fetch path drained the entire `queue_top`
+ranking (~423 sequential pages ≈ 3 minutes) before answering anything.
+
+- **Bounded, purpose-fit queue fetching.** Metadata comes from
+  queue-preview.json plus a live open-item count from the unpaged
+  `queue_pairs` RPC; ranked items are paged from `queue_top` only as deep as
+  the caller's selection needs (fetch-until-satisfied, bounded by
+  `CHAMPOLLION_QUEUE_MAX_PAGES`, default 20 pages / 10,000 rows); single
+  items are read by primary key over PostgREST with a verified-coverage
+  probe. When a bound truncates a search, the tool says how deep it looked —
+  no silent caps.
+- **`get_queue_item` / `run_benchmark(item_id)`** now do a direct by-id (or
+  mode+priority) lookup instead of scanning a full drain, and refuse items
+  already covered by a VERIFIED run instead of re-spending on them.
+- **Queue-mode `dry_run` is backgrounded** like a real run (the installed
+  harness loads the full queue before printing its plan): it returns a job id
+  immediately; the plan arrives via `get_run_status`.
+- **Failure ladder hardened.** A slow-but-alive DB degrades to a
+  truncated-but-honest prefix; a dead DB falls back to the static queue.json
+  blob; when both are down the error names both causes.
+- Harness (mt-eval, monorepo): `--top N` runs now page the DB queue only as
+  deep as selection needs, and `CHAMPOLLION_QUEUE_SOURCE=blob` is accepted as
+  a sentinel (previously read as a literal file path).
+
+## 0.1.0 (2026-08-27)
+
+Initial npm release.

package/README.md

@@ -27,7 +27,7 @@ When connected to an agent (Claude Code, Antigravity, Cursor, etc.), the server
 
 #### Training tools (nmt-forge)
 
-These wrap the [nmt-forge](https://github.com/gamedaysuits/Champollion) training suite. forge is part of the Champollion monorepo (not on PyPI) — clone the repo and set `CHAMPOLLION_FORGE_DIR` to its `forge/` directory; scoring additionally needs the eval harness (`pip install mt-eval`). Without forge present these tools return an actionable error rather than crashing.
+These wrap the [nmt-forge](https://github.com/gamedaysuits/Champollion) training suite. forge is part of the Champollion monorepo (not on PyPI) — clone the repo and set `CHAMPOLLION_FORGE_DIR` to its `forge/` directory; scoring additionally needs the eval harness (`pip install mt-eval-harness`). Without forge present these tools return an actionable error rather than crashing.
 
 | Tool | Type | Description |
 |---|---|---|
@@ -132,7 +132,7 @@ Once connected, you can talk to your agent naturally:
 >
 > **Agent** uses `list_queue` with `budget: 10` → sees what's available
 >
-> **Agent:** "I found a few thousand open benchmark items. Your $10 could fund dozens of runs. Any preference on languages?"
+> **Agent:** "The queue has over 200,000 open benchmark items. Your $10 could fund dozens of runs. Any preference on languages?"
 >
 > **You:** "West African languages"
 >

package/instructions.md

@@ -19,13 +19,13 @@ Start with `get_project_info` to understand what Champollion is and how contribu
 
 #### Running is asynchronous (important)
 
-A real benchmark runs a corpus through a live model and takes **minutes**, which is longer than the default 60-second request timeout most MCP clients (Claude Code, Cursor) enforce. So `run_benchmark` does **not** wait for the run to finish — it launches the run in the background and returns a `job id` right away. Treat that `STARTED` response as success, **not** completion.
+A real benchmark runs a corpus through a live model and takes **minutes**, which is longer than the default 60-second request timeout most MCP clients (Claude Code, Cursor) enforce. So `run_benchmark` does **not** wait for the run to finish — it launches the run in the background and returns a `job id` right away. Treat that `STARTED` response as success, **not** completion. (A queue-mode `dry_run` is backgrounded the same way — the harness loads the full ranked queue before printing its plan — so poll `get_run_status` for the plan; an `item_id` dry run answers inline.)
 
 - After `run_benchmark` returns, call `get_run_status { "job_id": "run-N" }`. Each poll returns instantly: `RUNNING` (keep polling), `COMPLETED` (output is in the response), `FAILED`, or `ERROR`.
 - Do **not** re-call `run_benchmark` because nothing "came back" — that would start a **second** run and spend tokens twice. The first call already started it; poll `get_run_status` instead.
 - Jobs live in the server process's memory, so a job id is only pollable from the same session. Call `get_run_status` with no `job_id` to list every job started this session.
 
-The estimate you show in step 4 is what executes: `run_benchmark` runs budget/top items in **deterministic top-of-queue order** (it passes `--no-spread`), so the selection matches the `estimate_cost` / `list_queue` preview item-for-item. (One caveat for honesty: `estimate_cost` samples up to ~500 matching items, so for a very large budget that funds more than that, treat its count/total as a lower bound.) A live run additionally skips any (corpus, model, condition) combo already on the leaderboard, so the executed set can be a subset of the preview — never a different, unseen set.
+The estimate you show in step 4 is what executes: `run_benchmark` runs budget/top items in **deterministic top-of-queue order** (it passes `--no-spread`), so the selection matches the `estimate_cost` / `list_queue` preview item-for-item. (One caveat for honesty: `estimate_cost` samples up to ~500 matching items from a bounded scan of the top of the ranking — its reply says how deep it looked when the bound bites — so for a very large budget or a very narrow filter, treat its count/total as a lower bound.) A live run additionally skips any (corpus, model, condition) combo already on the leaderboard, so the executed set can be a subset of the preview — never a different, unseen set.
 
 To spend tokens for **scoring/validation without writing to the leaderboard**, pass `publish: false` to `run_benchmark` (budget/top mode). A single `item_id` run is always scored locally and is never auto-published — publish it afterward with `mt-eval publish`, or use budget/top mode to auto-publish.
 
@@ -111,7 +111,7 @@ per-call report of what was cached, what was validated, and what it cost.
 
 ### "What languages need help?"
 
-1. Call `list_queue` with a generous limit to see what's available
+1. Call `list_queue` to see what's available (it fetches only as deep as your `limit` needs, so a generous limit is fine)
 2. Look for languages with the highest ECV (Expected Chain Value) — these have the most impact per dollar
 3. Use `search_languages` to find context: family, speakers, region, endonym
 
@@ -214,7 +214,7 @@ https://champollion.dev/docs/network/getting-started/contributing-compute
 - **Trust the queue ranking.** Items are ordered by ECV — the expected improvement in translation quality per dollar. Don't re-sort or second-guess the ranking.
 - **Budget mode skips, it doesn't stop.** If an item exceeds the remaining budget, the system skips it and continues to cheaper items further down the queue. This is by design — it maximizes what gets done within a budget.
 - **Items without cost estimates are skipped in budget mode.** Unknown cost ≠ free.
-- **The preview is what runs.** `run_benchmark` executes in deterministic top-of-queue order (`--no-spread`), so what `estimate_cost`/`list_queue` showed is what spends. Don't assume a different set ran.
+- **The preview is what runs.** `run_benchmark` executes in deterministic top-of-queue order (`--no-spread`), so what `estimate_cost`/`list_queue` showed is what spends. Don't assume a different set ran. (Both previews scan a bounded top slice of the ranking and say so when the bound bites; a very large budget can execute deeper than the preview sampled — the executed order is still the same ranking, top first.)
 - **Publishing writes to a public, production leaderboard.** Budget/top runs auto-publish each result by default. For a scoring/validation run with no leaderboard write, pass `publish: false`.
 - **Use `translate` for translation; don't improvise.** The tool's Translation Memory makes repeats free and its quality gate rejects garbage deterministically — a hand-rolled prompt has neither. Never present a gate-FAILED text as a translation.
 - **Translation ≠ evidence.** `translate` output is production translation; quality claims about methods and models come only from benchmark runs and the leaderboard.
@@ -225,7 +225,7 @@ The champollion.dev homepage map is an idealization — read the data, not
 the picture. The full endpoint table lives in the
 `champollion://network-data` resource.
 
-- **Queue**: served LIVE from the public database (read-only `queue_top` RPC) by default, with https://champollion.dev/queue.json as the fallback when the DB is unreachable (cached 5 minutes); small preview at https://champollion.dev/queue-preview.json
+- **Queue**: served LIVE from the public database by default — stats from queue-preview.json + the unpaged `queue_pairs` RPC, ranked items paged from the `queue_top` RPC only as deep as each question needs, single items by primary key — with https://champollion.dev/queue.json as the fallback when the DB is unreachable (cached 5 minutes); small preview at https://champollion.dev/queue-preview.json
 - **Mesh**: https://champollion.dev/mesh.json — the measured/registered pair network behind the map
 - **Corpus registry**: https://champollion.dev/registry.json — every registered eval corpus with license lane + attribution
 - **Provider coverage**: `shared/catalogue/method-coverage.json` (repo) — each provider's published language list, cited + as-of + `tier`. The map's green is two tiers by exact ISO-639-3 code: bright = a deployed service lists it (Google/Microsoft/DeepL/LibreTranslate); dim = only an open research model lists it (NLLB/OPUS/M2M-100/MADLAD-400 — a model-card code, not a usable service). "Covered" is a published-list claim, never a quality claim.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "champollion-mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP server for Champollion \u2014 exposes the public benchmark queue, language metadata, and mt-eval harness controls to AI agents.",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
     "src",
     "instructions.md",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {

package/src/index.js

@@ -42,7 +42,9 @@ import { readFile } from 'node:fs/promises';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { fetchQueue, filterQueue, getQueueItem, estimateCost } from './tools/queue.js';
+import {
+  fetchQueueMeta, selectFromQueue, lookupQueueItem, estimateCost,
+} from './tools/queue.js';
 import { searchLanguages, loadLanguageIndex } from './tools/languages.js';
 import { runBenchmark, getRunStatus } from './tools/harness.js';
 import { fetchResults, formatResults, fetchRunCard } from './tools/results.js';
@@ -84,8 +86,14 @@ export async function createServer() {
   // no instructions if the file is missing rather than failing startup.
   const instructions = await loadInstructions(resolve(__dirname, '..', 'instructions.md'));
 
+  // Version from package.json — the SSOT — so the handshake can never claim
+  // a stale release (0.1.1 shipped while the handshake still said 0.1.0).
+  const { version } = JSON.parse(
+    await readFile(resolve(__dirname, '..', 'package.json'), 'utf-8'),
+  );
+
   const server = new McpServer(
-    { name: 'champollion', version: '0.1.0' },
+    { name: 'champollion', version },
     instructions ? { instructions } : undefined,
   );
 
@@ -307,10 +315,10 @@ export async function createServer() {
     },
     async ({ budget, language, source_language, model, condition, limit }) => {
       try {
-        const queue = await fetchQueue();
-        const items = filterQueue(queue.items, {
+        const sel = await selectFromQueue({
           budget, language, source_language, model, condition, limit,
         });
+        const items = sel.selected;
 
         // Compute summary statistics for the filtered set
         const totalCost = items.reduce((s, it) => s + (it.est_cost_usd || 0), 0);
@@ -324,11 +332,19 @@ export async function createServer() {
           + `[${it.condition}]`
         );
 
+        // Honest truncation: the DB path only pages as deep as the selection
+        // needs (bounded); if the bound hit before `limit` matches were found,
+        // say how far the search went instead of implying the queue ran dry.
+        const depthNote = (!sel.complete && items.length < limit)
+          ? `Searched the top ${sel.scannedRows.toLocaleString()} ranked items — deeper matches may exist. Narrow the filters, or raise CHAMPOLLION_QUEUE_MAX_PAGES to scan deeper.`
+          : '';
+
         const summary = [
-          `Found ${items.length} items (of ${queue.metadata.open_items} total open).`,
+          `Found ${items.length} items (of ${sel.metadata.open_items} total open).`,
           `Estimated cost: $${totalCost.toFixed(2)}`,
           `Languages: ${languages.join(', ')}`,
-          `Models in queue: ${queue.metadata.models.map(m => m.split('/').pop()).join(', ')}`,
+          `Models in queue: ${sel.metadata.models.map(m => m.split('/').pop()).join(', ')}`,
+          ...(depthNote ? [depthNote] : []),
           '',
           ...lines,
         ].join('\n');
@@ -363,16 +379,21 @@ export async function createServer() {
         };
       }
       try {
-        const queue = await fetchQueue();
-        const item = getQueueItem(queue.items, { id, priority });
+        // Single-item lookups go straight to the queue_items primary key (or
+        // the mode+priority index) — never the ranked paging path.
+        const { item, covered, truncatedNote } = await lookupQueueItem({ id, priority });
         if (!item) {
+          const note = truncatedNote ? ` ${truncatedNote}` : '';
           return {
-            content: [{ type: 'text', text: `No queue item found for ${id ? `id="${id}"` : `priority=${priority}`}.` }],
+            content: [{ type: 'text', text: `No queue item found for ${id ? `id="${id}"` : `priority=${priority}`}.${note}` }],
             isError: true,
           };
         }
+        const coveredNote = covered === true
+          ? '\n\nNote: this item is already covered by a VERIFIED run — it is no longer an open work item and will not appear in list_queue.'
+          : '';
         return {
-          content: [{ type: 'text', text: JSON.stringify(item, null, 2) }],
+          content: [{ type: 'text', text: JSON.stringify(item, null, 2) + coveredNote }],
         };
       } catch (err) {
         return {
@@ -405,10 +426,17 @@ export async function createServer() {
     },
     async ({ budget, language, source_language, model, condition }) => {
       try {
-        const queue = await fetchQueue();
-        const result = estimateCost(queue.items, {
+        // Deepen the ranked prefix toward the estimate cap (500), then run
+        // the same pure aggregation as before over what was scanned.
+        const sel = await selectFromQueue({
+          budget, language, source_language, model, condition, limit: 500,
+        });
+        const result = estimateCost(sel.scanned, {
           budget, language, source_language, model, condition,
         });
+        const depthNote = (!sel.complete && !result.capped)
+          ? `Scanned the top ${sel.scannedRows.toLocaleString()} ranked items — treat count/total as a lower bound; deeper matches may exist.`
+          : '';
         return {
           content: [{
             type: 'text',
@@ -419,6 +447,7 @@ export async function createServer() {
               `Most expensive item: $${result.mostExpensive.toFixed(4)}`,
               `Languages covered: ${result.languages.join(', ')}`,
               budget ? `Budget remaining: $${(budget - result.totalCost).toFixed(2)}` : '',
+              depthNote,
             ].filter(Boolean).join('\n'),
           }],
         };
@@ -498,8 +527,9 @@ export async function createServer() {
     {},
     async () => {
       try {
-        const queue = await fetchQueue();
-        const meta = queue.metadata;
+        // Stats only — metadata comes from the preview + one aggregate RPC;
+        // this tool never needs a single ranked item.
+        const { metadata: meta } = await fetchQueueMeta();
         return {
           content: [{
             type: 'text',
@@ -520,7 +550,7 @@ export async function createServer() {
               'The easiest way to help: donate some API tokens to run benchmarks',
               'from the public queue. Anyone with an API key can contribute:',
               '',
-              '1. Install the harness: `pipx install mt-eval`',
+              '1. Install the harness: `pipx install mt-eval-harness`',
               '2. Set your API key: `export OPENROUTER_API_KEY=sk-or-...`',
               '3. Run from the queue: `mt-eval queue --budget 5`',
               '   (runs top items up to $5 estimated cost)',
@@ -537,7 +567,7 @@ export async function createServer() {
               '',
               '## Current Queue Stats',
               '',
-              `- Open items: ${meta.open_items.toLocaleString()}`,
+              `- Open items: ${meta.open_items.toLocaleString()}${meta.open_items_basis === 'generation' ? ' (as of last queue generation)' : ''}`,
               `- Corpora: ${meta.corpora}`,
               `- Models: ${meta.models.map(m => m.split('/').pop()).join(', ')}`,
               `- Conditions: ${meta.conditions.join(', ')}`,
@@ -1033,7 +1063,10 @@ export async function createServer() {
         .describe('Run a specific queue item by ID. One of '
           + 'budget/top/item_id is REQUIRED for a real run.'),
       dry_run: z.boolean().default(false)
-        .describe('If true, show what would be run without executing anything.'),
+        .describe('If true, show what would be run without executing anything. '
+          + 'A queue-mode (budget/top) dry run is backgrounded like a real run '
+          + '— it returns a job id; poll get_run_status for the plan. An '
+          + 'item_id dry run returns its plan inline.'),
       provider: z.enum(['openrouter', 'openai', 'anthropic', 'gemini']).optional()
         .describe('API provider. Auto-detected from environment if not specified.'),
       confirm: z.boolean().default(false)

package/src/tools/forge.js

@@ -91,7 +91,7 @@ export function runForge(subArgs, { workspace, timeout = 120_000 } = {}) {
           + 'Champollion monorepo (not on PyPI): clone '
           + 'https://github.com/gamedaysuits/Champollion and point '
           + 'CHAMPOLLION_FORGE_DIR at its forge/ directory. Scoring also needs '
-          + 'the eval harness: pip install mt-eval';
+          + 'the eval harness: pip install mt-eval-harness';
       }
       resolvePromise({ code: code ?? 1, stdout, stderr });
     });

package/src/tools/harness.js

@@ -146,22 +146,6 @@ export function stripAbsolutePaths(text) {
     .replace(/(?<![\w:/])\/(?:[^\s/'")\],]+\/)+([^\s/'")\],]+)/g, '$1');
 }
 
-/**
- * Reduce raw subprocess output to a single, path-stripped final error line.
- * A Python traceback ends with the `ExceptionType: message` line — the only
- * line worth relaying; the frames above it are local paths and stack noise.
- *
- * @param {string} stderr
- * @param {string} stdout
- * @returns {string}
- */
-function finalErrorLine(stderr, stdout) {
-  const source = (stderr || '').trim() || (stdout || '').trim();
-  if (!source) return '(no error output captured)';
-  const lines = source.split('\n').map((l) => l.trim()).filter(Boolean);
-  return stripAbsolutePaths(lines[lines.length - 1]);
-}
-
 // ---------------------------------------------------------------------------
 // Command construction — reconstruct argv locally, NEVER shell the queue.
 // ---------------------------------------------------------------------------
@@ -295,6 +279,7 @@ function tail(text) {
  * @param {object}   spec
  * @param {string[]} spec.argv     argv AFTER the `mt-eval` program name
  * @param {'item'|'queue'} spec.mode
+ * @param {boolean}  [spec.dryRun]  true = plan-only run, spends nothing
  * @param {string}   spec.label    human description of what's running
  * @param {string}   [spec.estLabel]  estimated-cost label for the start message
  * @param {boolean}  [spec.publish]   queue mode: will results publish?
@@ -302,11 +287,12 @@ function tail(text) {
  * @param {function} spec.exec     execCapture (injectable for tests)
  * @returns {object} the job record
  */
-function launchJob({ argv, mode, label, estLabel, publish, timeout, exec }) {
+function launchJob({ argv, mode, dryRun, label, estLabel, publish, timeout, exec }) {
   const id = newJobId();
   const job = {
     id,
     mode,
+    dryRun: dryRun === true,
     label,
     estLabel: estLabel ?? null,
     publish: publish !== false,
@@ -357,6 +343,22 @@ function launchJob({ argv, mode, label, estLabel, publish, timeout, exec }) {
 
 /** Build the "STARTED — poll get_run_status" message for a freshly launched job. */
 function formatJobStarted(job) {
+  if (job.dryRun) {
+    return [
+      'DRY-RUN STARTED — computing the queue plan in the background. No tokens',
+      'will be spent.',
+      '',
+      `Job id:  ${job.id}`,
+      `Running: ${job.label}`,
+      '',
+      'The harness loads the full ranked queue before printing its plan, which',
+      'can take a few minutes — longer than a default 60-second MCP client',
+      'request timeout — so it runs detached from this tool call.',
+      '',
+      `Next: poll get_run_status with { "job_id": "${job.id}" } every ~15-30s until`,
+      'it reports COMPLETED. The plan is in the job output.',
+    ].join('\n');
+  }
   const publishLine = job.mode === 'queue'
     ? (job.publish
       ? 'Each result auto-publishes to the public leaderboard as it finishes.'
@@ -427,12 +429,15 @@ export function getRunStatus(jobId) {
   }
 
   if (job.status === 'completed') {
-    const closing = job.mode === 'queue'
-      ? (job.publish
-        ? 'Each result was published to the public leaderboard — call get_results '
-          + '(filtered to this pair/model) to see it.'
-        : 'Results were scored but NOT published (validation run).')
-      : 'Scored locally (single-item runs are not auto-published).';
+    const closing = job.dryRun
+      ? 'Dry-run plan above — no tokens were spent. Run again with confirm: true '
+        + 'to execute it.'
+      : job.mode === 'queue'
+        ? (job.publish
+          ? 'Each result was published to the public leaderboard — call get_results '
+            + '(filtered to this pair/model) to see it.'
+          : 'Results were scored but NOT published (validation run).')
+        : 'Scored locally (single-item runs are not auto-published).';
     return [
       `COMPLETED — job ${job.id} (took ${secs}s)`,
       job.label,
@@ -495,8 +500,11 @@ export function resetJobs() {
  * subprocess is launched in the BACKGROUND and a job handle is returned
  * immediately, so the call returns well under any MCP client request timeout
  * (the SDK default is 60s, far shorter than a real run). The agent then polls
- * get_run_status with the returned job id until the job settles. dry_run and
- * the planner stay synchronous (they are fast, no model calls).
+ * get_run_status with the returned job id until the job settles. A queue-mode
+ * dry_run is ALSO backgrounded — the harness loads the full ranked queue
+ * before printing its plan, which can take minutes. Item-mode dry_run and the
+ * confirmation prompts stay synchronous (local argv construction, no
+ * subprocess).
  *
  * @param {object} params
  * @param {number} [params.budget]    Budget cap in USD
@@ -521,7 +529,7 @@ export async function runBenchmark(
 ) {
   const {
     isMtEvalInstalled: checkInstalled = isMtEvalInstalled,
-    fetchQueue = null,
+    lookupQueueItem = null,
     execCapture: exec = execCapture,
   } = deps;
 
@@ -532,7 +540,7 @@ export async function runBenchmark(
       'mt-eval is not installed on this machine.',
       '',
       'To install it, run:',
-      '  pipx install mt-eval',
+      '  pipx install mt-eval-harness',
       '',
       'After installation, set your API key:',
       '  export OPENROUTER_API_KEY=sk-or-...',
@@ -543,13 +551,23 @@ export async function runBenchmark(
 
   // ----- Specific item -----------------------------------------------------
   if (item_id) {
-    const getQueue = fetchQueue
-      ?? (await import('./queue.js')).fetchQueue;
-    const queue = await getQueue();
-    const item = queue.items.find((it) => it.id === item_id);
+    // Direct primary-key lookup — the 0.1.0 code drained the entire ranked
+    // queue (211k+ items, minutes of paging) to run one .find().
+    const lookup = lookupQueueItem
+      ?? (await import('./queue.js')).lookupQueueItem;
+    const { item, covered } = await lookup({ id: item_id });
     if (!item) {
       return `Queue item "${item_id}" not found. Use list_queue to see available items.`;
     }
+    if (covered === true) {
+      return [
+        `REFUSED — queue item "${item_id}" is already covered by a VERIFIED run.`,
+        '',
+        'Running it again would spend tokens re-measuring a combination the',
+        'leaderboard already has a refereed result for. Use list_queue to pick',
+        'an open item instead (open items are coverage-filtered automatically).',
+      ].join('\n');
+    }
 
     // Reconstruct a shell-free argv from STRUCTURED fields. The item's
     // network-supplied run_command is NEVER executed.
@@ -638,26 +656,26 @@ export async function runBenchmark(
 
   if (dry_run) {
     args.push('--dry-run');
-    const { code, stdout, stderr } = await exec('mt-eval', args, {
+    // Background even the dry-run: `mt-eval queue` loads the FULL ranked
+    // queue before printing its plan (the DB queue is 211k+ items — minutes
+    // of paging on harness versions that drain it), so awaiting it inline
+    // blew the client's 60s request timeout every time. The plan lands in
+    // the job's output; the agent polls get_run_status like any run.
+    const scope = budget != null
+      ? `dry-run plan for up to $${Number(budget).toFixed(2)}`
+      : top != null
+        ? `dry-run plan for the top ${top} item(s)`
+        : 'dry-run plan for the full queue';
+    const job = launchJob({
+      argv: args,
+      mode: 'queue',
+      dryRun: true,
+      label: scope,
+      publish,
       timeout: 1800_000,
+      exec,
     });
-    if (code !== 0) {
-      // Never relay the raw harness output here — a Python traceback carries
-      // local absolute paths. Surface the final error line (path-stripped)
-      // and keep the full detail in the debug log only.
-      await writeDebugLog(
-        `queue dry-run failed (exit ${code}) — argv: mt-eval ${args.join(' ')}`,
-        debugDetail(stdout, stderr),
-      );
-      return [
-        `Queue dry-run failed (exit code ${code}): ${finalErrorLine(stderr, stdout)}`,
-        '',
-        'Hint: this error came from the local mt-eval harness, not the queue. '
-        + 'Run the same mt-eval command in a terminal to reproduce; the full '
-        + `unedited output was saved to the debug log (${DEBUG_LOG_HINT}).`,
-      ].join('\n');
-    }
-    return stdout || 'Queue dry-run completed (no output captured).';
+    return formatJobStarted(job);
   }
 
   // ENFORCED bound on scope. Without a selector, argv is

package/src/tools/queue.js

@@ -3,11 +3,20 @@
  *
  * Data source (default): the live queue served from Postgres via the queue_top
  * RPC — a ranked list of (corpus, model, condition) items, coverage-filtered
- * against VERIFIED runs, so nothing stale or already-done is shown. Items are
- * paged from the RPC; metadata comes from the small queue-preview.json. If the
- * DB is unreachable, fetchQueue falls back to the full static queue.json blob,
- * so the tools never break. Set CHAMPOLLION_QUEUE_SOURCE=blob to force the blob.
- * An in-memory CACHE_TTL_MS cache avoids re-fetching on every tool call.
+ * against VERIFIED runs, so nothing stale or already-done is shown.
+ *
+ * The queue is six figures deep (211k+ open items as of 2026-08), so the DB
+ * path NEVER drains it: metadata comes from the small queue-preview.json (with
+ * a live open-item count from the unpaged queue_pairs RPC), ranked items are
+ * paged from queue_top only as deep as the caller's selection needs (bounded
+ * by MAX_DB_PAGES), and single-item lookups go straight to the queue_items
+ * primary key over PostgREST. Draining was the 0.1.0 failure mode: 423
+ * sequential pages ≈ 3 minutes, past every MCP client's 60s request timeout.
+ *
+ * If the DB is unreachable, every entry point falls back to the static
+ * queue.json blob, so the tools never break. Set CHAMPOLLION_QUEUE_SOURCE=blob
+ * to force the blob. An in-memory CACHE_TTL_MS cache (a growing ranked prefix,
+ * never re-fetched from page 0) avoids re-fetching on every tool call.
  */
 
 const QUEUE_URL = 'https://champollion.dev/queue.json';
@@ -15,7 +24,9 @@ const QUEUE_URL = 'https://champollion.dev/queue.json';
 // coverage-filtered against VERIFIED runs, so items are never stale. Metadata
 // (open_items, models, priority_model, cost_basis, how_to_run) comes from the
 // small queue-preview.json companion. The full static blob remains the FALLBACK
-// so this tool never breaks if the DB is unreachable.
+// so this tool never breaks if the DB is unreachable. (The blob itself is a
+// self-describing top slice when the ranking outgrows its size cap — see
+// metadata.blob_truncated — so "fallback" never silently means "everything".)
 const PREVIEW_URL = 'https://champollion.dev/queue-preview.json';
 const SUPABASE_URL = process.env.MT_EVAL_SUPABASE_URL
   || 'https://sjdomynysdljkbemupqa.supabase.co';
@@ -26,6 +37,21 @@ const QUEUE_TOP_PAGE = 500; // matches the RPC's hard page cap
 // the legacy static file (used by the existing fetch tests).
 const QUEUE_SOURCE = process.env.CHAMPOLLION_QUEUE_SOURCE || 'db';
 const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+// Selection-depth bound for the DB path: at most this many queue_top pages per
+// cache generation (default 20 → 10,000 ranked rows ≈ 8-10s of paging). Every
+// consumer needs ≤500 post-filter items, so the bound only bites on narrow
+// filters over a huge queue — and then the tools SAY how deep they looked
+// (no silent caps). Env-tunable for agents that want to scan deeper.
+const MAX_DB_PAGES = (() => {
+  const n = Number.parseInt(process.env.CHAMPOLLION_QUEUE_MAX_PAGES ?? '', 10);
+  return Number.isInteger(n) && n > 0 ? n : 20;
+})();
+// Wall-clock budget for one exported queue operation's DB round trips.
+// Chosen so that even the worst ladder — DB hangs to the full deadline, THEN
+// the blob fallback takes its whole 30s request window — still lands under
+// the 60s MCP client default (25s + 30s + parse < 60s). A slow network
+// degrades to a truncated-but-honest answer, not a dead tool.
+const DB_DEADLINE_MS = 25_000;
 
 // Served item fields (what queue.json publishes / consumers rely on). queue_top
 // rows also carry rank_mode/map_value/diagnostics/generation_id/generated_at —
@@ -37,103 +63,387 @@ const SERVED_FIELDS = [
   'run_command',
 ];
 
-let _cache = null;
+// The queue cache: ONE generation at a time. On the DB path `items` is a
+// ranked PREFIX that grows in place as callers ask deeper (never re-fetching
+// page 0); on the blob path it is whatever the blob shipped. `complete` means
+// "we have seen the end of the served ranking". A generation lives CACHE_TTL_MS
+// from its first fetch, then the whole thing resets.
+let _cache = null;   // { source, metadata, items, complete, pages }
 let _cacheTime = 0;
 
+/** Standard headers for Supabase REST/RPC calls (anon key is publishable). */
+function dbHeaders() {
+  return {
+    'apikey': SUPABASE_ANON_KEY,
+    'Authorization': `Bearer ${SUPABASE_ANON_KEY}`,
+    'Content-Type': 'application/json',
+    'Accept': 'application/json',
+  };
+}
+
+/** Per-request abort signal that also respects the operation deadline. */
+function signalFor(deadline) {
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) throw new Error('queue operation deadline exceeded');
+  return AbortSignal.timeout(Math.min(30_000, remaining));
+}
+
+/** Project a queue_top/queue_items row down to the served item shape. */
+function projectRow(row) {
+  const item = {};
+  for (const f of SERVED_FIELDS) if (row[f] !== undefined) item[f] = row[f];
+  // The restricted-corpus `transmission` stamp is a SERVED extra on
+  // queue.json but not a queue_items COLUMN — the ranker writes it into
+  // the diagnostics JSONB. Projecting columns alone dropped it from every
+  // DB-served item, so agents pulling work through MCP lost the no-train
+  // channel requirement the blob discloses. Lift it back.
+  const stamp = row.diagnostics?.transmission;
+  if (stamp && typeof stamp === 'object' && stamp.policy) item.transmission = stamp;
+  return item;
+}
+
+/** Return the fresh cache generation for `source`, or null. */
+function freshCache(source) {
+  if (_cache && _cache.source === source
+      && (Date.now() - _cacheTime) < CACHE_TTL_MS) {
+    return _cache;
+  }
+  return null;
+}
+
 /**
- * Fetch the queue, returning the cached version if still fresh.
+ * Ensure a cache generation exists: metadata loaded, items array started.
  *
- * The static host can serve an HTML holding page with HTTP 200 (site gated,
- * maintenance, CDN error page) — `resp.json()` would then surface a raw
- * `SyntaxError: Unexpected token '<'` to every queue-backed tool (list_queue,
- * get_queue_item, estimate_cost, get_project_info, and run_benchmark's item
- * lookup all relay err.message verbatim). The body is therefore read as text
- * and parsed here, so a non-JSON response becomes ONE clean, user-facing
- * error at this shared choke point. Failures are never cached — the next
- * call re-fetches.
+ * DB path: metadata from queue-preview.json, then the LIVE open-item count
+ * from one unpaged queue_pairs call (SUM of per-pair counts — same verified-
+ * coverage filter as queue_top, so it is the true served total without
+ * draining anything). If queue_pairs fails, the preview's generation-time
+ * open_items stands, stamped `open_items_basis: 'generation'`.
  *
- * @param {object} [opts]
- * @param {typeof fetch} [opts.fetchImpl]  Injectable fetch (for tests).
- * @returns {Promise<{ metadata: object, items: object[] }>}
+ * Blob path: the whole blob (metadata + items, complete by definition —
+ * "complete" meaning the end of what the blob SERVES; a size-capped blob
+ * says so itself via metadata.blob_truncated).
+ *
+ * Throws on failure so callers can fall back — never caches a failure.
  */
-export async function fetchQueue({ fetchImpl = fetch, source = QUEUE_SOURCE } = {}) {
-  const now = Date.now();
-  if (_cache && (now - _cacheTime) < CACHE_TTL_MS) {
-    return _cache;
-  }
+async function ensureCache(fetchImpl, source, deadline) {
+  const hit = freshCache(source);
+  if (hit) return hit;
 
-  let data;
+  let gen;
   if (source === 'blob') {
-    data = await fetchQueueFromBlob(fetchImpl);
+    const data = await fetchQueueFromBlob(fetchImpl);
+    gen = {
+      source, metadata: data.metadata, items: data.items,
+      complete: true, pages: 0,
+    };
   } else {
-    // Live DB path with a graceful fallback: a DB/preview failure must never
-    // take the tool down when the static blob is still being served.
+    // Metadata + preview from the companion file (a few hundred KB — ~292 KB
+    // as of 2026-08; it grows with the queue, so never assume it is tiny).
+    const pResp = await fetchImpl(PREVIEW_URL, {
+      headers: { 'Accept': 'application/json' },
+      signal: signalFor(deadline),
+    });
+    if (!pResp.ok) throw new Error(`preview HTTP ${pResp.status}`);
+    const preview = JSON.parse(await pResp.text());
+    const metadata = preview?.metadata;
+    if (metadata === null || typeof metadata !== 'object') {
+      throw new Error('queue-preview.json missing metadata');
+    }
+    gen = {
+      source,
+      metadata: { ...metadata, open_items_basis: 'generation' },
+      items: [],
+      complete: false,
+      pages: 0,
+    };
+    // Live open count — best-effort; the generation-time count stands if the
+    // aggregate RPC is down (the ranked items themselves are unaffected).
     try {
-      data = await fetchQueueFromDb(fetchImpl);
+      const resp = await fetchImpl(`${SUPABASE_URL}/rest/v1/rpc/queue_pairs`, {
+        method: 'POST',
+        headers: dbHeaders(),
+        body: JSON.stringify({ p_rank_mode: metadata.rank_mode || 'map' }),
+        signal: signalFor(deadline),
+      });
+      if (resp.ok) {
+        const pairs = JSON.parse(await resp.text());
+        if (Array.isArray(pairs)) {
+          // Live count = SUM over per-pair counts. Never used to short-circuit
+          // paging — a misreported 0 must not suppress the ranked fetch.
+          const live = pairs.reduce((s, p) => s + (Number(p.item_count) || 0), 0);
+          gen.metadata.open_items = live;
+          gen.metadata.open_items_basis = 'live';
+        }
+      }
     } catch {
-      data = await fetchQueueFromBlob(fetchImpl);
+      // keep generation-time open_items
     }
   }
 
-  _cache = data;
-  _cacheTime = now;
-  return data;
+  _cache = gen;
+  _cacheTime = Date.now();
+  return gen;
 }
 
-/** Serve the live queue from Postgres: items from the queue_top RPC (paged,
- *  coverage-filtered against verified runs), metadata from queue-preview.json.
- *  Throws on any failure so fetchQueue can fall back to the static blob. */
-async function fetchQueueFromDb(fetchImpl) {
-  // Metadata + preview from the companion file (a few hundred KB — ~292 KB
-  // as of 2026-08; it grows with the queue, so never assume it is tiny).
-  const pResp = await fetchImpl(PREVIEW_URL, {
-    headers: { 'Accept': 'application/json' },
-    signal: AbortSignal.timeout(30_000),
+/** Fetch ONE queue_top page at the generation's current watermark and append
+ *  it. Returns the number of rows appended. Marks the generation complete on
+ *  a short page. Throws on failure (callers decide whether that is fatal). */
+async function fetchNextPage(fetchImpl, gen, deadline) {
+  const resp = await fetchImpl(`${SUPABASE_URL}/rest/v1/rpc/queue_top`, {
+    method: 'POST',
+    headers: dbHeaders(),
+    body: JSON.stringify({
+      p_rank_mode: gen.metadata.rank_mode || 'map',
+      p_limit: QUEUE_TOP_PAGE,
+      p_offset: gen.items.length,
+    }),
+    signal: signalFor(deadline),
   });
-  if (!pResp.ok) throw new Error(`preview HTTP ${pResp.status}`);
-  const preview = JSON.parse(await pResp.text());
-  const metadata = preview?.metadata;
-  if (metadata === null || typeof metadata !== 'object') {
-    throw new Error('queue-preview.json missing metadata');
+  if (!resp.ok) throw new Error(`queue_top HTTP ${resp.status}`);
+  const page = JSON.parse(await resp.text());
+  if (!Array.isArray(page)) throw new Error('queue_top did not return an array');
+  for (const row of page) gen.items.push(projectRow(row));
+  gen.pages += 1;
+  if (page.length < QUEUE_TOP_PAGE) gen.complete = true;
+  return page.length;
+}
+
+/**
+ * Deepen the generation's ranked prefix until it satisfies `isSatisfied(items)`
+ * or a stop condition: ranking complete, MAX_DB_PAGES spent, deadline reached,
+ * or a mid-flight page error AFTER some rows already arrived (page-1 errors
+ * rethrow so the caller can fall back to the blob; later errors degrade to a
+ * truncated-but-honest prefix rather than throwing away everything fetched).
+ */
+async function deepenUntil(fetchImpl, gen, deadline, isSatisfied) {
+  while (!gen.complete
+      && !isSatisfied(gen.items)
+      && gen.pages < MAX_DB_PAGES
+      && Date.now() < deadline) {
+    try {
+      await fetchNextPage(fetchImpl, gen, deadline);
+    } catch (err) {
+      if (gen.items.length === 0) throw err;
+      break; // keep the partial prefix; tools report the depth honestly
+    }
   }
-  const rankMode = metadata.rank_mode || 'map';
-
-  // Page through the RPC until a short page signals the end.
-  const items = [];
-  for (let offset = 0; ; offset += QUEUE_TOP_PAGE) {
-    const resp = await fetchImpl(`${SUPABASE_URL}/rest/v1/rpc/queue_top`, {
-      method: 'POST',
-      headers: {
-        'apikey': SUPABASE_ANON_KEY,
-        'Authorization': `Bearer ${SUPABASE_ANON_KEY}`,
-        'Content-Type': 'application/json',
-        'Accept': 'application/json',
-      },
-      body: JSON.stringify({
-        p_rank_mode: rankMode, p_limit: QUEUE_TOP_PAGE, p_offset: offset,
-      }),
-      signal: AbortSignal.timeout(30_000),
-    });
-    if (!resp.ok) throw new Error(`queue_top HTTP ${resp.status}`);
-    const page = JSON.parse(await resp.text());
-    if (!Array.isArray(page)) throw new Error('queue_top did not return an array');
-    for (const row of page) {
-      const item = {};
-      for (const f of SERVED_FIELDS) if (row[f] !== undefined) item[f] = row[f];
-      // The restricted-corpus `transmission` stamp is a SERVED extra on
-      // queue.json but not a queue_items COLUMN — the ranker writes it into
-      // the diagnostics JSONB. Projecting columns alone dropped it from every
-      // DB-served item, so agents pulling work through MCP lost the no-train
-      // channel requirement the blob discloses. Lift it back.
-      const stamp = row.diagnostics?.transmission;
-      if (stamp && typeof stamp === 'object' && stamp.policy) item.transmission = stamp;
-      items.push(item);
+}
+
+/**
+ * Fetch queue metadata only — no ranked items. This is what get_project_info
+ * and any stats display should use: on the DB path it costs one preview GET
+ * plus one unpaged aggregate RPC, never a queue_top page.
+ *
+ * Falls back to the blob's metadata if the DB path fails outright.
+ *
+ * @returns {Promise<{ metadata: object }>}
+ */
+export async function fetchQueueMeta({ fetchImpl = fetch, source = QUEUE_SOURCE } = {}) {
+  const deadline = Date.now() + DB_DEADLINE_MS;
+  if (source === 'blob') {
+    const gen = await ensureCache(fetchImpl, 'blob', deadline);
+    return { metadata: gen.metadata };
+  }
+  try {
+    const gen = await ensureCache(fetchImpl, source, deadline);
+    return { metadata: gen.metadata };
+  } catch (dbErr) {
+    return { metadata: (await blobFallback(fetchImpl, dbErr, source)).metadata };
+  }
+}
+
+/**
+ * Fetch enough of the ranked queue to satisfy a filterQueue selection, then
+ * run the (untouched, SSOT-locked) filterQueue over it.
+ *
+ * The deepening loop exists because filter/budget semantics make "rows
+ * scanned" ≠ "items selected": budget mode SKIPS over-budget items and keeps
+ * walking, and narrow language/model filters may match sparsely. So we page,
+ * re-filter, and page again until the selection is satisfied or a bound hits.
+ *
+ * @param {object} [opts]  filterQueue filters + { limit, fetchImpl, source }
+ * @returns {Promise<{
+ *   selected: object[],   // filterQueue's picks, in ranking order
+ *   scanned:  object[],   // the ranked prefix examined (for estimateCost)
+ *   metadata: object,
+ *   complete: boolean,    // true = the WHOLE served ranking was examined
+ *   scannedRows: number,  // how deep the examination went
+ * }>}
+ */
+export async function selectFromQueue({
+  budget = null, language = null, source_language = null, model = null,
+  condition = null, limit = 20,
+  fetchImpl = fetch, source = QUEUE_SOURCE,
+} = {}) {
+  const deadline = Date.now() + DB_DEADLINE_MS;
+  const filters = { budget, language, source_language, model, condition, limit };
+
+  let gen;
+  if (source === 'blob') {
+    gen = await ensureCache(fetchImpl, 'blob', deadline);
+  } else {
+    try {
+      gen = await ensureCache(fetchImpl, source, deadline);
+      await deepenUntil(fetchImpl, gen, deadline,
+        (items) => filterQueue(items, filters).length >= limit);
+    } catch (dbErr) {
+      gen = await blobFallback(fetchImpl, dbErr, source);
+    }
+  }
+
+  return {
+    selected: filterQueue(gen.items, filters),
+    scanned: gen.items,
+    metadata: gen.metadata,
+    complete: gen.complete === true,
+    scannedRows: gen.items.length,
+  };
+}
+
+/**
+ * Look up ONE queue item by id or priority rank — without touching the ranked
+ * paging at all. On the DB path this is a primary-key (or mode+priority index)
+ * read on queue_items over PostgREST, plus a one-row run_cards probe that
+ * replicates queue_top's verified-coverage filter (queue_items itself is the
+ * raw registered set, so a row can exist yet already be verified-covered).
+ *
+ * NOTE: never offset arithmetic — queue_top's coverage filter means row N of
+ * the served ranking is NOT the row with priority N, so priority lookups
+ * match the stored priority field, exactly like the in-memory getQueueItem.
+ *
+ * @param {{ id?: string, priority?: number, fetchImpl?, source? }} opts
+ * @returns {Promise<{
+ *   item: object|null,
+ *   covered: boolean|null,   // true = exists but a VERIFIED run already covers
+ *                            // it (not an open work item); null = probe failed
+ *   truncatedNote: string|null, // set when a not-found came from a truncated
+ *                               // blob fallback and the item might exist deeper
+ * }>}
+ */
+export async function lookupQueueItem({
+  id, priority, fetchImpl = fetch, source = QUEUE_SOURCE,
+} = {}) {
+  const deadline = Date.now() + DB_DEADLINE_MS;
+
+  const fromItems = (gen) => {
+    const item = getQueueItem(gen.items, { id, priority });
+    const truncated = !item && gen.metadata?.blob_truncated
+      ? `Note: the fallback queue snapshot is a top slice (${gen.metadata.blob_truncated.kept} of ${gen.metadata.blob_truncated.total} items) — the item may exist deeper in the live queue.`
+      : null;
+    // Blob/queue.json items are coverage-filtered at generation time, so a hit
+    // there is an open item by construction.
+    return { item, covered: item ? false : null, truncatedNote: truncated };
+  };
+
+  if (source === 'blob') {
+    return fromItems(await ensureCache(fetchImpl, 'blob', deadline));
+  }
+
+  try {
+    const gen = await ensureCache(fetchImpl, source, deadline);
+    const rankMode = gen.metadata.rank_mode || 'map';
+    const query = id
+      ? `id=eq.${encodeURIComponent(id)}`
+      : `rank_mode=eq.${encodeURIComponent(rankMode)}&priority=eq.${Number(priority)}`;
+    const resp = await fetchImpl(
+      `${SUPABASE_URL}/rest/v1/queue_items?${query}&limit=1`,
+      { headers: dbHeaders(), signal: signalFor(deadline) },
+    );
+    if (!resp.ok) throw new Error(`queue_items lookup HTTP ${resp.status}`);
+    const rows = JSON.parse(await resp.text());
+    if (!Array.isArray(rows)) throw new Error('queue_items lookup did not return an array');
+    if (rows.length === 0) return { item: null, covered: null, truncatedNote: null };
+
+    const row = rows[0];
+    const item = projectRow(row);
+
+    // Coverage probe — the same NOT EXISTS queue_top applies (migration 059):
+    // a verified run_card for (corpus, model, condition) closes the item.
+    let covered = null;
+    try {
+      const probeQ = `dataset_id=eq.${encodeURIComponent(row.corpus_id)}`
+        + `&model_slug=eq.${encodeURIComponent(row.model)}`
+        + `&condition=eq.${encodeURIComponent(row.condition)}`
+        + '&trust=eq.verified&select=id&limit=1';
+      const probe = await fetchImpl(
+        `${SUPABASE_URL}/rest/v1/run_cards?${probeQ}`,
+        { headers: dbHeaders(), signal: signalFor(deadline) },
+      );
+      if (probe.ok) {
+        const hits = JSON.parse(await probe.text());
+        if (Array.isArray(hits)) covered = hits.length > 0;
+      }
+    } catch {
+      // covered stays null (unknown) — the item itself is still served
     }
-    if (page.length < QUEUE_TOP_PAGE) break;
+    return { item, covered, truncatedNote: null };
+  } catch (dbErr) {
+    return fromItems(await blobFallback(fetchImpl, dbErr, source));
+  }
+}
+
+/** Fall back to the blob after a DB-path failure, chaining both causes if the
+ *  blob is down too — the agent should see WHY both lanes failed, not just
+ *  the second one. Caches the blob generation so retries stay cheap. */
+async function blobFallback(fetchImpl, dbErr, source = QUEUE_SOURCE) {
+  try {
+    const data = await fetchQueueFromBlob(fetchImpl);
+    // Cached under the CALLER's source key so retries within the TTL reuse
+    // the blob instead of hammering a DB that just failed.
+    const gen = {
+      source, metadata: data.metadata, items: data.items,
+      complete: true, pages: 0,
+    };
+    _cache = gen;
+    _cacheTime = Date.now();
+    return gen;
+  } catch (blobErr) {
+    throw new Error(
+      `live queue unavailable (${dbErr.message}) and the static fallback also `
+      + `failed (${blobErr.message})`,
+    );
   }
+}
 
-  // open_items reflects the LIVE served count, not the last generation's stat.
-  return { metadata: { ...metadata, open_items: items.length }, items };
+/**
+ * Fetch the queue, returning the cached version if still fresh.
+ *
+ * LEGACY entry point: returns a `{ metadata, items }` queue object. On the
+ * blob path this is the whole blob, exactly as before. On the DB path it is
+ * now a BOUNDED ranked prefix (up to MAX_DB_PAGES pages), never the 0.1.0
+ * full drain — prefer fetchQueueMeta / selectFromQueue / lookupQueueItem,
+ * which fetch only what the caller's question needs.
+ *
+ * The static host can serve an HTML holding page with HTTP 200 (site gated,
+ * maintenance, CDN error page) — `resp.json()` would then surface a raw
+ * `SyntaxError: Unexpected token '<'` to every queue-backed tool. The body is
+ * therefore read as text and parsed at one choke point, so a non-JSON
+ * response becomes ONE clean, user-facing error. Failures are never cached —
+ * the next call re-fetches.
+ *
+ * @param {object} [opts]
+ * @param {typeof fetch} [opts.fetchImpl]  Injectable fetch (for tests).
+ * @returns {Promise<{ metadata: object, items: object[] }>}
+ */
+export async function fetchQueue({ fetchImpl = fetch, source = QUEUE_SOURCE } = {}) {
+  const deadline = Date.now() + DB_DEADLINE_MS;
+  let gen;
+  if (source === 'blob') {
+    gen = await ensureCache(fetchImpl, 'blob', deadline);
+  } else {
+    try {
+      gen = await ensureCache(fetchImpl, source, deadline);
+      await deepenUntil(fetchImpl, gen, deadline, () => false);
+    } catch (dbErr) {
+      gen = await blobFallback(fetchImpl, dbErr, source);
+    }
+  }
+  // One stable view per generation — callers within a TTL get the SAME object
+  // (metadata/items are the live cache references, so a deepened prefix shows
+  // through), preserving the original fetchQueue cache contract.
+  if (!gen.legacyView) gen.legacyView = { metadata: gen.metadata, items: gen.items };
+  return gen.legacyView;
 }
 
 /** The legacy path: the full static queue.json blob. Also the DB-path fallback. */