@bongos/core 1.19.1043 → 1.19.1045

package/modules/hall-ui/public/work.js

@@ -36,6 +36,10 @@
   // file's exact variants (date-only fmtDate; a 2200ms clearing toast).
   // fmtAgo / toAuth / getJSON / postJSON stay local below.
   const { escapeHtml, $, fmtNum, errCode, errDetails } = window.OTB; // task 1002462: envelope readers
+  // The hall's ONE claim/release refusal copy (task 1003458). This board's own
+  // copy is gone: a second surface that wants a claim button consumes this
+  // instead of lifting the switch, which is how the two drifted apart before.
+  const { friendlyClaimError, makeClaimAction } = window.OTBClaimAction;
   // Shared task-domain helpers (task 1002463). These lived in two copies here and
   // in the other board and had already drifted — goals-page.js had silently lost
   // friendlyBatchReason's MODULE_CONFLICT case. Destructured so every call site
@@ -180,6 +184,18 @@
     return data;
   }
 
+  // The hall's ONE claim/release action (task 1003458). Everything this board
+  // used to hand-roll four times — the POST, the refusal sentence, the
+  // stale-view refresh, the all-or-nothing batch report — lives in
+  // claim-action.js now; doClaim/doRelease/doBulkClaim/doBulkRelease below keep
+  // only what is genuinely this page: button text, the re-entrancy guard, the
+  // confirm() wording and the selection. friendlyBatchReason is injected rather
+  // than imported there, so claim-action.js stays dependency-free.
+  // refreshLive is a hoisted declaration; toast and API are already bound above.
+  const claimAction = makeClaimAction({
+    postJSON, toast, API, refresh: refreshLive, describeBatchReason: friendlyBatchReason,
+  });
+
   // ---- paginated lists (task 1931/1955 → kit, task 2170) --------------------
   // All four Work-page lists paginate through the shared OTBKit pager (the
   // canonical copy of the helper that used to live here). localStorage keys are
@@ -627,51 +643,6 @@
       }
     }
   }
-
-  // ---- claim / release actions ---------------------------------------------
-
-  // Map the server's typed error code to a builder-readable line. The codes are
-  // exactly those POST /claims and POST /claims/:id/resolve can return.
-  function friendlyActionError(status, data) {
-    // task 1002462: read the ADR 0116 envelope. `data.error` is an OBJECT, so the
-    // old `const code = data && data.error` compared a string to an object and
-    // EVERY case below fell through to the generic default — a wrong-but-plausible
-    // toast on every claim/release refusal.
-    const det = errDetails(data);
-    switch (errCode(data)) {
-      case 'ALREADY_CLAIMED':
-        return 'Someone else claimed that task first. The board will refresh.';
-      case 'TASK_NOT_READY':
-        return 'That task is no longer ready to be claimed.';
-      case 'TOUCHES_CONFLICT': {
-        const titles = Array.isArray(det.conflicts) ? det.conflicts.map((c) => c.title).filter(Boolean) : [];
-        return titles.length
-          ? `That task overlaps an active claim: ${titles.join('; ')}. Wait for it to ship.`
-          : 'That task overlaps another active claim. Wait for it to ship.';
-      }
-      case 'DEPS_NOT_SHIPPED':
-        return 'That task waits on unshipped dependencies. Pick another for now.';
-      case 'rank_too_low_for_task':
-      case 'XENOS_RESTRICTED':
-      case 'INSUFFICIENT_RANK':
-        return 'Your rank is not yet high enough for that task.';
-      case 'newcomer_must_ship_first':
-        return det.what_to_do || 'Ship your current claim before opening another.';
-      case 'NOT_YOUR_CLAIM':
-        return 'That claim is not yours to release.';
-      case 'ALREADY_RESOLVED':
-        return 'That claim was already resolved. The board will refresh.';
-      case 'BUILDER_INACTIVE':
-        return 'Your account is inactive. Contact an Archon.';
-      default:
-        return `The board could not complete that (${status}). Try again.`;
-    }
-  }
-
-  // Maps a single batch-item failure reason (POST /claims/batch,
-  // /claims/batch/validate) to a builder-readable fragment. Distinct from
-  // friendlyActionError above because a batch item's shape differs (reason,
-  // not error; extra fields like conflictsWithTaskId/module_key).
   async function copyText(text) {
     try { await navigator.clipboard.writeText(text); return true; }
     catch (_) {
@@ -735,18 +706,15 @@
   async function scheduleValidate(key, ids) {
     if (validateDebounce) clearTimeout(validateDebounce);
     validateDebounce = setTimeout(async () => {
-      try {
-        const result = await postJSON(`${API}/claims/batch/validate`, { task_ids: ids });
-        validateCache.key = key;
-        validateCache.parallelSafe = !!result.parallel_safe;
-        validateCache.byId = new Map((result.results || []).map((r) => [String(r.task_id), r]));
-      } catch (_) {
-        // Best-effort — leave Parallel disabled-with-a-generic-title on failure
-        // rather than risk copying a prompt for tasks we couldn't verify.
-        validateCache.key = key;
-        validateCache.parallelSafe = false;
-        validateCache.byId = new Map();
-      }
+      // The dry run lives in claim-action.js with the rest of the claim path; it
+      // is best-effort there, so a failure lands as parallelSafe:false with an
+      // empty map rather than a throw — Parallel stays disabled with a generic
+      // title instead of copying a prompt for tasks nobody verified. The
+      // debounce, the cache key and the re-render stay here: page furniture.
+      const out = await claimAction.validateMany(ids);
+      validateCache.key = key;
+      validateCache.parallelSafe = out.parallelSafe;
+      validateCache.byId = out.byId;
       renderBulkToolbar();
     }, 350);
   }
@@ -911,33 +879,8 @@
     const btn = $('#bulk-claim-btn');
     if (btn) { btn.disabled = true; btn.textContent = 'Claiming…'; }
     try {
-      if (ids.length === 1) {
-        await postJSON(`${API}/claims`, { task_id: ids[0], bind_session: false });
-        toast(`You claimed #${ids[0]}. Open a terminal to start work.`);
-      } else {
-        await postJSON(`${API}/claims/batch`, { task_ids: ids, bind_session: false });
-        toast(`Claimed ${ids.length} tasks. Open a terminal to start work.`);
-      }
-      selection.claim.clear();
-      await refreshLive();
-    } catch (err) {
-      if (err && err.message === 'redirecting to auth') return;
-      // task 1002462: same envelope defect — this tested `err.data.error === 'batch_failed'`
-      // against an object, so an all-or-nothing batch refusal rendered as the generic toast
-      // and the per-task reasons were dropped on the floor.
-      if (err.status === 409 && errCode(err.data) === 'batch_failed') {
-        // One read covers both envelopes — errDetails falls back to the body (task 1003657).
-        const bdet = errDetails(err.data);
-        const failures = Array.isArray(bdet.failures) ? bdet.failures : [];
-        const lines = failures.map((f) => `#${f.task_id} (${friendlyBatchReason(f)})`);
-        toast(lines.length
-          ? `The batch could not be claimed — ${lines.join('; ')}.`
-          : 'The batch could not be claimed. It was left untouched (all-or-nothing).');
-        await refreshLive().catch(() => {});
-      } else {
-        toast(friendlyActionError(err.status, err.data));
-        if (err.status === 409) await refreshLive().catch(() => {});
-      }
+      const out = await claimAction.claimMany(ids);
+      if (out.ok) selection.claim.clear();
     } finally {
       renderBulkToolbar();
     }
@@ -952,22 +895,8 @@
     const btn = $('#bulk-release-btn');
     if (btn) { btn.disabled = true; btn.textContent = 'Releasing…'; }
     try {
-      if (entries.length === 1) {
-        await postJSON(`${API}/claims/${encodeURIComponent(entries[0][0])}/resolve`, { outcome: 'abandoned' });
-        toast(`Released #${entries[0][1]}. It returns to the queue.`);
-      } else {
-        const result = await postJSON(`${API}/claims/batch/release`, { claim_ids: entries.map(([cid]) => Number(cid)) });
-        const released = Array.isArray(result.released) ? result.released.length : 0;
-        const failed = Array.isArray(result.failures) ? result.failures.length : 0;
-        toast(failed
-          ? `Released ${released} of ${entries.length} — ${failed} could not be released.`
-          : `Released ${released} tasks. They return to the queue.`);
-      }
-      selection.release.clear();
-      await refreshLive();
-    } catch (err) {
-      if (err && err.message === 'redirecting to auth') return;
-      toast(friendlyActionError(err.status, err.data));
+      const out = await claimAction.releaseMany(entries);
+      if (out.ok) selection.release.clear();
     } finally {
       renderBulkToolbar();
     }
@@ -979,18 +908,10 @@
     pending.add(key);
     if (btn) { btn.disabled = true; btn.textContent = 'Claiming…'; }
     try {
-      // bind_session:false — a web claim has no working session, so leave it
-      // unbound (see claims.js resolveCreatorSessionId) and the builder can ship
-      // it later from any of their own terminals.
-      await postJSON(`${API}/claims`, { task_id: Number(taskId), bind_session: false });
-      toast(`You claimed #${taskId}. Open a terminal to start work.`);
-      await refreshLive();
-    } catch (err) {
-      if (err && err.message === 'redirecting to auth') return;
-      toast(friendlyActionError(err.status, err.data));
-      // A conflict/already-claimed means our view is stale — pull fresh truth.
-      if (err.status === 409) await refreshLive().catch(() => {});
-      if (btn) { btn.disabled = false; btn.textContent = 'Claim'; }
+      const out = await claimAction.claim(taskId);
+      // Leave the button disabled while the page is navigating to sign-in —
+      // re-enabling it invites a click that cannot land.
+      if (!out.ok && !out.redirected && btn) { btn.disabled = false; btn.textContent = 'Claim'; }
     } finally {
       pending.delete(key);
     }
@@ -1003,17 +924,8 @@
     pending.add(key);
     if (btn) { btn.disabled = true; btn.textContent = 'Releasing…'; }
     try {
-      // No DELETE /claims/:id exists — release is resolve(outcome=abandoned),
-      // the same path /builder-release uses. Scoped to the caller's own claim
-      // server-side (NOT_YOUR_CLAIM).
-      await postJSON(`${API}/claims/${encodeURIComponent(claimId)}/resolve`, { outcome: 'abandoned' });
-      toast(`Released #${taskId}. It returns to the queue.`);
-      await refreshLive();
-    } catch (err) {
-      if (err && err.message === 'redirecting to auth') return;
-      toast(friendlyActionError(err.status, err.data));
-      if (err.status === 409) await refreshLive().catch(() => {});
-      if (btn) { btn.disabled = false; btn.textContent = 'Release'; }
+      const out = await claimAction.release(claimId, taskId);
+      if (!out.ok && !out.redirected && btn) { btn.disabled = false; btn.textContent = 'Release'; }
     } finally {
       pending.delete(key);
     }

package/modules/ideas/blockers.js

@@ -147,6 +147,65 @@ async function linkBlockerToTask({ blockerId, taskId }) {
   }
 }
 
+// Unlink a blocker from a task — the missing inverse of linkBlockerToTask
+// (task 1003518). Linking is one-way and Metic+, so before this a wrong link
+// (wrong task id, a duplicate filed by two people, a blocker later understood
+// to be irrelevant) could only be undone by a direct DELETE on task_blockers.
+//
+// LIKE resolveBlocker, THIS ONLY OBSERVES. The release lives in a DB trigger
+// (core_256), for the reason tests/blocker_resolve_guard.mjs states about the
+// resolve path: a promotion written here would be a second copy of core_223's
+// predicate, free to drift from it. One DELETE, then a read-back of what the
+// trigger did — the same shape resolveBlocker uses for `promoted_tasks`.
+//
+// The three statements share a transaction so `released` cannot be a lie told
+// by a concurrent writer between the delete and the read-back.
+//
+// `poolOverride` is injected by tests only, and is named so it cannot shadow the
+// module-level `pool` this file closes over.
+async function unlinkBlockerFromTask({ blockerId, taskId }, { pool: poolOverride = pool } = {}) {
+  const client = await poolOverride.connect();
+  try {
+    await client.query('BEGIN');
+    // Status BEFORE, so `released` means "this unlink moved it", not merely
+    // "it is ready now" — a task linked while it was never blockable would
+    // otherwise report a release that never happened (the task-1002559 lesson:
+    // a write that reports success without saying what changed hides a dead
+    // loop). FOR UPDATE so the row cannot move under the read-back below.
+    const { rows: before } = await client.query(
+      `SELECT status FROM tasks WHERE id = $1 FOR UPDATE`,
+      [taskId]
+    );
+    const { rows: removed } = await client.query(
+      `DELETE FROM task_blockers
+        WHERE task_id = $1 AND blocker_id = $2
+        RETURNING task_id`,
+      [taskId, blockerId]
+    );
+    // Answer honestly when nothing was there: a missing link is a refusal, not
+    // a silent success a caller would read as "detached".
+    if (removed.length === 0) {
+      await client.query('ROLLBACK');
+      const e = new Error('no such blocker link on that task');
+      e.code = 'LINK_NOT_FOUND';
+      throw e;
+    }
+    const { rows: after } = await client.query(
+      `SELECT status FROM tasks WHERE id = $1`,
+      [taskId]
+    );
+    await client.query('COMMIT');
+    const was = before[0] && before[0].status;
+    const now = after[0] && after[0].status;
+    return { unlinked: true, released: was === 'blocked' && now === 'ready' };
+  } catch (err) {
+    if (err.code !== 'LINK_NOT_FOUND') await client.query('ROLLBACK');
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
 module.exports = {
   listOpenBlockers,
   countOpenBlockers,
@@ -154,6 +213,7 @@ module.exports = {
   createBlocker,
   resolveBlocker,
   linkBlockerToTask,
+  unlinkBlockerFromTask,
   blocksOnLink,
   LINK_BLOCKABLE_STATUSES,
 };

package/modules/ideas/routes/blockers.js

@@ -145,5 +145,46 @@ module.exports = function buildBlockersRouter() {
     }
   });
 
+  // Unlink a blocker from a task — the inverse of /link (task 1003518). Both ids
+  // sit in the PATH, matching DELETE /tasks/:id/dependencies/:depId, the closest
+  // existing shape: an edge between two rows, removed by naming both.
+  //
+  // Post-core_223 a task is released only when its LAST open blocker resolves,
+  // so a wrong link is permanent: the only way out was to resolve a blocker that
+  // was never real, putting a falsehood in the blocker ledger to clear a
+  // bookkeeping artifact. This is the honest way out.
+  //
+  // Promotion is the TRIGGER's job here exactly as it is on /resolve: core_256
+  // fires AFTER DELETE on task_blockers and re-uses core_223's predicate, so
+  // "nothing open is left against this task" has one definition, not two.
+  // blockers.unlinkBlockerFromTask only deletes and reads back what happened.
+  //
+  // `released` says whether the task actually moved, never a bare {ok:true}
+  // (task 1002559 — a write that reports success without saying what changed is
+  // how a dead loop hides).
+  // Metic+ (#360 / ADR 0018) — same blocker-review grant as link and resolve.
+  // rank: metic+archon — unlink a blocker from a task; same blocker-review grant as link.
+  router.delete('/blockers/:id/link/:taskId', api.requireBuilder, api.requirePermission('blocker.review'), async (req, res) => {
+    // Both ids strict positive integers (`positiveInt`), via the shared parseId
+    // rather than a hand-rolled check: a `7.5` would otherwise pass a bare
+    // isFinite and then simply miss on the DELETE, answering "not linked" for
+    // what is really a malformed id. The sibling link/resolve routes predate
+    // that option; this one has no reason to be looser than it can be.
+    const id = parseId(req, res, { code: 'bad_id', positiveInt: true });
+    if (id === null) return;
+    const taskId = parseId(req, res, { param: 'taskId', code: 'bad_task_id', positiveInt: true });
+    if (taskId === null) return;
+    try {
+      const { released } = await blockers.unlinkBlockerFromTask({ blockerId: id, taskId });
+      res.json({ ok: true, unlinked: true, released });
+    } catch (err) {
+      if (err.code === 'LINK_NOT_FOUND') {
+        return res.fail('link_not_found', { status: 404, message: 'that blocker is not linked to that task' });
+      }
+      console.error('[gds] DELETE /blockers/:id/link/:taskId', err);
+      res.fail('unlink_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   return router;
 };

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1043",
+  "version": "1.19.1045",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.1043",
+      "version": "1.19.1045",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1043",
+  "version": "1.19.1045",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -7559,5 +7559,17 @@
       "id": "1004301",
       "text": "A task's own page now says where its code is — which version carries it, whether it is running on Bongos, whether it is released — and says plainly when a task marked done never actually landed."
     }
+  ],
+  "1.19.1044": [
+    {
+      "id": "1003518",
+      "text": "A blocker that was linked to the wrong task — a duplicate, or a mistake — can now be unlinked, and the task goes back to being claimable if nothing else was holding it. Before this the only way out was to mark the blocker reso"
+    }
+  ],
+  "1.19.1045": [
+    {
+      "id": "1003458",
+      "text": "The Tasks board and the Goals page now claim and release work through one shared piece of code instead of two copies that had already drifted apart — the same refusal was worded differently on each page, and one had lost its \""
+    }
   ]
 }

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // 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.1043'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1045'; // 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/blocker_unlink.mjs

@@ -0,0 +1,251 @@
+// tests/blocker_unlink.mjs
+//
+// Task 1003518 — a blocker can be UNLINKED from a task. Linking is one-way and
+// Metic+, and post-core_223 a task is released only when its LAST open blocker
+// resolves, so a wrong link (wrong task id, a duplicate filed twice, a blocker
+// later understood to be irrelevant) was permanent: the only escape was to
+// resolve a blocker that was never real, putting a falsehood in the ledger.
+//
+// TWO HALVES, mirroring tests/blocker_resolve_guard.mjs:
+//   1. the JS is an OBSERVER — it deletes and reads back, it never promotes;
+//   2. the promotion itself is core_256's trigger, pinned as SQL TEXT so a
+//      later edit cannot quietly drop the guard or "simplify" it into a bug.
+//
+// The JS half is behavioural, not shape assertions. The module-level `pool` is
+// replaced through require.cache BEFORE blockers.js loads, so the default
+// (zero-injection) path is the one under test — the shape a `deps.pool || pool`
+// shadowing bug would break while a harness that always injects stayed green.
+//
+// Run:  node tests/blocker_unlink.mjs
+
+import { strict as assert } from 'node:assert';
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+import { makeRunner, makeSqlAwareClient } from './helpers.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, '..');
+const read = (...p) => readFileSync(join(repoRoot, ...p), 'utf8');
+const require = createRequire(import.meta.url);
+const { test, summary } = makeRunner();
+
+// -- the fake pool, installed as the module's OWN pool ----------------------
+
+let current = null;   // the pool the stubbed module-api hands out this test
+let releases = 0;     // how many times client.release() was called
+
+const apiPath = require.resolve('../src/module-api.js');
+require.cache[apiPath] = {
+  id: apiPath,
+  filename: apiPath,
+  loaded: true,
+  exports: { pool: { connect: (...a) => current.connect(...a) } },
+};
+
+const blockers = require('../modules/ideas/blockers.js');
+
+// before/after: the task's status either side of the DELETE (the trigger is what
+// changes it in production, so the fake simply reports what it would have done).
+// deleted: rows the DELETE returns (0 = there was no such link).
+// failOn: a substring; the first matching statement throws.
+function scenario({ before = 'blocked', after = 'ready', deleted = 1, failOn = null } = {}) {
+  let seenDelete = false;
+  const pool = makeSqlAwareClient((sql) => {
+    if (failOn && sql.includes(failOn)) throw new Error('boom');
+    if (/^DELETE FROM task_blockers/.test(sql)) {
+      seenDelete = true;
+      return { rows: Array.from({ length: deleted }, () => ({ task_id: 7 })) };
+    }
+    if (/^SELECT status FROM tasks/.test(sql)) {
+      return { rows: [{ status: seenDelete ? after : before }] };
+    }
+    return { rows: [] };
+  });
+  const realRelease = pool._client.release.bind(pool._client);
+  pool._client.release = () => { releases += 1; realRelease(); };
+  current = pool;
+  releases = 0;
+  return pool;
+}
+
+const sqlOf = (pool) => pool.queries.map((q) => String(q.sql).replace(/\s+/g, ' ').trim());
+const unlink = (opts) => blockers.unlinkBlockerFromTask({ blockerId: 93, taskId: 7 }, opts);
+
+// == 1. the JS observes =====================================================
+
+await test('the link row is deleted, keyed on BOTH ids', async () => {
+  const pool = scenario();
+  await unlink();
+  const del = pool.queries.find((q) => /DELETE FROM task_blockers/.test(q.sql));
+  assert.ok(del, 'no DELETE was issued');
+  // Order matters: the SQL is (task_id, blocker_id), so a swap deletes a
+  // different edge — or silently none.
+  assert.deepEqual(del.params, [7, 93]);
+});
+
+await test('the JS never promotes — that is core_256s job', async () => {
+  // The same assertion blocker_resolve_guard.mjs makes about the resolve path,
+  // restated for unlink so the next person to "just fix it here" trips a test.
+  const src = read('modules', 'ideas', 'blockers.js');
+  assert.doesNotMatch(src, /UPDATE\s+tasks[\s\S]{0,200}?status\s*=\s*'ready'/);
+});
+
+await test('the whole unlink is one transaction', async () => {
+  const pool = scenario();
+  await unlink();
+  const s = sqlOf(pool);
+  assert.equal(s[0], 'BEGIN');
+  assert.equal(s[s.length - 1], 'COMMIT');
+});
+
+await test('the before-status is read FOR UPDATE so the read-back cannot be raced', async () => {
+  const pool = scenario();
+  await unlink();
+  const s = sqlOf(pool);
+  const first = s.find((q) => q.startsWith('SELECT status FROM tasks'));
+  assert.match(first, /FOR UPDATE/);
+  // …and it is read BEFORE the delete, or "did this unlink move it?" is unanswerable.
+  assert.ok(s.indexOf(first) < s.findIndex((q) => q.startsWith('DELETE FROM task_blockers')));
+});
+
+await test('released:true when the task went blocked -> ready', async () => {
+  scenario({ before: 'blocked', after: 'ready' });
+  assert.deepEqual(await unlink(), { unlinked: true, released: true });
+});
+
+await test('released:false while another blocker is still open', async () => {
+  // The trigger's NOT EXISTS fails, so the task stays blocked. The unlink still
+  // happened — but saying released:true here is the task-1002559 lie.
+  scenario({ before: 'blocked', after: 'blocked' });
+  assert.deepEqual(await unlink(), { unlinked: true, released: false });
+});
+
+await test('released:false when the task was never blocked in the first place', async () => {
+  // A link can land on a task that LINK_BLOCKABLE_STATUSES never parks (active,
+  // backlog, shipped). Reporting "released" for one of those would claim a
+  // promotion that never happened — and would be exactly what a naive
+  // "is it ready now?" read-back returns.
+  scenario({ before: 'active', after: 'active' });
+  assert.deepEqual(await unlink(), { unlinked: true, released: false });
+});
+
+await test('released:false for a task that was ALREADY ready before the unlink', async () => {
+  // THE DISCRIMINATING CASE. A legacy blocker_ref link, or one that landed while
+  // the task was not blockable, leaves a 'ready' task carrying a link. Removing
+  // it changes nothing — but a naive "is it ready NOW?" read-back reports a
+  // release that never happened. Only comparing against the BEFORE status can
+  // tell the two apart, which is why that status is read at all.
+  scenario({ before: 'ready', after: 'ready' });
+  assert.deepEqual(await unlink(), { unlinked: true, released: false });
+});
+
+await test('a link that is not there refuses with LINK_NOT_FOUND and rolls back', async () => {
+  const pool = scenario({ deleted: 0 });
+  await assert.rejects(() => unlink(), (e) => e.code === 'LINK_NOT_FOUND');
+  const s = sqlOf(pool);
+  assert.ok(s.includes('ROLLBACK'), 'must roll back');
+  assert.ok(!s.includes('COMMIT'), 'must not commit');
+});
+
+await test('an unexpected failure rolls back exactly once', async () => {
+  const pool = scenario({ failOn: 'DELETE FROM task_blockers' });
+  await assert.rejects(() => unlink());
+  const s = sqlOf(pool);
+  assert.equal(s.filter((q) => q === 'ROLLBACK').length, 1);
+  assert.ok(!s.includes('COMMIT'));
+});
+
+await test('the client is returned to the pool on EVERY path', async () => {
+  scenario();
+  await unlink();
+  assert.equal(releases, 1, 'success path');
+
+  scenario({ deleted: 0 });
+  await assert.rejects(() => unlink());
+  assert.equal(releases, 1, 'refusal path');
+
+  scenario({ failOn: 'DELETE FROM task_blockers' });
+  await assert.rejects(() => unlink());
+  assert.equal(releases, 1, 'error path');
+});
+
+await test('an injected pool overrides the module-level one', async () => {
+  scenario({ before: 'active', after: 'active' });   // module-level: would say false
+  let sawDelete = false;
+  const other = makeSqlAwareClient((sql) => {
+    if (/^DELETE FROM task_blockers/.test(sql)) { sawDelete = true; return { rows: [{ task_id: 7 }] }; }
+    if (/^SELECT status FROM tasks/.test(sql)) return { rows: [{ status: sawDelete ? 'ready' : 'blocked' }] };
+    return { rows: [] };
+  });
+  assert.equal((await unlink({ pool: other })).released, true, 'the injected pool must be the one used');
+  assert.equal(current.queries.length, 0, 'the module-level pool saw none');
+});
+
+// == 2. core_256 — the trigger that actually releases =======================
+
+const MIG = 'core_256_blocker_unlink_releases_task.sql';
+const mig = read('migrations', MIG);
+const migN = mig.replace(/\s+/g, ' ');
+// Comments carry the rationale; strip them when asserting on the executable
+// body, so a claim in prose can never stand in for the real SQL.
+const body = mig.replace(/^\s*--.*$/gm, '').replace(/\s+/g, ' ');
+
+await test('256 installs an AFTER DELETE row trigger on task_blockers', () => {
+  assert.match(body, /CREATE OR REPLACE FUNCTION trg_release_task_on_blocker_unlink\(\)/);
+  assert.match(body, /AFTER DELETE ON task_blockers/);
+  assert.match(body, /FOR EACH ROW/);
+});
+
+await test('the release targets ONLY a blocked task', () => {
+  assert.match(body, /UPDATE tasks SET status = 'ready'/);
+  assert.match(body, /WHERE id = OLD\.task_id/);
+  // Without this, an unlink would launder any task straight to 'ready' — past
+  // the metic+archon promote gate.
+  assert.match(body, /AND status = 'blocked'/);
+});
+
+await test("core_223's NOT EXISTS over the task's remaining open blockers is carried", () => {
+  assert.match(body, /AND NOT EXISTS \( SELECT 1 FROM task_blockers tb JOIN blockers b ON b\.id = tb\.blocker_id/);
+  assert.match(body, /WHERE tb\.task_id = OLD\.task_id/);
+  assert.match(body, /AND b\.status = 'open'/);
+});
+
+await test("and deliberately has NO `b.id <> …` exclusion — AFTER DELETE, the row is gone", () => {
+  // core_223 needs that clause because it runs BEFORE UPDATE, where the blocker
+  // being resolved still reads 'open' and would count itself, stalling forever.
+  // Here the link row is already deleted when the body runs, so the NOT EXISTS
+  // sees only what remains. Copying the clause across would be cargo-cult.
+  assert.doesNotMatch(body, /b\.id <>/);
+});
+
+await test('256 does NOT also gate on dependencies — that would strand the task', () => {
+  // The dep-promotion triggers (163) only flip backlog -> ready, so a task held
+  // in 'blocked' for unshipped deps would have no release path at all.
+  assert.doesNotMatch(body, /task_is_fully_unblocked/);
+});
+
+await test('256 is transactional and re-appliable', () => {
+  assert.match(migN, /BEGIN;.*COMMIT;/);
+  // A trigger has no CREATE OR REPLACE before PG 14, so the drop is what makes
+  // a re-run clean rather than a duplicate-object error.
+  assert.match(body, /DROP TRIGGER IF EXISTS release_task_on_blocker_unlink ON task_blockers/);
+  assert.doesNotMatch(body, /DROP FUNCTION/i);
+});
+
+await test('256 is the ONLY definition of the unlink-release function', () => {
+  const defs = readdirSync(join(repoRoot, 'migrations'))
+    .filter((f) => f.endsWith('.sql'))
+    .filter((f) => /FUNCTION trg_release_task_on_blocker_unlink/.test(read('migrations', f)))
+    .sort();
+  // migrate.sh applies in filename order, so a second, lower-numbered
+  // definition landing later would silently reinstate whatever it said.
+  assert.deepEqual(defs, [MIG]);
+});
+
+await test('unlinkBlockerFromTask is exported', () => {
+  assert.equal(typeof blockers.unlinkBlockerFromTask, 'function');
+});
+
+summary();