@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/portability-smoke-memory.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# C8 portability smoke — MEMORY (#280 / V3.R61).
+#
+# Certifies the core C8 promise end-to-end: the repo is cloneable, a fresh
+# clone leaks no secrets or another builder's memory, and a builder's
+# server-canonical memory is retrievable + byte-intact from a clean machine.
+#
+# WHY NOT "ship a tiny task" literally (per the task's done-when): shipping
+# from a smoke would merge to main + deploy + churn the DB every run — unsafe
+# for a nightly. The PUSH side is already exercised on every real /builder-ship
+# (each logs "memory sync: N stored"). The unique, untested-elsewhere promise
+# is the PULL/restore a fresh clone performs on SessionStart — that's what this
+# certifies, plus the cloneability + no-leak guarantees. See ADR 0024 §1-4.
+#
+# Read-only by default. The only server write is the optional push/sync leg
+# (step 6), which is CI-gated behind GDS_SMOKE_ALLOW_WRITE + a dedicated
+# GDS_SMOKE_TOKEN — it never writes when using a local builder's token.
+#
+# Usage:
+#   GDS_SMOKE_TOKEN=<token> bash scripts/bongos/portability-smoke-memory.sh
+#   # token falls back to this instance's CLI session for local runs (lib.sh)
+#   # target with GDS_API_BASE (default this instance; CI should point at staging)
+
+set -uo pipefail
+# Sourced BEFORE the cd — lib.sh captures its own directory at source time, and
+# both helpers below resolve the config through node rather than a baked-in path
+# or host, which is what made this script instance-blind (task 1002567).
+# shellcheck source=scripts/bongos/lib.sh
+source "$(dirname "$0")/lib.sh"
+cd "$(dirname "$0")/../.."   # repo root (consistent with portability-smoke-art.sh)
+
+BASE="$(gds_api_base)"
+PASS=0; FAIL=0
+ok()   { echo "PASS  $1"; PASS=$((PASS+1)); }
+bad()  { echo "FAIL  $1"; FAIL=$((FAIL+1)); }
+
+# --- resolve token -----------------------------------------------------------
+TOKEN="${GDS_SMOKE_TOKEN:-}"; TOKEN_SRC="env"
+if [ -z "$TOKEN" ]; then
+  # Same session lookup every /builder-* command does; stays a SKIP (not a FAIL)
+  # when there is no session, which is this script's contract.
+  TOKEN=$(gds_resolve_token 2>/dev/null) || TOKEN=""
+  [ -n "$TOKEN" ] && TOKEN_SRC="file"
+fi
+if [ -z "$TOKEN" ]; then
+  echo "SKIP: no GDS token (set GDS_SMOKE_TOKEN or run /builder-setup). Memory portability not certified this run."
+  exit 0
+fi
+
+# --- defense-in-depth: never send the token to another instance's host -------
+# We hold a real GDS_SMOKE_TOKEN and are about to send it (Authorization: Bearer)
+# to whatever GDS_API_BASE resolves to. A fat-fingered or compromised
+# STAGING_API_BASE must not be able to exfiltrate it, so refuse any host outside
+# THIS instance's own zone (localhost allowed for local dev). (idea 127 nit 3.)
+# The zone is resolved from the session + branding pack, never a baked-in domain
+# — a literal here pinned the guard to one instance and refused every other one
+# outright, the same instance-blindness as the base/token defaults (task 1002567).
+host_of() { printf '%s' "$1" | sed -E 's#^[a-zA-Z][a-zA-Z0-9+.-]*://##; s#[:/?].*$##'; }
+BASE_HOST=$(host_of "$BASE")
+ALLOWED_HOST=$(host_of "$(gds_instance_base)")
+if [ -z "$ALLOWED_HOST" ]; then
+  echo "FAIL  could not resolve this instance's own host (is node on PATH?)."
+  echo "      Refusing to send GDS_SMOKE_TOKEN to an unverified target."
+  exit 1
+fi
+# ALLOWED_HOST lands unquoted-side in the case patterns below, where glob
+# metacharacters (* ? [ ) would silently WIDEN the allowlist. It comes from
+# operator config, not attacker input, but a malformed branding pack must fail
+# closed, not open.
+case "$ALLOWED_HOST" in
+  *[!A-Za-z0-9.-]*)
+    echo "FAIL  resolved instance host '$ALLOWED_HOST' contains characters invalid in a hostname."
+    echo "      Refusing to build a token allowlist from it (check branding.domains / session api_base)."
+    exit 1
+    ;;
+esac
+case "$BASE_HOST" in
+  "$ALLOWED_HOST"|*."$ALLOWED_HOST"|localhost|127.0.0.1) ;;
+  *)
+    echo "FAIL  GDS_API_BASE host '$BASE_HOST' is not an allowed target for the smoke token"
+    echo "      (allow: $ALLOWED_HOST, *.$ALLOWED_HOST, localhost). Refusing to send GDS_SMOKE_TOKEN."
+    exit 1
+    ;;
+esac
+
+echo "=== C8 portability smoke: MEMORY (base=$BASE) ==="
+
+# --- 1. fresh clone: the repo is cloneable -----------------------------------
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+REMOTE=$(git remote get-url origin 2>/dev/null || echo "")
+if [ -z "$REMOTE" ]; then bad "could not resolve origin remote for fresh-clone test"; else
+  if git clone --depth 1 -q "$REMOTE" "$TMP/clone" 2>/dev/null; then
+    ok "repo clones from origin (cloneable)"
+    # --- 2. the fresh clone leaks NO secrets / NO builder memory ------------
+    LEAKS=0
+    CFG_DIR=$(gds_node "process.stdout.write(require('../../src/instance-config').configDirName())" 2>/dev/null) || CFG_DIR=""
+    for p in ".env.local" "spaces.env" ".config/${CFG_DIR:-otb}/bongos-session.json" ".config/${CFG_DIR:-otb}/gds-session.json" "etc/${CFG_DIR:-otb}"; do
+      if [ -e "$TMP/clone/$p" ]; then echo "  leak: $p present in clone"; LEAKS=$((LEAKS+1)); fi
+    done
+    # builder_memory is server-side only — no memory dir should ship in-repo
+    if find "$TMP/clone" -type d -name "memory" -path "*projects*" 2>/dev/null | grep -q .; then
+      echo "  leak: a builder memory dir is present in the clone"; LEAKS=$((LEAKS+1)); fi
+    [ "$LEAKS" -eq 0 ] && ok "fresh clone contains no secrets and no builder memory" \
+                       || bad "fresh clone leaked $LEAKS secret/memory artifact(s)"
+  else
+    bad "git clone failed"
+  fi
+fi
+
+# --- 3. unauthenticated memory read is rejected (guard) ----------------------
+code=$(curl -sS -o /dev/null -w '%{http_code}' "$BASE/api/bongos/memory/files" || echo 000)
+[ "$code" = "401" ] && ok "unauth GET /memory/files → 401" || bad "unauth GET /memory/files → $code (expected 401)"
+
+# --- 4. authenticated builder can pull their server-canonical memory ---------
+FILES_JSON=$(curl -sS -H "Authorization: Bearer $TOKEN" "$BASE/api/bongos/memory/files" || echo '{}')
+COUNT=$(echo "$FILES_JSON" | python3 -c "import json,sys;print(json.load(sys.stdin).get('count',-1))" 2>/dev/null || echo -1)
+if [ "$COUNT" -ge 1 ] 2>/dev/null; then
+  ok "authenticated pull lists $COUNT server-canonical memory file(s)"
+else
+  bad "authenticated pull returned count=$COUNT (expected >=1; a builder who has shipped should have memory)"
+fi
+
+# --- 5. pulled content is byte-intact (sha256 round-trip) --------------------
+# Take the first listed file, fetch it, recompute sha256, compare to server's.
+FIRST_PATH=$(echo "$FILES_JSON" | python3 -c "import json,sys;f=json.load(sys.stdin).get('files',[]);print(f[0]['path'] if f else '')" 2>/dev/null || echo "")
+if [ -n "$FIRST_PATH" ]; then
+  VERDICT=$(curl -sS -H "Authorization: Bearer $TOKEN" --get "$BASE/api/bongos/memory/file" --data-urlencode "path=$FIRST_PATH" \
+    | python3 -c "
+import json,sys,hashlib
+d=json.load(sys.stdin)
+content=d.get('content')
+if content is None: print('NOCONTENT'); sys.exit()
+calc=hashlib.sha256(content.encode('utf-8')).hexdigest()
+print('MATCH' if calc==d.get('sha256') else 'MISMATCH')
+" 2>/dev/null || echo "ERR")
+  case "$VERDICT" in
+    MATCH) ok "pulled content for '$FIRST_PATH' is byte-intact (sha256 round-trip)";;
+    *)     bad "content integrity check for '$FIRST_PATH' → $VERDICT";;
+  esac
+else
+  # Step 4 already required count>=1 to pass, so an empty path here means path
+  # extraction failed — a real parse regression, not a benign skip. Fail loudly
+  # rather than silently dropping the integrity check from the summary count.
+  bad "could not extract a memory file path despite count>=1 (parse regression?)"
+fi
+
+# --- 6. (CI-only, opt-in) push → pull round-trip exercises the SYNC path -----
+# Gated behind GDS_SMOKE_ALLOW_WRITE=1 AND a token supplied via GDS_SMOKE_TOKEN
+# (never the local-session fallback). Rationale: a push persists server-side
+# (no delete endpoint) and would sync into a real builder's local memory dir on
+# next SessionStart. CI runs this with a DEDICATED smoke-builder token, whose
+# memory is isolated and disposable. The fixed path is overwritten each run, so
+# it does not accumulate. This is the AC's "verify memory synced" (push) leg.
+if [ "${GDS_SMOKE_ALLOW_WRITE:-0}" = "1" ] && [ "$TOKEN_SRC" = "env" ]; then
+  SPATH="__smoke__/portability.md"
+  STAMP="portability smoke $(date -u +%FT%TZ) pid-$$"
+  PUSH_BODY=$(python3 -c "import json,sys;print(json.dumps({'files':[{'path':'$SPATH','content':sys.argv[1]}]}))" "$STAMP")
+  PUSH_CODE=$(curl -sS -o /dev/null -w '%{http_code}' -X POST \
+    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+    "$BASE/api/bongos/memory/sync" -d "$PUSH_BODY" || echo 000)
+  if [ "$PUSH_CODE" = "200" ]; then
+    RT=$(curl -sS -H "Authorization: Bearer $TOKEN" --get "$BASE/api/bongos/memory/file" --data-urlencode "path=$SPATH" \
+      | python3 -c "import json,sys;d=json.load(sys.stdin);print('OK' if d.get('content')==sys.argv[1] else 'MISMATCH')" "$STAMP" 2>/dev/null || echo ERR)
+    [ "$RT" = "OK" ] && ok "push→pull sync round-trip (content persisted + retrieved intact)" \
+                     || bad "push→pull round-trip content mismatch ($RT)"
+  else
+    bad "POST /memory/sync push → $PUSH_CODE (expected 200)"
+  fi
+else
+  echo "  (push/sync round-trip skipped — set GDS_SMOKE_ALLOW_WRITE=1 with a DEDICATED GDS_SMOKE_TOKEN to exercise the push leg)"
+fi
+
+# --- summary -----------------------------------------------------------------
+echo "=== memory portability: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/scripts/bongos/preflight.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+// scripts/bongos/preflight.js — the onboarding ENVIRONMENT PREFLIGHT (task 1002401,
+// onboarding-audit area 4).
+//
+// One shared, PURE check of the three things that used to bite a brand-new
+// builder one reactive crash at a time:
+//   1. Node >= 22        — the very first command (`bongos start`) shells to node;
+//                          on a bare machine it died with `node: command not found`.
+//   2. deps installed    — a missing node_modules is why a ship later blew up with
+//                          `Cannot find module 'pg'`.
+//   3. `claude` usable    — the grader spawns it per worker. Not launchable ⇒ every
+//                          ship failed grading with SUBAGENT_SPAWN_FAILED; launchable
+//                          but LOGGED OUT ⇒ SUBAGENT_NONZERO_EXIT (task 1003080).
+// Each finding carries a copy-paste fix.
+//
+// Before this, those checks lived only inside `bongos doctor` (doctor.js) and were
+// never run at setup/start time — so newcomers hit the failures reactively, deep
+// in the session. This module is the front-loadable, testable source of truth:
+//   - `setup.js`  runs it at the top of `/builder-setup` (catch a bare machine up front)
+//   - `doctor.js` `checkToolchain()` delegates to it (one source, no drift)
+//   - `node scripts/bongos/preflight.js` runs it standalone (a quick `bongos`-less check)
+//
+// Pure by construction: every OS touch (node version, fs, child_process) is an
+// injectable dep, so the unit test drives it with zero real I/O.
+
+'use strict';
+
+const nodeFs = require('node:fs');
+const nodePath = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { resolveEnv, envPrefix, LEGACY_ENV_PREFIXES } = require('../../src/instance-config');
+
+const REPO_ROOT = nodePath.resolve(__dirname, '..', '..');
+const MIN_NODE_MAJOR = 22;
+
+// Env that authenticates the CLI with no interactive login — a headless box or a
+// CI runner. ci-grade.js reads the same two to decide whether it can grade at all.
+const HEADLESS_AUTH_ENV = ['CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY'];
+
+// The node_modules-present check, factored out (task 1002403) so a HOT-PATH
+// caller — /builder-start runs on every session open — can reuse THIS exact
+// finding without paying for the `claude --version` spawn the full
+// preflightChecks() does. Pure: injectable fs + repoRoot.
+//
+// WORKTREES (task 1003167 / idea 1000788): this used to test `repoRoot/node_modules`
+// ONLY, and a git worktree never has its own. But node's module resolution walks UP
+// from the requiring file, so every require in a worktree resolves against the real
+// repo root and works fine — meaning the check fired on essentially every claim
+// (worktree-per-claim is the project default), telling the builder to burn an
+// `npm ci` they did not need. A preflight that cries wolf is worse than none: it
+// trains people to read past the one time it is right. So resolve the way node
+// itself does — walk up — and only then call it missing.
+function depsFinding({ repoRoot = REPO_ROOT, fs = nodeFs } = {}) {
+  let hasDeps = false;
+  let foundAt = null;
+  try {
+    let dir = nodePath.resolve(repoRoot);
+    for (;;) {
+      if (fs.existsSync(nodePath.join(dir, 'node_modules'))) { hasDeps = true; foundAt = dir; break; }
+      const up = nodePath.dirname(dir);
+      if (up === dir) break; // hit the filesystem root
+      dir = up;
+    }
+  } catch (_) { /* treat as missing */ }
+  if (hasDeps) {
+    const here = nodePath.resolve(repoRoot) === foundAt;
+    return {
+      level: 'ok',
+      title: 'Dependencies',
+      detail: here ? 'node_modules present.' : `node_modules resolved from a parent (${foundAt}) — normal in a git worktree; requires resolve fine.`,
+    };
+  }
+  return {
+    level: 'warn',
+    title: 'Dependencies',
+    detail: 'node_modules is missing — scripts that need pg/express (a ship, the server) will fail until installed.',
+    fix: 'Run `npm ci` in the repo root.',
+  };
+}
+
+// The AUTH half of the `claude CLI` row (task 1003080). Split out to keep
+// preflightChecks readable — the depsFinding precedent. Pure: spawn/env injected.
+//
+// WHY IT EXISTS. `claude --version` exits 0 while the CLI is LOGGED OUT, so the
+// launchable probe alone reported "the grader can spawn its workers" on a box
+// where every worker died on spawn. The grader runs one `claude -p` per panel
+// worker; logged out, each exits 1 in ~5s, so all four record
+// SUBAGENT_NONZERO_EXIT, the panel reports `unavailable`, and the builder gets a
+// 0/10 "grade failed" card with an empty issues[] — while doctor, the one tool
+// they're told to run, printed a green row. (Observed on task 1002459: two
+// consecutive outage rounds, cost_usd null on every worker, while the rest of the
+// fleet graded 21/21 the same day.)
+//
+// `claude auth status --json` answers `{ loggedIn: bool }` from local credentials
+// — no token spend, no model call. An unverifiable answer (an older CLI with no
+// `auth` subcommand, or any unparseable output) deliberately stays OK with the
+// caveat named: a working older box must never be turned red by a probe it can't
+// answer.
+function claudeAuthFinding({ bin, via, ver, env, spawn, platform }) {
+  const envVar = HEADLESS_AUTH_ENV.find((k) => env[k]);
+  if (envVar) {
+    return { level: 'ok', title: 'claude CLI', detail: `launches${via}: ${ver}; authenticated via ${envVar} — the grader can spawn its workers.` };
+  }
+
+  let a;
+  try {
+    a = spawn(bin, ['auth', 'status', '--json'], { encoding: 'utf8', shell: platform === 'win32', windowsHide: true, timeout: 15000 });
+  } catch (err) { a = { error: err }; }
+
+  let loggedIn = null; // null ⇒ the CLI didn't answer in a shape we understand
+  try {
+    const parsed = JSON.parse(String((a && a.stdout) || '').trim());
+    if (typeof parsed.loggedIn === 'boolean') loggedIn = parsed.loggedIn;
+  } catch (_) { /* older CLI without `auth status`, or non-JSON output */ }
+
+  if (loggedIn === false) {
+    return {
+      level: 'fail',
+      title: 'claude CLI',
+      detail: `launches${via} (${ver}) but is not logged in — the grader spawns one \`claude -p\` per panel worker and each exits 1 immediately, so every ship fails grading with SUBAGENT_NONZERO_EXIT and a 0/10 card carrying no findings.`,
+      fix: `Run \`${bin} auth login\` (or \`${bin}\`, then /login). On a headless box, set ${HEADLESS_AUTH_ENV.join(' or ')} instead.`,
+    };
+  }
+  if (loggedIn === true) {
+    return { level: 'ok', title: 'claude CLI', detail: `launches${via}: ${ver}, logged in — the grader can spawn its workers.` };
+  }
+  return { level: 'ok', title: 'claude CLI', detail: `launches${via}: ${ver} — the grader can spawn its workers (login state not verified: this CLI has no \`auth status\`).` };
+}
+
+// preflightChecks(deps) → [{ level:'ok'|'warn'|'fail', title, detail, fix? }]
+// No printing, no process.exit — callers (setup, doctor, the test) format it.
+function preflightChecks({
+  repoRoot = REPO_ROOT,
+  nodeVersion = process.version,
+  env = process.env,
+  fs = nodeFs,
+  spawn = spawnSync,
+  platform = process.platform,
+} = {}) {
+  const out = [];
+
+  // 1. Node >= 22.
+  const major = Number(String(nodeVersion).replace(/^v/, '').split('.')[0]) || 0;
+  if (major >= MIN_NODE_MAJOR) {
+    out.push({ level: 'ok', title: 'Node', detail: `${nodeVersion} (>= ${MIN_NODE_MAJOR}).` });
+  } else {
+    out.push({
+      level: 'fail',
+      title: 'Node',
+      detail: `${nodeVersion} is below the required v${MIN_NODE_MAJOR}.`,
+      fix: 'Install Node >= 22 — e.g. `brew install node`, `nvm install 22`, or https://nodejs.org.',
+    });
+  }
+
+  // 2. Dependencies installed (node_modules present) — shared with the hot-path
+  //    /builder-start caller via depsFinding() (task 1002403).
+  out.push(depsFinding({ repoRoot, fs }));
+
+  // 3. `claude` CLI launchable — same resolution order the grader uses:
+  //    <PREFIX>_CLAUDE_BIN (legacy spellings still read), then CLAUDE_BIN, then `claude`.
+  const prefixed = resolveEnv('CLAUDE_BIN', { env });
+  const bin = prefixed || env.CLAUDE_BIN || 'claude';
+  // The label names the spelling that actually supplied the value, so a builder who
+  // set the legacy OTB_CLAUDE_BIN is told so rather than shown a name they never set.
+  const viaName = prefixed
+    ? [envPrefix(), ...LEGACY_ENV_PREFIXES].map((p) => `${p}_CLAUDE_BIN`).find((n) => env[n] === prefixed)
+    : env.CLAUDE_BIN ? 'CLAUDE_BIN' : null;
+  const via = viaName ? ` (via ${viaName})` : '';
+  let r;
+  try {
+    r = spawn(bin, ['--version'], { encoding: 'utf8', shell: platform === 'win32', windowsHide: true, timeout: 15000 });
+  } catch (err) { r = { error: err }; }
+  if (r && !r.error && r.status === 0) {
+    const ver = String(r.stdout || '').trim().split('\n')[0] || 'present';
+    // task 1003080: launchable is only HALF this leg — `--version` exits 0 while
+    // the CLI is logged out, so this row used to go green at the exact moment
+    // the thing it checks is broken. claudeAuthFinding proves auth too.
+    out.push(claudeAuthFinding({ bin, via, ver, env, spawn, platform }));
+  } else {
+    const why = r && r.error ? (r.error.code || r.error.message) : `exited ${r ? r.status : '?'}`;
+    out.push({
+      level: 'fail',
+      title: 'claude CLI',
+      detail: `not launchable (${bin}: ${why}) — the grader spawns it per worker, so ships fail grading with SUBAGENT_SPAWN_FAILED.`,
+      fix: 'Run `npm i -g @anthropic-ai/claude-code` (puts a real claude on PATH), or set ' + envPrefix() + '_CLAUDE_BIN to its full path.',
+    });
+  }
+
+  return out;
+}
+
+const GLYPH = { ok: '✓', warn: '!', fail: '✖' };
+const ANSI = { ok: '\x1b[32m', warn: '\x1b[33m', fail: '\x1b[31m', dim: '\x1b[2m', reset: '\x1b[0m' };
+
+// formatPreflight(results, opts) → a printable multi-line string.
+function formatPreflight(results, { color = false, heading = false } = {}) {
+  const c = (k, s) => (color ? `${ANSI[k]}${s}${ANSI.reset}` : s);
+  const lines = [];
+  if (heading) lines.push('Checking your environment…');
+  for (const r of results) {
+    lines.push(`  ${c(r.level, GLYPH[r.level])} ${r.title}: ${r.detail}`);
+    if (r.fix) lines.push(`      ${c('dim', '→')} ${r.fix}`);
+  }
+  return lines.join('\n');
+}
+
+module.exports = { preflightChecks, depsFinding, claudeAuthFinding, formatPreflight, REPO_ROOT, MIN_NODE_MAJOR, HEADLESS_AUTH_ENV };
+
+// Standalone: `node scripts/bongos/preflight.js` — exit 1 if any hard fail.
+if (require.main === module) {
+  const results = preflightChecks();
+  console.log(formatPreflight(results, { color: process.stdout.isTTY, heading: true }));
+  process.exit(results.some((r) => r.level === 'fail') ? 1 : 0);
+}

package/scripts/bongos/probe-cache.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+// scripts/bongos/probe-cache.js — one answer, shared by the sessions that start together
+// (task 1003689).
+//
+// THE MEASUREMENT. SessionStart runs six hooks, three of which call the server. Start
+// four sessions within three seconds — the normal pattern for this project, one worktree
+// per claim — and ALL of them time out:
+//
+//   20:19:53  one session     med  4,797ms   timeouts 0/5
+//   20:49:59  four sessions   med 17,307ms   timeouts 5/5
+//   20:50:00                  med 18,341ms   timeouts 5/5
+//   20:50:01                  med 17,127ms   timeouts 5/5
+//   20:50:02                  med 17,350ms   timeouts 5/5
+//   21:03:46  one session     med  5,942ms   timeouts 0/5
+//
+// Identical config either side. It is contention, not the wrapper: the clean sessions are
+// wrapped too, the same collapse predates the wrapper, and run-node.sh's own cost is +15ms.
+//
+// WHAT IT COSTS. A timed-out SessionStart hook produces NO LINE. So deploy-divergence,
+// strand-watch, push-path-brief and stale-worktrees all go quiet — the truth-teller briefs
+// those hooks exist to emit. The builder gets four sessions flying blind and the only
+// symptom is a non-blocking status code. Silence is indistinguishable from "nothing to
+// report", which is exactly the shape these probes are designed to avoid.
+//
+// THE FIX, and why this one. The four sessions are asking the SAME server the SAME
+// question within three seconds. So the first to arrive answers it and the rest read that
+// answer. Not a jitter/backoff (which spends wall-clock to avoid a stampede that does not
+// need to happen), and not one merged process (which would couple four independent probes
+// into a single failure domain and is a much larger change).
+//
+// EVERY FAILURE MODE FALLS BACK TO "just run the probe". A cache that cannot be read,
+// written, parsed or locked must never be the reason a session loses its brief — that
+// would trade a timeout for a different silence.
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+// Default freshness. The probes this serves answer questions that change on a
+// deploy or a ship — minutes, not seconds — so 60s is generous for a session brief
+// and still collapses any realistic burst of concurrent starts.
+const DEFAULT_TTL_MS = 60_000;
+
+// How long a producer may hold the lock before another process stops waiting for it.
+// Sized just over the slowest observed clean probe (~7.7s), so a genuinely slow
+// answer is still shared rather than re-raced.
+const LOCK_STALE_MS = 10_000;
+
+// Cache lives in the OS temp dir, not the repo: it is derived, per-machine, and must
+// never be committed or survive a reboot.
+//
+// PRIVATE TO THIS USER (0o700), and every record written 0o600. The path is
+// deterministic and os.tmpdir() is world-writable on a multi-user POSIX box, so without
+// this another account could plant a record that readRecord() would parse and trust
+// verbatim — a session brief is not a credential, but it IS agent-facing text, and
+// nothing here should let one user write into another's context.
+function cacheDir() {
+  const dir = path.join(os.tmpdir(), `bongos-probe-cache-${process.getuid ? process.getuid() : os.userInfo().username}`);
+  try { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch { /* fall through; writeRecord fails open */ }
+  return dir;
+}
+
+// THE SCOPE IS THE INSTANCE, NOT THE DIRECTORY (grade round 1). This defaulted to
+// process.cwd(), which defeated the entire fix for the exact scenario it was built for:
+// the measured failure is four sessions in FOUR DIFFERENT WORKTREES — one per claim, the
+// normal pattern here — so four cwds hashed to four keys and nothing was ever shared.
+//
+// The four-process test missed it because all four children ran from one directory. A
+// test that does not model the scenario proves the wrong thing.
+//
+// git's COMMON dir is the right identity: every worktree of one checkout reports the
+// same `.git`, and two unrelated checkouts report different ones — which is the
+// distinction that actually matters, since the probes ask one server about one repo.
+let _scopeCache;
+function defaultScope() {
+  if (_scopeCache !== undefined) return _scopeCache;
+  try {
+    const out = require('node:child_process').execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    _scopeCache = out || process.cwd();
+  } catch {
+    // Not a git checkout, or git is unavailable: fall back to the directory. Worse
+    // sharing, never wrong sharing.
+    _scopeCache = process.cwd();
+  }
+  return _scopeCache;
+}
+
+function cachePath(key, scope = defaultScope()) {
+  const h = crypto.createHash('sha256').update(`${scope}\u0000${key}`).digest('hex').slice(0, 16);
+  return path.join(cacheDir(), `${String(key).replace(/[^a-z0-9._-]/gi, '_')}-${h}.json`);
+}
+
+// PURE — is this record still fresh? Exported so the decision is testable without a
+// clock or a disk.
+function isFresh(record, ttlMs, nowMs) {
+  if (!record || typeof record.at !== 'number') return false;
+  // A record from the FUTURE means the clock moved; treat it as stale rather than
+  // trusting it forever.
+  if (record.at > nowMs) return false;
+  return nowMs - record.at < ttlMs;
+}
+
+function readRecord(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch { return null; }
+}
+
+function writeRecord(file, value, nowMs) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    // Write-then-rename so a reader never sees a half-written record. The temp name
+    // carries the pid so two producers cannot collide on it.
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ at: nowMs, value }), { mode: 0o600 });
+    fs.renameSync(tmp, file);
+    return true;
+  } catch { return false; }
+}
+
+// Take the producer lock, or report who holds it. A lock is just a directory — mkdir
+// is atomic on every platform we run on, where an exclusive file open is not.
+function tryLock(file) {
+  const lock = `${file}.lock`;
+  try {
+    fs.mkdirSync(path.dirname(lock), { recursive: true, mode: 0o700 });
+    fs.mkdirSync(lock, { mode: 0o700 });
+    return { held: true, release: () => { try { fs.rmdirSync(lock); } catch { /* best effort */ } } };
+  } catch {
+    // Someone else is producing — unless their lock is stale, in which case they died
+    // and nobody would ever produce again.
+    try {
+      const age = Date.now() - fs.statSync(lock).mtimeMs;
+      if (age > LOCK_STALE_MS) {
+        fs.rmdirSync(lock);
+        return tryLock(file);
+      }
+    } catch { /* the lock vanished between the two calls: fall through */ }
+    return { held: false, release: () => {} };
+  }
+}
+
+// How long to wait for the process that holds the lock. Shorter than the 10s hook
+// timeout that this exists to stop tripping, and longer than the ~5s a clean probe
+// measured — so the common case is 'the holder answers and everyone reads it'.
+const WAIT_MS = 7_000;
+const POLL_MS = 100;
+
+// Poll for the holder's record. Returns it, or null if the wait expires or the lock
+// disappears without one (the holder died, or its write failed).
+async function waitForRecord(file, ttlMs, now) {
+  const deadline = Date.now() + WAIT_MS;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, POLL_MS));
+    const rec = readRecord(file);
+    if (isFresh(rec, ttlMs, now())) return rec;
+    // The holder is gone and left nothing: stop waiting and do the work ourselves.
+    let locked = true;
+    try { fs.statSync(`${file}.lock`); } catch { locked = false; }
+    if (!locked) {
+      // RE-READ, deliberately — and my own session log called this a redundant read,
+      // which was wrong. `rec` above was taken BEFORE the lock check; the lock
+      // vanishing between the two means the holder finished in that window, so the
+      // record it wrote is exactly what this branch is looking for. Reusing the
+      // earlier miss would discard the answer we waited for and send this caller off
+      // to repeat the probe.
+      //
+      // Down from three reads in the first cut (the ternary re-read twice more); two
+      // is the floor, because the two reads answer different questions.
+      const afterUnlock = readRecord(file);
+      return isFresh(afterUnlock, ttlMs, now()) ? afterUnlock : null;
+    }
+  }
+  return null;
+}
+
+// `producer` is async and returns the value to cache. Returns { value, from } where
+// `from` is 'cache' | 'fresh' | 'stale-while-locked' — exposed because a probe that
+// cannot tell where its answer came from cannot be debugged.
+async function cached(key, producer, opts = {}) {
+  const { ttlMs = DEFAULT_TTL_MS, now = () => Date.now(), scope = defaultScope() } = opts;
+  let file;
+  try { file = cachePath(key, scope); } catch { return { value: await producer(), from: 'fresh' }; }
+
+  const hit = readRecord(file);
+  if (isFresh(hit, ttlMs, now())) return { value: hit.value, from: 'cache' };
+
+  const lock = tryLock(file);
+  if (!lock.held) {
+    // Another session is asking right now.
+    //
+    // With something cached, prefer ITS LAST ANSWER however old: a slightly stale
+    // brief beats the timeout that produces no brief at all.
+    if (hit) return { value: hit.value, from: 'stale-while-locked' };
+    //
+    // With NOTHING cached — the cold start, which is precisely the measured failure
+    // (four fresh sessions, empty cache, all four timing out) — WAIT for the holder
+    // rather than making the same call alongside it. Falling through to the producer
+    // here is what the first cut did, and the four-process test showed it defeats the
+    // whole point: all four still ran.
+    //
+    // The wait is bounded and generous-but-shorter than the hook's own timeout: the
+    // caller has 10-15s and a clean probe measured ~5s, so waiting up to WAIT_MS for a
+    // shared answer is strictly better than adding the call that makes everyone time
+    // out. If the holder never delivers, we do the work — never return nothing.
+    const waited = await waitForRecord(file, ttlMs, now);
+    if (waited) return { value: waited.value, from: 'waited' };
+    return { value: await producer(), from: 'fresh' };
+  }
+
+  try {
+    const value = await producer();
+    writeRecord(file, value, now());
+    return { value, from: 'fresh' };
+  } finally {
+    lock.release();
+  }
+}
+
+// Drop everything. For tests and for an operator who wants a probe to ask again now.
+//
+// The first cut took a `scope` and then only deleted when it was exactly null — so
+// calling it with its own default deleted nothing while reporting success, which is
+// worse than not having it. It takes no argument now: there is one cache dir and this
+// empties it.
+function clear() {
+  try { fs.rmSync(cacheDir(), { recursive: true, force: true }); } catch { /* nothing cached */ }
+}
+
+if (require.main === module) {
+  // `node scripts/bongos/probe-cache.js --clear` — ask everything again on the next start.
+  if (process.argv.includes('--clear')) {
+    const dir = cacheDir();
+    clear();
+    console.log(`probe-cache: cleared ${dir}`);
+  } else {
+    console.log(`probe-cache: ${cacheDir()} (ttl ${DEFAULT_TTL_MS}ms) — --clear to empty it`);
+  }
+}
+
+module.exports = { cached, isFresh, cachePath, cacheDir, clear, defaultScope, DEFAULT_TTL_MS, LOCK_STALE_MS, WAIT_MS };