@bugb-technologies/bravos 0.0.0-stage → 1.0.1

package/dist/watch.js

@@ -0,0 +1,873 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, watch as fsWatch } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import * as graph from './codegraph.js';
+import { LOCK_PATH } from './lock.js';
+import { hooksDir, version } from './paths.js';
+import { readAllAnswers, readDraft } from './review.js';
+import { listReports, readMeta, reportDir } from './report/meta.js';
+import { renderFrame } from './watch-frame.js';
+export { buildFrame, layoutFor, renderFrame, tailPath } from './watch-frame.js';
+// @comment -- "bravos watch: a live, read-only, zero-token terminal view of a repository's security work, beside any harness. snapshot() gathers what the briefing gathers (guardlink ci, hypothesis next, tickets, git, gh, intent, proving, SAST, setup) plus the hypothesis and boundary ledgers, the model's size, review answers, branch state and the code graph's own answers; diffSnapshots() turns two snapshots into activity events in memory; watch-frame.ts draws them; handleKey() maps keys to read-only actions. Nothing here writes to the repository."
+export const WATCH_SCHEMA = 'bravos.watch/v1';
+// @comment -- "The newest report's summary for watch, from meta.json only (title, kind, check verdict and counts, exported formats) plus how many commits HEAD has moved since its evidence was gathered; null with no report. Read-only."
+export function readReportSummary(root, env) {
+    const id = listReports(root)[0];
+    if (!id)
+        return null;
+    const m = readMeta(root, id);
+    if (!m)
+        return null;
+    let behind = null;
+    if (m.sha) {
+        const r = spawnSync('git', ['rev-list', '--count', `${m.sha}..HEAD`], { cwd: root, env, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+        behind = r.status === 0 ? Number(r.stdout.trim()) : null;
+    }
+    return {
+        id,
+        kind: m.kind,
+        title: m.title,
+        createdAt: m.createdAt,
+        sha: m.sha,
+        commitsBehind: behind,
+        check: m.check ? { ok: m.check.ok, errors: m.check.errors, warnings: m.check.warnings, findings: m.check.findings, byLevel: m.check.byLevel, bySeverity: m.check.bySeverity, at: m.check.at } : null,
+        index: m.check?.index ?? [],
+        exports: Object.keys(m.exports),
+        dir: reportDir(root, id),
+    };
+}
+const libs = {};
+// @comment -- "The header's plan label from the briefing's licence status: short enough for one bar, honest about trial days and expiry."
+export function planLabel(v) {
+    if (!v || typeof v !== 'object')
+        return { label: 'Free', licensed: false };
+    const tier = typeof v.tier === 'string' ? v.tier.charAt(0).toUpperCase() + v.tier.slice(1) : 'Free';
+    if (v.licensed) {
+        if (v.trial)
+            return { label: `${tier} trial · ${Math.max(0, Math.ceil((v.trial.endsAt - Date.now() / 1000) / 86400))}d left`, licensed: true };
+        return { label: `${tier} · ${v.seats} seat${v.seats === 1 ? '' : 's'}${v.state === 'grace' ? ' · in grace' : ''}`, licensed: true };
+    }
+    if (v.state === 'expired')
+        return { label: `${tier} · expired`, licensed: false };
+    return { label: 'Free', licensed: false };
+}
+export const lib = (name) => (libs[name] ??= import(pathToFileURL(join(hooksDir(), 'lib', name)).href));
+export const runner = async () => (await lib('autopilot.mjs')).asyncRunner;
+export const parseJson = (r) => {
+    try {
+        return r.stdout ? JSON.parse(r.stdout) : null;
+    }
+    catch {
+        return null;
+    }
+};
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const arr = (v) => (Array.isArray(v) ? v : []);
+const fileOf = (c) => String(c.location?.file ?? c.file ?? '?');
+const lineOf = (c) => num(c.location?.line ?? c.line);
+const keyOf = (c) => `${c.threat ?? '?'}|${c.asset ?? '?'}|${fileOf(c)}`;
+const sevRank = (s) => ['critical', 'high', 'medium', 'low'].indexOf(s) >>> 0;
+// @comment -- "One graph question in the shape the Python CLI's `bravos graph --json` printed ({result} or {error: codegraph_unavailable}), so summarizeGraph and graphAnswer read both the old transcript fixtures and the live MCP answers alike."
+export async function askGraph(root, env, question, args = [], timeoutMs = 60000) {
+    if (!graph.graphBin('codegraph-mcp', env))
+        return null;
+    try {
+        return { result: await graph.ask(root, env, question, args, timeoutMs) };
+    }
+    catch (e) {
+        const m = e.message ?? '';
+        if (/no graph|No CodeGraph|codegraph_unavailable|not built/i.test(m))
+            return { error: 'codegraph_unavailable', message: m, remedy: '`bravos graph build .` indexes this repository' };
+        return { error: 'graph_error', message: m };
+    }
+}
+// @comment -- "Folds the graph's own answers (entry-points, auth-boundary, untested-exposures, hotspots, acceptance-register as bravos graph --json gives them) into the panel's facts: currency, size, call resolution per language, entry points, route access levels, which declared exposures a test reaches, hot files the model speaks about, and accepted risks. Pure; a missing answer leaves its part null."
+export function summarizeGraph(a, askedAt) {
+    const r = (x) => x?.result ?? null;
+    const entry = r(a.entry);
+    const auth = r(a.auth);
+    const tests = r(a.tests);
+    const hot = r(a.hot);
+    const accept = r(a.accept);
+    const density = auth?.resolver_density;
+    return {
+        askedAt,
+        currency: (entry ?? auth ?? tests ?? hot)?.graph_currency?.state ?? null,
+        files: num(tests?.classification?.files_in_graph),
+        testFiles: num(tests?.classification?.test_files),
+        callables: num(density?.callables),
+        callEdges: num(tests?.edges?.calls_edges),
+        languages: arr(density?.by_language).map((l) => ({ language: String(l.language ?? '?'), ratio: Number(l.resolution_ratio) || 0, sufficient: l.sufficient !== false })),
+        entry: entry ? { total: Number(entry.total) || 0, byKind: entry.by_kind ?? {}, byBoundary: entry.by_boundary ?? {}, unbound: Number(entry.unbound) || 0 } : null,
+        routes: auth ? { total: Number(auth.routes_total) || 0, byLevel: auth.by_level ?? {} } : null,
+        tests: tests ? { total: Number(tests.total_exposures) || 0, reached: Number(tests.by_verdict?.reached_by_test) || 0, byVerdict: tests.by_verdict ?? {} } : null,
+        hotspots: arr(hot?.hotspots)
+            .filter((h) => h.verdict === 'changes_open_exposure')
+            .slice(0, 5)
+            .map((h) => ({ file: String(h.file ?? '?'), verdict: String(h.verdict), commits: Number(h.commits) || 0, open: Number(h.security?.open_exposures) || 0 })),
+        hotVerdicts: hot?.by_verdict ?? null,
+        acceptances: accept ? { total: Number(accept.total) || 0, expiring: arr(accept.acceptances).filter((x) => x.status === 'expiring').length } : null,
+    };
+}
+// @comment -- "Asks the code graph five read-only questions at once through bravos graph --json (argv, no shell, 60 s cap each) and summarizes them; notBuilt when bravos reports no graph for this checkout, null when bravos is missing."
+export async function graphDetail(root, env) {
+    if (!graph.graphBin('codegraph-mcp', env))
+        return null;
+    const entry = await askGraph(root, env, 'entry-points');
+    if (!entry)
+        return null;
+    if (entry.error === 'codegraph_unavailable')
+        return { notBuilt: true };
+    // The first answer decided whether a graph is there; the other four run together on the same store.
+    const [auth, tests, hot, accept] = await Promise.all(['auth-boundary', 'untested-exposures', 'hotspots', 'acceptance-register'].map((q) => askGraph(root, env, q)));
+    const ok = (x) => (x && !x.error ? x : null);
+    const answers = { entry: ok(entry), auth: ok(auth), tests: ok(tests), hot: ok(hot), accept: ok(accept) };
+    if (!Object.values(answers).some(Boolean))
+        return null;
+    return summarizeGraph(answers, new Date().toISOString());
+}
+// @comment -- "Reads guardlink status's text summary (it has no JSON form) into counts by lowercased label, e.g. assets, threats, controls, flows, boundaries; lines without a number are skipped."
+export function parseStatus(text) {
+    const out = {};
+    for (const line of text.split('\n')) {
+        const m = /^\s*([A-Za-z][A-Za-z ]*?):\s+(-?\d+)/.exec(line);
+        if (m)
+            out[m[1].toLowerCase()] = Number(m[2]);
+    }
+    return Object.keys(out).length ? out : null;
+}
+// @comment -- "Counts open exposures per asset, worst severity first, then most exposures; the asset side of the top-threats list."
+export function topAssets(exposures, n = 5) {
+    const by = new Map();
+    for (const e of exposures) {
+        const cur = by.get(e.asset) ?? { asset: e.asset, count: 0, severity: 'unset' };
+        cur.count += 1;
+        if (sevRank(e.severity) < sevRank(cur.severity))
+            cur.severity = e.severity;
+        by.set(e.asset, cur);
+    }
+    return [...by.values()].sort((a, b) => sevRank(a.severity) - sevRank(b.severity) || b.count - a.count || a.asset.localeCompare(b.asset)).slice(0, n);
+}
+const readRepoVersion = (root) => {
+    try {
+        const p = JSON.parse(readFileSync(join(root, LOCK_PATH), 'utf8'));
+        return typeof p?.bravos_version === 'string' ? p.bravos_version : null;
+    }
+    catch {
+        return null;
+    }
+};
+// @comment -- "Builds one Snapshot for root from the briefing's collect() and the setup, SAST and review readers, with guardlink's hypothesis list beside it; read-only. Boundaries, the model's size and the unannotated check (refreshSlow) and the graph (refreshGraph) carry over from the previous snapshot unless asked for, because they take seconds."
+export async function snapshot(root, env, opts = {}) {
+    const briefing = await lib('briefing.mjs');
+    const setupLib = await lib('setup.mjs');
+    const run = await runner();
+    const prev = opts.previous ?? null;
+    const slow = opts.refreshSlow || !prev;
+    const gl = (args) => run('guardlink', args, { cwd: root, env, timeoutMs: 30000 });
+    const [collected, ledgerR, boundR, statusR, unannR, graphR] = await Promise.all([
+        briefing.collect(root, env, { nextCount: 5 }),
+        gl(['hypothesis', 'list', '--json', '.']),
+        slow ? gl(['hypothesis', 'boundaries', '--json', '.']) : null,
+        slow ? gl(['status', '.']) : null,
+        slow ? gl(['unannotated', '--json']) : null,
+        opts.refreshGraph ? graphDetail(root, env) : null,
+    ]);
+    const i = collected;
+    const g = i.guardlink === 'missing' ? null : (i.guardlink ?? {});
+    const ci = g?.ci ?? null;
+    const exposures = arr(ci?.exposures).map((e) => ({ key: keyOf(e), threat: String(e.threat ?? '?'), asset: String(e.asset ?? '?'), severity: String(e.severity ?? 'unset'), file: fileOf(e), line: lineOf(e) }));
+    const by = (ci?.summary?.by_severity ?? {});
+    const nextTotal = num(g?.next?.total);
+    const setup = setupLib.readSetup(root, i, 'claude');
+    let review = { drafted: false, answers: [] };
+    try {
+        const draft = readDraft(root, 'intent');
+        review = { drafted: true, answers: readAllAnswers(root, draft).files.map((f) => ({ by: f.by, date: f.date })) };
+    }
+    catch {
+        /* no draft yet */
+    }
+    const git = (args) => {
+        const r = spawnSync('git', args, { cwd: root, env, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+        return r.status === 0 ? r.stdout : null;
+    };
+    const porcelain = git(['status', '--porcelain']);
+    const files = porcelain === null ? [] : porcelain.split('\n').filter(Boolean).map((l) => ({ status: l.slice(0, 2).trim() || '?', path: l.slice(3) }));
+    const log = git(['log', '-5', '--format=%h%x09%cI%x09%s']);
+    const commits = (log ?? '').split('\n').filter(Boolean).map((l) => {
+        const [sha, at, ...rest] = l.split('\t');
+        return { sha, at, subject: rest.join('\t') };
+    });
+    const base = i.base ? String(i.base) : null;
+    const lr = base ? git(['rev-list', '--left-right', '--count', `${base}...HEAD`]) : null;
+    const [behind, ahead] = lr ? lr.trim().split(/\s+/).map(Number) : [null, null];
+    const ledgerJ = ledgerR ? parseJson(ledgerR) : null;
+    const ledger = ledgerJ?.summary ? { untested: Number(ledgerJ.summary.untested) || 0, confirmed: Number(ledgerJ.summary.confirmed) || 0, refuted: Number(ledgerJ.summary.refuted) || 0, retest: Number(ledgerJ.summary.retest) || 0 } : null;
+    const boundJ = boundR ? parseJson(boundR) : null;
+    const boundaries = boundR
+        ? boundJ?.summary
+            ? { unverified: Number(boundJ.summary.unverified) || 0, supported: Number(boundJ.summary.supported) || 0, contradicted: Number(boundJ.summary.contradicted) || 0, retest: Number(boundJ.summary.retest) || 0 }
+            : null
+        : (prev?.boundaries ?? null);
+    const model = statusR ? (statusR.status === 0 ? parseStatus(statusR.stdout) : null) : (prev?.model ?? null);
+    let unannotatedChanged = prev?.branchWork.unannotatedChanged ?? null;
+    if (unannR) {
+        const wl = parseJson(unannR);
+        const changed = new Set(files.map((f) => f.path));
+        unannotatedChanged = wl ? arr(wl.worklist).map((w) => (typeof w === 'string' ? w : (w?.file ?? w?.path))).filter((f) => changed.has(f)).length : null;
+    }
+    let graph = prev?.graph ?? { state: String(i.codegraph ?? 'unavailable'), entryPoints: null, byKind: null, detail: null };
+    if (opts.refreshGraph) {
+        if (i.codegraph === 'unavailable')
+            graph = { state: 'unavailable', entryPoints: null, byKind: null, detail: null };
+        else if (graphR && 'notBuilt' in graphR)
+            graph = { state: 'not-built', entryPoints: null, byKind: null, detail: null };
+        else
+            graph = { state: String(i.codegraph ?? 'unavailable'), entryPoints: graphR?.entry?.total ?? null, byKind: graphR?.entry?.byKind ?? null, detail: graphR ?? null };
+    }
+    const s = ci?.summary;
+    return {
+        schema: WATCH_SCHEMA,
+        at: new Date().toISOString(),
+        repo: String(i.repo ?? ''),
+        branch: i.branch ?? null,
+        base,
+        sha: String(i.sha ?? 'unknown'),
+        guardlink: i.guardlink === 'missing' ? 'missing' : ci ? 'ok' : 'unknown',
+        counts: ci
+            ? {
+                open: num(s?.exposures) ?? exposures.length,
+                bySeverity: by,
+                confirmed: arr(ci.confirmed).length,
+                tested: ledger ? ledger.confirmed + ledger.refuted : nextTotal === null ? null : Math.max(0, exposures.length - nextTotal),
+                stale: arr(ci.stale).length,
+            }
+            : null,
+        coverage: s?.coverage ? { percent: Number(s.coverage.percent) || 0, annotated: Number(s.coverage.annotated_files) || 0, source: Number(s.coverage.source_files) || 0 } : null,
+        claims: s
+            ? {
+                annotations: num(s.coverage?.annotations),
+                verified: num(s.verified),
+                unverified: num(s.unverified),
+                drift: Number(s.drift) || 0,
+                orphans: Number(s.orphans) || 0,
+                parseErrors: Number(s.parse_errors) || 0,
+                acceptances: Number(s.acceptances) || 0,
+                expiringAcceptances: Number(s.expiring_acceptances) || 0,
+            }
+            : null,
+        ledger,
+        boundaries,
+        model,
+        tickets: num(g?.tickets?.count),
+        exposures,
+        confirmedKeys: arr(ci?.confirmed).map(keyOf),
+        stale: arr(ci?.stale).map((c) => ({ file: fileOf(c), line: lineOf(c), verb: String(c.verb ?? 'claim') })),
+        next: arr(g?.next?.queue).map((q) => ({ severity: String(q.severity ?? 'unset'), threat: String(q.threat ?? '?'), asset: String(q.asset ?? '?'), file: String(q.file ?? '?'), line: num(q.line), state: String(q.state ?? '?') })),
+        top: ci ? briefing.topThreats(ci.exposures, 5) : [],
+        topAssets: topAssets(exposures),
+        setup: { done: setup.done, total: setup.total, items: setup.items.map((x) => ({ id: x.id, label: x.label, on: x.on })), next: setup.next ? { label: setup.next.label, cta: setup.next.cta, how: setup.next.how } : null },
+        sast: i.sast?.summary ? { total: i.sast.summary.total, reachable: i.sast.summary.reachable, unjoinedReachable: i.sast.summary.unjoinedReachable, staleCommits: i.sast.summary.staleCommits } : null,
+        sastAvailable: !!i.sast?.available?.ok,
+        plan: planLabel(i.licence),
+        graph,
+        team: { prs: num(i.inFlight?.prs), files: num(i.inFlight?.files), numbers: arr(i.inFlight?.numbers) },
+        branchWork: {
+            uncommitted: porcelain === null ? null : files.length,
+            lastCommit: commits[0]?.subject ?? null,
+            ahead: Number.isFinite(ahead) ? ahead : null,
+            behind: Number.isFinite(behind) ? behind : null,
+            files: files.slice(0, 20),
+            commits,
+            unannotatedChanged,
+        },
+        review,
+        intent: String(i.intent?.status ?? 'unknown'),
+        proving: i.proving?.status === 'set' ? String(i.proving.choice) : 'not set',
+        bravos: { cli: version(), repo: readRepoVersion(root) },
+        report: readReportSummary(root, env),
+        workspace: await workspaceView(i, prev, slow, env),
+    };
+}
+// @comment -- "The workspace part of a watch snapshot: members with their counts (from collect at an app folder; refreshed on the slow interval elsewhere, carried over between), the cached cross-service edges, unresolved references and clash count. Null outside a workspace."
+async function workspaceView(i, prev, slow, env) {
+    const ws = i.workspace;
+    if (!ws)
+        return null;
+    let counts = i.workspaceCounts;
+    if (!counts && slow) {
+        const wsLib = await lib('workspace.mjs');
+        const briefing = await lib('briefing.mjs');
+        counts = await wsLib.memberCounts(ws, briefing.runJsonAsync, env, 20000);
+    }
+    const prior = new Map((prev?.workspace?.members ?? []).map((m) => [m.name, m.counts]));
+    return {
+        name: String(ws.name),
+        isAppFolder: !!ws.isAppFolder,
+        member: ws.member ?? null,
+        appFolder: ws.appFolder ?? null,
+        members: ws.members.map((m) => ({ name: m.name, url: m.url ?? '', counts: counts ? (counts[m.name] ?? null) : (prior.get(m.name) ?? null) })),
+        edges: ws.export?.edges ?? null,
+        unresolved: (ws.export?.unresolved ?? []).map((u) => ({ member: u.member, reference: u.reference })),
+        clashes: (ws.export?.clashes ?? []).length,
+    };
+}
+// @comment -- "Turns two snapshots into activity events, in memory: exposures added or gone (and open → mitigated when one disappears from the open list), new confirmations and refutations, retests due, boundaries held or broken, coverage moves, the model's size, setup steps switched on or off, a SAST run, a rebuilt or missing graph, PRs opened or closed, review answers, a new commit, and the branch's uncommitted count."
+export function diffSnapshots(prev, next) {
+    if (!prev)
+        return [];
+    const at = next.at;
+    const out = [];
+    const add = (kind, text, hint) => out.push({ at, kind, text, ...(hint ? { hint } : {}) });
+    const before = new Map(prev.exposures.map((e) => [e.key, e]));
+    const after = new Map(next.exposures.map((e) => [e.key, e]));
+    for (const [k, e] of after)
+        if (!before.has(k))
+            add('exposure+', `new exposure ${e.threat} on ${e.asset} (${e.severity}) — ${e.file}`, 'record or test it');
+    for (const [k, e] of before)
+        if (!after.has(k))
+            add('exposure-', `${e.threat} on ${e.asset}: no longer open (mitigated or removed) — ${e.file}`, 'still untested until a run');
+    const wasConfirmed = new Set(prev.confirmedKeys);
+    for (const k of next.confirmedKeys)
+        if (!wasConfirmed.has(k))
+            add('confirmed', `confirmed exploitable: ${k.split('|').slice(0, 2).join(' on ')}`, 'fix first (/bravos-recheck after)');
+    const staleKey = (s) => `${s.file}:${s.line}`;
+    const wasStale = new Set(prev.stale.map(staleKey));
+    for (const s of next.stale)
+        if (!wasStale.has(staleKey(s)))
+            add('stale', `claim went stale: ${s.file}:${s.line ?? '?'} (${s.verb})`, 'recheck this (/bravos-recheck)');
+    if (prev.coverage && next.coverage && prev.coverage.percent !== next.coverage.percent)
+        add('coverage', `coverage ${prev.coverage.percent}% → ${next.coverage.percent}%`);
+    const wasOn = new Map(prev.setup.items.map((x) => [x.id, x.on]));
+    for (const x of next.setup.items)
+        if (wasOn.has(x.id) && wasOn.get(x.id) !== x.on)
+            add('setup', `${x.on ? 'done' : 'undone'}: ${x.label} (setup ${next.setup.done}/${next.setup.total})`);
+    if (!prev.sast && next.sast)
+        add('sast', `SAST ran: ${next.sast.total} findings, ${next.sast.reachable} reachable`, 'bravos sast candidates');
+    const prBefore = new Set(prev.team.numbers);
+    const prAfter = new Set(next.team.numbers);
+    for (const n of prAfter)
+        if (!prBefore.has(n))
+            add('pr', `PR #${n} opened`);
+    for (const n of prBefore)
+        if (!prAfter.has(n))
+            add('pr', `PR #${n} closed or merged`);
+    const answered = new Set(prev.review.answers.map((a) => a.by));
+    for (const a of next.review.answers)
+        if (!answered.has(a.by))
+            add('review', `${a.by} answered the intent review`, 'bravos review intent --summary');
+    const L0 = prev.ledger;
+    const L1 = next.ledger;
+    if (L0 && L1) {
+        if (L1.refuted > L0.refuted)
+            add('refuted', `${L1.refuted - L0.refuted} exposure(s) tested and refuted (not exploitable)`);
+        if (L1.retest > L0.retest)
+            add('stale', `${L1.retest - L0.retest} confirmed exposure(s) need a retest: their code changed`, 'recheck this (/bravos-recheck)');
+    }
+    const B0 = prev.boundaries;
+    const B1 = next.boundaries;
+    if (B0 && B1) {
+        if (B1.supported > B0.supported)
+            add('boundary', `${B1.supported - B0.supported} boundary claim(s) held when tested`);
+        if (B1.contradicted > B0.contradicted)
+            add('confirmed', `${B1.contradicted - B0.contradicted} boundary claim(s) did not hold`, 'fix first (/bravos-recheck after)');
+    }
+    if (prev.model && next.model) {
+        const keys = ['assets', 'threats', 'controls', 'mitigations', 'flows', 'boundaries', 'audits'];
+        const moved = keys.map((k) => [k, (next.model[k] ?? 0) - (prev.model[k] ?? 0)]).filter(([, d]) => d !== 0);
+        if (moved.length)
+            add('model', `threat model ${moved.map(([k, d]) => `${d > 0 ? '+' : ''}${d} ${k}`).join(', ')}`);
+    }
+    const c0 = prev.branchWork.commits?.[0]?.sha;
+    const c1 = next.branchWork.commits?.[0];
+    if (c0 && c1 && c1.sha !== c0)
+        add('commit', `commit ${c1.sha}: ${c1.subject}`);
+    const d0 = prev.graph.detail;
+    const d1 = next.graph.detail;
+    if (d1 && (!d0 || d0.callEdges !== d1.callEdges || JSON.stringify(d0.languages) !== JSON.stringify(d1.languages)) && prev.graph.state !== 'unavailable')
+        add('graph', `code graph ${d0 ? 'rebuilt' : 'ready'}${d1.languages.length ? `: ${d1.languages.map((l) => `${l.language} ${Math.round(l.ratio * 100)}% resolved`).join(', ')}` : ''}`);
+    if (next.graph.state === 'not-built' && prev.graph.state !== 'not-built')
+        add('graph', 'no code graph for this commit', 'bravos graph build . --scip no-exec');
+    const w0 = prev.workspace ?? null;
+    const w1 = next.workspace ?? null;
+    if (w0 && w1 && w0.name === w1.name) {
+        const key = (e) => `${e.srcMember}:${e.src}->${e.dstMember}:${e.dst}`;
+        if (w0.edges && w1.edges) {
+            const before = new Set(w0.edges.map(key));
+            const after = new Set(w1.edges.map(key));
+            for (const e of w1.edges)
+                if (!before.has(key(e)))
+                    add('workspace', `cross-service edge added: ${e.srcMember} → ${e.dstMember} (${e.src} → ${e.dst})`);
+            for (const e of w0.edges)
+                if (!after.has(key(e)))
+                    add('workspace', `cross-service edge gone: ${e.srcMember} → ${e.dstMember} (${e.src} → ${e.dst})`);
+        }
+        const c0 = new Map(w0.members.map((m) => [m.name, m.counts]));
+        for (const m of w1.members) {
+            const a = c0.get(m.name);
+            if (a && m.counts && m.name !== w1.member && m.counts.open !== a.open)
+                add('workspace', `${m.name}: ${m.counts.open - a.open > 0 ? '+' : ''}${m.counts.open - a.open} open exposure${Math.abs(m.counts.open - a.open) === 1 ? '' : 's'} (now ${m.counts.open})`);
+        }
+    }
+    const r0 = prev.report ?? null;
+    const r1 = next.report ?? null;
+    if (r1 && (!r0 || r0.id !== r1.id))
+        add('report', `report started: ${r1.kind} ${r1.id}`, 'bravos-report writes report.md, then bravos report check');
+    // A check that ran since the last snapshot: a new pass is "report written", a failure names its count.
+    const same = !!(r0 && r1 && r0.id === r1.id);
+    if (r1?.check && (!same || r0?.check?.at !== r1.check.at)) {
+        const ids = r1.index.map((f) => f.id);
+        const span = ids.length ? ` (${ids[0]}${ids.length > 1 ? `…${ids[ids.length - 1]}` : ''})` : '';
+        if (r1.check.ok && !(same && r0?.check?.ok))
+            add('report', `report written: ${r1.title ?? r1.id}${span}`, 'p shows it · bravos report export latest --format pdf');
+        if (!r1.check.ok && !(same && r0?.check && !r0.check.ok && r0.check.errors === r1.check.errors))
+            add('report', `report check failed: ${r1.check.errors} problem${r1.check.errors === 1 ? '' : 's'}`, `bravos report check ${r1.id}`);
+    }
+    if (r1 && r0 && r0.id === r1.id)
+        for (const f of r1.exports)
+            if (!r0.exports.includes(f) && f !== 'md')
+                add('report', `report exported: ${f}`, f === 'pdf' || f === 'html' ? 'o opens it' : undefined);
+    if (prev.branchWork.uncommitted !== null && next.branchWork.uncommitted !== null && prev.branchWork.uncommitted !== next.branchWork.uncommitted) {
+        add('files', `${next.branchWork.uncommitted} uncommitted file${next.branchWork.uncommitted === 1 ? '' : 's'} on this branch (was ${prev.branchWork.uncommitted})`);
+    }
+    return out;
+}
+// @comment -- "Reads the autopilot hook's nudges from .bravos/watch/events.jsonl (local, gitignored); a missing or unreadable log yields none."
+export function readAutopilotEvents(root) {
+    const file = join(root, '.bravos', 'watch', 'events.jsonl');
+    if (!existsSync(file))
+        return [];
+    const out = [];
+    for (const line of readFileSync(file, 'utf8').split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const e = JSON.parse(line);
+            if (typeof e?.at === 'string' && typeof e?.text === 'string')
+                out.push({ at: e.at, kind: 'autopilot', text: e.text });
+        }
+        catch {
+            /* skip a torn line */
+        }
+    }
+    return out;
+}
+/* ------------------------------------------------------------------ keys */
+// @comment -- "The recorded intent for the i overlay: .guardlink/intent.md as written, under a line naming who answered the review; when there is none, how to create it. Read-only."
+export function intentOverlay(root) {
+    const file = join(root, '.guardlink', 'intent.md');
+    if (!existsSync(file)) {
+        return ['INTENT', '', 'No intent recorded yet (.guardlink/intent.md is missing).', '', 'Create it: ask "learn what this app intends" (/bravos-context).', 'Severities are not calibrated to the product until it exists.'];
+    }
+    let who = '';
+    try {
+        const answers = readAllAnswers(root, readDraft(root, 'intent')).files;
+        who = answers.length ? `answered by ${answers.map((a) => `${a.by} (${a.date})`).join(', ')}` : 'no review answers saved yet';
+    }
+    catch {
+        who = 'no review draft';
+    }
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        text = `could not read it: ${e.message}`;
+    }
+    return [`INTENT  .guardlink/intent.md · ${who}`, 'answers vs suggestions: bravos review intent --summary · change it: bravos review intent, or /bravos-context to refresh', '', ...text.replace(/\s+$/, '').split('\n')];
+}
+// @comment -- "The p overlay: the newest report's title, check verdict, findings index (id, evidence level, severity, priority, title), its executive section from report.md, and how to export or open it. Read-only."
+export function reportOverlay(r) {
+    if (!r)
+        return ['REPORT', '', 'No report yet.', '', 'Ask "write the assessment report" (/bravos-report): it gathers the evidence with bravos report data,', 'writes .bravos/reports/<id>/report.md, checks it and exports it.'];
+    const out = [`REPORT  ${r.title ?? '(report.md not written yet)'}`, `${r.kind} · ${r.id} · ${r.check ? (r.check.ok ? 'check passes' : `check: ${r.check.errors} problems (bravos report check ${r.id})`) : 'not checked yet'}${r.commitsBehind ? ` · ${r.commitsBehind} commit${r.commitsBehind === 1 ? '' : 's'} since its evidence` : ''}`, ''];
+    if (r.index.length) {
+        out.push('FINDINGS');
+        for (const f of r.index)
+            out.push(`  ${f.id}  ${(f.level ?? '?').padEnd(11)} ${(f.severity ?? '?').padEnd(8)} ${(f.priority ?? '').padEnd(3)} ${f.title}`);
+        out.push('');
+    }
+    try {
+        const md = readFileSync(join(r.dir, 'report.md'), 'utf8');
+        const m = /^##\s+(?:\d+\.\s*)?(Executive assessment|Retest summary)\s*$([\s\S]*?)(?=^##\s)/im.exec(md + '\n## ');
+        if (m)
+            out.push(m[1].toUpperCase(), ...m[2].trim().split('\n'), '');
+    }
+    catch {
+        /* report.md not written yet */
+    }
+    out.push(`exports: ${r.exports.length ? r.exports.join(', ') : 'none'} — o opens the pdf or html · bravos report export ${r.id} --format md,txt,html,pdf`);
+    return out;
+}
+// @comment -- "The s overlay: every service with its URL and counts, every cross-service edge with its mechanism and where it is declared, and unresolved references; or how to set up a workspace."
+export function servicesOverlay(w) {
+    if (!w)
+        return ['SERVICES', '', 'This repo is not part of a bravos workspace.', '', 'For an app made of several repos: bravos workspace create NAME --member ./svc-a=svc-a@http://127.0.0.1:8081 --member ./svc-b=...'];
+    const out = [`SERVICES  ${w.name}${w.isAppFolder ? ' (app folder)' : ` · this repo is ${w.member}`}`, ''];
+    for (const m of w.members) {
+        const c = m.counts;
+        out.push(`  ${m.name === w.member ? '▸' : ' '} ${m.name.padEnd(16)} ${(m.url || 'no URL').padEnd(26)} ${c ? `${c.open} open · ${(c.bySeverity.critical ?? 0) + (c.bySeverity.high ?? 0)} high+ · ${c.confirmed} confirmed · coverage ${c.coverage ?? '?'}%` : 'counts not read yet'}`);
+    }
+    out.push('', 'CROSS-SERVICE EDGES');
+    if (!w.edges)
+        out.push('  unknown: run bravos workspace show');
+    else if (!w.edges.length)
+        out.push('  none declared: annotate calls as @flows #<this>-<x> -> #<other>-<y> via http|grpc|queue');
+    for (const e of w.edges ?? [])
+        out.push(`  ${e.srcMember}:${e.src} → ${e.dstMember}:${e.dst}${e.mechanism ? `  via ${e.mechanism}` : ''}  (${e.declaredIn})`);
+    if (w.unresolved.length)
+        out.push('', `UNRESOLVED (${w.unresolved.length})`, ...w.unresolved.map((u) => `  ${u.member}: ${u.reference}`));
+    if (w.clashes)
+        out.push('', `${w.clashes} id clash${w.clashes === 1 ? '' : 'es'}: bravos workspace show`);
+    out.push('', w.appFolder ? `graph across services: bravos graph build ${w.appFolder} --scip no-exec` : 'no app folder: the members do not share a parent');
+    return out;
+}
+/** Wraps lines to width, keeping each wrapped piece's indentation; never splits inside a word unless the word alone is too long. */
+export function wrapLines(lines, width) {
+    const w = Math.max(10, width);
+    const out = [];
+    for (const line of lines) {
+        const chars = [...line];
+        if (chars.length <= w) {
+            out.push(line);
+            continue;
+        }
+        const indent = /^\s*(?:[-*] |\d+\. )?/.exec(line)?.[0].replace(/\S/g, ' ') ?? '';
+        let rest = line;
+        let first = true;
+        while ([...rest].length > (first ? w : w - indent.length)) {
+            const room = first ? w : w - indent.length;
+            const head = [...rest].slice(0, room).join('');
+            const cut = head.lastIndexOf(' ') > room / 3 ? head.lastIndexOf(' ') : room;
+            out.push((first ? '' : indent) + [...rest].slice(0, cut).join('').replace(/\s+$/, ''));
+            rest = [...rest].slice(cut).join('').replace(/^\s+/, '');
+            first = false;
+        }
+        if (rest)
+            out.push((first ? '' : indent) + rest);
+    }
+    return out;
+}
+/** The script this bravos runs from, so keys start the same bravos, not whichever is first on PATH. */
+const selfArgs = () => (process.argv[1] ? [process.argv[1]] : []);
+// @comment -- "Turns a bravos graph answer into overlay lines: the result as indented JSON, or bravos's own error message and remedy when it reports one, or a one-line failure."
+export function graphAnswer(status, stdout, failure = '') {
+    try {
+        const j = JSON.parse(stdout || '');
+        if (j?.error)
+            return [`no answer: ${j.message ?? j.error}`, ...(j.remedy ? [`fix: ${j.remedy}`] : [])];
+        if (status === 0)
+            return JSON.stringify(j?.result ?? j, null, 2).split('\n');
+    }
+    catch {
+        /* not JSON */
+    }
+    return [`no answer${failure ? `: ${failure}` : status !== null ? ` (exit ${status})` : ''}`];
+}
+// @comment -- "Maps one key to a read-only action: copy the next command, open the intent review or guardlink's dashboard, ask the graph, show test-next, the recorded intent or the guide, scroll, refresh everything now, or quit; anything else does nothing."
+export function handleKey(key, sn, root = '.') {
+    switch (key) {
+        case 'n':
+            return sn?.setup.next ? { kind: 'copy', text: sn.setup.next.cta } : { kind: 'none' };
+        case 'r':
+            return { kind: 'spawn', cmd: process.execPath, args: [...selfArgs(), 'review', 'intent'], note: 'opening the intent review page' };
+        case 'd': {
+            // Written outside the repository so the key never changes the working tree.
+            const file = join(tmpdir(), `bravos-dashboard-${basename(root) || 'repo'}.html`);
+            return { kind: 'spawn', cmd: 'guardlink', args: ['dashboard', '.', '-o', file], note: `writing guardlink's dashboard to ${file}`, open: file };
+        }
+        case 'g':
+            return { kind: 'overlay', what: 'graph' };
+        case 't':
+            return { kind: 'overlay', what: 'next' };
+        case 'p':
+            return { kind: 'overlay', what: 'report' };
+        case 's':
+            return { kind: 'overlay', what: 'services' };
+        case 'o':
+            return { kind: 'open-report' };
+        case 'i':
+            return { kind: 'overlay', what: 'intent' };
+        case '?':
+            return { kind: 'overlay', what: 'guide' };
+        case 'j':
+        case '\u001b[B':
+            return { kind: 'scroll', by: 1 };
+        case 'k':
+        case '\u001b[A':
+            return { kind: 'scroll', by: -1 };
+        case ' ':
+        case '\u001b[6~':
+            return { kind: 'scroll', by: 10 };
+        case 'b':
+        case '\u001b[5~':
+            return { kind: 'scroll', by: -10 };
+        case '\u001b[H':
+            return { kind: 'scroll', by: 'top' };
+        case 'G':
+        case '\u001b[F':
+            return { kind: 'scroll', by: 'end' };
+        case 'u':
+            return { kind: 'refresh' };
+        case 'q':
+        case '\u0003':
+            return { kind: 'quit' };
+        default:
+            return { kind: 'none' };
+    }
+}
+/* ------------------------------------------------------------------ live loop */
+const ESC = '\x1b[';
+const clock = (d) => [d.getHours(), d.getMinutes(), d.getSeconds()].map((n) => String(n).padStart(2, '0')).join(':');
+// @comment -- "Which file changes do not trigger a redraw: git's internals except HEAD and refs (git status itself rewrites .git/index, which would loop), node_modules, bravos's SAST runs and its own watch folder except the autopilot log."
+export function ignoredChange(name) {
+    const n = name.replace(/\\/g, '/');
+    if (n === '.git' || n.startsWith('.git/'))
+        return !(n === '.git/HEAD' || n.startsWith('.git/refs/'));
+    if (n.startsWith('node_modules/') || n.includes('/node_modules/'))
+        return true;
+    if (n.startsWith('.bravos/sast/'))
+        return true;
+    if (n.startsWith('.bravos/watch/'))
+        return n !== '.bravos/watch/events.jsonl';
+    // A report redraws watch when its meta.json changes (written by report data, check and export).
+    if (n.startsWith('.bravos/reports/'))
+        return !n.endsWith('/meta.json');
+    return false;
+}
+function openTarget(target) {
+    const [cmd, args] = process.platform === 'darwin' ? ['open', [target]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', target]] : ['xdg-open', [target]];
+    spawn(cmd, args, { detached: true, stdio: 'ignore' }).on('error', () => { }).unref();
+}
+function copyToClipboard(text) {
+    const tries = process.platform === 'darwin' ? [['pbcopy', []]] : process.platform === 'win32' ? [['clip', []]] : [['wl-copy', []], ['xclip', ['-selection', 'clipboard']]];
+    for (const [cmd, args] of tries) {
+        const r = spawnSync(cmd, args, { input: text, stdio: ['pipe', 'ignore', 'ignore'] });
+        if (r.status === 0)
+            return true;
+    }
+    return false;
+}
+// @comment -- "Runs the live view in a TTY: alternate screen, redraw on file changes (debounced, one snapshot at a time), the slow parts (boundaries, model size, PRs) every interval and the code graph every graphInterval, keys for read-only actions and scrolling, and a clean restore on q, Ctrl-C, SIGTERM or a crash. Never writes to the repository."
+export async function runWatch(root, env, opts) {
+    const out = process.stdout;
+    const events = [];
+    const history = [];
+    let sn = null;
+    let busy = false;
+    let pending = null;
+    let note = '';
+    let overlay = null;
+    let overlayScroll = 0;
+    let seenAutopilot = 0;
+    let graphPrompt = null;
+    let scroll = 0;
+    let maxScroll = 0;
+    let refreshes = 0;
+    let lastMs = null;
+    let lastGraph = 0;
+    const graphEvery = Math.max(30, opts.graphIntervalSec ?? 300) * 1000;
+    const draw = () => {
+        if (!sn) {
+            out.write(`${ESC}H${ESC}2Jbravos watch — reading ${basename(root)} (guardlink, git, gh, the code graph)…`);
+            return;
+        }
+        const width = out.columns || 100;
+        const height = out.rows || 40;
+        const status = busy ? 'updating…' : `● live ${clock(new Date())}`;
+        let frame;
+        if (overlay) {
+            const all = wrapLines(overlay, width);
+            const room = Math.max(1, height - 2);
+            overlayScroll = Math.max(0, Math.min(overlayScroll, all.length - room));
+            const shown = all.slice(overlayScroll, overlayScroll + room);
+            const where = all.length > room ? `${overlayScroll + 1}–${overlayScroll + shown.length} of ${all.length} · j/k, space, b to scroll · ` : '';
+            frame = [...shown, '', `(${where}any other key closes)`].join('\n');
+        }
+        else {
+            const r = renderFrame(sn, events, { width, height: height - (graphPrompt !== null ? 1 : 0), color: opts.color, status, compact: opts.compact, scroll, history, note, stats: { refreshes, lastMs } });
+            maxScroll = r.maxScroll;
+            scroll = Math.min(scroll, maxScroll);
+            frame = r.text;
+        }
+        if (graphPrompt !== null)
+            frame += `\ngraph question (Enter to ask, Esc to cancel): ${graphPrompt}█`;
+        out.write(`${ESC}H${ESC}2J${frame}`);
+    };
+    const refresh = async (want = {}) => {
+        const graph = !!want.graph || !sn || Date.now() - lastGraph > graphEvery;
+        if (busy) {
+            pending = { slow: !!want.slow || !!pending?.slow, graph: graph || !!pending?.graph };
+            return;
+        }
+        busy = true;
+        draw();
+        const started = Date.now();
+        try {
+            const next = await snapshot(root, env, { refreshGraph: graph, refreshSlow: !!want.slow, previous: sn });
+            if (graph)
+                lastGraph = Date.now();
+            events.push(...diffSnapshots(sn, next));
+            const auto = readAutopilotEvents(root);
+            if (auto.length > seenAutopilot)
+                events.push(...auto.slice(seenAutopilot));
+            seenAutopilot = auto.length;
+            if (events.length > 50)
+                events.splice(0, events.length - 50);
+            history.push({ at: next.at, open: next.counts?.open ?? null, coverage: next.coverage?.percent ?? null });
+            if (history.length > 120)
+                history.splice(0, history.length - 120);
+            sn = next;
+            refreshes += 1;
+            lastMs = Date.now() - started;
+        }
+        catch (e) {
+            note = `refresh failed: ${e.message}`;
+        }
+        finally {
+            busy = false;
+            draw();
+            if (pending) {
+                const p = pending;
+                pending = null;
+                void refresh(p);
+            }
+        }
+    };
+    out.write(`${ESC}?1049h${ESC}?25l`);
+    let restored = false;
+    const restore = () => {
+        if (restored)
+            return;
+        restored = true;
+        out.write(`${ESC}?25h${ESC}?1049l`);
+    };
+    // A crash must still give the person their terminal back.
+    process.once('exit', restore);
+    let debounce;
+    const watcher = fsWatch(root, { recursive: true }, (_e, f) => {
+        const name = String(f ?? '');
+        if (ignoredChange(name))
+            return;
+        clearTimeout(debounce);
+        debounce = setTimeout(() => void refresh(), 1500);
+    });
+    const slow = setInterval(() => void refresh({ slow: true }), Math.max(10, opts.intervalSec) * 1000);
+    out.on('resize', draw);
+    await new Promise((resolve) => {
+        const finish = () => {
+            clearInterval(slow);
+            clearTimeout(debounce);
+            watcher.close();
+            if (process.stdin.isTTY)
+                process.stdin.setRawMode(false);
+            process.stdin.pause();
+            restore();
+            resolve();
+        };
+        process.once('SIGTERM', finish);
+        process.once('SIGINT', finish);
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(true);
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (key) => {
+            if (graphPrompt !== null) {
+                if (key === '\r' || key === '\n') {
+                    const q = graphPrompt.trim().split(/\s+/);
+                    graphPrompt = null;
+                    if (q[0]) {
+                        overlay = [`bravos graph ${q.join(' ')}`, '', 'asking…'];
+                        void askGraph(root, env, q[0], q.slice(1), 30000).then((a) => {
+                            overlay = [`bravos graph ${q.join(' ')}`, '', ...graphAnswer(a ? (a.error ? 2 : 0) : null, a ? JSON.stringify(a) : '', a ? '' : 'codegraph-mcp not installed')];
+                            draw();
+                        });
+                    }
+                }
+                else if (key === '\u007f')
+                    graphPrompt = graphPrompt.slice(0, -1);
+                else if (key === '\u001b')
+                    graphPrompt = null;
+                else if (!key.startsWith('\u001b'))
+                    graphPrompt += key;
+                draw();
+                return;
+            }
+            if (overlay) {
+                if (key === '\u0003')
+                    return finish();
+                const k = handleKey(key, sn, root);
+                if (k.kind === 'scroll')
+                    overlayScroll = k.by === 'top' ? 0 : k.by === 'end' ? Number.MAX_SAFE_INTEGER : Math.max(0, overlayScroll + k.by);
+                else
+                    overlay = null;
+                draw();
+                return;
+            }
+            const a = handleKey(key, sn, root);
+            if (a.kind === 'quit')
+                return finish();
+            if (a.kind === 'none')
+                return;
+            note = '';
+            if (a.kind === 'scroll')
+                scroll = a.by === 'top' ? 0 : a.by === 'end' ? maxScroll : Math.max(0, Math.min(maxScroll, scroll + a.by));
+            if (a.kind === 'open-report') {
+                const r = sn?.report;
+                const file = r ? (['pdf', 'html'].map((f) => join(r.dir, `report.${f}`)).find((f) => existsSync(f)) ?? null) : null;
+                note = file ? `opening ${file}` : r ? `no html or pdf yet: bravos report export ${r.id} --format html,pdf` : 'no report yet: ask "write the assessment report" (/bravos-report)';
+                if (file)
+                    openTarget(file);
+            }
+            if (a.kind === 'refresh') {
+                note = 'refreshing everything, the code graph too…';
+                void refresh({ slow: true, graph: true });
+            }
+            if (a.kind === 'copy')
+                note = copyToClipboard(a.text) ? `copied: ${a.text}` : `next: ${a.text}`;
+            if (a.kind === 'spawn') {
+                note = a.note;
+                const child = spawn(a.cmd, a.args, { cwd: root, env, detached: !a.open, stdio: 'ignore' });
+                child.on('error', () => {
+                    note = `${a.cmd} not found`;
+                    draw();
+                });
+                if (a.open) {
+                    const file = a.open;
+                    child.on('exit', (code) => {
+                        note = code === 0 ? `dashboard: ${file}` : `${a.cmd} exited ${code}`;
+                        if (code === 0)
+                            openTarget(file);
+                        draw();
+                    });
+                }
+                else
+                    child.unref();
+            }
+            if (a.kind === 'overlay') {
+                overlayScroll = 0;
+                if (a.what === 'graph')
+                    graphPrompt = '';
+                else if (a.what === 'intent')
+                    overlay = intentOverlay(root);
+                else if (a.what === 'report')
+                    overlay = reportOverlay(sn?.report ?? null);
+                else if (a.what === 'services')
+                    overlay = servicesOverlay(sn?.workspace ?? null);
+                else if (a.what === 'next' && sn) {
+                    overlay = ['TEST NEXT (guardlink hypothesis next)', '', ...sn.next.flatMap((q) => [`${q.severity.padEnd(8)} ${q.threat} on ${q.asset}  [${q.state}]`, `         ${q.file}:${q.line ?? '?'}`]), '', 'prove: ask "prove the top 3" (/bravos-prove) · make testable: /bravos-templatize'];
+                    if (sn.stale.length)
+                        overlay.push('', `STALE CLAIMS (${sn.stale.length})`, ...sn.stale.slice(0, 20).map((x) => `  ${x.verb.padEnd(10)} ${x.file}:${x.line ?? '?'}`), '  recheck: /bravos-recheck');
+                }
+                else if (a.what === 'guide') {
+                    const r = spawnSync(process.execPath, [...selfArgs(), 'guide', 'start'], { encoding: 'utf8', timeout: 10000 });
+                    overlay = (r.stdout || 'bravos guide unavailable').split('\n');
+                }
+            }
+            draw();
+        });
+        void refresh({ slow: true, graph: true });
+    });
+}