@bongos/core 1.17.0

package/modules/lifecycle/goal-conflicts.js

@@ -0,0 +1,133 @@
+// modules/lifecycle/goal-conflicts.js — the PURE goal task-conflict detector
+// (task 1736). Server-side replacement for the hall Goals page's client-side
+// exact-string overlap approximation: glob-aware touches[] intersection via the
+// ONE canonical prefix-aware matcher (path-match.js, task 880 — reached through
+// the published doorway), active-claim severity, and cross-goal overlaps
+// against other open goals sharing scope_modules.
+//
+// Pure on purpose (the goal-scope-check precedent): the route fetches tasks /
+// claims / sibling goals and calls computeGoalConflicts; every branch is pinned
+// by a DB-free unit test (tests/goal_conflicts.mjs).
+//
+// Conflict = two OPEN tasks (not completed/confirmed/shipped/abandoned) whose
+// DECLARED touches[] overlap. Declared touches are ADVISORY (ADR 0049 — git
+// merge is the authoritative collision detector at land time); this detector is
+// the PLANNING-time view a goal owner/manager resolves conflicts from, so pairs
+// carry the overlap paths + a claim-aware severity, not a verdict.
+
+const api = require('../../src/module-api');
+const { matchOne } = api.pathMatch;
+
+// Terminal statuses — a task here can no longer collide (its diff has landed,
+// is landing, or never will). Mirrors the hall page's DONE_STATUSES + abandoned.
+const RESOLVED_STATUSES = new Set(['completed', 'confirmed', 'shipped', 'abandoned']);
+
+// A task participates in conflict detection only if it is open AND declares a
+// blast radius. No touches → nothing to intersect (the client-side
+// approximation skips these too; R60 goal-authored tasks always declare).
+function isOpenWithTouches(t) {
+  return t && !RESOLVED_STATUSES.has(t.status)
+    && Array.isArray(t.touches) && t.touches.length > 0;
+}
+
+// Normalize one touches[] entry for the prefix matcher: tolerate the glob tail
+// convention ('src/bongos/*', 'modules/hall-ui/**') by trimming it to the
+// directory prefix matchOne already understands. Deeper glob syntax is not in
+// the touches vocabulary (path-match.js is the canonical matcher, and it is
+// prefix-based); an entry that trims to nothing is skipped.
+function normalizeEntry(e) {
+  return String(e || '').trim().replace(/\/?\*+$/, '');
+}
+
+// The overlapping entries between two touches[] sets — the pairwise application
+// of matchOne in both directions, keeping the MORE SPECIFIC side of each hit
+// (matches what the hall renders: 'src/bongos/db.js', not the 'src/bongos/' that
+// covers it). Returns a deduped, sorted list.
+function overlappingPaths(a, b) {
+  const hits = new Set();
+  for (const rawA of a || []) {
+    const na = normalizeEntry(rawA);
+    if (!na) continue;
+    for (const rawB of b || []) {
+      const nb = normalizeEntry(rawB);
+      if (!nb) continue;
+      if (matchOne(nb, [na])) hits.add(nb);        // na covers nb → nb is more specific (or equal)
+      else if (matchOne(na, [nb])) hits.add(na);   // nb covers na → na is more specific
+    }
+  }
+  return [...hits].sort();
+}
+
+// Claim-aware severity: two colliding tasks BOTH actively claimed are colliding
+// right now ('high'); one claimed means new work would land under someone's
+// feet ('medium'); neither claimed is a planning-time heads-up ('low').
+function severityFor(aClaimed, bClaimed) {
+  if (aClaimed && bClaimed) return 'high';
+  if (aClaimed || bClaimed) return 'medium';
+  return 'low';
+}
+
+const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
+
+// computeGoalConflicts — the detector.
+//   goalTasks:          this goal's tasks (any status; filtered here)
+//   activeClaimTaskIds: Set of task ids (any type; compared as strings) holding
+//                       an active claim (claims.released_at IS NULL)
+//   crossGoal:          [{ goal: {id,title}, tasks: [...] }] — other OPEN goals
+//                       sharing scope_modules, whose open tasks are checked
+//                       against THIS goal's open tasks (never against each other
+//                       — those pairs belong to that goal's own conflict view)
+// Returns pairs sorted most-severe first:
+//   { task_a, task_b, title_a, title_b, overlapping_paths, severity,
+//     has_active_claims, cross_goal, goal_b?, goal_b_title? }
+function computeGoalConflicts({ goalTasks = [], activeClaimTaskIds = new Set(), crossGoal = [] } = {}) {
+  const open = goalTasks.filter(isOpenWithTouches);
+  const claimed = (t) => activeClaimTaskIds.has(String(t.id));
+  const pair = (a, b, paths, extra) => ({
+    task_a: Number(a.id),
+    task_b: Number(b.id),
+    title_a: a.title || '',
+    title_b: b.title || '',
+    overlapping_paths: paths,
+    severity: severityFor(claimed(a), claimed(b)),
+    has_active_claims: claimed(a) || claimed(b),
+    cross_goal: false,
+    ...extra,
+  });
+
+  const out = [];
+  for (let i = 0; i < open.length; i++) {
+    for (let j = i + 1; j < open.length; j++) {
+      const paths = overlappingPaths(open[i].touches, open[j].touches);
+      if (paths.length) out.push(pair(open[i], open[j], paths));
+    }
+  }
+  for (const { goal, tasks } of crossGoal) {
+    const others = (tasks || []).filter(isOpenWithTouches);
+    for (const a of open) {
+      for (const b of others) {
+        const paths = overlappingPaths(a.touches, b.touches);
+        if (paths.length) {
+          out.push(pair(a, b, paths, {
+            cross_goal: true,
+            goal_b: Number(goal.id),
+            goal_b_title: goal.title || '',
+          }));
+        }
+      }
+    }
+  }
+  out.sort((x, y) =>
+    SEVERITY_ORDER[x.severity] - SEVERITY_ORDER[y.severity]
+    || x.task_a - y.task_a || x.task_b - y.task_b);
+  return out;
+}
+
+module.exports = {
+  RESOLVED_STATUSES,
+  isOpenWithTouches,
+  normalizeEntry,
+  overlappingPaths,
+  severityFor,
+  computeGoalConflicts,
+};

package/modules/lifecycle/hierarchy.js

@@ -0,0 +1,104 @@
+// GDS task hierarchy — shallow (one-level) parent/child tree.
+//
+// V2 introduces tasks.parent_task_id so a piece of work can decompose into
+// a parent task plus N child tasks (e.g., "F1: schema migration" with
+// children "table-x", "view-y", "seed-z"). The depth is intentionally
+// capped at one level — a parent cannot itself have a parent, and a task
+// that already has children cannot become a child. This module enforces
+// those invariants in app code; the DB enforces atomic ship-rollup via
+// the trigger added in migration 007_pms_v2_hierarchy_trigger.sql.
+//
+// See limitations/pms-v2.md (Activity 1 C2).
+
+const { pool } = require('../../src/module-api');
+
+// -------------------------------------------------------------------------
+// attachParent(taskId, parentTaskId)
+//
+// Sets tasks.parent_task_id = parentTaskId on the target task, after
+// validating:
+//   - both tasks exist
+//   - target !== parent (no self-reference)
+//   - target.version_id === parent.version_id (no cross-version trees)
+//   - parent.parent_task_id IS NULL                      (depth cap, side 1)
+//   - target has no children of its own                  (depth cap, side 2)
+//
+// Pass parentTaskId=null to detach (always allowed if the task exists).
+// Throws { code: 'TASK_NOT_FOUND' | 'PARENT_NOT_FOUND' | 'SELF_PARENT'
+//        | 'VERSION_MISMATCH' | 'PARENT_HAS_PARENT' | 'TARGET_HAS_CHILDREN' }.
+// -------------------------------------------------------------------------
+async function attachParent(taskId, parentTaskId) {
+  const targetId = Number(taskId);
+  if (!Number.isInteger(targetId) || targetId <= 0) {
+    throw { code: 'TASK_NOT_FOUND' };
+  }
+
+  // Detach path — no parent validation needed.
+  if (parentTaskId === null || parentTaskId === undefined) {
+    const { rowCount, rows } = await pool.query(
+      `UPDATE tasks SET parent_task_id = NULL WHERE id = $1 RETURNING *`,
+      [targetId]
+    );
+    if (rowCount === 0) throw { code: 'TASK_NOT_FOUND' };
+    return rows[0];
+  }
+
+  const parentId = Number(parentTaskId);
+  if (!Number.isInteger(parentId) || parentId <= 0) {
+    throw { code: 'PARENT_NOT_FOUND' };
+  }
+  if (parentId === targetId) {
+    throw { code: 'SELF_PARENT' };
+  }
+
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+
+    const { rows: targetRows } = await client.query(
+      `SELECT id, version_id, parent_task_id FROM tasks WHERE id = $1 FOR UPDATE`,
+      [targetId]
+    );
+    if (targetRows.length === 0) throw { code: 'TASK_NOT_FOUND' };
+    const target = targetRows[0];
+
+    const { rows: parentRows } = await client.query(
+      `SELECT id, version_id, parent_task_id FROM tasks WHERE id = $1 FOR UPDATE`,
+      [parentId]
+    );
+    if (parentRows.length === 0) throw { code: 'PARENT_NOT_FOUND' };
+    const parent = parentRows[0];
+
+    if (parent.version_id !== target.version_id) {
+      throw { code: 'VERSION_MISMATCH', target_version: target.version_id, parent_version: parent.version_id };
+    }
+    if (parent.parent_task_id !== null) {
+      throw { code: 'PARENT_HAS_PARENT', parent_id: parentId, grandparent_id: Number(parent.parent_task_id) };
+    }
+
+    const { rows: childRows } = await client.query(
+      `SELECT id FROM tasks WHERE parent_task_id = $1 LIMIT 1`,
+      [targetId]
+    );
+    if (childRows.length > 0) {
+      throw { code: 'TARGET_HAS_CHILDREN', target_id: targetId };
+    }
+
+    const { rows: updated } = await client.query(
+      `UPDATE tasks SET parent_task_id = $2 WHERE id = $1 RETURNING *`,
+      [targetId, parentId]
+    );
+
+    await client.query('COMMIT');
+    return updated[0];
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+module.exports = {
+  attachParent,
+};

package/modules/lifecycle/lifecycle.js

@@ -0,0 +1,58 @@
+'use strict';
+
+// modules/lifecycle/lifecycle.js — the `lifecycle` kernel PORT provider surface
+// (BV1.R86 / ADR 0093 §3). The lifecycle is carved last, so by now every
+// capability it INVOKES (grade, reward, onboarding) is a port it resolves; this
+// is the inverse — the surface CORE and the OTHER modules resolve to reach the
+// build state machine without importing modules/lifecycle/ (the one-way rule).
+//
+// It retires the three ADR-0091 §3 doorway leaks: `createTask`,
+// `VOTABLE_TASK_STATUSES`, and `tallyPeerVotes` now live HERE, behind the port,
+// not on src/module-api.js. Plus the work-tracking READS the staying-core read
+// routes (public/me/builders/analytics) need, and `classifyTaskKind` for the
+// dormant System-3 cascade-dispatch in core.
+//
+// DELEGATES (does not spread) to ./db + ./task-classifier so a test that stubs a
+// method on the live module object bites at call time (the economy `reward`
+// precedent). Constants are read live via getters for the same reason.
+
+const db = require('./db');
+const classifier = require('./task-classifier');
+
+module.exports = {
+  // --- retired doorway leaks (ADR 0093 §3) ---------------------------------
+  // createTask: the lifecycle task INSERT (consumers: the onboarding newcomer-
+  // restock + the discord bug-filing module db slices).
+  createTask: (...a) => db.createTask(...a),
+  // tallyPeerVotes: the peer-vote→karma weekly fold-in (consumer: the autonomy
+  // routine-timers poller — the SAME tx POST /tasks/peer-votes/tally runs).
+  tallyPeerVotes: (...a) => db.tallyPeerVotes(...a),
+  // VOTABLE_TASK_STATUSES: the votable-status set (consumer: discord-reaction —
+  // decide applause vs a real vote). classifyTaskKind: the kind heuristic
+  // (consumer: core cascade-dispatch.js, the dormant System-3 lib).
+  get VOTABLE_TASK_STATUSES() { return classifier.VOTABLE_TASK_STATUSES; },
+  classifyTaskKind: (...a) => classifier.classifyTaskKind(...a),
+
+  // --- work-tracking READS the staying-core read routes resolve --------------
+  // public.js (the status surface): version/ship feed + grade trend.
+  getTask: (...a) => db.getTask(...a),
+  listVersions: (...a) => db.listVersions(...a),
+  versionProgress: (...a) => db.versionProgress(...a),
+  recentShippedTasks: (...a) => db.recentShippedTasks(...a),
+  estimationDriftSummary: (...a) => db.estimationDriftSummary(...a),
+  rollingAvgGrade: (...a) => db.rollingAvgGrade(...a),
+  gradeTrendByDay: (...a) => db.gradeTrendByDay(...a),
+  // me.js (the profile reader): per-builder claims + estimation + grade reads.
+  getActiveClaimsForBuilder: (...a) => db.getActiveClaimsForBuilder(...a),
+  getEstVsActualRatio: (...a) => db.getEstVsActualRatio(...a),
+  recentGradesForBuilder: (...a) => db.recentGradesForBuilder(...a),
+  countShippedTasksForBuilder: (...a) => db.countShippedTasksForBuilder(...a),
+  recentShippedTasksByBuilder: (...a) => db.recentShippedTasksByBuilder(...a),
+  // builders.js (the Archon roster): the roster + stale-claim + per-builder grade.
+  getBuildersRoster: (...a) => db.getBuildersRoster(...a),
+  getActiveClaimsForBuilderWithStale: (...a) => db.getActiveClaimsForBuilderWithStale(...a),
+  gradeByBuilder: (...a) => db.gradeByBuilder(...a),
+  // analytics.js (the AI-dev-curve): the builder + ecosystem analytics.
+  builderAnalytics: (...a) => db.builderAnalytics(...a),
+  ecosystemAnalytics: (...a) => db.ecosystemAnalytics(...a),
+};

package/modules/lifecycle/merge-lock.js

@@ -0,0 +1,261 @@
+// Shared advisory mutex for the SINGLE shared `main` worktree.
+// (task 1146 / ADR 0058: this comment is a needs_trust gate-surface change used to
+//  verify the automatic gatekeeper auto-merges a trusted author's PR with no owner click.)
+//
+// Both ship.js's autoMerge() and the /merge-mode skill mutate the same main
+// worktree (REPO_ROOT). #462 (criterion C4) added a lockfile so two concurrent
+// SHIPS could no longer collide — but the lock lived inside ship.js, so
+// /merge-mode (which mutates the same tree by hand) never participated. This
+// module extracts the lock so BOTH surfaces share ONE mutex: ship-vs-ship,
+// ship-vs-merge-mode, and merge-mode-vs-merge-mode are all serialized.
+// (V3.R50 / #269, criterion C6.)
+//
+// The lock is a plain file at <repoRoot>/.git/otb-automerge.lock. We don't use
+// flock(2): ships and merge runs happen on macOS, where flock over an
+// iCloud-synced filesystem is unreliable, and the holder may be a short-lived
+// CLI process (the manual /merge-mode case has no long-lived owner). The file
+// records three lines:
+//   line 1: holder pid  (0 for a manual/CLI hold with no long-lived process)
+//   line 2: epoch-ms timestamp when acquired
+//   line 3: mode  ('auto' | 'manual')
+//
+// Staleness / liveness — a held lock is reclaimable when:
+//   - auto  : the holder pid is dead OR the stamp is older than AUTO_STALE_MS
+//             (a crashed automated ship that never released).
+//   - manual: only by time (MANUAL_STALE_MS). A manual hold has no stable pid
+//             (the CLI process that wrote it has already exited), so we trust
+//             the operator to release() and fall back to a generous timeout if
+//             they walk away mid-merge.
+//
+// Back-compat: a two-line lockfile written by the pre-#269 ship.js (pid\nts) is
+// read as mode='auto', so a ship mid-flight during the deploy of this change is
+// not disrupted.
+//
+// ⚠️ SYNCHRONOUS / CLI-ONLY. acquire() busy-waits (up to waitMs) and the
+// internal sleepSync() blocks the thread via Atomics.wait — by design, because
+// the only callers are execSync-style CLI scripts (ship.js auto-merge, the
+// merge-lock.js CLI) that have no event loop to yield to. **Do NOT import this
+// module from an Express route handler or any code on the request path** — a
+// blocking acquire would stall the Node event loop for the whole process. If a
+// route ever needs to inspect the lock, add a non-blocking readLock()-only
+// helper rather than calling acquire(). sleepSync is intentionally NOT exported
+// for this reason.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+const AUTO_STALE_MS = 10 * 60 * 1000; // crashed automated ship
+const MANUAL_STALE_MS = 30 * 60 * 1000; // operator walked away mid-merge-mode
+const INDEX_LOCK_GRACE_MS = 60 * 1000; // a git index.lock younger than this may be a LIVE op
+
+function lockPath(repoRoot) {
+  return path.join(repoRoot, '.git', 'otb-automerge.lock');
+}
+
+// Synchronous sleep without spawning a process (ship.js is execSync-style and
+// has no event loop to yield to while it holds the merge critical section).
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function pidAlive(pid) {
+  // pid <= 1 is never one of OUR holders: auto holds write process.pid (always
+  // > 1) and manual holds write 0 (and are reclaimed by time, not liveness).
+  // Rejecting pid 1 here also closes the theoretical case where a hand-crafted
+  // lockfile names pid 1 (init/launchd, always alive → EPERM) to look
+  // perpetually held; such a lock is now reclaimed immediately rather than
+  // lingering until AUTO_STALE_MS.
+  if (!Number.isInteger(pid) || pid <= 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM'; // EPERM: exists, not ours. ESRCH: dead.
+  }
+}
+
+// Parse the lockfile into { pid, ts, mode } or null if absent/unreadable.
+function readLock(repoRoot) {
+  try {
+    const [p, t, m] = fs.readFileSync(lockPath(repoRoot), 'utf8').split('\n');
+    const pid = parseInt(p, 10);
+    const ts = parseInt(t, 10) || 0;
+    const mode = m && m.trim() === 'manual' ? 'manual' : 'auto';
+    return { pid: Number.isFinite(pid) ? pid : NaN, ts, mode };
+  } catch (_) {
+    return null;
+  }
+}
+
+// Repair the shared main worktree after reclaiming a STALE lock. The prior
+// holder is, by definition of stale, dead or abandoned — and a holder that
+// crashed mid-merge leaves wreckage the NEXT holder would otherwise inherit:
+//   - an orphaned git `.git/index.lock` (every git write then fails with
+//     "Another git process seems to be running"), and/or
+//   - a half-applied merge (MERGE_HEAD + a dirty index full of staged changes)
+//     that wedges `mainWorktreeBusy()` and `git merge --ff-only` for everyone.
+// (Real incident 2026-06-01: a crashed /merge-mode run left 830 staged
+// deletions + an orphaned index.lock, wedging the queue for 30 min.)
+//
+// This ONLY runs on the stale-reclaim path, so it never touches a live holder's
+// tree. It is best-effort: every step is guarded so a repair hiccup can't block
+// the reclaim. `runner` (execSync) and `now` are injectable for tests.
+//
+// Safety of `reset --hard origin/main`: REPO_ROOT is the throwaway shared main
+// worktree that only ever holds `main` (all feature work lives in per-builder
+// worktrees), and the dead holder's local merge was never pushed — so resetting
+// to the fetched origin/main loses no committed, reachable work. Gated on being
+// mid-merge or dirty to avoid gratuitous churn on a clean reclaim.
+function recoverWorktree(repoRoot, { now = Date.now, runner = execSync } = {}) {
+  const run = (cmd) =>
+    runner(cmd, { cwd: repoRoot, stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' });
+  const tryRun = (cmd) => {
+    try { run(cmd); return true; } catch (_) { return false; }
+  };
+
+  // 1. Clear an ORPHANED git index.lock — but only if it's old enough that no
+  //    live git process could still own it. A fresh lock means a live op
+  //    (possibly a holder that just acquired after us); never yank that.
+  try {
+    const lk = path.join(repoRoot, '.git', 'index.lock');
+    const st = fs.statSync(lk); // throws ENOENT when absent → nothing to clear
+    if (now() - st.mtimeMs > INDEX_LOCK_GRACE_MS) fs.unlinkSync(lk);
+  } catch (_) {
+    /* absent, racing a live op, or unreadable — leave it */
+  }
+
+  // 2. Abort a half-applied merge and drop the dead holder's staged changes so
+  //    the next holder starts from a clean origin/main.
+  let midMerge = false;
+  try { run('git rev-parse -q --verify MERGE_HEAD'); midMerge = true; } catch (_) { /* not mid-merge */ }
+  let dirty = false;
+  try { dirty = run('git status --porcelain').trim().length > 0; } catch (_) { /* unknown — treat as clean */ }
+  if (midMerge) tryRun('git merge --abort');
+  if (midMerge || dirty) {
+    tryRun('git fetch origin main');
+    tryRun('git reset --hard origin/main');
+  }
+}
+
+// Is a held lock reclaimable right now? `now` is injectable for tests.
+function isStale(rec, now = Date.now()) {
+  if (!rec) return true;
+  const window = rec.mode === 'manual' ? MANUAL_STALE_MS : AUTO_STALE_MS;
+  if (now - rec.ts > window) return true;
+  if (rec.mode === 'manual') return false; // time-based only — no stable pid
+  return !pidAlive(rec.pid);
+}
+
+// Acquire the exclusive merge lock. Returns true (caller MUST release() on
+// every exit path) or false if a live holder keeps it past the wait window
+// (caller bails to /merge-mode). Reclaims a stale lock automatically.
+//
+// opts:
+//   waitMs : how long to wait for a live holder before giving up (default 30s)
+//   mode   : 'auto' (a process-backed ship) | 'manual' (a CLI/operator hold)
+//   pid    : holder pid to record (default process.pid; pass 0 for manual)
+//   sleep  : injectable sleeper (tests)
+//   now    : injectable clock (tests)
+function acquire(repoRoot, opts = {}) {
+  const {
+    waitMs = 30000,
+    mode = 'auto',
+    pid = process.pid,
+    sleep = sleepSync,
+    now = Date.now,
+    recover = recoverWorktree,
+  } = opts;
+  const p = lockPath(repoRoot);
+  const deadline = now() + waitMs;
+  for (;;) {
+    try {
+      const fd = fs.openSync(p, 'wx'); // create-exclusive; EEXIST if held
+      fs.writeSync(fd, `${pid}\n${now()}\n${mode}\n`);
+      fs.closeSync(fd);
+      return true;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      const rec = readLock(repoRoot);
+      if (isStale(rec, now())) {
+        let reclaimed = false;
+        try {
+          fs.unlinkSync(p);
+          reclaimed = true;
+        } catch (_) {
+          /* someone else reclaimed it first — retry */
+        }
+        // Only repair the worktree if WE won the unlink — otherwise a freshly
+        // arrived live holder now owns it and its (clean) tree must be left be.
+        if (reclaimed) {
+          try { recover(repoRoot, { now }); } catch (_) { /* best-effort */ }
+        }
+        continue; // reclaimed — retry the create immediately
+      }
+      if (now() >= deadline) return false; // live holder; gave up waiting
+      sleep(2000);
+    }
+  }
+}
+
+// Release the lock. By default only the recording process (auto holds) or any
+// caller of a manual hold may remove it — defensive against a stolen-stale
+// race where we reclaimed someone else's lock and they later try to release.
+//   pid   : the releasing process (default process.pid)
+//   force : remove regardless of owner (emergency operator escape hatch)
+function release(repoRoot, opts = {}) {
+  const { pid = process.pid, force = false } = opts;
+  try {
+    const rec = readLock(repoRoot);
+    if (!rec) return;
+    if (force || rec.mode === 'manual' || rec.pid === pid) {
+      fs.unlinkSync(lockPath(repoRoot));
+    }
+  } catch (_) {
+    /* already gone */
+  }
+}
+
+// ---------- the cross-machine tier: server-side merge lease (task 585 / idea 124) ----------
+//
+// Everything above is machine-LOCAL: a filesystem mutex on ONE checkout of main. When builders
+// ship from DIFFERENT physical machines (each with its own checkout), that lock can't serialize
+// them. The cross-machine tier is a TTL'd DB lease (src/bongos/db.js acquireMergeLease /
+// releaseMergeLease / mergeLeaseStatus), handed out by the GDS API at merge time. This helper is
+// the composition point: a multi-machine ship takes the server lease FIRST (one machine merges at
+// a time), then the local file lock above.
+//
+// async + DEPENDENCY-INJECTED `lease` backend, deliberately: this module must stay require-able by
+// the SYNC CLI path (ship.js, the merge-lock CLI) WITHOUT pulling in db.js + a pg pool, and the
+// server lease only matters for server-mediated / multi-machine ships. The caller injects
+//   lease = { acquire({key,holder,ttlSeconds}) -> {acquired,holder,expires_at}, release({key,holder}) }
+// (src/bongos/db.js satisfies this shape). With no backend, runs the fn directly — the file lock still
+// serializes the single-machine case. Throws MERGE_LEASE_HELD if another machine holds the lease.
+async function withServerMergeLease(holder, fn, { lease, key = 'main', ttlSeconds = 600 } = {}) {
+  if (!lease || typeof lease.acquire !== 'function') return fn();
+  const res = await lease.acquire({ key, holder, ttlSeconds });
+  if (!res || !res.acquired) {
+    const err = new Error(`merge lease for '${key}' held by ${res?.holder ?? 'another machine'} until ${res?.expires_at ?? '?'}`);
+    err.code = 'MERGE_LEASE_HELD';
+    throw err;
+  }
+  try {
+    return await fn();
+  } finally {
+    try { await lease.release({ key, holder }); } catch (_) { /* TTL reclaims it — best-effort */ }
+  }
+}
+
+module.exports = {
+  AUTO_STALE_MS,
+  MANUAL_STALE_MS,
+  INDEX_LOCK_GRACE_MS,
+  lockPath,
+  pidAlive,
+  readLock,
+  isStale,
+  recoverWorktree,
+  acquire,
+  release,
+  withServerMergeLease,
+};

package/modules/lifecycle/migrations/lifecycle_001_goal_first_leads.sql

@@ -0,0 +1,28 @@
+-- lifecycle_001_goal_first_leads.sql — backfill goal OWNERS into the member list
+-- (task 1735). The goal authority model: the OWNER is goals.created_by (fixed at
+-- create, moved only by POST /goals/:id/transfer); goal_members.role 'lead' is
+-- the MANAGER tier the hall renders. From now on db.createGoal inserts the
+-- creator's lead row atomically; this brings the goals created before that rule
+-- up to the same shape so owners appear in their own member lists.
+--
+-- Goals with created_by NULL (the migration-160 default "<version> — general"
+-- goals) have NO owner by design — Archons act as one via the gates' archon arm.
+-- Deliberately NO earliest-member fallback: promoting a member to manager on an
+-- ownerless goal would grant authority nobody asked for (fail-closed).
+--
+-- Data-only (no schema change), idempotent (the upsert converges), and
+-- replay-safe on a fresh DB (zero goals → zero rows; no builder id is
+-- hard-coded — learning 1238).
+
+BEGIN;
+
+INSERT INTO goal_members (goal_id, builder_id, role)
+SELECT g.id, g.created_by, 'lead'
+  FROM goals g
+ WHERE g.created_by IS NOT NULL
+ON CONFLICT (goal_id, builder_id) DO UPDATE SET role = 'lead';
+
+INSERT INTO schema_migrations (version) VALUES ('lifecycle_001_goal_first_leads')
+  ON CONFLICT (version) DO NOTHING;
+
+COMMIT;

package/modules/lifecycle/migrations/lifecycle_002_backfill_orphan_task_goals.sql

@@ -0,0 +1,36 @@
+-- lifecycle_002_backfill_orphan_task_goals.sql — task 1763.
+--
+-- The goal-clean-up invariant: every task belongs to a goal. Going forward,
+-- db.createTask defaults a goal-less new task into its version's catch-all
+-- "<version> — general" goal (created by migration 160), so no NEW orphan is
+-- minted by any create-vector. This one-time, idempotent backfill sweeps the
+-- PRE-EXISTING orphan tasks into that same per-version general goal — the exact
+-- mirror of migration 160's criterion backfill (same title match: the spaced
+-- em-dash `<version_id> — general`; keep in sync with db.generalGoalIdForVersion).
+--
+-- PORTABLE + replay-safe: no instance data is hard-coded. On a fresh/vanilla DB
+-- there are no orphan tasks (createTask assigns a goal from the first task), so
+-- the UPDATE simply touches zero rows. A version with no general goal (should not
+-- happen post-160, but defensively) leaves its tasks unlinked rather than erroring.
+--
+-- Instance-specific re-homing (e.g. OTB's hall-UI program tasks into a NAMED goal
+-- like #25 rather than the catch-all) is deliberately NOT done here — that is
+-- owning-instance data, applied under a claim via the PATCH /tasks/:id goal_id
+-- endpoint this task adds, not shipped to every instance.
+
+BEGIN;
+
+-- Deliberately does NOT bump updated_at (mirrors migration 160's criterion
+-- backfill): this is a one-time invariant cleanup, not a meaningful edit, so it
+-- must not churn "recently updated" sort orders across every backfilled row.
+UPDATE tasks t
+   SET goal_id = g.id
+  FROM goals g
+ WHERE g.version_id = t.version_id
+   AND g.title = t.version_id || ' — general'
+   AND t.goal_id IS NULL;
+
+INSERT INTO schema_migrations (version) VALUES ('lifecycle_002_backfill_orphan_task_goals')
+  ON CONFLICT (version) DO NOTHING;
+
+COMMIT;

package/modules/lifecycle/module.json

@@ -0,0 +1,13 @@
+{
+  "key": "lifecycle",
+  "title": "Lifecycle (the build state machine)",
+  "description": "The build state machine — tasks · claims · versions · done-when criteria · goals · dependencies · the claim→ship→grade→credit lifecycle · override requests · the ship/confirm/promote orchestration · github-push + merge-lease + conflict-resolve + the publish reconciler. The LAST and most-coupled core domain carved out of the GDS core in BV1.R86 (ADR 0093 §1,§3, 02-module-map §4 — kept whole, never split). default-on; every instance runs the lifecycle. Registers the `lifecycle` kernel PORT (createTask · VOTABLE_TASK_STATUSES · classifyTaskKind · tallyPeerVotes + the work-tracking reads) that core read routes + the ideas/discord/autonomy modules resolve. As a transaction-participant it RESOLVES the `reward` + `onboarding` ports inside its claim/ship/confirm txns — but via resolveOptional (graceful, like sessions→reward), so consumes is empty: a vanilla instance without those modules degrades the credit/onboarding writes to best-effort no-ops, it does not fail.",
+  "coreVersion": "^1.12.0",
+  "default": true,
+  "contributes": {
+    "routes": ["tasks", "claims", "versions", "done-when", "goals", "dependencies", "gate-approvals", "analytics", "lifecycle"],
+    "pollers": ["publish-reconciler"]
+  },
+  "provides": ["lifecycle"],
+  "consumes": []
+}

package/modules/lifecycle/pollers/publish-reconciler.js

@@ -0,0 +1,20 @@
+'use strict';
+
+// modules/lifecycle/pollers/publish-reconciler.js — the loader poller entry for
+// the confirmed→shipped auto-heal sweep (BV1.R86 / ADR 0093 §1).
+//
+// Was `publishReconciler.start()` / `.stop()` hardcoded in server.js; now a
+// loader-started POLLER (contributes.pollers:["publish-reconciler"]), exactly the
+// inversion the autonomy carve (routine-timers) made for its weekly timer. The
+// loader's startModulePollers requires THIS file and calls start(deps) at boot /
+// stop() at shutdown — failure-isolated, non-blocking. server.js no longer reaches
+// into the lifecycle module to start it. The reconciler resolves the economy
+// `reward` port for the cost sweep and its github-push/conflict-resolve siblings
+// for the merge land — all module-internal.
+
+const reconciler = require('../publish-reconciler');
+
+module.exports = {
+  start: (deps = {}) => reconciler.start(deps),
+  stop: () => reconciler.stop(),
+};