@bongos/core 1.17.0

package/scripts/gds/onboard.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/onboard.js — `bongos onboard`: the interactive CLI FORM over the
+// canonical onboarding runbook (BONGOS-V1 goal 35, task 1982). Self-serve for a
+// terminal-comfortable owner; drives the SAME step sequence the /new-project skill
+// (task 1981) defines and the hall wizard (task 1983) renders — so all three stay in
+// lockstep. It EXTENDS `bongos init` (which only writes config) with the scaffold →
+// provision → OAuth → verify → brand legs. Standalone model only (ADR 0108).
+//
+// It automates what it can (DNS token preflight, OAuth-cred validation, /healthz
+// verify) and renders the four irreducibly-human steps (create the GitHub repo, the
+// OAuth app + secret, own the domain, first sign-in) as precise, copy-paste-safe
+// prompts. It does NOT hold cloud tokens: the actual provision runs on the control
+// plane (it prints the exact `provision.js` command), preserving the trust boundary.
+
+const readline = require('node:readline');
+const path = require('node:path');
+
+const provision = require(path.join(__dirname, 'provision.js'));   // checkDnsTokenScope, zoneForDomain
+const oauth = require(path.join(__dirname, 'oauth-secret.js'));     // validateClientId/Secret
+
+// ── PURE core (exported for tests) ───────────────────────────────────────────
+
+// The canonical step sequence — the SINGLE source of truth the skill + hall wizard
+// mirror. `kind: 'human'` steps are the irreducibly-manual ones (UI-first prompts).
+// The sequence branches at exactly ONE leg — scaffold — into greenfield (`bongos init`,
+// a fresh empty repo) vs brownfield (`bongos init --adopt`, LAYER onto an existing repo;
+// ADR 0121 §Decision 1 / task 2046). Every other leg is identical, so passing `mode`
+// only relabels the github-repo / init / scaffold steps.
+function onboardPlan(mode = 'greenfield') {
+  const adopt = mode === 'adopt';
+  return [
+    { key: 'name-address', kind: 'auto', label: 'Decide name + address (interview)' },
+    { key: 'github-repo', kind: 'human', label: adopt ? 'Use your EXISTING GitHub repository' : 'Create the empty GitHub repository' },
+    { key: 'dns-preflight', kind: 'auto', label: 'DNS token preflight — before the address step (task 1980)' },
+    { key: 'init', kind: 'auto', label: adopt ? 'bongos init --adopt — LAYER onto the existing repo (pre-flight + accept)' : 'bongos init — scaffold the instance config' },
+    { key: 'scaffold', kind: 'auto', label: adopt ? 'Layer config + pinned @cloudbongos/core onto the existing repo (no clobber)' : 'Scaffold the standalone repo (own repo + pinned @cloudbongos/core)' },
+    { key: 'provision', kind: 'auto', label: 'Provision core + DB + address + service (standalone, task 1978)' },
+    { key: 'oauth-app', kind: 'human', label: 'Wire GitHub sign-in — one-click GitHub App (task 2080), or a manual OAuth app' },
+    { key: 'oauth-place', kind: 'auto', label: 'Place the OAuth secret — auto via the Manifest flow, or verified manual (task 1979)' },
+    { key: 'first-sign-in', kind: 'human', label: 'First sign-in (seats the founding Archon)' },
+    { key: 'verify', kind: 'auto', label: 'Verify /healthz auth_configured' },
+    { key: 'brand', kind: 'auto', label: 'Brand the instance look' },
+  ];
+}
+
+// The exact GitHub OAuth-app values for a domain. The callback is PINNED to the apex
+// /api/gds/auth/web/callback (auth.js WEB_REDIRECT_ORIGIN — a sign-in begun on a
+// builders. subdomain still calls back to the apex). PURE.
+function oauthAppInstructions(domain) {
+  const origin = `https://${domain}`;
+  return {
+    location: "GitHub → your ACCOUNT's Settings → Developer settings → OAuth Apps → New OAuth App",
+    homepageUrl: origin,
+    callbackUrl: `${origin}/api/gds/auth/web/callback`,
+  };
+}
+
+// Build the `bongos init` spec from the interview answers (standalone shape). PURE.
+function buildInitSpec(a = {}) {
+  const spec = {
+    identity: { productName: a.productName, worldName: a.worldName || a.productName, company: a.company ? { name: a.company } : {} },
+    repo: { owner: a.repoOwner, name: a.repoName },
+    firstAdmin: a.firstAdmin || a.repoOwner,
+    version: { id: a.versionId || 'V1', name: a.versionName || `${a.versionId || 'V1'} — Prove the loop`, done_when: a.doneWhen || 'The loop is proven end-to-end.' },
+  };
+  if (a.domain) spec.domains = { publicOrigin: `https://${a.domain}` };
+  if (a.domain || a.slug) spec.provisioning = { shape: 'standalone', domain: a.domain || null, slug: a.slug || null };
+  return spec;
+}
+
+function healthzUrl(domain) { return `https://${domain}/healthz`; }
+
+// ── Interactive shell ────────────────────────────────────────────────────────
+
+function ask(rl, q, dflt) {
+  const suffix = dflt ? ` [${dflt}]` : '';
+  return new Promise((res) => rl.question(`  ${q}${suffix} `, (ans) => res((ans || '').trim() || dflt || '')));
+}
+
+async function run() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const log = (m = '') => console.log(m);
+  try {
+    log('\nbongos onboard — stand up a STANDALONE Cloud Bongos instance (ADR 0108).');
+    log('The canonical sequence; the /new-project skill + hall wizard drive the same steps.\n');
+
+    // Greenfield vs adopt — the one branch in the sequence (ADR 0121 §Decision 1). Greenfield
+    // scaffolds a fresh empty repo; adopt LAYERS onto an existing repo (its own pre-flight + accept).
+    const modeAns = (await ask(rl, 'Greenfield (a NEW empty repo) or adopt (an EXISTING repo)?', 'greenfield')).toLowerCase();
+    const adopt = modeAns.startsWith('a');
+    const a = { mode: adopt ? 'adopt' : 'greenfield' };
+
+    // Step 1 — name + address
+    a.productName = await ask(rl, 'Product name?');
+    a.worldName = await ask(rl, 'World name?', a.productName);
+    a.company = await ask(rl, 'Company (optional)?');
+    a.repoOwner = await ask(rl, 'GitHub repo owner?');
+    a.repoName = await ask(rl, 'GitHub repo name?');
+    a.firstAdmin = await ask(rl, 'First admin (GitHub login — the founding Archon)?', a.repoOwner);
+    a.slug = await ask(rl, 'Instance slug? (DNS/db-safe, e.g. mercury)');
+    a.domain = await ask(rl, 'Domain you own (bring-your-own; blank = decide later)?');
+
+    // Step 2 — human: the GitHub repo (create empty for greenfield; use existing for adopt)
+    if (adopt) {
+      log('\n① Use your EXISTING GitHub repository:');
+      log(`   ${a.repoOwner}/${a.repoName} — the repo you're bringing under Cloud Bongos. Nothing is created or emptied.`);
+      await ask(rl, 'Press Enter once you have that repo checked out locally…');
+    } else {
+      log('\n① Create the GitHub repository (empty):');
+      log(`   github.com → New repository → name it "${a.repoName}" under ${a.repoOwner}, leave it empty, Create.`);
+      await ask(rl, 'Press Enter once the empty repo exists…');
+    }
+
+    // Step 3 — DNS token preflight (before committing the address)
+    if (a.domain) {
+      log('\n② DNS token preflight…');
+      const scope = await provision.checkDnsTokenScope(a.domain);
+      if (scope.reachable) {
+        log(`   ✓ the DNS token can reach zone ${scope.zone}.`);
+      } else {
+        log(`   ✖ ${scope.reason}`);
+        log(`   → ${scope.guidance}`);
+        log('   Resolve this BEFORE provisioning, then re-run `bongos onboard`. Stopping here.');
+        return;
+      }
+    } else {
+      log('\n② DNS preflight skipped (no domain yet) — add one before provisioning, then `bongos provision dns-check <domain>`.');
+    }
+
+    // Step 4 — bongos init (greenfield: scaffold from a spec; adopt: LAYER onto the existing repo)
+    if (adopt) {
+      log('\n③ Layer Cloud Bongos onto the existing repo with `bongos init --adopt`:');
+      log(`   cd into your ${a.repoOwner}/${a.repoName} checkout, then:  node bin/bongos.js init --adopt`);
+      log('   It detects your stack, shows a conflict PRE-FLIGHT (migration / CI / protected-path / boundary), and writes');
+      log('   NOTHING until you accept (interactive y/N, or --accept). It captures your CURRENT version + imports your existing');
+      log('   backlog (GitHub issues / a TODO·ROADMAP·BACKLOG file) — never a synthetic V1, and it never overwrites a file.');
+      await ask(rl, 'Press Enter once `bongos init --adopt` reports "Adopted."…');
+    } else {
+      const spec = buildInitSpec(a);
+      log('\n③ Scaffold the instance config with `bongos init`:');
+      log(`   node bin/bongos.js init --from <spec.json>   (shape: standalone)`);
+      log('   Spec built from your answers:');
+      log('   ' + JSON.stringify(spec));
+      await ask(rl, 'Press Enter once `bongos init` has written config/…');
+    }
+
+    // Step 5 — the standalone repo (greenfield scaffolds it; adopt already layered it in ③)
+    if (adopt) {
+      log('\n④ Your repo is now the standalone instance (ADR 0108):');
+      log('   `bongos init --adopt` already layered config/ + .claude/ + the pinned @cloudbongos/core dep onto it.');
+      log(`   Commit + push ${a.repoOwner}/${a.repoName}. That checkout is what the service runs.`);
+      await ask(rl, 'Press Enter once the layered repo is committed + pushed…');
+    } else {
+      log('\n④ Scaffold the STANDALONE repo (ADR 0108):');
+      log(`   Clone ${a.repoOwner}/${a.repoName} to the control-plane standalone root, add the config/ + .claude/`);
+      log('   from init, pin @cloudbongos/core in its package.json, commit + push. That checkout is what the service runs.');
+      await ask(rl, 'Press Enter once the standalone repo is pushed…');
+    }
+
+    // Step 6 — provision (control plane; trust boundary → print the command)
+    log('\n⑤ Provision (runs on the control plane — it alone holds the cloud tokens):');
+    log(`   node scripts/gds/provision.js provision ${a.slug || '<slug>'} --apply`);
+    log('   (standalone: pull + npm ci → createdb + instance-root migrate → web.env → systemd → DNS → Caddy → /healthz)');
+    await ask(rl, 'Press Enter once provisioning reports the instance active…');
+
+    // Step 7 — human: GitHub sign-in. The ONE-CLICK GitHub App Manifest flow (task 2080)
+    // is the recommended path when a control-plane hall is provisioning this instance —
+    // no OAuth app to hand-create, no secret to paste. This terminal CLI keeps the manual
+    // OAuth-app path below for the standalone/no-hall case.
+    if (a.domain) {
+      const oa = oauthAppInstructions(a.domain);
+      log('\n⑥ Wire GitHub sign-in:');
+      log('   RECOMMENDED — one click: in the control-plane hall, open “Start a project” →');
+      log('   “Set up GitHub sign-in”. Approve the pre-filled GitHub App; the control plane');
+      log('   places the credentials automatically (no secret to paste). Then skip to ⑦.');
+      log('   — or, to create an OAuth app BY HAND —');
+      log(`   ${oa.location}`);
+      log('   (Developer settings is under your ACCOUNT, not the repository.)');
+      log(`   Homepage URL:              ${oa.homepageUrl}`);
+      log(`   Authorization callback URL: ${oa.callbackUrl}`);
+      log('   Copy the Client ID; Generate a new client secret and copy it (shown once).');
+      const clientId = await ask(rl, 'Paste the OAuth Client ID:');
+      const clientSecret = await ask(rl, 'Paste the OAuth Client Secret:');
+      const idV = oauth.validateClientId(clientId);
+      const secV = oauth.validateClientSecret(clientSecret);
+      if (!idV.ok || !secV.ok) {
+        if (!idV.ok) log(`   ✖ client id: ${idV.reason}`);
+        if (!secV.ok) log(`   ✖ client secret: ${secV.reason}`);
+        log('   These look wrong — recheck the OAuth app and re-run. Stopping (nothing placed).');
+        return;
+      }
+      log('   ✓ creds validated. Place them VERIFIED on the control plane:');
+      log(`   node scripts/gds/oauth-secret.js place ${a.slug || '<slug>'} --client-id ${clientId} --client-secret <secret> --apply`);
+      log('   (validates + rewrites web.env via Node + restarts + probes /healthz auth_configured — never hand-edit web.env.)');
+      await ask(rl, 'Press Enter once oauth-secret reports auth_configured=true…');
+
+      // Step 8/9 — first sign-in + verify
+      log('\n⑦ First sign-in (seats the founding Archon):');
+      log(`   Open ${oauthAppInstructions(a.domain).homepageUrl} and sign in with GitHub once.`);
+      await ask(rl, 'Press Enter once you are signed in…');
+      log('\n⑧ Verify:');
+      log(`   curl -s ${healthzUrl(a.domain)}   → expect {"ok":true,"auth_configured":true}`);
+    }
+
+    // Step 10 — brand
+    log('\n⑨ Brand the instance look — fill theme/palette/fonts in config/branding.json (docs/branding-fill-prompt.md).');
+    log('\n✓ onboard walkthrough complete. Your standalone instance is live and owned.\n');
+  } finally {
+    rl.close();
+  }
+}
+
+if (require.main === module) run().catch((e) => { console.error('onboard failed:', e && e.message ? e.message : e); process.exit(1); });
+
+module.exports = { onboardPlan, oauthAppInstructions, buildInitSpec, healthzUrl };

package/scripts/gds/onboarding-analyze.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+// Passive onboarding-friction analysis (V3.R79 / #298, criterion C1).
+//
+// Reads each spooled onboarding transcript, asks an Opus subagent to flag
+// moments of confusion (long unresolved responses, repeated prompts, error
+// recovery), and files one idea_inbox row per flagged session — tagged with
+// onboarding.ONBOARDING_FRICTION_TAG so triage can find them. "Passive" means
+// no human in the loop: it's kicked detached from the SessionStart hook.
+//
+// The pure brains (parse, signals, prompt, validate, payload) live in
+// src/bongos/onboarding.js; the subagent subprocess is reused from src/bongos/grader.js
+// (same `claude -p --model opus` invocation that the quality grader uses).
+//
+// Usage:
+//   node scripts/gds/onboarding-analyze.js [--dry-run] [--only-flagged]
+//                                          [--max N] [--force] [--quiet]
+//
+//   --dry-run       parse + compute signals + print; no subagent, no POST.
+//   --only-flagged  only spend a subagent call on transcripts whose
+//                   deterministic signals already flagged (cost control).
+//   --max N         cap transcripts analyzed this run (default 5).
+//   --force         ignore the consent/window gate (testing).
+//
+// Bounded by design: at most --max per run, a lockfile prevents concurrent
+// runs, and it no-ops instantly when the builder hasn't consented.
+
+const fs = require('node:fs');
+const zlib = require('node:zlib');
+const path = require('node:path');
+const cfg = require('./onboarding-config');
+// The friction analyzer carved into modules/onboarding/ (BV1.R81 / ADR 0093 §1);
+// scripts are outside the kernel boundary, so this CLI requires the module file
+// directly (the grader.js / session-eval.js precedent — the line below already
+// does the same for grading).
+const onboarding = require('../../modules/onboarding/onboarding');
+const grader = require('../../modules/grading/grader');
+const llmCache = require('../../src/bongos/llm-cache'); // System 5 (task 1360): re-analyzing an immutable session is 100% idempotent
+const { apiCall, cliClient, requireSession, arg } = require('./cli-lib');
+llmCache.setApiFallback(apiCall); // task 1381: runs on a builder machine (no DB pool) → reach the cache via the GDS API
+
+const DRY_RUN = process.argv.includes('--dry-run');
+const ONLY_FLAGGED = process.argv.includes('--only-flagged');
+const FORCE = process.argv.includes('--force');
+const QUIET = process.argv.includes('--quiet');
+const MAX_PER_RUN = Math.max(1, Number(arg('--max')) || 5);
+const LOCK_PATH = path.join(cfg.SPOOL_DIR, '.analyze.lock');
+const LOCK_STALE_MS = 30 * 60 * 1000;
+
+function log(...a) {
+  if (!QUIET) console.log(...a);
+}
+
+// Best-effort single-writer lock. Returns true if we hold it.
+function acquireLock() {
+  cfg.ensureDir(cfg.SPOOL_DIR);
+  try {
+    fs.writeFileSync(LOCK_PATH, String(process.pid), { flag: 'wx' });
+    return true;
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+    // Steal a stale lock (a crashed prior run).
+    try {
+      const st = fs.statSync(LOCK_PATH);
+      if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+        fs.writeFileSync(LOCK_PATH, String(process.pid));
+        return true;
+      }
+    } catch (_) {
+      /* fall through */
+    }
+    return false;
+  }
+}
+function releaseLock() {
+  try {
+    fs.unlinkSync(LOCK_PATH);
+  } catch (_) {
+    /* ignore */
+  }
+}
+
+async function analyzeOne(name, entry) {
+  let jsonl;
+  try {
+    jsonl = zlib.gunzipSync(fs.readFileSync(entry.gz)).toString('utf8');
+  } catch (err) {
+    return { name, status: 'unreadable', error: err.message };
+  }
+
+  const { turns, meta } = onboarding.parseTranscript(jsonl);
+  const signals = onboarding.detectFrictionSignals(turns);
+
+  if (DRY_RUN) {
+    return { name, status: 'dry-run', meta, signals, turns: turns.length };
+  }
+
+  if (ONLY_FLAGGED && !signals.flagged) {
+    return { name, status: 'skipped-clean', signals };
+  }
+
+  // Run the Opus subagent on the transcript.
+  const prompt = onboarding.buildAnalysisPrompt({
+    sessionMeta: meta,
+    signals,
+    turns,
+  });
+  let analysis;
+  try {
+    // System 5 (task 1360): a session transcript is immutable, so re-analysis is
+    // 100% idempotent — cache on the session id so a re-run replays at $0.
+    const cache = llmCache.makeCacheSpec({
+      prompt, model: grader.DEFAULT_GRADER_MODEL, task_type: 'onboarding-analyze', scope_sha: String(name),
+    });
+    const { stdout } = await grader.runSubagentCached({
+      prompt,
+      opts: { cwd: process.cwd() },
+      cache,
+    });
+    const result = grader.extractAssistantResult(stdout);
+    analysis = onboarding.validateAnalysis(result);
+  } catch (err) {
+    // Subagent failed. Fall back to deterministic signals: if they flagged
+    // strongly, still file with a low-confidence note; otherwise leave it.
+    if (signals.flagged) {
+      analysis = {
+        ok: false,
+        flagged: true,
+        confidence: 0.3,
+        summary: `Subagent unavailable (${err.code || err.message}); filed from deterministic signals only.`,
+        friction_moments: [],
+      };
+    } else {
+      return { name, status: 'subagent-failed-clean', error: err.code || err.message, signals };
+    }
+  }
+
+  if (!analysis.flagged) {
+    return { name, status: 'not-flagged', signals, summary: analysis.summary };
+  }
+
+  const payload = onboarding.buildIdeaPayload({ sessionMeta: meta, analysis, signals });
+  const api = await cliClient();
+  const resp = await api.inbox.postInbox({
+    body: {
+      title: payload.title,
+      body_md: payload.body_md,
+      kind: payload.kind,
+    },
+  });
+  if (!resp.ok) {
+    return { name, status: 'file-failed', http: resp.status, body: resp.data };
+  }
+  return {
+    name,
+    status: 'filed',
+    idea_id: resp.data?.idea?.id ?? null,
+    moments: analysis.friction_moments.length,
+    confidence: analysis.confidence,
+  };
+}
+
+(async () => {
+  const consent = cfg.readConsent();
+  if (!FORCE && !cfg.onboardingActive(consent)) {
+    process.exit(0); // silent no-op
+  }
+  if (!DRY_RUN) {
+    await requireSession(); // need a token to POST /inbox
+  }
+
+  if (!acquireLock()) {
+    log('[onboarding] another analysis run holds the lock — skipping.');
+    process.exit(0);
+  }
+
+  try {
+    const manifest = cfg.readManifest();
+    const pending = Object.entries(manifest.entries || {})
+      .filter(([, e]) => e && e.gz && !e.analyzed && fs.existsSync(e.gz));
+
+    if (pending.length === 0) {
+      log('[onboarding] nothing to analyze.');
+      return;
+    }
+
+    let analyzed = 0;
+    for (const [name, entry] of pending) {
+      if (analyzed >= MAX_PER_RUN) {
+        log(`[onboarding] hit --max ${MAX_PER_RUN}; ${pending.length - analyzed} left for next run.`);
+        break;
+      }
+      const result = await analyzeOne(name, entry);
+      analyzed += 1;
+
+      if (DRY_RUN) {
+        log(`[onboarding] DRY ${name}: turns=${result.turns} flagged(det)=${result.signals?.flagged} ` +
+          `signals=${JSON.stringify(result.signals && {
+            longThenCorrection: result.signals.longThenCorrection,
+            repeatedSimilarPrompts: result.signals.repeatedSimilarPrompts,
+            errorRecoveryAttempts: result.signals.errorRecoveryAttempts,
+          })}`);
+        continue; // don't mutate manifest in dry-run
+      }
+
+      // Record terminal outcome so we never re-analyze the same snapshot.
+      manifest.entries[name] = {
+        ...entry,
+        analyzed: true,
+        analyzed_at: new Date().toISOString(),
+        outcome: result.status,
+        idea_id: result.idea_id ?? null,
+      };
+      cfg.writeManifest(manifest);
+      log(`[onboarding] ${name}: ${result.status}` +
+        (result.idea_id ? ` → idea #${result.idea_id} (${result.moments} moment(s))` : '') +
+        (result.error ? ` (${result.error})` : ''));
+    }
+  } finally {
+    releaseLock();
+  }
+  process.exit(0);
+})().catch((err) => {
+  releaseLock();
+  console.error('[onboarding] fatal:', err.message);
+  process.exit(1);
+});

package/scripts/gds/onboarding-config.js

@@ -0,0 +1,178 @@
+// Local config + spool I/O for the onboarding-friction pipeline (V3.R79 / #298).
+//
+// Three on-disk artifacts, all under ~/.config/otb/ (same dir as the GDS
+// session token), so they survive worktree churn:
+//
+//   onboarding.json          — the builder's consent decision + onboarding window
+//   onboarding-spool/        — gzipped copies of session transcripts to analyze
+//   onboarding-spool/manifest.json — what's been spooled + analyzed (dedupe)
+//
+// This module is deliberately pure I/O + small predicates; the analysis brains
+// live in src/bongos/onboarding.js. Both onboarding-ship.js and onboarding-analyze.js
+// (and scripts/gds/setup.js for the consent write) import from here so the
+// paths and window math have a single source of truth.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const ic = require('../../src/instance-config');
+
+// The instance config dir (OTB → ~/.config/otb, unchanged; a fresh instance →
+// its neutral dir). R61 / task 1200.
+const CONFIG_DIR = ic.configHome();
+const CONSENT_PATH = path.join(CONFIG_DIR, 'onboarding.json');
+const SPOOL_DIR = path.join(CONFIG_DIR, 'onboarding-spool');
+const MANIFEST_PATH = path.join(SPOOL_DIR, 'manifest.json');
+
+// How long the onboarding window stays open after the consent decision.
+// Friction-mining is for the first stretch of a builder's life; after that
+// they're not "onboarding" and shipping their transcripts would be noise (and
+// a privacy overreach). Override for tests via OTB_ONBOARDING_WINDOW_DAYS.
+const DEFAULT_WINDOW_DAYS = 14;
+
+function windowDays() {
+  const env = Number(process.env.OTB_ONBOARDING_WINDOW_DAYS);
+  return Number.isFinite(env) && env > 0 ? env : DEFAULT_WINDOW_DAYS;
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+// -------------------------------------------------------------------------
+// Consent
+// -------------------------------------------------------------------------
+
+function readConsent() {
+  try {
+    return JSON.parse(fs.readFileSync(CONSENT_PATH, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+// Persist the consent decision. consent=false is recorded too (so we never
+// re-prompt and the pipeline reliably no-ops). Window starts at decision time.
+function writeConsent({ consent }) {
+  ensureDir(CONFIG_DIR);
+  const now = new Date().toISOString();
+  const record = {
+    consent: consent === true,
+    decided_at: now,
+    window_started_at: now,
+    window_days: windowDays(),
+  };
+  fs.writeFileSync(CONSENT_PATH, JSON.stringify(record, null, 2), { mode: 0o600 });
+  return record;
+}
+
+function windowExpiry(record) {
+  if (!record?.window_started_at) return null;
+  const start = new Date(record.window_started_at).getTime();
+  if (!Number.isFinite(start)) return null;
+  const days = Number(record.window_days) || windowDays();
+  return start + days * 24 * 60 * 60 * 1000;
+}
+
+// The single gate the whole pipeline checks: consent given AND still inside
+// the onboarding window. Everything no-ops to false otherwise.
+function onboardingActive(record = readConsent(), now = Date.now()) {
+  if (!record || record.consent !== true) return false;
+  const expiry = windowExpiry(record);
+  if (expiry == null) return false;
+  return now < expiry;
+}
+
+// -------------------------------------------------------------------------
+// Transcript discovery
+//
+// Claude Code stores session transcripts as JSONL under
+//   ~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl
+// where <encoded-cwd> is the absolute project path with every non-alphanumeric
+// char replaced by '-' (e.g. "/Users/x/Desktop/Claude - OTB" becomes
+// "-Users-x-Desktop-Claude---OTB"). We derive the dir from a given cwd so the
+// pipeline works in any worktree without needing the hook's stdin payload.
+// -------------------------------------------------------------------------
+
+function encodeProjectPath(absPath) {
+  return String(absPath).replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+function transcriptDirForCwd(cwd) {
+  return path.join(os.homedir(), '.claude', 'projects', encodeProjectPath(cwd));
+}
+
+// List transcript files (newest first by mtime) for a project dir.
+function listTranscripts(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch (_) {
+    return [];
+  }
+  const files = [];
+  for (const name of entries) {
+    if (!name.endsWith('.jsonl')) continue;
+    const full = path.join(dir, name);
+    let st;
+    try {
+      st = fs.statSync(full);
+    } catch (_) {
+      continue;
+    }
+    if (!st.isFile()) continue;
+    files.push({ name, path: full, size: st.size, mtimeMs: st.mtimeMs });
+  }
+  files.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return files;
+}
+
+// -------------------------------------------------------------------------
+// Spool manifest
+//
+// Keyed by transcript basename. We record the size+mtime we spooled so an
+// updated transcript (same session continued in a later run) re-spools and
+// re-analyzes. `analyzed` flips once the analyzer has filed (or decided not to
+// file) for that snapshot.
+// -------------------------------------------------------------------------
+
+function readManifest() {
+  try {
+    return JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
+  } catch (_) {
+    return { entries: {} };
+  }
+}
+
+function writeManifest(manifest) {
+  ensureDir(SPOOL_DIR);
+  fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2), { mode: 0o600 });
+}
+
+// A transcript snapshot is "fresh" (needs re-spooling) when we haven't seen it
+// or its size changed since we last spooled it.
+function needsSpool(manifest, file) {
+  const e = manifest.entries[file.name];
+  if (!e) return true;
+  return e.size !== file.size;
+}
+
+module.exports = {
+  CONFIG_DIR,
+  CONSENT_PATH,
+  SPOOL_DIR,
+  MANIFEST_PATH,
+  DEFAULT_WINDOW_DAYS,
+  windowDays,
+  ensureDir,
+  readConsent,
+  writeConsent,
+  windowExpiry,
+  onboardingActive,
+  encodeProjectPath,
+  transcriptDirForCwd,
+  listTranscripts,
+  readManifest,
+  writeManifest,
+  needsSpool,
+};