@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/recall.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+// scripts/bongos/recall.js — one-call project-knowledge search (task 955, V4.R17 /
+// ADR 0060). Wraps POST /api/bongos/search: lexical (FTS + pg_trgm) fused with RRF,
+// rank/owner-scoped server-side (a sub-Metic caller never sees protected docs;
+// you only ever see your own private chunks). Authenticated — reads the builder
+// session like every other /builder-* CLI.
+//
+// Progressive disclosure (ADR 0095 C1 / task 1658): a plain `recall <query>`
+// returns the COMPACT summary layer — each hit shows a snippet plus its token
+// cost (what you see now vs. what a full expansion would cost), so you see the
+// price before paying it. `recall --expand <id>` then fetches one hit's full
+// content. Step 1 surfaces what's relevant + cheap; step 2 spends tokens only on
+// the hit you actually want.
+//
+// Usage:
+//   node scripts/bongos/recall.js <query…>            # step 1: ranked summary + per-hit token cost
+//   node scripts/bongos/recall.js "trust boundary" --limit 5
+//   node scripts/bongos/recall.js grader bypass --kind doc
+//   node scripts/bongos/recall.js --expand 1234       # step 2: full content of hit #1234
+//   node scripts/bongos/recall.js <query…> --json     # raw JSON (for scripts)
+
+const { cliClient } = require('./cli-lib');
+
+function parseArgs(argv) {
+  const out = { terms: [], limit: undefined, kind: undefined, json: false, expand: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') out.json = true;
+    else if (a === '--limit') out.limit = Number(argv[++i]);
+    else if (a === '--kind') out.kind = argv[++i];
+    else if (a === '--expand') out.expand = Number(argv[++i]);
+    else if (a.startsWith('--limit=')) out.limit = Number(a.slice(8));
+    else if (a.startsWith('--kind=')) out.kind = a.slice(7);
+    else if (a.startsWith('--expand=')) out.expand = Number(a.slice(9));
+    else out.terms.push(a);
+  }
+  out.q = out.terms.join(' ').trim();
+  return out;
+}
+
+function truncate(s, n) {
+  const t = String(s || '').replace(/\s+/g, ' ').trim();
+  return t.length > n ? t.slice(0, n - 1) + '…' : t;
+}
+
+function reportError(r) {
+  if (r.status === 401) {
+    console.error(`Not signed in. Run ${require('./surface').action('setup')} first — recall searches as you, so it can scope results to your rank.`);
+  } else if (r.status === 429) {
+    console.error(`Rate limited (${r.data && r.data.retry_after_seconds ? r.data.retry_after_seconds + 's' : 'slow down'}). Recall is capped per builder per minute.`);
+  } else {
+    console.error(`recall failed (${r.status}):`, r.data);
+  }
+}
+
+// Step 2 — fetch + print one hit's full content (the EXPAND half).
+async function runExpand(args) {
+  const api = await cliClient();
+  const r = await api.search.postSearch({ body: { expand: args.expand } });
+  if (!r.ok) {
+    if (r.status === 404) {
+      console.error(`No chunk #${args.expand} visible to you. Re-run the search to get a current id (ids are stable but a chunk may be above your rank).`);
+    } else {
+      reportError(r);
+    }
+    process.exit(1);
+  }
+  if (args.json) { console.log(JSON.stringify(r.data, null, 2)); return; }
+  const c = r.data.chunk;
+  console.log(`${c.title || c.source_ref}`);
+  console.log(`${c.heading_path || c.source_ref}`);
+  console.log(`${c.source_ref}  ·  ~${c.body_tokens} tokens\n`);
+  console.log(c.body);
+}
+
+
+// task 1003097: the zero-result message, as a PURE function of (query, corpus)
+// so the three outcomes are unit-tested instead of eyeballed.
+//
+// The old single line hedged — "or it may not be indexed yet" — which reads
+// identically whether the index is fine or completely dead. /recall returned zero
+// for EVERY query for weeks and this sentence was the only thing a builder saw,
+// so it read as "we have never touched this" and sessions re-derived work that
+// already existed. Returns { stream, lines, exitCode }: an OUTAGE goes to stderr
+// with a non-zero exit, because a scheduled routine scripting /recall has to be
+// able to tell a broken index from an honest miss.
+function renderNoMatch({ q, corpus }) {
+  if (!corpus || !corpus.message) {
+    // Older server with no corpus diagnostic — previous wording, unchanged.
+    return {
+      stream: 'out',
+      exitCode: 0,
+      lines: [`No matches for "${q}". The index covers repo docs + (nightly) DB prose; try fewer / different terms, or it may not be indexed yet.`],
+    };
+  }
+  // "Corpus last changed", NOT "last indexed" — the server derives this from
+  // updated_at on the chunks, and both ingesters delta-gate their upsert, so it
+  // moves when CONTENT changes and stands still through a healthy ingest over an
+  // unchanged corpus. It was labelled "Last indexed:" until task 1003145, which
+  // read as an ingest-liveness signal it was never measuring.
+  //
+  // Both keys are read for the version-skew window: this CLI ships before the
+  // server pin moves, so an OLD server still answers with last_indexed_at. Same
+  // value either way — only the name was wrong.
+  const changedAt = corpus.last_content_change_at || corpus.last_indexed_at;
+  const stamp = changedAt ? ` Corpus last changed: ${changedAt}.` : '';
+  if (corpus.healthy) {
+    return { stream: 'out', exitCode: 0, lines: [`No matches for "${q}". ${corpus.message}${stamp}`] };
+  }
+  return {
+    stream: 'err',
+    exitCode: 1,
+    lines: [
+      `\n  ⚠ RECALL IS NOT ANSWERING — "${q}" returned nothing, and the reason is not your query.\n`,
+      `  ${corpus.message}${stamp}\n`,
+      '  Do NOT read this as "the project has never touched this subject".\n',
+    ],
+  };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  // Step 2: --expand <id> bypasses the search and pulls one hit's full content.
+  if (Number.isFinite(args.expand)) {
+    return runExpand(args);
+  }
+
+  if (!args.q) {
+    console.error('Usage: node scripts/bongos/recall.js <query…> [--limit N] [--kind doc|db] [--json]');
+    console.error('       node scripts/bongos/recall.js --expand <id>   # full content of one hit');
+    process.exit(1);
+  }
+  const body = { q: args.q };
+  if (Number.isFinite(args.limit)) body.limit = args.limit;
+  if (args.kind === 'doc' || args.kind === 'db') body.source_kind = args.kind;
+
+  const api = await cliClient();
+  const r = await api.search.postSearch({ body });
+  if (!r.ok) {
+    reportError(r);
+    process.exit(1);
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(r.data, null, 2));
+    return;
+  }
+
+  const { count, results, total_full_tokens, corpus } = r.data;
+  if (!count) {
+    const out = renderNoMatch({ q: args.q, corpus });
+    const sink = out.stream === 'err' ? console.error : console.log;
+    for (const line of out.lines) sink(line);
+    if (out.exitCode) process.exitCode = out.exitCode;
+    return;
+  }
+  const totalNote = Number.isFinite(total_full_tokens)
+    ? `  ·  ~${total_full_tokens} tokens to expand all`
+    : '';
+  console.log(`${count} result(s) for "${args.q}"${totalNote}:\n`);
+  for (const [i, res] of results.entries()) {
+    const where = res.heading_path || res.source_ref;
+    const legs = [res.fts_rank ? 'fts' : null, res.trgm_rank ? 'trgm' : null].filter(Boolean).join('+') || '—';
+    // Token-cost label: full_tokens is what a full read of this hit COSTS; the
+    // `+` flags that the snippet below is only a preview of a larger chunk.
+    const cost = res.full_tokens != null
+      ? `~${res.full_tokens} tok${res.truncated ? ' to expand' : ''}`
+      : '';
+    console.log(`#${res.id}. ${res.title || res.source_ref}`);
+    console.log(`   ${where}`);
+    console.log(`   ${res.source_ref}  ·  score ${Number(res.score).toFixed(4)}  ·  ${legs}${cost ? '  ·  ' + cost : ''}`);
+    console.log(`   ${truncate(res.snippet, 240)}`);
+    if (res.truncated) console.log(`   → recall --expand ${res.id}  for the full section`);
+    console.log('');
+  }
+}
+
+if (require.main === module) {
+  main().catch((e) => { console.error('recall: error', e && e.message ? e.message : e); process.exit(1); });
+}
+
+module.exports = { parseArgs, truncate, renderNoMatch };

package/scripts/bongos/redteam-patrol.js

@@ -0,0 +1,437 @@
+#!/usr/bin/env node
+// scripts/bongos/redteam-patrol.js — the weekly deterministic red-team patrol
+// (task 1003128, goal 1000076; ADR 0180 §3, docs/audits/ai-dev-redteam-baseline.md).
+//
+// The patrol is the third enforcement layer (prevent → gate → PATROL): checks
+// too slow, too networked, or too history-wide for the merge gate, run weekly
+// by the .claude/scheduled-tasks/redteam-weekly routine. It is ADVISORY by
+// doctrine (ADR 0158 §2 — a verdict never self-executes): findings are FILED as
+// security reports for Archon adjudication, never turned into gates here.
+//
+// Checks (all deterministic — no model reads anything):
+//   1. history-secrets — full-git-history gitleaks scan (.gitleaks.toml config;
+//      the CI gate only scans the current tree, so a key deleted years ago but
+//      still live is THIS check's catch). Needs the gitleaks binary
+//      (GITLEAKS_BIN or on PATH) — absent means a loud degraded note.
+//   2. dependency-review — npm audit delta vs config/audit-baseline.json
+//      (reuses audit-gate.js), release-age cooldown (<7 days — ADR 0180 §3),
+//      young direct deps (<90 days — the slopsquat shape), stale overrides.
+//   3. action-pins — every workflow `uses:` must be pinned to a 40-hex SHA
+//      (the tj-actions lesson).
+//   4. baseline-staleness — a shrink-only quality baseline that has not moved in
+//      8 weeks (task 1003210). Belongs HERE and not in the merge gate for the
+//      same reason the other three do: it is history-wide and time-based, so it
+//      is not a property of anyone's diff — failing a PR because ambient debt
+//      turned eight weeks old punishes whoever pushed next. The audit asked for
+//      "the repeatable, scheduled version" of a review it had done by hand; this
+//      is it.
+//
+// Filing: DRY-RUN by default (prints what it would file). --file POSTs one
+// report PER CLASS (max severity within the class, details in repro_steps_md)
+// to /api/bongos/security/reports. --canary proves the end-to-end pipe: plants a
+// constructed token, asserts the scanner catches it, files a low "[canary]"
+// report, and dispute-closes it so the queue stays clean.
+//
+// UNATTENDED RUNS (task 1003209). The scheduler is .github/workflows/redteam-patrol.yml
+// — CI, not the always-on server, because all three checks read things only the
+// REPO has: full git history, .github/workflows/, and a package-lock npm can audit
+// (ADR 0188). A CI runner has no GDS session, so --file would otherwise hit
+// cli-lib's interactive re-auth wall and print "run /builder-reauth" into a cron
+// log. Instead --file preflights the session and, when there is none, follows the
+// main-audit.js --require-roster doctrine: report LOUDLY rather than green-and-
+// vacuous. The exit code says whether a finding was LOST, not whether findings
+// exist — findings are advisory (ADR 0158 §2) and a patrol that goes red merely for
+// doing its job trains everyone to ignore it:
+//
+//   ran + filed                     → 0
+//   ran, nothing to file            → 0 (with or without a session)
+//   ran, has findings, cannot file  → 2 — the one state where evidence evaporates
+//
+// Findings are ALSO appended to $GITHUB_STEP_SUMMARY when set, so a scheduled run
+// is readable in the Actions UI without opening the log.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync, execFileSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const COOLDOWN_DAYS = 7;   // ADR 0180 §3 — patrol-enforced until npm ≥ 11.10 in CI
+const YOUNG_PKG_DAYS = 90; // a very new package is the slopsquat/typosquat shape
+const MAX_ITEMS_PER_REPORT = 10;
+
+const SEV_ORDER = { low: 0, medium: 1, high: 2, critical: 3 };
+// npm audit says "moderate"; the bounty table says "medium".
+function mapSeverity(s) {
+  const v = String(s || '').toLowerCase();
+  return v === 'moderate' ? 'medium' : (SEV_ORDER[v] !== undefined ? v : 'low');
+}
+function maxSeverity(findings) {
+  return findings.reduce((m, f) => (SEV_ORDER[f.severity] > SEV_ORDER[m] ? f.severity : m), 'low');
+}
+
+// ---------- 1. full-history secret scan ----------
+
+function gitleaksBin() {
+  const explicit = process.env.GITLEAKS_BIN;
+  if (explicit && fs.existsSync(explicit)) return explicit;
+  try {
+    execFileSync(process.platform === 'win32' ? 'where' : 'which', ['gitleaks'], { stdio: 'pipe' });
+    return 'gitleaks';
+  } catch {
+    return null;
+  }
+}
+
+// Parse a gitleaks JSON report file into patrol findings.
+function parseGitleaksReport(raw) {
+  let rows;
+  try { rows = JSON.parse(raw); } catch { return []; }
+  if (!Array.isArray(rows)) return [];
+  return rows.map((r) => ({
+    severity: 'high',
+    item: `${r.RuleID || r.ruleID || 'secret'} in ${r.File || r.file || '?'}${r.Commit ? ` @ ${String(r.Commit).slice(0, 8)}` : ''}`,
+  }));
+}
+
+function historySecretScan() {
+  const bin = gitleaksBin();
+  if (!bin) {
+    return { degraded: 'gitleaks binary not found (set GITLEAKS_BIN or `brew install gitleaks`) — history scan SKIPPED', findings: [] };
+  }
+  const report = path.join(os.tmpdir(), `gitleaks-patrol-${process.pid}.json`);
+  try {
+    execFileSync(bin, ['git', '.', '--config', '.gitleaks.toml', '--redact', '--no-banner',
+      '--report-format', 'json', '--report-path', report], { cwd: ROOT, stdio: 'pipe' });
+  } catch {
+    /* non-zero exit = leaks found; the report file is still written */
+  }
+  let findings = [];
+  try { findings = parseGitleaksReport(fs.readFileSync(report, 'utf8')); } catch { /* no report = clean */ }
+  try { fs.unlinkSync(report); } catch { /* already gone */ }
+  return { degraded: null, findings };
+}
+
+// ---------- 2. dependency review ----------
+
+function npmViewJson(spec) {
+  try {
+    return JSON.parse(execSync(`npm view ${spec} --json`, { cwd: ROOT, stdio: 'pipe', timeout: 30000 }).toString());
+  } catch {
+    return null;
+  }
+}
+
+function ageDays(iso, now = Date.now()) {
+  const t = Date.parse(iso);
+  return Number.isFinite(t) ? (now - t) / 86400000 : null;
+}
+
+function lockedVersion(lock, name) {
+  const entry = lock.packages && lock.packages[`node_modules/${name}`];
+  return entry && entry.version;
+}
+
+// Pure: what to say about ONE `overrides` entry. Extracted so the rule is a table
+// a test can enumerate — the networked half (npm view) stays outside.
+//
+// THE BUG THIS REPLACES (task 1003283, report 1000025). The old rule compared the
+// pinned MAJOR against `dist-tags.latest` and filed a medium whenever latest was
+// higher. That flags every override which deliberately holds a major line — which
+// is the normal reason an override exists at all. It fired on `undici ^6.28.0`
+// "while latest is 8.10.0", when 6.28.0 is the newest 6.x, `discord.js` (the only
+// consumer) requires the 6.x line, and `npm audit` finds nothing. Acting on it
+// would have BROKEN the dependent; ignoring it weekly is the alert-fatigue failure
+// ADR 0188 §2.4 exists to prevent — here inside the patrol itself.
+//
+// The real signal is narrower: a pin whose LOCKED version has fallen behind what
+// its own range already allows. That is rot nobody chose. Trailing the latest
+// major is reported as a NOTE instead, because only a human can say whether a
+// dependent still constrains the line.
+//
+// `satisfying` is every published version matching `range`, ASCENDING (npm's own
+// order), so the newest in-range version is simply the last element — no semver
+// comparator needed, and no dependency added to do it.
+function overrideVerdict({ name, range, locked, satisfying = [], latest = null } = {}) {
+  const newestInRange = satisfying.length ? satisfying[satisfying.length - 1] : null;
+  if (newestInRange && locked && newestInRange !== locked && satisfying.includes(locked)) {
+    return {
+      finding: { severity: 'medium', item: `stale override: ${name} is locked at ${locked} but its own pin "${range}" already allows ${newestInRange} — refresh the lockfile` },
+    };
+  }
+  const pinnedMajor = parseInt(String(range).replace(/^[^0-9]*/, ''), 10);
+  const latestMajor = parseInt(String(latest), 10);
+  if (Number.isFinite(pinnedMajor) && Number.isFinite(latestMajor) && latestMajor > pinnedMajor) {
+    return {
+      note: `override ${name} "${range}" trails the latest major (${latest}) — expected when a dependent requires that line; verify before lifting, do NOT bump blind`,
+    };
+  }
+  return {};
+}
+
+function dependencyReview() {
+  const findings = [];
+  const notes = [];
+  const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+  const lock = JSON.parse(fs.readFileSync(path.join(ROOT, 'package-lock.json'), 'utf8'));
+
+  // 2a — audit delta vs the committed baseline (same lens as the CI gate, but
+  // the patrol also reports RESOLVED entries so the baseline gets shrunk).
+  const auditGate = require('./audit-gate.js');
+  try {
+    let raw;
+    try { raw = execSync('npm audit --omit=dev --json', { cwd: ROOT, maxBuffer: 32 * 1024 * 1024, stdio: 'pipe' }).toString(); }
+    catch (e) { raw = e && e.stdout ? e.stdout.toString() : null; }
+    const current = auditGate.extractFindings(JSON.parse(raw));
+    const baseline = JSON.parse(fs.readFileSync(auditGate.BASELINE_PATH, 'utf8')).findings || [];
+    const verdict = auditGate.compare(current, baseline);
+    for (const f of [...verdict.newGating, ...verdict.newAdvisory]) {
+      findings.push({ severity: mapSeverity(f.severity), item: `new advisory: [${f.severity}] ${f.name} (${f.id}) ${f.title}` });
+    }
+    for (const f of verdict.resolved) notes.push(`baseline shrinkable: ${f.name} (${f.id}) no longer reproduces`);
+  } catch (e) {
+    notes.push(`audit delta SKIPPED (infra): ${e.message}`);
+  }
+
+  // 2b — release-age cooldown + young packages, direct deps only (9 today).
+  for (const name of Object.keys(pkg.dependencies || {})) {
+    const version = lockedVersion(lock, name);
+    if (!version) continue;
+    const meta = npmViewJson(`${name} time`);
+    const time = meta && (meta.time || meta);
+    if (!time) { notes.push(`npm view failed for ${name} — cooldown check skipped`); continue; }
+    const vAge = ageDays(time[version]);
+    if (vAge !== null && vAge < COOLDOWN_DAYS) {
+      findings.push({ severity: 'medium', item: `cooldown breach: ${name}@${version} published ${vAge.toFixed(1)}d ago (<${COOLDOWN_DAYS}d — ADR 0180 §3)` });
+    }
+    const cAge = ageDays(time.created);
+    if (cAge !== null && cAge < YOUNG_PKG_DAYS) {
+      findings.push({ severity: 'medium', item: `young package: ${name} created ${cAge.toFixed(0)}d ago (<${YOUNG_PKG_DAYS}d — verify it is the intended package)` });
+    }
+  }
+
+  // 2c — override staleness (the undici lesson: a pin nobody watches rots) —
+  // measured INSIDE the pinned range, see overrideVerdict above.
+  for (const [name, range] of Object.entries(pkg.overrides || {})) {
+    if (typeof range !== 'string') continue;
+    const latest = npmViewJson(`${name} dist-tags.latest`);
+    // Every published version matching the range, ascending. npm returns a bare
+    // string when exactly one matches, so normalise to an array.
+    const matched = npmViewJson(`"${name}@${range}" version`);
+    const satisfying = matched == null ? [] : (Array.isArray(matched) ? matched : [matched]);
+    if (!latest && !satisfying.length) { notes.push(`npm view failed for override ${name} — staleness check skipped`); continue; }
+    const v = overrideVerdict({ name, range, locked: lockedVersion(lock, name), satisfying, latest });
+    if (v.finding) findings.push(v.finding);
+    if (v.note) notes.push(v.note);
+  }
+  return { findings, notes };
+}
+
+// ---------- 3. workflow action pins ----------
+
+const USES_RE = /^\s*(?:-\s+)?uses:\s*(\S+)/;
+const SHA_PINNED_RE = /@[0-9a-f]{40}(\s|$)/;
+
+function unpinnedUses(yamlText) {
+  const out = [];
+  for (const line of yamlText.split('\n')) {
+    const m = USES_RE.exec(line);
+    if (!m) continue;
+    const ref = m[1];
+    if (ref.startsWith('./') || ref.startsWith('docker://')) continue; // local/composite + digest-pinnable images
+    if (!SHA_PINNED_RE.test(ref)) out.push(ref);
+  }
+  return out;
+}
+
+function actionPinCheck() {
+  const dir = path.join(ROOT, '.github', 'workflows');
+  const findings = [];
+  if (!fs.existsSync(dir)) return { findings };
+  for (const f of fs.readdirSync(dir).filter((n) => n.endsWith('.yml') || n.endsWith('.yaml'))) {
+    for (const ref of unpinnedUses(fs.readFileSync(path.join(dir, f), 'utf8'))) {
+      findings.push({ severity: 'medium', item: `unpinned action in ${f}: "${ref}" — pin to a 40-hex commit SHA (tj-actions lesson)` });
+    }
+  }
+  return { findings };
+}
+
+// ---------- report assembly + filing ----------
+
+function buildClassReport(className, findings, notes = []) {
+  const shown = findings.slice(0, MAX_ITEMS_PER_REPORT);
+  const body = [
+    ...shown.map((f) => `- [${f.severity}] ${f.item}`),
+    ...(findings.length > shown.length ? [`…and ${findings.length - shown.length} more`] : []),
+    ...(notes.length ? ['', 'Notes:', ...notes.map((n) => `- ${n}`)] : []),
+  ].join('\n');
+  return {
+    target: `redteam-patrol/${className}`,
+    severity: maxSeverity(findings),
+    title: `[patrol] ${className}: ${findings.length} finding(s)`,
+    description: `Weekly deterministic red-team patrol (task 1003128; advisory per ADR 0158 §2 — adjudicate, then fix via ordinary tasks).`,
+    repro_steps_md: body,
+  };
+}
+
+// Append markdown to the Actions job summary when running under GitHub Actions.
+// Best-effort and inert everywhere else — a patrol run must never fail because a
+// log surface was unavailable.
+function stepSummary(md) {
+  const dest = process.env.GITHUB_STEP_SUMMARY;
+  if (!dest) return;
+  try { fs.appendFileSync(dest, `${md}\n`); } catch { /* never fatal */ }
+}
+
+// Pure: what a completed sweep should DO with its findings, and the exit code
+// that disposition deserves. Extracted so the honest-exit contract is a table a
+// test can enumerate rather than branching buried in main().
+//
+// The load-bearing row is the last one. Findings are ADVISORY (ADR 0158 §2), so a
+// run that finds three things and files them is a SUCCESS — going red merely for
+// doing its job is how a weekly lane becomes noise everyone filters. Red is
+// reserved for the single state where evidence EVAPORATES: findings exist,
+// filing was asked for, and it cannot happen.
+function disposition({ findingClasses = 0, doFile = false, blocker = null } = {}) {
+  if (!findingClasses) return { action: 'clean', exitCode: 0 };
+  if (!doFile) return { action: 'dry-run', exitCode: 0 };
+  if (blocker) return { action: 'not-filed', exitCode: 2 };
+  return { action: 'file', exitCode: 0 };
+}
+
+// Is there a GDS session this run could file with? Returns the reason it cannot,
+// or null when filing is possible. Read directly (readSessionToken) rather than
+// probing with apiCall, because apiCall's 401 path exits the process with
+// interactive re-auth guidance — useless in a cron log and indistinguishable from
+// a crash.
+function filingBlocker() {
+  try {
+    const { readSessionToken } = require('./cli-lib.js');
+    return readSessionToken() ? null : 'no GDS session on this runner';
+  } catch (e) {
+    return `session unreadable: ${e && e.message}`;
+  }
+}
+
+async function fileReport(report) {
+  const { apiCall } = require('./cli-lib.js');
+  const r = await apiCall('POST', '/api/bongos/security/reports', report);
+  const row = (r.data && r.data.report) || {};
+  return row.id || null;
+}
+
+async function disputeReport(id, note) {
+  const { apiCall } = require('./cli-lib.js');
+  return apiCall('POST', `/api/bongos/security/reports/${id}/dispute`, { note });
+}
+
+// ---------- canary ----------
+
+async function runCanary(file) {
+  const bin = gitleaksBin();
+  if (!bin) { console.error('canary FAIL: gitleaks binary unavailable'); process.exit(1); }
+  const token = 'ghp_' + 'Ab1Cd2Ef3Gh4Ij5Kl6Mn7Op8Qr9St0Uv1Wx2Y'; // constructed, never a literal shape
+  const canaryPath = path.join(ROOT, 'src', `patrol-canary-${process.pid}.js`);
+  fs.writeFileSync(canaryPath, `const t = "${token}";\n`);
+  let caught = false;
+  try {
+    const report = path.join(os.tmpdir(), `gitleaks-canary-${process.pid}.json`);
+    try {
+      execFileSync(bin, ['dir', '.', '--config', '.gitleaks.toml', '--redact', '--no-banner',
+        '--report-format', 'json', '--report-path', report], { cwd: ROOT, stdio: 'pipe' });
+    } catch { /* leaks found → non-zero, expected */ }
+    try {
+      caught = parseGitleaksReport(fs.readFileSync(report, 'utf8')).some((f) => f.item.includes('patrol-canary'));
+      fs.unlinkSync(report);
+    } catch { caught = false; }
+  } finally {
+    fs.unlinkSync(canaryPath);
+  }
+  if (!caught) { console.error('canary FAIL: planted token was not detected'); process.exit(1); }
+  console.log('canary: planted token detected by the scanner ✓');
+  if (file) {
+    const id = await fileReport({
+      target: 'redteam-patrol/canary',
+      severity: 'low',
+      title: '[canary] patrol self-test — planted token detected end-to-end',
+      description: 'Seeded finding proving the patrol can detect and FILE (task 1003128 done-when). Dispute-closed by the patrol itself; no action needed.',
+      repro_steps_md: '- plant constructed ghp_ token in src/ → gitleaks dir catches it → report filed → dispute-closed.',
+    });
+    if (!id) { console.error('canary FAIL: report did not file'); process.exit(1); }
+    console.log(`canary: filed security report ${id} ✓`);
+    await disputeReport(id, 'canary self-test (task 1003128) — auto-closed by the patrol');
+    console.log('canary: dispute-closed ✓ — end-to-end pipe proven');
+  }
+}
+
+// ---------- main ----------
+
+async function main() {
+  if (process.argv.includes('--canary')) {
+    await runCanary(process.argv.includes('--file'));
+    return;
+  }
+  const doFile = process.argv.includes('--file');
+
+  const classes = [];
+  const secrets = historySecretScan();
+  if (secrets.findings.length) classes.push(buildClassReport('history-secrets', secrets.findings));
+  if (secrets.degraded) console.warn(`patrol: DEGRADED — ${secrets.degraded}`);
+
+  const deps = dependencyReview();
+  if (deps.findings.length) classes.push(buildClassReport('dependency-review', deps.findings, deps.notes));
+  else if (deps.notes.length) console.log(`patrol: dependency notes:\n${deps.notes.map((n) => `  - ${n}`).join('\n')}`);
+
+  const pins = actionPinCheck();
+  if (pins.findings.length) classes.push(buildClassReport('action-pins', pins.findings));
+
+  // Deterministic and local (git history + one JSON file) — no network, no model.
+  const stale = require('./baseline-staleness.js').stalenessFindings();
+  if (stale.length) classes.push(buildClassReport('baseline-staleness', stale));
+
+  if (secrets.degraded) stepSummary(`> **DEGRADED** — ${secrets.degraded}`);
+
+  if (!classes.length) {
+    console.log('patrol: clean sweep — nothing to file.');
+    stepSummary('## red-team patrol\n\nClean sweep — no findings to file.');
+    return;
+  }
+
+  stepSummary(['## red-team patrol', ...classes.map((c) =>
+    `### ${c.title}\n\nseverity: **${c.severity}**\n\n${c.repro_steps_md}`)].join('\n\n'));
+
+  // Preflight the session ONCE, before the first POST: a half-filed sweep (class
+  // one lands, class two hits the auth wall and exits) is worse than not starting.
+  const blocker = doFile ? filingBlocker() : null;
+  const { action, exitCode } = disposition({ findingClasses: classes.length, doFile, blocker });
+  if (action === 'not-filed') {
+    console.error(`patrol: DID NOT FILE — ${blocker}. ${classes.length} finding class(es) above are NOT in the adjudication queue.`);
+    console.error('patrol: sign in on this runner (or set the scheduler\'s session secret) and re-run — see docs/recipes/redteam-patrol.md.');
+    for (const report of classes) console.error(`  [${report.severity}] ${report.title}\n${report.repro_steps_md}`);
+    stepSummary(`\n> **NOT FILED** — ${blocker}. These findings exist only in this run's log.`);
+    process.exitCode = exitCode;
+    return;
+  }
+
+  for (const report of classes) {
+    if (doFile) {
+      const id = await fileReport(report);
+      console.log(`patrol: filed [${report.severity}] ${report.title} → report ${id}`);
+    } else {
+      console.log(`patrol (dry-run): would file [${report.severity}] ${report.title}\n${report.repro_steps_md}\n`);
+    }
+  }
+  if (!doFile) console.log('patrol: dry run — pass --file to POST these as security reports.');
+}
+
+if (require.main === module) {
+  main().catch((e) => { console.error(`patrol: ERROR ${e.message}`); process.exit(1); });
+}
+
+module.exports = {
+  parseGitleaksReport, unpinnedUses, ageDays, mapSeverity, maxSeverity,
+  buildClassReport, lockedVersion, COOLDOWN_DAYS, YOUNG_PKG_DAYS,
+  stepSummary, filingBlocker, disposition, overrideVerdict,
+};

package/scripts/bongos/regen-instance-docs.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+'use strict';
+// regen-instance-docs.js — regenerate a STANDALONE instance's live navigation docs (task 1002314).
+//
+// THE GAP. On the monorepo, the gitignored whole-file navigation docs are regenerated at deploy by
+// scripts/deploy/deploy-prod.sh (ADR 0110 §2/§3). STANDALONE instances
+// (ADR 0108 — their own lean repo with @bongos/core vendored) never got that step: their bespoke
+// pull-deploy regenerated NOTHING, so a fresh instance shipped with an empty docs/ and nothing kept
+// the session-log index live. This script is the STANDALONE analogue of deploy-prod.sh's regen block
+// — one line for an instance's deploy.sh to call after `git reset --hard` + migrate.
+//
+// USAGE (from the instance repo, core vendored in node_modules):
+//   node node_modules/@bongos/core/scripts/bongos/regen-instance-docs.js
+// It resolves the INSTANCE root (bongos.config.json instanceRoot / <PREFIX>_INSTANCE_ROOT / cwd) and
+// writes docs/session-log-index.md THERE (gitignored on the instance, so the next
+// `git reset --hard origin/main` never wipes it and no branch can ever diff it).
+//
+// SCOPE + CONTRACT: see regenerateNavDocs() in upgrade.js — it owns the generator list and the
+// rationale for what is and isn't deploy-regenerated (repo-map is core-scoped; file-map + API docs
+// are tracked/committed; diagrams are the headless-browser exception). Best-effort + LOUD per
+// ADR 0110 §2 "accepted staleness": a broken generator prints `::ERROR::` (journald greps it) but
+// this script ALWAYS exits 0 — a stale nav doc is tolerable; a failed deploy is not.
+
+const path = require('node:path');
+const { resolveInstanceRoot } = require('../../src/instance-config');
+const { regenerateNavDocs } = require('./upgrade');
+
+function main() {
+  const coreRoot = path.resolve(__dirname, '..', '..'); // the @bongos/core package this script ships in
+  const instanceDir = resolveInstanceRoot();
+  const res = regenerateNavDocs({ instanceDir, coreRoot });
+  if (res.ran.length) {
+    console.log(`regen-instance-docs: regenerated ${res.ran.join(', ')} → ${instanceDir}/docs/`);
+  }
+  if (!res.ok) {
+    for (const f of res.failed) {
+      // LOUD (ADR 0110 §2): journald greps ::ERROR:: so a broken generator surfaces.
+      console.error(`::ERROR:: regen-instance-docs: ${f.gen} failed — ${f.reason}`);
+    }
+  }
+  // Best-effort: NEVER fail the deploy. A stale/absent nav doc is tolerable; the ::ERROR:: is the alarm.
+  process.exit(0);
+}
+
+if (require.main === module) main();
+
+module.exports = { main };