@bugb-technologies/bravos 0.0.0-stage → 1.0.0

package/dist/help.js

@@ -0,0 +1,334 @@
+// @comment -- "Long-form help text appended to `bravos --help` and each command's --help; pure strings, no logic."
+export const PROGRAM_HELP = `
+What bravos is
+  bravos makes the coding agents you already use (Claude Code, Codex, and Cursor through a
+  pointer) power users of guardlink (threat model as code), cert-x-gen / cxg (authorized
+  pentest as code), the code graph (codegraph-mcp) and licensed SAST (bravos-cli).
+  It installs skills, a session-start briefing, MCP wiring and optional CI into a repository.
+  The agents do the work with the real CLIs. bravos has no orchestrator and keeps no state:
+  .bravos/ holds only its hooks and a lock file.
+
+Commands
+  init [dir]     First install in a repository. Runs guardlink init if .guardlink/ is absent.
+  sync [dir]     Re-apply bravos to a repository that already has it (after upgrading bravos,
+                 or to add --ci / --pre-pr-hook / --scope / --autopilot later). Never runs
+                 guardlink init. init and sync take --global for a user-level install.
+  doctor [dir]   Read-only check of tools, licence, installed skills and hooks.
+  uninstall [dir]
+                 Remove bravos from a repository (--global: from your user), keeping
+                 anything you edited unless --force; --dry-run lists it first.
+  review <kind>  Answer bravos's questions in a branded page (kind 'intent' from bravos-context),
+                 pre-filled with bravos's suggestions: change what is wrong, make the calls marked
+                 'needs your call', Confirm. Answers save to .guardlink/<kind>-answers/<name>.json;
+                 --summary for the agent, --share for a claude.ai link (Claude Code).
+  next [dir]     The setup score: what is switched on, what each step unlocks, the exact
+                 command for the next one (also in the banner and the agent's briefing).
+  watch [dir]    A live view for a second terminal pane beside any agent: setup, open and
+                 confirmed exposures, the hypothesis ledger, what to test next, stale claims, the
+                 code graph's resolution and entry points, SAST, the branch, PRs and autopilot
+                 nudges, redrawn as files change. Read-only, no model. --once prints one frame,
+                 --json one snapshot (bravos.watch/v1).
+  workspace <create|add|remove|target|show|sync>
+                 One app made of several repos: create NAME --member PATH[=service[@url]]...
+                 makes a bravos workspace, links the members with guardlink link-project,
+                 installs bravos in each member and in the app folder they share, and keeps a
+                 snapshot the briefing, watch (SERVICES panel, key s) and reports read. Calls
+                 between services are written @flows #<this>-<x> -> #<other>-<y> via http.
+  report <data|check|export|list>
+                 Evidence-bound write-ups for bravos-report: data gathers the facts into
+                 .bravos/reports/<id>/evidence.json (not committed), check gates report.md,
+                 export renders md, txt, html and pdf (pdf through an installed Chrome, Edge,
+                 Brave or Chromium). No model.
+  sast <run|status|candidates>
+                 run analyzes the repository with the staged bravos-cli into .bravos/sast/<run>/
+                 (Team plan; not committed); status is one line about the newest run; candidates
+                 lists its reachable findings joined to a claim, not yet in the threat model,
+                 dependencies and secrets. No model.
+  setup          Put the binaries bravos drives on this machine: the analyzer (SAST) and the
+                 code graph are signed bundles fetched through the account portal (Team plan),
+                 verified and staged under $BRAVOS_HOME; --tools adds guardlink and cxg (-y).
+                 --check reports, --dry-run says what would happen.
+  graph          The code graph (Team plan): graph build [DIR] [--scip MODE] indexes a repo;
+                 graph <question> [args] --json asks it (the codegraph_ tools' answers);
+                 graph --json lists every question this machine's binary answers.
+  licence        Which plan this machine is on, where the licence is, what it unlocks
+                 (--json: bravos.licence/v1). 'license' works too.
+  account <activate|import FILE|status>
+                 activate: sign in once in the browser and get this machine its licence — a
+                 30-day Team trial when the account has no plan, no card. import: install a
+                 licence downloaded from account.bugb.io/dashboard/license.
+  guide [topic]  How to use bravos: by role, by task, every skill, the safety rules.
+                 Topics: start, roles, tasks, skills, states, safety, harnesses, all.
+  Run 'bravos <command> --help' for every flag and what it writes.
+
+Plans
+  Free (researcher): the research loop in one repository — context, annotate, templatize,
+  env, prove, recheck, report, watch — with no licence at all.
+  Team (per developer; Solo is one seat): the pre-PR gate and autopilot, the CI and nightly
+  workflows, scheduled upkeep, multi-repository workspaces, campaigns, SAST and the code graph.
+  A paid command or flag without a licence says what it would do and how to start the trial;
+  a paid hook stands down with one line and never blocks. The licence is an offline-verified
+  token: BRAVOS_LICENCE, or licence.jwt in $BRAVOS_HOME (default ~/.bravos). Grace after
+  expiry is min(14 days, a quarter of the term). Seats are counted in the account portal.
+
+The skills it installs (one folder each in .claude/skills/ and .agents/skills/)
+  bravos              Start here: reads the briefing, explains the loop, routes to the rest.
+  bravos-annotate     Extends the threat model in a budgeted slice (5 files) or deep rounds,
+                      skipping files teammates have in open PRs; lint gate until 0 errors.
+  bravos-codegraph    Answers reachability, attack-surface and blast-radius questions.
+  bravos-ship         The pre-PR security gate; opens a PR only when you ask for one.
+  bravos-templatize   Turns open exposures into validated cxg templates and retest kits.
+  bravos-env          Brings up a target you own: loopback by default, reviewed scope.yaml,
+                      your typed authorization, test accounts created on loopback only.
+  bravos-prove        Runs the authorized test, reads cxg's verdicts, writes outcomes back
+                      only through guardlink's hypothesis ledger.
+  bravos-recheck      After a fix: re-verifies stale claims, replays retest kits.
+  bravos-sast         Licensed static analysis; says plainly when it is unavailable.
+  bravos-schedule     /loop while you work, the nightly workflow, or a cloud task you create.
+  bravos-cicd         Writes and audits the security GitHub Actions workflows.
+  bravos-context      Learns what the product intends: drafts answers from the code, asks you
+                      a short interview, writes .guardlink/intent.md with invariants (INV-n)
+                      and intended-by-design behaviour (INT-n) that every annotation is judged by.
+  bravos-campaign     Reaches a goal in rounds ("coverage 100%", "test every exposure"):
+                      disjoint batches, one subagent each, gate per batch, rest, repeat, stop.
+  bravos-report       Writes the assessment, one finding, a retest or an executive brief from
+                      bravos report data's evidence; every proof claim cites its evidence and its
+                      level (reproduced / held / code review / suspected) is computed, not
+                      asserted; bravos report check gates it; export to md, txt, html, pdf.
+
+Intent-aware annotation
+  Threats are judged against .guardlink/intent.md, not only against code patterns. Business
+  invariants ("a user never reads another tenant's data") become threats beside the code that
+  should enforce them; each exposure is rated by impact x reach x ease with the reason written
+  down; something that looks dangerous but is intended gets an "intended?" audit for you to
+  answer, never an automatic acceptance. The briefing's Intent line says whether intent is
+  recorded, still draft, or missing.
+
+Session start
+  One hook run returns two things. The briefing (counts, FIX NOW, what to test next, stale
+  claims, tickets, intent) goes to the model on every start, resume, clear and compact. On a
+  fresh start only, a banner goes to you and not to the model: the bravos logo, repo and
+  branch, counts, the top threats (or FIX NOW) beside a quick start chosen from the repo's
+  state, and a short introduction while .guardlink/intent.md is missing. Claude Code shows
+  it above the first prompt; Codex shows it as a hook message. BRAVOS_BANNER=off hides it;
+  the briefing still reaches the model. The banner uses bravos's brand colours (truecolor);
+  NO_COLOR or BRAVOS_BANNER_COLOR=off prints it plain. Codex lists a hook message as a
+  warning, so there it is a two-line summary instead of the art. Since 0.5.0 the hook is registered with
+  --harness claude or --harness codex so the banner prints /skill or $skill; sync migrates
+  the older entry, and Codex asks you to trust the changed hook once (/hooks).
+  omp runs no hooks, so when omp is in use (.omp/ exists or omp is on PATH) bravos writes
+  .omp/extensions/bravos.js: it shows the banner above the editor and hands the briefing to
+  the model with your first prompt. No command is needed in any of the three; /bravos is
+  for "what next". A harness with neither hooks nor extensions gets the briefing when the
+  bravos skill runs 'node .bravos/hooks/session-start.mjs --briefing'.
+  Antigravity (agy) reads .agents/hooks.json: bravos adds a 'bravos' SessionStart group
+  there that hands the briefing to the model (it documents no way to show a banner).
+
+Autopilot (hands-off): bravos init --autopilot
+  For teams who would rather not ask. At the end of every turn a check (a Stop hook in
+  Claude Code and Codex, a few seconds) sends the agent back once when the turn's changes
+  leave a file with no GuardLink annotation, code under a confirmed or stale claim, or open
+  exposures on changed files, naming the skill to use; the pre-PR gate runs on every
+  gh pr create / gh pr ready. Each finding is raised once per session; a missing tool or a
+  timeout lets the turn finish; BRAVOS_AUTOPILOT=off pauses it.
+  Proving is the team's choice, not a rule: the first time it comes up the agent asks once
+  (prove automatically on your loopback target, ask each time, on a schedule, or not now;
+  model-API probes or not) and records your words in .guardlink/proving.md. The briefing
+  shows it; say "ask me first" to change it. Non-loopback targets still need a reviewed
+  scope and typed authorization every time.
+
+Harnesses
+  Claude Code, Codex, Antigravity (agy), opencode and omp; --agent all installs for every
+  one. bravos init --global installs for your user (skills in ~/.claude/skills, a user hook
+  that briefs repos with a threat model but no bravos). bravos sync --link-skills keeps one
+  copy of each skill when a tool reads both .claude/skills and .agents/skills (Warp).
+  bravos uninstall [--global] removes it again.
+
+Effort: low | medium | high | max
+  One dial every skill reads: from your words ("annotate at high"), else a line
+  'bravos effort: <level>' in AGENTS.md or CLAUDE.md, else medium (campaign: high).
+    annotate     changed files | +5 from the worklist | 25 per round + chains | until done
+    templatize   changed exposures | top 5 | top 20 | every open exposure
+    prove        replay kits | +generation, 8 templates | 32 + chaining | every class, spend pre-approved
+    recheck      stale claims | +confirmed on changed files | every confirmed | everything + gaps
+    ship         deterministic gates | +code-graph gaps | +SAST | +recheck
+  These are starting budgets, not limits: the agent goes beyond one when the work needs it and
+  says why. bravos adds method and memory to the model; it never caps it. Only the safety rules
+  below are hard.
+
+Campaign examples
+  Claude Code:  /bravos-campaign coverage 100% at max, rest 10m
+  Codex:        $bravos-campaign test every open exposure on loopback
+  Claude Code rests between rounds with its own wakeup or /loop; Codex has no in-session timer,
+  so rounds run back to back there, or the nightly workflow carries them.
+
+The evidence loop
+  claim (guardlink annotation) -> testable template (cxg) -> authorized run -> verified
+  outcome (hypothesis ledger) -> recheck after every change. Three independent states per
+  claim: open / mitigated / accepted; untested / confirmed / refuted; verified / stale.
+
+Rules every skill follows
+  Never spawns a second coding agent (no guardlink annotate/translate agent flags; cxg probe
+  generation only through its API providers). Never writes @accepts, @entitles or @confirmed
+  by hand. Never sends a request to a non-loopback host without a committed, reviewed
+  scope.yaml and the human's typed authorization. Destructive probe classes only on a
+  disposable loopback target. Never invents credentials. Never calls anything clean unless
+  a gate exited 0.
+
+Typical first run
+  bravos doctor                      # what is installed, what is missing
+  bravos init --dry-run              # preview every write
+  bravos init                        # install; then open a Claude Code or Codex session
+  bravos sync --ci --pre-pr-hook     # later: add CI and the pre-PR gate
+  In Codex, run /hooks once to trust .codex/hooks.json.
+
+Exit codes
+  0 success (files skipped to protect your edits are not failures)
+  1 refused (an unparsable config file; nothing in that file was written)
+  2 usage error
+`;
+const SHARED_WRITES = `
+What it writes (repository-relative)
+  .claude/skills/bravos*/            Claude Code skills (when Claude Code is a harness)
+  .agents/skills/bravos*/            Codex and shared-agent skills (when codex is a harness)
+  .agents/skills/guardlink-*/        guardlink's playbook skills mirrored for Codex, if
+                                     guardlink wrote them under .claude/skills/
+  .bravos/hooks/                     session-start briefing (and pre-PR gate) scripts
+  .bravos/skills.lock                sha256 of every file bravos wrote
+  .claude/settings.json              SessionStart hook, --harness claude (+ PreToolUse gate
+                                     with --pre-pr-hook)
+  .codex/hooks.json                  the same for Codex, --harness codex
+  .mcp.json, .codex/config.toml      MCP servers: guardlink always; cxg when on PATH; codegraph-mcp
+                                     when on PATH or inside the bravos install (by full path, with
+                                     the launcher's graph store as BRAVOS_CODEGRAPH_DIR; sync
+                                     refreshes that entry when bravos is replaced)
+  .cursor/rules/bravos.mdc           pointer to the skills, only if .cursor/ exists
+  .omp/extensions/bravos.js          omp session start, only if .omp/ exists or omp is on PATH
+  Every merge keeps entries bravos did not write. A file it cannot parse is refused with
+  its path, and nothing is written to it.
+
+Your edits are safe
+  A bravos file you edited (hash differs from the lock) or a file bravos did not write is
+  skipped and reported, with a 'git diff --no-index' hint. --force overwrites it.
+  If .agents/skills is a link to .claude/skills, skills are written once.
+  A written path your .gitignore ignores is reported, since it will not reach teammates.
+
+Agents
+  Detected from the repository: CLAUDE.md or .claude/ means Claude Code; AGENTS.md,
+  GEMINI.md, .agents/ or .codex/ means Codex. No evidence means both. --agent overrides.
+`;
+const FLAG_DETAIL = `
+Flags in depth
+  --agent claude,codex,agy,opencode,omp   (or --agent all)
+      Install for these harnesses only, instead of detecting them. 'all' installs for
+      every one: Claude Code, Codex and Antigravity (both skill roots), opencode and omp. claude and codex
+      pick the skill roots (agy shares codex's .agents/ root). opencode and omp add
+      their own files on top (.opencode/ and opencode.json; .omp/extensions/), which
+      are otherwise written only when that tool is detected; once written, sync keeps
+      them up to date without the flag.
+  --autopilot
+      Upkeep without being asked. Registers an end-of-turn check (a Stop hook, Claude Code
+      and Codex) that sends the agent back once when the turn's changes leave code with no
+      GuardLink annotation, a confirmed or stale claim on a changed file, or open exposures
+      on changed files; and the pre-PR gate (implies --pre-pr-hook), which also lints. New
+      exposures are handled as you choose: the first time proving comes up the agent asks
+      you once (prove automatically on your loopback target, ask each time, on a schedule,
+      or not now; and whether cxg may generate probes through a model API) and records your
+      words in .guardlink/proving.md, which a PR that changes it must mention. It uses only
+      guardlink's fast calls (a few seconds); a missing tool or timeout lets the turn finish.
+      BRAVOS_AUTOPILOT=off pauses the check.
+  --link-skills
+      Make .agents/skills a link to .claude/skills, so each skill exists once. Tools that
+      read both folders (Warp, for one) otherwise list every skill twice. bravos removes
+      only its own unchanged copies; anything else in .agents/skills stops it, and nothing
+      is removed. Symlinks need core.symlinks on Windows checkouts.
+  --global
+      Install for your user instead of a repository: skills once in ~/.claude/skills
+      (absolute paths), a link per skill from ~/.agents/skills, the hook in ~/.bravos/hooks
+      registered in ~/.claude/settings.json and ~/.codex/hooks.json, guardlink MCP in
+      ~/.codex/config.toml. The user hook stays silent in a repo that has its own bravos
+      hook or no .guardlink/, so it briefs only repos with a threat model and no bravos.
+      Personal skills are not in git: bravos init in a repo is still how a team shares it.
+      Claude Code prefers personal skills over a repo's, so once a user-level install
+      exists, bravos sync in any repo also brings it to the same version (it never creates
+      one). BRAVOS_SYNC_GLOBAL=off keeps them separate and only warns.
+  --force
+      Overwrite bravos files you edited, and same-named files bravos did not write.
+  --dry-run
+      Print every line of the summary without writing anything.
+  --ci
+      Copies three GitHub Actions workflows into .github/workflows/:
+        bravos-pr-gate.yml          On every PR (opened, synchronize, reopened, edited):
+                                    guardlink validate, lint since the merge base, new
+                                    unmitigated exposure must be named in the PR body,
+                                    confirmed exploits on changed files block unless a
+                                    @ticket covers them, SARIF uploaded to code scanning.
+                                    A gate input that fails reads as unknown and blocks.
+        bravos-nightly-claude.yml   Weekdays 03:17 UTC: Claude Code annotates the next slice
+        bravos-nightly-codex.yml    (or Codex does), the lint gate checks it, one PR opens.
+                                    Keep the one for your harness and delete the other.
+                                    Opt-in scan step: replays retest kits only when
+                                    .guardlink/scope.yaml has a human-written
+                                    authorization_attestation and vars.BRAVOS_SCAN_TARGET is
+                                    loopback (started by vars.BRAVOS_APP_START) or in the
+                                    scope's host_allowlist; optional vars.BRAVOS_SCAN_AUTH +
+                                    secrets.BRAVOS_AUTH_STATE import a login. Otherwise it
+                                    skips with a notice.
+      Needs repository secret ANTHROPIC_API_KEY or OPENAI_API_KEY, and Settings > Actions >
+      "Allow GitHub Actions to create and approve pull requests". Workflows you wrote or
+      edited are skipped unless --force.
+  --pre-pr-hook
+      Registers the pre-PR gate as a PreToolUse hook on Bash for 'gh pr create' and
+      'gh pr ready' in .claude/settings.json and .codex/hooks.json, and lists
+      'node .bravos/hooks/pre-pr.mjs --check' in .guardlink/config.json pre_pr so guardlink's
+      agent block tells every agent to run it. Exit 2 blocks the PR on lint errors, undisclosed
+      new exposure, or an unticketed confirmed claim on a changed file. It allows (with a note)
+      only when guardlink is not installed or there is no merge base. BRAVOS_PRE_PR=off
+      disables it for one shell.
+  --scope
+      Copies the loopback-only cxg scope starter to .guardlink/scope.yaml if none exists:
+      GET/HEAD/OPTIONS/POST only, empty host_allowlist, cxg's nine destructive-path patterns,
+      and an empty authorization_attestation for you to write and get reviewed in a PR.
+`;
+export const INIT_HELP = `
+What init does, in order
+  1. Detects the harnesses (see Agents below).
+  2. Runs 'guardlink init --agent <ids> --mode <inline|external>' if .guardlink/ is absent
+     (skipped with --no-guardlink-init; reported if guardlink is not installed).
+  3. Installs the skills, the hooks and the MCP wiring.
+  4. With --ci / --pre-pr-hook / --scope, adds those too.
+  5. Prints a summary, gitignore warnings, and the next step.
+${SHARED_WRITES}${FLAG_DETAIL}
+  --guardlink-mode inline|external
+      Where guardlink keeps annotations: in source comments (default) or .gal sidecars.
+  --no-guardlink-init
+      Do not run guardlink init even if .guardlink/ is absent.
+
+Examples
+  bravos init --dry-run
+  bravos init --agent claude
+  bravos init --ci --pre-pr-hook --scope
+`;
+export const SYNC_HELP = `
+What sync does
+  Re-applies the installed bravos version: refreshes skills, hooks, MCP wiring and the
+  Cursor pointer, and (with the flags) workflows, the pre-PR gate and the scope starter.
+  It never runs guardlink init. Run it after upgrading bravos, or to add a flag later.
+${SHARED_WRITES}${FLAG_DETAIL}
+Examples
+  bravos sync
+  bravos sync --ci                   # add the PR gate and nightly workflows
+  bravos sync --agent codex --dry-run
+`;
+export const DOCTOR_HELP = `
+What doctor reports (read-only; writes nothing, starts nothing)
+  Tools on PATH, with an install hint for each one missing:
+    guardlink       npm install -g guardlink
+    cxg             cargo install cert-x-gen  (or brew tap bugb-technologies/cxg && brew install cxg)
+    codegraph-mcp   bravos setup --codegraph  (Team plan)
+    bravos-cli      bravos setup --analyzer   (Team plan); the licence is BRAVOS_LICENCE or
+                    licence.jwt in $BRAVOS_HOME, ~/.bravos or ~/.bugb
+  The plan line (Free, Team trial, Team, expired or in grace), whether guardlink initialised the repo, bravos skills installed
+  per harness, guardlink playbook skills per harness, session-start hooks per harness,
+  and whether the pre-PR gate is registered.
+`;

package/dist/hooks.js

@@ -0,0 +1,167 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, copyFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { hooksDir as packageHooksDir } from './paths.js';
+import { OLD_HOOK_COMMANDS, OLD_NAME, oldGlobalHookCommand } from './migrate.js';
+import { BravosError } from './types.js';
+// @comment -- "The SessionStart command before 0.5.0; init and sync replace it with the per-harness form, and doctor still accepts it."
+export const LEGACY_HOOK_COMMAND = 'node .bravos/hooks/session-start.mjs';
+// @comment -- "The SessionStart command bravos registers per harness; --harness tells the banner which skill syntax to print. doctor matches on the same constants."
+export const HOOK_COMMANDS = {
+    claude: `${LEGACY_HOOK_COMMAND} --harness claude`,
+    agents: `${LEGACY_HOOK_COMMAND} --harness codex`,
+};
+// @comment -- "The command bravos registers as its opt-in PreToolUse pre-PR gate; doctor matches on the same constant."
+export const PRE_PR_COMMAND = 'node .bravos/hooks/pre-pr.mjs';
+// @comment -- "The SessionStart registration bravos writes into .claude/settings.json and .codex/hooks.json, per harness; the Codex plugin build reuses its shape."
+// @comment -- "The user-level SessionStart command (bravos init --global): an absolute path into ~/.bravos/hooks, and --global so the hook stays silent in repos that have their own bravos hook or no threat model."
+export const globalHookCommand = (home, harness) => `node "${home}/.bravos/hooks/session-start.mjs" --harness ${harness === 'claude' ? 'claude' : 'codex'} --global`;
+export function sessionStart(harness, home) {
+    const command = home ? globalHookCommand(home, harness) : HOOK_COMMANDS[harness];
+    return {
+        event: 'SessionStart',
+        command,
+        // The pre-0.5.0 form, and every form the old name (joseph) registered, repo-level and user-level.
+        replaces: [
+            LEGACY_HOOK_COMMAND,
+            OLD_HOOK_COMMANDS.sessionStart,
+            ...['claude', 'codex', 'agy'].map((h) => `${OLD_HOOK_COMMANDS.sessionStart} --harness ${h}`),
+            ...(home ? ['claude', 'codex'].map((h) => oldGlobalHookCommand(home, h)) : []),
+        ],
+        group: { matcher: 'startup|resume|clear|compact', hooks: [{ type: 'command', command, timeout: 30 }] },
+    };
+}
+// @comment -- "The command bravos registers as its opt-in autopilot Stop hook (Claude Code and Codex); doctor and uninstall match on it."
+export const AUTOPILOT_COMMAND = 'node .bravos/hooks/autopilot.mjs';
+const AUTOPILOT = {
+    event: 'Stop',
+    command: AUTOPILOT_COMMAND,
+    replaces: [OLD_HOOK_COMMANDS.autopilot],
+    group: { hooks: [{ type: 'command', command: AUTOPILOT_COMMAND, timeout: 30 }] },
+};
+// The hook script itself only acts on commands that run gh pr create or gh pr ready.
+const PRE_PR = {
+    event: 'PreToolUse',
+    command: PRE_PR_COMMAND,
+    replaces: [OLD_HOOK_COMMANDS.prePr],
+    group: { matcher: 'Bash', hooks: [{ type: 'command', command: PRE_PR_COMMAND, timeout: 180 }] },
+};
+const SETTINGS_FILE = {
+    claude: '.claude/settings.json',
+    agents: '.codex/hooks.json',
+};
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+function listFiles(dir) {
+    const out = [];
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const abs = join(dir, e.name);
+        if (e.isDirectory())
+            out.push(...listFiles(abs));
+        else if (e.isFile())
+            out.push(abs);
+    }
+    return out;
+}
+// @comment -- "Reads and validates one harness settings file and decides which of bravos's hook groups must be appended and which superseded bravos commands removed; writes nothing so every file can be validated before any write."
+function planRegistration(root, rel, regs) {
+    const abs = join(root, rel);
+    let doc = {};
+    if (existsSync(abs)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(abs, 'utf8'));
+        }
+        catch {
+            throw new BravosError(`${rel} is not valid JSON; fix it or remove it, nothing was written`);
+        }
+        if (!isObject(parsed)) {
+            throw new BravosError(`${rel} is not a JSON object; fix it or remove it, nothing was written`);
+        }
+        doc = parsed;
+    }
+    if (doc.hooks !== undefined && !isObject(doc.hooks)) {
+        throw new BravosError(`${rel} has a hooks value that is not an object; fix it or remove it, nothing was written`);
+    }
+    const hooks = (doc.hooks ?? {});
+    let changed = false;
+    for (const reg of regs) {
+        if (hooks[reg.event] !== undefined && !Array.isArray(hooks[reg.event])) {
+            throw new BravosError(`${rel} has a hooks.${reg.event} value that is not an array; fix it or remove it, nothing was written`);
+        }
+        let groups = (hooks[reg.event] ?? []);
+        const old = new Set(reg.replaces ?? []);
+        if (old.size > 0) {
+            // Drop superseded bravos commands from every group, and groups left empty by that.
+            const before = JSON.stringify(groups);
+            groups = groups
+                .map((g) => (isObject(g) && Array.isArray(g.hooks) ? { ...g, hooks: g.hooks.filter((h) => !(isObject(h) && typeof h.command === 'string' && old.has(h.command))) } : g))
+                .filter((g) => !(isObject(g) && Array.isArray(g.hooks) && g.hooks.length === 0));
+            if (JSON.stringify(groups) !== before) {
+                hooks[reg.event] = groups;
+                changed = true;
+            }
+        }
+        const present = groups.some((g) => isObject(g) && Array.isArray(g.hooks) && g.hooks.some((h) => isObject(h) && h.command === reg.command));
+        if (present)
+            continue;
+        hooks[reg.event] = [...groups, reg.group];
+        changed = true;
+    }
+    if (changed)
+        doc.hooks = hooks;
+    return { file: rel, changed, doc };
+}
+// @comment -- "The command Antigravity runs from .agents/hooks.json; --harness agy makes the hook print Antigravity's injectSteps."
+export const AGY_HOOK_COMMAND = `${LEGACY_HOOK_COMMAND} --harness agy`;
+export const AGY_HOOKS_FILE = '.agents/hooks.json';
+const AGY_GROUP = { SessionStart: [{ type: 'command', command: AGY_HOOK_COMMAND, timeout: 30 }] };
+// @comment -- "Plans bravos's entry in Antigravity's workspace hooks file, whose top-level keys are named hook groups; only the 'bravos' key is bravos's, every other key is kept, and a malformed file is refused before anything is written."
+function planAgy(root) {
+    const abs = join(root, AGY_HOOKS_FILE);
+    let doc = {};
+    if (existsSync(abs)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(abs, 'utf8'));
+        }
+        catch {
+            throw new BravosError(`${AGY_HOOKS_FILE} is not valid JSON; fix it or remove it, nothing was written`);
+        }
+        if (!isObject(parsed))
+            throw new BravosError(`${AGY_HOOKS_FILE} is not a JSON object; fix it or remove it, nothing was written`);
+        doc = parsed;
+    }
+    const hadOld = OLD_NAME in doc;
+    if (!hadOld && JSON.stringify(doc.bravos) === JSON.stringify(AGY_GROUP))
+        return { file: AGY_HOOKS_FILE, changed: false, doc };
+    const { [OLD_NAME]: _old, ...rest } = doc;
+    return { file: AGY_HOOKS_FILE, changed: true, doc: { ...rest, bravos: AGY_GROUP } };
+}
+// @comment -- "Copies the hook scripts into <root>/.bravos/hooks and registers the SessionStart briefing, plus the PreToolUse pre-PR gate when prePr is set, for Claude Code (.claude/settings.json), Codex (.codex/hooks.json) and Antigravity (.agents/hooks.json); settings files are validated before anything is written and existing keys and groups are preserved."
+export function installHook(root, harnesses, opts = {}) {
+    const src = opts.hooksDir ?? packageHooksDir();
+    const files = listFiles(src).map((abs) => relative(src, abs).split('\\').join('/')).sort();
+    const copied = files.map((f) => `.bravos/hooks/${f}`);
+    const plans = [...new Set(harnesses)].map((h) => planRegistration(root, SETTINGS_FILE[h], [
+        sessionStart(h, opts.globalHome),
+        ...((opts.prePr || opts.autopilot) && !opts.globalHome ? [PRE_PR] : []),
+        ...(opts.autopilot && !opts.globalHome ? [AUTOPILOT] : []),
+    ]));
+    // Antigravity reads .agents/skills and .agents/hooks.json, so it rides on the shared-agents harness (per repo only).
+    if (harnesses.includes('agents') && !opts.globalHome)
+        plans.push(planAgy(root));
+    if (!opts.dryRun) {
+        for (const f of files) {
+            const dest = join(root, '.bravos/hooks', f);
+            mkdirSync(dirname(dest), { recursive: true });
+            copyFileSync(join(src, f), dest);
+        }
+        for (const p of plans) {
+            if (!p.changed)
+                continue;
+            const abs = join(root, p.file);
+            mkdirSync(dirname(abs), { recursive: true });
+            writeFileSync(abs, JSON.stringify(p.doc, null, 2) + '\n');
+        }
+    }
+    return { copied, registered: plans.map((p) => ({ file: p.file, changed: p.changed })) };
+}