backpass 0.1.0 → 0.1.2

package/README.md

@@ -15,6 +15,11 @@
   <a href="https://x.com/kunchenguid"
     ><img alt="X" src="https://img.shields.io/badge/X-@kunchenguid-black?style=flat-square"
   /></a>
+  <a href="https://discord.gg/Wsy2NpnZDu"
+    ><img
+      alt="Discord"
+      src="https://img.shields.io/discord/1439901831038763092?style=flat-square&label=discord"
+  /></a>
 </p>
 
 <h3 align="center">Gradient descent for your agent memory.</h3>
@@ -27,7 +32,7 @@ The loop only closes when a human happens to remember a failure and edits the fi
 what happened in them, and proposes evidence-backed edits to your memory file - under a
 token budget, gated by you.
 
-- **Local-first** - Reads the transcript stores of six agent harnesses directly from disk.
+- **Local-first** - Reads the transcript stores of seven agent harnesses directly from disk.
   No API, no upload; transcripts never leave your machine except into an agent you already
   authenticated, and obvious secrets are redacted before they do.
 - **Evidence-gated** - Every proposed edit carries verbatim quotes from real sessions, a
@@ -73,16 +78,20 @@ backpass apply     # review each edit, accept or reject, then write
 
 ### 1. Collect samples - which sessions belong to this repo
 
-backpass reads the local transcript stores of six harnesses directly. No API, no upload.
+backpass reads the local transcript stores of seven harnesses directly. No API, no upload.
+
+| Harness        | Store                                          | Repo tie                                |
+| -------------- | ---------------------------------------------- | --------------------------------------- |
+| **claude**     | `~/.claude/projects/<munged-cwd>/<uuid>.jsonl` | per-line `cwd`                          |
+| **codex**      | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` | `cwd` + recorded `git.repository_url`   |
+| **pi**         | `~/.pi/agent/sessions/<escaped-cwd>/*.jsonl`   | session-header `cwd`                    |
+| **opencode**   | `~/.local/share/opencode/opencode.db` (sqlite) | `session.directory`                     |
+| **grok**       | `~/.grok/sessions/<encoded-cwd>/<uuid>/`       | `summary.json` `cwd` + `git_remotes`    |
+| **cursor CLI** | `~/.cursor/chats/<md5(cwd)>/<uuid>/`           | `meta.json` `cwd`                       |
+| **hermes**     | `~/.hermes/state.db` (sqlite)                  | CLI prompt cwd / ACP `model_config.cwd` |
 
-| Harness        | Store                                          | Repo tie                              |
-| -------------- | ---------------------------------------------- | ------------------------------------- |
-| **claude**     | `~/.claude/projects/<munged-cwd>/<uuid>.jsonl` | per-line `cwd`                        |
-| **codex**      | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` | `cwd` + recorded `git.repository_url` |
-| **pi**         | `~/.pi/agent/sessions/<escaped-cwd>/*.jsonl`   | session-header `cwd`                  |
-| **opencode**   | `~/.local/share/opencode/opencode.db` (sqlite) | `session.directory`                   |
-| **grok**       | `~/.grok/sessions/<encoded-cwd>/<uuid>/`       | `summary.json` `cwd` + `git_remotes`  |
-| **cursor CLI** | `~/.cursor/chats/<md5(cwd)>/<uuid>/`           | `meta.json` `cwd`                     |
+Hermes collection includes CLI and ACP sessions only. Gateway, cron, and WhatsApp sessions
+are excluded because their recorded cwd belongs to the shared gateway process, not a project.
 
 Association runs in three tiers:
 
@@ -226,12 +235,15 @@ the evidence quotes and their sources, a live budget gauge, and ACCEPT / REJECT.
 
 The surface is a static template shipped in the package - the CLI injects one JSON payload,
 so it is instant, deterministic, and identical every run. Nothing there is model-generated.
+It opens in your default browser when one is available; the URL is always printed too, so
+a headless box or `--no-open` just hands you the link.
 
 There is no DEFER button, and it isn't missing: **rejections are remembered.** A rejected
 edit is not proposed again unless materially new evidence arrives.
 
 ```sh
 backpass apply --no-ui     # same decision, in the terminal
+backpass apply --no-open   # print the surface URL, don't launch a browser
 backpass apply --dry-run   # show what would be written
 ```
 
@@ -347,7 +359,7 @@ CLI flags on top:
     ]
   },
   "discovery": {
-    "harnesses": ["claude", "codex", "pi", "opencode", "grok", "cursor"],
+    "harnesses": ["claude", "codex", "pi", "opencode", "grok", "cursor", "hermes"],
     "since": "30d",
     "worktreeGlobs": [],
     "minUserTurns": 2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backpass",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "packageManager": "pnpm@11.5.0",
   "description": "Gradient descent for your agent memory - analyzes past agent session transcripts and proposes evidence-backed edits to AGENTS.md / CLAUDE.md",
   "type": "module",

package/src/apply/browser.js

@@ -0,0 +1,49 @@
+import { spawn } from "node:child_process";
+
+/**
+ * Open a URL in the user's default browser, best effort.
+ *
+ * The review surface URL is always printed as the fallback, so this must never throw or
+ * block: a missing opener, a headless box, or a crashing helper all degrade to "print the
+ * URL only". Returns true when an opener was launched, false when the environment opted
+ * out or had no display.
+ *
+ * Dependencies are injectable so the decision logic is testable without a real browser.
+ *
+ * @typedef {(bin: string, args: string[], options: object) => { on?: Function, unref?: Function }} Spawner
+ * @param {string | null} url
+ * @param {{ platform?: string, env?: Record<string, string | undefined>, spawnFn?: Spawner }} [deps]
+ */
+export function openInBrowser(url, { platform = process.platform, env = process.env, spawnFn = spawn } = {}) {
+  if (!url || !/^https?:\/\//.test(url)) return false;
+  if (!canOpenBrowser({ platform, env })) return false;
+
+  const { bin, args } = openerCommand(url, platform);
+  try {
+    const child = spawnFn(bin, args, { stdio: "ignore", detached: true, windowsHide: true });
+    // A missing or failing opener must not surface as an unhandled error.
+    child.on?.("error", () => {});
+    child.unref?.();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Headless detection: honor explicit opt-outs, CI, and display-less Linux.
+ * @param {{ platform?: string, env?: Record<string, string | undefined> }} [deps]
+ */
+export function canOpenBrowser({ platform = process.platform, env = process.env } = {}) {
+  if (env.BACKPASS_NO_BROWSER || env.CI) return false;
+  if (platform === "darwin" || platform === "win32") return true;
+  return Boolean(env.DISPLAY || env.WAYLAND_DISPLAY);
+}
+
+/** @returns {{ bin: string, args: string[] }} */
+function openerCommand(url, platform) {
+  if (platform === "darwin") return { bin: "open", args: [url] };
+  // `start` treats its first quoted argument as the window title; pass an empty one.
+  if (platform === "win32") return { bin: "cmd", args: ["/c", "start", "", url] };
+  return { bin: "xdg-open", args: [url] };
+}

package/src/apply/lavish.js

@@ -88,18 +88,37 @@ export async function openApplySurface(file) {
   if (result.code !== 0) {
     throw new UserError(`${LAVISH_BIN} failed to open the apply surface`, result.stderr.trim().slice(0, 400));
   }
-  const url = /(https?:\/\/\S+)/.exec(`${result.stdout}\n${result.stderr}`);
-  return url ? url[1] : null;
+  return extractUrl(`${result.stdout}\n${result.stderr}`);
 }
 
+/**
+ * Pull the session URL out of lavish-axi's output. The CLI prints it YAML-style as
+ * `url: "http://..."`, so a bare `\S+` would swallow the closing quote; stop at any
+ * quote or bracket and drop trailing punctuation.
+ */
+export function extractUrl(text) {
+  const match = /https?:\/\/[^\s"'<>()[\]]+/.exec(text || "");
+  if (!match) return null;
+  return match[0].replace(/[.,;:!?]+$/, "");
+}
+
+/** Breathing room between polls that came back without a decision vector. */
+export const POLL_RETRY_DELAY_MS = 1000;
+
 /**
  * Long-poll for the human's decision vector. `lavish-axi poll` blocks until the reviewer
  * sends feedback, so this is intentionally a foreground wait.
+ *
+ * Feedback that is not a decision vector (a comment, a queued layout report) keeps the
+ * wait going. Each state is announced once: the wait line on entry, and a single note the
+ * first time non-decision feedback arrives - never one line per poll cycle, which on a
+ * chatty surface floods the terminal.
  */
-export async function pollDecisions(file, editIds) {
+export async function pollDecisions(file, editIds, { delayMs = POLL_RETRY_DELAY_MS } = {}) {
   info(
     `${color.dim("waiting for your decisions in the browser (Ctrl-C to abort; nothing is written until you send)")}`,
   );
+  let notedOtherFeedback = false;
 
   for (;;) {
     const result = await runLavish(["poll", file]);
@@ -118,8 +137,14 @@ export async function pollDecisions(file, editIds) {
       warn("review session ended without a decision vector - nothing applied");
       return null;
     }
-    // Feedback that was not a decision vector (a comment, a layout report): keep waiting.
-    info(`${color.dim("received feedback without a decision vector; still waiting")}`);
+
+    if (!notedOtherFeedback) {
+      notedOtherFeedback = true;
+      info(
+        `${color.dim("feedback arrived without a decision vector - click APPLY in the browser and send from the panel; still waiting")}`,
+      );
+    }
+    if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
   }
 }
 

package/src/cli.js

@@ -53,6 +53,7 @@ const OPTIONS = {
 
   "dry-run": { type: "boolean" },
   "no-ui": { type: "boolean" },
+  "no-open": { type: "boolean" },
   "no-auto-agent": { type: "boolean" },
   force: { type: "boolean" },
   limit: { type: "string" },
@@ -82,7 +83,7 @@ COMMANDS
 COLLECT SAMPLES
   --since <dur>            only sessions newer than this (30d, 12h, 2w, all)  [30d]
   --harness <a,b>          limit to these harnesses
-                           (claude, codex, pi, opencode, grok, cursor)
+                           (claude, codex, pi, opencode, grok, cursor, hermes)
   --strict                 deterministic associations only (tiers 1 and 2)
   --include-cursor-ide     also scan the Cursor IDE store (best-effort, v1.1 preview)
   --limit <n>              analyze at most N transcripts this run (newest first)
@@ -114,6 +115,7 @@ BUDGET AND SHAPE
 
 APPLY
   --no-ui                  terminal accept/reject instead of the Lavish surface
+  --no-open                print the review surface URL without opening a browser
   --dry-run                show what would be written, write nothing
   --force                  re-analyze transcripts that already have fresh evidence,
                            and re-probe agents instead of trusting the probe cache

package/src/commands/apply.js

@@ -2,6 +2,7 @@ import { UserError, color, info, json, out, warn } from "../logger.js";
 import { applyDecisions } from "../apply/writer.js";
 import { closeApplySurface, openApplySurface, pollDecisions, renderApplySurface } from "../apply/lavish.js";
 import { reviewInTerminal } from "../apply/terminal.js";
+import { openInBrowser } from "../apply/browser.js";
 import { budgetBar, formatTokens } from "../tokens.js";
 
 /**
@@ -45,6 +46,8 @@ export async function cmdApply(ctx) {
     surfaceFile = renderApplySurface(proposal, config.state, ctx.version);
     const url = await openApplySurface(surfaceFile);
     info(`${color.cyan("·")} review surface: ${url || surfaceFile}`);
+    // Best effort: the printed URL above is the fallback when nothing opens.
+    if (!ctx.flags["no-open"]) openInBrowser(url);
     decisions = await pollDecisions(surfaceFile, editIds);
   }
 

package/src/config.js

@@ -7,7 +7,7 @@ import { UserError, warn } from "./logger.js";
 export const CONFIG_FILENAME = ".backpassrc.json";
 export const STATE_DIRNAME = ".backpass";
 
-export const ALL_HARNESSES = ["claude", "codex", "pi", "opencode", "grok", "cursor"];
+export const ALL_HARNESSES = ["claude", "codex", "pi", "opencode", "grok", "cursor", "hermes"];
 /** Cursor IDE is deferred to v1.1 and only ever runs behind --include-cursor-ide. */
 export const OPT_IN_HARNESSES = ["cursor-ide"];
 

package/src/discovery/adapters/hermes.js

@@ -0,0 +1,222 @@
+import path from "node:path";
+
+import { home, contentToEvents, attachToolResults } from "./shared.js";
+import { openReadOnly, safeJsonParse } from "./sqlite.js";
+
+/**
+ * hermes: ~/.hermes/state.db (sqlite)
+ *
+ * Observed schema version 13 (upstream is 26; SELECT named columns so additive
+ * columns are tolerated). Hermes has no cwd, git branch, or git remote column.
+ *
+ * Association is recovered only for source in ('cli', 'acp'):
+ *   acp - model_config.cwd when it is an absolute path
+ *   cli - first `Current working directory:` / `Working directory:` line in
+ *         system_prompt
+ * Gateway / cron / whatsapp sessions are skipped: their prompt cwd is the
+ * gateway process cwd, not a project, and would pin unrelated sessions to one
+ * repo. Sessions with no recoverable cwd are skipped.
+ *
+ * Timestamps are epoch seconds; backpass uses milliseconds (x1000).
+ * Structured content uses a `\x00json:` prefix; node:sqlite truncates TEXT at
+ * NUL, so message content is read as BLOB and decoded.
+ * JSONL leftovers under ~/.hermes/sessions/ are abandoned and not read.
+ * Honor HERMES_HOME; do not walk profile directories.
+ */
+
+export const name = "hermes";
+export const sqliteBacked = true;
+
+const CLI_ACP = new Set(["cli", "acp"]);
+const JSON_PREFIX = "\x00json:";
+const CWD_LINE = /^(?:Current working directory|Working directory):\s*(.+)$/m;
+
+export function storeRoot() {
+  return process.env.HERMES_HOME || home(".hermes");
+}
+
+export function dbPath() {
+  return path.join(storeRoot(), "state.db");
+}
+
+function toMs(epochSeconds) {
+  const n = Number(epochSeconds);
+  return Number.isFinite(n) ? Math.round(n * 1000) : null;
+}
+
+function looksAbsolute(value) {
+  return typeof value === "string" && value.length > 0 && path.isAbsolute(value);
+}
+
+function cwdFromConfig(raw) {
+  const parsed = typeof raw === "string" ? safeJsonParse(raw) : raw;
+  return looksAbsolute(parsed?.cwd) ? parsed.cwd : null;
+}
+
+function cwdFromPrompt(prompt) {
+  if (typeof prompt !== "string" || !prompt) return null;
+  const match = prompt.match(CWD_LINE);
+  if (!match) return null;
+  const cwd = match[1].trim();
+  return looksAbsolute(cwd) ? cwd : null;
+}
+
+function recoverCwd(row, source) {
+  if (source === "acp") return cwdFromConfig(row.model_config);
+  if (source === "cli") return cwdFromPrompt(row.system_prompt);
+  return null;
+}
+
+function activeMessageFilter(db, alias = "") {
+  const hasActive = db
+    .prepare("PRAGMA table_info(messages)")
+    .all()
+    .some((column) => column.name === "active");
+  return hasActive ? ` AND ${alias}active = 1` : "";
+}
+
+/**
+ * Discovery is one indexed query. The caller applies the shared association
+ * tiers and handles schema errors per harness. A missing DB yields an empty list.
+ * @param {{ cutoffMs?: number }} [options]
+ */
+export async function discover({ cutoffMs } = {}) {
+  const db = await openReadOnly(dbPath());
+  if (!db) return [];
+
+  const cutoffSec = cutoffMs == null ? null : cutoffMs / 1000;
+  try {
+    const activeFilter = activeMessageFilter(db, "m.");
+    const rows = db
+      .prepare(
+        `SELECT s.id, s.source, s.model, s.model_config, s.system_prompt, s.title,
+                s.started_at, s.ended_at,
+                MAX(s.started_at,
+                    COALESCE(s.ended_at, s.started_at),
+                    COALESCE((SELECT MAX(m.timestamp)
+                                FROM messages m
+                               WHERE m.session_id = s.id${activeFilter}),
+                             s.started_at)) AS activity_at
+           FROM sessions s
+          WHERE lower(s.source) IN ('cli', 'acp')
+            AND (? IS NULL OR
+                 MAX(s.started_at,
+                     COALESCE(s.ended_at, s.started_at),
+                     COALESCE((SELECT MAX(m.timestamp)
+                                 FROM messages m
+                                WHERE m.session_id = s.id${activeFilter}),
+                              s.started_at)) >= ?)`,
+      )
+      .all(cutoffSec, cutoffSec ?? 0);
+
+    const out = [];
+    for (const row of rows) {
+      const source = String(row.source || "").toLowerCase();
+      if (!CLI_ACP.has(source)) continue;
+      const cwd = recoverCwd(row, source);
+      if (!cwd) continue;
+      const startedAt = toMs(row.started_at);
+      const activityAt = toMs(row.activity_at);
+      out.push({
+        key: `hermes:${row.id}`,
+        id: row.id,
+        path: dbPath(),
+        cwd,
+        gitRoot: null,
+        gitBranch: null,
+        remotes: [],
+        title: row.title || null,
+        startedAt,
+        mtimeMs: activityAt || startedAt || 0,
+        bytes: 0,
+        model: row.model || null,
+        extra: { sessionId: row.id, source },
+      });
+    }
+    return out;
+  } finally {
+    db.close();
+  }
+}
+
+/** node:sqlite truncates TEXT at a NUL, so `\x00json:` payloads must be read as BLOB. */
+function sqliteText(value) {
+  if (value == null) return value;
+  if (typeof value === "string") return value;
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+    return new TextDecoder("utf8").decode(value);
+  }
+  return String(value);
+}
+
+function decodeContent(content) {
+  const text = sqliteText(content);
+  if (typeof text !== "string") return content;
+  if (!text.startsWith(JSON_PREFIX)) return text;
+  const parsed = safeJsonParse(text.slice(JSON_PREFIX.length));
+  return parsed == null ? text : parsed;
+}
+
+function emitTools(raw, events, idAlias) {
+  const text = sqliteText(raw);
+  const parsed = typeof text === "string" ? safeJsonParse(text) : text;
+  if (!Array.isArray(parsed)) return;
+  for (const call of parsed) {
+    if (!call || typeof call !== "object") continue;
+    const fn = call.function && typeof call.function === "object" ? call.function : {};
+    const name = fn.name || call.name;
+    let input = fn.arguments ?? call.arguments;
+    if (typeof input === "string") {
+      const parsedInput = safeJsonParse(input);
+      if (parsedInput !== null) input = parsedInput;
+    }
+    const pendingId = call.id || call.call_id;
+    if (call.id) idAlias.set(call.id, pendingId);
+    if (call.call_id) idAlias.set(call.call_id, pendingId);
+    events.push({ kind: "tool", name, input, pendingId });
+  }
+}
+
+export async function read(ref) {
+  const db = await openReadOnly(dbPath());
+  if (!db) return { events: [], model: ref.model || null };
+
+  try {
+    const sessionId = ref.extra?.sessionId || ref.id;
+    const activeFilter = activeMessageFilter(db);
+    const rows = db
+      .prepare(
+        `SELECT role, CAST(content AS BLOB) AS content, tool_call_id, tool_calls, tool_name
+           FROM messages
+          WHERE session_id = ?${activeFilter}
+          ORDER BY timestamp, id`,
+      )
+      .all(sessionId);
+
+    const events = [];
+    const idAlias = new Map();
+    for (const row of rows) {
+      const role = row.role;
+      if (role === "session_meta") continue;
+      const content = decodeContent(row.content);
+      if (role === "user" || role === "assistant") {
+        contentToEvents(role, content, events);
+        if (role === "assistant") emitTools(row.tool_calls, events, idAlias);
+        continue;
+      }
+      if (role === "tool") {
+        events.push({
+          kind: "tool-result",
+          id: idAlias.get(row.tool_call_id) || row.tool_call_id,
+          result: content,
+          status: "completed",
+        });
+      }
+    }
+    return { events: attachToolResults(events), model: ref.model || null };
+  } catch {
+    return { events: [], model: ref.model || null };
+  } finally {
+    db.close();
+  }
+}

package/src/discovery/adapters/opencode.js

@@ -11,7 +11,7 @@ import { openReadOnly, safeJsonParse } from "./sqlite.js";
  *   message(id, session_id, data)     - data is JSON: {role, model, time, ...}
  *   part(id, message_id, session_id, data) - data is JSON: {type: text|tool|reasoning|...}
  *
- * This is the best-behaved store of the six: association is a SQL predicate on
+ * This is the best-behaved store: association is a SQL predicate on
  * `session.directory`, deleted worktrees included, and both listing and reading are
  * indexed. Older opencode versions used file storage under `storage/`; that layout is
  * handled as a fallback so long-lived machines still yield transcripts.

package/src/discovery/index.js

@@ -3,6 +3,7 @@ import * as codex from "./adapters/codex.js";
 import * as pi from "./adapters/pi.js";
 import * as grok from "./adapters/grok.js";
 import * as opencode from "./adapters/opencode.js";
+import * as hermes from "./adapters/hermes.js";
 import * as cursorCli from "./adapters/cursor-cli.js";
 import * as cursorIde from "./adapters/cursor-ide.js";
 
@@ -18,6 +19,7 @@ export const ADAPTERS = {
   pi,
   grok,
   opencode,
+  hermes,
   cursor: cursorCli,
   "cursor-ide": cursorIde,
 };
@@ -34,8 +36,8 @@ export function getAdapter(harness) {
  * Re-scans are then O(new files) - which matters: codex alone had 10,317 rollouts on
  * the machine this was designed against.
  *
- * SQLite-backed stores (opencode, cursor IDE) answer the same question with one indexed
- * query, so they skip the cache entirely.
+ * SQLite-backed stores (opencode, hermes, cursor IDE) answer the same question with one
+ * indexed query, so they skip the cache entirely.
  *
  * Every harness is fail-soft: a store that is missing, unreadable, or has drifted into
  * an unrecognised format produces a named warning and is skipped, never a failed run.

package/src/discovery/self.js

@@ -16,7 +16,7 @@ import { SELF_SESSION_SENTINEL } from "../prompts.js";
  *
  * The check reads only the head of the file and keys on the JSON-encoded user text as
  * every file-backed harness records it (`"text":"..."` / `"content":"..."` /
- * `"message":"..."`). SQLite-backed stores (opencode, cursor IDE) have no file to
+ * `"message":"..."`). SQLite-backed stores (opencode, hermes, cursor IDE) have no file to
  * inspect and acpx does not drive them, so they are passed through.
  */
 

package/src/tui/render.js

@@ -33,6 +33,7 @@ const HARNESS_HUES = {
   grok: "magenta",
   cursor: "blue",
   "cursor-ide": "blue",
+  hermes: "yellow",
 };
 
 /**
@@ -302,7 +303,7 @@ function discoverDetail(state, theme, width, spin) {
       const scanned = `${formatCount(h.scanned)} sessions`;
       const fresh = h.newCount > 0 || h.scanned > 0 ? ` · ${formatCount(h.newCount)} new` : "";
       const self = h.self > 0 ? ` · ${formatCount(h.self)} self` : "";
-      const query = harness === "opencode" ? "1 sqlite query" : `${scanned}${fresh}${self}`;
+      const query = harness === "opencode" || harness === "hermes" ? "1 sqlite query" : `${scanned}${fresh}${self}`;
       activity = theme.paint(fitPlain(query, activityWidth), "dim");
       count = padVis(
         `${theme.paint(formatCount(h.matched), "text", { bold: true })} ${theme.paint("this repo", "faint")}`,