@bongos/core 1.17.0

package/modules/lifecycle/routes/claims.js

@@ -0,0 +1,506 @@
+const express = require('express');
+// Intra-module + the published doorway — a module never requires a core internal.
+const api = require('../../../src/module-api');
+const auth = api;
+const db = require('../db');
+// The evergreen newcomer-chore restock carved into modules/onboarding/ (BV1.R81 /
+// ADR 0093 §1): POST /claims restocks the chore shelf the instant one is claimed,
+// through the `onboarding` kernel port (seams.resolveOptional('onboarding')) —
+// never a direct require of a module file. The doorway re-exports the seam fns.
+const seams = api;
+const { validateOrRespond, LIMITS, parseId } = api;
+
+// V3.R33 (#254): input validation guards. Length caps + shape checks at the
+// top of every write handler. Schemas describe KNOWN-field constraints only —
+// extra unknown fields pass through (supervisor-permissive; see _helpers.js).
+
+const CLAIM_OUTCOMES = ['shipped', 'abandoned', 'partial'];
+
+// Which session a fresh claim is bound to. A CLI claim binds to the calling
+// session (creator_session_id) so a later ship from a DIFFERENT terminal trips
+// CLAIM_SESSION_MISMATCH — that guard catches a builder accidentally shipping
+// from the wrong worktree. But a claim made from the WEB UI (#616) has no
+// working session: the builder claims in the browser, then opens a terminal to
+// do the work. Binding to the throwaway web session would force every such
+// builder to `release --force` before they could ship. So a web claim passes
+// bind_session=false and is created session-UNBOUND (creator_session_id=null),
+// which makes the mismatch check short-circuit and lets any of the builder's
+// own CLI sessions adopt and ship it. Default true keeps every CLI caller
+// (which omits the flag) on the existing bind-to-session behaviour.
+function resolveCreatorSessionId(bindSession, sessionId) {
+  return bindSession === false ? null : (sessionId ?? null);
+}
+
+// V4.R14 (#952): the way-forward hint on a TASK_NOT_READY 409. A 'backlog' task
+// is promoted; any other non-ready status (blocked/active/…) is explained. Pure +
+// exported so the message is pinned by a test without standing up a route.
+function taskNotReadyHint(taskId, currentStatus) {
+  const idNum = Number(taskId);
+  return currentStatus === 'backlog'
+    ? `Task #${idNum} is in 'backlog' — promote it first: POST /api/bongos/tasks/${idNum}/promote (Archon), then claim.`
+    : `Task #${idNum} is '${currentStatus}', not 'ready' — only 'ready' tasks are claimable (promote applies to 'backlog': POST /api/bongos/tasks/${idNum}/promote).`;
+}
+
+// task 1642 — the pure session-scoped one-active-claim decision. Working two
+// tasks from one worktree means every commit lands on the single branch that
+// worktree owns; /builder-ship publishes the whole branch, so shipping one task
+// drags the other's commits with it (commingled ships). The structural cure: a
+// CLI session (≈ one worktree) may hold at most ONE active claim at a time.
+//
+// Keyed on creator_session_id, NOT builder id — a builder may run many sessions
+// in parallel, each with its own worktree and exactly one claim; that norm must
+// keep working. Session-scoped, all ranks (generalizes the old Xenos-only,
+// builder-scoped gateNewcomerClaim).
+//
+// NULL-session handling: a web claim (bind_session=false) stores
+// creator_session_id=NULL and is adoptable by any of the builder's CLI sessions.
+// We MUST skip the check when the *incoming* claim has no session (nothing to
+// scope to) — the caller passes creatorSessionId=null and we allow. The DB
+// helper that feeds activeClaimsForSession already filters to the SAME non-null
+// session, so a pile of NULL-session web claims can never count against a CLI
+// session either.
+//
+// Pure + exported so the decision is unit-testable without a DB or a route.
+// Returns { refuse, inFlightTaskId, inFlightTitle, reason }.
+function shouldRefuseSessionClaim({ activeClaimsForSession, creatorSessionId }) {
+  // No session to scope to (web/unbound claim, or a CLI caller with no session):
+  // there is nothing this guard can key on — let it through. The per-task unique
+  // index and the newcomer gate still apply.
+  if (!creatorSessionId) {
+    return { refuse: false, inFlightTaskId: null, inFlightTitle: null, reason: null };
+  }
+  const claims = Array.isArray(activeClaimsForSession) ? activeClaimsForSession : [];
+  // Defence in depth: only count claims that actually belong to THIS session and
+  // are genuinely session-bound. A NULL-session row must never trip the block.
+  const inFlight = claims.find(
+    (c) => c && c.creator_session_id != null && c.creator_session_id === creatorSessionId
+  );
+  if (inFlight) {
+    return {
+      refuse: true,
+      inFlightTaskId: inFlight.task_id ?? null,
+      inFlightTitle: inFlight.title ?? null,
+      reason: 'session_already_has_active_claim',
+    };
+  }
+  return { refuse: false, inFlightTaskId: null, inFlightTitle: null, reason: null };
+}
+
+// task 1642 — the route middleware that enforces the rule above. FAIL-CLOSED:
+// this is a hard correctness block (it stops commingled ships), so if the
+// session-active-claim lookup throws we REFUSE rather than silently allow. That
+// is the deliberate inverse of gateNewcomerClaim's fail-open posture (onboarding
+// plumbing must never brick a claim; this concurrency guard must never let a
+// second claim slip through on an error). A NULL incoming session short-circuits
+// to allow (handled inside shouldRefuseSessionClaim) — web/unbound claims and
+// session-less CLI callers are unaffected.
+async function gateOneActiveClaimPerSession(req, res, next) {
+  // bind_session=false ⇒ session-UNBOUND web claim: resolveCreatorSessionId
+  // will store NULL, so there is nothing to scope to. Mirror that here so we
+  // never do a needless lookup and never block a web claim.
+  const creatorSessionId = resolveCreatorSessionId(req.body?.bind_session, req.gdsSession?.session_id);
+  if (!creatorSessionId) return next();
+  let activeClaimsForSession;
+  try {
+    activeClaimsForSession = await db.getActiveClaimsForSession(creatorSessionId);
+  } catch (err) {
+    // FAIL-CLOSED. A lookup failure must not let a commingling second claim land.
+    console.error('[gds] gateOneActiveClaimPerSession lookup failed (failing closed):', err);
+    return res.fail('session_claim_check_failed', { status: 409, message: 'Could not verify this session has no other claim in flight. Try again, or start a fresh session/worktree for this task.' });
+  }
+  const decision = shouldRefuseSessionClaim({ activeClaimsForSession, creatorSessionId });
+  if (decision.refuse) {
+    const n = decision.inFlightTaskId;
+    return res.fail('session_already_has_active_claim', { status: 409, message: `This session already has task ${n} in flight — ship or release it first, or start a new session/worktree for this one.`, details: { active_task_id: n, active_task_title: decision.inFlightTitle, what_to_do: `Run /builder-ship ${n} (or /builder-release ${n}) before claiming new work, or open a fresh worktree/session for this task.` } });
+  }
+  next();
+}
+
+// Newcomer claim gate. Keeps a fresh arrival focused: ship thy current work
+// before opening another. This applies only while the builder is a Xenos —
+// once they graduate to Thetes (after 3 shipped tasks, #692 / ADR 0034) they
+// may juggle claims freely.
+//
+// History: until #766 this also enforced a primer_read stage ("read the primer
+// before claiming"). That gate was removed when the primer requirement was
+// dropped from the Xenos path; the one-claim-at-a-time rule below is all that
+// remains, and it's now keyed on the live rank rather than an onboarding stage.
+async function gateNewcomerClaim(req, res, next) {
+  try {
+    // Only Xenos are held to the one-claim-at-a-time rule. Everyone else
+    // (Thetes, Metic, Archon — and the no-rank fail-open below) passes through.
+    if (!req.builder || req.builder.rank !== 'xenos') return next();
+    const active = await db.getActiveClaimsForBuilder(req.builder.id);
+    if (active.length > 0) {
+      const top = active[0];
+      return res.fail('newcomer_must_ship_first', { status: 403, message: 'Ship thy current claim before opening another. The first work must be carried through.', details: { active_claim_id: top.claim_id, active_task_id: top.task_id, active_task_title: top.title, what_to_do: `Run /builder-ship ${top.task_id} (or /builder-release ${top.task_id} to abandon it) before claiming new work.` } });
+    }
+    next();
+  } catch (err) {
+    console.error('[gds] gateNewcomerClaim failed:', err);
+    // Fail open — onboarding plumbing must never brick a claim attempt.
+    next();
+  }
+}
+
+module.exports = function buildClaimsRouter() {
+  const router = express.Router();
+
+  // rank: any-builder — own work (claim a ready task); Xenos additionally filtered
+  // to newcomer_friendly rows inside db.claimTask (returns rank_too_low_for_task
+  // 403). Supervisor hot path (preserved per CRITICAL §4 — no requireRank).
+  // gateNewcomerClaim enforces the newcomer focus rule — a Xenos must ship
+  // their current claim before opening another (#766; the prior primer gate
+  // was removed there).
+  // task 1642: gateOneActiveClaimPerSession is the session-scoped, all-rank,
+  // FAIL-CLOSED hard block on a second active claim in the same session (one
+  // worktree → one claim → no commingled ships). It runs BEFORE the Xenos-only
+  // gateNewcomerClaim, which stays for its rank-graduation messaging.
+  router.post('/claims', auth.requireBuilder, gateOneActiveClaimPerSession, gateNewcomerClaim, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      task_id: { required: true },
+      worktree_name: { type: 'string', maxLength: LIMITS.WORKTREE_NAME },
+      head_sha: { type: 'string', maxLength: 64 },
+      bind_session: { type: 'boolean' },
+      // touches[] cleanup [5/8] (task 880): the autonomous --parallel runner
+      // sets this true so file-footprint overlap is a HARD 409. Default false:
+      // an interactive single-human claim only WARNS (git merge is the real
+      // collision detector — ADR 0017).
+      enforce_touches: { type: 'boolean' },
+    })) return;
+    const { task_id: taskId, worktree_name: worktreeName, head_sha: headSha, bind_session: bindSession, enforce_touches: enforceTouches } = req.body || {};
+    // Belt-and-braces — task_id must coerce to a finite number. Older calls
+    // sent string ints (Number.isFinite passes both); reject NaN/garbage.
+    if (!Number.isFinite(Number(taskId))) {
+      return res.fail('validation_failed', 400, [{ field: 'task_id', reason: 'wrong_type', expected: 'integer' }]);
+    }
+    try {
+      const claimResult = await db.claimTask({
+        taskId: Number(taskId),
+        builderId: req.builder.id,
+        worktreeName: worktreeName ?? null,
+        headSha: headSha ?? null,
+        creatorSessionId: resolveCreatorSessionId(bindSession, req.gdsSession?.session_id),
+        enforceOverlap: enforceTouches === true,
+      });
+      const { just_unlocked: justUnlocked, overlap_warning: overlapWarning, ...claim } = claimResult;
+      const task = await db.getTask(Number(taskId));
+      // task 1168: keep the evergreen newcomer-chore shelf full. If this claim
+      // took a chore instance, stamp a replacement NOW (before responding) so
+      // the next newcomer always finds one ready — the owner's requirement that
+      // a fresh one is there the instant one is CLAIMED, not when completed.
+      // Best-effort + fail-open: a restock failure must never break the claim
+      // (it self-heals on the next claim, and the manual seeder is a backstop).
+      // Resolved through the `onboarding` kernel port (BV1.R81); when the module
+      // is off there is no chore shelf, so this is a clean no-op.
+      const onboarding = seams.resolveOptional('onboarding');
+      if (onboarding && task && task.source === onboarding.SOURCE_TAG) {
+        try {
+          await onboarding.restockForClaim(task);
+        } catch (e) {
+          console.log('[gds] newcomer chore restock after claim failed (non-blocking):', e && e.message);
+        }
+      }
+      // V3.R51 (#270): claim.worktree_name is the SERVER-DECIDED name. If the
+      // requested name collided with another currently-active claim, the server
+      // silently disambiguated it (e.g. "foo" → "foo-2") and the claim still
+      // succeeded — so the caller must read claim.worktree_name back, not assume
+      // it got the name it asked for.
+      res.status(201).json({ claim, task, just_unlocked: justUnlocked ?? [], overlap_warning: overlapWarning ?? null });
+    } catch (err) {
+      if (err && err.code) {
+        const status =
+          err.code === 'TASK_NOT_FOUND' ? 404 :
+          err.code === 'TASK_NOT_READY' ? 409 :
+          err.code === 'TOUCHES_CONFLICT' ? 409 :
+          err.code === 'MODULE_CONFLICT' ? 409 :
+          err.code === 'DEPS_NOT_SHIPPED' ? 409 :
+          // task 1670 / ADR 0096: an unrewarded (0/NULL credits_reward) task can't
+          // be claimed — the claim-time backstop to the promote gate. Grandfathered
+          // tasks (already 'ready' at migration 177) are exempt and never reach here.
+          err.code === 'REWARD_REQUIRED' ? 409 :
+          err.code === 'ALREADY_CLAIMED' ? 409 :
+          err.code === 'BUILDER_INACTIVE' ? 403 :
+          // V3.R15 #239: rank_too_low_for_task is the canonical Xenos-gate code;
+          // XENOS_RESTRICTED is the pre-rename alias still honored by callers
+          // on older releases.
+          err.code === 'rank_too_low_for_task' ? 403 :
+          err.code === 'XENOS_RESTRICTED' ? 403 :
+          // V3.R82 #301: the inverse rank gate — task.requires_rank above the
+          // builder's. Same 403 semantics as the Xenos gate; the body carries
+          // { required, actual } so the CLI can render a clean message.
+          err.code === 'INSUFFICIENT_RANK' ? 403 :
+          500;
+        // V4.R14 (#952): a TASK_NOT_READY 409 names the way forward instead of
+        // leaving the caller to discover the promote route by spelunking (#506).
+        if (err.code === 'TASK_NOT_READY') {
+          err.hint = taskNotReadyHint(taskId, err.currentStatus);
+        }
+        return res.fail(err.code, status, { ...err });
+      }
+      console.error('[gds] POST /claims', err);
+      res.fail('claim_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // Atomic multi-claim. Body: { task_ids: [n,n,n], worktree_name?: string }.
+  // All-or-nothing: if any single task fails (already claimed, not ready, or
+  // touches conflict with another active claim OR another task in the batch),
+  // the whole transaction rolls back and we return 409 with a structured
+  // failures[] enumerating every problem found in one pass.
+  // rank: any-builder — atomic multi-claim; same Xenos row-level filter applies.
+  // V3.R13 (#237): same newcomer gate as POST /claims — a fresh builder can't
+  // sneak around the "one claim at a time" rule by batching.
+  router.post('/claims/batch', auth.requireBuilder, gateNewcomerClaim, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      task_ids: { required: true, type: 'array', maxItems: 20 },
+      worktree_name: { type: 'string', maxLength: LIMITS.WORKTREE_NAME },
+      // task 1795: mirrors POST /claims' bind_session (web claims): passing
+      // false stores EVERY row's session as NULL, matching how a
+      // session-unbound claim already works there.
+      // task 1802: omitting the flag (the real-CLI-session default) no longer
+      // binds every row — db.claimTasksBatch only binds the FIRST inserted
+      // claim to the caller's session and leaves the rest unbound, so a real
+      // session can batch-claim 2+ tasks without tripping
+      // uniq_active_claim_per_session (migration 180) on the 2nd+ INSERT. A
+      // single-task batch call is unaffected (first row IS the only row).
+      bind_session: { type: 'boolean' },
+    })) return;
+    const { task_ids: taskIds, worktree_name: worktreePrefix, bind_session: bindSession } = req.body || {};
+    if (taskIds.length === 0) {
+      return res.fail('task_ids_required', 400);
+    }
+    if (taskIds.length > 20) {
+      // Safety cap. The optimizer doesn't return more than a handful at a time,
+      // and unlimited batches let one slow transaction lock up the table.
+      return res.fail('batch_too_large', 400, { max: 20 });
+    }
+    if (!taskIds.every((id) => Number.isFinite(Number(id)))) {
+      return res.fail('task_ids_must_be_numbers', 400);
+    }
+    try {
+      const { claims } = await db.claimTasksBatch({
+        taskIds: taskIds.map(Number),
+        builderId: req.builder.id,
+        worktreePrefix: worktreePrefix ?? null,
+        creatorSessionId: resolveCreatorSessionId(bindSession, req.gdsSession?.session_id),
+      });
+      res.status(201).json({ claims });
+    } catch (err) {
+      if (err && err.code === 'BATCH_FAILED') {
+        return res.fail('batch_failed', 409, { failures: err.failures });
+      }
+      if (err && err.code === 'BATCH_EMPTY') {
+        return res.fail('task_ids_required', 400);
+      }
+      if (err && err.code === 'BATCH_DUPLICATE_IDS') {
+        return res.fail('duplicate_task_ids', 400);
+      }
+      if (err && err.code === 'BUILDER_INACTIVE') {
+        return res.fail('BUILDER_INACTIVE', 403);
+      }
+      console.error('[gds] POST /claims/batch', err);
+      res.fail('batch_claim_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // Bulk release (task 1758) — the batch twin of resolve(outcome='abandoned').
+  // Body: { claim_ids: [n,n,n], force?: boolean }. NOT all-or-nothing: each
+  // claim_id is scoped to its own ownership/state, so one bad id fails only
+  // that item — see db.releaseClaimsBatch for why (no cross-claim invariant
+  // makes sense for a release the way touches/module conflicts do for a claim).
+  // rank: any-builder — scoped to the caller's own claims (NOT_YOUR_CLAIM per item).
+  router.post('/claims/batch/release', auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      claim_ids: { required: true, type: 'array', maxItems: 20 },
+      force: { type: 'boolean' },
+    })) return;
+    const { claim_ids: claimIds, force } = req.body || {};
+    if (claimIds.length === 0) {
+      return res.fail('claim_ids_required', 400);
+    }
+    if (claimIds.length > 20) {
+      return res.fail('batch_too_large', 400, { max: 20 });
+    }
+    if (!claimIds.every((id) => Number.isFinite(Number(id)))) {
+      return res.fail('claim_ids_must_be_numbers', 400);
+    }
+    try {
+      const { released, failures } = await db.releaseClaimsBatch({
+        claimIds: claimIds.map(Number),
+        builderId: req.builder.id,
+        resolverSessionId: req.gdsSession?.session_id ?? null,
+        force: force === true,
+      });
+      res.json({ released, failures });
+    } catch (err) {
+      if (err && err.code === 'BATCH_EMPTY') {
+        return res.fail('claim_ids_required', 400);
+      }
+      console.error('[gds] POST /claims/batch/release', err);
+      res.fail('batch_release_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // Dry-run validate (task 1758) — read-only twin of claimTasksBatch's
+  // pre-flight checks. Tells the caller which of an arbitrary task_id set are
+  // individually claimable right now AND which pairs would conflict if claimed
+  // together (touches/module overlap, incl. against other builders' active
+  // claims) — WITHOUT claiming anything. Powers the hall's multi-select
+  // toolbar greying out invalid actions before a real batch claim.
+  // Body: { task_ids: [n,n,n] }.
+  // rank: any-builder — a Xenos can validate too (to see WHY something's invalid).
+  router.post('/claims/batch/validate', auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      task_ids: { required: true, type: 'array', maxItems: 20 },
+    })) return;
+    const { task_ids: taskIds } = req.body || {};
+    if (taskIds.length === 0) {
+      return res.fail('task_ids_required', 400);
+    }
+    if (!taskIds.every((id) => Number.isFinite(Number(id)))) {
+      return res.fail('task_ids_must_be_numbers', 400);
+    }
+    try {
+      const result = await db.validateClaimBatch({
+        taskIds: taskIds.map(Number),
+        builderId: req.builder.id,
+      });
+      res.json(result);
+    } catch (err) {
+      if (err && err.code === 'BATCH_EMPTY') {
+        return res.fail('task_ids_required', 400);
+      }
+      console.error('[gds] POST /claims/batch/validate', err);
+      res.fail('batch_validate_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — resolve own claim (ship/abandon); ownership checked in
+  // db.resolveClaim (NOT_YOUR_CLAIM). Supervisor hot path (preserved per CRITICAL §4).
+  router.post('/claims/:id/resolve', auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      outcome: { required: true, type: 'string', enum: CLAIM_OUTCOMES },
+      notes_md: { type: 'string', maxLength: LIMITS.NOTES },
+      value_summary: { type: 'string', maxLength: LIMITS.VALUE_SUMMARY },
+      verification: { type: 'object' },
+      force: { type: 'boolean' },
+      // touches[] cleanup [7/8] (task 882): the real committed changed-files,
+      // used to backfill touches[] from reality on a successful ship (the
+      // planning-time touches[] is now optional).
+      committed_files: { type: 'array', maxItems: 5000, itemsType: 'string' },
+      // Task #1048 (ADR 0046 follow-up): the builder's sandbox self-approval
+      // record { stamp, url, method } when a staged game change was reviewed +
+      // approved. The server stamps `by`/`at` authoritatively in db.resolveClaim.
+      sandbox_review: { type: 'object' },
+    })) return;
+    if (!Number.isFinite(Number(req.params.id))) {
+      return res.fail('validation_failed', 400, [{ field: 'id', reason: 'wrong_type', expected: 'integer' }]);
+    }
+    const claimId = Number(req.params.id);
+    const {
+      outcome,
+      notes_md: notesMd,
+      value_summary: valueSummary,
+      verification, // { passed: bool, scanner_clean: bool, smoke_clean: bool, notes_md: string }
+      force,
+      committed_files: committedFiles,
+      sandbox_review: sandboxReview, // { stamp, url, method } — server stamps by/at
+    } = req.body || {};
+    try {
+      const result = await db.resolveClaim({
+        claimId,
+        builderId: req.builder.id,
+        outcome,
+        notesMd: notesMd ?? null,
+        valueSummary: valueSummary ?? null,
+        verification: verification ?? null,
+        resolverSessionId: req.gdsSession?.session_id ?? null,
+        force: force === true,
+        committedFiles: Array.isArray(committedFiles) ? committedFiles : null,
+        sandboxReview: sandboxReview && typeof sandboxReview === 'object' ? sandboxReview : null,
+      });
+      // Response shape (Phase 5):
+      //   taskStatus       'completed' | 'confirmed' | 'ready'
+      //   creditsAwarded   number — non-zero only if status reached 'confirmed'
+      //   advanceToMerge   bool — CLI should chain into merge-mode if true
+      res.json({ ok: true, ...result, just_unlocked: result.justUnlocked ?? [] });
+    } catch (err) {
+      if (err && err.code) {
+        const status =
+          err.code === 'CLAIM_NOT_FOUND' ? 404 :
+          err.code === 'NOT_YOUR_CLAIM' ? 403 :
+          err.code === 'CLAIM_SESSION_MISMATCH' ? 403 :
+          err.code === 'ALREADY_RESOLVED' ? 409 :
+          500;
+        return res.fail(err.code, status, { ...err });
+      }
+      console.error('[gds] POST /claims/:id/resolve', err);
+      res.fail('resolve_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /claims/:id/release-on-behalf — V3.R14 (#238).
+  //
+  // Archon-only escape hatch. The normal /claims/:id/resolve path only
+  // accepts the original claimant; this route lets the Archon release
+  // someone else's stuck claim (typically a stale one the sweeper has
+  // not picked up yet, or a deliberate intervention).
+  //
+  // Body: { reason: string }. The reason is required — every Archon
+  // intervention needs a paper trail. Capped at LIMITS.NOTES.
+  //
+  // The release sets outcome='abandoned' and returns the task to
+  // status='ready' (same as a normal abandon). No credits land. The
+  // session_logs row carries the original builder_id with notes_md
+  // tagged "[archon-release]" + the acting Archon's @login so an audit
+  // grep can find every third-party release.
+  router.post('/claims/:id/release-on-behalf',
+    auth.requireBuilder,
+    auth.requireRank('archon'),
+    async (req, res) => {
+      if (validateOrRespond(req, res, {
+        reason: { required: true, type: 'string', maxLength: LIMITS.NOTES },
+      })) return;
+      const claimId = parseId(req, res, { code: 'bad_claim_id', positiveInt: true });
+      if (claimId === null) return;
+      const reason = String(req.body.reason || '').trim();
+      if (!reason) {
+        // Empty-after-trim is rejected — the whole point of the
+        // endpoint is the paper trail.
+        return res.fail('validation_failed', 400, [{ field: 'reason', reason: 'empty' }]);
+      }
+      try {
+        const result = await db.releaseClaimOnBehalf({
+          claimId,
+          archonId: req.builder.id,
+          archonLogin: req.builder.github_login || req.builder.display_name || null,
+          reason,
+        });
+        res.json({ ok: true, ...result });
+      } catch (err) {
+        if (err && err.code === 'CLAIM_NOT_FOUND') {
+          return res.fail('claim_not_found', 404);
+        }
+        if (err && err.code === 'ALREADY_RESOLVED') {
+          return res.fail('already_resolved', 409);
+        }
+        if (err && err.code === 'BAD_CLAIM_ID') {
+          return res.fail('bad_claim_id', 400);
+        }
+        console.error('[gds] POST /claims/:id/release-on-behalf', err);
+        res.fail('release_on_behalf_failed', { status: 500, message: 'internal error' });
+      }
+    }
+  );
+
+  return router;
+};
+
+// Exported for unit testing (tests/claims_bind_session.mjs) and reuse.
+module.exports.resolveCreatorSessionId = resolveCreatorSessionId;
+// V4.R14 (#952): the TASK_NOT_READY 409 hint — exported so its wording is pinned.
+module.exports.taskNotReadyHint = taskNotReadyHint;
+// task 1642: the pure session-scoped one-active-claim decision — exported for
+// tests/one_active_claim_per_session.mjs (DB-free) and reuse.
+module.exports.shouldRefuseSessionClaim = shouldRefuseSessionClaim;

package/modules/lifecycle/routes/dependencies.js

@@ -0,0 +1,82 @@
+// src/bongos/routes/dependencies.js — the polymorphic dependency edge's HTTP surface
+// (ADR 0086 §5, BV1.R62 / task 1516).
+//
+// One "blocked-until-done" edge over {task, goal, criterion}. The task->task subset
+// keeps its historical API (POST/PUT/DELETE /tasks/:id/dependencies in tasks.js);
+// THIS router creates/removes edges that involve a goal or criterion — the new
+// cross-tier coordination contract. A dependency is a REFERENCE, not a grant: it
+// never widens module scope, so cross-goal / cross-version edges are allowed. The
+// claim gate (db.unsatisfiedDeps) and the auto-promotion triggers resolve them.
+//
+// rank: archon. Authoring a cross-tier dependency reshapes execution order across
+// shared workspaces; it stays owner-gated (the same posture as the Archon-only task
+// dependency mutations in tasks.js). route-rank-check.EXPECTED_RANKS pins it.
+
+const express = require('express');
+// Intra-module + the published doorway — a module never requires a core internal.
+const api = require('../../../src/module-api');
+const auth = api;
+const db = require('../db');
+
+const KINDS = ['task', 'goal', 'criterion'];
+
+// Validate + coerce the 4-tuple edge body. Ids may arrive as JSON numbers or numeric
+// strings (pg serializes bigint as a string). Returns { fromKind, fromId, toKind,
+// toId } or null when it has already sent a 400.
+function parseEdge(req, res) {
+  const fromKind = req.body.from_kind;
+  const toKind = req.body.to_kind;
+  if (!KINDS.includes(fromKind) || !KINDS.includes(toKind)) {
+    res.fail('bad_kind', 400, { valid: KINDS });
+    return null;
+  }
+  const fromId = Number(req.body.from_id);
+  const toId = Number(req.body.to_id);
+  if (!Number.isInteger(fromId) || fromId <= 0 || !Number.isInteger(toId) || toId <= 0) {
+    res.fail('bad_id', { status: 400, message: 'from_id and to_id must be positive integers.' });
+    return null;
+  }
+  return { fromKind, fromId, toKind, toId };
+}
+
+function mapDepError(err, res, tag) {
+  if (err && err.code === 'SELF_DEP') return res.fail('self_dep', 400);
+  if (err && err.code === 'BAD_KIND') return res.fail('bad_kind', 400, { valid: KINDS });
+  if (err && err.code === 'NODE_NOT_FOUND') return res.fail('node_not_found', 404);
+  if (err && err.code === 'CYCLE') return res.fail('cycle', 409, { path: err.path });
+  console.error(`[gds] ${tag}`, err);
+  return res.fail('dependency_op_failed', { status: 500, message: 'internal error' });
+}
+
+module.exports = function buildDependenciesRouter() {
+  const router = express.Router();
+
+  // POST /dependencies — create an edge "from is blocked until to is done".
+  // rank: archon.
+  router.post('/dependencies', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    const edge = parseEdge(req, res);
+    if (!edge) return;
+    try {
+      const dependency = await db.addDependency(edge.fromKind, edge.fromId, edge.toKind, edge.toId);
+      return res.status(201).json({ ok: true, dependency });
+    } catch (err) {
+      return mapDepError(err, res, 'POST /dependencies');
+    }
+  });
+
+  // DELETE /dependencies — remove an edge (body carries the 4-tuple).
+  // rank: archon.
+  router.delete('/dependencies', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    const edge = parseEdge(req, res);
+    if (!edge) return;
+    try {
+      const removed = await db.removeDependency(edge.fromKind, edge.fromId, edge.toKind, edge.toId);
+      if (!removed) return res.fail('dependency_not_found', 404);
+      return res.json({ ok: true });
+    } catch (err) {
+      return mapDepError(err, res, 'DELETE /dependencies');
+    }
+  });
+
+  return router;
+};