feat(regent): integrate re_gent audit trail for AI agents (#73)

* feat: integrate regent for claude agents

* docs(regent): document

Author: mdelapenya

ARCHITECTURE.md

@@ -14,20 +14,23 @@ cmd/biomelab/
 
 internal/
   gui/
-    app.go             FyneApp: window, HSplit layout, multi-repo management, mode switching
-    dashboard.go       Right panel: main card + scrollable linked cards grid, refresh timestamps
-    card.go            Worktree card rendering: branch, path, PR, agents, IDEs, status
-    repo_panel.go      Left panel: tappable VBox of repo/mode items (NOT widget.Tree)
-    repo_panel_drag.go Drag-handle widget + reorder math for repo panel
-    shortcuts.go       All keyboard handling: handleKeyName + handleRune, navigation, operations
-    keycapture.go      desktop.Canvas.SetOnKeyDown setup, zoom shortcuts
-    dialogs.go         Confirmation dialogs (delete, sandbox create/remove, send PR flow)
-    input_dialogs.go   Input dialogs (branch, PR ref, repo path, agent select)
-    refresh.go         RefreshManager: goroutine tickers for local (5s) and network refresh
-    state.go           RepoState: domain + UI state, worktree sorting
-    theme.go           Dark theme with zoom support (Ctrl+/Ctrl-)
-    icon.go            AppIcon resource (set from embedded icon at startup)
-    systray.go         System tray: Show/Hide toggle, Quit
+    app.go                  FyneApp: window, HSplit layout, multi-repo management, mode switching
+    dashboard.go            Right panel: main card + scrollable linked cards grid, refresh timestamps
+    card.go                 Worktree card rendering: branch, path, PR, agents, IDEs, status
+    repo_panel.go           Left panel: tappable VBox of repo/mode items (NOT widget.Tree)
+    repo_panel_drag.go      Drag-handle widget + reorder math for repo panel
+    shortcuts.go            All keyboard handling: handleKeyName + handleRune, navigation, operations
+    keycapture.go           desktop.Canvas.SetOnKeyDown setup, zoom shortcuts
+    dialogs.go              Confirmation dialogs (delete, sandbox create/remove, send PR flow)
+    input_dialogs.go        Input dialogs (branch, PR ref, repo path, agent select)
+    refresh.go              RefreshManager: goroutine tickers for local (5s) and network refresh
+    state.go                RepoState: domain + UI state, worktree sorting
+    theme.go                Dark theme with zoom support (Ctrl+/Ctrl-)
+    icon.go                 AppIcon resource (set from embedded icon at startup)
+    systray.go              System tray: Show/Hide toggle, Quit, Dependencies summary
+    sysdeps_dialog.go       System Dependencies modal + first-run banner
+    regent_log_dialog.go    Regent activity window (single instance, resizable, JSON export)
+    save_file.go            OS-native save dialog (osascript/zenity/PowerShell) + Fyne fallback
 
   ops/
     refresh.go         QuickRefresh, LocalRefresh, NetworkRefresh, CardRefresh
@@ -36,6 +39,7 @@ internal/
 
   config/config.go     Repo list persistence (~/.config/biomelab/repos.json)
   git/worktree.go      Go-git v6 wrapper: list, create, remove, pull, fetch, sync status
+  git/exclude.go       Per-worktree git info/exclude writer (used by notes + regent)
   git/credential.go    Git credential helper protocol (git credential fill)
   agent/               Agent kind registry + process detection
   ide/                 IDE kind registry + process detection
@@ -44,6 +48,9 @@ internal/
   sandbox/sandbox.go   Docker Sandbox (sbx) CLI wrapper
   terminal/terminal.go Open new terminal window (macOS .command / Linux x-terminal-emulator)
   github/pr.go         GitHub-specific PR helpers (ParsePRRef, ValidatePR)
+  notes/notes.go       Per-worktree Markdown notes (.biomelab/note.md, pr-title.md)
+  regent/              re_gent (rgt) integration: detection, init, hook install, log fetch
+  sysdeps/             External CLI dependency checks (gh/glab/sbx/rgt) + cache
 ```
 
 ## Key dependencies
@@ -176,6 +183,80 @@ skill (and similar tools) target: write the generated title and description
 to those two paths, and biomelab turns them into the actual PR on the next
 `Shift+P`.
 
+## re_gent integration
+
+[re_gent](https://github.com/regent-vcs/re_gent) captures every agent turn
+(prompt, reply, tool calls) into a content-addressed `.regent/` directory
+per worktree. Biomelab wraps it so the integration is invisible until the
+user installs `rgt`:
+
+- **Auto-init on host worktrees.** `ops.CreateWorktree` runs
+  `regent.EnsureInit` after every new worktree creation, and
+  `app.buildRepoEntry` walks existing worktrees on startup
+  (`migrateRegentForRepo`) so an `rgt install` retroactively wires up
+  every regular-mode worktree on the next refresh. Sandbox worktrees
+  skip this path — rgt belongs inside the container, installed via the
+  regent kit.
+- **`EnsureInit` runs `rgt init --skip-hook --skip-skills`** with
+  `cmd.Dir = wtPath`. `rgt init` ignores positional path args and always
+  operates on `cwd`, so `cmd.Dir` is mandatory. The `--skip-hook` flag is
+  used because rgt's interactive installer needs a TTY biomelab can't
+  provide; we install Claude hooks ourselves.
+- **`EnsureClaudeHooks` writes `.claude/settings.json`** with three event
+  hooks (`UserPromptSubmit`, `Stop`, `PostToolBatch`) pointing at
+  `rgt message-hook` / `rgt tool-batch-hook`. Idempotent: rgt-related
+  entries are deduplicated on each call, non-rgt entries are preserved.
+  The JSON shape is ported from rgt's own installer
+  (`internal/cli/init.go`, Apache-2.0, attributed in source).
+- **Git exclude.** `git.EnsureExcluded` writes `/.regent/` (and
+  `/.biomelab/`) to the worktree's common `info/exclude` so neither
+  directory shows up in `git status`. Extracted to `internal/git` so
+  both `notes` and `regent` share one helper (used to live in `notes`,
+  caused a `git → notes` import that prevented `notes → git`).
+- **Log viewer.** `l` shortcut opens `regent_log_dialog.go`, a single
+  top-level resizable window. Content comes from `rgt log --json`
+  (parsed in `internal/regent/log_json.go`) and renders structured rows:
+  `sha · timestamp · origin`, `Human:` prompt, `Agent:` reply, then a
+  `▶ N tools` toggle that reveals one row per tool call with the
+  primary arg inline (file_path / command / query) and the rest below.
+  Full file paths, no truncation. Single window: pressing `l` on a
+  different card reuses the open window (`App.regentLogWindow` +
+  `regentLogReload`).
+- **JSON export.** The window's `Export JSON…` button calls
+  `regent.LogJSONRaw` and saves the bytes via the OS-native save dialog
+  helper (`gui/save_file.go`: osascript on macOS, zenity/kdialog on
+  Linux, PowerShell on Windows; falls back to `dialog.NewFileSave`).
+
+## System dependencies
+
+`internal/sysdeps` is the registry of external CLIs biomelab cares
+about. Each `Check` has a `Probe` that returns `Result{Status, Version,
+Note}`; a `Cache` (default TTL 30s) memoizes results across the systray
+menu, the dialog, and the first-run banner.
+
+Two filtering layers apply before rendering:
+
+- `ApplySuppression` drops `Missing` entries whose `SuppressIfAny` list
+  names another check that is currently `OK` or `Degraded`. Used so
+  `glab missing` doesn't appear when `gh` is installed.
+- `ApplyVisibility` drops `Missing` entries whose `Applies(cfg)` callback
+  says the tool isn't relevant. Used so `sbx` doesn't appear at all
+  when the user has no sandbox-mode repo. **Important:** `Applies`
+  gates visibility of missing entries only — installed tools always
+  show as green even when the user's config doesn't strictly need them.
+  That way `sbx v0.29.0` is reported correctly on machines where the
+  user just happens to have it.
+- `Partition` splits the surviving entries into a primary list and an
+  optional list (`Optional && Missing`). The dialog renders the
+  primary list at the top and the optional list (currently just `rgt`)
+  under an "Optional tools" heading.
+
+The systray label is `Dependencies: N/M ✓` (or
+`Dependencies: N/M (X need attention)`), where N/M counts only the
+visible primary entries. Clicking opens the dialog; the dialog's
+**Re-check** button invalidates the cache and refreshes the systray
+label in one call.
+
 ## Pitfalls
 
 - go-git v6 is a pseudo-version. Do NOT use a `replace` directive.
@@ -185,3 +266,7 @@ to those two paths, and biomelab turns them into the actual PR on the next
 - `widget.Button` implements Focusable — don't put buttons in the main content.
 - IDE `ProcessPatterns` order matters: specific before broad (`"nvim"` before `"vim"`).
 - Always bounds-check `a.active < len(a.repos)` before accessing repos.
+- `rgt init` ignores positional path args and operates on `cwd`. Use `cmd.Dir`, not `rgt init <path>`.
+- `rgt init` hook installer needs a TTY; biomelab writes `.claude/settings.json` itself via `regent.EnsureClaudeHooks`. Don't rely on `--agent claude` to skip the prompt — it doesn't.
+- `widget.Accordion` misbehaves inside `container.NewVScroll` (clicks don't toggle). Use a button + visibility toggle instead — see the regent log dialog's tools collapsible.
+- The shared regent log window is keyed by `App.regentLogWindow` (single instance). Don't spawn a new window per worktree; reuse via `regentLogReload`.

CLAUDE.md

@@ -39,23 +39,29 @@ Go version: 1.25+ (check `go env GOROOT` if you hit version mismatches).
 - **go-git v6** (unreleased, from main branch) -- All git operations.
 - **gopsutil** -- Cross-platform process detection.
 - **gh CLI / glab CLI** -- External tools for PR/MR status.
+- **rgt CLI** ([re_gent](https://github.com/regent-vcs/re_gent)) -- Optional. When installed, biomelab auto-initializes `.regent/` per worktree and wires Claude Code hooks.
 
 ## Package layout
 
 ```
 cmd/biomelab/          Entry point, icon embedding, PATH expansion
 internal/
   gui/                 Fyne GUI: app, dashboard, cards, repo panel, dialogs,
-                       keyboard handling, theme, refresh manager, system tray
+                       keyboard handling, theme, refresh manager, system tray,
+                       sysdeps dialog + banner, regent log window, OS-native
+                       save dialog helper
   ops/                 Shared business operations (refresh, worktree CRUD,
                        sandbox ops) — extracted from old TUI for reuse
   config/              Repo list persistence (~/.config/biomelab/repos.json)
-  git/                 Go-git v6 wrapper
+  git/                 Go-git v6 wrapper + EnsureExcluded helper
   agent/               Agent process detection
   ide/                 IDE process detection
   process/             Shared process enumeration
   provider/            PR/MR provider abstraction (GitHub, GitLab)
   sandbox/             Docker Sandbox (sbx) CLI wrapper
+  notes/               Per-worktree Markdown notes (.biomelab/note.md)
+  regent/              re_gent (rgt) integration: detect, init, hooks, log
+  sysdeps/             External CLI dependency checks (gh/glab/sbx/rgt)
   terminal/            Open new terminal window
   github/              GitHub-specific PR helpers
 ```
@@ -88,6 +94,17 @@ Always run `go test -race ./...`.
   prefix truncation (`truncatePath`), PR text uses suffix truncation.
 - **Card grid navigation** — up/down jump by column count, left/right by 1.
   Column count computed from `dashSlot.Size().Width / cardCellSize().Width`.
+- **`rgt init` ignores positional path args** — it always operates on `cwd`.
+  Use `cmd.Dir = wtPath`, not `rgt init <wtPath>`.
+- **rgt hook installer needs a TTY** — `--agent claude` doesn't skip the
+  prompt in a non-TTY environment. Biomelab writes `.claude/settings.json`
+  itself via `regent.EnsureClaudeHooks` (ported from rgt upstream, Apache-2.0).
+- **`widget.Accordion` misbehaves inside `VScroll`** — clicks don't toggle.
+  Use a `widget.Button` that flips the inner container's visibility instead;
+  see the regent log dialog's tools collapsible for the pattern.
+- **One regent log window at a time** — keyed by `App.regentLogWindow` plus
+  a `regentLogReload` closure. Different cards reuse the same window via
+  reload; don't spawn a new one per worktree.
 
 ## Release process
 

README.md

@@ -22,6 +22,8 @@
 - **Open in terminal** -- Press `Enter` to open a worktree in a terminal. If a terminal is already detected for that worktree, it is brought to the foreground instead of opening a new one. On macOS, activation uses TTY matching via AppleScript (requires Automation permission on first use).
 - **Open in editor** -- Press `e` to open in `$BIOME_EDITOR` (defaults to VS Code).
 - **Task notes** -- Press `m` (or right-click a card) to open a Markdown editor with a live preview, scoped to that worktree. Notes are stored at `<worktree>/.biomelab/note.md` (description) and `<worktree>/.biomelab/pr-title.md` (single-line title), auto-excluded from git, and mounted into the sandbox alongside the source so agents can read them. When you `Shift+P` to send a PR, biomelab offers to use the prepared title and description in place of the commit-derived defaults. External tools that write to those two paths become contributors to the next PR.
+- **Agent audit trail** ([re_gent](https://github.com/regent-vcs/re_gent)) -- When `rgt` is installed, biomelab auto-initializes `.regent/` in every regular-mode worktree and writes Claude Code hooks into `.claude/settings.json` — no terminal step. Press `l` (or systray → Dependencies) to open the activity window: one resizable view per session with `Human` / `Agent` rows, collapsible tool lists (full file paths, no truncation), and an **Export JSON…** button that writes the raw `rgt log --json` via the OS-native save dialog.
+- **System dependencies dialog** -- Systray entry (`Dependencies: N/M ✓`) opens a modal listing every external CLI biomelab relies on (`gh`, `glab`, `sbx`, `rgt`) with status dot, version, install hint, and docs link. A first-run banner above the dashboard nags only when a primary tool is missing or degraded; redundant CLIs (e.g. `glab` when `gh` is fine) are suppressed.
 - **Zoom** -- `Ctrl+=` / `Ctrl+-` / `Ctrl+0` to scale the UI font.
 - **System tray** -- Closing the window hides to system tray. Tray menu toggles Show/Hide.
 - **Auto-refresh** -- Local state refreshes every 5s, network state every 30s (configurable).
@@ -126,6 +128,7 @@ Launch `biomelab` from any directory, or open `Biomelab.app` from Spotlight/Find
 | `Enter` | Activate existing terminal or open new | Any card |
 | `e` | Open in editor | Any card |
 | `m` | Open note editor (right-click also works) | Any card |
+| `l` | Open regent activity log | Any card |
 | `c` | Create worktree | Main card |
 | `f` | Fetch PR/MR | Main card |
 | `d` | Delete worktree / remove sandbox | Linked: delete; Main+sandbox: remove |
@@ -136,6 +139,9 @@ Launch `biomelab` from any directory, or open `Biomelab.app` from Spotlight/Find
 | `s` | Start stopped sandbox | Main card |
 | `Shift+S` | Stop running sandbox | Main card |
 | `k` | Pick kits → create (if missing) or recreate sandbox with `--kit` flags | Sandbox mode |
+| `g` | Toggle kanban / grid view | Global |
+| `Tab` | Toggle focus between panels | Global |
+| `Ctrl+T` | Toggle dark / light theme | Global |
 | `Ctrl+=` | Zoom in | Global |
 | `Ctrl+-` | Zoom out | Global |
 | `Ctrl+0` | Reset zoom | Global |

internal/git/exclude.go

@@ -0,0 +1,111 @@
+package git
+
+import (
+	"bufio"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// excludeDirPerm and excludeFilePerm are the standard git info/exclude
+// file permissions (mirrors what `git worktree add` produces).
+const (
+	excludeDirPerm  = 0o755
+	excludeFilePerm = 0o644
+)
+
+// EnsureExcluded appends line to the worktree's info/exclude file if it
+// isn't already present. Idempotent. Used by sidecar packages (notes,
+// regent) to hide per-worktree directories from `git status`.
+//
+// Git reads info/exclude from the common gitdir for both the main worktree
+// and any linked worktrees — the per-worktree
+// .git/worktrees/<name>/info/exclude is created by `git worktree add` but
+// is not honored by `git status` (verified empirically). This function
+// resolves the right file in both cases:
+//
+//   - main worktree: .git is a directory → <wt>/.git/info/exclude
+//   - linked worktree: .git is a file with "gitdir: <wt-gitdir>" → read
+//     <wt-gitdir>/commondir to find the common gitdir, then
+//     <common-gitdir>/info/exclude.
+//
+// As a side effect, all worktrees of a repo share the same exclude file.
+// Patterns are anchored to the worktree root at match time (e.g.
+// "/.regent/"), so each worktree's own sidecar dir stays hidden.
+func EnsureExcluded(worktreeDir, line string) error {
+	excludePath, err := excludeFilePath(worktreeDir)
+	if err != nil {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Dir(excludePath), excludeDirPerm); err != nil {
+		return fmt.Errorf("create info dir: %w", err)
+	}
+	existing, err := os.ReadFile(excludePath)
+	if err != nil && !errors.Is(err, os.ErrNotExist) {
+		return fmt.Errorf("read exclude: %w", err)
+	}
+	if hasExcludeLine(existing, line) {
+		return nil
+	}
+	f, err := os.OpenFile(excludePath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, excludeFilePerm)
+	if err != nil {
+		return fmt.Errorf("open exclude: %w", err)
+	}
+	var buf strings.Builder
+	if len(existing) > 0 && !strings.HasSuffix(string(existing), "\n") {
+		buf.WriteString("\n")
+	}
+	buf.WriteString(line)
+	buf.WriteString("\n")
+	if _, werr := f.WriteString(buf.String()); werr != nil {
+		_ = f.Close()
+		return fmt.Errorf("write exclude: %w", werr)
+	}
+	if cerr := f.Close(); cerr != nil {
+		return fmt.Errorf("close exclude: %w", cerr)
+	}
+	return nil
+}
+
+func excludeFilePath(worktreeDir string) (string, error) {
+	gitPath := filepath.Join(worktreeDir, ".git")
+	info, err := os.Stat(gitPath)
+	if err != nil {
+		return "", fmt.Errorf("stat .git: %w", err)
+	}
+	if info.IsDir() {
+		return filepath.Join(gitPath, "info", "exclude"), nil
+	}
+	data, err := os.ReadFile(gitPath)
+	if err != nil {
+		return "", fmt.Errorf("read .git: %w", err)
+	}
+	const prefix = "gitdir:"
+	line := strings.TrimSpace(string(data))
+	if !strings.HasPrefix(line, prefix) {
+		return "", fmt.Errorf(".git file missing %q prefix", prefix)
+	}
+	wtGitDir := strings.TrimSpace(strings.TrimPrefix(line, prefix))
+
+	commonDir := wtGitDir
+	if raw, rerr := os.ReadFile(filepath.Join(wtGitDir, "commondir")); rerr == nil {
+		cd := strings.TrimSpace(string(raw))
+		if !filepath.IsAbs(cd) {
+			cd = filepath.Join(wtGitDir, cd)
+		}
+		commonDir = filepath.Clean(cd)
+	}
+	return filepath.Join(commonDir, "info", "exclude"), nil
+}
+
+func hasExcludeLine(content []byte, line string) bool {
+	scanner := bufio.NewScanner(strings.NewReader(string(content)))
+	for scanner.Scan() {
+		if strings.TrimSpace(scanner.Text()) == line {
+			return true
+		}
+	}
+	return false
+}

internal/git/worktree.go

@@ -18,8 +18,14 @@ import (
 	"github.com/go-git/go-git/v6/plumbing"
 	githttp "github.com/go-git/go-git/v6/plumbing/transport/http"
 	xworktree "github.com/go-git/go-git/v6/x/plumbing/worktree"
+)
 
-	"github.com/mdelapenya/biomelab/internal/notes"
+// biomelabDir is the per-worktree sidecar directory that biomelab uses
+// to store notes, PR drafts, and other transient state. Kept under the
+// worktree so it travels with the sandbox bind mount.
+const (
+	biomelabDir         = ".biomelab"
+	biomelabExcludeLine = "/.biomelab/"
 )
 
 // SyncStatus indicates whether a branch is up-to-date with its remote tracking branch.
@@ -991,10 +997,15 @@ func (r *Repository) HasStash() (bool, error) {
 }
 
 // ensureBiomelabDir ensures the .biomelab directory exists in the given
-// worktree path so external tools can write files without creating it themselves.
+// worktree path and that it's git-excluded. External tools (pr-scribe,
+// note editor) write files inside without needing to create the directory
+// themselves, and the entries never show up in `git status`.
 // Errors are silently ignored as this is a best-effort initialization.
 func (r *Repository) ensureBiomelabDir(wtPath string) error {
-	return notes.EnsureDir(wtPath)
+	if err := os.MkdirAll(filepath.Join(wtPath, biomelabDir), 0o755); err != nil {
+		return err
+	}
+	return EnsureExcluded(wtPath, biomelabExcludeLine)
 }
 
 // MigrateWorktreeDirs ensures .biomelab exists for all worktrees in the