Beagle SCM

BEE-027: ticket worktrees on the board — the $SRC_ROOT scan, the fsw rev tree, the per-wt status memo

The board (BEE-025) must show each ticket's WORKTREE: a file frame (the BEE-022 quad counts) and a commit frame (ahead/behind, current tip) on the row of the ticket the worktree is named for. Three pieces, rulings gritzko 2026-08-19: (1) the SCAN — every worktree lives under $SRC_ROOT as //parent-tail, parent a registered repo, so one readdir of $SRC_ROOT matched against the registry names finds them all, naming convention only; (2) the WATCHER — quickjab fsw over each worktree, be's shared/cache.js rev tree (STATUS-019) as the model; (3) the MEMO — the status model per worktree, in-process only, dropped WHOLE on ANY event under that tree, never persisted.

Input

Context

• Have: view/status.js (BEE-022) computes the quad + ahead/behind for ONE repo; it is the model this memoizes, untouched.
• Have: quickjab fsw.c (JAB-036): fsw.init() one watcher fd, fsw.dir arms a dir, drain packs (wd, len, name) records, wd -1 = kernel overflow; pol.run owns the blocking, so the pager/http loop is where events arrive.
• Have: be's shared/cache.js — the per-dir rev tree (an event stamps its dir and every ancestor; revs exist only under a live watcher; arming is lazy and lands on the query) and todo.js:476:4h wtIndex, :629 wtStat, :1009 _memoOn — the consumer shape.
• Have: BEE-026 creates the worktrees this finds: $SRC_ROOT/repo-TKT-123, branch TKT-123, submodules populated.
• Missing: bee has no watcher, no rev tree, no process-resident memo of any kind; every view recomputes per call.
• Missing: any notion of "the worktrees of a repo" beyond mount.js fold of registry lines (BEE-009).

Goals

• index/wts.js scan(): readdir $SRC_ROOT once per run; a dir whose basename is <name>-<tail> for the LONGEST registry name name and which holds a .git (file or dir) is a worktree { name, tail, root }; bee1, bee-BEE022 (no dash) are NOT found, and git worktree list is not consulted (ruling).
• index/cache.js: the rev tree over fsw — rev(dir) returns the rev stamped on a dir by the last event under it; an overflow or a failed drain bumps the ROOT (everything misses); no watcher ⇒ a fresh token per query (nothing memoizes); arming is lazy, on the query, before the caller computes; recursive over the worktree MINUS .git and gitignored dirs (igno).
• view/wtstat.js (or inside view/todo.js): per worktree { rev, model }, the BEE-022 status model; a HIT is rev(root) standing still; any event under the tree drops the whole entry (ruling: whole-wt drop, no per-block witnesses).
• The board row: <●> KEY ┄ title <file frame> <commit frame> for a ticket whose code is some worktree's tail; a worktree whose tail is no ticket code lists in a worktrees block of the board.
• Pager and http hold the memo for the process lifetime; a one-shot CLI run (bee todo --plain) computes everything once and memoizes nothing.
• The ahead/behind frame reads the tracked tip through index/refs.js as status does; a ref move under .git is NOT witnessed (unwatched) — the tip pair is a fingerprint checked on every render, be's tips precedent.

Constraints

• Memos exist ONLY under a live watcher; there is no persisted form and no mtime mark — a missed event is never read as truth (be ruling 3, reaffirmed).
• The scan is a naming convention, nothing else: no .git/worktrees reading, no registry edit, no auto-registration (BEE-009).
• .git is never armed (object churn); gitignored dirs (build/) are never armed, so the watch count stays under the kernel default; a tree too big to arm degrades to "no watcher" for that tree, not to a wrong answer.
• The status model is view/status.js's and is not forked; this ticket adds a memo and a frame renderer, not a second status.
• A nested repo (submodule worktree, BEE-026) is armed on its own first query and reaches the parent through the ancestor rule, as in be.

WIP

Design decisions

• RULED (gritzko 2026-08-19): status quad + ahead/behind per wt on the row; in-process memo, whole-wt drop, rev tree over fsw; $SRC_ROOT naming-convention scan only; own ticket, BEE-025 depends on it.
• The rev tree is generic infra (any view may memoize by it); the first consumer is the board, the next is bee http's status page.
• OPEN: the frame widths and glyphs — take be's (todo.js:721:4h FRAMEW_FILE 16, FRAMEW_COMMIT 13) or the BEE-022 quad vocabulary per column? Default: be's widths, BEE-022's glyphs.
  • Landed at that default, unruled: [v3 v1 v2 v5 !1] and [o2 o1 a1b2c], ASCII canon, POSITION naming the column as the quad's does.

TODOs

• index/wts.js scan() over $SRC_ROOT + registry names, longest prefix, .git probe
• index/cache.js: fsw init/arm/drain wiring into the pager and http loops, rev tree, overflow → root bump, lazy arming, igno + .git exclusion
• per-wt memo of the status model + the two frames; the tips fingerprint
• board rows and the worktrees block in view/todo.js; http — landed with BEE-025, the frames on a forked ticket's row and every other worktree in its own block
• test/wts/run.sh: scan fixtures (match, no-dash miss, dashed parent name, non-git dir), rev tree (event drops the wt, sibling stays, overflow drops all, no watcher = no memo), a board row after a wt edit
• README.mkd usage; INDEXES.mkd note that nothing here is persisted

Blockers and bummers

• Needs the fsw binding reachable from the bundled bee runtime (fsw.init etc.); verify in quickjab/API.md / jab.md first — if the bundle lacks it, that is a quickjab ticket.
• Blocked on BEE-023 for $SRC_ROOT and the registry names; the rev tree and the memo do not wait on it.

Outcome