@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/land-watch.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/bongos/land-watch.js — show the SHIPPED banner once an async CI land completes.
+//
+// THE GAP (task 1687). In CI deploy mode /builder-ship arms auto-merge and EXITS at
+// status=confirmed; the real confirmed->shipped land happens minutes later, server-side
+// (GitHub auto-merge + the 5-min publish-reconciler). So the last card the builder sees
+// is the "confirmed — landing" banner — the SHIPPED success banner ship-card.js already
+// models never renders in-session (observed on task 1211/PR #512).
+//
+// THE MECHANISM (non-blocking, next-turn). ship.js drops a small PENDING-LAND breadcrumb
+// when it exits at confirmed (it owns writeBreadcrumb below, so the schema lives in ONE
+// place). On a later prompt the land-watch-card hook runs this in --hook mode: it reads
+// the breadcrumbs, GETs each task, and when one has flipped to `shipped` it renders the
+// shipped lifecycle card (reusing ship-card.js — the same card ship.js would have shown)
+// and clears the breadcrumb. Terminal-non-shipped or stale breadcrumbs are dropped. With
+// no breadcrumb it does nothing (the common case) — the hook is a fast no-op when idle.
+//
+// Read-only + safe: it never mutates GDS state; it only reads task status and renders.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { SESSION_PATH, cliClient, cliExit } = require('./cli-lib');
+const shipCard = require('../../modules/lifecycle/ship-card');
+
+// Breadcrumbs live beside the session token (per-machine, per-instance config dir —
+// NOT in the repo, so they are never committed). Derive the dir from SESSION_PATH so
+// it tracks the instance-config resolution (OTB → ~/.config/otb/pending-land/).
+const PENDING_DIR = path.join(path.dirname(SESSION_PATH || ''), 'pending-land');
+const DEFAULT_STALE_MS = 30 * 60 * 1000; // stop watching a land that never completes
+
+function ensureDir() {
+  try { fs.mkdirSync(PENDING_DIR, { recursive: true }); } catch (_) { /* best-effort */ }
+}
+
+// Written by ship.js at confirmed-exit. Atomic (tmp + rename) so a concurrent read can
+// never see a half-written file. `data` = { branch, widgetsEnabled, cardInputs } where
+// cardInputs is exactly the object ship.js passed to buildCardModel (postGradeStatus is
+// overridden to 'shipped' at render time).
+function writeBreadcrumb(taskId, data = {}) {
+  const id = String(taskId);
+  if (!/^\d+$/.test(id)) return null;
+  ensureDir();
+  const dest = path.join(PENDING_DIR, `${id}.json`);
+  const tmp = `${dest}.tmp`;
+  const row = { taskId: id, at: new Date().toISOString(), ...data };
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(row), 'utf8');
+    fs.renameSync(tmp, dest);
+    return dest;
+  } catch (_) {
+    try { fs.rmSync(tmp, { force: true }); } catch (__) { /* ignore */ }
+    return null;
+  }
+}
+
+function readBreadcrumbs() {
+  let names = [];
+  try { names = fs.readdirSync(PENDING_DIR); } catch (_) { return []; } // dir absent → none
+  const out = [];
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    const file = path.join(PENDING_DIR, name);
+    try {
+      const row = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (row && typeof row === 'object' && /^\d+$/.test(String(row.taskId))) out.push({ ...row, _file: file });
+    } catch (_) { /* skip a corrupt/partial file */ }
+  }
+  return out;
+}
+
+function removeBreadcrumb(fileOrId) {
+  const file = typeof fileOrId === 'string' && fileOrId.endsWith('.json')
+    ? fileOrId
+    : path.join(PENDING_DIR, `${fileOrId}.json`);
+  try { fs.rmSync(file, { force: true }); } catch (_) { /* ignore */ }
+}
+
+// PURE decision — exported so the truth table is unit-tested with no fs/network.
+//   'emit' → the task landed inside the watch window: render the shipped card, then clear.
+//   'drop' → give up watching: past the window, OR it left the land path (grade-failed back
+//            to completed, released, …) so the confirmed→shipped transition won't happen.
+//   'keep' → still landing (confirmed), or a transient read failure — retry next turn.
+//
+// The window wins over EVERY status, 'shipped' included (task 1003466). It used not to:
+// 'emit' was checked first, so a breadcrumb for a task that landed days ago still rendered a
+// "Shipped" banner. That went unnoticed until a dead publish-reconciler (task 1002419) let a
+// backlog build — eleven tasks flipped to shipped at once and the builder paid a prompt-turn
+// of stale news for each. A land the builder has already moved past is not news; it is spam.
+// An unknown/unparseable age is treated as past the window for the same reason: we cannot
+// prove the crumb is fresh, and the safe direction is always silence.
+function classifyLand(task, ageMs, { staleMs = DEFAULT_STALE_MS } = {}) {
+  if (!Number.isFinite(ageMs) || ageMs > staleMs) return 'drop';
+  if (task && task.status === 'shipped') return 'emit';
+  if (!task || typeof task.status !== 'string') return 'keep'; // couldn't read → retry
+  if (task.status === 'confirmed') return 'keep';               // still landing
+  return 'drop';                                                // no longer on the land path
+}
+
+async function fetchTask(taskId) {
+  try {
+    const api = await cliClient({ allowUnauthenticated: true });
+    const r = await api.tasks.getTasksId({ id: taskId });
+    return r?.data?.task ?? r?.data ?? null;
+  } catch (_) {
+    return null; // transient → classifyLand keeps it for a retry
+  }
+}
+
+// Build the { widgets_enabled, html, markdown, warnings, title } envelope (the same
+// shape session-cards.js consumes) for a landed breadcrumb, reusing ship-card.js so the
+// shipped banner is byte-identical to what ship.js emits inline. `nowMs` is injected for
+// determinism in tests.
+function buildShippedEnvelope(crumb, task) {
+  const inputs = (crumb && crumb.cardInputs && typeof crumb.cardInputs === 'object') ? crumb.cardInputs : {};
+  const model = shipCard.buildCardModel({
+    ...inputs,
+    postGradeStatus: 'shipped',
+    taskId: crumb.taskId,
+    // Prefer a fact from the fresh task row when the breadcrumb didn't carry it.
+    title: inputs.title || (task && task.title) || `Task #${crumb.taskId}`,
+    valueSummary: inputs.valueSummary || (task && task.value_summary) || '',
+  });
+  // task 1002518: prefer the rung the shipping session actually resolved, so the
+  // later-rendered shipped card matches the one it printed. A breadcrumb written
+  // by an older CLI carries only `widgetsEnabled`, which still reads correctly.
+  const flags = (crumb.cardFlags && typeof crumb.cardFlags === 'object')
+    ? crumb.cardFlags
+    : { showWidget: crumb.widgetsEnabled !== false, expanded: false };
+  return {
+    widgets_enabled: flags.showWidget === true,
+    html: shipCard.renderCardHtml(model, { expanded: flags.expanded === true }),
+    markdown: shipCard.renderMonospaceCard(model),
+    warnings: [],
+    title: `task_${crumb.taskId}_card`,
+  };
+}
+
+// Walk the breadcrumbs; emit AT MOST ONE shipped card per run (avoid flooding a turn),
+// dropping the give-ups. Returns the envelope to inject, or null. Deps injected for tests.
+//
+// The backlog drains in THIS pass (task 1003466): the newest land gets the card and every
+// other landed crumb is folded into one "also landed" line and cleared. Holding the extras
+// for later turns is what turned a backlog into a card per prompt — the builder had to ask
+// why the session kept showing cards instead of working.
+async function watch({ nowMs = Date.now(), staleMs = DEFAULT_STALE_MS, getTask = fetchTask, readCrumbs = readBreadcrumbs, removeCrumb = removeBreadcrumb } = {}) {
+  const crumbs = readCrumbs().sort((a, b) => String(b.at).localeCompare(String(a.at))); // newest first
+  let envelope = null;
+  const alsoLanded = [];
+  for (const crumb of crumbs) {
+    const at = Date.parse(crumb.at || '');
+    const ageMs = Number.isFinite(at) ? nowMs - at : Infinity; // unparseable → past the window
+    const task = await getTask(crumb.taskId);
+    const verdict = classifyLand(task, ageMs, { staleMs });
+    if (verdict === 'emit') {
+      if (!envelope) envelope = buildShippedEnvelope(crumb, task);
+      else alsoLanded.push(crumb.taskId);
+      removeCrumb(crumb._file);
+    } else if (verdict === 'drop') {
+      removeCrumb(crumb._file);
+    }
+    // 'keep' → leave it
+  }
+  // Written as `task N`, never `#N` — a bare #NNN autolinks to a GitHub issue and 404s.
+  if (envelope && alsoLanded.length) {
+    envelope.warnings = [`Also landed: ${alsoLanded.map((id) => `task ${id}`).join(', ')}.`];
+  }
+  return envelope;
+}
+
+module.exports = {
+  PENDING_DIR, DEFAULT_STALE_MS,
+  writeBreadcrumb, readBreadcrumbs, removeBreadcrumb,
+  classifyLand, buildShippedEnvelope, watch,
+};
+
+// CLI. `--hook`: print ONLY the envelope JSON on stdout when a card should render (the
+// land-watch-card hook parses it); nothing otherwise. Bare: a human-readable summary.
+if (require.main === module) {
+  const hookMode = process.argv.includes('--hook');
+  (async () => {
+    // task 1002592: every exit below routes through cliExit (task 1002734's rule).
+    // This script exits 0 on ALL paths on purpose — it is hook-invoked and must
+    // never report failure — but on Windows the post-request teardown aborted with
+    // "Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)" and handed the hook
+    // 127, which conventionally reads as "command not found". Measured 3/3 before
+    // this change: the one script written never to fail always reported failure.
+    // Draining also lets the --hook stdout write flush, which a hard exit can cut
+    // mid-JSON — the card hook parses that stdout.
+    // Cheap idle fast-path: no breadcrumbs → do nothing (no network).
+    if (readBreadcrumbs().length === 0) { if (!hookMode) console.error('land-watch: no pending lands.'); return cliExit(0); }
+    const envelope = await watch();
+    if (hookMode) {
+      if (envelope) process.stdout.write(JSON.stringify(envelope));
+      return cliExit(0);
+    }
+    console.error(envelope ? `land-watch: a task landed — shipped card ready (${envelope.title}).` : 'land-watch: nothing landed this pass.');
+    return cliExit(0);
+  })().catch(() => cliExit(0)); // never throw from a hook-invoked script
+}

package/scripts/bongos/leak-scan-allowlist.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/bongos/leak-scan-allowlist.js — the NAMED, REASONED exceptions to the
+// prior-instance leak scan (task 1003869, the public-@bongos/core gate).
+//
+// WHY THIS EXISTS. scanArtifactForLeaks (scripts/bongos/package-core.js) flags any
+// prior-instance literal or public IP anywhere in the built artifact. Most hits are
+// real and get swept at source. A residue is not: some files must contain the very
+// string the scan looks for, because containing it is their job. A detector has to
+// carry the pattern it detects; a test that proves "a public IP is flagged" has to
+// hand the scanner a public IP. Those cannot be swept — swept, the tests stop
+// testing — so they are recorded HERE, each one named with the reason it stays.
+//
+// THE RULE THIS FILE ENFORCES ON ITSELF. An entry is (path, classes, reason). Never
+// a bare path: allowlisting a whole FILE would let a genuinely new leak ride into an
+// already-listed file unnoticed, which is precisely the failure mode the scan exists
+// to prevent. A literal whose class is not named for that path is still a hard failure.
+//
+// STALENESS IS A FAILURE TOO. unusedEntries() reports entries that matched nothing.
+// An allowlist nobody prunes becomes a list of permissions nobody remembers granting,
+// so the sweep's own test asserts every entry still earns its place.
+
+// Addresses that are never ANY instance's topology: public resolvers, IANA's
+// documentation host, and a well-known forge. Global rather than per-file because
+// the safety here comes from the literal itself, not from which file holds it —
+// 8.8.8.8 is Google's resolver in every file in the world. RFC-reserved ranges
+// (5737 TEST-NET, 2544 benchmarking, 3849 v6 doc) are NOT here: those are handled
+// a layer down in mirror-redact.js, which never classes them public to begin with.
+const WELL_KNOWN_PUBLIC_IPS = {
+  '8.8.8.8': 'Google Public DNS — the canonical example resolver',
+  '8.8.4.4': 'Google Public DNS, secondary',
+  '1.1.1.1': 'Cloudflare DNS — the canonical example resolver',
+  '1.0.0.1': 'Cloudflare DNS, secondary',
+  '9.9.9.9': 'Quad9 DNS — a public resolver used as a probe fixture',
+  '4.4.4.4': 'a public resolver address used as a second, distinct fixture',
+  '1.2.3.4': 'the conventional placeholder quad — routable, so it exercises the "public" branch, but nobody here owns it',
+  '3.8.8.8': 'a near-miss of 8.8.8.8, used to prove the match is exact and not a prefix',
+  '93.184.216.34': "IANA's example.com — the documentation host, by definition not ours",
+  '140.82.121.4': 'github.com — a public forge, reached by name everywhere else in the tree',
+  '2606:4700:4700::1111': 'Cloudflare DNS over IPv6 — the v6 counterpart of 1.1.1.1',
+  '2606:2800:220:1:248:1893:25c8:1946': "IANA's example.com over IPv6",
+};
+
+// (path, classes, reason). Scoped to one file and the classes that file legitimately
+// carries; see floorLiteralsFor() below for why an entry names a class, not a string.
+const FILE_ALLOWLIST = [
+  {
+    path: 'scripts/bongos/mirror-redact.js',
+    classes: ['public-ip'],
+    reason:
+      'This file IS the IP detector. Its RFC range comments and boundary-guard doc comments '
+      + 'quote address forms so the next reader can see what each guard rejects. The same '
+      + "self-reference the file's own SELF-LEAK INVARIANT describes for instance literals: it "
+      + 'carries no instance topology, only universal RFC constants.',
+  },
+  {
+    path: 'scripts/bongos/audit-authorship.sh',
+    classes: ['owner', 'token'],
+    reason:
+      'This IS the authorship detector. Its PATTERN and SPEC_ALLOWLIST_PATTERN must contain the '
+      + 'literals verbatim or they match nothing — the script exists to find exactly these. '
+      + 'Neutralising them here would silently disarm the audit that keeps them out elsewhere.',
+  },
+  {
+    path: 'tests/package_core.mjs',
+    classes: ['token', 'owner', 'public-ip'],
+    reason:
+      "The leak scanner's own test suite. It feeds scanArtifactForLeaks each literal and a "
+      + 'routable address and asserts they are flagged; with neutral fixtures it would assert '
+      + "nothing. The addresses it uses are placeholders (1.2.3.4), never this instance's.",
+  },
+  {
+    path: 'tests/mirror_redact.mjs',
+    classes: ['public-ip'],
+    reason:
+      'The redactor/detector test suite. It must hand firstPublicIP genuinely routable v4 and v6 '
+      + 'addresses to prove the narrowing guards did not blunt the gate, and near-miss forms '
+      + '(leading-zero octets, ::/8 shorthand) to prove they are rejected. Public resolvers only.',
+  },
+  {
+    path: 'tests/public_mirror_export.mjs',
+    classes: ['public-ip'],
+    reason:
+      'Exercises redactBlob end to end, which requires an address that survives to the gate. '
+      + 'Uses the synthetic-instance fixtures declared at the top of that file.',
+  },
+  // ── the DEFINITIONS the scan itself reads ──────────────────────────────────────────
+  {
+    path: 'scripts/bongos/package-core.js',
+    classes: ['token', 'owner'],
+    reason:
+      'Holds PRIOR_INSTANCE_FLOOR — the single definition of what counts as a prior-instance '
+      + 'literal, which this allowlist and the scan both read. The list cannot be neutral without '
+      + 'the scan matching nothing at all.',
+  },
+  {
+    path: 'scripts/bongos/fitness-checks-identity.js',
+    classes: ['token'],
+    reason:
+      'The identity fitness check. Its rule array IS a case-insensitive regex per host-brand '
+      + 'literal — the patterns that stop a brand being re-hardcoded anywhere else in the tree. '
+      + 'Neutralising them disarms the check that keeps the rest of this sweep from regressing. '
+      + '(Described, not quoted: quoting the patterns here put them straight back into a shipped '
+      + 'file, and the check itself caught this file doing exactly that.)',
+  },
+  {
+    path: 'scripts/bongos/publish-manifest.js',
+    classes: ['token'],
+    reason:
+      'The exclusion list names real excluded FILES (the instance-decouple recipes). A path is not '
+      + 'prose — renamed, it stops matching and the excluded docs start publishing.',
+  },
+
+  // ── the literal IS the test subject ────────────────────────────────────────────────
+  // These four PLANT a host-brand literal and assert a guard catches it, or compare a
+  // fixture against this instance's real identity. Neutralising the literal does not make
+  // the test neutral — it makes it pass while proving nothing, which is worse than the hit
+  // it removes. Each was caught by the suite when a first sweep renamed it (task 1003869).
+  {
+    path: 'tests/fitness.mjs',
+    classes: ['token'],
+    reason:
+      'The identity gate\'s "not a no-op" proof plants a bare host-brand literal in code, a URL '
+      + 'and HTML, and asserts the gate reports all three. A neutral literal is not caught, so the '
+      + 'test would assert the gate works by handing it nothing to find.',
+  },
+  {
+    path: 'tests/government_vanilla_boot.mjs',
+    classes: ['token'],
+    reason:
+      'Same shape: it plants a host brand in the NEUTRAL config pack and asserts the identity '
+      + 'guard catches it. The planted string has to be a real host brand or there is nothing to catch.',
+  },
+  {
+    path: 'tests/module_provenance.mjs',
+    classes: ['token'],
+    reason:
+      "Asserts a module whose origin equals THIS instance's name resolves as own-built rather than "
+      + 'core-loaded. The fixture must carry the real identity for the comparison to mean anything; '
+      + 'renamed, it silently classified own-built modules as core.',
+  },
+  {
+    path: 'tests/claude_materialize.mjs',
+    classes: ['token'],
+    reason:
+      'Tests the REBRAND rules, whose whole job is rewriting a founder brand to a target. The '
+      + 'literal is the input being rewritten and the assertion is that it does not survive; '
+      + 'neutralising it collides with the example.org targets the same test rebrands TO.',
+  },
+  {
+    path: 'tests/cli_lib_formatters.mjs',
+    classes: ['token'],
+    reason:
+      'A negative assertion — that the formatter does not reintroduce a hardcoded founder host. '
+      + 'The literal is what must be absent, so it has to be named to be checked for.',
+  },
+  {
+    path: 'tests/smoke_target.mjs',
+    classes: ['token'],
+    reason:
+      'Four assert.doesNotMatch calls proving the smoke target resolves to THIS instance and never '
+      + 'the old hardcoded founder fallback. The literal is what must be absent — a test for its '
+      + 'absence has to name it, and neutralised the guard would pass against anything.',
+  },
+  {
+    path: 'tests/lib_sh_resolution.mjs',
+    classes: ['token'],
+    reason:
+      'Carries the host-identity scan pattern it runs over the bash smoke scripts — a detector '
+      + 'pattern, the same case as fitness-checks-identity.js.',
+  },
+  {
+    path: 'modules/provisioning/module.json',
+    classes: ['token'],
+    reason:
+      'author / origin / maintainer. This is genuine AUTHORSHIP attribution in an AGPL module '
+      + 'manifest, not leaked topology — naming who wrote a module is what a manifest is for. '
+      + 'Left as the owner wrote it: how a contributor is credited is the owner\'s call, not a '
+      + 'sweep\'s. Raise it with them if the core should attribute to the project instead.',
+  },
+
+  // ── migrations: already applied, therefore immutable ───────────────────────────────
+  // A migration that has run on every existing instance cannot be edited: the text is the
+  // historical record of what happened, and rewriting it desynchronises new installs from
+  // old ones without changing a single existing database. Listed file by file ON PURPOSE —
+  // a NEW migration naming a host brand is a real defect and must still fail the scan.
+  { path: 'migrations/003_pms.sql', classes: ['token'], reason: 'applied migration — comment names the status page of the instance it was written for' },
+  { path: 'migrations/006_pms_v2.sql', classes: ['token'], reason: 'applied migration — records where instance-scope rows were relocated' },
+  { path: 'migrations/011_backfill_v2_v3_done_when.sql', classes: ['token'], reason: 'applied migration — backfills done_when prose that names the instance' },
+  { path: 'migrations/067_builder_boxes.sql', classes: ['token'], reason: 'applied migration — documents the per-builder DNS shape in use at the time' },
+  { path: 'migrations/093_tasks_sandbox_review.sql', classes: ['token'], reason: 'applied migration — sample sandbox URL in a column comment' },
+  { path: 'migrations/111_medusa_customer0_framing.sql', classes: ['token'], reason: 'applied migration — the customer-zero framing IS its subject' },
+  { path: 'migrations/185_module_upstreaming_goal_wiring.sql', classes: ['token'], reason: 'applied migration — names the historical extract-core/split work items' },
+  { path: 'migrations/core_191_module_submissions.sql', classes: ['owner'], reason: 'applied migration — names the private upstream repo it explains the absence of' },
+
+  {
+    path: 'modules/public-landing/public/projects.html',
+    classes: ['public-ip'],
+    reason:
+      'Dense SVG path coordinates. The inlined forge logo contains runs like "…1.08.58 1.23.82.72 '
+      + '1.21…", which are four dot-separated numbers under 256 and therefore a valid dotted quad by '
+      + 'SHAPE — no guard can separate them from an address without knowing they sit in a path "d" '
+      + 'attribute, the same "why not a shape rule" secret-scrub.js records. The leading-zero guard '
+      + 'catches the variants that have one; this is the residue. No topology here, only geometry.',
+  },
+  {
+    path: 'modules/security/tests/artifact_scan.mjs',
+    classes: ['public-ip'],
+    reason: "The security module's scanner test — same reason as tests/package_core.mjs.",
+  },
+];
+
+// SELF-LEAK INVARIANT (the same one scripts/bongos/mirror-redact.js holds about itself,
+// and enforced on this file by scripts/bongos/audit-authorship.sh). An allowlist that
+// spelled out the literals it governs would reintroduce customer-zero's name into two
+// more shipped files — defeating the sweep that motivated it. So an entry names a
+// CLASS ('owner', 'token') and the concrete strings are resolved at call time from
+// PRIOR_INSTANCE_FLOOR, which is already the one definition package-core scans by.
+// Scoping is unchanged where it matters: an entry still only covers the file it names.
+function floorLiteralsFor(cls) {
+  const floor = require('./package-core.js').PRIOR_INSTANCE_FLOOR;
+  if (cls === 'owner') return floor.owners.map((s2) => s2.toLowerCase());
+  if (cls === 'token') return floor.tokens.map((s2) => s2.toLowerCase());
+  return [];
+}
+
+// Every concrete literal an entry's classes resolve to, plus 'public-ip' verbatim.
+function entryLiterals(entry) {
+  const out = [];
+  for (const c of entry.classes || []) {
+    if (c === 'public-ip') out.push('public-ip');
+    else out.push(...floorLiteralsFor(c));
+  }
+  return out;
+}
+
+const SEP = '>>';
+
+// The key a hit is looked up by. An IP hit collapses to the label (any well-known
+// address in an allowlisted file is covered by that file's reason); an instance
+// literal is keyed by the literal itself, so listing one never covers another.
+function hitKey(pathRel, label, sample) {
+  return `${pathRel}${SEP}${label === 'public-ip' ? 'public-ip' : String(sample).toLowerCase()}`;
+}
+
+// The reason a hit is tolerated, or null if it is not. `label` distinguishes an IP hit
+// ('public-ip') from an instance-literal hit, matching findLeaks' own labelling.
+function allowReason(pathRel, label, sample) {
+  if (label === 'public-ip' && Object.prototype.hasOwnProperty.call(WELL_KNOWN_PUBLIC_IPS, sample)) {
+    return `well-known address: ${WELL_KNOWN_PUBLIC_IPS[sample]}`;
+  }
+  const key = hitKey(pathRel, label, sample);
+  for (const e of FILE_ALLOWLIST) {
+    for (const l of entryLiterals(e)) {
+      if (`${e.path}${SEP}${l.toLowerCase()}` === key) return e.reason;
+    }
+  }
+  return null;
+}
+
+// Split scan hits into the ones a named exception covers and the ones that remain.
+function partitionHits(hits) {
+  const allowed = [];
+  const remaining = [];
+  for (const h of hits || []) {
+    const reason = allowReason(h.path, h.label, h.sample);
+    if (reason) allowed.push({ ...h, reason }); else remaining.push(h);
+  }
+  return { allowed, remaining };
+}
+
+// Entries that covered nothing in this scan — a stale permission. Reported so the
+// allowlist shrinks as the trunk gets cleaner instead of quietly outliving its reasons.
+function unusedEntries(hits) {
+  const seen = new Set((hits || []).map((h) => hitKey(h.path, h.label, h.sample)));
+  const stale = [];
+  for (const e of FILE_ALLOWLIST) {
+    // Staleness is per CLASS, not per resolved literal. A grant of 'token' covers every
+    // token in the floor, and a file that legitimately carries one of them but not the
+    // other is not a stale permission — reporting it as one would fire on a healthy tree
+    // forever, and a warning that never goes away is one nobody reads.
+    for (const cls of e.classes || []) {
+      const lits = cls === 'public-ip' ? ['public-ip'] : floorLiteralsFor(cls);
+      if (!lits.some((l) => seen.has(`${e.path}${SEP}${l.toLowerCase()}`))) {
+        stale.push({ path: e.path, literal: cls });
+      }
+    }
+  }
+  return stale;
+}
+
+module.exports = { WELL_KNOWN_PUBLIC_IPS, FILE_ALLOWLIST, entryLiterals, allowReason, partitionHits, unusedEntries };

package/scripts/bongos/learning-capture.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// Capture a learning — durable storage in the GDS DB (Phase 2b: the DB is
+// now the only canonical home for short-form learnings; long-form recipes
+// live under docs/recipes/).
+//
+// Usage:
+//   node scripts/bongos/learning-capture.js \
+//     --tags "caddy,cloudflare" \
+//     --title "Origin cert needs *.example.com SAN" \
+//     --body-file path/to/body.md
+//
+// Body source (in priority order): --body-file PATH > --body "text" > stdin.
+// Related files: --files "infra/Caddyfile,..." > auto-detected `git diff --name-only HEAD`.
+// Idempotency: --source / --source-ref pair acts as soft-key (server skips on duplicate).
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+const { cliClient, requireSession, arg } = require('./cli-lib');
+
+
+function csv(v) {
+  if (!v) return [];
+  return String(v).split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+async function readStdin() {
+  return new Promise((resolve, reject) => {
+    if (process.stdin.isTTY) return resolve('');
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => (data += chunk));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+function autoDetectFiles() {
+  try {
+    const out = execSync('git diff --name-only HEAD', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out.split('\n').map((s) => s.trim()).filter(Boolean);
+  } catch (_) {
+    return [];
+  }
+}
+
+
+(async () => {
+  await requireSession();
+  const args = process.argv.slice(2);
+
+  const title = arg('--title', args);
+  const tags = csv(arg('--tags', args));
+  const bodyFile = arg('--body-file', args);
+  const bodyInline = arg('--body', args);
+  const filesArg = arg('--files', args);
+  const source = arg('--source', args);
+  const sourceRef = arg('--source-ref', args);
+  const taskIdStr = arg('--task-id', args);
+  const taskId = taskIdStr ? Number(taskIdStr) : null;
+  const dryRun = args.includes('--dry-run');
+
+  if (!title || tags.length === 0) {
+    console.error('usage: node scripts/bongos/learning-capture.js --tags "a,b" --title "..." (--body-file PATH | --body "..." | stdin) [--files "f,g"] [--source manual] [--source-ref id] [--task-id N] [--dry-run]');
+    process.exit(2);
+  }
+
+  let body;
+  if (bodyFile) {
+    try {
+      body = await fsp.readFile(bodyFile, 'utf8');
+    } catch (err) {
+      console.error(`failed to read --body-file ${bodyFile}: ${err.message}`);
+      process.exit(2);
+    }
+  } else if (bodyInline) {
+    body = bodyInline;
+  } else {
+    body = await readStdin();
+  }
+  if (!body || !body.trim()) {
+    console.error('body is empty (provide via --body-file PATH, --body "...", or piped stdin)');
+    process.exit(2);
+  }
+
+  const relatedFiles = filesArg ? csv(filesArg) : autoDetectFiles();
+
+  // Find current builder login so the file footer says who captured.
+  let capturedByLogin = null;
+  try {
+    const api = await cliClient();
+    const me = await api.me.getMe();
+    if (me.ok) capturedByLogin = me.data?.builder?.github_login ?? null;
+  } catch (_) {}
+
+  if (dryRun) {
+    console.log('=== DRY RUN ===');
+    console.log('POST /api/bongos/learnings:');
+    console.log(JSON.stringify({
+      title, body_md: body, tags, related_files: relatedFiles, source, source_ref: sourceRef, task_id: taskId,
+    }, null, 2));
+    process.exit(0);
+  }
+
+  const api = await cliClient();
+  const r = await api.learnings.postLearnings({
+    body: {
+      title,
+      body_md: body,
+      tags,
+      related_files: relatedFiles,
+      source,
+      source_ref: sourceRef,
+      task_id: taskId,
+    },
+  });
+
+  if (r.status === 200 && r.data?.skipped) {
+    console.log(`Skipped: duplicate (source=${source}, source_ref=${sourceRef}) already captured.`);
+    return;
+  }
+  if (r.status !== 201) {
+    console.error(`capture failed (${r.status}):`, r.data);
+    process.exit(1);
+  }
+
+  const { learning } = r.data;
+  console.log(`Captured learning #${learning.id}: ${learning.title}`);
+  console.log(`Tags: ${learning.tags.join(', ')}`);
+  if (learning.related_files?.length) {
+    console.log(`Related files: ${learning.related_files.join(', ')}`);
+  }
+  console.log('Stored in GDS DB. Query with: node scripts/bongos/learning-list.js (TBD) or GET /api/bongos/learnings');
+  // Phase 2b — the per-tag markdown append was removed. The DB is now the
+  // canonical store for short-form learnings; long-form operational recipes
+  // live separately under docs/recipes/.
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});