geneseed 3.11.0 → 3.13.0

package/js/loop/cli.mjs

@@ -0,0 +1,173 @@
+/**
+ * `geneseed loop <action>` — the loop engine's only face. Every action prints exactly one JSON
+ * object: the loop skill is a model reading stdout, and a JSON error it can quote beats a
+ * stack trace it has to interpret. Exit 1 on any refusal so a script can still branch on it.
+ *
+ * NO SPAWN. The CLI's closure may not start processes, so git is the model's job: it pipes
+ * `git diff --cached --numstat` into `score --diff` and `git status --porcelain` into `record`.
+ * stdin is read only when it is not a TTY — a hand-run `geneseed loop record` must not hang.
+ *
+ * NO `--file`. `state.mjs`'s `LOOP_FILE` constant is the ROOT-RELATIVE path the engine filters
+ * out of every diff and porcelain check, so LOOP.md has to live at the git root of the worktree
+ * for that filter to mean anything. This entry finds that root itself — walking up from the cwd
+ * to the first directory holding `.git` (a directory for a normal clone, a FILE for a worktree
+ * or submodule) — rather than taking a path the caller could point anywhere.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { readText, writeText, isFile, printOut } from '../lib/fs.mjs';
+import { loadCatalog, catalogProblems, parseBrick } from './catalog.mjs';
+import { checkGraph } from './graph.mjs';
+import { parseNumstat, DEFAULT_PRESET } from './score.mjs';
+import { gitRootOf, gitDirOf, currentBranch } from '../hosts/gitref.mjs';
+import {
+  initState, nextStep, scoreDeclared, scoreDiff, recordOutcome, decideAwaiting,
+  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'));
+const list = (s) => (s ? String(s).split(',').map((x) => x.trim()).filter(Boolean) : null);
+
+function requireRoot() {
+  const root = gitRootOf(process.cwd());
+  if (!root) throw new Error('not inside a git repository');
+  return root;
+}
+
+/**
+ * When `score --diff`/`decide` closes a unit (`commit: true`), write the commit message to
+ * `<gitdir>/LOOP_COMMIT_MSG` — never tracked, never part of any diff — so the loop's own
+ * automation never has to quote a message on a command line (`js/hosts/hooks.mjs`'s
+ * `loopExempt` only whitelists `git commit -F <path>`).
+ *
+ * `gitdir` is RESOLVED BY THE CALLER, before `withState` ran the state change (X6, fix round
+ * 2): a malformed `.git` FILE makes `gitDirOf` throw, and that throw must abort the action
+ * before anything about the loop's state has moved, not after. Adds `message_file` to the
+ * result for the skill to read back, with forward slashes (`C:/...`) even on Windows — Git
+ * Bash and git itself both accept that form on every platform, and a backslash-laden path
+ * breaks when a later shell command tries to use it unquoted.
+ */
+function writeCommitMessage(root, gitdir, result) {
+  if (!result || result.commit !== true) return result;
+  const branch = currentBranch(root);
+  const slug = branch && branch.startsWith('loop/') ? branch.slice('loop/'.length) : 'loop';
+  const file = path.join(gitdir, 'LOOP_COMMIT_MSG');
+  writeText(file, `loop(${slug}): iteration ${result.iteration} — ${result.intent || 'setup'}\n\n${result.trailers}\n`);
+  return { ...result, message_file: file.replaceAll('\\', '/') };
+}
+
+function withState(fn) {
+  const root = requireRoot();
+  const file = path.join(root, LOOP_FILE);
+  if (!isFile(file)) throw new Error(`${file} does not exist — run \`geneseed loop init\` first`);
+  const state = parseLoopFile(readText(file));
+  const { bricks } = loadCatalog({ projectRoot: root });
+  const result = fn(state, bricks);
+  writeLoopFile(file, state);
+  return result;
+}
+
+function resolveGraph(spec, catalog) {
+  if (spec && spec.endsWith('.json')) return JSON.parse(readText(path.resolve(spec)));
+  const g = catalog.templates.get(spec);
+  if (!g) throw new Error(`no loop template named ${JSON.stringify(spec)}`);
+  const { origin, ...graph } = g;
+  return graph;
+}
+
+const ACTIONS = {
+  check(args) {
+    if (args.brick) {
+      const { problems } = parseBrick(readText(path.resolve(args.brick)), 'checked');
+      return { ok: !problems.length, problems };
+    }
+    if (args.graph) {
+      const catalog = loadCatalog({ projectRoot: process.cwd() });
+      const problems = checkGraph(resolveGraph(args.graph, catalog), catalog.bricks);
+      return { ok: !problems.length, problems };
+    }
+    // The bare check doubles as the catalogue LISTING the loop skill composes a free graph
+    // from — frontmatter only: a brick's body reaches the model through `next`, for the node
+    // the engine chose, never as a menu.
+    const problems = catalogProblems({ projectRoot: process.cwd() });
+    const { bricks, templates, overridden } = loadCatalog({ projectRoot: process.cwd() });
+    const byName = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    return {
+      ok: !problems.length, problems,
+      templates: [...templates.keys()].sort(byName),
+      bricks: [...bricks.values()].sort((a, b) => byName(a.name, b.name))
+        .map(({ body, available, reason, ...b }) => ({ ...b, available, ...(reason ? { reason } : {}) })),
+      overridden,
+    };
+  },
+  init(args) {
+    const root = requireRoot();
+    const file = path.join(root, LOOP_FILE);
+    if (isFile(file)) throw new Error(`${file} already exists — a loop is already running here`);
+    if (!args.title || !args.requirement || !args.graph) throw new Error('init needs --title, --requirement and --graph');
+    const catalog = loadCatalog({ projectRoot: root });
+    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,
+      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)),
+  score(args) {
+    if (args.diff) {
+      // X6: resolve (and validate) the gitdir BEFORE withState runs the state change, so a
+      // malformed `.git` file errors without advancing the loop.
+      const root = requireRoot();
+      const gitdir = gitDirOf(root);
+      return writeCommitMessage(root, gitdir, withState((s) => scoreDiff(s, parseNumstat(stdin()))));
+    }
+    if (!args.declared) throw new Error('score needs --declared or --diff');
+    return withState((s) => scoreDeclared(s, {
+      actions: list(args.actions), writeSet: list(args.writeSet), intent: args.intent ?? null,
+    }));
+  },
+  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 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.
+    const root = requireRoot();
+    const gitdir = gitDirOf(root);
+    return writeCommitMessage(root, gitdir, withState((s, b) => decideAwaiting(s, b, args.verdict, args.note ?? '')));
+  },
+};
+
+export function cmdLoop(args) {
+  try {
+    return emit(ACTIONS[args.action](args));
+  } catch (e) {
+    return emit({ error: e.message });
+  }
+}

package/js/loop/graph.mjs

@@ -0,0 +1,163 @@
+/**
+ * The rules a loop graph must satisfy before a single node runs. ONE function, three callers:
+ * `geneseed loop check`, the doctor over the shipped templates, and `loop init` over a graph the
+ * model composed at run time — the composed graph never meets the doctor, so the engine has to
+ * carry the same check or free composition would be unchecked composition.
+ *
+ * WHY EVERY CYCLE NEEDS A DECLARED LOOP. Edges are free, so a graph can loop anywhere. A loop
+ * that terminates only because the model eventually reports a different outcome is a loop that
+ * may not terminate; a declared `max` is what turns "should stop" into "will stop". The check is
+ * structural (strongly connected components), so it needs no simulation and cannot miss a path.
+ *
+ * Problems are returned in a fixed order — per node, per edge, per outcome, then loops — so a
+ * test can write the expected list out instead of sorting it.
+ *
+ * WHY A CYCLE INSIDE AN ITERATION NEEDS ITS OWN LOOP. The whole-SCC check (rule 4) is satisfied
+ * by the iteration loop alone, since every node in an iteration is reachable from every other —
+ * but the runtime gives a node outside every *inner* loop exactly one entry per iteration (no
+ * re-entry at all), so a cycle that never reaches the iteration head and is not inside its own
+ * declared inner loop would hit that "max of 0" path by construction, not by a model's mistake.
+ * The static check has to refuse that graph, not just the ones the runtime would loop forever on.
+ */
+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);
+}
+
+/** Tarjan — the strongly connected components of the node graph (terminals excluded). */
+function components(nodes, edges) {
+  const succ = new Map(nodes.map((n) => [n, []]));
+  for (const e of edges) if (succ.has(e.from) && succ.has(e.to)) succ.get(e.from).push(e.to);
+  let index = 0;
+  const idx = new Map(); const low = new Map(); const stack = []; const on = new Set(); const out = [];
+  const visit = (v) => {
+    idx.set(v, index); low.set(v, index); index += 1; stack.push(v); on.add(v);
+    for (const w of succ.get(v)) {
+      if (!idx.has(w)) { visit(w); low.set(v, Math.min(low.get(v), low.get(w))); }
+      else if (on.has(w)) low.set(v, Math.min(low.get(v), idx.get(w)));
+    }
+    if (low.get(v) === idx.get(v)) {
+      const comp = [];
+      for (;;) { const w = stack.pop(); on.delete(w); comp.push(w); if (w === v) break; }
+      const selfLoop = comp.length === 1 && succ.get(v).includes(v);
+      if (comp.length > 1 || selfLoop) out.push(comp.sort());
+    }
+  };
+  for (const n of nodes) if (!idx.has(n)) visit(n);
+  return out;
+}
+
+export function checkGraph(graph, bricks) {
+  const problems = [];
+  const nodes = Array.isArray(graph.nodes) ? graph.nodes : [];
+  const edges = Array.isArray(graph.edges) ? graph.edges : [];
+  const loops = Array.isArray(graph.loops) ? graph.loops : [];
+  const nodeSet = new Set(nodes);
+
+  // rule 1 — nodes name available bricks
+  for (const n of nodes) {
+    const brick = bricks.get(n);
+    if (!brick) problems.push(`node ${n}: no brick named ${n}`);
+    else if (!brick.available) problems.push(`node ${n}: brick unavailable (${brick.reason})`);
+  }
+  // rule 1 — edge endpoints; rule 2 — edges use declared outcomes
+  for (const e of edges) {
+    const label = `edge ${e.from} --${e.on}--> ${e.to}`;
+    if (!nodeSet.has(e.from)) { problems.push(`${label}: ${e.from} is not a node`); continue; }
+    if (!nodeSet.has(e.to) && !TERMINALS.has(e.to)) {
+      problems.push(`${label}: ${e.to} is not a node, $close or $stop`);
+      continue;
+    }
+    const brick = bricks.get(e.from);
+    if (brick && !brick.outcomes.includes(e.on)) problems.push(`${label}: ${e.on} is not an outcome of ${e.from}`);
+  }
+  // rule 2 — exactly one edge per declared outcome (nodes in sorted order)
+  for (const n of [...nodes].sort()) {
+    const brick = bricks.get(n);
+    if (!brick) continue;
+    for (const o of brick.outcomes) {
+      const count = edges.filter((e) => e.from === n && e.on === o).length;
+      if (count === 0) problems.push(`node ${n}: no edge for outcome ${o}`);
+      else if (count > 1) problems.push(`node ${n}: ${count} edges for outcome ${o}`);
+    }
+  }
+  // rule 3 — start, and $close reachable
+  if (!nodeSet.has(graph.start)) {
+    problems.push(`start ${graph.start} is not a node`);
+  } else {
+    const seen = new Set([graph.start]); const queue = [graph.start];
+    while (queue.length) {
+      const v = queue.shift();
+      for (const e of edges) {
+        if (e.from === v && !seen.has(e.to)) { seen.add(e.to); if (nodeSet.has(e.to)) queue.push(e.to); }
+      }
+    }
+    if (!seen.has('$close')) problems.push(`$close is not reachable from ${graph.start}`);
+  }
+  // rule 5 — loops are well formed
+  for (const l of loops) {
+    if (!Number.isInteger(l.max) || l.max < 1) problems.push(`loop ${l.name}: max must be a positive integer`);
+    else if (l.iteration === true && l.max > ENGINE_MAX_ITERATIONS) {
+      problems.push(`loop ${l.name}: max ${l.max} is above the engine ceiling of ${ENGINE_MAX_ITERATIONS}`);
+    }
+    for (const n of l.nodes ?? []) if (!nodeSet.has(n)) problems.push(`loop ${l.name}: ${n} is not a node`);
+  }
+  const iterations = loops.filter((l) => l.iteration === true).length;
+  if (iterations !== 1) problems.push(`${iterations} loops are marked iteration; exactly one must be`);
+  // rule 4 — every cycle is inside a declared loop
+  for (const comp of components(nodes, edges)) {
+    const covered = loops.some((l) => comp.every((n) => (l.nodes ?? []).includes(n)));
+    if (!covered) problems.push(`cycle ${comp.join(', ')} has no declared loop around it`);
+  }
+  // rule 4b — a cycle that never reaches the iteration head needs its own non-iteration loop
+  const iterationLoops = loops.filter((l) => l.iteration === true);
+  if (iterationLoops.length === 1) {
+    const [iteration] = iterationLoops;
+    const head = iteration.nodes?.[0];
+    const innerEdges = edges.filter((e) => e.to !== head);
+    for (const comp of components(nodes, innerEdges)) {
+      const covered = loops.some((l) => l !== iteration && comp.every((n) => (l.nodes ?? []).includes(n)));
+      if (!covered) problems.push(`cycle ${comp.join(', ')} inside an iteration has no inner loop around it`);
+    }
+    // rule 4c — the iteration is entered only at its head: the runtime opens and closes units
+    // on re-entering nodes[0], so entering anywhere else runs a unit with no head behind it.
+    const inside = new Set(iteration.nodes ?? []);
+    if (head !== undefined) {
+      if (inside.has(graph.start) && graph.start !== head) {
+        problems.push(`start ${graph.start} is inside the iteration but is not its head ${head}`);
+      }
+      for (const e of edges) {
+        if (!inside.has(e.from) && inside.has(e.to) && e.to !== head) {
+          problems.push(`edge ${e.from} --${e.on}--> ${e.to} enters the iteration at ${e.to}, not at its head ${head}`);
+        }
+      }
+    }
+  }
+  // template weight overrides
+  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);
+}