@bongos/core 1.19.1063 → 1.19.1065

package/modules/hall-ui/records/approval-queue.md

@@ -0,0 +1,32 @@
+# The Approval queue — a glass panel on /studio, the applied page before and after (task 1004323)
+
+**BV2.TW12 (goal 1000095; [ADR 0341](../../../docs/adr/0341-the-page-is-the-unit-of-tweak-mode.md) D7, D11).** Built 1:1 on the Approval queue dialog of the owner-approved master design [`docs/design/mocks/tweak-mode/Main.dc.html`](../../../docs/design/mocks/tweak-mode/README.md): the queue position ("approval queue · 1 of 2"), the page name and "· landing · N lines rewritten, applied", the before/after pills, close, the applied page on its light frame, "approve and ship", "send it back" (a one-line note and "send"), "highlighted: the words you changed", and the approved and sent-back lines.
+
+Files: `approval-queue-lib.js` (the pure rules, `window.OTBApprovalQueueLib`, node-require-safe: every word the panel says, the render pick, the note floor), `approval-queue.js` (the panel, `window.OTBApprovalQueue.mount`) and `approval-queue.css` (the artboard's inline styles, one rule per element). The studio loads all three and mounts the panel behind a quick action (`#studio-approvals`, "Approval queue", "2 pages applied, waiting for you").
+
+## A component, so TW16 places it without rebuilding it
+
+`OTBApprovalQueue.mount({ api, apiBase, writes: { approve, sendBack }, onCount })` returns `{ open, close, refresh, count }`. The panel appends its own overlay to `body`, reads `GET /copy-desk/approvals` and `GET /tasks/:id/visuals`, and writes ONLY through the `writes` it is handed. The studio hands it `WRITE_ROUTES.approve` and `WRITE_ROUTES.sendBack` from its own allowlist, so the studio's no-live-CMS test still names every write the room can make. **TW16 (the lofi home) keeps the three files as they are:** it calls `mount` with the same two writes and turns its own "Approval queue" quick action into `open()`, with `onCount` feeding the action's detail line.
+
+## The page is a picture of the applied branch
+
+The frame shows the renders `/tweak` attached (TW11's named slots, `before|after-desktop|phone-light|dark`), never a page rebuilt from the batch (ADR 0341 builder pick 9, which keeps ADR 0233's "nothing renders a task description as product copy" true). Only server-minted `task-visuals` URLs are put in a `src`. A missing view falls back to the other colour mode, then the other device, and says what it shows. With no render at all, approve is disabled (there is nothing to approve from) and send-back stays. On a phone (760px and under) the phone render is the default.
+
+**A word cannot be highlighted inside an image**, so the changed lines stand beside the render (under it on a phone): the section in mono, the new words in the artboard's accent mark (after) or the old words unmarked (before), "was:" / "becomes:" under each, and a line the applier refused says why ("not applied: the page no longer shows it"). The hint "highlighted: the words you changed" points at that list.
+
+## Where it differs from the artboard, and what forced it
+
+- **The page is an image of the real page**, not the artboard's hand-drawn light landing page: ADR 0341 pick 9 and the task. So the highlight is on the list beside it, not on the words in the page.
+- **A second switch, desktop · phone and light · dark**, sits above the lines: the task says the eight renders fill the view switch. The header keeps the artboard's before/after pills and close exactly.
+- **The page frame is 300px narrower** to make room for the lines.
+- **The header counts refused lines** ("· 1 not applied"), which the artboard's sample never had: ADR 0341 D4, a refused line is shown to the artist at approval.
+- **After a decision, "open <next page>"** sits beside the outcome line when another page waits; the artboard names the next page and stops.
+- **The scrim is .94 over the light hall and .88 on a phone** (the artboard's .42 over the dark room otherwise): at .42 over a light page, or through the full-screen phone glass, the grey words fall below the AA floor.
+- **A viewer who may not decide** (neither the author nor an artist) reads the queue with one sentence in place of the two buttons, the studio's `studio-verdict__sealed` precedent.
+- **Not on the artboard at all:** the phone layout, light mode, the empty queue ("Nothing waiting"), the could-not-read line, the refusal line (the server's `what_this_means`), and the studio door itself (the artboard's 72px quick-action row, in the hall's tokens; the night room is TW16's).
+
+The overlay root is `.aq-overlay` and its palette is its own token tier (`tests/hall_audit.mjs` `LITERAL_EXEMPT`), the tweak editor's precedent: glass over the night studio in both modes, so it cannot spend the hall's mode-flipping tier or its `--scrim`.
+
+## The proof
+
+`studio.states.json` renders six panel states (approvals, approvals-before, approvals-phone, approvals-note, approved, sent-back) beside the studio's own. Populated, against the hall-preview harness (`node scripts/hall-preview/server.js --port 4634 --fixture-me`), which answers the queue from `copy-desk__approvals.json` (built by the real `composeApprovals`), the renders from `tasks__visuals.json`, and the two decisions from its CANNED WRITES. `HALL_PREVIEW_VISUALS=<dir>` makes the harness serve real images by the fixture's names (the review sheet used TW11's real renders of landing:index). All clean at 1440, 390 and 320, dark and light. Behaviour: `tests/hall_approval_queue.mjs` (the real panel in a vm over the real composer's answer) and `tests/copy_desk_page_approve.mjs` (the routes and the lifecycle port, whole path).

package/modules/lifecycle/db-grade.js

@@ -15,6 +15,81 @@ const { pool, withTx } = api;
 const seams = api;
 const { logGradeAttempt } = require('./db-analytics.js');
 const { mostRecentClaimHolderId } = require('./db-shared.js');
+const tweakHold = require('./page-tweak-hold.js');
+
+// promoteToConfirmed — completed -> confirmed, and the grade-time rewards that
+// go with it: the net-negative bonus, the ship achievements and the achievement
+// reconcile. Runs inside the CALLER's transaction, on its client, after the task
+// row is locked. Two callers: applyGrade (an ordinary pass) and approveHeldTweak
+// (task 1004323 / BV2.TW12, ADR 0341 D7), which performs for a page tweak the
+// promotion its pass was held from. One body, so an approved page is promoted
+// and rewarded exactly as any passed grade is, and the two cannot drift.
+//
+//   diffStats       the ship's diff_stats (the grade's signals carry them)
+//   committedFiles  the ship's committed paths, or null (touches[] then)
+//   reward          the resolved `reward` port
+//
+// Returns { netNegativeBonus, justUnlocked }.
+async function promoteToConfirmed(client, { taskId, creditedBuilderId, diffStats = null, committedFiles = null, reward }) {
+  await client.query(
+    `UPDATE tasks
+        SET status = 'confirmed',
+            shipped_by = COALESCE(shipped_by, $2),
+            updated_at = now()
+      WHERE id = $1 AND status = 'completed'`,
+    [taskId, creditedBuilderId]
+  );
+
+  // V3.R93 (#354): reward simplification. A ship whose diff removed more
+  // lines than it added earns a small flat bonus, written as its own
+  // credit_log row (reason='ship.net_negative') with a self-describing
+  // description. Idempotent on (task_id, reason) so a re-grade is a no-op.
+  // diff_stats arrives via the grade's signals (ship.js decorates it).
+  //
+  // Awarded BEFORE the achievement evaluators so the Subtractor achievement
+  // (which counts the builder's net-negative ships) sees the current ship's
+  // bonus row in this same transaction.
+  const nn = await reward.awardNetNegativeBonus(
+    client, creditedBuilderId, taskId, diffStats
+  );
+  const netNegativeBonus = nn.bonus;
+  const subtractorUnlocks = nn.justUnlocked;
+
+  // ADR 0120 "pay on land": the per-task credit + idea-promotion bonus are
+  // NO LONGER awarded at grader-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`.
+  // The net-negative (simplification) bonus above STAYS here — it derives
+  // from grade-time diff_stats that only exist at grade time, so it cannot
+  // move to shipTask (and is outside ADR 0120's two named reward writes).
+  // creditsAwarded/creditsRaw/creditsMultiplier/ideaBonus stay 0/null at
+  // confirm for a stable return contract; the credit lands at ship. The
+  // credit-crossing achievement evaluator (evaluateAfterCreditAward) moves
+  // with the credit to shipTask's reconcile; here we still fire the
+  // ship/subtractor unlocks that DON'T depend on the per-task credit.
+  const shipUnlocks = await reward.evaluateAfterShip(client, creditedBuilderId, taskId, committedFiles);
+  let justUnlocked = [...subtractorUnlocks, ...shipUnlocks];
+
+  // task 1679: state-based safety net. The granular evaluators above are
+  // boundary-/path-sensitive — breaking-the-100c-bar only fires when a
+  // per-task confirm credit crosses 100 (the session cost-plus reward never
+  // hits it), and streaks key off current_streak. reconcile re-checks every
+  // achievement against current state and unlocks any straggler. It is
+  // idempotent: anything the granular calls just unlocked is visible in this
+  // txn, so reconcile's alreadyUnlocked guard skips it (no dup awards).
+  // SAVEPOINT-wrapped so it can never fail the grade-confirm.
+  if (reward && reward.reconcileBuilderAchievements) {
+    await client.query('SAVEPOINT ach_reconcile');
+    try {
+      const reconciled = await reward.reconcileBuilderAchievements(client, creditedBuilderId, { taskId });
+      await client.query('RELEASE SAVEPOINT ach_reconcile');
+      if (reconciled.length) justUnlocked = [...justUnlocked, ...reconciled];
+    } catch (_) {
+      await client.query('ROLLBACK TO SAVEPOINT ach_reconcile');
+    }
+  }
+  return { netNegativeBonus, justUnlocked };
+}
 
 // applyGrade — V3.R18 (#209). Writes the subagent grader result to task_grades
 // and, if the grade passed, promotes completed→confirmed + awards credits.
@@ -124,7 +199,6 @@ async function applyGrade({ taskId, builderId, gradeResult, committedFiles = nul
     let creditsMultiplier = 1.0;
     let ideaBonus = null; // { ideaBonusAwarded, bonusBuilderId, ideaId } | null
     let netNegativeBonus = 0;
-    let subtractorUnlocks = [];
     let justUnlocked = [];
     // Credit allocation + gamification carved to modules/economy/ (BV1.R77 / ADR
     // 0093 §1-2): resolve the `reward` kernel port ONCE; every credit/achievement
@@ -132,69 +206,29 @@ async function applyGrade({ taskId, builderId, gradeResult, committedFiles = nul
     // state-machine SQL (FOR UPDATE, task_grades upsert, UPDATE tasks status,
     // claim-holder lookup, logGradeAttempt) stays here in the lifecycle.
     const reward = seams.resolveOptional('reward');
+
+    // THE HOLD (ADR 0341 D7; task 1004322 / BV2.TW11). A page tweak whose grade
+    // passes WAITS at completed for its artist: the grade row above is written,
+    // and the promotion below is withheld. TW12's approve performs it. Asked only
+    // on a pass at completed, and false for every task whose source is not
+    // exactly 'page-tweak', so every other grade takes the unchanged path below.
+    let held = false;
     if (gradeResult.passed && task.status === 'completed') {
-      await client.query(
-        `UPDATE tasks
-            SET status = 'confirmed',
-                shipped_by = COALESCE(shipped_by, $2),
-                updated_at = now()
-          WHERE id = $1 AND status = 'completed'`,
-        [taskId, creditedBuilderId]
-      );
+      const { rows: srcRows } = await client.query(`SELECT source FROM tasks WHERE id = $1`, [taskId]);
+      held = tweakHold.isPageTweak(srcRows[0] || null);
+    }
+    if (gradeResult.passed && task.status === 'completed' && !held) {
+      const promoted = await promoteToConfirmed(client, {
+        taskId, creditedBuilderId, diffStats: gradeResult.signals?.diff_stats, committedFiles, reward,
+      });
       finalStatus = 'confirmed';
-
-      // V3.R93 (#354): reward simplification. A ship whose diff removed more
-      // lines than it added earns a small flat bonus, written as its own
-      // credit_log row (reason='ship.net_negative') with a self-describing
-      // description. Idempotent on (task_id, reason) so a re-grade is a no-op.
-      // diff_stats arrives via gradeResult.signals (ship.js decorates it).
-      //
-      // Awarded BEFORE the achievement evaluators so the Subtractor achievement
-      // (which counts the builder's net-negative ships) sees the current ship's
-      // bonus row in this same transaction.
-      const nn = await reward.awardNetNegativeBonus(
-        client, creditedBuilderId, taskId, gradeResult.signals?.diff_stats
-      );
-      netNegativeBonus = nn.bonus;
-      subtractorUnlocks = nn.justUnlocked;
-
-      // ADR 0120 "pay on land": the per-task credit + idea-promotion bonus are
-      // NO LONGER awarded at grader-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`.
-      // The net-negative (simplification) bonus above STAYS here — it derives
-      // from grade-time diff_stats that only exist at grade time, so it cannot
-      // move to shipTask (and is outside ADR 0120's two named reward writes).
-      // creditsAwarded/creditsRaw/creditsMultiplier/ideaBonus stay 0/null at
-      // confirm for a stable return contract; the credit lands at ship. The
-      // credit-crossing achievement evaluator (evaluateAfterCreditAward) moves
-      // with the credit to shipTask's reconcile; here we still fire the
-      // ship/subtractor unlocks that DON'T depend on the per-task credit.
-      const shipUnlocks = await reward.evaluateAfterShip(client, creditedBuilderId, taskId, committedFiles);
-      justUnlocked = [...subtractorUnlocks, ...shipUnlocks];
-
-      // task 1679: state-based safety net. The granular evaluators above are
-      // boundary-/path-sensitive — breaking-the-100c-bar only fires when a
-      // per-task confirm credit crosses 100 (the session cost-plus reward never
-      // hits it), and streaks key off current_streak. reconcile re-checks every
-      // achievement against current state and unlocks any straggler. It is
-      // idempotent: anything the granular calls just unlocked is visible in this
-      // txn, so reconcile's alreadyUnlocked guard skips it (no dup awards).
-      // SAVEPOINT-wrapped so it can never fail the grade-confirm.
-      if (reward && reward.reconcileBuilderAchievements) {
-        await client.query('SAVEPOINT ach_reconcile');
-        try {
-          const reconciled = await reward.reconcileBuilderAchievements(client, creditedBuilderId, { taskId });
-          await client.query('RELEASE SAVEPOINT ach_reconcile');
-          if (reconciled.length) justUnlocked = [...justUnlocked, ...reconciled];
-        } catch (_) {
-          await client.query('ROLLBACK TO SAVEPOINT ach_reconcile');
-        }
-      }
+      netNegativeBonus = promoted.netNegativeBonus;
+      justUnlocked = promoted.justUnlocked;
     }
     // !passed → task_grades row written above; task stays at completed; no
     // credits, no achievements. Builder can manual-confirm via /confirm if the
     // grade was wrong.
+    // held → the same row, the same completed; the pass is recorded and waits.
 
     return {
       taskId,
@@ -207,6 +241,9 @@ async function applyGrade({ taskId, builderId, gradeResult, committedFiles = nul
       ideaBonus, // V3.R27 (#247): { ideaBonusAwarded, bonusBuilderId, ideaId } | null
       netNegativeBonus,
       advanceToMerge: finalStatus === 'confirmed',
+      // task 1004322: true only for a page tweak whose pass is waiting for its
+      // artist. ship.js reads it to publish the branch without landing it.
+      held,
       justUnlocked,
       grade: {
         score: gradeResult.score,
@@ -230,4 +267,5 @@ async function applyGrade({ taskId, builderId, gradeResult, committedFiles = nul
 
 module.exports = {
   applyGrade,
+  promoteToConfirmed,
 };

package/modules/lifecycle/github-pr-close.js

@@ -0,0 +1,41 @@
+// modules/lifecycle/github-pr-close.js — close an open PR without merging it
+// (task 1004323 / BV2.TW12, ADR 0341 D7).
+//
+// The Approval queue's send-back returns a page tweak to the /tweak queue, and
+// the applied branch's PR must not sit open to be merged by anything that sweeps
+// green PRs. Same server credential and the same PATCH as github-push.js
+// recheckPullRequest's close half, never reopened here. Its own file because
+// github-push.js sits at the 1,500-line ratchet; it reuses that file's token and
+// headers rather than a second copy of either.
+
+'use strict';
+
+const githubPush = require('./github-push');
+const { repoInfo } = require('../../src/module-api');
+
+function fail(code, extra = {}) {
+  return Object.assign(new Error(code), { code, ...extra });
+}
+
+// closePullRequest({ number }, deps) -> { closed: true, number }
+// deps: token / repoInfo / fetchImpl, the github-push test seams.
+async function closePullRequest({ number }, deps = {}) {
+  const token = await githubPush.resolveToken(deps);
+  if (!token) throw fail('PUSH_UNCONFIGURED');
+  if (!Number.isInteger(number) || number < 1) throw fail('BAD_PR');
+  const info = deps.repoInfo || repoInfo.loadRepoInfo();
+  if (!info || info.error) throw fail('NO_REPO_INFO');
+  const doFetch = deps.fetchImpl || fetch;
+  const res = await doFetch(`https://api.github.com/repos/${info.owner}/${info.repo}/pulls/${number}`, {
+    method: 'PATCH',
+    headers: { ...githubPush.ghHeaders(token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ state: 'closed' }),
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '');
+    throw fail('PR_PATCH_FAILED', { status: res.status, detail: githubPush.scrubCredential(detail).slice(0, 200) });
+  }
+  return { closed: true, number };
+}
+
+module.exports = { closePullRequest };

package/modules/lifecycle/github-push.js

@@ -1392,7 +1392,9 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 // `reopened` event carrying full PR context. Stays inside the App's existing
 // `pull_requests:write` — no new permission (the deterministic Actions rerun API would
 // need `actions:write`, deliberately not granted; see blocker 37).
-async function recheckPullRequest({ number }, deps = {}) {
+// `arm: false` (task 1004323): reopen WITHOUT re-arming, for a page tweak held for its
+// artist (ADR 0341 D7); `heldReason` becomes the auto_merge_reason.
+async function recheckPullRequest({ number, arm = true, heldReason = null }, deps = {}) {
   const token = await resolveToken(deps);
   if (!token) throw err('PUSH_UNCONFIGURED');
   if (!Number.isInteger(number) || number < 1) throw err('BAD_PR');
@@ -1426,7 +1428,8 @@ async function recheckPullRequest({ number }, deps = {}) {
   let autoMerge = false;
   let autoMergeReason = null;
   try {
-    if (reopened && reopened.node_id) {
+    if (!arm) autoMergeReason = heldReason || 'auto-merge was not re-armed (held)';
+    else if (reopened && reopened.node_id) {
       // The DETAILED variant: the boolean façade discarded the cause here, and no
       // response body carried it either — the quietest of the four (task 1003511).
       const armed = await enableAutoMergeDetailed(

package/modules/lifecycle/lifecycle.js

@@ -27,6 +27,7 @@ const mingle = require('./mingle');
 const pageTweakReads = require('./page-tweak-reads');
 const pageTweakClaim = require('./page-tweak-claim');
 const pageTweakWrite = require('./page-tweak-write');
+const pageTweakApprove = require('./page-tweak-approve');
 
 module.exports = {
   // --- retired doorway leaks (ADR 0093 §3) ---------------------------------
@@ -126,6 +127,17 @@ module.exports = {
   // updateTaskDescription and releaseClaim; see modules/lifecycle/page-tweak-write.js.
   updateHeldTaskDescription: (...a) => pageTweakWrite.updateHeldTaskDescription(...a),
   submitPageTweak: (...a) => pageTweakWrite.submitPageTweak(...a),
+  // The Approval queue's two decisions (task 1004323 / BV2.TW12, ADR 0341 D7,
+  // D11): approve a page tweak held for its artist (completed -> confirmed with
+  // the grade-time rewards its pass skipped, then the server lands it), or send
+  // it back (a sent-back block, the claim released, the grade row dropped, the
+  // PR closed, the round back to ready). Only the author or an artist decides.
+  // See modules/lifecycle/page-tweak-approve.js.
+  approveHeldTweak: (...a) => pageTweakApprove.approveHeldTweak(...a),
+  sendBackHeldTweak: (...a) => pageTweakApprove.sendBackHeldTweak(...a),
+  // A builder's crafts (help-requests' reader, from builders.preferred_disciplines),
+  // so the queue read can say whether the caller may decide before they try.
+  builderCrafts: (...a) => helpRequests.craftsForBuilder(...a),
   listVersions: (...a) => db.listVersions(...a),
   versionProgress: (...a) => db.versionProgress(...a),
   recentShippedTasks: (...a) => db.recentShippedTasks(...a),

package/modules/lifecycle/migrations/lifecycle_013_task_visual_slots.sql

@@ -0,0 +1,52 @@
+-- lifecycle_013_task_visual_slots.sql — a task can carry NAMED visuals, not only
+-- the one (task 1004322 / BV2.TW11, goal 1000095; ADR 0341 D7 and its builder
+-- pick 9).
+--
+-- WHY. core_223 gave a task ONE optional image (tasks.visual_url + visual_alt),
+-- the picture beside its value summary. A page tweak needs eight: the applied
+-- page before and after, on desktop and on a phone, in light and in dark. The
+-- Approval queue (TW12) shows the artist exactly those renders, images of the
+-- applied branch, never a page built from the batch, which is what keeps ADR
+-- 0233's "nothing renders a task description as product copy" true. One column
+-- cannot hold eight pictures, and eight columns would be a schema for one
+-- feature, so a visual gets a NAME and a row.
+--
+-- THE SINGLE VISUAL IS UNTOUCHED. tasks.visual_url stays the ship-time picture
+-- every existing reader renders (the hall, the status feed); a slot is a
+-- separate, named picture a reader asks for by name. Nothing here moves,
+-- copies or backfills the existing column.
+--
+-- A MODULE TABLE, because ADR 0083 lets a module migration create only its own
+-- lifecycle_-namespaced tables; it references the core tasks table the way
+-- lifecycle_010 does, and never alters it.
+--
+-- THE SAME AUDIENCE AS THE ONE VISUAL. A slot's file is stored and served by the
+-- existing task-visuals store (task-<id>-<hex>.<ext>, GET /task-visuals/:name),
+-- whose serve route derives who may see an image from the TASK it names. So a
+-- slot adds no privacy axis, exactly as core_223 promised of the column.
+--
+-- PORTABLE and replay-safe: IF NOT EXISTS throughout, no instance data.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS lifecycle_task_visual_slots (
+  task_id    bigint NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+
+  -- The slot's name: lowercase words joined by dashes, such as
+  -- 'after-phone-dark'. The vocabulary a page tweak uses is declared once in
+  -- modules/lifecycle/task-visuals.js (TWEAK_RENDER_SLOTS); the column checks only
+  -- the SHAPE, so a later feature can name its own slots without a migration.
+  slot       text   NOT NULL CHECK (slot ~ '^[a-z0-9]+(-[a-z0-9]+){0,5}$' AND length(slot) <= 48),
+
+  -- The served URL (/api/bongos/task-visuals/<file>), minted by the store.
+  visual_url text   NOT NULL,
+  visual_alt text,
+
+  updated_at timestamptz NOT NULL DEFAULT now(),
+
+  -- One picture per (task, slot): attaching a slot again REPLACES it, and the
+  -- route unlinks the superseded file.
+  PRIMARY KEY (task_id, slot)
+);
+
+COMMIT;

package/modules/lifecycle/page-tweak-approve.js

@@ -0,0 +1,242 @@
+// modules/lifecycle/page-tweak-approve.js — the two decisions of the Approval
+// queue: approve a held page tweak so it lands, or send it back to the /tweak
+// queue with a note (task 1004323 / BV2.TW12, ADR 0341 D7 and D11).
+//
+// On the `lifecycle` port because they move `tasks.status`, and the lifecycle
+// owns the state machine; copy-desk calls them through the port and never
+// writes a status itself (ADR 0341 D7). What the sent-back block SAYS is
+// copy-desk's (modules/copy-desk/pages.js, its one writer) and is handed in as
+// a function; the transaction, the hold check and the authority are here.
+//
+// THE HOLD THEY RELEASE. A page tweak whose grade passes waits at `completed`
+// (page-tweak-hold.js, applyGrade): its branch and PR are published, not armed.
+// Both decisions are refused (`not_waiting`) unless the round is exactly that:
+// source 'page-tweak', status 'completed', and a strict passed grade. So a round
+// still being applied, one already landing, or an ordinary task cannot be moved
+// through here.
+//
+// WHO DECIDES (ADR 0341 D7, builder pick 3): the round's author (the builder of
+// its latest WEB claim, the D10 payee rule, read from `claims`, never the
+// request), or any other builder whose crafts include artist (help-requests'
+// own reader), so an absent author does not strand a page. The project owner's
+// escape hatch is the existing override-request path (confirmTask is not held),
+// recorded and audit-logged there. Everyone else is refused `not_an_artist`.
+//
+// APPROVE performs the promotion the grade withheld, through the SAME body
+// applyGrade runs (db-grade.promoteToConfirmed): completed -> confirmed, the
+// net-negative bonus from the grade's own diff_stats, the ship achievements and
+// the reconcile, all credited to the applier (the task's most recent claim
+// holder, applyGrade's rule). Then the server lands it as it lands any
+// confirmed task: after the commit it nudges the PR's merge once (mergeIfGreen,
+// best-effort), and the publish reconciler's sweep merges it otherwise. Nothing
+// here arms or forces anything GitHub's own gate refuses.
+//
+// SEND-BACK appends the page-tweak-sent-back block, releases any claim still
+// open on the round (the applier's CLI claim is normally released by its ship
+// already), DELETES the round's grade row and returns the task to `ready`, so
+// the round reads `submitted` again: back in the /tweak queue. After the commit
+// it closes the unmerged PR (best-effort; a ready task's PR is never swept).
+//
+// WHY THE GRADE ROW GOES. task_grades keeps one row per task, the latest. Left
+// in place, the re-applied round would reach `completed` at its next ship with
+// the OLD pass still on it, and read as waiting for the artist, approvable,
+// before its new work was graded; ship.js would also take that stale pass as a
+// held pass and re-publish instead of grading (ship-flow's hold check). The
+// attempt stays in the append-only grade-attempts log.
+//
+// Outcomes are returned, not thrown, so the route maps each to a named answer:
+//   approved | sent_back
+//   not_found        no such task
+//   wrong_source     not a page tweak
+//   not_waiting      not held for its artist (status and grade named)
+//   not_an_artist    the caller is neither the author nor an artist
+//   builder_inactive
+//   refused          copy-desk's compose refused (its refusal passed back)
+
+'use strict';
+
+const api = require('../../src/module-api');
+const hold = require('./page-tweak-hold');
+const helpRequests = require('./help-requests');
+const githubPush = require('./github-push');
+const prClose = require('./github-pr-close');
+
+// The GitHub reads and writes the two decisions make, resolved at call time so a
+// test's stub of either file bites. A test hands its own as deps.push.
+const PUSH = Object.freeze({
+  isConfigured: () => githubPush.isConfigured(),
+  findTaskPullRequest: (a) => githubPush.findTaskPullRequest(a),
+  mergeIfGreen: (a) => githubPush.mergeIfGreen(a),
+  closePullRequest: (a) => prClose.closePullRequest(a),
+});
+const { mostRecentClaimHolderId } = require('./db-shared.js');
+const { promoteToConfirmed } = require('./db-grade.js');
+
+const log = api.logger('lifecycle');
+
+function activePoolFor(deps) {
+  return (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : api.pool;
+}
+
+// Lock the round, check it is held for its artist, and check the caller may
+// decide it. Returns { task, grade, authorId } or an outcome.
+async function lockWaitingRound(client, { taskId, builderId }) {
+  const { rows } = await client.query(
+    `SELECT id, status, title, description, source, source_ref, version_id, goal_id, touches
+       FROM tasks WHERE id = $1 FOR UPDATE`,
+    [taskId]
+  );
+  const task = rows[0];
+  if (!task) return { outcome: 'not_found' };
+  if (!hold.isPageTweak(task)) return { outcome: 'wrong_source', task };
+  const { rows: g } = await client.query('SELECT passed, signals FROM task_grades WHERE task_id = $1', [taskId]);
+  const grade = g[0] || null;
+  if (!hold.isHeldForArtist(task, grade ? grade.passed : null)) {
+    return { outcome: 'not_waiting', task, grade_passed: grade ? grade.passed : null };
+  }
+  const { rows: b } = await client.query(
+    'SELECT id, status, github_login, display_name FROM builders WHERE id = $1', [builderId]
+  );
+  if (!b[0] || b[0].status === 'inactive') return { outcome: 'builder_inactive', task };
+  const { rows: w } = await client.query(
+    `SELECT builder_id FROM claims
+      WHERE task_id = $1 AND worktree_name IS NULL AND creator_session_id IS NULL
+      ORDER BY claimed_at DESC, id DESC LIMIT 1`,
+    [taskId]
+  );
+  const authorId = w[0] ? String(w[0].builder_id) : null;
+  if (authorId !== String(builderId)) {
+    const crafts = await helpRequests.craftsForBuilder(builderId, { pool: client });
+    if (!crafts.includes('artist')) return { outcome: 'not_an_artist', task, author_id: authorId };
+  }
+  return { task, grade, authorId };
+}
+
+async function inTx(deps, body) {
+  const client = await activePoolFor(deps).connect();
+  try {
+    await client.query('BEGIN');
+    const out = await body(client);
+    await client.query(out && out.commit ? 'COMMIT' : 'ROLLBACK');
+    return out;
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// The round's PR, from the server's own GitHub reads (the reconciler's
+// adopt-by-task lookup). Null when there is no credential or no such PR.
+async function roundPullRequest(taskId, push) {
+  if (!push.isConfigured()) return null;
+  return push.findTaskPullRequest({ taskId: Number(taskId) });
+}
+
+// After an approve commits: one merge nudge, the reconciler's own first step.
+// Best-effort and never thrown: the task is confirmed either way, and the
+// sweep lands it when this misses.
+async function nudgeLand(taskId, push = PUSH) {
+  try {
+    const pr = await roundPullRequest(taskId, push);
+    if (!pr) return { nudged: false, reason: 'no_pr_found', lands_via: 'reconciler' };
+    if (pr.merged) return { nudged: false, merged: true, pr_number: pr.pr_number };
+    if (pr.pr_state !== 'open') return { nudged: false, reason: `pr_${pr.pr_state || 'unknown'}`, pr_number: pr.pr_number, lands_via: 'reconciler' };
+    const m = await push.mergeIfGreen({ branch: pr.branch });
+    return { nudged: true, merged: !!(m && m.merged), merged_now: !!(m && m.merged_now), reason: (m && m.reason) || null, pr_number: pr.pr_number, lands_via: m && m.merged ? 'merged' : 'reconciler' };
+  } catch (err) {
+    log.warn({ task_id: String(taskId), err: err && err.message }, 'approve: merge nudge failed (the reconciler lands it)');
+    return { nudged: false, reason: 'nudge_failed', lands_via: 'reconciler' };
+  }
+}
+
+// After a send-back commits: close the applied branch's unmerged PR.
+async function closeRoundPr(taskId, push = PUSH) {
+  try {
+    const pr = await roundPullRequest(taskId, push);
+    if (!pr) return { closed: false, reason: 'no_pr_found' };
+    if (pr.merged) return { closed: false, reason: 'already_merged', pr_number: pr.pr_number };
+    if (pr.pr_state !== 'open') return { closed: false, reason: `pr_${pr.pr_state || 'unknown'}`, pr_number: pr.pr_number };
+    await push.closePullRequest({ number: Number(pr.pr_number) });
+    return { closed: true, pr_number: pr.pr_number };
+  } catch (err) {
+    log.warn({ task_id: String(taskId), err: err && err.message }, 'send-back: closing the PR failed (it stays un-armed)');
+    return { closed: false, reason: 'close_failed' };
+  }
+}
+
+// approveHeldTweak({ taskId, builderId }, deps)
+//
+// deps.pool (NODE_ENV=test only), deps.reward (the resolved reward port),
+// deps.push (github-push, for the post-commit nudge).
+async function approveHeldTweak({ taskId, builderId }, deps = {}) {
+  const reward = deps.reward || api.resolveOptional('reward');
+  const out = await inTx(deps, async (client) => {
+    const held = await lockWaitingRound(client, { taskId, builderId });
+    if (held.outcome) return held;
+    const creditedBuilderId = (await mostRecentClaimHolderId(client, taskId)) ?? builderId;
+    const signals = (held.grade && held.grade.signals) || {};
+    const promoted = await promoteToConfirmed(client, {
+      taskId,
+      creditedBuilderId,
+      diffStats: signals.diff_stats || null,
+      committedFiles: null,
+      reward,
+    });
+    return {
+      commit: true,
+      outcome: 'approved',
+      task: { id: String(held.task.id), status: 'confirmed', source_ref: held.task.source_ref, title: held.task.title },
+      advanceToMerge: true,
+      author_id: held.authorId,
+      credited_builder_id: creditedBuilderId == null ? null : String(creditedBuilderId),
+      net_negative_bonus: promoted.netNegativeBonus,
+      just_unlocked: promoted.justUnlocked,
+    };
+  });
+  delete out.commit;
+  if (out.outcome !== 'approved') return out;
+  out.land = await nudgeLand(taskId, deps.push || PUSH);
+  return out;
+}
+
+// sendBackHeldTweak({ taskId, builderId, compose }, deps)
+//
+//   compose(task) -> { ok: true, description } | { ok: false, code, detail }
+//
+// copy-desk's compose appends the page-tweak-sent-back block ({ at, by, note });
+// the note's floor is checked there and at the route.
+async function sendBackHeldTweak({ taskId, builderId, compose }, deps = {}) {
+  const out = await inTx(deps, async (client) => {
+    const held = await lockWaitingRound(client, { taskId, builderId });
+    if (held.outcome) return held;
+    const r = compose(held.task);
+    if (!r || !r.ok) return { outcome: 'refused', refusal: r, task: held.task };
+    const { rows } = await client.query(
+      `UPDATE tasks SET description = $2, status = 'ready', updated_at = now() WHERE id = $1
+       RETURNING id, status, description, source_ref, updated_at`,
+      [taskId, r.description]
+    );
+    const { rows: released } = await client.query(
+      `UPDATE claims SET released_at = now(), outcome = 'partial'
+        WHERE task_id = $1 AND released_at IS NULL
+        RETURNING id`,
+      [taskId]
+    );
+    await client.query('DELETE FROM task_grades WHERE task_id = $1', [taskId]);
+    return {
+      commit: true,
+      outcome: 'sent_back',
+      task: rows[0],
+      author_id: held.authorId,
+      released_claim_ids: released.map((x) => String(x.id)),
+    };
+  });
+  delete out.commit;
+  if (out.outcome !== 'sent_back') return out;
+  out.pr = await closeRoundPr(taskId, deps.push || PUSH);
+  return out;
+}
+
+module.exports = { approveHeldTweak, sendBackHeldTweak };