failproofai 0.0.12 → 0.0.13-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "0.0.12",
+  "version": "0.0.13-beta.1",
   "description": "The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously — for Claude Code & the Agents SDK",
   "bin": {
     "failproofai": "./dist/cli.mjs"
@@ -22,7 +22,7 @@
   "scripts": {
     "predev": "bun run build:cli && bun link",
     "dev": "FAILPROOFAI_TELEMETRY_DISABLED=1 bun scripts/dev.ts --port 8020",
-    "build:cli": "bun build --target=node --format=esm --outfile=dist/cli.mjs bin/failproofai.mjs --external posthog-node && node -e \"const fs=require('fs');const c=fs.readFileSync('dist/cli.mjs','utf8');fs.writeFileSync('dist/cli.mjs',c.replace('#!/usr/bin/env bun','#!/usr/bin/env node').replace('// @bun\\n',''))\"",
+    "build:cli": "bun build --target=node --format=esm --outfile=dist/cli.mjs bin/failproofai.mjs --external posthog-node --external sql.js && node -e \"const fs=require('fs');const c=fs.readFileSync('dist/cli.mjs','utf8');fs.writeFileSync('dist/cli.mjs',c.replace('#!/usr/bin/env bun','#!/usr/bin/env node').replace('// @bun\\n',''))\"",
     "build": "bun build --target=node --format=cjs --outfile=dist/index.js src/index.ts && bun run build:cli && bun --bun next build && node -e \"const {cpSync}=require('fs');cpSync('.next/static','.next/standalone/.next/static',{recursive:true});\" && node scripts/prune-standalone.mjs",
     "prestart": "bun run build:cli && bun link",
     "start": "FAILPROOFAI_TELEMETRY_DISABLED=1 bun scripts/start.ts",
@@ -99,7 +99,9 @@
   "dependencies": {
     "html-to-image": "^1.11.13",
     "html2canvas": "^1.4.1",
-    "posthog-node": "^5.37.1"
+    "posthog-node": "^5.37.1",
+    "sql.js": "^1.14.1",
+    "yaml": "^2.9.0"
   },
   "overrides": {
     "postcss": "8.5.14",

package/scripts/sync-agent-cli-harnesses-prompt.md

@@ -0,0 +1,222 @@
+ultracode
+
+You are an automated **ultracode** (multi-agent) run inside a fresh clone of the
+failproofai repository. Your job is to keep failproofai in sync with the upstream
+documentation for **every** agent CLI we integrate with, then open exactly one
+pull request with the fix — or, if a sync PR is already open, comment on it instead.
+
+## Run contract (read first)
+
+- You are running **headless and autonomously**. No human is watching; nobody can
+  answer a question mid-run. For reversible actions that follow from this task,
+  proceed without asking. Do **not** end your turn with a plan or a question —
+  finish the work.
+- The entrypoint has **already cut a fresh branch** named `auto/sync-cli-harnesses-<UTC>`.
+  Do all your work here; do **not** switch branches or work on `main`.
+- failproofai's own Stop hooks are active in this checkout. If you make commits, you
+  will not be allowed to stop until you have **committed**, **pushed**, and **opened a
+  PR** for them. If you make **no** commits (nothing to sync, or you only commented on
+  an already-open sync PR), a clean working tree stops fine — so on those paths, do
+  **not** edit any files.
+- Use ultracode / multi-agent orchestration: in Phase 1, fan out **one subagent per
+  CLI** so the seven harnesses are checked in parallel.
+
+failproofai integrates with **seven** agent CLIs. Each has its own hook surface,
+tracked in `src/hooks/types.ts` and written to disk by `src/hooks/integrations.ts`:
+
+| CLI            | Event array (`src/hooks/types.ts`) | Event map | Settings file written (`src/hooks/integrations.ts`) |
+|----------------|------------------------------------|-----------|------------------------------------------------------|
+| Claude Code    | `HOOK_EVENT_TYPES` (canonical)     | — (canonical)          | `.claude/settings.json` |
+| OpenAI Codex   | `CODEX_HOOK_EVENT_TYPES`           | `CODEX_EVENT_MAP`      | `.codex/hooks.json` |
+| GitHub Copilot | `COPILOT_HOOK_EVENT_TYPES`         | — (already Pascal)     | `.github/hooks/failproofai.json` |
+| Cursor Agent   | `CURSOR_HOOK_EVENT_TYPES`          | `CURSOR_EVENT_MAP`     | `.cursor/hooks.json` |
+| OpenCode       | `OPENCODE_HOOK_EVENT_TYPES`        | `OPENCODE_EVENT_MAP`   | `.opencode/opencode.json` + `.opencode/plugins/failproofai.mjs` |
+| Pi             | `PI_HOOK_EVENT_TYPES`              | `PI_EVENT_MAP`         | `.pi/settings.json` |
+| Gemini CLI     | `GEMINI_HOOK_EVENT_TYPES`          | `GEMINI_EVENT_MAP`     | `.gemini/settings.json` |
+
+## What "drift" means — three scopes
+
+For each verified CLI, compare the upstream docs to this repo across three scopes:
+
+1. **Scope 1 — hook event names.** Events documented upstream but missing from (or
+   removed from) the CLI's `*HOOK_EVENT_TYPES` array in `src/hooks/types.ts`.
+2. **Scope 2 — tool / payload schema.** Changes to the CLI's tool names or payload
+   field shapes, tracked in the `*_TOOL_MAP` / `*_TOOL_INPUT_MAP` tables in
+   `src/hooks/types.ts` and in the per-CLI response-shape branches of
+   `src/hooks/policy-evaluator.ts`.
+3. **Scope 3 — settings-file shape.** Changes to the structure of the config file
+   failproofai writes for the CLI: the hard-coded literals in
+   `src/hooks/integrations.ts` (matcher-wrapper vs flat-array vs packages-array vs
+   plugin registration; field names like `command` vs `bash`/`powershell`;
+   `timeout` vs `timeoutSec` and its **unit** seconds-vs-ms; presence of `version`
+   / `$schema` / `matcher`; the settings-file path) **and** the committed dogfood
+   fixture on disk. The canonical worked example is git history / PR #482, which
+   dropped an invalid top-level `version` field and fixed a `60000`ms→`60`s timeout
+   unit in `.codex/hooks.json` by editing the writer, the fixture, and the tests
+   together.
+
+## Reading rules
+
+- This run relaxed two policies (`require-ci-green-before-stop`,
+  `block-read-outside-cwd`) so you can read and edit the settings fixtures. Even so,
+  when you only need to **inspect** a committed fixture, prefer
+  `git show HEAD:<path>` (e.g. `git show HEAD:.codex/hooks.json`) — it is never
+  blocked and is the reliable way to read `.claude/settings.json`, `.codex/hooks.json`,
+  `.cursor/hooks.json`, `.github/hooks/failproofai.json`, `.gemini/settings.json`,
+  `.pi/settings.json`, and `.opencode/*`.
+- Do **NOT** run `failproofai policies --install` (or any `failproofai` subcommand)
+  to regenerate a fixture — it is blocked. Edit fixtures by hand.
+
+## Phase 1 — Fan out one subagent per CLI
+
+Spawn one subagent per CLI (seven, in parallel). Each subagent, for its CLI:
+
+1. `WebFetch` the docs URL(s) below and extract the authoritative lists: the hook
+   **event names**, the **tool names / payload field names**, and the
+   **settings-file schema** (top-level keys, per-entry shape, command field name,
+   timeout field name **and unit**, and whether `matcher` / `version` / `$schema`
+   are present). **Use upstream casing exactly** — Codex snake_case, Cursor
+   camelCase, OpenCode dot.namespaced, Pi snake_case, Claude/Copilot/Gemini
+   PascalCase. Do **not** normalize.
+2. Compare against this repo: the CLI's `*HOOK_EVENT_TYPES` array + paired
+   `*EVENT_MAP` (scope 1); its `*_TOOL_MAP` / `*_TOOL_INPUT_MAP` and its branch in
+   `src/hooks/policy-evaluator.ts` (scope 2); its literals in
+   `src/hooks/integrations.ts` + its dogfood fixture read via `git show` (scope 3).
+3. Return a structured report: `{ cli, status: up-to-date | drift | unverified,
+   scope1: {added, removed}, scope2: {...}, scope3: {...}, sources: [...] }`.
+
+If a docs URL 404s, redirects to a stub, or has no parseable list, mark that CLI
+`unverified` and skip its diff. **Do not invent events, tools, or fields. Do not
+guess from prior knowledge.** Pi is the most likely `unverified` candidate (its
+surface is documented in the package source, not a clean enumeration).
+
+| CLI       | Docs URL(s) |
+|-----------|-------------|
+| Claude    | https://code.claude.com/docs/en/hooks (reference) · https://code.claude.com/docs/en/hooks-guide (summary) |
+| Codex     | https://developers.openai.com/codex/hooks |
+| Copilot   | https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-hooks · https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-hooks-reference (tool names) |
+| Cursor    | https://cursor.com/docs/hooks |
+| OpenCode  | https://opencode.ai/docs/plugins/ |
+| Pi        | https://www.npmjs.com/package/@mariozechner/pi-coding-agent |
+| Gemini    | https://geminicli.com/docs/hooks/ · https://geminicli.com/docs/reference/tools/ (tool names) |
+
+## Phase 2 — Decide what to do (do this BEFORE editing any files)
+
+Merge the subagent reports into one list of detected drift. Then, **before you edit a
+single file**, decide which path you are on — editing first would leave uncommitted
+changes that block a clean stop on the comment / no-op paths below.
+
+1. **No drift in any verified CLI** → do nothing: make no edits, open no PR, post no
+   comment. Stop. (`unverified` alone is not drift — the docs may just be unreachable
+   today.)
+
+2. **Drift exists — first check for an already-open sync PR:**
+   `gh pr list --base main --state open --search "[auto] sync agent CLI harnesses" --json number,url,headRefName`.
+
+   - **If an open sync PR already exists, do NOT open a second PR and do NOT edit any
+     files.** Read what it already covers (`gh pr diff <number>` plus its body) and
+     compare against your detected drift. If that PR already covers everything you
+     found, stop — nothing to add. If you found drift the PR is **missing**, post ONE
+     comment listing exactly what's missing, then stop —
+     `gh pr comment <number> --body "..."`, e.g.:
+
+     > This open sync PR is missing newly-detected drift:
+     > - **Cursor**: upstream added event `afterEdit` — append to `CURSOR_HOOK_EVENT_TYPES` (+ a `CURSOR_EVENT_MAP` entry).
+     > - **Gemini**: the `run_shell_command` tool was renamed to `shell` — the `GEMINI_TOOL_MAP` key is stale.
+     >
+     > (hook-sync bot — please fold these into this PR rather than opening a second sync PR.)
+
+     Never push commits to another PR's branch; only comment, and leave the working
+     tree clean so this run stops cleanly.
+
+   - **If no open sync PR exists → go to Phase 3** to apply the fixes and open one.
+
+## Phase 3 — Apply the fixes and open one PR
+
+Only reached when there is real drift **and** no open sync PR. Edit only what drift
+requires.
+
+### Scope 1 (event names)
+- **Append** new events just before `] as const`, preserving upstream casing.
+- **Delete** removed events; if the CLI has an `*EVENT_MAP`, also delete the same
+  key from that map (the `Record` is exhaustive — a stale key fails `tsc`).
+- For **map-bearing CLIs** (Codex, Cursor, OpenCode, Pi, Gemini), do **NOT** invent
+  the canonical mapping for a newly-added event — leave it out of the `*EVENT_MAP`
+  so `tsc` fails intentionally, and add a reviewer-checklist item to the PR body
+  (see below). For **Claude and Copilot** (no map), the build stays green.
+- **Fix hardcoded test counts** when the relevant array changed:
+  - If `HOOK_EVENT_TYPES` (Claude) changed: in `__tests__/hooks/manager.test.ts`,
+    update the `installs hooks for all <N> event types` description AND both
+    `expect(Object.keys(written.hooks)).toHaveLength(<N>)` assertions.
+  - If `GEMINI_HOOK_EVENT_TYPES` changed: in `__tests__/hooks/integrations.test.ts`,
+    update the `expect(gemini.eventTypes).toHaveLength(<N>)` assertion AND the
+    matching description string.
+  - Locate these by searching for the current count number.
+
+### Scope 2 / Scope 3 (tool schema / settings-file shape)
+- Apply a fix **only when it is unambiguous and needs no human judgement** — e.g.
+  an invalid field to remove, a wrong timeout unit, or a renamed tool id (the PR
+  #482 class). When you do, move the whole quartet together, exactly like #482:
+  the writer in `src/hooks/integrations.ts` (+ a shared helper if it dedupes
+  logic), the committed dogfood fixture, the unit test in
+  `__tests__/hooks/integrations.test.ts`, and the e2e test in
+  `__tests__/e2e/hooks/<cli>-integration.e2e.test.ts` — plus a `types.ts` comment
+  if it documents the old shape.
+- If the correct fix needs judgement (which canonical event/tool a new item maps
+  to; an ambiguous schema change), **leave the code untouched** and record it as a
+  reviewer-checklist item instead. Bias toward reporting over auto-editing core
+  integration code.
+- Do **NOT** add `*EVENT_MAP`, `*_TOOL_MAP`, or `*_TOOL_INPUT_MAP` entries for
+  newly-added items — the canonical mapping is a human decision.
+
+### CHANGELOG (required)
+Add a single-line entry to `CHANGELOG.md` under `## <version> — <YYYY-MM-DD>` where
+`<version>` is the `version` field in `package.json` (read it) and `<YYYY-MM-DD>` is
+today's UTC date. If that heading does not exist yet, create it above the previous
+version's section. There is no `## Unreleased` section. Use the `### Features` (or
+`### Fixes` for a shape correction) subsection.
+
+### Commit, push, open the PR
+1. Stage only the files you intentionally edited (never `git add -A`):
+   `src/hooks/types.ts`, `src/hooks/integrations.ts`, `src/hooks/policy-evaluator.ts`,
+   the touched `__tests__/...` files, the touched dogfood fixtures, and
+   `CHANGELOG.md` — whichever actually changed.
+2. Commit (e.g. `feat: sync agent CLI harnesses with upstream docs`), then
+   `git push -u origin "$(git branch --show-current)"`.
+3. `gh pr create --base main --title "[auto] sync agent CLI harnesses with upstream docs" --body "<body>"`.
+
+The PR **body** must contain, in order:
+
+1. **Summary table** — one row per CLI: `| CLI | scope-1 | scope-2 | scope-3 | status |`
+   where status is `up to date`, `drift`, or `unverified`.
+2. **Per-CLI sections** — for each CLI with drift, list the added/removed events,
+   tool/schema changes, and settings-shape changes.
+3. **Reviewer checklist** — one unchecked box per item that needs a human decision:
+   - For each newly-added event on a map-bearing CLI:
+     `- [ ] Add \`<event>: "???"\` to \`<MAP_NAME>\` in \`src/hooks/types.ts\` (canonical Claude \`HookEventType\` chosen by reviewer)`
+   - For each scope-2/scope-3 change you deferred as judgement-heavy.
+4. **Sources** — the docs URL(s) consulted per CLI.
+5. **Unverified notes** — one line per `unverified` CLI explaining why.
+6. **Final note (verbatim):**
+   > **CI is expected to fail on this PR if a map-bearing CLI gained new events — a
+   > reviewer must add the missing `*EVENT_MAP` entries (replacing `"???"`) before
+   > merging. For drift in Claude or Copilot only (no event map), CI should pass on
+   > this commit alone. CI must pass and this PR must be reviewed before merging.**
+
+## Constraints
+
+- **Only edit** these paths, and only where drift requires it: `src/hooks/types.ts`,
+  `src/hooks/integrations.ts`, `src/hooks/policy-evaluator.ts`,
+  `__tests__/hooks/manager.test.ts`, `__tests__/hooks/integrations.test.ts`,
+  `__tests__/e2e/hooks/<cli>-integration.e2e.test.ts`, the seven dogfood fixtures
+  (`.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json`,
+  `.github/hooks/failproofai.json`, `.opencode/opencode.json`,
+  `.opencode/plugins/failproofai.mjs`, `.pi/settings.json`, `.gemini/settings.json`),
+  and `CHANGELOG.md`.
+- Do **NOT** edit `.failproofai/policies-config.json` (the entrypoint manages it),
+  `src/hooks/handler.ts`, `src/hooks/manager.ts`, or any other source file.
+- Do **NOT** add entries to any `*EVENT_MAP`, `*_TOOL_MAP`, or `*_TOOL_INPUT_MAP`
+  for newly-added items. Removing a key when its array entry is removed IS allowed
+  (and required to keep the build green).
+- Do **NOT** invent events, tools, or fields. If WebFetch fails or the docs don't
+  expose a clean list, mark the CLI `unverified` and move on.

package/src/audit/cli-adapters/hermes.ts

@@ -0,0 +1,58 @@
+/**
+ * Hermes (hermes-agent) transcript adapter — AUDIT-ONLY (Pillar 2).
+ *
+ * Hermes keeps every gateway user's sessions in one SQLite DB. We read it
+ * directly via the bundled sql.js reader (lib/hermes-projects.ts enumerates the
+ * `sessions` table; lib/hermes-sessions.ts parses each session's `messages`),
+ * producing the same LogEntry[] shape the other adapters do — so
+ * `logEntriesToEvents` handles the rest.
+ *
+ * Gateway sessions have no `cwd` (Slack/Telegram runs aren't in a repo), so they
+ * group by `source` (slack/telegram/cli/cron) instead of working directory.
+ */
+import { getHermesSessions } from "../../../lib/hermes-projects";
+import { getHermesSessionLog } from "../../../lib/hermes-sessions";
+import type { NormalizedToolEvent, TranscriptMetadata } from "../types";
+import type { ListOpts } from "./claude";
+import { logEntriesToEvents } from "./shared";
+
+export async function listHermesTranscriptMetadata(
+  opts: ListOpts = {},
+): Promise<TranscriptMetadata[]> {
+  // `audit --project <cwd>` filters on working directory; gateway sessions have
+  // none, so Hermes contributes nothing to a cwd-scoped audit.
+  if (opts.projects && opts.projects.length > 0) return [];
+
+  const sinceMs = opts.sinceMs ?? 0;
+  const sessions = await getHermesSessions();
+  const out: TranscriptMetadata[] = [];
+  for (const s of sessions) {
+    if (s.mtimeMs < sinceMs) continue;
+    if (s.messageCount <= 0 && !s.hasMessages) continue; // empty → no events (message_count can lag; trust real messages)
+    out.push({
+      cli: "hermes",
+      // Group by channel; gateway sessions are cwd-less.
+      projectName: s.source ? `hermes:${s.source}` : "hermes",
+      sessionId: s.sessionId,
+      transcriptPath: `hermes://${s.sessionId}`,
+      mtimeMs: s.mtimeMs,
+      // message_count is stable for an ended session, so (mtime, size) forms a
+      // real per-transcript cache key — an ended session is parsed once.
+      sizeBytes: s.messageCount,
+    });
+  }
+  return out;
+}
+
+export async function streamHermesEvents(
+  meta: TranscriptMetadata,
+): Promise<NormalizedToolEvent[]> {
+  const log = await getHermesSessionLog(meta.sessionId);
+  if (!log) return [];
+  return logEntriesToEvents(log.entries, {
+    cli: "hermes",
+    sessionId: meta.sessionId,
+    transcriptPath: meta.transcriptPath,
+    cwd: log.cwd ?? "",
+  });
+}

package/src/audit/cli-adapters/index.ts

@@ -18,6 +18,7 @@ import { listCursorTranscriptMetadata, streamCursorEvents } from "./cursor";
 import { listOpenCodeTranscriptMetadata, streamOpenCodeEvents } from "./opencode";
 import { listPiTranscriptMetadata, streamPiEvents } from "./pi";
 import { listGeminiTranscriptMetadata, streamGeminiEvents } from "./gemini";
+import { listHermesTranscriptMetadata, streamHermesEvents } from "./hermes";
 
 export type { ListOpts };
 
@@ -63,6 +64,11 @@ export const ADAPTERS: Record<IntegrationType, CliAdapter> = {
     listTranscripts: listGeminiTranscriptMetadata,
     streamEvents: streamGeminiEvents,
   },
+  hermes: {
+    cli: "hermes",
+    listTranscripts: listHermesTranscriptMetadata,
+    streamEvents: streamHermesEvents,
+  },
 };
 
 export function getAdapter(cli: IntegrationType): CliAdapter {

package/src/hooks/handler.ts

@@ -13,12 +13,14 @@ import type {
   CursorHookEventType,
   PiHookEventType,
   GeminiHookEventType,
+  HermesHookEventType,
 } from "./types";
 import {
   CODEX_EVENT_MAP,
   CURSOR_EVENT_MAP,
   PI_EVENT_MAP,
   GEMINI_EVENT_MAP,
+  HERMES_EVENT_MAP,
 } from "./types";
 import { canonicalizeToolName, canonicalizeToolInput } from "./tool-name-canonicalize";
 import type { PolicyFunction, PolicyResult } from "./policy-types";
@@ -65,6 +67,12 @@ function canonicalizeEventType(raw: string, cli: IntegrationType): HookEventType
     const mapped = GEMINI_EVENT_MAP[raw as GeminiHookEventType];
     if (mapped) return mapped;
   }
+  if (cli === "hermes") {
+    // Hermes sends snake_case event names (pre_tool_call, on_session_start, …);
+    // map to PascalCase. Has no turn-end Stop event, so no Stop mapping exists.
+    const mapped = HERMES_EVENT_MAP[raw as HermesHookEventType];
+    if (mapped) return mapped;
+  }
   // claude / copilot / unknown — already PascalCase, pass through.
   // HOOK_EVENT_TYPES type-checks downstream.
   return raw as HookEventType;

package/src/hooks/install-prompt.ts

@@ -11,8 +11,8 @@
  */
 import * as readline from "node:readline";
 import { BUILTIN_POLICIES } from "./builtin-policies";
-import { detectInstalledClis, getIntegration } from "./integrations";
-import { INTEGRATION_TYPES, type IntegrationType } from "./types";
+import { detectInstalledClis, getIntegration, listInstallableIds } from "./integrations";
+import { type IntegrationType } from "./types";
 import { trackHookEvent } from "./hook-telemetry";
 import { getInstanceId } from "../../lib/telemetry-id";
 
@@ -139,7 +139,11 @@ export function buildCliMenuOptions(
 ): { options: CliMenuOption[]; undetected: IntegrationType[] } {
   const undetected: IntegrationType[] =
     action === "install"
-      ? INTEGRATION_TYPES.filter((id) => !detected.includes(id))
+      ? // Only CLIs that support live-hook install — a future audit-only CLI
+        // (one with no INTEGRATIONS entry) has no install path and must not
+        // appear as a forward-install option. (hermes IS installable, so it
+        // correctly appears here.)
+        listInstallableIds().filter((id) => !detected.includes(id))
       : [];
 
   const options: CliMenuOption[] = [];

package/src/hooks/integrations.ts

@@ -11,6 +11,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from "
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
+import { parseDocument, type Document } from "yaml";
 import {
   HOOK_EVENT_TYPES,
   HOOK_SCOPES,
@@ -27,6 +28,8 @@ import {
   PI_HOOK_SCOPES,
   GEMINI_HOOK_EVENT_TYPES,
   GEMINI_HOOK_SCOPES,
+  HERMES_HOOK_EVENT_TYPES,
+  HERMES_HOOK_SCOPES,
   FAILPROOFAI_HOOK_MARKER,
   INTEGRATION_TYPES,
   type IntegrationType,
@@ -50,6 +53,23 @@ function writeJsonFile(path: string, data: Record<string, unknown>): void {
   writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf8");
 }
 
+/** Read a YAML file as a `Document` so writes round-trip the user's other keys +
+ *  comments (a plain parse→stringify would strip comments). Empty / missing /
+ *  corrupt → an empty Document. Used by the Hermes integration, whose config
+ *  lives in `~/.hermes/config.yaml`. */
+function readYamlDoc(path: string): Document {
+  try {
+    return existsSync(path) ? parseDocument(readFileSync(path, "utf8")) : parseDocument("");
+  } catch {
+    return parseDocument("");
+  }
+}
+
+function writeYamlDoc(path: string, doc: Document): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, doc.toString(), "utf8");
+}
+
 function isMarkedHook(hook: unknown): boolean {
   if (!hook || typeof hook !== "object") return false;
   const h = hook as Record<string, unknown>;
@@ -154,7 +174,10 @@ export const claudeCode: Integration = {
     return {
       type: "command",
       command,
-      timeout: 60_000,
+      // Claude reads `timeout` in SECONDS per https://code.claude.com/docs/en/hooks
+      // ("Seconds before canceling. Defaults: 600 for command ...; 60 for agent"),
+      // NOT milliseconds. 60 = 60s; the old 60000 meant ~16.7h. (#482-class unit fix)
+      timeout: 60,
       [FAILPROOFAI_HOOK_MARKER]: true,
     };
   },
@@ -285,8 +308,10 @@ export const codex: Integration = {
         : `"${binaryPath}" --hook ${eventType} --cli codex`;
     return {
       type: "command",
-      // Codex reads `timeout` in SECONDS (its `timeout_sec` field, default 600) —
-      // NOT milliseconds like Claude/Cursor/Gemini. 60 = 60s, not 60000ms (~16.7h).
+      // Codex reads `timeout` in SECONDS (the field is literally `timeout`,
+      // default 600 per https://developers.openai.com/codex/hooks) — same unit as
+      // Claude/Cursor/Copilot, and unlike Gemini, whose `timeout` is in
+      // milliseconds (default 60000). 60 = 60s, not 60000ms (~16.7h).
       command,
       timeout: 60,
       [FAILPROOFAI_HOOK_MARKER]: true,
@@ -591,11 +616,13 @@ export const cursor: Integration = {
       scope === "project"
         ? `npx -y failproofai --hook ${eventType} --cli cursor`
         : `"${binaryPath}" --hook ${eventType} --cli cursor`;
-    // `timeout` is documented as ms in Cursor's schema (matches Claude).
+    // `timeout` is documented in SECONDS in Cursor's schema per
+    // https://cursor.com/docs/hooks ("Execution timeout in seconds"; doc examples
+    // use 30 and 10), NOT milliseconds. 60 = 60s; the old 60000 meant ~16.7h.
     return {
       type: "command",
       command,
-      timeout: 60_000,
+      timeout: 60,
       [FAILPROOFAI_HOOK_MARKER]: true,
     };
   },
@@ -1416,9 +1443,146 @@ export const gemini: Integration = {
   },
 };
 
+// ── Hermes (hermes-agent) — live hooks (Pillar 1) ────────────────────────────
+//
+// External-command CLI like codex/cursor, but its config is YAML
+// (`~/.hermes/config.yaml`) under a `hooks:` map, so the I/O layer uses the yaml
+// Document API (comment-preserving). Flat per-event arrays like cursor:
+// `hooks: { pre_tool_call: [ { command, timeout, <marker> } ], … }`. Hermes
+// reads a `{"decision":"block",…}` JSON response on stdout (see
+// policy-evaluator.ts); exit codes are ignored. User-scope only.
+
+/** One hook entry as stored under a `hooks:` event key in config.yaml. */
+interface HermesHookEntry {
+  command: string;
+  timeout?: number;
+  [key: string]: unknown;
+}
+
+export const hermes: Integration = {
+  id: "hermes",
+  displayName: "Hermes",
+  scopes: HERMES_HOOK_SCOPES,
+  eventTypes: HERMES_HOOK_EVENT_TYPES,
+
+  // Hermes config is USER-scope only (`~/.hermes/config.yaml`); there is no
+  // project/local file, so scope/cwd are irrelevant here.
+  getSettingsPath() {
+    return resolve(homedir(), ".hermes", "config.yaml");
+  },
+
+  readSettings(settingsPath) {
+    // Return the yaml Document (cast) so writeHookEntries/writeSettings can
+    // round-trip it while preserving the user's other keys + comments.
+    return readYamlDoc(settingsPath) as unknown as Record<string, unknown>;
+  },
+
+  writeSettings(settingsPath, settings) {
+    writeYamlDoc(settingsPath, settings as unknown as Document);
+  },
+
+  buildHookEntry(binaryPath, eventType, scope) {
+    // No matcher → fires for ALL tools / all platforms (slack/telegram/cli/cron)
+    // and internal subagents. `timeout` is in seconds; Hermes runs the command
+    // via shlex.split (shell=false).
+    const command =
+      scope === "project"
+        ? `npx -y failproofai --hook ${eventType} --cli hermes`
+        : `"${binaryPath}" --hook ${eventType} --cli hermes`;
+    return {
+      command,
+      timeout: 30,
+      [FAILPROOFAI_HOOK_MARKER]: true,
+    };
+  },
+
+  isFailproofaiHook: isMarkedHook,
+
+  writeHookEntries(settings, binaryPath, scope) {
+    const doc = settings as unknown as Document;
+    // Read the current hooks map as plain JS, then re-set ONLY the `hooks` key —
+    // preserving comments on every other part of config.yaml.
+    const js = (doc.toJS() ?? {}) as { hooks?: Record<string, HermesHookEntry[]> };
+    const hooks: Record<string, HermesHookEntry[]> =
+      js.hooks && typeof js.hooks === "object" ? js.hooks : {};
+
+    for (const eventType of HERMES_HOOK_EVENT_TYPES) {
+      const entry = this.buildHookEntry(binaryPath, eventType, scope) as unknown as HermesHookEntry;
+      const arr = Array.isArray(hooks[eventType]) ? hooks[eventType] : [];
+      const idx = arr.findIndex((h) => isMarkedHook(h));
+      if (idx >= 0) arr[idx] = entry;
+      else arr.push(entry);
+      hooks[eventType] = arr;
+    }
+    doc.set("hooks", hooks);
+    // The headless gateway has no TTY to answer Hermes's first-use hook-consent
+    // prompt, so auto-accept declared hooks. Tradeoff: also auto-accepts any
+    // other hook the operator adds; a targeted `shell-hooks-allowlist.json`
+    // pre-seed is a future refinement.
+    doc.set("hooks_auto_accept", true);
+  },
+
+  removeHooksFromFile(settingsPath) {
+    if (!existsSync(settingsPath)) return 0;
+    const doc = readYamlDoc(settingsPath);
+    const js = (doc.toJS() ?? {}) as { hooks?: Record<string, HermesHookEntry[]> };
+    const hooks = js.hooks;
+
+    let removed = 0;
+    if (hooks && typeof hooks === "object") {
+      for (const eventType of Object.keys(hooks)) {
+        const entries = hooks[eventType];
+        if (!Array.isArray(entries)) continue;
+        const before = entries.length;
+        const filtered = entries.filter((h) => !isMarkedHook(h));
+        removed += before - filtered.length;
+        if (filtered.length === 0) delete hooks[eventType];
+        else hooks[eventType] = filtered;
+      }
+      if (removed > 0) {
+        if (Object.keys(hooks).length === 0) doc.delete("hooks");
+        else doc.set("hooks", hooks);
+      }
+    }
+
+    // Always drop our headless-consent flag on uninstall — even if the hooks were
+    // already removed manually — so it can't silently auto-accept future operator
+    // hooks. `doc.delete` returns true iff the key was present.
+    const droppedAutoAccept = doc.delete("hooks_auto_accept");
+    if (removed > 0 || droppedAutoAccept) writeYamlDoc(settingsPath, doc);
+    return removed;
+  },
+
+  hooksInstalledInSettings(scope, cwd) {
+    const settingsPath = this.getSettingsPath(scope, cwd);
+    if (!existsSync(settingsPath)) return false;
+    try {
+      const doc = readYamlDoc(settingsPath);
+      const js = (doc.toJS() ?? {}) as { hooks?: Record<string, HermesHookEntry[]> };
+      const hooks = js.hooks;
+      if (!hooks || typeof hooks !== "object") return false;
+      for (const entries of Object.values(hooks)) {
+        if (Array.isArray(entries) && entries.some((h) => isMarkedHook(h))) return true;
+      }
+    } catch {
+      // Corrupt config — treat as not installed.
+    }
+    return false;
+  },
+
+  detectInstalled() {
+    return binaryExists("hermes");
+  },
+};
+
 // ── Registry ────────────────────────────────────────────────────────────────
 
-const INTEGRATIONS: Record<IntegrationType, Integration> = {
+// `Partial` is kept (not every IntegrationType is guaranteed installable for
+// LIVE hooks / Pillar 1) so a future audit-only CLI can omit its entry without a
+// type error. `hermes` now has BOTH an audit adapter
+// (src/audit/cli-adapters/hermes.ts) AND live-hook install support, so it is
+// registered here.
+const INTEGRATIONS: Partial<Record<IntegrationType, Integration>> = {
   claude: claudeCode,
   codex,
   copilot,
@@ -1426,21 +1590,38 @@ const INTEGRATIONS: Record<IntegrationType, Integration> = {
   opencode,
   pi,
   gemini,
+  hermes,
 };
 
 export function getIntegration(id: IntegrationType): Integration {
   const integration = INTEGRATIONS[id];
   if (!integration) {
-    throw new Error(`Unknown integration: ${id}. Valid: ${INTEGRATION_TYPES.join(", ")}`);
+    // A future audit-only CLI (one with an audit adapter but no INTEGRATIONS
+    // entry) reaches here when someone tries to install live hooks for it. Be
+    // explicit rather than "unknown integration". (hermes is NOT audit-only — it
+    // has a live-hook entry — so it never reaches this branch.)
+    throw new Error(
+      `"${id}" is audit-only — live-hook install is not supported for it yet. Installable: ${listInstallableIds().join(", ")}`,
+    );
   }
   return integration;
 }
 
+/** IntegrationTypes that support live-hook install (i.e. have an INTEGRATIONS
+ *  entry). Any audit-only CLI (one with an audit adapter but no hook install)
+ *  is excluded so it never appears in install menus. */
+export function listInstallableIds(): IntegrationType[] {
+  return INTEGRATION_TYPES.filter((id) => INTEGRATIONS[id] !== undefined);
+}
+
 export function listIntegrations(): Integration[] {
-  return INTEGRATION_TYPES.map((id) => INTEGRATIONS[id]);
+  return INTEGRATION_TYPES.map((id) => INTEGRATIONS[id]).filter(
+    (i): i is Integration => i !== undefined,
+  );
 }
 
-/** Detect which agent CLIs are installed on PATH. */
+/** Detect which agent CLIs are installed on PATH. Only considers CLIs that
+ *  support live-hook install (audit-only CLIs have no INTEGRATIONS entry). */
 export function detectInstalledClis(): IntegrationType[] {
-  return INTEGRATION_TYPES.filter((id) => INTEGRATIONS[id].detectInstalled());
+  return INTEGRATION_TYPES.filter((id) => INTEGRATIONS[id]?.detectInstalled());
 }