geneseed 3.10.0 → 3.12.0

package/js/README.md

@@ -1,6 +1,6 @@
 # `js/` — the module map
 
-Fifty-seven modules in seven folders. This page is the address book: **what each one owns**, and
+Sixty-one modules in eight folders. This page is the address book: **what each one owns**, and
 **which file to open first** for a given task. It is not documentation of behaviour — every module
 has a docblock for that, and the docblock is the thing to read before editing.
 
@@ -20,6 +20,7 @@ js/build/     src/ + themes/  →  rendered text  →  a bundle  →  a per-host
 js/hosts/     where it stops being a renderer and touches the machine
 js/inspect/   the read-only half: doctor, status, diff, validate, catalog
 js/lib/       primitives, every one a deliberate divergence from the Node default
+js/loop/      `geneseed loop` — the state machine over LOOP.md, and what it steps through
 js/maintain/  lifecycle verbs that change an install that already exists
 js/ui/        what it prints at a terminal
 js/web/       the `geneseed web` console
@@ -68,10 +69,11 @@ user co-owns, and the hook verbs those emitted configs then run.
 |---|---|
 | `hosts.mjs` | The four host config dirs (opencode/claude/bob/openclaude), plus `resolvePath`/`expanduser` |
 | `hooks.mjs` | The verbs the emitted hooks run every session: `context`, `git-gate`, `rule-gate`, `tool-gate` (the two gates fused, for Bob), `learn`. `--host` picks the verdict dialect |
+| `gitref.mjs` | fs/path-only: `gitRootOf`, `gitDirOf`, `currentBranch`, `loopLaunched` — read straight off `.git`, never spawn git. Shared by `hooks.mjs`'s git-gate and `js/loop/cli.mjs`'s commit-message writer |
 | `settings.mjs` | Merges into user-owned `settings.json`/`opencode.json`; owns the hook shim and the managed blocks |
 | `native.mjs` | Capability specs → host-native subagents and skills. The impure half of the emit |
 | `opencode.mjs` | OpenCode-only extras: colour themes, primary agent, `/commands`, plugins, overrides stub |
-| `installs.mjs` | Detects deployed installs and reads back their theme, footprint, posture and mode |
+| `installs.mjs` | Detects deployed installs and reads back their theme, footprint, posture, mode and loop trust preset |
 | `mcp.mjs` | MCP server presets, the per-host `mcpServers` config read/write, and toggle state |
 | `link.mjs` | `geneseed link`/`unlink` — the PATH shim, and the only Windows USER-Path registry edit |
 
@@ -118,12 +120,33 @@ into files users have committed, so change the test that states it in the same c
 | `text.mjs` | String primitives: `codePointLength`, `WHITESPACE`, `parseIntStrict`, `percentDecode` |
 | `udiff.mjs` | `geneseed diff`'s own difflib clone — the alignment IS the printed hunks — plus `splitLines` |
 | `proc.mjs` | One constant: the `windowsHide` flag every spawn in `js/` must reuse |
+| `node-floor.mjs` | The first import of all three binaries: below Node 22.3, one sentence on stderr and exit 1 (0 in the hook) instead of a stack trace |
 
 **Before editing:** parse with `parseJson`, never `JSON.parse` — the latter collapses int `1` and
 float `1.0` into one double, and that value gets written into a user's file. Do not swap in a diff
 library for `udiff.mjs`: it is not Myers, ties resolve to the earliest match. Every function in
 `paths.mjs` branches on `process.platform`, so green on one OS proves nothing about the other.
 
+## `js/loop/` — the loop engine
+
+`geneseed loop` — a state machine over a brick graph, persisted as a JSON block in `LOOP.md` at
+the git root. The model only ever runs the node it is handed and reports an outcome; every
+transition, score and stop is computed here.
+
+| module | owns |
+|---|---|
+| `graph.mjs` | `checkGraph` — the rules a loop graph must satisfy before a node runs: nodes name real bricks, edges cover every outcome, `$close` is reachable, every cycle is inside a declared loop |
+| `score.mjs` | The risk arithmetic: `WEIGHTS`, `PRESETS`, `declaredRisk`/`actualRisk`/`decide`, `parseNumstat`. Pure — no import but node builtins |
+| `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 |
+
+**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.
+
 ## `js/maintain/` — lifecycle
 
 Verbs that change an install that already exists, as opposed to rendering one.
@@ -168,7 +191,7 @@ the deployed harness as JSON.
 | `actions.mjs` | The mutating endpoints — rules, profile, memory, MCP, excludes — plus install/deploy argv |
 | `daemon.mjs` | Detached web start/stop/status/restart, the `.geneseed-web.json` record, and `openUrl` |
 | `jobs.mjs` | `JobManager` and the action→argv table. The only module here that spawns job children |
-| `docs.mjs` | The Docs tab: the `docs/web/` page registry, `?harness=` filtering, the five page kinds |
+| `docs.mjs` | The Docs tab: the `docs/<folder>/` page registry, `?harness=` filtering, link rewriting, the six page kinds |
 | `activity.mjs` | The `activity/` session files: pid-liveness prune, list, detail, and the on/off flag |
 
 **Before editing:** `makeHandler(state, jm, token, dist, holder)`'s arity is load-bearing — three
@@ -190,6 +213,6 @@ and inline lists are held against a surface list written out in
 | a web endpoint | GET → `js/web/api.mjs`; POST → `js/web/actions.mjs` | declare it in `js/web/routes.mjs`; the partition test probes the real handler |
 | a CLI verb | `js/cli-table.json` — the table IS the parser | the `VERBS` row in `bin/geneseed-cli.mjs`, the row count in `cli_table.test.mjs`, `NATIVE` in **two** test files |
 | a hook verb | `js/hosts/hooks.mjs` | `claudeHookGroups` in `settings.mjs`, `VERBS` in `bin/geneseed-hook.mjs`. Keep the import graph tiny |
-| a console doc page | `docs/web/<id>.md` — the stem is the id | `docs/extending.md` §4c. Only `kind: "concept"` gets `{N_*}` substitution |
+| a console doc page | `docs/<understand|guides|concepts|reference>/<id>.md` — the stem is the id | `docs/extending.md` §4c. Only `kind: "concept"` gets `{N_*}` substitution |
 | an OpenCode plugin | `adapters/opencode/plugins/geneseed-<name>.js` | `docs/extending.md` §4a — the `geneseed-` prefix is mechanically load-bearing |
 | to change a `js/lib/` primitive | `tests/fixtures/pure_probe.mjs` **first** | the docblock says which Node default it deliberately departs from — change that sentence too, or the next reader restores the default |

package/js/build/driver.mjs

@@ -65,6 +65,9 @@ import {
 // registry to find every install it must re-emit, and a CLI verb may not reach into a driver
 // for a reader. See js/inspect/registry.mjs.
 import { registryRecord, registryRoots } from '../inspect/registry.mjs';
+// The loop engine's trust presets — the `--trust` choices. `score.mjs` imports nothing, which is
+// what lets it sit inside this driver's total `child_process` ban.
+import { DEFAULT_PRESET, PRESETS } from '../loop/score.mjs';
 
 // P2. `--sync-themes` crossed into its own module rather than into this file: it is 90 lines
 // of textual surgery over committed files with a corpus of its own, and it is the half of the
@@ -111,8 +114,8 @@ export function resolveOut(raw) {
  */
 function configDefaults() {
   const d = {
-    theme: 'neutral', posture: 'peer', mode: 'direct', doctrines: [...PACK_ORDER],
-    excludeRules: [],
+    theme: 'neutral', posture: 'peer', mode: 'direct', trust: DEFAULT_PRESET,
+    doctrines: [...PACK_ORDER], excludeRules: [],
   };
   if (!existsSync(CONFIG)) return d;
   try {
@@ -163,7 +166,7 @@ function configDefaults() {
  * flag is added to one and not the other, and nothing downstream would say so.
  */
 const VALUED = {
-  '--theme': 'theme', '--posture': 'posture', '--mode': 'mode',
+  '--theme': 'theme', '--posture': 'posture', '--mode': 'mode', '--trust': 'trust',
   '--doctrines': 'doctrines', '--exclude-rules': 'excludeRules',
   '--out': 'out', '--target': 'out', '--emit': 'emit',
   '--footprint': 'footprint', '--root': 'root', '--config-dir': 'cfgDir',
@@ -194,13 +197,13 @@ const FLAG_BY_NAME = Object.fromEntries(
 );
 
 /**
- * The four flags `choice` validates, as ONE table for the same anti-drift reason.
+ * The five flags `choice` validates, as ONE table for the same anti-drift reason.
  *
- * A function and not a constant because two of the four read the checkout: `discoverNames`
+ * A function and not a constant because two of the five read the checkout: `discoverNames`
  * scans `postures/` and `modes/`, so the answer depends on the source tree this driver is
  * standing in and cannot be frozen at import.
  *
- * `--doctrines` is DELIBERATELY not a fifth row. Every consumer of this table treats an
+ * `--doctrines` is DELIBERATELY not a sixth row. Every consumer of this table treats an
  * entry as one value drawn from a closed list — `choice` refuses anything else, and
  * `usage`'s metavar prints the list as the whole legal surface. `--doctrines` takes a comma
  * LIST plus the sentinel `none`, so a row here would have refused `craft,rigor` outright and
@@ -213,6 +216,7 @@ function choicesFor() {
     '--footprint': ['lean', 'full'],
     '--posture': discoverNames('postures', 'peer'),
     '--mode': discoverNames('modes', 'direct'),
+    '--trust': Object.keys(PRESETS),
   };
 }
 
@@ -340,6 +344,7 @@ function usage() {
 function parseArgs(argv, defaults) {
   const args = {
     theme: defaults.theme, posture: defaults.posture, mode: defaults.mode,
+    trust: defaults.trust,
     doctrines: defaults.doctrines,
     excludeRules: defaults.excludeRules,
     out: 'Harness', emit: 'files', footprint: 'lean', root: null,
@@ -1035,7 +1040,7 @@ export function buildInto({ theme, out, footprint = 'lean' }) {
 }
 
 export function emitGlobalInto(host, {
-  theme, out, cfgDir, footprint, posture = null, mode = null, doctrines = null,
+  theme, out, cfgDir, footprint, posture = null, mode = null, doctrines = null, trust = null,
 }) {
   // `build.HOSTS.get(host, build.HOSTS["opencode"])` — an unknown host falls back rather than
   // raising, because the host comes from a marker file a user can edit.
@@ -1058,7 +1063,8 @@ export function emitGlobalInto(host, {
       // at `[]`, so the key is OMITTED instead of passed through — `makeCfg`'s own default is
       // the fail-closed answer and an explicit `doctrines: null` would not reach it.
       makeCfg({
-        posture: posture || 'peer', mode: mode || 'direct', ...(doctrines ? { doctrines } : {}),
+        posture: posture || 'peer', mode: mode || 'direct', trust: trust || DEFAULT_PRESET,
+        ...(doctrines ? { doctrines } : {}),
       }),
       { theme, footprint, root: null, cfgDir }, out,
     ),

package/js/build/generate.mjs

@@ -34,11 +34,12 @@ import path from 'node:path';
 
 import { main as driverMain } from './driver.mjs';
 import { makeCfg, PACK_ORDER } from './source.mjs';
+import { DEFAULT_PRESET } from '../loop/score.mjs';
 import { opencodeConfigDir, resolvePath } from '../hosts/hosts.mjs';
 import {
   EMIT_HOST_SCOPE, defaultMode, defaultPosture, defaultTheme, doctrinesForBuild,
   excludedRulesOfDir, footprintOfDir, installState, installTargets, modeOfDir, postureOfDir,
-  readMaybe, themeOfDir,
+  readMaybe, themeOfDir, trustOfDir,
 } from '../hosts/installs.mjs';
 import { colorThemeFiles, colorThemeJson, PALETTE_ROLES } from '../hosts/opencode.mjs';
 import { renderAll } from './render.mjs';
@@ -93,7 +94,7 @@ function sysExit(msg) {
  */
 const BUILD_FORWARD = [
   ['theme', '--theme'], ['emit', '--emit'], ['footprint', '--footprint'],
-  ['posture', '--posture'], ['mode', '--mode'], ['doctrines', '--doctrines'],
+  ['posture', '--posture'], ['mode', '--mode'], ['trust', '--trust'], ['doctrines', '--doctrines'],
   ['excludeRules', '--exclude-rules'], ['out', '--out'], ['root', '--root'],
   ['configDir', '--config-dir'],
 ];
@@ -114,7 +115,7 @@ export function cmdBuild(args) {
  * The elision rules are not symmetric and the Python says why: `footprint` is ALWAYS passed,
  * because omitting it when it matched the generator's default silently coupled the answer to
  * whatever that default happened to be — the moment the default moved, picking the old one
- * produced the new one. `posture` and `mode` still elide at theirs, and neither has moved.
+ * produced the new one. `posture`, `mode` and `trust` still elide at theirs, and none has moved.
  *
  * ⚠ `doctrines` DOES NOT ELIDE, AND THAT IS THE SAFETY DECISION, NOT A STYLE ONE. It used to
  * elide on the full set, by analogy with posture and mode — but those two compare against a
@@ -137,7 +138,7 @@ export function cmdBuild(args) {
  */
 export function setupBuildArgs(theme, emit, out = null, root = null, footprint = 'lean',
   posture = 'peer', mode = 'direct', doctrines = null, allPacks = PACK_ORDER,
-  excludeRules = null) {
+  excludeRules = null, trust = DEFAULT_PRESET) {
   const argv = ['--theme', theme, '--emit', emit];
   if (!emit.endsWith('-global')) {
     if (out) argv.push('--out', out);
@@ -146,6 +147,7 @@ export function setupBuildArgs(theme, emit, out = null, root = null, footprint =
   if (footprint) argv.push('--footprint', footprint);
   if (posture && posture !== 'peer') argv.push('--posture', posture);
   if (mode && mode !== 'direct') argv.push('--mode', mode);
+  if (trust && trust !== DEFAULT_PRESET) argv.push('--trust', trust);
   if (Array.isArray(doctrines)) {
     // Emitted in `allPacks` order, not the order handed in: a caller may legitimately pass an
     // unsorted list, and the flag has to be canonical for the same reason the driver
@@ -199,6 +201,8 @@ export function installProfile(host, scope, root) {
   const footprint = footprintOfDir(root);
   const posture = postureOfDir(root) || defaultPosture();
   const mode = modeOfDir(root) || defaultMode();
+  // Read off the deployed loop skill; no config fallback — `DEFAULT_PRESET` is the engine's.
+  const trust = trustOfDir(root) || DEFAULT_PRESET;
   // A rebuild that defaulted the pack selection would re-emit an install into a constitution
   // its owner did not choose — and in one direction that is not merely surprising: dropping
   // the process pack takes the commit/push consent RULES out of AGENT.md while
@@ -213,7 +217,7 @@ export function installProfile(host, scope, root) {
   const excludeRules = excludedRulesOfDir(root);
   const out = scope === 'global' ? null : root;
   const argv = setupBuildArgs(theme, emit, out, out, footprint, posture, mode, doctrines,
-    PACK_ORDER, excludeRules);
+    PACK_ORDER, excludeRules, trust);
   // A GLOBAL ROW NAMES ITS OWN DIR. `root` came from the host's config-dir resolver, which
   // honours env overrides (`OPENCODE_CONFIG_DIR`, `CLAUDE_CONFIG_DIR`…); without the flag the
   // same argv run from a shell lacking that variable re-emits into the DEFAULT dir — a second
@@ -221,7 +225,7 @@ export function installProfile(host, scope, root) {
   if (scope === 'global') argv.push('--config-dir', root);
   return {
     host, scope, root, state: installState(root, host, scope),
-    emit, theme, footprint, posture, mode, doctrines, excludeRules, argv,
+    emit, theme, footprint, posture, mode, trust, doctrines, excludeRules, argv,
   };
 }
 
@@ -254,7 +258,18 @@ export function rebuildCommand(argv) {
  * choose — which is the same failure mode `_footprint_of_dir`'s WARN exists to prevent, at a
  * larger scale.
  */
-export function cmdRebuildAll() {
+export async function cmdRebuildAll() {
+  const rc = rebuildAll();
+  // A console started before an upgrade keeps serving the old `index.html`; restart it — only
+  // when stale, see `bounceDaemonIfRunning`. Lazy: no other verb in this module needs js/web/.
+  const { bounceDaemonIfRunning } = await import('../web/daemon.mjs');
+  await bounceDaemonIfRunning(null, (m) => printOut(`${m}
+`), { onlyIfStale: true });
+  return rc;
+}
+
+/** The rebuild itself, synchronous — `cmdRebuildAll` is it plus the console restart. */
+export function rebuildAll() {
   const targets = installTargets().filter(([h, s, r]) => installState(r, h, s) === 'active');
   if (!targets.length) {
     printOut('[rebuild-all] no active installs detected.\n');

package/js/build/render.mjs

@@ -35,6 +35,7 @@ import { parseJson } from '../lib/json.mjs';
 import { normcase, comparePaths } from '../lib/paths.mjs';
 // `js/build/source.mjs` imports nothing but node builtins, so this direction cannot cycle.
 import { PACK_ORDER, readPackText, resolveRuleIds } from './source.mjs';
+import { DEFAULT_PRESET } from '../loop/score.mjs';
 
 /** Document STRUCTURE is theme-INDEPENDENT — mirrors `_build_render.STRUCTURE`. */
 export const STRUCTURE = {
@@ -391,6 +392,10 @@ export function effectiveTheme(cfg, themeName, { footprint = 'full', lawsPrefix
   const theme = { ...loadTheme(cfg, themeName), ...(cfg.structure ?? STRUCTURE) };
   theme.POSTURE_BODY = registerBody(cfg, theme, 'postures', cfg.posture ?? 'peer', 'peer');
   theme.MODE_BODY = registerBody(cfg, theme, 'modes', cfg.mode ?? 'direct', 'direct');
+  // The loop skill's default trust preset (`--trust`), raw for `--preset` and capitalised for
+  // the `Default trust preset: **<Label>**` line `trustOfDir` reads back off an install.
+  theme.TRUST = cfg.trust ?? DEFAULT_PRESET;
+  theme.TRUST_LABEL = theme.TRUST[0].toUpperCase() + theme.TRUST.slice(1);
   // The doctrines pair is threaded, not read off `cfg`: `footprint` is a per-RENDER value
   // (`renderAll`'s option, and the same cfg renders both ways in one process), so parking it
   // on cfg would make the terse/full choice sticky across calls. An options object rather

package/js/build/source.mjs

@@ -26,6 +26,7 @@
  */
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
+import { DEFAULT_PRESET } from '../loop/score.mjs';
 
 /**
  * One doctrine pack file used to be read three times per render — the survives gate and the
@@ -168,6 +169,12 @@ export const CONFIG = path.join(ROOT, 'harness.config.json');
 export const THEMES = path.join(ROOT, 'themes');
 export const PLUGIN_SRC = path.join(ROOT, 'adapters', 'opencode', 'plugins');
 export const WORKFLOW_SRC = path.join(ROOT, 'adapters', 'opencode', 'workflows');
+/**
+ * The user docs: one folder per kind of reading, all under `docs/` so GitHub renders the same
+ * files the console serves. A page's id is its basename, so ids must be unique across folders.
+ */
+export const DOCS = path.join(ROOT, 'docs');
+export const DOC_FOLDERS = ['understand', 'guides', 'concepts', 'reference'];
 
 /**
  * `_build_render.posture_names()` / `mode_names()` — discovered, never hardcoded, so a new
@@ -250,7 +257,8 @@ export function knownRuleIds() {
  * `PACK_ORDER` for the whole process.
  */
 export function makeCfg({
-  posture = 'peer', mode = 'direct', doctrines = PACK_ORDER, excludeRules = [],
+  posture = 'peer', mode = 'direct', trust = DEFAULT_PRESET, doctrines = PACK_ORDER,
+  excludeRules = [],
 } = {}) {
   return {
     root: ROOT,
@@ -262,6 +270,8 @@ export function makeCfg({
     workflowSrc: WORKFLOW_SRC,
     posture,
     mode,
+    // The loop skill's default preset (`--trust`); the skill is its only reader.
+    trust,
     doctrines: Array.isArray(doctrines) ? [...doctrines] : [...PACK_ORDER],
     // ⚠ THE SECOND DOCTRINE AXIS, AND ITS DEFAULT IS THE OPPOSITE WAY ROUND. `doctrines`
     // defaults to EVERYTHING because an unknown selection must bind the most; `excludeRules`

package/js/cli-table.json

@@ -1,5 +1,5 @@
 {
-  "prog": "harness",
+  "prog": "geneseed",
   "commands": [
     {
       "name": "bootstrap",
@@ -133,6 +133,21 @@
           "type": null,
           "hidden": false
         },
+        {
+          "names": [
+            "--trust"
+          ],
+          "dest": "trust",
+          "metavar": null,
+          "help": "default loop trust preset: how much a loop may do before it stops to ask (default balanced)",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
         {
           "names": [
             "--doctrines"
@@ -623,6 +638,226 @@
       "options": [],
       "mutex": []
     },
+    {
+      "name": "loop",
+      "help": "run a loop: check graphs, start one in LOOP.md, and step its state machine (next/score/record/decide)",
+      "description": "",
+      "positionals": [
+        {
+          "names": [],
+          "dest": "action",
+          "metavar": null,
+          "help": "",
+          "choices": [
+            "check",
+            "init",
+            "next",
+            "score",
+            "record",
+            "decide"
+          ],
+          "default": null,
+          "required": true,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        }
+      ],
+      "options": [
+        {
+          "names": ["--graph"],
+          "dest": "graph",
+          "metavar": null,
+          "help": "a loop template name or a .json graph file",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--brick"],
+          "dest": "brick",
+          "metavar": null,
+          "help": "check one brick file instead of the whole catalogue",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--title"],
+          "dest": "title",
+          "metavar": null,
+          "help": "the loop's title, written into LOOP.md",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--requirement"],
+          "dest": "requirement",
+          "metavar": null,
+          "help": "the requirement the loop exists to satisfy",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--preset"],
+          "dest": "preset",
+          "metavar": null,
+          "help": "the risk preset to run under (default: balanced)",
+          "choices": [
+            "prudent",
+            "balanced",
+            "aggressive"
+          ],
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--declared"],
+          "dest": "declared",
+          "metavar": null,
+          "help": "score the card just declared, before it runs",
+          "choices": null,
+          "default": false,
+          "required": false,
+          "nargs": "0",
+          "is_flag": true,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--diff"],
+          "dest": "diff",
+          "metavar": null,
+          "help": "score the actual diff, read as numstat on stdin",
+          "choices": null,
+          "default": false,
+          "required": false,
+          "nargs": "0",
+          "is_flag": true,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--actions"],
+          "dest": "actions",
+          "metavar": null,
+          "help": "comma-separated declared action kinds (new-file, logic, api, ...)",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--write-set"],
+          "dest": "write_set",
+          "metavar": null,
+          "help": "comma-separated files the declared card expects to touch",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--intent"],
+          "dest": "intent",
+          "metavar": null,
+          "help": "a short label for what the declared card is doing",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--outcome"],
+          "dest": "outcome",
+          "metavar": null,
+          "help": "the brick's reported outcome, one of its declared outcomes",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--card"],
+          "dest": "card",
+          "metavar": null,
+          "help": "a JSON card to record alongside the outcome",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--verdict"],
+          "dest": "verdict",
+          "metavar": null,
+          "help": "the user's answer to an awaiting validation",
+          "choices": [
+            "ok",
+            "no",
+            "amend"
+          ],
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": ["--note"],
+          "dest": "note",
+          "metavar": null,
+          "help": "a note attached to the verdict, written into LOOP.md",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        }
+      ],
+      "mutex": []
+    },
     {
       "name": "mcp",
       "help": "list the MCP servers wired into each active install, and the presets available to add",

package/js/hosts/gitref.mjs

@@ -0,0 +1,99 @@
+/**
+ * js/hosts/gitref.mjs — "what branch, and is a loop running here", read straight off the
+ * filesystem. Never spawns git.
+ *
+ * ONE OWNER, fs/path ONLY, NOTHING ELSE. Before this module, `currentBranch` and the
+ * launched-loop evidence reader were duplicated in `js/hosts/hooks.mjs` (the hook's
+ * `loopExempt`) and `js/loop/cli.mjs` (the CLI's commit-message writer) — two copies of the
+ * same worktree-following walk that could silently drift apart. Both now import this one.
+ * `js/hosts/hooks.mjs` is NOT a safe shared home for it: it pulls in `node:child_process`
+ * (`spawnSync`, for the destructive-act guard's own concerns) and the hook-dispatch
+ * machinery (`jsonDumpsCompact`, the ledger), none of which `js/loop/cli.mjs` — under a hard
+ * `child_process` ban like every other closure that feeds `bin/geneseed-cli.mjs` — may ever
+ * import. A module that is fs/path only is importable from anywhere.
+ *
+ * The OpenCode guard plugin (`adapters/opencode/plugins/geneseed-guard.js`) keeps its own
+ * standalone copy — it cannot import from `js/` at all — kept in step by hand, commented as
+ * this module's twin.
+ */
+import { existsSync, statSync, lstatSync, readFileSync, openSync, readSync, closeSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * The directory holding `.git` for `cwd` — walking up from `cwd`. A worktree's `.git` is a
+ * FILE naming its gitdir elsewhere; LOOP.md always lives beside that FILE, not beside the
+ * gitdir it points to, so this is the directory the launched-loop evidence reader looks in.
+ * null on anything unexpected.
+ */
+export function gitRootOf(cwd) {
+  try {
+    let dir = path.resolve(cwd);
+    for (;;) {
+      if (existsSync(path.join(dir, '.git'))) return dir;
+      const up = path.dirname(dir);
+      if (up === dir) return null;
+      dir = up;
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The `.git` DIRECTORY for `root` — itself, or the gitdir a worktree's `.git` FILE names.
+ * Throws if `.git` is a file that does not name one: a malformed worktree link is a louder
+ * failure than a silent "no gitdir", and every caller here wants to know before it acts on it.
+ */
+export function gitDirOf(root) {
+  const dotgit = path.join(root, '.git');
+  if (statSync(dotgit).isFile()) {
+    const m = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(dotgit, 'utf8'));
+    if (!m) throw new Error(`${dotgit} does not name a gitdir`);
+    return path.resolve(root, m[1]);
+  }
+  return dotgit;
+}
+
+/**
+ * The branch checked out in `cwd`, read from .git/HEAD without spawning git. null on
+ * anything unexpected (detached HEAD, no repo, a malformed worktree link, unreadable) — the
+ * caller then falls back to asking, never to allowing.
+ */
+export function currentBranch(cwd) {
+  try {
+    const root = gitRootOf(cwd);
+    if (!root) return null;
+    const ref = /^ref:\s*refs\/heads\/(.+?)\s*$/m.exec(readFileSync(path.join(gitDirOf(root), 'HEAD'), 'utf8'));
+    return ref ? ref[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+const LOOP_STATE_MARKER = '<!-- loop-state:begin -->';
+
+/**
+ * Whether `<root>/LOOP.md` carries the engine's state marker — `geneseed loop init`'s mark
+ * that a loop was actually LAUNCHED here, not merely that the branch is named `loop/...`,
+ * which anyone can type. `lstatSync` (never `statSync`, which follows a link) must find an
+ * ordinary file: a FIFO would block the read, and a symlink could point anywhere outside the
+ * repo — either makes "LOOP.md says so" a claim this reader cannot stand behind. Read at
+ * most the first 64 KB: the marker is not on the first line (it follows the title and the
+ * requirement), so it must appear within those 64 KB — a huge LOOP.md (notes, history) must
+ * never make this check slow.
+ */
+export function loopLaunched(root) {
+  let fd;
+  try {
+    const p = path.join(root, 'LOOP.md');
+    if (!lstatSync(p).isFile()) return false;
+    fd = openSync(p, 'r');
+    const buf = Buffer.alloc(65536);
+    const n = readSync(fd, buf, 0, buf.length, 0);
+    return buf.toString('utf8', 0, n).includes(LOOP_STATE_MARKER);
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) { try { closeSync(fd); } catch { /* already gone */ } }
+  }
+}