@bongos/core 1.17.0

package/scripts/gds/main-audit.js

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+// scripts/gds/main-audit.js — post-push main audit (SEC #863, ADR 0043).
+//
+// LAYER 3, the AUTHORITATIVE net. The pre-push hook (layer 1) and the grader
+// pre-pass (layer 2) gate the cooperative path, but a free-plan private repo
+// can't forbid a raw `git push origin main` at GitHub, and a builder can
+// `--no-verify`. This audit reads the REAL git history on main and the REAL
+// builder ranks (from the GDS roster) and flags commits where a builder BELOW
+// Metic edited a permission-sensitive surface — exactly the Builder 25 incident
+// (a Thetes editing the rank-tier CASE in src/bongos/db.js and pushing to main).
+//
+// Two modes:
+//   (report, default)   list findings on a commit range; non-zero exit if any
+//                        blocker — usable from CI.
+//   --verify-head       gate for the deploy step (infra/deploy.sh): exit non-zero
+//                        if HEAD's range contains a blocker, so a poisoned main
+//                        never reaches production. THIS is the bridge to Option
+//                        A: even though builders technically can push main today,
+//                        the DEPLOY refuses un-authorized commits.
+//
+// Identity: a commit's author NAME is the builder's github_login in this
+// pipeline (verified on the #863 commit: author "IAMMASTERQUA"). We resolve the
+// author against the GDS roster (github_login / display_name). MERGE commits are
+// skipped — their protected-path content is attributed to the feature commits
+// they bring in (which carry the real author). An author we cannot resolve to a
+// rank on a protected-path commit is a 'review' finding (in --verify-head it
+// blocks unless --allow-unverified, fail-closed).
+//
+// Usage:
+//   node scripts/gds/main-audit.js                       # audit last 50 on origin/main
+//   node scripts/gds/main-audit.js --range A..B          # audit an explicit range
+//   node scripts/gds/main-audit.js --verify-head         # deploy gate: HEAD~30..HEAD
+//   node scripts/gds/main-audit.js --verify-head --db    # deploy gate on the droplet (rank from Postgres)
+//   node scripts/gds/main-audit.js --revert              # also print `git revert` plan
+//   node scripts/gds/main-audit.js --strict              # also block on unresolved authors
+//   node scripts/gds/main-audit.js --db                  # resolve ranks from Postgres instead of the API
+
+'use strict';
+
+const { execSync } = require('node:child_process');
+const ppc = require(require('node:path').join(__dirname, '..', '..', 'src', 'bongos', 'permission-path-check.js'));
+const { cliClient } = require('./cli-lib');
+
+// ---------- pure analyzer (tested in tests/main_audit.mjs) ----------
+
+// commits: [{ sha, subject, authorName, authorEmail, isMerge, files: [] }]
+// rankByIdentity: { '<lowercased login-or-name-or-email>': '<rank>' }
+// Returns { ok, hardFail, findings[] }.
+// strict=true escalates "author couldn't be resolved to a rank" from a
+// 'review' note to a hard blocker. Default is NON-strict: only a RESOLVED
+// sub-Metic author is a blocker (the high-confidence, zero-false-positive
+// signal — the #863 case). This matters because the trusted operator/deployer
+// commits under a git author name ('Lars Kristensen') that is a display name,
+// not a GDS github_login, and every builder shares one commit email — so the
+// author NAME is the only distinguishing signal, and an unresolved name is
+// 'needs a human glance', not 'definitely a violation'.
+function analyzeCommits(commits, rankByIdentity, { strict = false } = {}) {
+  const findings = [];
+  for (const c of commits || []) {
+    // #863-followup (finding #5): we no longer blanket-skip merges. For a
+    // regular commit, `files` is its name-only diff. For a MERGE commit, the
+    // git layer (parseCommits) populates `files` with the EVIL-MERGE surface —
+    // the `git diff-tree --cc` set, i.e. changes the merge introduced that are
+    // in NEITHER parent (conflict resolutions / smuggled edits). A normal
+    // pipeline merge has an empty --cc set → no files → no finding, so feature
+    // changes are still attributed to their feature commits (no double-count);
+    // but a merge that smuggles a protected change is now caught and attributed
+    // to the MERGE author.
+    const hits = ppc.matchProtected(c.files || []);
+    if (hits.length === 0) continue;
+
+    const rank = resolveRank(c, rankByIdentity);
+    const fileList = hits.map((h) => h.file).join(', ');
+    if (rank == null) {
+      findings.push({
+        severity: strict ? 'blocker' : 'review',
+        sha: c.sha,
+        author: c.authorName,
+        rank: null,
+        files: hits.map((h) => h.file),
+        summary: `commit ${short(c.sha)} by '${c.authorName}' touched permission-sensitive path(s) [${fileList}] but the author could not be resolved to a GDS rank. Verify it is Metic+ work.`,
+      });
+    } else if (ppc.isBelowFloor(rank)) {
+      findings.push({
+        severity: 'blocker',
+        sha: c.sha,
+        author: c.authorName,
+        rank,
+        files: hits.map((h) => h.file),
+        summary: `commit ${short(c.sha)} by '${c.authorName}' (rank '${rank}', below Metic) modified permission-sensitive path(s) [${fileList}] — this is the SEC #863 violation class. It must be reverted and re-landed by an Archon if genuinely needed.`,
+      });
+    }
+  }
+  return {
+    ok: findings.every((f) => f.severity !== 'blocker'),
+    hardFail: findings.some((f) => f.severity === 'blocker'),
+    findings,
+  };
+}
+
+// #863-followup (red-team finding #6): resolve ONLY against github_login.
+// We deliberately do NOT match on email (everyone shares one commit email —
+// non-distinguishing) nor display_name (builder-controlled — a malicious builder
+// can set display_name to another builder's login to ALIAS/poison resolution).
+// github_login is GitHub-controlled and immutable per account. A commit whose
+// git author name is not a known github_login resolves to null → handled by the
+// strict gate (block) rather than silently passing.
+function resolveRank(c, rankByIdentity) {
+  const name = (c.authorName || '').toLowerCase();
+  return name && rankByIdentity[name] != null ? rankByIdentity[name] : null;
+}
+
+function short(sha) {
+  return String(sha || '').slice(0, 9);
+}
+
+// ---------- git + API glue (CLI) ----------
+
+function git(args) {
+  return execSync(`git ${args}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+// Parse `git log --name-only` with a NUL-delimited custom format into commits.
+function parseCommits(range) {
+  // %x00 = NUL. Format: NUL sha NUL parents NUL authorName NUL authorEmail NUL subject \n files...
+  const fmt = '%x00%H%x00%P%x00%an%x00%ae%x00%s';
+  let out;
+  try {
+    out = git(`log ${range} --name-only --format=${JSON.stringify(fmt)}`);
+  } catch (e) {
+    return { error: `git log failed for range ${range}: ${e.message}` };
+  }
+  const records = out.split('\x00').slice(1); // first chunk is empty / pre-first-NUL
+  const commits = [];
+  // Each commit emits: sha, parents, an, ae, "subject\nfile\nfile...". We split
+  // on NUL so chunks come in groups of 5; the 5th holds subject + file list.
+  for (let i = 0; i + 4 < records.length; i += 5) {
+    const sha = records[i].trim();
+    const parents = records[i + 1].trim();
+    const authorName = records[i + 2];
+    const authorEmail = records[i + 3];
+    const rest = records[i + 4].split('\n');
+    const subject = rest.shift();
+    const files = rest.map((s) => s.trim()).filter(Boolean);
+    if (!sha) continue;
+    const isMerge = parents.split(/\s+/).filter(Boolean).length > 1;
+    commits.push({ sha, subject, authorName, authorEmail, isMerge, files });
+  }
+  // #863-followup (finding #5): `git log --name-only` emits NO files for merge
+  // commits, so a merge that SMUGGLES a protected change (an "evil merge" /
+  // conflict resolution that edits a file present in neither parent) would slip
+  // through. Backfill each merge's `files` with the combined-diff (`--cc`)
+  // surface — exactly the changes the merge introduced vs. all parents. A clean
+  // pipeline merge has an empty --cc set (nothing to flag); a smuggled edit
+  // shows up here and is attributed to the merge author by analyzeCommits.
+  for (const c of commits) {
+    if (!c.isMerge) continue;
+    try {
+      const cc = git(`diff-tree --cc --name-only --no-commit-id -r ${c.sha}`);
+      c.files = cc.split('\n').map((s) => s.trim()).filter(Boolean);
+    } catch (_) {
+      c.files = []; // can't compute → empty (the nightly full-history audit re-checks)
+    }
+  }
+  return { commits };
+}
+
+// #863-followup (finding #6): key ONLY on github_login. display_name is
+// builder-controlled — keying it let a malicious builder alias another login's
+// rank (last-write-wins poisoning). github_login is GitHub-controlled.
+function rowsToMap(rows) {
+  const map = {};
+  for (const b of rows || []) {
+    if (b.github_login) map[String(b.github_login).toLowerCase()] = b.rank;
+  }
+  return map;
+}
+
+// API mode (default): for an Archon session / operator laptop. DB mode (--db):
+// for the droplet deploy gate, which has DB access but no GDS session — it reads
+// the roster straight from Postgres. db.js is lazy-required so importing this
+// module (e.g. in tests) never pulls in pg.
+async function fetchRankMap({ useDb = false } = {}) {
+  if (useDb) {
+    try {
+      const db = require('../../src/bongos/db.js');
+      const roster = await db.getBuildersRoster({ staleHours: 24 });
+      return rowsToMap(roster.builders || roster);
+    } catch (e) {
+      console.error(`main-audit: --db roster read failed (${e.message})`);
+      return {};
+    }
+  }
+  try {
+    const api = await cliClient({ allowUnauthenticated: true });
+    const res = await api.builders.getBuildersRoster();
+    if (res && res.ok) return rowsToMap(res.data?.builders || []);
+  } catch (_) { /* offline / not archon — map stays empty → unresolved authors */ }
+  return {};
+}
+
+function arg(name, fallback = null) {
+  const i = process.argv.indexOf(name);
+  return i >= 0 ? (process.argv[i + 1] && !process.argv[i + 1].startsWith('--') ? process.argv[i + 1] : true) : fallback;
+}
+
+async function main() {
+  const verifyHead = process.argv.includes('--verify-head');
+  const doRevert = process.argv.includes('--revert');
+  const strict = process.argv.includes('--strict');
+  const useDb = process.argv.includes('--db');
+  let range = arg('--range');
+  // #863-followup (findings #8/#14): the verify-head window was a fixed
+  // HEAD~30..HEAD — a poisoned commit buried under >30 commits (merges inflate
+  // the count) or landed before a rebase/force-push could escape it. The deploy
+  // gate now passes the EXACT previously-deployed SHA via OTB_AUDIT_RANGE
+  // (deploy-main-audit-gate.sh sets it to <prev-deployed-sha>..HEAD), so the
+  // gate audits precisely what this deploy introduces — no window to slip under.
+  // Fallbacks widen to HEAD~200 (verify-head) / a deeper origin scan otherwise.
+  if ((!range || range === true) && process.env.OTB_AUDIT_RANGE) {
+    range = process.env.OTB_AUDIT_RANGE;
+  }
+  if (!range || range === true) {
+    if (verifyHead) {
+      range = 'HEAD~200..HEAD';
+    } else {
+      // Default: recent origin/main. Fetch first so we're auditing the truth.
+      try { git('fetch origin main'); } catch (_) { /* offline — audit local */ }
+      range = 'origin/main~200..origin/main';
+    }
+  }
+
+  const parsed = parseCommits(range);
+  if (parsed.error) {
+    console.error(`main-audit: ${parsed.error}`);
+    process.exit(2);
+  }
+  const rankMap = await fetchRankMap({ useDb });
+  if (Object.keys(rankMap).length === 0) {
+    console.error('main-audit: WARNING — could not load the GDS roster (offline / not Archon / no DB). Authors will be unresolved; run as an Archon or with --db (on the droplet) for a definitive audit.');
+  }
+
+  const result = analyzeCommits(parsed.commits, rankMap, { strict });
+
+  console.log(`\nMain audit (SEC #863) — range ${range}, ${parsed.commits.length} commit(s)`);
+  if (result.findings.length === 0) {
+    console.log('  ✓ clean — no sub-Metic edits to permission-sensitive paths.\n');
+    process.exit(0);
+  }
+  for (const f of result.findings) {
+    const tag = f.severity === 'blocker' ? '\x1b[31m[BLOCKER]\x1b[0m' : '\x1b[33m[review]\x1b[0m';
+    console.log(`  ${tag} ${f.summary}`);
+  }
+  if (doRevert) {
+    const blockers = result.findings.filter((f) => f.severity === 'blocker');
+    if (blockers.length) {
+      console.log('\nRevert plan (review before running — an Archon decides):');
+      for (const f of blockers) console.log(`  git revert --no-edit ${f.sha}   # ${f.author} / ${f.rank}`);
+    }
+  }
+  console.log('');
+
+  // verify-head is the deploy gate: any blocker (and, unless allowed, any
+  // unresolved author) must stop the deploy.
+  if (verifyHead) {
+    process.exit(result.hardFail ? 1 : 0);
+  }
+  // report mode: non-zero on a real blocker so CI can fail.
+  process.exit(result.hardFail ? 1 : 0);
+}
+
+if (require.main === module) {
+  main().catch((e) => {
+    console.error(`main-audit: ${e.message}`);
+    process.exit(2);
+  });
+}
+
+module.exports = { analyzeCommits, resolveRank, parseCommits };

package/scripts/gds/me.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Show the current builder profile, leaderboard top 10, and active claim.
+
+const { cliClient, requireSession } = require('./cli-lib');
+
+(async () => {
+  await requireSession();
+  const api = await cliClient();
+  const me = await api.me.getMe();
+  if (!me.ok) {
+    console.error('me failed:', me.data);
+    process.exit(1);
+  }
+  const lb = await api.leaderboard.getLeaderboard();
+
+  const b = me.data.builder;
+  const rankLabel = b.rank ? b.rank.charAt(0).toUpperCase() + b.rank.slice(1) : 'Thetes';
+  console.log(`${b.display_name} (@${b.github_login})`);
+  console.log(`Builder #${b.id}  ·  ${rankLabel}  ·  ${b.total_credits} credits`);
+  // V3 auth-flow slice 1: the /me call we just made succeeded, which means the
+  // session is valid AND just rolled forward (mig 035 refreshes expires_at to
+  // NOW()+1h on every authenticated request). Surface that so 1h-rolling is
+  // visible to the builder rather than being silent infrastructure.
+  console.log(`Session valid — auto-refreshes on every API call (1h rolling TTL).`);
+
+  // Streak panel — shown only when current streak > 0 (per task spec).
+  const s = me.data.streak;
+  if (s && s.current > 0) {
+    console.log('');
+    console.log(`Streak: ${s.current} day${s.current === 1 ? '' : 's'}  🔥 (longest: ${s.longest})`);
+    if (s.last_ship_day) {
+      console.log(`Last ship-day: ${s.last_ship_day}${s.today === s.last_ship_day ? ' (today)' : ''}`);
+    }
+  }
+
+  const claims = me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []);
+  if (claims.length === 0) {
+    console.log('');
+    console.log('No active claims.');
+  } else {
+    console.log('');
+    console.log(`Active claim${claims.length > 1 ? 's' : ''} (${claims.length}):`);
+    for (const c of claims) {
+      console.log(`  #${c.task_id} ${c.title}`);
+      console.log(`    Version: ${c.version_id} · P${c.priority ?? '?'} · ${c.credits_reward}c reward`);
+      console.log(`    Claimed: ${new Date(c.claimed_at).toLocaleString()}`);
+      if (c.worktree_name) console.log(`    Worktree: ${c.worktree_name}`);
+      // Streak preview — only when qualifying + extending (skip the noisy
+      // "today-already-counted" + "task-not-found" cases).
+      const sp = c.streak_preview;
+      if (sp && sp.qualifies && sp.projected_streak > sp.current_streak) {
+        console.log(`    🔥 Shipping this would extend streak to ${sp.projected_streak} day${sp.projected_streak === 1 ? '' : 's'}`);
+      }
+    }
+  }
+
+  // Recent quality grades (task 197). Surface only when the builder has at
+  // least one graded task so a fresh builder sees no empty section.
+  const grades = me.data.grades || {};
+  const recent = grades.recent || [];
+  const rolling = grades.rolling || {};
+  if (recent.length > 0) {
+    console.log('');
+    console.log('Recent quality marks (last 5):');
+    for (const g of recent) {
+      const verdict = g.passed ? 'PASS' : 'FAIL';
+      const dateStr = new Date(g.graded_at).toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+      console.log(`  ${dateStr}  #${g.task_id}  ${Number(g.score).toFixed(1)}/10  ${verdict}  ${g.title || ''}`);
+    }
+    if (Number(rolling.n) > 0) {
+      const avg = Number(rolling.avg_score).toFixed(1);
+      console.log(`  14-day avg: ${avg}/10 across ${rolling.n} task${rolling.n === 1 ? '' : 's'} (${rolling.n_passed} passed)`);
+    }
+  }
+
+  if (lb.ok) {
+    console.log('\nLeaderboard (top 10):');
+    let i = 1;
+    for (const row of (lb.data.leaderboard || []).slice(0, 10)) {
+      const me = row.id === b.id ? ' ← you' : '';
+      console.log(`  ${i.toString().padStart(2)}. ${row.display_name} (@${row.github_login}) — ${row.total_credits}c${me}`);
+      i++;
+    }
+  }
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});

package/scripts/gds/memory-map.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+// memory-map.js — keep the always-loaded memory MAP (MEMORY.md) light.
+//
+// MEMORY.md is the index the Claude Code harness loads IN FULL every session:
+// one line per memory → its topic file (the full fact). The topic files are the
+// "drawer" — they live on disk, sync to the GDS server (builder_memory), and are
+// searchable via /recall (ADR 0060), so they cost nothing until something fetches
+// them. The map is the only part paid for every session, so it must stay small.
+//
+// Nothing kept it small, so it re-bloated until the harness's ~24.4KB truncation
+// fired (too late — by then it was dropping lines). This module is the cure
+// (task 1362): a budget GUARD + an auto-TIDY that demotes the oldest non-rule
+// entries out of the map. **Demote = delete the entry's LINE from MEMORY.md only;
+// the topic file is never touched** — it stays on disk + server + /recall, one
+// query away. Standing rules (feedback_*/user memories) are never demoted.
+//
+// This file holds the PURE, testable logic. The session-start hook
+// (.claude/hooks/pull-memory.js) calls it; the actual file write is done by the
+// caller so it can be parallel-safe (optimistic: skip if the file changed since
+// read — the builder runs many concurrent sessions).
+
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Budgets, in bytes of MEMORY.md (~4 chars/token for markdown prose).
+const WARN_BYTES = 16000;   // ~4K tok — drifting up; warn so it gets tidied.
+const TIDY_BYTES = 20000;   // ~5K tok — auto-compact kicks in (still well under the ~24.4KB harness truncation).
+const TARGET_BYTES = 13000; // ~3.25K tok — compact back to about here.
+const MAX_LINE_CHARS = 280; // an index line past this has slipped the "one line" rule.
+const KEEP_NEWEST = 25;     // newest non-rule entries always kept in the map.
+
+const estTokens = (bytes) => Math.round(bytes / 4);
+
+// A map entry is a top-level bullet linking a topic file:
+//   - [Title](some-file.md) — one-line hook
+const ENTRY_RE = /^- \[([^\]]*)\]\(([A-Za-z0-9_-]+\.md)\)/;
+
+// Parse MEMORY.md into ordered entries. Non-entry lines (blank, headers) are
+// preserved positionally as { raw, entry:false } so render() can't drop them.
+function parseLines(text) {
+  return text.split('\n').map((raw) => {
+    const m = raw.match(ENTRY_RE);
+    return m ? { raw, entry: true, title: m[1], file: m[2], len: raw.length } : { raw, entry: false };
+  });
+}
+
+function entries(text) {
+  return parseLines(text).filter((l) => l.entry);
+}
+
+// Measure the map: size, token estimate, count, and any over-long lines.
+function measure(text) {
+  const bytes = Buffer.byteLength(text, 'utf8');
+  const es = entries(text);
+  const longLines = es.filter((e) => e.len > MAX_LINE_CHARS).map((e) => ({ file: e.file, len: e.len }));
+  return {
+    bytes,
+    tokens: estTokens(bytes),
+    count: es.length,
+    longLines,
+    overWarn: bytes > WARN_BYTES,
+    overTidy: bytes > TIDY_BYTES,
+  };
+}
+
+// type/mtime for a topic file. feedback_* and `user`-type memories are STANDING
+// RULES — never demoted. Everything else is demotable by age.
+function metaOf(file, memoryDir, deps = {}) {
+  const readFile = deps.readFile || ((p) => fs.readFileSync(p, 'utf8'));
+  const stat = deps.stat || ((p) => fs.statSync(p));
+  let type = /^feedback_/.test(file) ? 'feedback' : 'unknown';
+  let mtime = 0;
+  let pin = false;
+  const abs = path.join(memoryDir, file);
+  try {
+    mtime = stat(abs).mtimeMs;
+    const fm = readFile(abs).match(/^---\n([\s\S]*?)\n---/);
+    if (fm) {
+      if (type === 'unknown') {
+        const t = fm[1].match(/(?:^|\n)\s*type:\s*([a-z]+)/);
+        if (t) type = t[1];
+      }
+      // `pin: true` in frontmatter marks an entry the owner always wants on the
+      // home screen — kept regardless of age or budget (e.g. the live-version
+      // pointer, standing security alerts).
+      pin = /(?:^|\n)\s*pin:\s*(?:true|yes)\b/i.test(fm[1]);
+    }
+  } catch { /* missing file → treat as demotable, oldest */ }
+  return { type, mtime, pin };
+}
+
+const isRule = (type) => type === 'feedback' || type === 'user';
+// Never demoted: a standing rule (feedback_*/user) OR an explicitly pinned entry.
+const keepAlways = (meta) => isRule(meta.type) || !!meta.pin;
+
+// Decide what stays in the map and what gets demoted to the drawer.
+// Keep: every standing rule + the newest `keepNewest` of the rest; then, if still
+// over targetBytes, demote more from the oldest kept until under target.
+// Rules are NEVER demoted. Returns { newText, demote:[{file,title}], willChange }.
+function planCompaction(text, opts = {}) {
+  const memoryDir = opts.memoryDir;
+  const targetBytes = opts.targetBytes ?? TARGET_BYTES;
+  const keepNewest = opts.keepNewest ?? KEEP_NEWEST;
+  const meta = opts.metaOf || ((file) => metaOf(file, memoryDir, opts.deps));
+
+  const lines = parseLines(text);
+  const es = lines.filter((l) => l.entry);
+  const enriched = es.map((e) => ({ ...e, ...meta(e.file) }));
+
+  const rules = new Set(enriched.filter((e) => keepAlways(e)).map((e) => e.file));
+  const others = enriched.filter((e) => !keepAlways(e)).sort((a, b) => b.mtime - a.mtime); // newest first
+  const keptOthers = others.slice(0, keepNewest);
+  const demote = new Map(others.slice(keepNewest).map((e) => [e.file, e.title]));
+
+  // Still over target? Demote more from the OLDEST end of the kept others.
+  const sizeIfKept = () => {
+    const drop = new Set(demote.keys());
+    return Buffer.byteLength(lines.filter((l) => !(l.entry && drop.has(l.file))).map((l) => l.raw).join('\n') + '\n', 'utf8');
+  };
+  for (let i = keptOthers.length - 1; i >= 0 && sizeIfKept() > targetBytes; i--) {
+    demote.set(keptOthers[i].file, keptOthers[i].title);
+  }
+
+  const drop = new Set(demote.keys());
+  const keptLines = lines.filter((l) => !(l.entry && drop.has(l.file)));
+  const newText = keptLines.map((l) => l.raw).join('\n').replace(/\n*$/, '') + '\n';
+  return {
+    newText,
+    demote: [...demote.entries()].map(([file, title]) => ({ file, title })),
+    willChange: drop.size > 0,
+    keptCount: keptLines.filter((l) => l.entry).length,
+    ruleCount: rules.size,
+  };
+}
+
+// Parallel-safe apply: only write if the file on disk still matches what we read
+// (another concurrent session may have just rewritten it — don't clobber it).
+function applyCompaction(mapPath, expectedText, newText, deps = {}) {
+  const readFile = deps.readFile || ((p) => fs.readFileSync(p, 'utf8'));
+  const writeFile = deps.writeFile || ((p, c) => fs.writeFileSync(p, c));
+  let current;
+  try { current = readFile(mapPath); } catch { return { written: false, reason: 'missing' }; }
+  if (current !== expectedText) return { written: false, reason: 'changed-since-read' };
+  writeFile(mapPath, newText);
+  return { written: true };
+}
+
+module.exports = {
+  WARN_BYTES, TIDY_BYTES, TARGET_BYTES, MAX_LINE_CHARS, KEEP_NEWEST,
+  estTokens, parseLines, entries, measure, metaOf, isRule, keepAlways,
+  planCompaction, applyCompaction,
+};
+
+// CLI: `node scripts/gds/memory-map.js [--dir <memoryDir>] [--apply]`
+// Prints the measurement + the compaction plan; --apply writes it (parallel-safe).
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const dirArg = args.indexOf('--dir');
+  const memoryDir = dirArg >= 0 ? args[dirArg + 1] : process.env.OTB_MEMORY_DIR;
+  if (!memoryDir) { console.error('usage: memory-map.js --dir <memoryDir> [--apply]'); process.exit(2); }
+  const mapPath = path.join(memoryDir, 'MEMORY.md');
+  let text; try { text = fs.readFileSync(mapPath, 'utf8'); } catch { console.error('no MEMORY.md at', mapPath); process.exit(0); }
+  const m = measure(text);
+  console.log(`map: ${m.bytes} bytes (~${m.tokens} tok), ${m.count} entries · overWarn=${m.overWarn} overTidy=${m.overTidy} · longLines=${m.longLines.length}`);
+  const plan = planCompaction(text, { memoryDir });
+  if (!plan.willChange) { console.log('nothing to demote — map is within target.'); process.exit(0); }
+  console.log(`would demote ${plan.demote.length} entries to the drawer (topic files kept):`);
+  for (const d of plan.demote) console.log(`  - ${d.file}`);
+  if (args.includes('--apply')) {
+    const r = applyCompaction(mapPath, text, plan.newText);
+    console.log(r.written ? `applied — map now ${Buffer.byteLength(plan.newText)} bytes` : `not written (${r.reason})`);
+  }
+}

package/scripts/gds/merge-lock.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// CLI wrapper so the /merge-mode skill shares the SAME merge mutex as ship.js's
+// auto-merge (V3.R50 / #269, criterion C6). Before #269 the lock lived inside
+// ship.js, so a manual /merge-mode run could collide with a concurrent ship on
+// the shared main worktree. /merge-mode now acquires this lock before it
+// checks out main + merges, and releases it after deploy.
+//
+// Usage:
+//   node scripts/gds/merge-lock.js acquire   # blocks up to 30s; exit 0 acquired, 3 if held
+//   node scripts/gds/merge-lock.js release   # remove a manual hold
+//   node scripts/gds/merge-lock.js status    # report holder + age
+//
+// The hold is recorded as mode='manual' (pid=0) because the acquiring CLI
+// process exits immediately — there's no long-lived owner. Manual holds are
+// reclaimed by time only (merge-lock.MANUAL_STALE_MS), so an operator who
+// walks away mid-merge doesn't deadlock the queue forever.
+
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+// the merge-lock lib carved to modules/lifecycle/ (BV1.R86); a CLI may require a
+// module directly (outside the kernel boundary — the grading/economy precedent).
+const lock = require('../../modules/lifecycle/merge-lock');
+
+// Resolve the main checkout root regardless of which worktree we're invoked
+// from: dirname of the shared common .git directory. Rename-proof — matches
+// the /merge-mode SKILL.md REPO_ROOT derivation and ship.js's findMainWorktree.
+function mainWorktreeRoot() {
+  const common = execSync('git rev-parse --git-common-dir', {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+  const abs = path.isAbsolute(common) ? common : path.resolve(process.cwd(), common);
+  return path.dirname(abs);
+}
+
+const cmd = process.argv[2];
+let root;
+try {
+  root = mainWorktreeRoot();
+} catch (e) {
+  console.error('merge-lock: not a git repo (cannot resolve main worktree):', e.message);
+  process.exit(2);
+}
+
+if (cmd === 'acquire') {
+  // Manual hold: pid=0 (no long-lived owner), reclaimed by time only.
+  const ok = lock.acquire(root, { mode: 'manual', pid: 0, waitMs: 30000 });
+  if (ok) {
+    console.log('merge-lock: acquired (manual hold). Release with `node scripts/gds/merge-lock.js release` when the merge run is done.');
+    process.exit(0);
+  }
+  console.error('merge-lock: held by another ship or merge run — wait and retry, or run `merge-lock status` to inspect the holder.');
+  process.exit(3);
+} else if (cmd === 'release') {
+  lock.release(root);
+  console.log('merge-lock: released.');
+  process.exit(0);
+} else if (cmd === 'status') {
+  const rec = lock.readLock(root);
+  if (!rec) {
+    console.log('merge-lock: free.');
+    process.exit(0);
+  }
+  const ageS = Math.round((Date.now() - rec.ts) / 1000);
+  const stale = lock.isStale(rec) ? ' (STALE — reclaimable)' : '';
+  console.log(`merge-lock: HELD  mode=${rec.mode}  pid=${rec.pid}  age=${ageS}s${stale}`);
+  process.exit(0);
+} else {
+  console.error('usage: node scripts/gds/merge-lock.js acquire|release|status');
+  process.exit(2);
+}