geneseed 3.12.0 → 3.13.0

package/docs/web-ui.md

@@ -111,27 +111,47 @@ streams the output of background jobs and keeps their history across reloads.
   **Promote to rule** control turns a recurring lesson into a trial rule in
   `user-rules.md` — provenance recorded, the source fact deleted so it isn't loaded
   twice — landing you on the Rules page.
-- **Loops** (`#/loops`) — the loop catalogue `geneseed loop` runs from, read-only.
-  **Templates** draws the selected template as a ring: the iteration turning clockwise from
-  its head, each inner retry loop hung outside on its head node, the ⛨ *validate* gate the
-  engine adds before the first mutate step, setup entering from the left and `done → close`
-  leaving from the head; a card per brick sits under it, and clicking a node scrolls to its
-  card. A graph a ring cannot draw cleanly (more than eight iteration steps, a node in more
-  than three loops) falls back to left-to-right boxes. **Bricks** lists every brick with its
-  origin (shipped / global / project), what it overrides, why it is unavailable, and its
-  source. **Active** (live runs) is announced for v2 and disabled. Reads `GET /api/loops`,
-  resolved from the selected install's root, so a project install shows its
-  `.geneseed/` bricks and templates.
+- **Loops** (`#/loops`) — the loop catalogue `geneseed loop` runs from, read-only, laid out
+  like the Library: a rail of sections (**Templates**, **Bricks**, **Active**, each with its
+  count; `#/loops/<section>/<item>` opens an entry), with the selected section's groups
+  nested under it in the rail (template categories, brick origins, run statuses — pick one to
+  narrow the list), a filterable list, and a reader.
+  **Templates** are grouped by their `category` (architecture, tests, development,
+  refactoring, day-to-day, then *Other*), a *human gate* pill on any that stops for you. The
+  reader draws the selected template as a ring: the iteration turning clockwise from its head,
+  each inner retry loop hung outside on its head node, the ⛨ *validate* gate the engine adds
+  before the first mutate step, setup entering from the left and `done → close` leaving from
+  the head; its `rules` follow, then a compact row per brick (effect, agent or skill, outcomes,
+  human gate), and clicking a node scrolls to and lights its row. A graph a ring cannot draw
+  cleanly (more than eight iteration steps, a node in more than three loops) falls back to
+  left-to-right boxes. **Bricks** are grouped by origin (project / global / shipped), pilled
+  for *mutate*, *human gate*, what they override and *unavailable*; the reader shows the
+  frontmatter facts (outcomes as pills, availability with its reason), then the body rendered as
+  markdown, with a **View source** toggle for the file as parsed, frontmatter and all. Templates and
+  Bricks read `GET /api/loops`, resolved from the selected install's root, so a project
+  install shows its `.geneseed/` bricks and templates. **Active** is every loop
+  `geneseed loop init` registered on this machine (`GET /api/loops/active`, polled every
+  5 s), grouped awaiting, running, done/stopped, finished/unreadable; the reader shows its
+  branch, `iteration N / max`, current node and a preset picker (`POST /api/loops/preset`,
+  the page's only write), what an awaiting loop waits on (launch / declared / actual / a
+  human gate, with its node) — the answer is given in the agent's session, never here — and
+  its ring with the current node filled, with its iteration history under it.
 - **Profile** (`#/profile`) — `PROFILE.md` beside the deployed AGENT.md: who you are and
   how you like to work. Opens rendered; **Edit** is a whole-file editor. The save carries
   the fingerprint it loaded — if an agent session changed the file first, your edit stays
   on screen and a second Save replaces the newer version.
 - **Skills** (`#/skills`) and **Agents** (`#/agents`) — the deployed catalogue, each entry
-  with its purpose line and full spec.
+  with its purpose line and full spec. While Skills is selected, its skill types sit nested
+  under it in the rail, each with its count, above a thin bar of their shares; pick one to
+  narrow the list.
 - **Docs** (`#/docs`) — rendered documentation: markdown pages, concept pages, a CLI
-  reference (generated from the harness argument parser), and a glossary, grouped into
-  Get started / Core concepts / How-to / MCP servers / Plugins / Reference / Deeper. Filtered
-  for one host family (OpenCode, or Claude Code — which Bob and OpenClaude share); with no
+  reference (generated from the harness argument parser), and a glossary, in the Library's
+  three panes: the parts (Understand / Guides / Concepts / Reference) with their page counts,
+  the open part's sections nested under it in the rail (pick one to narrow the list), the
+  part's pages under their sections with a filter, and the page with its breadcrumb,
+  outline and Previous / Next within the section. Filtered for one host (OpenCode, Claude
+  Code, Bob or OpenClaude; Claude-family pages show to all three Claude-engine hosts, a page
+  tagged with a list of hosts only to those); with no
   choice stored it follows the deployed install.
 
 ### 🩺 Care

package/harness.config.json

@@ -2,5 +2,5 @@
   "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
   "theme": "neutral",
   "product": "Geneseed",
-  "version": "3.12.0"
+  "version": "3.13.0"
 }

package/js/README.md

@@ -140,12 +140,20 @@ transition, score and stop is computed here.
 | `catalog.mjs` | `loadCatalog` — bricks and loop templates from shipped/global/project origins, later overrides earlier BY NAME |
 | `state.mjs` | The engine itself: `initState`, `nextStep`, `scoreDeclared`/`scoreDiff`, `recordOutcome`, `decideAwaiting`, `renderLoopFile`/`parseLoopFile` |
 | `cli.mjs` | `geneseed loop check\|init\|next\|score\|record\|decide` — the only face either a model or a human reaches this engine through |
+| `registry.mjs` | `loops.json` under XDG — the launched-loop identity list `loop init` records into and the Active tab's `activeLoops`/`setLoopPreset` read and rewrite |
 
 **Before editing:** `score.mjs` is imported by the build driver (the `--trust` choices), so it must
 stay free of every import but node builtins and `graph.mjs`. `state.mjs` excludes `LOOP.md` itself
-from every score and every read-brick porcelain check — it is the engine's own bookkeeping, never
-part of the work being scored. `cli.mjs` may not spawn: git output is piped in on stdin by the
-model, never read by this entry.
+(and its own atomic-write sibling, `LOOP.md.tmp`) from every score and every read-brick porcelain
+check — it is the engine's own bookkeeping, never part of the work being scored. Every LOOP.md
+write goes through `state.mjs`'s `writeLoopFile`, never a bare `writeText`, so a killed process
+cannot leave a torn file. `cli.mjs` may not spawn: git output is piped in on stdin by the model,
+never read by this entry. `registry.mjs` swallows its own errors on `recordLoop`/`activeLoops` on
+purpose, like `js/inspect/registry.mjs` — a registry hiccup must never fail `loop init` or a
+read — but `setLoopPreset` does not: a preset change the caller asked for must be reported when it
+fails. `activeLoops` saves the registry back only when the kept set actually changed (a pruned
+root, a loop newly seen finished or seen running again) — a routine poll from the Active tab must
+never be a write.
 
 ## `js/maintain/` — lifecycle
 

package/js/cli-table.json

@@ -734,6 +734,19 @@
           "type": null,
           "hidden": false
         },
+        {
+          "names": ["--contracts"],
+          "dest": "contracts",
+          "metavar": null,
+          "help": "comma-separated contract globs appended to the template's own (init)",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
         {
           "names": ["--declared"],
           "dest": "declared",
@@ -846,7 +859,20 @@
           "names": ["--note"],
           "dest": "note",
           "metavar": null,
-          "help": "a note attached to the verdict, written into LOOP.md",
+          "help": "a note attached to a record or a decide verdict, written into LOOP.md so it survives the unit",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--note-file"],
+          "dest": "note_file",
+          "metavar": null,
+          "help": "record's note read from this file instead of the command line (CRLF folded, trimmed) — for a multi-line note or one that mentions git commit/push",
           "choices": null,
           "default": null,
           "required": false,

package/js/hosts/mcp.mjs

@@ -68,7 +68,7 @@ export const MCP_PRESETS = {
       + 'install). Edit GITLAB_PERSONAL_ACCESS_TOKEN (scopes: api, read_repository) '
       + 'and GITLAB_API_URL before use. For a second instance (a self-hosted server), '
       + 'copy this block by hand under a new name and point it at the other URL — '
-      + 'docs/guides/mcp.md has the pattern.',
+      + 'docs/guides/mcp-gitlab.md has the pattern.',
     block: {
       type: 'local',
       command: ['npx', '-y', '@zereight/mcp-gitlab'],

package/js/hosts/native.mjs

@@ -149,12 +149,50 @@ function triggerOf(text) {
  * 900-char cap the catalogue weighed 22k chars (~5.6k tokens) across 51 skills, three times
  * the figure the footprint page quoted. The first sentence says WHEN; the later sentences
  * disambiguate, and the body — read as soon as the skill is chosen — still carries them.
- * Cut at the last sentence end inside the cap, never mid-word.
+ * Cut at the last sentence end inside the cap, never mid-word. The `…` fallback (no sentence
+ * end inside the cap) is a truncated routing signal: `checkBuild` reports it as a doctor
+ * failure, so the cure is a shorter first trigger sentence in the source, never a wider cap.
  */
 const DESCRIPTION_CAP = 320;
 function skillDescription(text) {
-  const desc = descOf(text);
-  const trig = triggerOf(text);
+  return withWhen(descOf(text), triggerOf(text));
+}
+
+/**
+ * The `## When to dispatch` section's FIRST bullet, flattened like `triggerOf` — the agent's
+ * WHEN. Claude Code delegates on the subagent `description:` alone, and a purpose line
+ * ("Writes, runs, and diagnoses tests.") says what an agent does but never when to hand it
+ * work; the dispatch list carried that, in a body the router never reads.
+ */
+function dispatchOf(text) {
+  const lines = text.split('\n');
+  const start = lines.findIndex((ln) => /^##\s+When to dispatch\b/.test(ln.trim()));
+  if (start < 0) return '';
+  const para = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const s = lines[i].trim();
+    if (!para.length) {
+      if (s.startsWith('- ')) para.push(s.slice(2));
+      else if (s.startsWith('#')) break;
+      continue;
+    }
+    if (s === '' || s.startsWith('- ') || s.startsWith('#')) break;
+    para.push(s);
+  }
+  return para.join(' ')
+    .replace(HTML_COMMENT_RE, '')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** The emitted `description:` of an agent — purpose + its first dispatch condition. */
+export function agentDescription(text) {
+  return withWhen(descOf(text), dispatchOf(text));
+}
+
+/** Purpose + ` Use when: ` + the first sentence of `trig`, capped — see `skillDescription`. */
+function withWhen(desc, trig) {
   if (!trig) return desc;
   const first = trig.match(/^.*?[.;](?=\s|$)/);
   const full = `${desc} Use when: ${first ? first[0] : trig}`;
@@ -302,7 +340,7 @@ const WEBFETCH_MARKER = '<!-- webfetch: allow -->';
  * Bash keeps the unmarked line byte-identical to what it was before the webfetch marker existed.
  */
 function claudeAgentFrontmatter(stem, text, overrides) {
-  const fm = [`name: ${stem}`, `description: ${jsonDumps(descOf(text))}`];
+  const fm = [`name: ${stem}`, `description: ${jsonDumps(agentDescription(text))}`];
   const ov = agentOverride(overrides, stem);
   if (isTruthy(ov.model)) fm.push(`model: ${formatValue(ov.model)}`);
   if (isReadonly(text)) {
@@ -316,7 +354,7 @@ function claudeAgentFrontmatter(stem, text, overrides) {
 
 /** `_build_emit._opencode_agent_frontmatter`. */
 function opencodeAgentFrontmatter(stem, text, overrides, theme = null) {
-  const fm = [`description: ${jsonDumps(descOf(text))}`, 'mode: subagent'];
+  const fm = [`description: ${jsonDumps(agentDescription(text))}`, 'mode: subagent'];
   fm.push(`color: ${agentColor(stem, theme)}`);
   pushOverrideLines(fm, agentOverride(overrides, stem));
   if (isReadonly(text)) {

package/js/inspect/checks-build.mjs

@@ -81,6 +81,34 @@ export function checkBuild(themeName, out, isVendored = isVendoredPath) {
       problems.push(`[${themeName}] unresolved token ${tok} in ${rel}`);
     }
     for (const p of linkProblems(md, text, outAbs, rel)) problems.push(`[${themeName}] ${p}`);
+    for (const p of descriptionProblems(text, rel)) problems.push(`[${themeName}] ${p}`);
+  }
+  return problems;
+}
+
+/**
+ * The `description:` of an emitted native skill or agent, held to Anthropic's skill-authoring
+ * rules — it is the ONLY text a host routes on, so a defect here is a skill that silently
+ * never fires. Three arms: a `…` ending is `withWhen`'s mid-sentence fallback (the trigger
+ * was cut, cure it with a shorter first trigger sentence); an XML-looking tag is rejected
+ * outright by the Agent Skills spec; a first/second-person pronoun is the point-of-view drift
+ * the spec warns degrades discovery, since the text is injected into the system prompt.
+ * The pronoun arm reads only the `Use when:` half, and skips quoted user phrases ("teach me
+ * X" is what the user types, not the description's voice): the purpose half is the theme's
+ * persona copy ("Make your own OpenCode theme"), authored per theme on purpose.
+ * Files without frontmatter (every bundle `.md`, AGENT.md) carry no description and pass.
+ */
+const DESC_LINE_RE = /^---\n(?:.*\n)*?description: (".*")\n(?:.*\n)*?---\n/;
+export function descriptionProblems(text, rel) {
+  const m = text.match(DESC_LINE_RE);
+  if (!m) return [];
+  const desc = parseJson(m[1]);
+  const problems = [];
+  if (desc.endsWith('…')) problems.push(`description cut mid-sentence in ${rel} — shorten the first trigger sentence`);
+  if (/<\/?[A-Za-z][^>]*>/.test(desc)) problems.push(`description carries an XML-like tag in ${rel}`);
+  const when = desc.split(' Use when: ')[1] ?? '';
+  if (/\b(I|I'm|me|my|you|you're|your)\b/i.test(when.replace(/"[^"]*"|\bI\/O\b/g, ''))) {
+    problems.push(`description's "Use when" is not in the third person in ${rel}`);
   }
   return problems;
 }

package/js/loop/catalog.mjs

@@ -47,8 +47,19 @@ export function parseBrick(text, origin) {
   if (!agent === !skill) problems.push(`${name}: exactly one of agent or skill`);
   const outcomes = get('outcomes').split(',').map((s) => s.trim()).filter(Boolean);
   if (!outcomes.length) problems.push(`${name}: outcomes is empty`);
+  // `gate: human` holds the transition after this brick until the user answers (state.mjs).
+  // Present on the brick only when declared, so an ungated brick's shape is unchanged.
+  const gate = get('gate');
+  if (gate && gate !== 'human') problems.push(`${name}: gate must be human, not ${JSON.stringify(gate)}`);
+  // `gateOn` narrows the gate to the outcomes it lists; any other outcome follows its edge ungated.
+  const gateOn = get('gateOn').split(',').map((s) => s.trim()).filter(Boolean);
+  if (gateOn.length && gate !== 'human') problems.push(`${name}: gateOn needs gate: human`);
+  for (const o of gateOn) if (!outcomes.includes(o)) problems.push(`${name}: gateOn ${o} is not one of its outcomes`);
   return {
-    brick: { name, description, effect, agent, skill, outcomes, body: body.trim(), origin },
+    brick: {
+      name, description, effect, agent, skill, outcomes, ...(gate ? { gate } : {}),
+      ...(gateOn.length ? { gateOn } : {}), body: body.trim(), origin,
+    },
     problems,
   };
 }

package/js/loop/cli.mjs

@@ -22,8 +22,9 @@ import { parseNumstat, DEFAULT_PRESET } from './score.mjs';
 import { gitRootOf, gitDirOf, currentBranch } from '../hosts/gitref.mjs';
 import {
   initState, nextStep, scoreDeclared, scoreDiff, recordOutcome, decideAwaiting,
-  renderLoopFile, parseLoopFile, LOOP_FILE,
+  writeLoopFile, parseLoopFile, LOOP_FILE,
 } from './state.mjs';
+import { recordLoop } from './registry.mjs';
 
 const emit = (obj) => { printOut(`${JSON.stringify(obj)}\n`); return obj.error || obj.ok === false ? 1 : 0; };
 const stdin = () => (process.stdin.isTTY ? '' : readFileSync(0, 'utf8'));
@@ -64,7 +65,7 @@ function withState(fn) {
   const state = parseLoopFile(readText(file));
   const { bricks } = loadCatalog({ projectRoot: root });
   const result = fn(state, bricks);
-  writeText(file, renderLoopFile(state));
+  writeLoopFile(file, state);
   return result;
 }
 
@@ -110,8 +111,14 @@ const ACTIONS = {
     const graph = resolveGraph(args.graph, catalog);
     const problems = checkGraph(graph, catalog.bricks);
     if (problems.length) return { error: 'the graph does not pass loop check', problems };
-    const state = initState({ title: args.title, requirement: args.requirement, graph, preset: args.preset || DEFAULT_PRESET });
-    writeText(file, renderLoopFile(state));
+    const state = initState({
+      title: args.title, requirement: args.requirement, graph, preset: args.preset || DEFAULT_PRESET,
+      contracts: list(args.contracts) ?? [],
+    });
+    writeLoopFile(file, state);
+    // Best-effort: the registry is how the Active tab discovers this loop, but a registry
+    // hiccup must never fail the init the loop itself just succeeded at.
+    recordLoop({ root, branch: currentBranch(root), title: args.title });
     return { file, graph: graph.name, preset: state.preset, status: state.status };
   },
   next: () => withState((s, b) => nextStep(s, b)),
@@ -130,9 +137,24 @@ const ACTIONS = {
   },
   record(args) {
     if (!args.outcome) throw new Error('record needs --outcome');
+    if (args.note && args.noteFile) throw new Error('record takes --note or --note-file, not both');
+    let note = args.note ?? '';
+    if (args.noteFile) {
+      // A note too long for a shell argument, or one that mentions `git … commit`/`push` (and
+      // would otherwise sit inside the command line GIT_GATE_RE matches whole), goes through a
+      // file instead — never through the shell at all. CRLF-folded and trimmed the same way the
+      // porcelain stdin below is, so a Windows-authored file round-trips identically.
+      let raw;
+      try { raw = readText(path.resolve(args.noteFile)); } catch (e) {
+        throw new Error(`cannot read --note-file ${args.noteFile}: ${e.message}`, { cause: e });
+      }
+      note = raw.replace(/\r\n/g, '\n').trimEnd();
+    }
     const card = args.card ? JSON.parse(args.card) : null;
-    const raw = stdin();
-    return withState((s, b) => recordOutcome(s, b, args.outcome, { card, porcelain: raw ? raw.replace(/\r\n/g, '\n').trimEnd() : null }));
+    const porcelain = stdin();
+    return withState((s, b) => recordOutcome(s, b, args.outcome, {
+      card, porcelain: porcelain ? porcelain.replace(/\r\n/g, '\n').trimEnd() : null, note,
+    }));
   },
   decide(args) {
     // X6: same ordering as `score --diff` above.

package/js/loop/graph.mjs

@@ -23,6 +23,8 @@ import { WEIGHTS } from './score.mjs';
 
 export const TERMINALS = new Set(['$close', '$stop']);
 export const ENGINE_MAX_ITERATIONS = 20;
+/** A template's optional `category`, in the order the console's Loops list shows them. */
+export const CATEGORIES = ['architecture', 'tests', 'development', 'refactoring', 'day-to-day'];
 
 export function iterationLoop(graph) {
   return (graph.loops ?? []).find((l) => l.iteration === true);
@@ -141,5 +143,21 @@ export function checkGraph(graph, bricks) {
   for (const k of Object.keys(graph.weights ?? {})) {
     if (!Object.hasOwn(WEIGHTS, k)) problems.push(`weights: ${k} is not an action`);
   }
+  // optional glob lists (score.mjs's `globMatch` reads them)
+  for (const k of ['contracts', 'ignoreDeletions']) {
+    const v = graph[k];
+    if (v !== undefined && !(Array.isArray(v) && v.every((g) => typeof g === 'string' && g.trim()))) {
+      problems.push(`${k}: must be a list of non-empty glob strings`);
+    }
+  }
+  // optional instruction list every brick receives through `loop next`
+  const rules = graph.rules;
+  if (rules !== undefined && !(Array.isArray(rules) && rules.every((r) => typeof r === 'string' && r.trim()))) {
+    problems.push('rules: must be a list of non-empty strings');
+  }
+  // optional catalogue shelf: the console groups templates by it, an absent one under OTHER
+  if (graph.category !== undefined && !CATEGORIES.includes(graph.category)) {
+    problems.push(`category: must be one of ${CATEGORIES.join(', ')}`);
+  }
   return problems;
 }

package/js/loop/registry.mjs

@@ -0,0 +1,196 @@
+/**
+ * The loop registry — `<userLoopsDir()>/loops.json` — the list of worktrees `geneseed loop init`
+ * has launched a loop in. `LOOP.md` stays the only source of loop STATE; this file stores
+ * identity only (root, branch, title, started, finishedAt), so the Active tab can discover a
+ * loop without scanning every worktree on the machine.
+ *
+ * WRITER CONVENTIONS, mirrored from `js/inspect/registry.mjs` (`installs.json`'s own registry)
+ * on purpose rather than invented fresh: `jsonDumpsIndent` because these rows are absolute
+ * paths and a username carrying an accent writes one here (ensure_ascii matters); a
+ * `<file>.tmp` + `renameSync` so a crash mid-write cannot leave `loops.json` half-written where
+ * the NEXT read would see valid-but-truncated JSON instead of either the old file or the new
+ * one; and every public function swallows its own errors — a registry hiccup must never fail
+ * `loop init`, and a corrupt `loops.json` must read back as empty rather than throw. The one
+ * difference from `installs.json`: this file keys rows by object (`{root, branch, title,
+ * started, finishedAt}`), not by a bare path, because identity alone is not enough to render a
+ * card.
+ *
+ * NO `lastSeen`. The Active tab POLLS `activeLoops` on an interval, and a field refreshed on
+ * every read would make every poll a write — fine for `installs.json` (`record` fires once per
+ * emit), wrong here (the page's own `usePoll` fires every few seconds, for as long as the tab
+ * is open, on a machine that may be a laptop on battery). So `activeLoops` saves the registry
+ * back ONLY when the kept set actually differs from what it loaded — a root pruned, a loop
+ * newly seen finished, or a loop seen running again after having been finished — never merely
+ * to record that a poll happened. `finishedAt` replaces `lastSeen` for the one thing a
+ * timestamp was doing here: it is set ONCE, the first time a row is found WITHOUT a LOOP.md
+ * (the loop finished), and the 7-day prune window counts from there — not from a last-poll time
+ * nothing refreshes any more. A loop seen running again afterwards (the same worktree
+ * re-`init`ed) clears it, so a stale finished-window never survives into a loop that is running
+ * again.
+ *
+ * `recordLoop` and `activeLoops`/`setLoopPreset` never call each other's normalisation by
+ * accident: both resolve a root through `realpathSync.native` (falling back to `path.resolve`
+ * for a root that no longer exists) and compare with `normcase` — the same case-folding
+ * `js/lib/paths.mjs` uses everywhere a Windows path is compared — so a loop launched from a
+ * differently-cased spelling of the same worktree is still one row, not two.
+ */
+import { readFileSync, mkdirSync, realpathSync, renameSync } from 'node:fs';
+import path from 'node:path';
+
+import { userLoopsDir } from './catalog.mjs';
+import { writeText, readText, isDir, isFile } from '../lib/fs.mjs';
+import { parseJson, jsonDumpsIndent } from '../lib/json.mjs';
+import { normcase } from '../lib/paths.mjs';
+import { parseLoopFile, writeLoopFile, LOOP_FILE } from './state.mjs';
+import { PRESETS } from './score.mjs';
+
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+
+export function registryPath() {
+  return path.join(userLoopsDir(), 'loops.json');
+}
+
+function load() {
+  try {
+    const data = parseJson(readFileSync(registryPath(), 'utf8'));
+    return Array.isArray(data?.loops) ? data.loops.filter((l) => l && typeof l.root === 'string') : [];
+  } catch {
+    return [];
+  }
+}
+
+function save(loops) {
+  try {
+    const file = registryPath();
+    mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp`;
+    writeText(tmp, `${jsonDumpsIndent({ loops })}\n`);
+    renameSync(tmp, file);
+  } catch {
+    /* best-effort: a registry hiccup must never fail init or a read */
+  }
+}
+
+function normalize(dir) {
+  try { return realpathSync.native(dir); } catch { return path.resolve(dir); }
+}
+
+const sameRoot = (a, b) => normcase(a) === normcase(b);
+
+/** The soft-decision iterations of `state.history` — the same shape `state.mjs`'s own
+ * end-of-run `summary()` reports, so a card and a finished-loop review read the same fields. */
+function reviewOf(state) {
+  return state.history.filter((h) => h.decision === 'soft').map((h) => ({ iteration: h.iteration, intent: h.intent }));
+}
+
+function runningRow(entry, state) {
+  return {
+    root: entry.root, branch: entry.branch, title: entry.title, started: entry.started,
+    status: state.status, iteration: state.iteration, node: state.node, preset: state.preset,
+    threshold: PRESETS[state.preset], current: state.current, history: state.history,
+    review: reviewOf(state), reason: state.reason, awaiting: state.awaiting, graph: state.graph,
+  };
+}
+
+/**
+ * Upsert `root`'s identity row. Called by `geneseed loop init` right after `LOOP.md` is
+ * written — `started` is set once, on insert, and never moved by a later call. An update never
+ * touches `finishedAt` either way: `activeLoops` is the only writer of that field, and it will
+ * clear it on the very next poll once it sees LOOP.md present again. Never throws: an `init`
+ * must succeed even when the registry itself cannot be written.
+ */
+export function recordLoop({ root, branch, title, now = new Date() }) {
+  try {
+    const key = normalize(root);
+    const loops = load();
+    const idx = loops.findIndex((l) => sameRoot(l.root, key));
+    if (idx >= 0) {
+      loops[idx] = { ...loops[idx], root: key, branch, title };
+    } else {
+      loops.push({ root: key, branch, title, started: now.toISOString() });
+    }
+    save(loops);
+  } catch {
+    /* a registry hiccup must never fail loop init */
+  }
+}
+
+/**
+ * The rows the Active tab renders, read fresh off every registered worktree's `LOOP.md` —
+ * never off the registry's own stale copy of a loop's state. Four outcomes per row; the
+ * write-back at the end fires ONLY when one of the first three actually changed something
+ * (see the module docblock on why a routine poll must not be a write):
+ *   - the worktree root no longer exists: dropped, silently (a removed clone or worktree);
+ *   - `<root>/LOOP.md` exists but fails to parse (corrupt, or written mid-crash before this
+ *     module's own atomic writer existed): the entry is KEPT exactly as read — dropping it here
+ *     would be indistinguishable from a removed worktree, and a card the user can still see
+ *     beats one that silently vanishes — and the row reports `status: 'unreadable'`;
+ *   - `<root>/LOOP.md` exists and parses: the row carries the state fields the page needs, and
+ *     if the entry still carried a `finishedAt` from a previous finish it is cleared (the loop
+ *     is running again — that counts as a change, and is saved);
+ *   - `LOOP.md` is gone (the loop finished): the first time this is seen, `finishedAt` is set
+ *     to `now` and saved; after that it is read-only here until `now` is more than 7 days past
+ *     that frozen `finishedAt`, at which point the row is dropped (and the drop is saved).
+ */
+export function activeLoops({ now = new Date() } = {}) {
+  const loops = load();
+  const kept = [];
+  const rows = [];
+  let changed = false;
+  for (const entry of loops) {
+    if (!isDir(entry.root)) { changed = true; continue; }
+    const file = path.join(entry.root, LOOP_FILE);
+    const identity = { root: entry.root, branch: entry.branch, title: entry.title, started: entry.started };
+    if (isFile(file)) {
+      let state;
+      try { state = parseLoopFile(readText(file)); } catch {
+        kept.push(entry);
+        rows.push({ ...identity, status: 'unreadable' });
+        continue;
+      }
+      let next = entry;
+      if (entry.finishedAt !== undefined) {
+        next = { ...entry }; delete next.finishedAt; changed = true;
+      }
+      kept.push(next);
+      rows.push(runningRow(next, state));
+      continue;
+    }
+    if (entry.finishedAt === undefined) {
+      const next = { ...entry, finishedAt: now.toISOString() };
+      changed = true;
+      kept.push(next);
+      rows.push({ ...identity, status: 'finished' });
+      continue;
+    }
+    const age = now.getTime() - new Date(entry.finishedAt).getTime();
+    if (age > SEVEN_DAYS_MS) { changed = true; continue; }
+    kept.push(entry);
+    rows.push({ ...identity, status: 'finished' });
+  }
+  if (changed) save(kept);
+  return rows;
+}
+
+/**
+ * Rewrite `root`'s `LOOP.md` `preset` field and nothing else — the per-loop preset picker on
+ * the Active tab. Refuses a `root` the registry does not know about (no arbitrary path
+ * writes — `POST /api/loops/preset`'s whole safety argument) and a `preset` outside `PRESETS`,
+ * each with its own message so the web action can tell the two refusals apart. Unlike
+ * `recordLoop`/`activeLoops`, this one DOES throw: a preset change the caller asked for and did
+ * not happen must be reported, not swallowed. Writes through `writeLoopFile` (atomic, like
+ * every other LOOP.md persist — see `state.mjs`'s docblock).
+ */
+export function setLoopPreset(root, preset) {
+  if (!Object.hasOwn(PRESETS, preset)) throw new Error(`unknown preset ${JSON.stringify(preset)}`);
+  const key = normalize(root);
+  const loops = load();
+  const entry = loops.find((l) => sameRoot(l.root, key));
+  if (!entry || !isDir(entry.root)) throw new Error('unknown loop');
+  const file = path.join(entry.root, LOOP_FILE);
+  if (!isFile(file)) throw new Error('unknown loop');
+  const state = parseLoopFile(readText(file));
+  state.preset = preset;
+  writeLoopFile(file, state);
+  return runningRow(entry, state);
+}