@bongos/core 1.23.21 → 1.24.1

package/scripts/bongos/seed-tasks.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+// scripts/bongos/seed-tasks.js — file one planning session's tasks from a JSON spec (task 1004979).
+//
+// WHY. Every planning session used to copy a whole seed SCRIPT (seed-bv1-profiles-tasks.js,
+// seed-bongos-v1-idea-routing-tasks.js, seed-bv2-ideator-surface-tasks.js) and edit its TASKS
+// array: about 700 lines of three near-identical HTTP loops, each with its own drift — one
+// tallied replays twice, one never verified its criterion links, one never promoted anything.
+// The only part that differs per session is DATA, so this is the one seeder and a session now
+// writes a spec. The three old scripts were replaced by their specs, and
+// tests/seed_tasks.mjs proves this filer sends exactly the same writes they did.
+//
+// THE SPEC (see scripts/bongos/seed-tasks.example.json):
+//   version_id, goal_id          where every task lands
+//   source_ref_prefix            each task's source_ref is `<prefix>-<ref>`; POST /tasks is
+//                                idempotent on (source, source_ref), so a re-run replays
+//   source                       default 'planning-session'
+//   tasks[]                      { ref, title, description, kind, discipline, priority,
+//                                  criterion_ids, deps?, est_minutes?, touches?, requires_rank?,
+//                                  manual_degree?, credits_reward?, security_sensitive? }
+//   promote[]                    refs to POST /tasks/:id/promote after the edges are wired
+//   links[]                      { method, path, body } follow-up writes (an idea marked
+//                                promoted, a meta task moved into the goal); a body value
+//                                { "$task": "R11" } becomes that ref's task id, and a link
+//                                whose ref did not land is skipped
+//   verify_criteria              default true — see below
+//   allow_positional_criteria    default false — only the historical bv1-profiles spec sets it
+//
+// THE ORDER is the old scripts' order: baseline the goal, create every task, wire every
+// dependency edge, promote, follow-up links, then verify. Verification is
+// seed-verify-criteria.js's contract (task 1003076, task 1004668): baseline BEFORE the first
+// write, tally only the criterion links this run CREATED (a replay is already in the baseline),
+// and exit 1 loudly on any mismatch.
+//
+// Positional "Cn" criterion refs are refused at validation. They rank over the whole VERSION's
+// criteria and mislinked all 15 tasks of goal 1000071 (learning 1000188); the server now
+// refuses them on a multi-goal version too, but a spec should fail before its first write.
+//
+// Usage:
+//   node scripts/bongos/seed-tasks.js <spec.json> --dry-run   # validate + print the plan; files nothing
+//   node scripts/bongos/seed-tasks.js <spec.json>             # file it
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { sleep } = require('../../src/sleep');
+const { baselineSeedCriteria, expectedCriterionCounts, verifySeedCriteriaLinks } = require('./seed-verify-criteria');
+
+// Optional per-task fields that POST /tasks accepts and a spec may carry through as-is.
+const OPTIONAL_FIELDS = ['est_minutes', 'touches', 'requires_rank', 'manual_degree', 'credits_reward', 'security_sensitive'];
+const POSITIONAL_CRITERION = /^C\d+$/;
+
+/** Every problem with a spec, as plain sentences. An empty list means it can be filed. */
+function validateSpec(spec) {
+  const errs = [];
+  if (!spec || typeof spec !== 'object') return ['the spec is not a JSON object'];
+  if (typeof spec.version_id !== 'string' || !spec.version_id) errs.push('version_id must be a non-empty string');
+  if (!Number.isInteger(Number(spec.goal_id)) || Number(spec.goal_id) <= 0) errs.push('goal_id must be a positive integer');
+  if (typeof spec.source_ref_prefix !== 'string' || !spec.source_ref_prefix) errs.push('source_ref_prefix must be a non-empty string');
+  if (!Array.isArray(spec.tasks) || !spec.tasks.length) { errs.push('tasks must be a non-empty array'); return errs; }
+  const refs = new Set();
+  for (const [i, t] of spec.tasks.entries()) {
+    const at = `tasks[${i}]${t && t.ref ? ` (${t.ref})` : ''}`;
+    if (!t || typeof t.ref !== 'string' || !t.ref) { errs.push(`${at}: ref must be a non-empty string`); continue; }
+    if (refs.has(t.ref)) errs.push(`${at}: duplicate ref`);
+    refs.add(t.ref);
+    for (const f of ['title', 'description', 'kind', 'discipline']) {
+      if (typeof t[f] !== 'string' || !t[f]) errs.push(`${at}: ${f} must be a non-empty string`);
+    }
+    if (!Number.isInteger(t.priority)) errs.push(`${at}: priority must be an integer`);
+    if (!Array.isArray(t.criterion_ids) || !t.criterion_ids.length) errs.push(`${at}: criterion_ids must name at least one criterion`);
+    else if (!spec.allow_positional_criteria) {
+      for (const c of t.criterion_ids) {
+        if (POSITIONAL_CRITERION.test(String(c))) errs.push(`${at}: "${c}" is a positional criterion ref — use the criterion_id slug (learning 1000188)`);
+      }
+    }
+    if (t.deps !== undefined && !Array.isArray(t.deps)) errs.push(`${at}: deps must be an array of refs`);
+  }
+  for (const t of spec.tasks) {
+    for (const d of (t && Array.isArray(t.deps) ? t.deps : [])) {
+      if (d === t.ref) errs.push(`${t.ref}: depends on itself`);
+      else if (!refs.has(d)) errs.push(`${t.ref}: depends on unknown ref ${d}`);
+    }
+  }
+  for (const r of spec.promote || []) if (!refs.has(r)) errs.push(`promote: unknown ref ${r}`);
+  for (const [i, l] of (spec.links || []).entries()) {
+    if (!l || !['PATCH', 'POST'].includes(l.method)) errs.push(`links[${i}]: method must be PATCH or POST`);
+    if (!l || typeof l.path !== 'string' || !l.path.startsWith('/')) errs.push(`links[${i}]: path must start with /`);
+    for (const r of linkRefs(l && l.body)) if (!refs.has(r)) errs.push(`links[${i}]: unknown ref ${r}`);
+  }
+  return errs;
+}
+
+function linkRefs(body) {
+  return Object.values(body || {}).filter((v) => v && typeof v === 'object' && typeof v.$task === 'string').map((v) => v.$task);
+}
+
+/** The POST /tasks body for one spec task — the field order the old scripts sent. */
+function taskBody(spec, t) {
+  const body = {
+    version_id: spec.version_id, goal_id: Number(spec.goal_id), title: t.title, description: t.description,
+    kind: t.kind, discipline: t.discipline, priority: t.priority,
+  };
+  for (const f of OPTIONAL_FIELDS) if (t[f] !== undefined) body[f] = t[f];
+  body.criterion_ids = t.criterion_ids;
+  body.source = spec.source || 'planning-session';
+  body.source_ref = `${spec.source_ref_prefix}-${t.ref}`;
+  return body;
+}
+
+/** The dry run: what would be filed, in order. Sends nothing. */
+function describePlan(spec, log = console.log) {
+  log(`DRY RUN — would seed ${spec.tasks.length} task(s) into goal ${spec.goal_id} (${spec.version_id}), source_ref ${spec.source_ref_prefix}-<ref>:`);
+  for (const t of spec.tasks) {
+    const deps = t.deps && t.deps.length ? ` after ${t.deps.join(',')}` : '';
+    log(`  ${t.ref}  ${t.kind}/${t.discipline} P${t.priority} [${t.criterion_ids.join(',')}]${deps}  ${t.title}`);
+  }
+  if ((spec.promote || []).length) log(`  then promote: ${spec.promote.join(', ')}`);
+  for (const l of spec.links || []) log(`  then ${l.method} ${l.path}`);
+  log(`  then ${spec.verify_criteria === false ? 'skip' : 'verify'} the criterion links.`);
+  log('Nothing was filed.');
+}
+
+/**
+ * File a spec. `api(method, path, body)` resolves to { status, ok, json } for a path under
+ * /api/bongos; it is injected so the equivalence test can point this at a fake server.
+ */
+async function seedTasks(spec, { api, log = console.log, exit = process.exit } = {}) {
+  const goalId = Number(spec.goal_id);
+  const verify = spec.verify_criteria !== false;
+  const fetchGoal = (gid) => api('GET', `/goals/${gid}`);
+  const baseline = verify ? await baselineSeedCriteria({ goalId, fetchGoal, log, exit }) : null;
+
+  const idByRef = {};
+  const criterionIdListsPerTask = [];
+  let created = 0, replayed = 0, failed = 0;
+  log(`Seeding ${spec.tasks.length} task(s) into goal ${goalId} (${spec.version_id})…`);
+  for (const t of spec.tasks) {
+    const r = await api('POST', '/tasks', taskBody(spec, t));
+    const task = r.ok && r.json ? (r.json.task || r.json) : null;
+    if (!task || task.id == null) { failed++; log(`  ${t.ref}: FAILED ${r.status} ${JSON.stringify(r.json).slice(0, 300)}`); continue; }
+    idByRef[t.ref] = task.id;
+    if (r.json.idempotent) replayed++;
+    else { created++; criterionIdListsPerTask.push(t.criterion_ids); }
+    log(`  ${t.ref} → task ${task.id}${r.json.idempotent ? ' (already there)' : ''}  ${t.title.slice(0, 80)}`);
+  }
+
+  log('Wiring dependencies…');
+  let edges = 0;
+  for (const t of spec.tasks) {
+    if (!t.deps || !t.deps.length) continue;
+    const id = idByRef[t.ref];
+    const depIds = t.deps.map((d) => idByRef[d]).filter((x) => x != null);
+    if (id == null || depIds.length !== t.deps.length) { log(`  ${t.ref}: a task in this edge did not land — skipped`); continue; }
+    const r = await api('POST', `/tasks/${id}/dependencies`, { depends_on_task_ids: depIds });
+    if (!r.ok) { failed++; log(`  ${t.ref}: dependency FAILED ${r.status} ${JSON.stringify(r.json).slice(0, 180)}`); continue; }
+    edges += (r.json && r.json.added) || depIds.length;
+    log(`  ${t.ref} depends on ${t.deps.join(',')}`);
+  }
+
+  if ((spec.promote || []).length) log('Promoting…');
+  for (const ref of spec.promote || []) {
+    const id = idByRef[ref];
+    if (id == null) continue;
+    const r = await api('POST', `/tasks/${id}/promote`, {});
+    log(`  ${ref} (task ${id}): ${r.ok ? 'ready' : 'promote note ' + JSON.stringify(r.json).slice(0, 120)}`);
+  }
+
+  if ((spec.links || []).length) log('Follow-up links…');
+  for (const l of spec.links || []) {
+    const missing = linkRefs(l.body).filter((ref) => idByRef[ref] == null);
+    if (missing.length) { log(`  ${l.method} ${l.path}: skipped, ${missing.join(',')} did not land`); continue; }
+    const body = {};
+    for (const [k, v] of Object.entries(l.body || {})) body[k] = v && typeof v === 'object' && typeof v.$task === 'string' ? Number(idByRef[v.$task]) : v;
+    const r = await api(l.method, l.path, body);
+    log(`  ${l.method} ${l.path}: ${r.ok ? 'OK' : 'note ' + JSON.stringify(r.json).slice(0, 160)}`);
+  }
+
+  log(`\nDONE. created=${created} replayed=${replayed} failed=${failed} depEdges=${edges}.`);
+  log('ref→id: ' + JSON.stringify(idByRef));
+  if (verify) {
+    log('Verifying criterion links against the plan…');
+    await verifySeedCriteriaLinks({ goalId, expectedCounts: expectedCriterionCounts(criterionIdListsPerTask), baseline, fetchGoal, log, exit });
+  }
+  return { idByRef, created, replayed, failed };
+}
+
+/** The real transport: the CLI session, a base throttle, and the 429 back-off every seed needs. */
+function cliApi({ throttleMs = 400 } = {}) {
+  const { apiCall } = require('./cli-lib');
+  return async function api(method, p, body, tries = 0) {
+    await sleep(throttleMs);
+    const r = await apiCall(method, `/api/bongos${p}`, body || null);
+    const json = r.data || {};
+    if (r.status === 429 && tries < 8) {
+      const wait = ((json.error && json.error.details && json.error.details.retry_after_seconds) || 30) + 1;
+      console.log(`  …rate-limited, waiting ${wait}s`);
+      await sleep(wait * 1000);
+      return api(method, p, body, tries + 1);
+    }
+    return { status: r.status, ok: r.ok, json };
+  };
+}
+
+async function main(argv) {
+  const file = argv.find((a) => !a.startsWith('--'));
+  if (!file) { console.error('usage: node scripts/bongos/seed-tasks.js <spec.json> [--dry-run]'); return 2; }
+  let spec;
+  try { spec = JSON.parse(fs.readFileSync(path.resolve(file), 'utf8')); }
+  catch (e) { console.error(`seed-tasks: cannot read ${file}: ${e.message}`); return 2; }
+  const errs = validateSpec(spec);
+  if (errs.length) { console.error(`seed-tasks: ${file} is not a valid spec:\n  ${errs.join('\n  ')}`); return 1; }
+  if (argv.includes('--dry-run')) { describePlan(spec); return 0; }
+  const out = await seedTasks(spec, { api: cliApi() });
+  return out.failed ? 1 : 0;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (e) => { console.error(e); process.exitCode = 1; });
+}
+
+module.exports = { validateSpec, taskBody, describePlan, seedTasks, cliApi, main };

package/scripts/bongos/seed-verify-criteria.js

@@ -27,8 +27,7 @@
 // names. A seed is resumable (POST /tasks is idempotent on source_ref and replays
 // an existing task with `idempotent: true`), and a replayed task's links are
 // already inside the baseline — tally it again and a correct re-run expects them
-// twice. So a baselined seed skips replays when it tallies (see
-// seed-bv2-ideator-surface-tasks.js).
+// twice. So a baselined seed skips replays when it tallies (see seed-tasks.js).
 
 // countsByCriterion — { criterion_id: linked_tasks } from GET /goals/:id rows.
 function countsByCriterion(criteriaRows) {

package/scripts/bongos/ship-finish.js

@@ -217,6 +217,8 @@ async function finishShip({ taskId, summary, advanceToMerge, skipMerge, postGrad
   // task 1719: pass the reconciled status so a just-landed ship shows SHIPPED (and
   // writes no breadcrumb), not the stale pre-merge 'confirmed'.
   await printCompletionCard({ taskId, postGradeStatus: landedStatus, card, usage, land });
+  // task 1004956: a landed strand needs no fixer — clear whoever held its lease.
+  if (landedStatus === 'shipped') require('./strand-lease.js').clearOnExit(taskId);
   // task 932: reconcile the working tree — ONLY on a successful land. A
   // grade-failed ship stays at 'completed'; leave that tree untouched so the
   // builder can fix findings + re-ship.

package/scripts/bongos/ship-resume.js

@@ -186,6 +186,8 @@ async function resumeMerge(taskId, { summary, skipMerge, force, task, dbOnly = f
   try {
     const t = await (await cliClient()).tasks.getTasksId({ id: taskId });
     const status = (t.ok && t.data && t.data.task) ? t.data.task.status : 'shipped';
+    // task 1004956: a landed strand needs no fixer — clear whoever held its lease.
+    if (t.ok && status === 'shipped') require('./strand-lease.js').clearOnExit(taskId);
     await printCompletionCard({
       taskId, postGradeStatus: status, usage, land,
       card: { title: task?.title, valueSummary: effSummary, notes: '', creditsAwarded: null },

package/scripts/bongos/strand-lease.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/bongos/strand-lease.js — ONE session fixes a stuck ship; the others are told who
+// has it (task 1004956).
+//
+// THE GAP. A builder runs several sessions at once, one worktree each. When a ship strands,
+// every session start prints the same strand note, and that note told every one of them to
+// fix it. So N sessions ran /strand-fix on the SAME task: duplicated paid work, sessions
+// colliding on one branch, and the owner watching all of them recommend the same fix
+// (owner, 2026-10-29: "maybe all sessions point to one session to fix").
+//
+// THE LEASE. Fixing a strand takes a short-lived mark: "this worktree is on task N until T".
+// /strand-fix takes it first and stops if another live session holds it; the strand note and
+// the claim refusal name the holder, so every other session carries on with its own work.
+//
+// WHY A FILE IN THE COMMON GIT DIR, NOT A SERVER ROW. Every session a builder runs on one
+// machine is a worktree of one repo, and they all share one common git dir — the same reason
+// merge-lock.js keeps the auto-merge mutex there. That is exactly the set that collides, it
+// needs no migration and no route, and it still works when the API is unreachable. A session
+// on another machine cannot see it; that machine's sessions share their own.
+//
+// KEYED ON THE WORKTREE, NOT THE BUILDER. One builder, many sessions, is the normal case here,
+// so a builder-keyed lease would make every one of their sessions look like the owner. The
+// claim gate keys on the worktree for the same reason (routes/claims.js,
+// gateOneActiveClaimPerSession).
+//
+// EXPIRY IS THE CRASH PATH. A session that just stops never releases. The lease lives
+// LEASE_TTL_MS from its last take; /strand-fix re-takes it at each step to renew it, so a live
+// fixer keeps it and a dead one loses it on its own. Landing (ship.js) and releasing
+// (release.js) clear it at once.
+//
+// Usage:
+//   node scripts/bongos/strand-lease.js take <task-id>      # take or renew; exit 3 if another session holds it
+//   node scripts/bongos/strand-lease.js release <task-id>   # drop this worktree's lease
+//   node scripts/bongos/strand-lease.js show [<task-id>]    # who holds what
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LEASE_TTL_MS = 45 * 60 * 1000;
+const HELD_EXIT = 3;
+const DIR_NAME = 'otb-strand-leases';
+
+const safeId = (v) => (/^\d{1,19}$/.test(String(v)) ? String(v) : null);
+
+// One spelling per folder. Windows can hand the cwd in 8.3 short form (GMK1_P~1), so the same
+// folder reached two ways would otherwise read as two holders.
+function canonical(p) {
+  try { return fs.realpathSync.native(p); } catch { return path.resolve(p); }
+}
+
+// Find this checkout WITHOUT spawning git. strand-watch --line calls this on the SessionStart
+// path, whose cost was cut from 8.2 s by caching (task 1004928), so no subprocess belongs here.
+// Walk up to `.git`: a directory is a main checkout (it IS the common dir); a file is a linked
+// worktree, `gitdir: <common>/worktrees/<name>`, whose `commondir` file names the common dir.
+// Memoised per cwd for the life of the process.
+const located = new Map();
+function locate(cwd) {
+  const start = path.resolve(cwd);
+  if (located.has(start)) return located.get(start);
+  let found = null;
+  for (let d = start; ; d = path.dirname(d)) {
+    const g = path.join(d, '.git');
+    let st = null;
+    try { st = fs.statSync(g); } catch { /* keep walking */ }
+    if (st && st.isDirectory()) { found = { top: d, common: g }; break; }
+    if (st && st.isFile()) {
+      const m = /^gitdir:\s*(.+?)\s*$/m.exec(fs.readFileSync(g, 'utf8'));
+      if (!m) break;
+      const gitdir = path.resolve(d, m[1]);
+      let common = gitdir;
+      try { common = path.resolve(gitdir, fs.readFileSync(path.join(gitdir, 'commondir'), 'utf8').trim()); } catch { /* not a linked worktree's gitdir */ }
+      found = { top: d, common };
+      break;
+    }
+    if (path.dirname(d) === d) break;
+  }
+  if (found) found = { top: canonical(found.top), common: canonical(found.common) };
+  located.set(start, found);
+  return found;
+}
+
+// The lease folder: shared by every worktree of this repo. Null when not in a git checkout.
+function leaseDir({ cwd = process.cwd() } = {}) {
+  const at = locate(cwd);
+  return at ? path.join(at.common, DIR_NAME) : null;
+}
+
+// Who "this session" is: its worktree. The label is what other sessions are shown.
+function currentHolder({ cwd = process.cwd() } = {}) {
+  const at = locate(cwd);
+  if (!at) return null;
+  return { holder: at.top.toLowerCase().replace(/\\/g, '/'), label: path.basename(at.top) };
+}
+
+function leaseFile(dir, taskId) { return path.join(dir, `${taskId}.json`); }
+
+function readRaw(dir, taskId) {
+  try { return JSON.parse(fs.readFileSync(leaseFile(dir, taskId), 'utf8')); } catch { return null; }
+}
+
+function isLive(lease, now) {
+  return !!lease && Number.isFinite(lease.expires_at) && lease.expires_at > now;
+}
+
+// The live lease on a task, or null (none, expired, or unreadable).
+function read(taskId, { dir, now = Date.now() } = {}) {
+  const id = safeId(taskId);
+  if (!id || !dir) return null;
+  const l = readRaw(dir, id);
+  return isLive(l, now) ? l : null;
+}
+
+// A temp file older than this was left by a process that died mid-write; nothing will rename it.
+const TMP_STALE_MS = 60 * 1000;
+function sweepTmp(dir, now) {
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { return; }
+  for (const n of names) {
+    if (!n.endsWith('.tmp')) continue;
+    const f = path.join(dir, n);
+    try { if (now - fs.statSync(f).mtimeMs > TMP_STALE_MS) fs.unlinkSync(f); } catch { /* raced */ }
+  }
+}
+
+// Take or renew. { ok: true, lease, renewed } when this holder has it now; { ok: false, lease }
+// naming the live holder otherwise. A FREE lease is created exclusively (flag 'wx'), so of two
+// sessions taking it at the same instant the filesystem lets exactly one in. Renewing, and taking
+// over an EXPIRED lease, replace the file atomically (temp + rename) and read it back: a takeover
+// race can only happen after the holder has already been gone for the whole TTL.
+function take(taskId, { dir, holder, label, now = Date.now(), ttlMs = LEASE_TTL_MS } = {}) {
+  const id = safeId(taskId);
+  if (!id) throw new Error(`not a task id: ${taskId}`);
+  if (!dir || !holder) throw new Error('no lease folder or holder (not inside a git checkout?)');
+  fs.mkdirSync(dir, { recursive: true });
+  sweepTmp(dir, now);
+  let cur = readRaw(dir, id);
+  const lease = (taken) => ({
+    task_id: id, holder, label: label || path.basename(holder), taken_at: taken, expires_at: now + ttlMs,
+  });
+  if (!cur) {
+    try {
+      const fresh = lease(now);
+      fs.writeFileSync(leaseFile(dir, id), JSON.stringify(fresh), { flag: 'wx' });
+      return { ok: true, lease: fresh, renewed: false };
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      cur = readRaw(dir, id); // another session got there first
+    }
+  }
+  if (isLive(cur, now) && cur.holder !== holder) return { ok: false, lease: cur };
+  const renewed = isLive(cur, now) && cur.holder === holder;
+  const tmp = `${leaseFile(dir, id)}.${process.pid}.${now}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(lease(renewed ? cur.taken_at : now)));
+    fs.renameSync(tmp, leaseFile(dir, id));
+  } finally {
+    try { fs.unlinkSync(tmp); } catch { /* renamed away: the normal case */ }
+  }
+  const back = readRaw(dir, id);
+  if (!back || back.holder !== holder) return { ok: false, lease: back };
+  return { ok: true, lease: back, renewed };
+}
+
+// Drop the lease if this holder has it (or always, with force — landing clears it whoever
+// held it). Returns true when a lease file was removed.
+function release(taskId, { dir, holder, force = false } = {}) {
+  const id = safeId(taskId);
+  if (!id || !dir) return false;
+  const cur = readRaw(dir, id);
+  if (!cur) return false;
+  if (!force && cur.holder !== holder) return false;
+  try { fs.unlinkSync(leaseFile(dir, id)); return true; } catch { return false; }
+}
+
+// Every live lease, oldest first.
+function liveLeases({ dir, now = Date.now() } = {}) {
+  if (!dir) return [];
+  let names;
+  try { names = fs.readdirSync(dir); } catch { return []; }
+  return names
+    .map((n) => /^(\d{1,19})\.json$/.exec(n))
+    .filter(Boolean)
+    .map((m) => readRaw(dir, m[1]))
+    .filter((l) => isLive(l, now))
+    .sort((a, b) => a.taken_at - b.taken_at);
+}
+
+function minutes(ms) { return `${Math.max(1, Math.round(ms / 60000))}m`; }
+
+// "session <label> (on it 12m)" — the words every other session is shown. The label is a
+// worktree folder name, so it is safe to inject (no builder-authored text).
+function describe(lease, now = Date.now()) {
+  const label = String(lease.label || '').replace(/[^\w.-]/g, '').slice(0, 80) || 'another session';
+  return `session ${label} (on it ${minutes(now - lease.taken_at)})`;
+}
+
+// The clause the strand note appends: the strands OTHER sessions hold, so this one leaves
+// them alone. Null when nobody else holds one.
+function othersClause(leases, holder, now = Date.now()) {
+  const others = (leases || []).filter((l) => l.holder !== holder);
+  if (!others.length) return null;
+  const list = others.map((l) => `task ${safeId(l.task_id)} by ${describe(l, now)}`).join('; ');
+  return `Already being fixed: ${list}. Leave ${others.length === 1 ? 'that one' : 'those'} to that session and carry on with your own work.`;
+}
+
+// Drop the lease for a task that has left the strand board (landed or released). Never throws:
+// a cleanup that fails must not fail the ship or release it rides on.
+function clearOnExit(taskId, { cwd = process.cwd() } = {}) {
+  try { return release(taskId, { dir: leaseDir({ cwd }), force: true }); } catch { return false; }
+}
+
+function main(argv = process.argv.slice(2)) {
+  const [cmd, rawId] = argv;
+  const dir = leaseDir();
+  const me = currentHolder();
+  if (!dir || !me) { console.error('strand-lease: not inside a git checkout'); return 2; }
+  if (cmd === 'take') {
+    const r = take(rawId, { dir, holder: me.holder, label: me.label });
+    if (r.ok) {
+      console.log(`strand-lease: ${r.renewed ? 'renewed' : 'took'} task ${r.lease.task_id} for this session until ${new Date(r.lease.expires_at).toISOString()}.`);
+      return 0;
+    }
+    console.log(`strand-lease: task ${safeId(rawId)} is already being fixed by ${describe(r.lease)}.`);
+    console.log('  Leave it to that session and carry on with your own work. The hold runs out on its own if that session stops.');
+    return HELD_EXIT;
+  }
+  if (cmd === 'release') {
+    console.log(release(rawId, { dir, holder: me.holder })
+      ? `strand-lease: released task ${safeId(rawId)}.`
+      : `strand-lease: this session held no lease on task ${safeId(rawId)}.`);
+    return 0;
+  }
+  if (cmd === 'show') {
+    const leases = rawId ? [read(rawId, { dir })].filter(Boolean) : liveLeases({ dir });
+    if (!leases.length) { console.log('strand-lease: nobody is fixing a stuck ship right now.'); return 0; }
+    for (const l of leases) console.log(`  task ${l.task_id}  ${describe(l)}${l.holder === me.holder ? '  ← this session' : ''}`);
+    return 0;
+  }
+  console.error('usage: node scripts/bongos/strand-lease.js take|release|show [<task-id>]');
+  return 2;
+}
+
+if (require.main === module) process.exitCode = main();
+
+module.exports = {
+  LEASE_TTL_MS, HELD_EXIT, leaseDir, currentHolder, take, release, read, liveLeases,
+  describe, othersClause, clearOnExit,
+};