@bongos/core 1.19.550 → 1.19.551

package/scripts/gds/bug-triage.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+// /bug-triage — walk every open kind=bug task and verdict it one-at-a-time
+// (task 1001478). The idea-triage precedent for a queue with no gate: bugs now
+// land directly as kind=bug tasks with no triage step (task 1003071), so
+// near-duplicate reports accumulate with nothing to fold them together.
+//
+// Usage:
+//   node scripts/gds/bug-triage.js
+//
+// BATCH CLUSTER PASS, mirroring /idea-triage's (task 1001465): before the
+// one-at-a-time walk, near-duplicate open bug tasks are grouped (shared
+// `goal_id`, high title/description word overlap — `clusterRecords`, shared
+// with triage.js so the union-find/Jaccard core is written once) and offered
+// ONE verdict per group: keep a canonical task and merge the rest into it,
+// dismiss the whole group as won't-fix, walk them individually, or skip.
+// Partitioned by `goal_id` rather than `kind` (every row here is already
+// kind=bug, so that gate would be a no-op) — two bug reports in unrelated
+// goals describing similar-sounding symptoms are not the same triage
+// decision, the same reasoning idea-triage applies to its own `kind` gate.
+//
+// Prompts per bug task:
+//   [m]erge with #N  → POST /tasks/:id/merge {into_task_id:N} (N is the
+//                      canonical TASK to keep; this task's status becomes
+//                      'abandoned' with merged_into_task_id=N — no new
+//                      'merged' status, see db-ship.js mergeTask's header)
+//   [w]on't-fix      → POST /tasks/:id/abandon {reason} (not a bug / already
+//                      fixed / can't reproduce — the report itself is closed,
+//                      not folded into another task)
+//   [s]kip           → no write; the task surfaces again next triage
+//   [q]uit           → exit early, print partial summary
+//
+// Prompts per duplicate cluster (before the per-task walk):
+//   [k]eep #N        → merge every other member into #N (default: the
+//                      oldest); #N itself is NOT verdicted here — it still
+//                      gets the normal per-task walk below
+//   [d]iscard        → won't-fix every member in the cluster
+//   [i]ndividually   → ignore the cluster grouping; walk each member normally
+//   [s]kip           → no write; the whole cluster surfaces again next triage
+//
+// Exit codes:
+//   0  walked cleanly (incl. nothing open)
+//   1  api / network error
+//   2  no session
+
+const readline = require('node:readline');
+const { cliClient, requireSession, cliExit } = require('./cli-lib');
+const { clusterRecords } = require('./triage');
+
+function prompt(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+function trim(s, n) {
+  const str = String(s || '');
+  return str.length > n ? `${str.slice(0, n - 1)}…` : str;
+}
+
+// Statuses a bug can still be triaged FROM. 'shipped'/'abandoned' are terminal
+// (the latter includes already-merged rows, since merge reuses that status —
+// see db-ship.js mergeTask's header), so neither belongs in an "open" walk.
+const OPEN_STATUSES = new Set(['backlog', 'ready', 'active', 'blocked', 'completed', 'confirmed']);
+
+async function listOpenBugTasks() {
+  const api = await cliClient();
+  const r = await api.tasks.getTasks({ query: { kind: 'bug', limit: 1000 } });
+  if (!r.ok) throw new Error(`GET /tasks?kind=bug failed (${r.status}): ${JSON.stringify(r.data)}`);
+  // GET /tasks responds { tasks: [...] } (modules/lifecycle/routes/tasks.js),
+  // not a bare array — triage.js:163's `r.data?.ideas ?? []` is the same shape
+  // one route over. Grade finding: this was `(r.data || [])`, an object with
+  // no .filter, so every real run threw before listing a single bug.
+  return (r.data?.tasks ?? []).filter((t) => OPEN_STATUSES.has(t.status));
+}
+
+async function mergeTaskInto(id, intoTaskId, reason) {
+  const api = await cliClient();
+  const r = await api.tasks.postTasksIdMerge({ id, body: { into_task_id: Number(intoTaskId), reason: reason || '' } });
+  if (!r.ok) throw Object.assign(new Error(`merge failed (${r.status}): ${JSON.stringify(r.data)}`), { code: r.data?.error?.code || r.data?.error });
+  return r.data;
+}
+
+async function dismissTask(id, reason) {
+  const api = await cliClient();
+  const r = await api.tasks.postTasksIdAbandon({ id, body: { reason: reason || '' } });
+  if (!r.ok) throw Object.assign(new Error(`won't-fix failed (${r.status}): ${JSON.stringify(r.data)}`), { code: r.data?.error?.code || r.data?.error });
+  return r.data;
+}
+
+function printTask(task, idx, total) {
+  console.log(`\n[${idx + 1}/${total}] #${task.id}  [${task.status}]  ${task.title}`);
+  if (task.description) console.log(`  ${trim(task.description, 300)}`);
+  if (task.goal_id) console.log(`  goal ${task.goal_id}`);
+}
+
+function printCluster(cluster) {
+  const sep = '┄'.repeat(72);
+  console.log(`\n${sep}`);
+  console.log(`Cluster of ${cluster.length} likely-duplicate bug reports (oldest first — the suggested keeper):`);
+  for (const m of cluster) console.log(`  #${m.id}  [${m.status}]  ${trim(m.title, 80)}`);
+  console.log(sep);
+}
+
+// The interactive batch pass over one cluster. Mutates `state` (summary
+// counts) and returns nothing; `clusteredIds` is mutated in place so a choice
+// of "individually" or "keep #N" puts the affected task(s) back into the
+// normal per-task walk that runs after every cluster has been offered.
+// Mirrors triage.js's handleCluster exactly, task-shaped.
+async function handleCluster(rl, cluster, clusteredIds, state) {
+  printCluster(cluster);
+  let handled = false;
+  while (!handled) {
+    const ans = (await prompt(rl, `  [k]eep #${cluster[0].id} & merge the rest / [d]iscard all / [i]ndividually / [s]kip cluster > `)).trim().toLowerCase();
+
+    if (ans === 's' || ans === 'skip' || ans === '') { handled = true; break; }
+
+    if (ans === 'i' || ans === 'individually') {
+      for (const m of cluster) clusteredIds.delete(m.id);
+      console.log('  → walking this cluster\'s bugs individually');
+      handled = true; break;
+    }
+
+    if (ans === 'd' || ans === 'discard') {
+      const reason = (await prompt(rl, '  reason (optional, enter to skip): ')).trim();
+      for (const m of cluster) {
+        try {
+          await dismissTask(m.id, reason || 'won\'t-fix as part of a batch-verdicted duplicate cluster');
+          state.summary.dismissed++;
+          state.dismissedIds.push(m.id);
+        } catch (err) {
+          console.error(`  ! #${m.id}: ${err.message}`);
+        }
+      }
+      console.log(`  ✖ dismissed ${cluster.length} duplicate bug reports`);
+      handled = true; break;
+    }
+
+    if (ans === 'k' || ans === 'keep' || ans.startsWith('k ') || ans.startsWith('k#')) {
+      let canonicalId = cluster[0].id;
+      const inline = ans.replace(/^k(eep)?(\s|#)*/, '').trim();
+      if (inline) {
+        const n = Number(inline.replace(/^#/, ''));
+        if (Number.isFinite(n) && n > 0 && cluster.some((m) => String(m.id) === String(n))) canonicalId = n;
+        else if (Number.isFinite(n) && n > 0) console.log(`  ! #${n} isn't in this cluster; keeping #${canonicalId}`);
+      }
+      for (const m of cluster) {
+        if (String(m.id) === String(canonicalId)) continue;
+        try {
+          await mergeTaskInto(m.id, canonicalId, `duplicate cluster batch-merged into #${canonicalId}`);
+          state.summary.merged++;
+          state.mergedIds.push(m.id);
+        } catch (err) {
+          console.error(`  ! #${m.id}: ${err.message}`);
+          // A failed merge must not silently vanish the bug for this session:
+          // without this, the member stays in clusteredIds and the later
+          // `tasks.filter((t) => !clusteredIds.has(t.id))` drops it from BOTH
+          // the batch verdict (it never merged) and the individual walk —
+          // one stderr line and the report is skipped entirely.
+          clusteredIds.delete(m.id);
+        }
+      }
+      // The keeper is untouched by the batch verdict — it still needs its own
+      // won't-fix/merge/skip decision, so it goes back into the normal walk.
+      clusteredIds.delete(canonicalId);
+      console.log(`  ⇢ merged ${cluster.length - 1} duplicate(s) into #${canonicalId} — #${canonicalId} still needs its own verdict below`);
+      handled = true; break;
+    }
+
+    console.log('  ? unknown — type k, d, i, or s');
+  }
+}
+
+async function main() {
+  await requireSession();
+
+  let tasks;
+  try {
+    tasks = await listOpenBugTasks();
+  } catch (err) {
+    console.error(err.message);
+    cliExit(1);
+    return;
+  }
+
+  if (tasks.length === 0) {
+    console.log('bug queue empty — nothing to triage.');
+    cliExit(0);
+    return;
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const summary = { merged: 0, dismissed: 0, skipped: 0 };
+  const mergedIds = [];
+  const dismissedIds = [];
+  let quit = false;
+
+  // BATCH CLUSTER PASS — partitioned by goal_id, not kind (every row here is
+  // already kind=bug, so a kind gate would be a no-op; see module header).
+  const { clusters, clusteredIds } = clusterRecords(tasks, {
+    textOf: (t) => `${t.title || ''} ${t.description || ''}`,
+    kindOf: (t) => t.goal_id || null,
+    timeOf: (t) => new Date(t.created_at),
+  });
+  if (clusters.length > 0) {
+    console.log(`\n🔗 ${clusters.length} likely-duplicate cluster${clusters.length === 1 ? '' : 's'} found (${clusteredIds.size} bug reports) — batch verdict available before the individual walk.`);
+    const state = { summary, mergedIds, dismissedIds };
+    for (const cluster of clusters) {
+      await handleCluster(rl, cluster, clusteredIds, state);
+    }
+  }
+  tasks = tasks.filter((t) => !clusteredIds.has(t.id));
+  if (tasks.length === 0) {
+    console.log('\nnothing left to walk individually — every open bug report was resolved in a batch cluster verdict.');
+    rl.close();
+    printSummary(summary, mergedIds, dismissedIds);
+    cliExit(0);
+    return;
+  }
+
+  console.log(`\n🐛 ${tasks.length} open bug report${tasks.length === 1 ? '' : 's'} to triage individually.`);
+
+  let walked = 0;
+  for (let i = 0; i < tasks.length && !quit; i++) {
+    const task = tasks[i];
+    printTask(task, i, tasks.length);
+
+    let handled = false;
+    while (!handled) {
+      const ans = (await prompt(rl, '[m]erge / [w]on\'t-fix / [s]kip / [q]uit > ')).trim().toLowerCase();
+
+      if (ans === 'q' || ans === 'quit') { quit = true; handled = true; break; }
+
+      if (ans === 's' || ans === 'skip' || ans === '') {
+        summary.skipped++;
+        handled = true; break;
+      }
+
+      if (ans === 'w' || ans === 'wontfix' || ans === "won't-fix" || ans === 'dismiss') {
+        const reason = (await prompt(rl, '  reason (not a bug / already fixed / cannot reproduce): ')).trim();
+        try {
+          await dismissTask(task.id, reason);
+          summary.dismissed++;
+          dismissedIds.push(task.id);
+          console.log(`  ✖ dismissed #${task.id}`);
+        } catch (err) {
+          console.error(`  ! ${err.message}`);
+          continue;
+        }
+        handled = true; break;
+      }
+
+      if (ans === 'm' || ans === 'merge' || ans.startsWith('m ') || ans.startsWith('m#')) {
+        const inline = ans.replace(/^m(erge)?(\s|#)*/, '').trim();
+        const target = inline || (await prompt(rl, '  merge into which task id? #')).trim().replace(/^#/, '');
+        const n = Number(target);
+        if (!Number.isFinite(n) || n <= 0) { console.log('  ? not a valid task id'); continue; }
+        try {
+          await mergeTaskInto(task.id, n, '');
+          summary.merged++;
+          mergedIds.push(task.id);
+          console.log(`  ⇢ merged #${task.id} into #${n}`);
+        } catch (err) {
+          console.error(`  ! ${err.message}`);
+          continue;
+        }
+        handled = true; break;
+      }
+
+      console.log('  ? unknown — type m, w, s, or q');
+    }
+    if (handled && !quit) walked++;
+  }
+
+  rl.close();
+  printSummary(summary, mergedIds, dismissedIds, tasks.length - walked);
+  cliExit(0);
+}
+
+function printSummary(summary, mergedIds, dismissedIds, unseen = 0) {
+  console.log('\n── bug triage summary ──');
+  console.log(`  merged:    ${summary.merged}${mergedIds.length ? ` (${mergedIds.map((i) => `#${i}`).join(', ')})` : ''}`);
+  console.log(`  dismissed: ${summary.dismissed}${dismissedIds.length ? ` (${dismissedIds.map((i) => `#${i}`).join(', ')})` : ''}`);
+  console.log(`  skipped:   ${summary.skipped}`);
+  if (unseen > 0) console.log(`  ${unseen} unseen (quit early) — will surface again next triage`);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('fatal:', err);
+    cliExit(1);
+  });
+}
+
+module.exports = { listOpenBugTasks, mergeTaskInto, dismissTask, OPEN_STATUSES };

package/scripts/gds/triage.js

@@ -313,31 +313,35 @@ function jaccard(a, b) {
   return shared / (a.size + b.size - shared);
 }
 
-// Group likely-duplicate OPEN ideas so the walk can offer one batch verdict
-// per group instead of re-litigating each member individually. Heuristic, not
-// semantic: two ideas cluster only when they share the same `kind` (a bug and
-// a feature asking the same underlying question are not the same triage
-// decision) AND their title+body word sets clear both a minimum SHARED-word
-// floor and a Jaccard similarity threshold — the floor stops two long,
-// unrelated ideas from clustering on a borderline ratio built from a single
-// coincidental word. Full Ideas are never eligible: they get their own shape
-// recommendation (SKILL.md Step 2.5), and batching one away would skip that
-// judgment. Pure (no I/O, no randomness, no idea mutated) — directly
-// unit-testable; the interactive merge/discard/skip choice lives in main().
-// Returns { clusters, clusteredIds }: clusters is an array of idea-arrays
-// (each length >= 2, oldest member first — the natural "keep this one"
-// default), clusteredIds is a Set of every idea id inside some cluster.
-function clusterIdeas(ideas, { threshold = 0.34, minShared = 2 } = {}) {
-  const eligible = ideas.filter((i) => (i.grade || 'quick') !== 'full');
-  const words = eligible.map((i) => significantWords(`${i.title || ''} ${i.body_md || ''}`));
-  const n = eligible.length;
+// Group likely-duplicate records so a walk can offer one batch verdict per
+// group instead of re-litigating each member individually. Heuristic, not
+// semantic: two records cluster only when `kindOf` agrees (a bug and a
+// feature asking the same underlying question are not the same triage
+// decision) AND `textOf`'s word sets clear both a minimum SHARED-word floor
+// and a Jaccard similarity threshold — the floor stops two long, unrelated
+// records from clustering on a borderline ratio built from a single
+// coincidental word. Pure (no I/O, no randomness, nothing mutated) — directly
+// unit-testable; the interactive merge/discard/skip choice lives in each
+// caller's own walk. Returns { clusters, clusteredIds }: clusters is an array
+// of record-arrays (each length >= 2, sorted oldest-`timeOf`-first — the
+// natural "keep this one" default), clusteredIds is a Set of every id (by
+// `.id`) inside some cluster.
+//
+// Extracted from the idea-only `clusterIdeas` below (task 1001478) so
+// /bug-triage's kind=bug tasks can reuse the same union-find/Jaccard core
+// against `description`/`created_at` instead of `body_md`/`captured_at` —
+// duplicating the algorithm would be the one thing worth avoiding twice.
+function clusterRecords(records, { textOf, kindOf, timeOf, threshold = 0.34, minShared = 2 }) {
+  const words = records.map((r) => significantWords(textOf(r)));
+  const kinds = records.map((r) => kindOf(r));
+  const n = records.length;
   const parent = Array.from({ length: n }, (_, i) => i);
   function find(x) { while (parent[x] !== x) { parent[x] = parent[parent[x]]; x = parent[x]; } return x; }
   function union(a, b) { const ra = find(a); const rb = find(b); if (ra !== rb) parent[ra] = rb; }
 
   for (let i = 0; i < n; i++) {
     for (let j = i + 1; j < n; j++) {
-      if ((eligible[i].kind || null) !== (eligible[j].kind || null)) continue;
+      if (kinds[i] !== kinds[j]) continue;
       let shared = 0;
       for (const w of words[i]) if (words[j].has(w)) shared++;
       if (shared < minShared) continue;
@@ -349,19 +353,33 @@ function clusterIdeas(ideas, { threshold = 0.34, minShared = 2 } = {}) {
   for (let i = 0; i < n; i++) {
     const root = find(i);
     if (!groups.has(root)) groups.set(root, []);
-    groups.get(root).push(eligible[i]);
+    groups.get(root).push(records[i]);
   }
   const clusters = [];
   const clusteredIds = new Set();
   for (const members of groups.values()) {
     if (members.length < 2) continue;
-    members.sort((a, b) => new Date(a.captured_at) - new Date(b.captured_at));
+    members.sort((a, b) => timeOf(a) - timeOf(b));
     clusters.push(members);
     for (const m of members) clusteredIds.add(m.id);
   }
   return { clusters, clusteredIds };
 }
 
+// The idea-shaped call: Full Ideas are never eligible (they get their own
+// shape recommendation, SKILL.md Step 2.5, and batching one away would skip
+// that judgment), clustered on title+body_md / kind / captured_at. Same
+// signature and behavior as before the clusterRecords extraction.
+function clusterIdeas(ideas, { threshold = 0.34, minShared = 2 } = {}) {
+  const eligible = ideas.filter((i) => (i.grade || 'quick') !== 'full');
+  return clusterRecords(eligible, {
+    textOf: (i) => `${i.title || ''} ${i.body_md || ''}`,
+    kindOf: (i) => i.kind || null,
+    timeOf: (i) => new Date(i.captured_at),
+    threshold, minShared,
+  });
+}
+
 function printCluster(cluster) {
   const sep = '┄'.repeat(72);
   console.log(`\n${sep}`);
@@ -671,6 +689,7 @@ module.exports = {
   loadDevelopment,
   formatDevelopment,
   clusterIdeas,
+  clusterRecords,
   significantWords,
   jaccard,
 };

package/src/module-api.js

@@ -49,7 +49,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.550'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.551'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/abandon_task.mjs

@@ -151,6 +151,9 @@ await test('restore: an abandoned task flips to backlog, COMMITs, reports previo
 });
 
 await test("restore: clears only an 'Abandoned: …' value_summary, leaving any other note", async () => {
+  // mergeTask (task 1001478) preserves value_summary rather than synthesizing
+  // a "Merged into #N" default, so there is no merge-specific stamp for
+  // restore to clean up here beyond the abandon one.
   const pool = fakePool({ status: 'abandoned', updatedStatus: 'backlog' });
   await restoreTask({ taskId: TASK }, { pool });
   const upd = find(pool._client.queries, /^UPDATE tasks/);
@@ -161,6 +164,20 @@ await test("restore: clears only an 'Abandoned: …' value_summary, leaving any
   assert.equal(upd.params.length, 1, 'only the task id is bound');
 });
 
+await test('restore: clears merged_into_task_id + triage_note (task 1001478 grade finding)', async () => {
+  // Without this, restoring a MERGED task (status flips 'abandoned'→'backlog'
+  // while merged_into_task_id stays set) violates core_232's CHECK
+  // (merged_into_task_id IS NULL OR status='abandoned') — the exact 23514
+  // mergeTask's own header prescribes this route to fix ("retarget by
+  // restoring first").
+  const pool = fakePool({ status: 'abandoned', updatedStatus: 'backlog' });
+  await restoreTask({ taskId: TASK }, { pool });
+  const upd = find(pool._client.queries, /^UPDATE tasks/);
+  const sql = String(upd.sql).replace(/\s+/g, ' ');
+  assert.match(sql, /merged_into_task_id = NULL/, 'must clear the merge target so the CHECK stays satisfied');
+  assert.match(sql, /triage_note = NULL/, 'must clear the triage note left by the merge it undoes');
+});
+
 await test('restore: a task that is not abandoned is refused and rolls back', async () => {
   for (const status of ['ready', 'backlog', 'shipped']) {
     const pool = fakePool({ status });

package/tests/bug_triage.mjs

@@ -0,0 +1,205 @@
+// tests/bug_triage.mjs
+//
+// Regression guard for task 1001478 — /bug-triage's task-shaped reuse of
+// triage.js's generalized clusterRecords (extracted from the idea-only
+// clusterIdeas so the union-find/Jaccard core is written once), the
+// OPEN_STATUSES set that decides which kind=bug tasks a triage walk sees, and
+// the three HTTP-facing functions (listOpenBugTasks/mergeTaskInto/
+// dismissTask) a grading round caught completely untested — which is exactly
+// how a real envelope-shape bug (GET /tasks responds `{ tasks: [...] }`, not
+// a bare array; `(r.data || []).filter` threw on every run) shipped green.
+//
+// cliClient() is mocked by mutating cli-lib.js's exports BEFORE requiring
+// bug-triage.js (same trick as tests/idea_triage.mjs patching
+// `api.pool.query` before requiring inbox.js): bug-triage.js destructures
+// `{ cliClient }` at require time, so the patched function is what it binds.
+//
+// Run:  node tests/bug_triage.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+
+// A fake api client whose `tasks.*` methods answer from a per-test script of
+// { ok, data, status } responses, and record every call for assertion.
+const calls = [];
+let responses = {};
+const cliLib = require('../scripts/gds/cli-lib.js');
+cliLib.cliClient = async () => ({
+  tasks: {
+    getTasks: async (args) => { calls.push({ method: 'getTasks', args }); return responses.getTasks; },
+    postTasksIdMerge: async (args) => { calls.push({ method: 'postTasksIdMerge', args }); return responses.merge; },
+    postTasksIdAbandon: async (args) => { calls.push({ method: 'postTasksIdAbandon', args }); return responses.abandon; },
+  },
+});
+
+const { clusterRecords } = require('../scripts/gds/triage.js');
+const { listOpenBugTasks, mergeTaskInto, dismissTask, OPEN_STATUSES } = require('../scripts/gds/bug-triage.js');
+
+const { test, summary } = makeRunner();
+
+const mkBug = (id, title, { goalId = 1000001, description = '', createdAt = '2026-01-01T00:00:00Z' } = {}) =>
+  ({ id, title, description, goal_id: goalId, created_at: createdAt });
+
+const bugCluster = (records, opts = {}) => clusterRecords(records, {
+  textOf: (t) => `${t.title || ''} ${t.description || ''}`,
+  kindOf: (t) => t.goal_id || null,
+  timeOf: (t) => new Date(t.created_at),
+  ...opts,
+});
+
+// ---------- OPEN_STATUSES ----------
+
+await test('OPEN_STATUSES: excludes shipped and abandoned (merged tasks reuse abandoned)', () => {
+  assert.ok(!OPEN_STATUSES.has('shipped'));
+  assert.ok(!OPEN_STATUSES.has('abandoned'));
+});
+
+await test('OPEN_STATUSES: includes every live status a bug can sit in', () => {
+  for (const s of ['backlog', 'ready', 'active', 'blocked', 'completed', 'confirmed']) {
+    assert.ok(OPEN_STATUSES.has(s), `${s} should be an open bug status`);
+  }
+});
+
+// ---------- clusterRecords, task-shaped ----------
+
+await test('clusterRecords: near-duplicate bug reports in the SAME goal cluster together', () => {
+  const bugs = [
+    mkBug(1, 'Login button does nothing on Safari', { createdAt: '2026-01-03T00:00:00Z' }),
+    mkBug(2, 'Safari: login button unresponsive', { createdAt: '2026-01-01T00:00:00Z' }),
+    mkBug(3, 'The login button is broken in Safari', { createdAt: '2026-01-02T00:00:00Z' }),
+  ];
+  const { clusters, clusteredIds } = bugCluster(bugs);
+  assert.equal(clusters.length, 1, 'expected exactly one cluster');
+  assert.equal(clusters[0].length, 3);
+  assert.deepEqual(clusteredIds, new Set([1, 2, 3]));
+  assert.equal(clusters[0][0].id, 2, 'oldest first — the suggested keeper');
+});
+
+await test('clusterRecords: unrelated bug reports never cluster', () => {
+  const bugs = [
+    mkBug(1, 'Login button does nothing on Safari'),
+    mkBug(2, 'Export to CSV drops the last row'),
+    mkBug(3, 'Dark mode flickers on page load'),
+  ];
+  const { clusters, clusteredIds } = bugCluster(bugs);
+  assert.equal(clusters.length, 0);
+  assert.equal(clusteredIds.size, 0);
+});
+
+await test('clusterRecords: same-symptom bugs in DIFFERENT goals do not cluster', () => {
+  const bugs = [
+    mkBug(1, 'Login button does nothing on Safari', { goalId: 1000001 }),
+    mkBug(2, 'Login button does nothing on Safari', { goalId: 1000002 }),
+  ];
+  const { clusters, clusteredIds } = bugCluster(bugs);
+  assert.equal(clusters.length, 0, 'two goals reporting the same symptom are not one triage decision');
+  assert.equal(clusteredIds.size, 0);
+});
+
+await test('clusterRecords: a single overlapping word alone is not enough (minShared floor)', () => {
+  const bugs = [
+    mkBug(1, 'Improve the deploy pipeline reliability with retries'),
+    mkBug(2, 'Improve onboarding copy for new builders'),
+  ];
+  const { clusters } = bugCluster(bugs);
+  assert.equal(clusters.length, 0, 'sharing only "improve" must not cluster two unrelated reports');
+});
+
+await test('clusterRecords: no goal_id (null) still partitions consistently', () => {
+  const bugs = [
+    mkBug(1, 'Login button does nothing on Safari', { goalId: null }),
+    mkBug(2, 'Safari login button is unresponsive', { goalId: null }),
+  ];
+  const { clusters } = bugCluster(bugs);
+  assert.equal(clusters.length, 1, 'two homeless bug reports (goal_id null) can still cluster against each other');
+});
+
+await test('clusterRecords: empty input → no clusters', () => {
+  const { clusters, clusteredIds } = bugCluster([]);
+  assert.equal(clusters.length, 0);
+  assert.equal(clusteredIds.size, 0);
+});
+
+// ---------- listOpenBugTasks (the envelope-shape blocker) ----------
+
+await test('listOpenBugTasks: reads the { tasks: [...] } envelope, not a bare array', async () => {
+  responses.getTasks = { ok: true, data: { tasks: [mkBug(1, 'x', {}), { ...mkBug(2, 'y'), status: 'ready' }] } };
+  responses.getTasks.data.tasks[0].status = 'ready';
+  const out = await listOpenBugTasks();
+  assert.equal(out.length, 2, '(r.data || []).filter would have thrown TypeError here — r.data is an object, not an array');
+});
+
+await test('listOpenBugTasks: filters out shipped/abandoned, keeps every open status', async () => {
+  responses.getTasks = {
+    ok: true,
+    data: { tasks: [
+      { ...mkBug(1, 'a'), status: 'ready' },
+      { ...mkBug(2, 'b'), status: 'shipped' },
+      { ...mkBug(3, 'c'), status: 'abandoned' },
+      { ...mkBug(4, 'd'), status: 'confirmed' },
+    ] },
+  };
+  const out = await listOpenBugTasks();
+  assert.deepEqual(out.map((t) => t.id), [1, 4]);
+});
+
+await test('listOpenBugTasks: queries kind=bug with a bounded limit', async () => {
+  calls.length = 0;
+  responses.getTasks = { ok: true, data: { tasks: [] } };
+  await listOpenBugTasks();
+  assert.equal(calls[0].method, 'getTasks');
+  assert.deepEqual(calls[0].args.query, { kind: 'bug', limit: 1000 });
+});
+
+await test('listOpenBugTasks: a non-ok response throws with the status + body', async () => {
+  responses.getTasks = { ok: false, status: 500, data: { error: 'boom' } };
+  await assert.rejects(() => listOpenBugTasks(), /500/);
+});
+
+// ---------- mergeTaskInto ----------
+
+await test('mergeTaskInto: posts into_task_id + reason to the merge route', async () => {
+  calls.length = 0;
+  responses.merge = { ok: true, data: { ok: true, taskId: 5, taskStatus: 'abandoned', mergedIntoTaskId: 9 } };
+  const out = await mergeTaskInto(5, 9, 'same report');
+  assert.equal(calls[0].method, 'postTasksIdMerge');
+  assert.deepEqual(calls[0].args, { id: 5, body: { into_task_id: 9, reason: 'same report' } });
+  assert.equal(out.mergedIntoTaskId, 9);
+});
+
+await test('mergeTaskInto: intoTaskId is coerced to a Number even if passed as a string', async () => {
+  calls.length = 0;
+  responses.merge = { ok: true, data: {} };
+  await mergeTaskInto(5, '9', '');
+  assert.equal(calls[0].args.body.into_task_id, 9);
+  assert.equal(typeof calls[0].args.body.into_task_id, 'number');
+});
+
+await test('mergeTaskInto: a refused merge throws with the server error code attached', async () => {
+  responses.merge = { ok: false, status: 409, data: { error: { code: 'MERGE_TARGET_MERGED' } } };
+  const err = await mergeTaskInto(5, 9, '').catch((e) => e);
+  assert.ok(err instanceof Error);
+  assert.equal(err.code, 'MERGE_TARGET_MERGED');
+});
+
+// ---------- dismissTask ----------
+
+await test('dismissTask: posts a reason to the abandon route', async () => {
+  calls.length = 0;
+  responses.abandon = { ok: true, data: { ok: true, taskId: 5, taskStatus: 'abandoned' } };
+  await dismissTask(5, 'cannot reproduce');
+  assert.equal(calls[0].method, 'postTasksIdAbandon');
+  assert.deepEqual(calls[0].args, { id: 5, body: { reason: 'cannot reproduce' } });
+});
+
+await test('dismissTask: a refused won\'t-fix throws with the server error code attached', async () => {
+  responses.abandon = { ok: false, status: 409, data: { error: { code: 'TASK_HAS_ACTIVE_CLAIM' } } };
+  const err = await dismissTask(5, '').catch((e) => e);
+  assert.equal(err.code, 'TASK_HAS_ACTIVE_CLAIM');
+});
+
+// -------------------------------------------------------------------------
+summary();