@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/strand-watch.js

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/bongos/strand-watch.js — say out loud that a ship got stuck (task 1003163).
+//
+// THE GAP. Nothing watched for a stranded ship. On 2026-08-22 a manual status sweep found
+// task 1002483 parked at `completed` for THREE DAYS carrying 651 lines of tested work on a
+// local branch, task 1002792 parked two days behind it, and task 1002459 sitting at
+// `confirmed` for FOUR DAYS with no artifact anywhere. Not one of the three had produced a
+// single signal; all were found by accident.
+//
+// WHY land-watch.js IS NOT THIS (it looks like it should be). land-watch.js renders the
+// SHIPPED banner after an async CI land (task 1687). It cannot detect a strand: it reads
+// machine-local breadcrumbs that ship.js writes only at CONFIRMED-exit — so a task parked at
+// `completed` never gets one — it DROPS a breadcrumb after 30 minutes by design, and it is
+// per-machine, so a strand on a box nobody reopens is invisible forever.
+//
+// THE SIGNAL ALREADY EXISTS. This is the part worth knowing: the publish-reconciler ALREADY
+// diagnoses the worst case and already writes it down. Task 1002459 has carried
+// `needs_rebase_reason = 'strand:land_not_proven'` since 2026-08-18 — the reconciler probed
+// it, could not prove a land, gave up, and recorded exactly that. Nobody ever read the field.
+// So this module is not a detector. It is the READOUT of a diagnosis the system performs and
+// then discards, which is why it is small.
+//
+// SHAPE COPIED FROM deploy-divergence.js, deliberately. That check was written after the
+// ten-day staleness incident (blocker 1000097 / task 1002521), is wired into SessionStart in
+// .claude/settings.json, and on 2026-08-22 it reported the stale pin in the first message of
+// the session — which is how that whole day's work started. A cheap check, on a path that
+// already runs, reporting loudly, beats a monitoring subsystem that can itself silently stop.
+// So: fail-open, bounded, and SILENT when the board is clean.
+//
+// Usage:
+//   node scripts/bongos/strand-watch.js                 # human-readable report
+//   node scripts/bongos/strand-watch.js --line          # ONE line, or nothing; always exit 0
+//   node scripts/bongos/strand-watch.js --json          # machine shape
+//   node scripts/bongos/strand-watch.js --hours N       # override the `completed` threshold
+//
+// Exit codes: 0 always on --line (fail-open). Otherwise 0 clean, 1 strands found, 2 undetermined.
+
+const { apiCall, arg, hasFlag } = require('./cli-lib');
+const tweakHold = require('../../modules/lifecycle/page-tweak-hold.js');
+
+// ---- thresholds -------------------------------------------------------------
+// Reasoned, not magic. Written down because a future reader will want to retune them.
+//
+// `confirmed` means the grade PASSED and only the land is outstanding. The publish-reconciler
+// sweeps every ~5 minutes, so one hour is twelve missed sweeps — already anomalous, while
+// still leaving room for a slow CI queue or a transient GitHub failure.
+const CONFIRMED_STALE_MS = 60 * 60 * 1000;
+// `completed` means the grade did NOT pass. A builder may legitimately be mid-recovery for
+// hours (see the /grade-recover loop), so this is deliberately generous: 12 hours means the
+// strand survived a night, which no active recovery does. The three real cases were 2–3 DAYS.
+const COMPLETED_STALE_MS = 12 * 60 * 60 * 1000;
+
+// A reconciler-recorded strand needs NO threshold. The reconciler already probed every branch
+// convention, failed to prove a land, and wrote the reason down; waiting longer cannot change
+// that verdict, and task 1002459 proves the alternative is sitting for days.
+const STRAND_REASON_PREFIX = 'strand:';
+
+const WATCHED = ['completed', 'confirmed'];
+const DEFAULT_TIMEOUT_MS = 8000;
+// Page size per watched status. A queue past this would silently lose the OLDEST strands —
+// exactly the class of quiet cap this whole check exists to abolish — so a full page is
+// reported as `truncated` rather than passed off as complete. 200 is far above any healthy
+// board (the real numbers were 1 and 2).
+const PAGE_LIMIT = 200;
+
+// ---- classification (pure — this is the unit-testable core) -----------------
+
+// Task ids are numeric and reconciler reasons come from a fixed vocabulary, so both are safe
+// to print. TITLES ARE NOT, and that omission is deliberate — see the trust-boundary note on
+// `line()` below.
+const safeId = (v) => (/^\d{1,19}$/.test(String(v)) ? String(v) : null);
+const safeReason = (v) => (typeof v === 'string' && /^[a-z0-9_:.-]{1,64}$/i.test(v) ? v : null);
+
+function humanAge(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return 'unknown';
+  const h = ms / 3600000;
+  if (h < 1) return `${Math.max(1, Math.round(ms / 60000))}m`;
+  if (h < 48) return `${Math.round(h)}h`;
+  return `${Math.round(h / 24)}d`;
+}
+
+// Decide whether ONE task is a strand, and if so which shape and what fixes it. The two
+// shapes need opposite responses, which is the whole reason to distinguish them:
+//   completed -> the GRADE parked it; re-grade or fix findings (/grade-recover).
+//   confirmed -> the grade passed and the LAND is outstanding (/merge-mode is the fallback).
+// A reconciler-recorded strand is called out separately because it is terminal without a
+// human: the automated healers have already refused it.
+function classifyStrand(task, { nowMs, confirmedStaleMs = CONFIRMED_STALE_MS, completedStaleMs = COMPLETED_STALE_MS } = {}) {
+  const t = task || {};
+  const status = String(t.status || '');
+  if (!WATCHED.includes(status)) return null;
+
+  const id = safeId(t.id);
+  if (!id) return null;
+
+  const updated = Date.parse(t.updated_at || '');
+  const ageMs = Number.isFinite(updated) && Number.isFinite(nowMs) ? nowMs - updated : NaN;
+
+  const reason = safeReason(t.needs_rebase_reason);
+  const reconcilerGaveUp = status === 'confirmed'
+    && t.needs_rebase === true
+    && !!reason
+    && reason.toLowerCase().startsWith(STRAND_REASON_PREFIX);
+
+  if (reconcilerGaveUp) {
+    return {
+      id, status, ageMs, age: humanAge(ageMs), shape: 'unprovable', reason,
+      remedy: 'check whether any artifact exists at all — a confirm with no branch and nothing on main was codeless',
+    };
+  }
+
+  const limit = status === 'confirmed' ? confirmedStaleMs : completedStaleMs;
+  // An unreadable updated_at must not manufacture a strand — fail QUIET on bad data here,
+  // because this text is injected into every session and a false alarm trains people to
+  // scroll past the real one.
+  if (!Number.isFinite(ageMs) || ageMs <= limit) return null;
+
+  return status === 'confirmed'
+    ? { id, status, ageMs, age: humanAge(ageMs), shape: 'unlanded', reason: null,
+        remedy: '/merge-mode is the documented manual fallback' }
+    : { id, status, ageMs, age: humanAge(ageMs), shape: 'ungraded', reason: null,
+        remedy: '/grade-recover diagnoses which of the three shapes parked it' };
+}
+
+// Sort worst-first so a truncated line shows the most urgent: reconciler-refused, then oldest.
+const SHAPE_RANK = { unprovable: 0, unlanded: 1, ungraded: 2 };
+function rankStrands(strands) {
+  return strands.slice().sort((a, b) => {
+    const d = (SHAPE_RANK[a.shape] ?? 9) - (SHAPE_RANK[b.shape] ?? 9);
+    return d !== 0 ? d : (b.ageMs || 0) - (a.ageMs || 0);
+  });
+}
+
+// ---- the held pass (task 1004322, ADR 0341 D7) --------------------------------
+//
+// A page tweak whose grade PASSED waits at `completed` for its artist on purpose:
+// the artist approves the applied page before it lands. It is not a strand and not
+// a failed grade, and calling it one would send someone to /grade-recover a task
+// nobody should touch. The task list carries no grade, so each completed page
+// tweak's grade is read on its own (there are a handful at most; the read is
+// bounded anyway). A read that FAILS leaves the task to the ordinary
+// classification: an unknown must stay loud, never be explained away as a hold.
+const HOLD_READ_LIMIT = 25;
+
+async function heldPageTweaks(tasks, { call, withTimeout }) {
+  const candidates = tasks.filter((t) => t && t.status === 'completed' && tweakHold.isPageTweak(t) && safeId(t.id)).slice(0, HOLD_READ_LIMIT);
+  const held = new Set();
+  await Promise.all(candidates.map(async (t) => {
+    try {
+      const res = await withTimeout(call('GET', `/api/bongos/tasks/${safeId(t.id)}?include=grade`), 'page-tweak grade');
+      const body = res && (res.data || res);
+      const grade = body && body.grade;
+      if (tweakHold.isHeldForArtist(t, grade ? grade.passed : null)) held.add(String(t.id));
+    } catch { /* unknown: classified as usual */ }
+  }));
+  return held;
+}
+
+// ---- fetch ------------------------------------------------------------------
+
+async function check({ nowMs = Date.now(), timeoutMs = DEFAULT_TIMEOUT_MS, confirmedStaleMs, completedStaleMs, call = apiCall } = {}) {
+  // CONCURRENT, not sequential. This runs on the SessionStart path beside deploy-divergence,
+  // so a serial loop would double the latency the builder waits through for no reason.
+  const withTimeout = (p, label) => Promise.race([
+    p,
+    new Promise((_, rej) => setTimeout(() => rej(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs)),
+  ]).catch((e) => { throw new Error(`could not read ${label} tasks: ${e.message || e}`); });
+
+  let pages;
+  try {
+    pages = await Promise.all(WATCHED.map(async (status) => {
+      const res = await withTimeout(call('GET', `/api/bongos/tasks?status=${status}&limit=${PAGE_LIMIT}`), status);
+      const body = res && (res.data || res);
+      const tasks = body && Array.isArray(body.tasks) ? body.tasks : null;
+      if (!tasks) throw new Error(`unexpected shape from /tasks?status=${status}`);
+      return { status, tasks };
+    }));
+  } catch (e) {
+    return { undetermined: true, reason: e.message || String(e), strands: [], truncated: [] };
+  }
+
+  const strands = [];
+  const truncated = [];
+  const waiting = [];
+  const completed = (pages.find((p) => p.status === 'completed') || { tasks: [] }).tasks;
+  const held = await heldPageTweaks(completed, { call, withTimeout });
+  for (const { status, tasks } of pages) {
+    if (tasks.length >= PAGE_LIMIT) truncated.push(status);
+    for (const t of tasks) {
+      if (status === 'completed' && held.has(String(t.id))) {
+        const updated = Date.parse(t.updated_at || '');
+        const ageMs = Number.isFinite(updated) ? nowMs - updated : NaN;
+        waiting.push({ id: safeId(t.id), status, ageMs, age: humanAge(ageMs), shape: tweakHold.HOLD_STATE });
+        continue;
+      }
+      const s = classifyStrand(t, { nowMs, confirmedStaleMs, completedStaleMs });
+      if (s) strands.push(s);
+    }
+  }
+  return { undetermined: false, ok: strands.length === 0 && !truncated.length, strands: rankStrands(strands), truncated, waiting };
+}
+
+// ---- rendering --------------------------------------------------------------
+
+// ONE line for SessionStart, or null. Null IS the silence: a clean board must say nothing,
+// or the line becomes wallpaper and the real warning gets scrolled past.
+//
+// TRUST BOUNDARY — why no task titles. A task title is builder-authored free text, and this
+// string is injected into an agent's context at the start of every session. Interpolating a
+// title raw would hand anyone who can file a task a standing prompt-injection channel, which
+// is the same reasoning deploy-divergence.js applies to the /version response it reads (it
+// accepts only a strict semver for exactly this purpose). Ids and a fixed reason vocabulary
+// carry all the signal that is needed and none of the risk — the agent can GET the task.
+function line(r, { max = 3 } = {}) {
+  if (!r || r.undetermined) return null;
+  const trunc = Array.isArray(r.truncated) && r.truncated.length
+    ? ` (the ${r.truncated.join(' and ')} queue${r.truncated.length > 1 ? 's' : ''} filled a full ${PAGE_LIMIT}-row page, so older strands may be unlisted)`
+    : '';
+  if (!r.strands.length) {
+    // A full page with no strand still means coverage was capped — say so rather than imply
+    // a clean board, which is the silent-cap failure this check is against.
+    return trunc ? `Strand check could not see the whole board${trunc}. Run: node scripts/bongos/strand-watch.js` : null;
+  }
+  const shown = r.strands.slice(0, max)
+    .map((s) => `task ${s.id} (${s.status}, ${s.age}${s.reason ? `, ${s.reason}` : ''})`);
+  const more = (r.strands.length > shown.length ? ` +${r.strands.length - shown.length} more` : '') + trunc;
+  const worst = r.strands[0];
+  // Lead with what the WORST shape actually means. "work is finished but not landed" is true
+  // of a confirmed strand and false of a completed one (the grade parked that, so the work may
+  // not be finished at all) — one generic sentence for both would be wrong half the time.
+  const lead = {
+    unprovable: 'the reconciler already probed this and gave up, so it will never self-heal',
+    unlanded: 'the grade passed and only the land is outstanding',
+    ungraded: 'the grade parked this; it is not waiting on a land',
+  }[worst.shape] || 'parked mid-pipeline';
+  return `Stranded ship${r.strands.length === 1 ? '' : 's'}: ${shown.join('; ')}${more}. `
+    + `Worst: ${lead} — ${worst.remedy}. `
+    // Name the skill, not just the diagnosis: 19 of the last 30 days' session logs mention a strand,
+    // and the next claim is refused REBASE_REQUIRED until one is landed or released (task 1003548).
+    + `Run /strand-fix ${worst.id} to walk it. `
+    + 'A strand produces no signal of its own; this line is the only one.';
+}
+
+function report(r) {
+  if (!r) { console.error('strand-watch: no result'); return; }
+  if (r.undetermined) { console.error(`strand-watch: undetermined — ${r.reason}`); return; }
+  console.log('');
+  console.log('  Stranded ships');
+  console.log('  ──────────────────────────────────────────────────────────');
+  if (Array.isArray(r.truncated) && r.truncated.length) {
+    console.log(`  ! coverage capped: the ${r.truncated.join(' and ')} queue(s) returned a full ${PAGE_LIMIT}-row page,`);
+    console.log('    so strands older than the cutoff are NOT listed below.');
+  }
+  // task 1004322: named, and kept apart from the strands — nobody should recover these.
+  const waiting = Array.isArray(r.waiting) ? r.waiting : [];
+  for (const w of waiting) {
+    console.log(`  task ${w.id}  waiting for the artist (${w.age}) — a page tweak whose grade passed; not a strand, leave it`);
+  }
+  if (r.ok) {
+    console.log('  ✓ none — nothing parked at completed or confirmed past its threshold.');
+    console.log('');
+    return;
+  }
+  for (const s of r.strands) {
+    console.log(`  task ${s.id}  ${s.status.padEnd(9)} ${String(s.age).padStart(4)}  ${s.shape}${s.reason ? ` (${s.reason})` : ''}`);
+    console.log(`      ${s.remedy}`);
+  }
+  console.log('');
+  console.log('  "completed" means the grade parked it. "confirmed" means it passed and the');
+  console.log('  land never finished. Neither state produces a signal on its own.');
+  console.log('');
+}
+
+async function main() {
+  const hours = Number(arg('--hours'));
+  const opts = Number.isFinite(hours) && hours > 0 ? { completedStaleMs: hours * 3600000 } : {};
+
+  // --line: the SessionStart shape. FAIL-OPEN — a strand is context for the agent, and an
+  // unreachable API is nothing at all; neither is a failure of the session this rides into.
+  // Note it sets exitCode and RETURNS rather than calling process.exit: an explicit exit here
+  // races libuv's teardown of the request socket and aborts the process on Windows/Node 24
+  // (the documented `UV_HANDLE_CLOSING` assertion — see cli-lib's cliExit note and
+  // deploy-divergence's identical comment).
+  if (hasFlag('--line')) {
+    try {
+      // SHARED ACROSS CONCURRENT SESSION STARTS (task 1003689). Four sessions opened
+      // within three seconds — one worktree per claim, the normal pattern here — used
+      // to make this same call four times and ALL of them timed out, which produces no
+      // line at all. Silence from a truth-teller is indistinguishable from 'nothing to
+      // report', so the brief was lost without a symptom. The first session to ask now
+      // answers for the rest.
+      const { cached } = require('./probe-cache.js');
+      const { value: one } = await cached('strand-watch-line', async () => line(await check(opts)));
+      if (one) console.log(one);
+    } catch { /* no session, offline, unreadable — all silence */ }
+    process.exitCode = 0;
+    return;
+  }
+
+  const r = await check(opts);
+  if (hasFlag('--json')) console.log(JSON.stringify(r, null, 2));
+  else report(r);
+  process.exitCode = r.undetermined ? 2 : (r.ok ? 0 : 1);
+}
+
+if (require.main === module) {
+  main().catch((e) => { console.error('strand-watch: failed —', e.message || e); process.exit(2); });
+}
+
+module.exports = {
+  check, line, report, classifyStrand, rankStrands, humanAge,
+  CONFIRMED_STALE_MS, COMPLETED_STALE_MS, STRAND_REASON_PREFIX, WATCHED, PAGE_LIMIT,
+};

package/scripts/bongos/stranded-rows.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+// scripts/bongos/stranded-rows.js — a task whose work already landed, still sitting in
+// `ready`/`backlog` (task 1003775).
+//
+// THE FAILURE. Three tasks closed in one 2026-08-20 session needed no work at all:
+// the fix was already in main. That was 3 of 8 tasks in one sweep, and every one was
+// found by a human reading code. The cost is not the wasted claim — it is that the
+// next builder claims it, reads the code, finds nothing to do, and has to prove a
+// negative before releasing it.
+//
+// SCOPE — ONE OF THE TWO FAILURE MODES, DELIBERATELY. Idea 1000807 named two:
+//
+//   1. STRANDED ROW — the work landed under the task's OWN id, but the row never
+//      moved off `ready`. Mechanical. This file.
+//   2. SILENT SUPERSESSION — a LATER task solved the same problem under a different
+//      id. The idea's author tried commit-message scanning for this and reports it
+//      does NOT work: a broad scan and a narrowed one (826 commits) both returned
+//      ~44 open tasks that merely MENTION an id — seeded-task commits, session logs,
+//      ADRs citing planned work. Not attempted here. It needs a human or LLM read and
+//      belongs in a review cadence, not new machinery.
+//
+// THE SIGNAL, and why it is this one. A commit says which task it DID by ending a
+// line with `(task N)`. That is narrower than "mentions N", which is the distinction
+// the idea's investigation failed on: "1002792, 1002200, 1002571" in a session-log
+// body is a comma list, not a line ending in `(task N)`.
+//
+// It reads the WHOLE message, not just the subject, and that detail is load-bearing.
+// The historical case the idea names — task 1002200 — landed on a cloud-agent branch
+// whose own commit subject never named it; the `(task 1002200)` line lives in the
+// MERGE commit's body, where GitHub echoes the branch's subject. A subject-only scan
+// misses the one case this file exists for.
+//
+// MEASURED on this repo before shipping: 877 ids are named as an authoring subject
+// across 4,784 commits, and ZERO of them are open `ready`/`backlog` rows (434 of
+// those). So today's board is clean and the signal is not merely quiet — the same
+// rule catches 1002200 when its row is treated as open.
+//
+// HOUSE RULES (the truth-teller family: strand-watch.js, stale-worktrees.js).
+// Fail OPEN — a probe never blocks a session. Silent when healthy. Prints IDS AND
+// FIXED VOCABULARY ONLY: never a commit subject or a task title, both of which are
+// builder-authored text.
+//
+// Usage:
+//   node scripts/bongos/stranded-rows.js            # human report; exit 1 if any found
+//   node scripts/bongos/stranded-rows.js --json     # { stranded: [{ id, status, sha }] }
+//   node scripts/bongos/stranded-rows.js --line     # ONE line, or nothing; always exit 0
+
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+const MAIN_REF = 'origin/main';
+// A record separator no commit message can contain: the word is wrapped in U+0001
+// (START OF HEADING), a C0 control character git will not carry in a message body.
+//
+// Built from an explicit escape rather than written as a literal, because the control
+// bytes are INVISIBLE in a source listing - the first reviewer of this file read it as
+// `const SEP = 'COMMIT'` and correctly flagged that a body containing the word COMMIT
+// would split a record in half. It would; that is exactly why the sentinels are there,
+// and now you can see them. A test pins a body carrying the bare word.
+const SOH = String.fromCharCode(1);
+const SEP = `${SOH}COMMIT${SOH}`;
+
+// The authoring convention: a line whose END is `(task N)`. Anchored at end-of-line on
+// purpose — that is what distinguishes "this commit did task N" from "this commit
+// mentioned N", and the second is the noise that made the supersession half undoable.
+const AUTHORED_RE = /\(task (\d{6,7})\)\s*$/;
+
+// PURE — every task id a commit message claims to have DONE. Exported so the rule is
+// testable without a repo: a scanner that quietly stops matching reports a clean board,
+// which is indistinguishable from a healthy one.
+function authoredIds(message) {
+  const out = new Set();
+  for (const line of String(message || '').split('\n')) {
+    const m = AUTHORED_RE.exec(line.trim());
+    if (m) out.add(m[1]);
+  }
+  return out;
+}
+
+// PURE — id -> first sha that claimed it, over a whole `git log` payload.
+function scanLog(raw) {
+  const byId = new Map();
+  for (const block of String(raw || '').split(SEP)) {
+    if (!block.trim()) continue;
+    const nl = block.indexOf('\n');
+    const sha = (nl === -1 ? block : block.slice(0, nl)).trim();
+    const body = nl === -1 ? '' : block.slice(nl + 1);
+    for (const id of authoredIds(body)) if (!byId.has(id)) byId.set(id, sha);
+  }
+  return byId;
+}
+
+// PURE — the stranded set. `openRows` are { id, status }; `landed` is scanLog's map.
+// Kept separate from the IO so the decision is unit-testable with no git and no API.
+function strandedRows(openRows, landed) {
+  const out = [];
+  for (const row of openRows || []) {
+    const id = String(row && row.id);
+    if (!landed.has(id)) continue;
+    out.push({ id, status: String(row.status || ''), sha: landed.get(id).slice(0, 8) });
+  }
+  return out.sort((a, b) => Number(a.id) - Number(b.id));
+}
+
+function readLog(cwd) {
+  return execFileSync('git', ['log', MAIN_REF, `--pretty=${SEP}%H%n%B`], {
+    cwd, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'],
+  });
+}
+
+// Both statuses that mean "nobody has started this". A row already `active` or
+// `completed` is someone's live work, not a strand.
+const OPEN_STATUSES = ['ready', 'backlog'];
+
+// A hard stop so a paging bug cannot loop forever. Reaching it means the board grew
+// past what one scan should walk, which is a fact worth SAYING rather than silently
+// truncating — a detector that quietly stops early reports a clean board.
+const MAX_PAGES = 50;
+
+// PURE-ish — the paging walk, with `getPage` injected. Extracted and exported because
+// it was the only untested IO in this file, and off-by-one paging is exactly the kind
+// of logic that silently returns a short list (and a short list here means 'nothing is
+// stranded').
+async function pageOpenRows(getPage, { statuses = OPEN_STATUSES, pageSize = 200, maxPages = MAX_PAGES } = {}) {
+  const rows = [];
+  for (const status of statuses) {
+    let offset = 0;
+    let page = 0;
+    for (; page < maxPages; page += 1) {
+      const r = await getPage({ status, limit: pageSize, offset });
+      if (!r || !r.ok) throw new Error(`could not list ${status} tasks (${r && r.status})`);
+      const got = (r.data && r.data.tasks) || [];
+      for (const t of got) rows.push({ id: t.id, status: t.status });
+      // A SHORT page is the end of the table. Compared against the size the route
+      // actually honoured, never the size we asked for — the route clamps.
+      if (got.length < (r.limit || pageSize)) break;
+      offset += got.length;
+    }
+    if (page >= maxPages) {
+      throw new Error(`more than ${maxPages} pages of ${status} tasks — refusing to report a partial board as clean`);
+    }
+  }
+  return rows;
+}
+
+async function readOpenRows() {
+  const { cliClient } = require('./cli-lib.js');
+  const { TASK_LIST_MAX_LIMIT, buildTaskPageQuery } = require('../../modules/lifecycle/task-list-limits.js');
+  const api = await cliClient();
+  return pageOpenRows(async ({ status, limit, offset }) => {
+    const q = buildTaskPageQuery({ status, limit, offset });
+    const r = await api.tasks.getTasks({ query: q });
+    // Carry the limit the route HONOURED back to the walker, so its short-page test
+    // compares against the clamped size rather than the requested one.
+    return r && { ok: r.ok, status: r.status, data: r.data, limit: q.limit };
+  }, { pageSize: TASK_LIST_MAX_LIMIT });
+}
+
+async function scan(cwd) {
+  const landed = scanLog(readLog(cwd));
+  // The scan must not pass by finding nothing: this repo's own history is built out of
+  // these lines, so an empty map means the pattern broke.
+  if (landed.size === 0) throw new Error('no commit claims to have done any task — the pattern has drifted');
+  return { stranded: strandedRows(await readOpenRows(), landed), scanned: landed.size };
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const line = argv.includes('--line');
+  let r;
+  try {
+    r = await scan(process.cwd());
+  } catch (e) {
+    if (line) process.exit(0); // fail OPEN — a probe never blocks a session
+    console.error(`stranded-rows: undetermined — ${e.message || e}`);
+    process.exit(2);
+  }
+
+  if (argv.includes('--json')) { console.log(JSON.stringify(r, null, 2)); return; }
+  if (line) {
+    if (r.stranded.length) {
+      const ids = r.stranded.slice(0, 6).map((s) => s.id).join(', ');
+      const more = r.stranded.length > 6 ? ` +${r.stranded.length - 6} more` : '';
+      console.log(`Stranded rows: ${r.stranded.length} open task(s) whose work already landed on main (${ids}${more}). `
+        + 'Claiming one means reading the code to prove there is nothing to do. Run node scripts/bongos/stranded-rows.js.');
+    }
+    return;
+  }
+  console.log(`  Stranded rows: ${r.stranded.length} (of ${r.scanned} task id(s) named as an authoring subject on main)`);
+  for (const s of r.stranded) console.log(`    task ${s.id}  [${s.status}]  landed in ${s.sha}`);
+  if (r.stranded.length) {
+    console.log('  Each of these has a commit on main claiming to have done it. Verify, then ship or abandon the row.');
+    process.exit(1);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = { authoredIds, scanLog, strandedRows, pageOpenRows, AUTHORED_RE, SEP, OPEN_STATUSES, MAX_PAGES };

package/scripts/bongos/stray-unit-sweep.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# scripts/bongos/stray-unit-sweep.sh — find (and with --apply, stop + remove) a project's systemd
+# units that are still on the control plane although its provisioning row is torn down
+# (task 1003939, an ADR 0285 follow-up).
+#
+# WHY. On 2026-09-16 `demo.service` was RUNNING and enabled while the demo row read torn_down:
+# a torn-down project holding ~80 MB on a box whose ceiling is 15 projects, outside the count
+# the ledger keeps. The live MemAvailable floor (task 1003927) covers placement, but the memory
+# is still gone and the unit still restarts on boot. The teardown leg is the fix going forward
+# (task 1003940 added reset-failed); this is the BACKSTOP that finds what an older teardown
+# left behind, from the ledger's own list of torn-down rows, and names it so the ship note can.
+#
+# Run on the control plane as a sudoer:
+#   bash scripts/bongos/stray-unit-sweep.sh            # survey only — read-only
+#   bash scripts/bongos/stray-unit-sweep.sh --apply    # disable --now, remove the unit files, reload, reset-failed
+# Run from anywhere but an instance's own vendored core, set INSTANCE_DIR to that instance.
+#
+# Left in place on purpose, even with --apply: the project's database, its dumps under
+# /var/backups/gds, any checkout, and its Caddy block — data is precious, and the address is
+# task 1002897's to reclaim.
+set -uo pipefail
+
+APPLY=0; [ "${1:-}" = "--apply" ] && APPLY=1
+DB="${PGDATABASE:-cloudbongos}"
+ETC=/etc/systemd/system
+
+# The app account (task 1004135) — never a named person: PROVISION_APP_USER, else the owner
+# of the instance checkout, found the way address-park-sweep.sh finds it (three levels up
+# from an instance's vendored core; from anywhere else INSTANCE_DIR names it). A clone in an
+# operator's own home must not decide it. root is refused: it holds no Postgres role here.
+CORE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+case "$CORE_DIR" in */node_modules/@bongos/core) INSTANCE_DIR="${INSTANCE_DIR:-${CORE_DIR%/node_modules/@bongos/core}}" ;; esac
+[ -n "${PROVISION_APP_USER:-}${INSTANCE_DIR:-}" ] || { echo "set INSTANCE_DIR to the control plane's instance checkout (or PROVISION_APP_USER) — this sweep is not running from one"; exit 1; }
+# Owner by name: GNU stat `-c %U`, else BSD/macOS stat `-f %Su` — each refuses the other's
+# flag (task 1004170), the same lookup address-park-sweep.sh makes.
+APP_USER="${PROVISION_APP_USER:-$(stat -c %U "$INSTANCE_DIR" 2>/dev/null || stat -f %Su "$INSTANCE_DIR" 2>/dev/null)}"
+if [ "$APP_USER" = root ] || ! [[ "$APP_USER" =~ ^[a-z_][a-z0-9_-]{0,31}$ ]]; then
+  echo "cannot use '$APP_USER' as the app account — set PROVISION_APP_USER to the unprivileged account that owns ${INSTANCE_DIR:-the instance checkout}"; exit 1
+fi
+
+# The torn-down slugs, from the ledger, read as the app account (peer auth — the runner's
+# own identity; nothing here needs a superuser).
+slugs=$(sudo -n -u "$APP_USER" psql -d "$DB" -tAc "select slug from provisioning_instances where status='torn_down' order by slug" 2>/dev/null) \
+  || { echo "cannot read provisioning_instances from $DB as $APP_USER"; exit 1; }
+
+found=(); cleared=()
+echo "== torn-down rows that still have systemd units =="
+for slug in $slugs; do
+  # The slug grammar provisioning.isValidSlug enforces; anything else never reaches a command.
+  [[ "$slug" =~ ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ ]] || continue
+  units="$slug.service $slug-db-backup.service $slug-db-backup.timer"
+  loaded=$(systemctl list-units --all --no-legend $units 2>/dev/null | awk '{print ($1 == "●") ? $2 : $1}' | tr '\n' ' ')
+  files=$(for u in $units; do [ -e "$ETC/$u" ] && printf '%s ' "$u"; done)
+  [ -z "$loaded" ] && [ -z "$files" ] && continue
+  state=$(systemctl is-active "$slug.service" 2>/dev/null || true)
+  printf '  %-24s service=%-9s loaded=[%s] files=[%s]\n' "$slug" "$state" "${loaded% }" "${files% }"
+  found+=("$slug")
+  [ "$APPLY" = 1 ] || continue
+  sudo -n systemctl disable --now "$slug.service" 2>/dev/null || true
+  sudo -n systemctl disable --now "$slug-db-backup.timer" 2>/dev/null || true
+  sudo -n rm -f "$ETC/$slug.service" "$ETC/$slug-db-backup.service" "$ETC/$slug-db-backup.timer"
+  sudo -n systemctl daemon-reload
+  sudo -n systemctl reset-failed "$slug.service" "$slug-db-backup.service" 2>/dev/null || true
+  cleared+=("$slug")
+done
+
+echo "== summary =="
+echo "  stray   (${#found[@]}): ${found[*]:-none}"
+if [ "$APPLY" = 1 ]; then echo "  cleared (${#cleared[@]}): ${cleared[*]:-none}";
+else echo "  (survey only — re-run with --apply to disable, remove and reset-failed them)"; fi
+echo "  MemAvailable: $(awk '/MemAvailable/ {print int($2/1024) " MB"}' /proc/meminfo)"