@bongos/core 1.17.0

package/src/bongos/middleware/rate-limit.js

@@ -0,0 +1,195 @@
+// src/bongos/middleware/rate-limit.js — V3.R34 (#255).
+//
+// Two sliding-window in-memory limiters that protect write methods on
+// /api/gds/*. Read methods (GET, HEAD, OPTIONS) bypass entirely.
+//
+//   1. Per-IP limiter      — 30 writes / 60s. Anchors on req.ip (which honors
+//                            'trust proxy' in server.js so Cloudflare's
+//                            X-Forwarded-For is what counts). Catches
+//                            unauthenticated abuse and stolen-token replay
+//                            from a single source.
+//
+//   2. Per-session limiter — 60 writes / 60s, keyed on the bearer token (or
+//                            session cookie) if present. Catches a runaway
+//                            authenticated script that's spreading writes
+//                            across multiple IPs.
+//
+//   3. Public-read limiter  — 120 reads / 60s per IP, applied ONLY to the
+//                            unauthenticated /public/* surface (mounted there by
+//                            routes/public.js, NOT globally — the two write
+//                            limiters above bypass reads by design). It exists
+//                            because /public/uptime + /public/repo-health run
+//                            multi-row 90-day aggregates on every uncached call,
+//                            so the surface is a DoS / cost-amplification target
+//                            (red-team #604 / task 1035). 120/min clears a legit
+//                            dashboard load (~13 /public/* fetches per page, and
+//                            browsers honor the routes' Cache-Control so they
+//                            don't re-fetch within the window) with wide margin,
+//                            while capping a cache-ignoring scraper at ~2 req/s.
+//                            Keyed on req.ip — the SAME real-client-IP resolution
+//                            as the per-IP write limiter: Caddy trusts the
+//                            Cloudflare ranges and forwards the client IP, and
+//                            server.js sets 'trust proxy', so req.ip is the end
+//                            user, not Cloudflare's single origin IP.
+//
+// Any limiter tripping → 429 with Retry-After (seconds rounded up to the
+// nearest whole second). Audit middleware still fires on a write 429 — the row
+// in audit_log is forensic value for "who tried too hard." (Reads are never
+// audit-logged, by the GET-skip rule, so a public-read 429 is not recorded.)
+//
+// Storage: a Map of {key → timestamp[]}. Each request walks the array, drops
+// timestamps older than the window, then either pushes the new one (allow)
+// or returns 429 (deny). O(window-size) per request. We sweep the whole Map
+// once per SWEEP_MS to keep memory bounded under load.
+//
+// In-memory means a process restart wipes the windows — which is fine; a
+// burst tracked across restarts is a different kind of problem (we have
+// audit_log + dep-scan for that). The cost of "we forget after a restart"
+// is far cheaper than wiring an external store like Redis for a single-node
+// deployment.
+
+const PER_IP_WINDOW_MS      = 60 * 1000;
+const PER_IP_LIMIT          = 30;
+const PER_SESSION_WINDOW_MS = 60 * 1000;
+const PER_SESSION_LIMIT     = 60;
+const PUBLIC_READ_WINDOW_MS = 60 * 1000;
+const PUBLIC_READ_LIMIT     = 120;
+const SWEEP_MS              = 5 * 60 * 1000;
+
+const ipBuckets         = new Map();
+const sessionBuckets    = new Map();
+const publicReadBuckets = new Map();
+
+const WRITE_METHODS = new Set(['POST', 'PATCH', 'PUT', 'DELETE']);
+// HEAD is metered too: Express runs the GET handler (incl. the DB query) for a
+// HEAD, so it carries the same cost as the GET. OPTIONS never reaches this
+// limiter — the public router answers CORS preflights and returns 204 first.
+const READ_METHODS  = new Set(['GET', 'HEAD']);
+
+function pruneAndCount(bucket, now, windowMs) {
+  const cutoff = now - windowMs;
+  // arr is the in-place timestamps array; trim in place.
+  let i = 0;
+  while (i < bucket.length && bucket[i] < cutoff) i++;
+  if (i > 0) bucket.splice(0, i);
+  return bucket.length;
+}
+
+function extractSessionKey(req) {
+  // Bearer token first (CLI flow); cookie second (web flow). We use the
+  // token AS-IS as the limiter key — it's already opaque + cheap to hash to
+  // its column in the Map. The token never leaves this process.
+  const authHeader = req.headers && req.headers.authorization;
+  if (authHeader && /^Bearer\s+/.test(authHeader)) {
+    return 'b:' + authHeader.replace(/^Bearer\s+/, '').trim();
+  }
+  const cookie = req.headers && req.headers.cookie;
+  if (cookie) {
+    const m = /(?:^|;\s*)(?:gds_session|pms_session)=([^;]+)/.exec(cookie);
+    if (m) return 'c:' + m[1];
+  }
+  return null;
+}
+
+function sweep() {
+  const now = Date.now();
+  for (const [k, arr] of ipBuckets) {
+    pruneAndCount(arr, now, PER_IP_WINDOW_MS);
+    if (arr.length === 0) ipBuckets.delete(k);
+  }
+  for (const [k, arr] of sessionBuckets) {
+    pruneAndCount(arr, now, PER_SESSION_WINDOW_MS);
+    if (arr.length === 0) sessionBuckets.delete(k);
+  }
+  for (const [k, arr] of publicReadBuckets) {
+    pruneAndCount(arr, now, PUBLIC_READ_WINDOW_MS);
+    if (arr.length === 0) publicReadBuckets.delete(k);
+  }
+}
+
+// Schedule the sweep. unref() so it doesn't keep the process alive during
+// graceful shutdown in tests.
+const sweepTimer = setInterval(sweep, SWEEP_MS);
+if (typeof sweepTimer.unref === 'function') sweepTimer.unref();
+
+function rateLimitMiddleware(req, res, next) {
+  if (!WRITE_METHODS.has(req.method)) return next();
+
+  const now = Date.now();
+
+  // --- per-IP ---
+  const ip = req.ip || req.socket?.remoteAddress || 'unknown';
+  let ipBucket = ipBuckets.get(ip);
+  if (!ipBucket) { ipBucket = []; ipBuckets.set(ip, ipBucket); }
+  const ipCount = pruneAndCount(ipBucket, now, PER_IP_WINDOW_MS);
+  if (ipCount >= PER_IP_LIMIT) {
+    const oldest = ipBucket[0];
+    const retryAfter = Math.max(1, Math.ceil((oldest + PER_IP_WINDOW_MS - now) / 1000));
+    res.set('Retry-After', String(retryAfter));
+    res.set('X-RateLimit-Scope', 'per-ip');
+    res.set('X-RateLimit-Limit', String(PER_IP_LIMIT));
+    res.set('X-RateLimit-Window-Seconds', String(PER_IP_WINDOW_MS / 1000));
+    return res.fail('rate_limited', 429, { scope: 'per-ip', retry_after_seconds: retryAfter });
+  }
+
+  // --- per-session ---
+  const sessionKey = extractSessionKey(req);
+  if (sessionKey) {
+    let sBucket = sessionBuckets.get(sessionKey);
+    if (!sBucket) { sBucket = []; sessionBuckets.set(sessionKey, sBucket); }
+    const sCount = pruneAndCount(sBucket, now, PER_SESSION_WINDOW_MS);
+    if (sCount >= PER_SESSION_LIMIT) {
+      const oldest = sBucket[0];
+      const retryAfter = Math.max(1, Math.ceil((oldest + PER_SESSION_WINDOW_MS - now) / 1000));
+      res.set('Retry-After', String(retryAfter));
+      res.set('X-RateLimit-Scope', 'per-session');
+      res.set('X-RateLimit-Limit', String(PER_SESSION_LIMIT));
+      res.set('X-RateLimit-Window-Seconds', String(PER_SESSION_WINDOW_MS / 1000));
+      return res.fail('rate_limited', 429, { scope: 'per-session', retry_after_seconds: retryAfter });
+    }
+    sBucket.push(now);
+  }
+
+  // record the allow on the IP bucket
+  ipBucket.push(now);
+  next();
+}
+
+// Per-IP read limiter for the unauthenticated /public/* surface. Mounted by
+// routes/public.js scoped to '/public' (NOT globally), so it only ever sees
+// public reads — the global rateLimitMiddleware above still bypasses reads
+// everywhere else. See limiter #3 in the header comment for the rationale.
+function publicReadRateLimitMiddleware(req, res, next) {
+  // Only meter reads. There are no write routes under /public; if one is ever
+  // added it falls through to the global write limiter, so pass it along here.
+  if (!READ_METHODS.has(req.method)) return next();
+
+  const now = Date.now();
+  const ip = req.ip || req.socket?.remoteAddress || 'unknown';
+  let bucket = publicReadBuckets.get(ip);
+  if (!bucket) { bucket = []; publicReadBuckets.set(ip, bucket); }
+  const count = pruneAndCount(bucket, now, PUBLIC_READ_WINDOW_MS);
+  if (count >= PUBLIC_READ_LIMIT) {
+    const oldest = bucket[0];
+    const retryAfter = Math.max(1, Math.ceil((oldest + PUBLIC_READ_WINDOW_MS - now) / 1000));
+    res.set('Retry-After', String(retryAfter));
+    res.set('X-RateLimit-Scope', 'public-read');
+    res.set('X-RateLimit-Limit', String(PUBLIC_READ_LIMIT));
+    res.set('X-RateLimit-Window-Seconds', String(PUBLIC_READ_WINDOW_MS / 1000));
+    return res.fail('rate_limited', 429, { scope: 'public-read', retry_after_seconds: retryAfter });
+  }
+  bucket.push(now);
+  next();
+}
+
+module.exports = {
+  rateLimitMiddleware,
+  publicReadRateLimitMiddleware,
+  // exported for tests + the security-baseline-check script
+  PER_IP_WINDOW_MS,
+  PER_IP_LIMIT,
+  PER_SESSION_WINDOW_MS,
+  PER_SESSION_LIMIT,
+  PUBLIC_READ_WINDOW_MS,
+  PUBLIC_READ_LIMIT,
+};

package/src/bongos/module-scope-map.js

@@ -0,0 +1,271 @@
+// module-scope-map.js — the module → path-globs + `protected` roster (BV1.R54, ADR 0086 §4).
+//
+// This is the SOURCE OF THE SCOPE WALL for the goal-scoped work hierarchy. A goal
+// is scoped to a set of modules; this map says (a) which file paths each module
+// owns — the territory a goal member may author tasks within (consumed by the
+// scope-subset check, BV1.R59 / goal-scope-check.js, via touchesOverlap) — and
+// (b) whether that module is `protected` (its territory intersects the trust /
+// ship-pipeline / migration / authz core), which makes creating a goal scoped to
+// it Archon-only (BV1.R57 / POST /goals).
+//
+// TWO HARD RULES (ADR 0086 §7; the SEC #863 "second list that drifts" failure mode):
+//   1. `protected` is DERIVED, never hand-set — a module is protected iff its
+//      globs overlap PROTECTED_GLOBS, the SINGLE source in permission-path-check.js.
+//   2. We IMPORT PROTECTED_GLOBS; we never re-declare it. A fitness check
+//      (scripts/gds/fitness.js) reds the build if this file re-declares it.
+//
+// GLOB FORMAT = the touches[] convention (path-match.js): an exact path matches
+// one file; a trailing '/' covers the whole subtree. No '*'/'**' wildcards — the
+// goal scope-subset check is touchesOverlap (prefix-aware both directions), not a
+// regex, so wildcards would never match. Every PROTECTED_GLOBS entry is likewise
+// an exact path or dir-prefix, so the overlap is exact.
+//
+// FIRST CUT, auto-tightening. We are mid-strangler (ADR 0083): only dev-box has
+// moved into modules/<key>/; the rest still live fused in src/bongos/. So a module's
+// globs list WHERE ITS CODE LIVES TODAY plus its modules/<key>/ home, and the
+// `protected` result reflects the current tree (most core domains are protected
+// because their routes still sit under the blanket-protected src/bongos/routes/).
+// As ADR 0083 moves a module's code into modules/<key>/, edit its globs here —
+// the carve precedes the feature (ADR 0086 §4). The roster is the decided ~16
+// modules + kernel from docs/design/modular-architecture/02-module-map.md §6.
+//
+// RELATION to src/modules.js: that registry tracks only the OPTIONAL feature
+// modules (game/art-pipeline/discord/dev-box) an instance toggles. This map is a
+// SUPERSET — every module including the always-on core domains — because the goal
+// scope wall must place ALL work, not just the optional features.
+
+'use strict';
+
+const { PROTECTED_GLOBS } = require('./permission-path-check');
+const { touchesOverlap } = require('./path-match');
+
+// key → the path globs that constitute the module's code (exact paths or
+// trailing-'/' subtree prefixes). See the header for the auto-tighten contract.
+const MODULE_GLOBS = {
+  // --- the trust kernel: auth, rank, db pool, loader, seam registry, audit,
+  //     config/identity, the route mount table, the server entrypoint ---
+  kernel: [
+    'src/bongos/auth.js', 'src/bongos/db.js', 'src/bongos/db-kernel.js', 'src/bongos/pool.js',
+    'src/bongos/routes.js', 'src/bongos/route-rank-check.js',
+    'src/bongos/permission-path-check.js', 'src/bongos/sensitive-surfaces.js',
+    'src/bongos/middleware/', 'src/bongos/live-channel.js', 'src/bongos/secret-box.js',
+    'src/bongos/repo-info.js', 'src/bongos/api-path-404.js', 'src/bongos/serve-internal.js',
+    'src/bongos/module-scope-map.js', 'src/bongos/hierarchy-config.js',
+    'src/instance-config.js', 'src/branding.js', 'src/modules.js',
+    'src/module-api.js', 'src/module-loader/',
+    // security-the-PROPERTY: the threat-model (/security/adr) + Archon-only
+    // exploit-detail engagement-doc store (/security/docs). Stays kernel when the
+    // red-team FEATURE carved to modules/security/ (BV1.R79 / 02-module-map §5).
+    'src/bongos/routes/security.js',
+    'server.js', 'config/',
+  ],
+  // --- the build state machine + ship/grade/deploy orchestration + schema ---
+  // Carved into modules/lifecycle/ (BV1.R86 / ADR 0093 §1,§3): the task/claim/
+  // version/goal/done-when/dependency/gate-approvals routes + the db slice, the
+  // task-classifier + hierarchy + done-when libs, github-push + ship-card +
+  // ship-preflight + merge-lock + conflict-resolve + publish-reconciler +
+  // version-close, and the `lifecycle` kernel PORT — all under the
+  // modules/lifecycle/ glob. The db.js RESIDUE (kernel identity/auth/twin/leak)
+  // stays under the kernel key. The lifecycle CLIs travel with the domain but stay
+  // under scripts/; `migrations/` stays here (the schema is lifecycle territory for
+  // goal-scope/task-affinity).
+  lifecycle: [
+    'modules/lifecycle/',
+    'scripts/gds/ship.js', 'scripts/gds/claim.js', 'scripts/gds/release.js',
+    'scripts/gds/merge-mode.js', 'scripts/gds/confirm.js', 'scripts/gds/main-audit.js',
+    'scripts/gds/gate-review.js', 'scripts/gds/push-main.js', 'scripts/gds/ci-grade.js',
+    'scripts/gds/merge-lock.js', 'scripts/gds/version-close.js',
+    'migrations/',
+  ],
+  // --- credit-allocation model + ledger + pricing + gamification ---
+  economy: [
+    // Carved into modules/economy/ (BV1.R77 / ADR 0093 §1-2): credits, cost,
+    // streak, achievements, leaderboard + the `reward` kernel PORT. llm-pricing.js
+    // stays core shared LLM-cost infra (doorway leak `llmPricing`, like llm-cache.js).
+    'src/bongos/llm-pricing.js',
+    'modules/economy/',
+  ],
+  // --- grade-a-diff adversarial panel (the `grade` kernel PORT — BV1.R73) ---
+  grading: [
+    // grader.js + grader-workers/ + grader-rubric.json carved to modules/grading/
+    // (BV1.R73, ADR 0091 §4). cascade-dispatch.js stays a CORE lib (dormant
+    // System 3; its deps are lifecycle + builder-settings, not the grader — see
+    // modules/grading/CLAUDE.md "NOT in this module"); grade-smoke is its CLI.
+    'modules/grading/',
+    'src/bongos/cascade-dispatch.js', 'scripts/gds/grade-smoke.js',
+  ],
+  // --- memory, recall, search, learnings ---
+  memory: [
+    // Carved into modules/memory/ (BV1.R72 / ADR 0091 §2); the memory-owned CLIs
+    // stay under scripts/gds/ (a command travels with its domain — design 02§1).
+    'modules/memory/',
+    'scripts/gds/recall.js', 'scripts/gds/learning-capture.js',
+    'scripts/gds/search-ingest-md.js', 'scripts/gds/search-ingest-db.js',
+  ],
+  // --- admission, setup, newcomer floor ---
+  // Carved into modules/onboarding/ (BV1.R81 / ADR 0093 §1): the friction
+  // analyzer + onboarding state machine + newcomer-restock + the access-request
+  // admission routes + approval-broadcast + their db slice + the `onboarding`
+  // kernel PORT all moved (covered by the modules/onboarding/ glob). The core
+  // lifecycle (db.js claim/ship), auth callbacks, and the me/builders profile
+  // readers resolve the port — they stay in core (kernel / builder-settings).
+  // The onboarding-domain CLIs travel with the domain but stay under scripts/.
+  onboarding: [
+    'modules/onboarding/',
+    'scripts/gds/setup.js', 'scripts/gds/onboarding-config.js',
+    'scripts/gds/onboarding-analyze.js', 'scripts/gds/newcomer-floor.js',
+  ],
+  // --- inbox, capture, triage, blockers (carved → modules/ideas/, BV1.R78) ---
+  ideas: [
+    'modules/ideas/',
+    'scripts/gds/capture.js', 'scripts/gds/triage.js', 'scripts/gds/render-ideas.js',
+  ],
+  // --- builder prefs (wandering/skill/sound/render) + builder-needs ---
+  // Carved into modules/builder-settings/ (BV1.R80 / ADR 0093 §1): the five pref
+  // libs + builder-needs + their db slice + the `/me/*-prefs` routes + the
+  // `builder-settings` kernel PORT. The `GET /me` aggregator stays a thin core
+  // facade (routes/me.js) resolving that port — listed for task affinity. The
+  // pref-mirroring CLIs travel with the domain but stay under scripts/.
+  'builder-settings': [
+    'src/bongos/routes/me.js',
+    'scripts/gds/fetch-sound-prefs.js',
+    'modules/builder-settings/',
+  ],
+  // --- session records, cost/eval/digest, transcript corpus, BFG ---
+  // Carved into modules/sessions/ (BV1.R82 / ADR 0093 §1): bfg.js + pulse.js +
+  // routes/sessions.js + the session_records db slice all moved (covered by the
+  // modules/sessions/ glob). The session-domain CLIs travel with the domain but
+  // stay under scripts/ (session-eval.js keeps its sibling read of
+  // modules/builder-settings/wandering-prefs — scripts are outside the kernel
+  // boundary, so it's not a cross-module import).
+  sessions: [
+    'scripts/gds/session.js', 'scripts/gds/session-cost.js', 'scripts/gds/session-eval.js',
+    'scripts/gds/session-digest.js', 'scripts/gds/backfill-sessions.js',
+    'scripts/gds/bfg-principal-token.js', 'scripts/gds/pulse.js',
+    'scripts/gds/repo-metrics.js',
+    'modules/sessions/',
+  ],
+  // --- conductor dispatch, architect audits, autonomy gate, routine timers ---
+  // Carved into modules/autonomy/ (BV1.R83 / ADR 0093 §1): the autonomy_runs db
+  // slice + the routine-timers poller + the precheck route moved (covered by the
+  // modules/autonomy/ glob). The MAS-domain CLIs (gate / conductor / architect /
+  // run-routine) travel with the domain but stay under scripts/ (a command travels
+  // with its domain — design 02§1), as do the scheduled-task SKILL.md files.
+  autonomy: [
+    'modules/autonomy/',
+    'scripts/gds/autonomy-gate.js',
+    'scripts/gds/conductor-dispatch.js', 'scripts/gds/architect-audit.js',
+    'scripts/gds/run-routine.js', '.claude/scheduled-tasks/',
+  ],
+  // --- red-team reports + bounty (rank-gated Metic+) ---
+  security: [
+    // Carved into modules/security/ (BV1.R79 / ADR 0093 §1): the red-team /
+    // vulnerability-report + bounty FEATURE + the `security` kernel PORT.
+    // security-the-PROPERTY (the /security/adr threat-model reader + /security/docs
+    // exploit-detail store in src/bongos/routes/security.js) stays KERNEL — it moved
+    // to the kernel key (02-module-map §5).
+    'modules/security/',
+  ],
+  // --- the two web surfaces ---
+  // BV1.R85: hall-UI graduated to modules/hall-ui/ — public-builders/ moved to
+  // modules/hall-ui/public/ and is now a loader-discovered web-surface module
+  // (contributes.webSurfaces host "builders."). serve-internal keeps the hall's
+  // DEDICATED serving block (re-pointed at the module dir), not the generic
+  // status-style loop. The me/public/leaderboard reads it renders stay SHARED core
+  // in routes/{me,public,builders}.js (the status surface + the off-box mirror read
+  // them too).
+  'hall-ui': ['modules/hall-ui/'],
+  // BV1.R84: status-UI graduated to modules/status-ui/ — public-status/ moved to
+  // modules/status-ui/public/ and is now served by the loader web-surface seam
+  // (moduleWebSurfaces → serve-internal). Its public read endpoints stay SHARED
+  // core in routes/public.js (the hall + the off-box mirror consume them too).
+  'status-ui': ['modules/status-ui/'],
+  // --- feature modules ---
+  // BV1.R49: game graduated to modules/game/ — src/rooms/, src/world/, src/seats.js,
+  // src/db.js, migrations/game/, and public/ all moved there. src/preview-server.js
+  // stays in src/ as the game-only sandbox entrypoint but is owned by the game module.
+  game: [
+    'modules/game/', 'src/preview-server.js',
+  ],
+  'art-pipeline': ['modules/art-pipeline/'],
+  discord: [
+    // The bot, broadcast, link/role seams, channels, and bug-attachments graduated
+    // into modules/discord/ (BV1.R47); the outbound webhook lib + post CLI stay
+    // core/CLI-side under scripts/discord/.
+    'scripts/discord/', 'modules/discord/',
+  ],
+  'dev-box': ['modules/dev-box/', 'devbox-app/'],
+};
+
+// A glob set is protected iff it overlaps the imported PROTECTED_GLOBS — the one
+// source of truth (permission-path-check.js). Prefix-aware both directions
+// (path-match.touchesOverlap), so e.g. a module owning 'src/bongos/routes/inbox.js'
+// is protected because PROTECTED_GLOBS carries the 'src/bongos/routes/' subtree.
+function isProtected(globs) {
+  return touchesOverlap(globs || [], PROTECTED_GLOBS);
+}
+
+// The frozen exported roster: key → { globs:[...], protected:bool } (derived).
+const MODULE_SCOPE_MAP = Object.freeze(
+  Object.fromEntries(
+    Object.entries(MODULE_GLOBS).map(([key, globs]) => [
+      key,
+      Object.freeze({ globs: Object.freeze([...globs]), protected: isProtected(globs) }),
+    ]),
+  ),
+);
+
+function moduleKeys() {
+  return Object.keys(MODULE_SCOPE_MAP);
+}
+
+function isModuleKey(key) {
+  return Object.prototype.hasOwnProperty.call(MODULE_SCOPE_MAP, key);
+}
+
+// { globs, protected } for one module, or null for an unknown key.
+function scopeForModule(key) {
+  return MODULE_SCOPE_MAP[key] || null;
+}
+
+// true / false for a known key; null for an unknown one (caller decides — an
+// unknown module in a goal's scope_modules should fail closed at the route).
+function isProtectedModule(key) {
+  const e = MODULE_SCOPE_MAP[key];
+  return e ? e.protected : null;
+}
+
+// The protected subset — the modules whose goals require Archon to create.
+function protectedModules() {
+  return moduleKeys().filter((k) => MODULE_SCOPE_MAP[k].protected);
+}
+
+// Flatten the globs for a set of module keys into one touches[]-style list — what
+// the goal scope-subset check (BV1.R59) tests a task's touches[] against. Unknown
+// keys contribute nothing (the route validates membership separately).
+function globsForModules(keys) {
+  const out = [];
+  for (const k of keys || []) {
+    const e = MODULE_SCOPE_MAP[k];
+    if (e) out.push(...e.globs);
+  }
+  return out;
+}
+
+// Does a goal scoped to `keys` include any protected module? (goal-create → Archon)
+function scopeIncludesProtected(keys) {
+  return (keys || []).some((k) => isProtectedModule(k) === true);
+}
+
+module.exports = {
+  MODULE_GLOBS,
+  MODULE_SCOPE_MAP,
+  isProtected,
+  moduleKeys,
+  isModuleKey,
+  scopeForModule,
+  isProtectedModule,
+  protectedModules,
+  globsForModules,
+  scopeIncludesProtected,
+};

package/src/bongos/optimizer.js

@@ -0,0 +1,166 @@
+// GDS session optimizer (P1).
+//
+// Recommends a parallel-safe set of tasks for a given session shape:
+//   { builderId, mode, timeBudgetMin, maxParallel }
+//
+// Mode is one of 'active' | 'check-in' | 'autonomous'. The set of tasks
+// that "fit" each mode is derived (not stored) by the tasks_session_fit
+// view in migration 006_pms_v2.sql, computed from automation_tag +
+// manual_degree + blocker presence.
+//
+// Greedy selection:
+//   1. Pull claimable tasks for this builder, joined to tasks_session_fit
+//      so we get fits_session_modes[] + credits_per_minute. Filter to
+//      tasks whose fits_session_modes contains the requested mode.
+//   2. Sort by credits_per_minute DESC NULLS LAST, then priority ASC,
+//      then calibrated minutes ASC.
+//   3. Walk the sorted list; pick a task iff:
+//        - chosen.length < maxParallel
+//        - calibrated estimate <= timeBudgetMin (falls back to raw
+//          est_minutes when calibration is unavailable; NULL passes
+//          through — we accept unestimated tasks rather than silently
+//          skip them). Calibration: see migration 015.
+//        - touches[] is disjoint from every already-chosen task's touches[]
+//   4. Everything not picked becomes the long-tail.
+//
+// We DO NOT enforce sum-of-est_minutes <= timeBudgetMin: this is a
+// PARALLEL set. Each task runs in its own claim/worktree, so the
+// session length is governed by the LONGEST task, not the sum. The
+// per-task est_minutes <= timeBudgetMin guard already enforces that.
+
+const { pool } = require('./pool');
+// touches[] cleanup [5/8] (task 880): the same prefix-aware overlap matcher the
+// claim guard uses, so the planner's "parallel-safe set" agrees with what
+// claimTask / claimTasksBatch will actually allow.
+const { touchesOverlap } = require('./path-match');
+
+const VALID_MODES = ['active', 'check-in', 'autonomous'];
+const DEFAULT_MAX_PARALLEL = 3;
+
+async function optimizeSession({ builderId, mode, timeBudgetMin, maxParallel }) {
+  if (!VALID_MODES.includes(mode)) {
+    throw { code: 'BAD_MODE', validModes: VALID_MODES };
+  }
+  if (!Number.isFinite(timeBudgetMin) || timeBudgetMin <= 0) {
+    throw { code: 'BAD_TIME_BUDGET' };
+  }
+  const cap = Number.isFinite(maxParallel) && maxParallel > 0
+    ? Math.floor(maxParallel)
+    : DEFAULT_MAX_PARALLEL;
+
+  // Join claimable_tasks (already enforces status='ready', not blocked,
+  // touches-disjoint vs other builders' active claims, smoke-filter) with
+  // tasks_session_fit (derived fits_session_modes[] + credits_per_minute).
+  // Also exclude tasks this builder already has an active claim on, mirroring
+  // listClaimableTasks in db.js.
+  const { rows } = await pool.query(
+    `SELECT ct.*, sf.fits_session_modes, sf.credits_per_minute
+       FROM claimable_tasks ct
+       JOIN tasks_session_fit sf ON sf.id = ct.id
+      WHERE $1 = ANY(sf.fits_session_modes)
+        AND NOT EXISTS (
+          SELECT 1 FROM claims c
+           WHERE c.task_id = ct.id
+             AND c.builder_id = $2
+             AND c.released_at IS NULL
+        )
+      ORDER BY sf.credits_per_minute DESC NULLS LAST,
+               ct.priority ASC NULLS LAST,
+               COALESCE(ct.est_minutes_calibrated, ct.est_minutes) ASC NULLS LAST,
+               ct.id ASC`,
+    [mode, builderId]
+  );
+
+  const chosen = [];
+  const longTail = [];
+  const chosenTouches = []; // accumulated touches[] of everything already chosen
+
+  for (const task of rows) {
+    if (chosen.length >= cap) {
+      longTail.push(task);
+      continue;
+    }
+    const effectiveMinutes = task.est_minutes_calibrated ?? task.est_minutes;
+    if (effectiveMinutes != null && effectiveMinutes > timeBudgetMin) {
+      longTail.push(task);
+      continue;
+    }
+    const touches = Array.isArray(task.touches) ? task.touches : [];
+    // Prefix-aware overlap (was JS Set-equality, which missed dir-prefix
+    // adjacency) so the recommended set matches the claim-time guard.
+    if (touchesOverlap(touches, chosenTouches)) {
+      longTail.push(task);
+      continue;
+    }
+    chosen.push(task);
+    for (const t of touches) chosenTouches.push(t);
+  }
+
+  // CLI (scripts/gds/session.js printPlan) expects this exact shape, matching
+  // the local-fallback contract: { recommended, long_tail, rationale_for,
+  // time_used_min, time_budget_min }. The local fallback was written first
+  // and is the canonical contract — this endpoint was diverging in field
+  // names + per-task rationale and crashing the CLI on every 200 response
+  // (idea #12 → task #176).
+  const rationale_for = {};
+  for (const t of chosen) {
+    const m = (t.est_minutes_calibrated ?? t.est_minutes) || 60;
+    const cpm = t.credits_per_minute != null ? Number(t.credits_per_minute) : ((t.credits_reward || 0) / m);
+    const mFmt = m < 60 ? `${m}min` : `${(m / 60).toFixed(1)}h`;
+    rationale_for[t.id] = `${(cpm * 60).toFixed(1)}c/h · ${mFmt} · P${t.priority ?? '?'}`;
+  }
+  const time_used_min = chosen.reduce(
+    (s, t) => s + ((t.est_minutes_calibrated ?? t.est_minutes) || 0),
+    0
+  );
+
+  return {
+    // `recommended` is a touches-DISJOINT set (the prefix-aware overlap filter
+    // above guarantees no two chosen tasks share a path). System 3 (ADR 0079)
+    // relies on that: the overnight builder, when armed, fans these workers from
+    // ONE supervisor that loads orientation once — disjointness is what makes the
+    // concurrent fan claim-safe and merge-safe (the merge leg stays serialized).
+    recommended: chosen,
+    long_tail: longTail,
+    rationale_for,
+    time_used_min,
+    time_budget_min: timeBudgetMin,
+    // rationale stays as a top-level human-readable summary for any non-CLI
+    // consumer (web UI, future dashboards). CLI ignores it; safe to keep.
+    rationale: buildRationale({
+      chosen,
+      longTail,
+      mode,
+      timeBudgetMin,
+      cap,
+    }),
+  };
+}
+
+function buildRationale({ chosen, longTail, mode, timeBudgetMin, cap }) {
+  if (chosen.length === 0) {
+    if (longTail.length === 0) {
+      return `No claimable tasks fit mode '${mode}' for this builder right now.`;
+    }
+    return `No tasks within ${timeBudgetMin}min budget for mode '${mode}'; ${longTail.length} candidate(s) all exceed the budget or conflict.`;
+  }
+  const longest = chosen.reduce(
+    (acc, t) => {
+      const m = t.est_minutes_calibrated ?? t.est_minutes;
+      return m != null && m > acc ? m : acc;
+    },
+    0
+  );
+  const sumCredits = chosen.reduce((acc, t) => acc + (t.credits_reward || 0), 0);
+  const cap_phrase = chosen.length === cap ? ` (capped at max_parallel=${cap})` : '';
+  const longest_phrase = longest > 0
+    ? `; longest task is ${longest}min within ${timeBudgetMin}min budget`
+    : '';
+  return `Selected ${chosen.length} task(s)${cap_phrase}: highest credits-per-minute fitting '${mode}' mode with disjoint touches[]${longest_phrase}. Total reward: ${sumCredits} credits. Long-tail: ${longTail.length} task(s) deferred.`;
+}
+
+module.exports = {
+  optimizeSession,
+  VALID_MODES,
+  DEFAULT_MAX_PARALLEL,
+};