@bongos/core 1.19.316 → 1.19.317

package/modules/lifecycle/db-ship.js

@@ -0,0 +1,994 @@
+// modules/lifecycle/db-ship.js — the resolve→confirm→ship state machine, landing credit + the rebase/publish flags.
+//
+// Carved out of modules/lifecycle/db.js by task 1003204 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original db.js lines 3442-4400 unchanged. db.js remains the facade that
+// re-exports every name, so every existing db call site is unchanged.
+//
+// THE BOUNDARY (ADR 0093 §1): this file reaches core ONLY through the published
+// doorway ../../src/module-api.js — never a core internal, never a sibling module.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const { pool, withTx, insertAuditLog } = api;
+const log = api.logger('lifecycle');
+const seams = api;
+const doneWhen = require('./done-when.js');
+const { THETES_GRADUATION_THRESHOLD, maybeAutoGraduateToThetes } = require('./db-rank-authz.js');
+const { mostRecentClaimHolderId, sealSessionLog, staleClaimHourPredicate } = require('./db-shared.js');
+
+// Resolve a claim. Three-state task lifecycle:
+//   active → completed         (builder declared done; awaiting grader)
+//   active → completed → confirmed   (promoted by applyGrade when the subagent
+//                                      grader passes; verified but NOT yet paid —
+//                                      ADR 0120 books credits at ship, not confirm)
+//   active → ready             (abandoned or partial — back to the queue)
+//
+// Caller passes `verification` = { passed: bool, scanner_clean, smoke_clean,
+// diff_stats, notes_md }. `passed` here is the LOCAL verification (scanner +
+// smoke). It is no longer the credits gate — that's the subagent grader, applied
+// in a separate call to applyGrade(). resolveClaim always lands the task at
+// `completed` when passed=true; the caller is expected to invoke the grader and
+// POST the result to /tasks/:id/grade (which calls applyGrade).
+//
+// Returns: { taskId, taskTitle, taskStatus, creditsAwarded, advanceToMerge,
+//            justUnlocked, grade }. With the v2 subagent grader, resolveClaim
+// itself never awards credits or advances to confirmed — those happen later
+// via applyGrade. advanceToMerge is therefore always false and grade is null
+// at resolveClaim time. Both keys stay in the response shape so existing
+// callers (ship.js) don't break.
+
+async function resolveClaim({ claimId, builderId, outcome, notesMd, valueSummary, verification, resolverSessionId, force, committedFiles = null, sandboxReview = null }) {
+  return withTx(async (client) => {
+    const { rows: claimRows } = await client.query(
+      `SELECT c.id, c.task_id, c.builder_id, c.released_at, c.claimed_at,
+              c.worktree_name, c.creator_session_id,
+              t.credits_reward, t.title
+         FROM claims c JOIN tasks t ON t.id = c.task_id
+        WHERE c.id = $1 FOR UPDATE`,
+      [claimId]
+    );
+    if (claimRows.length === 0) throw { code: 'CLAIM_NOT_FOUND' };
+    const claim = claimRows[0];
+    if (claim.builder_id !== builderId) throw { code: 'NOT_YOUR_CLAIM' };
+    if (claim.released_at) throw { code: 'ALREADY_RESOLVED' };
+    // Session lock: only the session that created this claim can resolve it.
+    // Skipped when force=true (emergency), when the claim pre-dates this
+    // migration (creator_session_id IS NULL), or when the resolver has no
+    // session context (legacy path). This closes the cross-session release hole.
+    if (!force && claim.creator_session_id && resolverSessionId &&
+        claim.creator_session_id !== resolverSessionId) {
+      throw { code: 'CLAIM_SESSION_MISMATCH', claimWorktree: claim.worktree_name ?? null };
+    }
+
+    await client.query(
+      `UPDATE claims SET released_at = now(), outcome = $2 WHERE id = $1`,
+      [claimId, outcome]
+    );
+
+    // Map outcome → task status under the new lifecycle.
+    // 'shipped' from the CLI now means "builder declared done" → completed.
+    // The CLI keeps the legacy outcome name to avoid an enum migration on
+    // claims.outcome; the task-level status is what's gaining the new states.
+    let newTaskStatus;
+    if (outcome === 'shipped') newTaskStatus = 'completed';
+    else if (outcome === 'abandoned') newTaskStatus = 'ready';
+    else if (outcome === 'partial') newTaskStatus = 'ready';
+    else newTaskStatus = 'ready';
+
+    await client.query(
+      `UPDATE tasks
+          SET status = $2,
+              value_summary = COALESCE($3, value_summary),
+              updated_at = now()
+        WHERE id = $1`,
+      [claim.task_id, newTaskStatus, valueSummary ?? null]
+    );
+
+    // touches[] cleanup [7/8] (task 882): backfill touches[] from the REAL
+    // committed diff at ship. The planning-time touches[] is now optional (a
+    // prediction nobody has to get right up front); on a successful ship we
+    // replace it with what git actually reports, so the declared set becomes
+    // reality. This is the write path that makes the touches[]-keyed profile
+    // counters (art_ships / pms_ships, see achievements + db leaderboard) and
+    // the historical record diff-accurate — closing the loop left open in #878.
+    // Only on a 'shipped' resolve with a non-empty list (never wipe touches[]
+    // with an empty diff on a DB-only / no-op ship).
+    if (outcome === 'shipped' && Array.isArray(committedFiles) && committedFiles.length > 0) {
+      const cleaned = Array.from(
+        new Set(committedFiles.map((p) => String(p || '').trim()).filter(Boolean))
+      );
+      if (cleaned.length > 0) {
+        await client.query(
+          `UPDATE tasks SET touches = $2, updated_at = now() WHERE id = $1`,
+          [claim.task_id, cleaned]
+        );
+      }
+    }
+
+    // Task #1048 (ADR 0046 follow-up): record the builder's sandbox self-approval
+    // as a durable fact on the task. When a dev-box builder reviews a staged
+    // game change on their sandbox and approves shipping it (TTY 'y', or an
+    // explicit --approved re-run on the dominant non-TTY path), ship.js threads
+    // { stamp, url, method } through this resolve call. We stamp `by` + `at`
+    // SERVER-SIDE (never trust the client for identity or time) and persist the
+    // blob to tasks.sandbox_review. Only on a 'shipped' resolve carrying a
+    // payload — laptop ships, non-game diffs, quick-tunnel boxes, --skip-stage,
+    // and un-approved re-runs send nothing, leaving the column NULL.
+    if (outcome === 'shipped' && sandboxReview && typeof sandboxReview === 'object' && sandboxReview.stamp) {
+      // Sanitize the client-supplied fields (defense in depth): the builder's
+      // box controls stamp/url/method, so clamp lengths, whitelist `method`, and
+      // accept only an https:// URL. This keeps a forged/oversized value — or a
+      // future stored-XSS string like a `javascript:` URL rendered in the hall —
+      // out of the persisted record. `by`/`at` stay SERVER-stamped (never
+      // client-set), so identity and time can't be spoofed.
+      const srStamp = String(sandboxReview.stamp).slice(0, 128);
+      const srUrl = (typeof sandboxReview.url === 'string' && /^https:\/\//.test(sandboxReview.url))
+        ? sandboxReview.url.slice(0, 256)
+        : null;
+      const srMethod = ['tty', 'flag'].includes(sandboxReview.method) ? sandboxReview.method : 'flag';
+      await client.query(
+        `UPDATE tasks
+            SET sandbox_review = jsonb_build_object(
+                  'by',     (SELECT github_login FROM builders WHERE id = $2),
+                  'at',     now(),
+                  'stamp',  $3::text,
+                  'url',    $4::text,
+                  'method', $5::text
+                ),
+                updated_at = now()
+          WHERE id = $1`,
+        [claim.task_id, builderId, srStamp, srUrl, srMethod]
+      );
+    }
+
+    // Write the session_logs entry + recompute actual_minutes FIRST, so the
+    // grader (below) can see a fresh actual_minutes value when scoring the
+    // est/actual ratio criterion.
+    await sealSessionLog(client, {
+      builderId, taskId: claim.task_id, claimId, startedAt: claim.claimed_at,
+      outcome, notesMd: notesMd ?? null,
+    });
+    await client.query(
+      `UPDATE tasks
+          SET actual_minutes = (
+            SELECT COALESCE(
+              SUM(EXTRACT(EPOCH FROM (ended_at - started_at)) / 60)::integer,
+              0
+            )
+            FROM session_logs
+            WHERE task_id = $1
+          )
+        WHERE id = $1`,
+      [claim.task_id]
+    );
+
+    // V3.R18 (#209): the credits gate moved out of resolveClaim into a separate
+    // subagent grader. resolveClaim's job is now just "did local verification
+    // (scanner + smoke) pass — if yes, land at completed and stop." The caller
+    // then runs the subagent grader and POSTs the result to /tasks/:id/grade,
+    // which advances completed→confirmed and awards credits when the grader
+    // passes (see applyGrade below).
+    //
+    // The response shape preserves `advanceToMerge` and `grade` so ship.js
+    // doesn't need to change at the resolveClaim seam — both are always
+    // false/null with the new flow.
+
+    return {
+      taskId: claim.task_id,
+      taskTitle: claim.title,
+      taskStatus: newTaskStatus,
+      creditsAwarded: 0,
+      advanceToMerge: false,
+      justUnlocked: [],
+      grade: null,
+    };
+  });
+}
+
+// Final transition: confirmed → shipped. Called by /merge-mode (or auto-merge
+// in /builder-ship) once the branch is on main + deployed. THIS is the credit
+// moment — ADR 0120 pays on land, so awardLandingCredit books the reward here
+// (credit_log.reason = 'task.shipped'), not at confirm. Sets shipped_at.
+//
+// V3.R14 (#238): also stamps builders.first_ship_at the first time this
+// builder ever crosses the ship threshold. COALESCE makes the write
+// idempotent — subsequent ships leave the first stamp untouched. Done in
+// the same transaction so a roster query that joins both tables sees a
+// consistent view.
+
+// awardLandingCredit — the per-task reward, booked at the SHIPPED transition
+// (ADR 0120 "pay on land"). Moved out of the three confirm paths (confirmTask /
+// decideOverrideRequest / applyGrade): the per-task credit + idea-promotion
+// bonus now exist ONLY once the code is merged to `main`, so a task that
+// strands at 'confirmed' pays nothing. Idempotent on (task_id,
+// reason='task.shipped') — mirrors the old (task_id, 'task.confirmed') guard —
+// so a re-ship or a reconciler re-sweep is a true no-op. The reason is
+// deliberately 'task.shipped' (not 'task.confirmed'): after the one-time
+// clawback (ADR 0120 part 4) reverses a stranded task's OLD 'task.confirmed'
+// row, re-landing books a FRESH 'task.shipped' row — the reward is fully
+// re-earnable, exactly as the ADR promises. Caller passes its ship txn client
+// so the credit commits atomically with the status flip.
+async function awardLandingCredit(client, { taskId, creditedBuilderId, creditsReward, kind }) {
+  const reward = seams.resolveOptional('reward');
+  if (!reward || creditedBuilderId == null || !(Number(creditsReward) > 0)) {
+    return { creditsAwarded: 0, ideaBonus: null };
+  }
+  const { rows: existing } = await client.query(
+    `SELECT 1 FROM credit_log WHERE task_id = $1 AND reason = 'task.shipped' LIMIT 1`,
+    [taskId]
+  );
+  if (existing.length > 0) return { creditsAwarded: 0, ideaBonus: null };
+  const credit = await reward.insertMultipliedConfirmCredit(
+    client, creditedBuilderId, taskId, creditsReward, kind, 'task.shipped'
+  );
+  // Stream 1 of the ideator credit lane (ADR 0172 / IC4) REPLACES the ADR 0023
+  // 25% idea-promotion slice here — one idea-credit-on-ship path, not two
+  // (ADR 0172 §4). Unlike the slice (25% of the builder estimate, so zero under
+  // cost-plus-only), this pays 5×grade-factor on the IDEATOR lane, so an idea
+  // earns as its work ships even when per-task builder credit is withheld. It
+  // reads the one-idea-many-tasks lineage (ideas_task_lineage, IC3), so a Full
+  // Idea that became a whole goal pays on every one of its shipped tasks — the
+  // old slice only saw the single promoted_to_task_id. `maybeAwardIdeaPromotionBonus`
+  // stays on the port for its unit tests / any compat caller, but is no longer
+  // wired at ship. Guarded so a null return (lane off, no source idea) is fine.
+  const ideaBonus = reward.awardIdeaTaskShipCredit
+    ? await reward.awardIdeaTaskShipCredit(client, { taskId })
+    : null;
+  return {
+    creditsAwarded: credit.creditsAwarded,
+    creditsRaw: credit.raw,
+    creditsMultiplier: credit.multiplier,
+    ideaBonus,
+  };
+}
+
+// flagTaskNeedsRebase — ADR 0120 part 2. The publish-reconciler calls this when
+// a confirmed task's land cannot be completed after the auto-land grace (its
+// retries + the ADR 0082 generated-file self-heal): a persistently-red PR that
+// hit the regen-heal cap, or a strand older than the stale threshold that can't
+// be proven landed (never pushed / no recorded tip). It is a SIGNAL, not a
+// status change — the task stays 'confirmed'; it is simply marked as awaiting
+// its BUILDER's rebase (attribution via tasks.shipped_by = claim holder).
+//
+// Idempotent + self-limiting: only a still-'confirmed', not-already-flagged task
+// is touched (WHERE status='confirmed' AND needs_rebase=false), so a task that
+// has since shipped or been released is never (re-)flagged, and a re-sweep of an
+// already-flagged task is a no-op. Returns true iff this call newly flagged it
+// (so the reconciler logs the transition once). needs_rebase_at is set once
+// (COALESCE) so the hall/CLI can show how long it has been outstanding.
+async function flagTaskNeedsRebase(taskId, reason = null) {
+  const { rows } = await pool.query(
+    `UPDATE tasks
+        SET needs_rebase = true,
+            needs_rebase_reason = $2,
+            needs_rebase_at = COALESCE(needs_rebase_at, now()),
+            updated_at = now()
+      WHERE id = $1 AND status = 'confirmed' AND needs_rebase = false
+      RETURNING id`,
+    [taskId, reason]
+  );
+  return rows.length > 0;
+}
+
+// needsRebaseTasksForBuilder — the confirmed tasks a builder owes a rebase on
+// (ADR 0120 parts 2-3). Attribution is tasks.shipped_by (= the claim holder,
+// COALESCE'd there at confirm). Used by the claim gate (part 3) to refuse NEW
+// claims and by the hall/CLI surfacing (part 5). Accepts an optional client so
+// it can run inside claimTask's FOR UPDATE txn or standalone on the pool.
+// Ordered oldest-flagged first so the surfacing can show the longest-outstanding.
+async function needsRebaseTasksForBuilder(builderId, client = pool) {
+  const { rows } = await client.query(
+    `SELECT id, title, needs_rebase_reason, needs_rebase_at
+       FROM tasks
+      WHERE needs_rebase = true AND status = 'confirmed' AND shipped_by = $1
+      ORDER BY needs_rebase_at ASC NULLS LAST, id ASC`,
+    [builderId]
+  );
+  return rows;
+}
+
+// The ship gate (task 1002483, ADR 0184) — see ./ship-assurance for the why.
+const { normalizeShipAssurance, assertShipAssurance, recordShipAssurance, SHIP_ASSURANCE_KINDS } = require('./ship-assurance');
+
+async function shipTask({ taskId, builderId, landAssurance }, deps = {}) {
+  const shipAssuranceValue = assertShipAssurance(landAssurance); // FAIL-CLOSED, ADR 0184
+  // #538 test seam (mirrors confirmTask): a caller-supplied pool is honored ONLY
+  // under NODE_ENV==='test', so a regression test can drive the txn with a
+  // SQL-aware fakeClient. Production callers omit deps → module pool.
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { shipRow, graduationBuilder, rankGraduation, actualShipperId, closedClaimCount, creditedBuilderId, creditsAwarded, ideaBonus, justUnlocked } = await withTx(async (client) => {
+    const { rows } = await client.query(
+      `UPDATE tasks
+          SET status = 'shipped',
+              shipped_at = now(),
+              shipped_by = COALESCE(shipped_by, $2),
+              needs_rebase = false,
+              needs_rebase_reason = NULL,
+              needs_rebase_at = NULL,
+              updated_at = now()
+        WHERE id = $1 AND status = 'confirmed'
+        RETURNING id, title, status, shipped_at, shipped_by, security_sensitive, value_summary, credits_reward, kind`,
+      [taskId, builderId]
+    );
+    if (rows.length === 0) {
+      const e = new Error('task not in confirmed state');
+      e.code = 'TASK_NOT_CONFIRMED';
+      throw e;
+    }
+    // task 1643: close any claim still OPEN on this task, inside the same txn
+    // that shipped it. The normal path already closed the claim in resolveClaim
+    // (claimed→completed); this is the safety net for STRANDS — a task that
+    // reached a terminal state without that resolve (strand recovery, direct-SQL
+    // fixups, or the confirm paths, which flip status + award credits but never
+    // touch the claim). Without it the claim dangles released_at=NULL forever and
+    // every claim-aware view (builder dashboard, parallel-safety) keeps showing
+    // the shipped task as actively claimed — the BV1.R04/R05 strand class (live
+    // repro task 1300 / claim #1292). COALESCE preserves any existing outcome; an
+    // open claim has outcome=NULL so it lands 'shipped'. The stale-claim sweeper
+    // can't do this — its release resets the task to 'ready', un-shipping it.
+    // Invariant established here: a shipped task has no open claims.
+    const { rows: closedClaims } = await client.query(
+      `UPDATE claims
+          SET released_at = now(),
+              outcome = COALESCE(outcome, 'shipped')
+        WHERE task_id = $1 AND released_at IS NULL
+        RETURNING id`,
+      [taskId]
+    );
+    // shipped_by is what actually counts — COALESCE above means the row's
+    // historical shipped_by wins over the late-arriving builderId, so use
+    // the returned value to be sure we credit the right onboarding ship.
+    const actualShipperId = rows[0].shipped_by ?? builderId;
+    if (actualShipperId != null) {
+      await client.query(
+        `UPDATE builders
+            SET first_ship_at = COALESCE(first_ship_at, now())
+          WHERE id = $1`,
+        [actualShipperId]
+      );
+    }
+    // V3.R75 (#294) / #766: tick the onboarding state machine inside the same
+    // transaction that bumped first_ship_at. The terminal stage is now
+    // 'ship_three' — it clears only once the builder has THREE shipped tasks,
+    // the same threshold that auto-promotes a Xenos to Thetes below, so the
+    // checklist graduation coincides with the rank promotion. The 1st/2nd ships
+    // are deliberately no-ops for the stage (the hall's "N of 3" counter comes
+    // from the live shipped count, not from the stage). markStage is idempotent.
+    // We wrap in try/catch so the ship can't fail because of an onboarding
+    // plumbing error — best-effort, mirrors the safeMarkStage helper but inlined
+    // to share the transaction.
+    // The onboarding state machine carved into modules/onboarding/ (BV1.R81 /
+    // ADR 0093 §1): resolve the `onboarding` kernel port and pass this txn
+    // `client` — never a direct require of a module. ?. degrades to a no-op when
+    // the module is off (best-effort anyway).
+    let graduationBuilder = null;
+    if (actualShipperId != null) {
+      try {
+        const onboarding = seams.resolveOptional('onboarding');
+        const { rows: sc } = await client.query(
+          `SELECT count(*)::int AS n FROM tasks WHERE shipped_by = $1 AND status = 'shipped'`,
+          [actualShipperId]
+        );
+        const result = (onboarding && sc[0].n >= THETES_GRADUATION_THRESHOLD)
+          ? await onboarding.markStage(client, actualShipperId, 'ship_three')
+          : null;
+        if (result && result.justGraduated) {
+          // Read the builder row for the broadcast (display_name). Cheap —
+          // same transaction. Broadcast itself fires AFTER COMMIT so a chat
+          // failure can't roll back the ship.
+          const { rows: br } = await client.query(
+            `SELECT id, display_name, github_login FROM builders WHERE id = $1`,
+            [actualShipperId]
+          );
+          graduationBuilder = br[0] || null;
+        }
+      } catch (e) {
+        // Don't roll back the ship for an onboarding write failure.
+        console.log('[gds] shipTask onboarding markStage failed (non-blocking):', e && e.message);
+      }
+    }
+
+    // #692 / ADR 0034 (trigger #704): thetes RANK auto-graduation — distinct
+    // from the onboarding-stage graduation above. Keyed on the attributed
+    // shipper; if they're now a Xenos with 3 successfully SHIPPED tasks, promote
+    // xenos→thetes atomically with this ship. Rank-guarded + idempotent.
+    const rankGraduation = await maybeAutoGraduateToThetes(client, actualShipperId);
+
+    // ADR 0120 "pay on land": the per-task credit + idea-promotion bonus are
+    // booked HERE, at the confirmed→shipped flip — no longer at confirm. The
+    // credit only exists once the code is on `main`; a task that strands at
+    // 'confirmed' (never lands) now pays nothing. Attribution is the CLAIM
+    // HOLDER (the builder who did the work), computed the same way as
+    // confirmTask — never the caller who happened to trigger the ship (the
+    // reconciler / a supervisor). mostRecentClaimHolderId reads the latest
+    // claim by claimed_at regardless of released_at, so it is correct even
+    // though the claims for this task were just closed above. Idempotent on
+    // (task_id, reason='task.shipped'), so a re-ship / reconciler re-sweep is a
+    // true no-op. Runs in THIS txn so the credit commits atomically with the
+    // status flip.
+    const creditedBuilderId = (await mostRecentClaimHolderId(client, taskId)) ?? actualShipperId;
+    const landing = await awardLandingCredit(client, {
+      taskId,
+      creditedBuilderId,
+      creditsReward: rows[0].credits_reward,
+      kind: rows[0].kind,
+    });
+    // task 1679 pattern: state-based achievement reconcile now that the credit
+    // (above) + the ship count are reflected in this txn. SAVEPOINT-wrapped so
+    // a gamification error can never fail the ship. Moved to ship because the
+    // credit it keys off (breaking-the-100c-bar etc.) now lands here.
+    let justUnlocked = [];
+    const rewardPort = seams.resolveOptional('reward');
+    if (rewardPort && rewardPort.reconcileBuilderAchievements && creditedBuilderId != null) {
+      await client.query('SAVEPOINT ach_reconcile_ship');
+      try {
+        justUnlocked = await rewardPort.reconcileBuilderAchievements(client, creditedBuilderId, { taskId });
+        await client.query('RELEASE SAVEPOINT ach_reconcile_ship');
+      } catch (_) {
+        await client.query('ROLLBACK TO SAVEPOINT ach_reconcile_ship');
+        justUnlocked = [];
+      }
+    }
+    await doneWhen.closeCompletedWorkForShip(client, taskId); // task 1002069/ADR 0183 — in-txn criterion+goal close
+    return {
+      shipRow: rows[0], graduationBuilder, rankGraduation, actualShipperId,
+      closedClaimCount: closedClaims.length,
+      creditedBuilderId, creditsAwarded: landing.creditsAwarded, ideaBonus: landing.ideaBonus, justUnlocked,
+    };
+  }, { pool: activePool });
+  if (closedClaimCount > 0) {
+    // Post-commit observability: a normal ship closes 0 here (resolveClaim
+    // already released the claim). A non-zero count means this ship healed a
+    // strand — worth a log line so the class is visible if it recurs (task 1643).
+    console.log(`[gds] shipTask: closed ${closedClaimCount} orphaned claim(s) on shipped task ${taskId} (strand safety net — task 1643)`);
+  }
+  if (graduationBuilder) {
+    try {
+      seams.resolveOptional('onboarding')?.broadcastGraduation(graduationBuilder);
+    } catch (e) {
+      console.log('[gds] graduation broadcast post-ship failed:', e && e.message);
+    }
+  }
+  if (rankGraduation) {
+    await seams.emitAsync('builder.box-reconcile-needed', {
+      builderId: actualShipperId, rank: 'thetes', status: rankGraduation.status, actor: 'auto-graduation:#692',
+    }).catch(() => {});
+  }
+  await recordShipAssurance({ insertAuditLog, taskId, builderId: actualShipperId, assurance: shipAssuranceValue, log });
+  return {
+    ...shipRow,
+    shipAssurance: shipAssuranceValue, // echoed so a caller can show it, not guess
+
+    graduatedTo: rankGraduation ? 'thetes' : null,
+    // ADR 0120: the per-task reward that landed on THIS ship (0 on a re-ship /
+    // reconciler re-sweep — idempotent). The ship route surfaces it so the
+    // builder sees "credits landed" at ship, not at confirm.
+    creditedBuilderId, creditsAwarded, ideaBonus, justUnlocked,
+  };
+}
+
+// task 1134 — feed for the server-owned publish reconciler (src/bongos/
+// publish-reconciler.js). Returns one row per CONFIRMED task from its LATEST claim
+// (by claimed_at): builder_id (the claim holder, passed to shipTask so the ship is
+// attributed to whoever did the work — shipped_by / first_ship_at / thetes
+// graduation — exactly as a self-poll would), worktree_name (→ branch
+// `claude/<worktree_name>`), and head_sha.
+//
+// task 1313 — TWO changes that close the strand class:
+//   1) head_sha is now selected, so the reconciler can prove a land directly from
+//      the commit (isAncestorOfDefaultBranch) when the PR/branch is gone.
+//   2) the `worktree_name IS NOT NULL` filter is GONE. A confirmed task whose
+//      latest claim carries no worktree_name (a server-mediated publish that never
+//      recorded one) used to be omitted entirely and strand forever; it now comes
+//      through so the head_sha ancestry check can heal it. Rows with neither a
+//      usable branch nor a sha-shaped head_sha are simply no-ops in the sweep.
+// No schema change for head_sha: claims.worktree_name + head_sha + claimed_at all
+// exist. task 1547 adds c.published_head_sha (the SERVER-pushed tip) so the sweep
+// proves a per-task land from this task's OWN commit, not a (reusable) branch name.
+
+async function listConfirmedTasksForReconcile({ limit = 100 } = {}) {
+  // t.updated_at is set to now() when confirmTask flips status→'confirmed', so for a
+  // STRANDED confirmed task (nothing else touches it) it is a faithful proxy for the
+  // confirm time. The reconciler ages out silent strands on it (task 1546 / blocker 47:
+  // 15 tasks sat unprovable for up to 66h because every sweep miss was a silent continue).
+  const { rows } = await pool.query(
+    `SELECT DISTINCT ON (t.id) t.id AS task_id, t.title, t.security_sensitive,
+            c.builder_id, c.worktree_name, c.head_sha,
+            c.published_head_sha, t.updated_at AS confirmed_at
+       FROM tasks t
+       JOIN claims c ON c.task_id = t.id
+      WHERE t.status = 'confirmed'
+      ORDER BY t.id, c.claimed_at DESC
+      LIMIT $1`,
+    [limit]
+  );
+  return rows;
+}
+
+// task 1547 — record the tip the server actually pushed for this task's
+// server-mediated publish (ADR 0055), on the LATEST claim for the task. Called by
+// POST /tasks/:id/publish-branch after a successful pushBundle. This is the durable
+// per-task land proof the reconcile gates on: claims.head_sha is the claim-time
+// BASE, which for a task whose base is already on main (e.g. an R03 base) would
+// false-positive an ancestry check; the published tip cannot. Idempotent — a
+// re-publish of the same branch just re-stamps the same sha. Returns the updated
+// claim id, or null if no claim exists (defensive — publish-branch is ownership-gated).
+
+async function setClaimPublishedSha({ taskId, builderId, sha }) {
+  if (!sha || !/^[0-9a-f]{7,64}$/.test(String(sha))) return null;
+  const { rows } = await pool.query(
+    `UPDATE claims
+        SET published_head_sha = $3
+      WHERE id = (
+        SELECT id FROM claims
+         WHERE task_id = $1 AND builder_id = $2
+         ORDER BY claimed_at DESC, id DESC
+         LIMIT 1
+      )
+      RETURNING id`,
+    [taskId, builderId, sha]
+  );
+  return rows[0]?.id ?? null;
+}
+
+// task 1547 — the published tip for the LATEST claim on a task (any builder), used
+// by the publish-status reconcile-on-read to verify the task's own commit landed
+// before flipping confirmed->shipped. NULL when no server-mediated publish recorded
+// one (legacy rows / a publish that never succeeded — e.g. the BV1.R04/R05 strand).
+
+async function getClaimPublishedSha(taskId) {
+  const { rows } = await pool.query(
+    `SELECT published_head_sha
+       FROM claims
+      WHERE task_id = $1
+      ORDER BY claimed_at DESC, id DESC
+      LIMIT 1`,
+    [taskId]
+  );
+  return rows[0]?.published_head_sha ?? null;
+}
+
+// V3.R14 (#238) — onboarding observability roster.
+//
+// One row per builder, joined with the live "what are they doing right
+// now" signals the Archon needs to triage onboarding from /builders:
+//
+//   - identity:    id, github_login, display_name, rank, status
+//   - credits:     total_credits (drachmae)
+//   - karma:       karma (good-citizenship track)
+//   - onboarding:  onboarded_at, first_ship_at,
+//                  time_to_first_ship_minutes (NULL until they've shipped)
+//   - claims:      active_claim_count, stale_claim
+//
+// "stale_claim" mirrors the stale-claim-release sweeper definition
+// (.claude/scheduled-tasks/stale-claim-release/SKILL.md): a still-open
+// claim where either the last session_pulses row is older than the
+// stale threshold, or there's no pulse row at all AND claimed_at is
+// older than the threshold. Default threshold is 24h to match this
+// task's spec — the sweeper itself uses GDS_STALE_CLAIM_HOURS (default
+// 6h) and is in charge of *acting*. The roster only *surfaces*.
+//
+// Returns: array of builder roster rows, ordered by:
+//   1. inactive builders sink to the bottom (status='inactive' last)
+//   2. still-onboarding (first_ship_at IS NULL) above shipped builders
+//   3. then by created_at DESC inside each group (newest first)
+
+async function getBuildersRoster({ staleHours = 24 } = {}) {
+  const hours = Number(staleHours);
+  if (!Number.isFinite(hours) || hours <= 0) {
+    throw new Error('getBuildersRoster: staleHours must be a positive number');
+  }
+  const { rows } = await pool.query(
+    `WITH stale_active AS (
+       SELECT c.builder_id,
+              COUNT(*) FILTER (
+                WHERE ${staleClaimHourPredicate('$1')}
+              ) AS stale_claim_count,
+              COUNT(*) AS active_claim_count
+         FROM claims c
+         LEFT JOIN session_pulses sp ON sp.claim_id = c.id
+        WHERE c.released_at IS NULL
+        GROUP BY c.builder_id
+     )
+     SELECT
+       b.id,
+       b.github_login,
+       b.display_name,
+       b.avatar_url,
+       b.rank,
+       b.status,
+       b.total_credits,
+       b.karma,
+       b.created_at,
+       b.onboarded_at,
+       b.first_ship_at,
+       CASE
+         WHEN b.first_ship_at IS NULL OR b.onboarded_at IS NULL THEN NULL
+         ELSE GREATEST(
+           0,
+           EXTRACT(EPOCH FROM (b.first_ship_at - b.onboarded_at))::bigint / 60
+         )
+       END AS time_to_first_ship_minutes,
+       COALESCE(sa.active_claim_count, 0) AS active_claim_count,
+       (COALESCE(sa.stale_claim_count, 0) > 0) AS stale_claim
+       FROM builders b
+       LEFT JOIN stale_active sa ON sa.builder_id = b.id
+      ORDER BY
+        (b.status = 'inactive') ASC,
+        (b.first_ship_at IS NOT NULL) ASC,
+        b.created_at DESC`,
+    [hours]
+  );
+  return rows;
+}
+
+// V3.R14 (#238) — stale claim detail for the roster expand view.
+// Returns the active claim rows for a specific builder *with* stale
+// signals, so the Archon can pick the right one to release. Used by
+// the management panel's per-row "release stale claim" action.
+
+async function getActiveClaimsForBuilderWithStale(builderId, { staleHours = 24 } = {}) {
+  const builder = Number(builderId);
+  const hours = Number(staleHours);
+  if (!Number.isFinite(builder)) {
+    throw new Error('getActiveClaimsForBuilderWithStale: builderId must be numeric');
+  }
+  if (!Number.isFinite(hours) || hours <= 0) {
+    throw new Error('getActiveClaimsForBuilderWithStale: staleHours must be a positive number');
+  }
+  const { rows } = await pool.query(
+    `SELECT c.id          AS claim_id,
+            c.task_id     AS task_id,
+            c.builder_id  AS builder_id,
+            c.claimed_at  AS claimed_at,
+            c.worktree_name AS worktree_name,
+            t.title       AS task_title,
+            sp.last_pulse_at AS last_pulse_at,
+            (
+              ${staleClaimHourPredicate('$2')}
+            ) AS stale_claim
+       FROM claims c
+       JOIN tasks t ON t.id = c.task_id
+       LEFT JOIN session_pulses sp ON sp.claim_id = c.id
+      WHERE c.released_at IS NULL
+        AND c.builder_id = $1
+      ORDER BY c.claimed_at ASC`,
+    [builder, hours]
+  );
+  return rows;
+}
+
+// V3.R14 (#238) — release a claim "on behalf of" the original builder.
+// Archon-only at the route layer; this helper does no rank check itself,
+// so callers MUST gate it.
+//
+// Mirrors the stale-claim-release sweeper's transaction shape:
+//   1. lock the claim row, skip if it raced to released
+//   2. set released_at + outcome='abandoned'
+//   3. send the task back to status='ready'
+//   4. write a session_logs entry tagged "[archon-release] ..." so the
+//      audit trail makes it obvious this was a third-party intervention
+//      and not the original builder abandoning their own work
+//
+// reason: free-text the Archon supplies (≤512 chars; the route validates).
+// archonLogin: display string of the acting Archon, embedded in notes_md.
+
+async function releaseClaimOnBehalf({ claimId, archonId, archonLogin, reason }) {
+  const id = Number(claimId);
+  if (!Number.isFinite(id)) {
+    throw Object.assign(new Error('claimId must be numeric'), { code: 'BAD_CLAIM_ID' });
+  }
+  return withTx(async (client) => {
+    const { rows: cur } = await client.query(
+      `SELECT c.id, c.task_id, c.builder_id, c.claimed_at, c.released_at,
+              t.title
+         FROM claims c JOIN tasks t ON t.id = c.task_id
+        WHERE c.id = $1
+        FOR UPDATE`,
+      [id]
+    );
+    if (cur.length === 0) {
+      throw Object.assign(new Error('claim not found'), { code: 'CLAIM_NOT_FOUND' });
+    }
+    if (cur[0].released_at) {
+      throw Object.assign(new Error('claim already released'), { code: 'ALREADY_RESOLVED' });
+    }
+    const { task_id: taskId, builder_id: ownerId, claimed_at: claimedAt, title } = cur[0];
+    const tag = '[archon-release]';
+    const actor = archonLogin
+      ? `@${archonLogin} (builder #${archonId})`
+      : `archon #${archonId}`;
+    const reasonText = (typeof reason === 'string' && reason.trim().length > 0)
+      ? reason.trim()
+      : 'no reason given';
+    const notesMd =
+      `${tag} released by ${actor}: ${reasonText} ` +
+      `Original claim by builder #${ownerId} for task #${taskId} "${title}".`;
+
+    await client.query(
+      `UPDATE claims SET released_at = now(), outcome = 'abandoned' WHERE id = $1`,
+      [id]
+    );
+    await client.query(
+      `UPDATE tasks
+          SET status = 'ready',
+              needs_rebase = false,
+              needs_rebase_reason = NULL,
+              needs_rebase_at = NULL,
+              updated_at = now()
+        WHERE id = $1`,
+      [taskId]
+    );
+    // session_logs row carries the original builder_id (whose session this
+    // was) PLUS the tagged notes_md identifying the acting Archon. The
+    // sweeper writes the same way — "the session belongs to the builder,
+    // the release was decided by someone else."
+    await sealSessionLog(client, {
+      builderId: ownerId, taskId, claimId: id, startedAt: claimedAt,
+      outcome: 'abandoned', notesMd,
+    });
+    return {
+      claim_id: id,
+      task_id: taskId,
+      original_builder_id: ownerId,
+      task_title: title,
+      notes_md: notesMd,
+    };
+  });
+}
+
+// Manual confirm: completed → confirmed without going through resolveClaim
+// again. Awards credits if the task carries a reward and credits haven't
+// already been awarded. For human override of failed auto-verification.
+
+async function confirmTask({ taskId, builderId }, deps = {}) {
+  // #538 test seam: a caller-supplied pool is honored ONLY under NODE_ENV==='test'
+  // so a regression test can drive the txn with a SQL-aware fakeClient (same
+  // pattern as decideOverrideRequest / override_attribution.mjs). Production
+  // callers omit deps → module pool.
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  return withTx(async (client) => {
+    // #661: credit the builder who actually DID the work — the task's claim
+    // holder — never the confirming Archon. The /tasks/:id/confirm route is
+    // archon-only and passes req.builder.id (the confirmer); before this fix
+    // both the credit_log row AND tasks.shipped_by were attributed to that
+    // Archon when they manual-confirmed someone else's completed task (live
+    // repro 2026-06-04: Xenos's #660 credit landed on builder #1). The claim
+    // holder is the builder on the most-recent claims row for the task — for a
+    // 'completed' task that is the builder whose 'shipped' resolve drove it
+    // there. Fall back to the confirmer only if the task has no claim at all (a
+    // degenerate state, e.g. status set directly via SQL) so a legitimate
+    // confirm is never refused. Mirrors the #538 fix on the override path.
+    const creditedBuilderId = (await mostRecentClaimHolderId(client, taskId)) ?? builderId;
+
+    const { rows } = await client.query(
+      `UPDATE tasks
+          SET status = 'confirmed',
+              shipped_by = COALESCE(shipped_by, $2),
+              updated_at = now()
+        WHERE id = $1 AND status = 'completed'
+        RETURNING id, title, credits_reward, kind`,
+      [taskId, creditedBuilderId]
+    );
+    if (rows.length === 0) {
+      throw Object.assign(new Error('task not in completed state'), { code: 'TASK_NOT_COMPLETED' });
+    }
+    const task = rows[0];
+
+    // Credit allocation carved to modules/economy/ (BV1.R77 / ADR 0093 §1-2):
+    // resolve the `reward` kernel port once; every credit/achievement write below
+    // runs inside this same txn. resolveOptional → undefined on a vanilla instance
+    // without economy, so every use is guarded (degrades to a best-effort no-op).
+    const reward = seams.resolveOptional('reward');
+
+    // ADR 0120 "pay on land": the per-task credit + idea-promotion bonus are NO
+    // LONGER awarded at confirm. They land at the confirmed→shipped flip
+    // (shipTask → awardLandingCredit, keyed 'task.shipped'), so a task that
+    // strands at 'confirmed' pays nothing until its code is on `main`. confirm
+    // still flips the status and attributes shipped_by to the claim holder
+    // (above); the reward waits for the land. creditsAwarded/ideaBonus stay in
+    // the return shape (0 / null at confirm) so callers/tests keep a stable
+    // contract.
+    const creditsAwarded = 0;
+    const ideaBonus = null;
+
+    // task 1679: confirmTask is the --skip-grade / grader_bypass ship path — the
+    // DOMINANT one — and until now it awarded credits but NEVER evaluated
+    // achievements (only applyGrade did), so builders shipping with grader_bypass
+    // on only ever unlocked first-claim. Reconcile the full state-based set here
+    // so every ship path unlocks achievements. The claim is already
+    // outcome='shipped' (resolveClaim ran first) and credits (above + the session
+    // reward) are reflected in builders.total_credits, so all predicates see
+    // current state. Wrapped in a SAVEPOINT: achievements are best-effort
+    // gamification and must never fail a confirm — a reconcile error rolls back
+    // only the reconcile, leaving the confirm + credit intact.
+    let justUnlocked = [];
+    if (reward && reward.reconcileBuilderAchievements) {
+      await client.query('SAVEPOINT ach_reconcile');
+      try {
+        justUnlocked = await reward.reconcileBuilderAchievements(client, creditedBuilderId, { taskId });
+        await client.query('RELEASE SAVEPOINT ach_reconcile');
+      } catch (_) {
+        await client.query('ROLLBACK TO SAVEPOINT ach_reconcile');
+        justUnlocked = [];
+      }
+    }
+
+    // #704: thetes graduation is NOT evaluated here — it fires at SHIP time
+    // (shipTask), keyed on 3 successfully SHIPPED tasks, not at confirm.
+
+    return { taskId, taskTitle: task.title, taskStatus: 'confirmed', creditsAwarded, ideaBonus, creditedBuilderId, justUnlocked };
+  }, { pool: activePool });
+}
+
+// abandonTask (task 987) — the terminal "retire this task" transition. The GDS
+// lifecycle had promote (backlog→ready), the claim-resolve path (active→
+// completed/ready), and confirm/ship (completed→confirmed→shipped), but NO
+// first-class way to KILL a task that is no longer relevant. The only routes to
+// status='abandoned' were offboarding a builder (offboardBuilder, which seals
+// each open claim) and a raw SQL UPDATE — so stale/moot tasks sat in 'ready' as
+// claimable noise (the box-teardown chores #819/#822/#827 and the dup tasks
+// #907/#926 that other sessions had already shipped, all retired 2026-06-13).
+// This is the missing transition.
+//
+// Guards:
+//   - already 'abandoned' → idempotent no-op (alreadyAbandoned:true) so a retry
+//                           or a double-click never errors.
+//   - 'shipped'           → CANNOT_ABANDON_SHIPPED. Shipped work is immutable
+//                           history; retiring it would corrupt the ledger and
+//                           the version_progress rollups.
+//   - an unreleased claim → TASK_HAS_ACTIVE_CLAIM. A live claim means a session
+//                           still owns the work; release it first so the abandon
+//                           can never race a ship in flight.
+// Any other status (backlog/ready/blocked/completed/confirmed) abandons. The
+// route is metic+archon-gated (ADR 0152; archon-only until then), and the abandon
+// + its reason are captured in audit_log by the writing middleware, so the
+// append-only ledger records who retired what. restoreTask (below) is the undo.
+//
+// NOTE on dependencies: abandoning a task that is listed in another task's
+// dependencies[] does NOT auto-adjust those dependents — they will simply never
+// auto-promote on this (now dead) dep. That is intentionally left to the Archon
+// (PUT/DELETE /tasks/:id/dependencies) rather than guessed at here; the stale
+// chores this was built for are dependency leaves.
+//
+// #538 test seam: a caller-supplied pool is honored ONLY under NODE_ENV==='test'
+// so a regression test can drive the txn with a SQL-aware fakeClient, same as
+// confirmTask / decideOverrideRequest. Production callers omit deps → module pool.
+
+async function abandonTask({ taskId, reason }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const client = await activePool.connect();
+  try {
+    await client.query('BEGIN');
+
+    const { rows: taskRows } = await client.query(
+      `SELECT id, title, status FROM tasks WHERE id = $1 FOR UPDATE`,
+      [taskId]
+    );
+    if (taskRows.length === 0) {
+      throw Object.assign(new Error('task not found'), { code: 'TASK_NOT_FOUND' });
+    }
+    const task = taskRows[0];
+
+    if (task.status === 'abandoned') {
+      await client.query('COMMIT');
+      return { taskId, taskTitle: task.title, taskStatus: 'abandoned', previousStatus: 'abandoned', alreadyAbandoned: true };
+    }
+    if (task.status === 'shipped') {
+      throw Object.assign(new Error('cannot abandon a shipped task'), { code: 'CANNOT_ABANDON_SHIPPED' });
+    }
+
+    const { rows: activeClaims } = await client.query(
+      `SELECT id FROM claims WHERE task_id = $1 AND released_at IS NULL LIMIT 1`,
+      [taskId]
+    );
+    if (activeClaims.length > 0) {
+      throw Object.assign(new Error('task has an active claim; release it first'), { code: 'TASK_HAS_ACTIVE_CLAIM' });
+    }
+
+    const { rows: updated } = await client.query(
+      `UPDATE tasks
+          SET status = 'abandoned',
+              value_summary = COALESCE(NULLIF($2, ''), value_summary),
+              updated_at = now()
+        WHERE id = $1
+        RETURNING id, title, status`,
+      [taskId, reason ? `Abandoned: ${reason}` : '']
+    );
+
+    await client.query('COMMIT');
+    return {
+      taskId,
+      taskTitle: updated[0].title,
+      taskStatus: 'abandoned',
+      previousStatus: task.status,
+      alreadyAbandoned: false,
+    };
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// restoreTask (ADR 0152) — the inverse of abandonTask: 'abandoned' → 'backlog'.
+// Added when abandon was re-ranked Archon→Metic+, because until then abandon was
+// one-way through the API (promote took only backlog/blocked, PATCH refuses
+// `status`), so a mis-retire could only be undone with hand-SQL on prod. Handing a
+// Metic the kill switch without an undo at the same rank would have moved the
+// owner-cleanup burden rather than removed it.
+//
+// Restores to **backlog**, not ready: the task was retired deliberately, so it
+// comes back un-workable and needs a second, explicit promote to be claimable.
+// abandonTask stamps `value_summary = 'Abandoned: <reason>'`; a restored task
+// clears exactly that stamp (and nothing else) so a live task never carries a
+// retire note into its ship card / broadcast.
+//
+// Guards: TASK_NOT_FOUND, and TASK_NOT_ABANDONED for any other status (the route
+// checks first, but the db guard makes a direct caller — a CLI, a poller — safe
+// too). Reached via POST /tasks/:id/promote; the audit_log row is written by the
+// writing middleware there, same as the abandon it reverses.
+//
+// #538 test seam: a caller-supplied pool is honored ONLY under NODE_ENV==='test'
+// (matches abandonTask/confirmTask). Production callers omit deps → module pool.
+async function restoreTask({ taskId }, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const client = await activePool.connect();
+  try {
+    await client.query('BEGIN');
+
+    const { rows: taskRows } = await client.query(
+      `SELECT id, title, status FROM tasks WHERE id = $1 FOR UPDATE`,
+      [taskId]
+    );
+    if (taskRows.length === 0) {
+      throw Object.assign(new Error('task not found'), { code: 'TASK_NOT_FOUND' });
+    }
+    const task = taskRows[0];
+    if (task.status !== 'abandoned') {
+      throw Object.assign(new Error('task is not abandoned'), { code: 'TASK_NOT_ABANDONED' });
+    }
+
+    const { rows: updated } = await client.query(
+      `UPDATE tasks
+          SET status = 'backlog',
+              value_summary = CASE WHEN value_summary LIKE 'Abandoned: %' THEN NULL ELSE value_summary END,
+              updated_at = now()
+        WHERE id = $1
+        RETURNING id, title, status`,
+      [taskId]
+    );
+
+    await client.query('COMMIT');
+    return {
+      taskId,
+      taskTitle: updated[0].title,
+      taskStatus: 'backlog',
+      previousStatus: 'abandoned',
+    };
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+module.exports = {
+  abandonTask,
+  confirmTask,
+  flagTaskNeedsRebase,
+  getActiveClaimsForBuilderWithStale,
+  getBuildersRoster,
+  getClaimPublishedSha,
+  listConfirmedTasksForReconcile,
+  needsRebaseTasksForBuilder,
+  releaseClaimOnBehalf,
+  resolveClaim,
+  restoreTask,
+  setClaimPublishedSha,
+  shipTask,
+};