geneseed 3.12.0 → 3.14.0

package/js/loop/state.mjs

@@ -21,14 +21,31 @@
  * action — is excluded from every score and every read-brick porcelain check: it is never part
  * of the work being scored, and including it would make every action's own bookkeeping look
  * like an undeclared file touch.
+ *
+ * `writeLoopFile` IS THE ONLY WRITER. Every call site that persists LOOP.md — `cli.mjs`'s
+ * `withState` and `init`, and `registry.mjs`'s `setLoopPreset` — writes through it rather than
+ * through a bare `writeText(file, renderLoopFile(state))`, so a process killed mid-write can
+ * never leave a torn, half-written LOOP.md for the next `loop next`/`score`/`record` to choke
+ * on. `LOOP_FILE_TMP` sits BESIDE `LOOP_FILE` in the worktree, not inside the gitdir: the gitdir
+ * is resolved by `gitDirOf`, which can THROW on a malformed worktree link (X6 in `cli.mjs`), and
+ * every one of these three call sites must still be able to rewrite LOOP.md when that resolution
+ * fails or was never attempted (`setLoopPreset` has no gitdir concept at all). A temp file beside
+ * LOOP.md needs no new failure mode to reason about instead — it is exposed to `git status`, but
+ * only for the instant between the write and the rename (ordinarily unobservable; a crash in
+ * that window is the one case it lingers), and `LOOP_FILE_TMP` joins `LOOP_FILE` in both
+ * `filterPorcelain` and `scoreDiff`'s exclusion below for exactly that case: a lingering
+ * `LOOP.md.tmp` is the engine's own bookkeeping too, never scored work.
  */
+import { renameSync, unlinkSync } from 'node:fs';
+import { writeText } from '../lib/fs.mjs';
 import { declaredRisk, actualRisk, decide, worst, PRESETS, DEFAULT_PRESET } from './score.mjs';
 import { iterationLoop, ENGINE_MAX_ITERATIONS } from './graph.mjs';
 
 const BEGIN = '<!-- loop-state:begin -->';
 const END = '<!-- loop-state:end -->';
-export const VERIFY_COMMAND = 'git add -A && git diff --cached --numstat | geneseed loop score --diff';
+const VERIFY_COMMAND = 'git add -A && git diff --cached --numstat | geneseed loop score --diff';
 export const LOOP_FILE = 'LOOP.md';
+const LOOP_FILE_TMP = `${LOOP_FILE}.tmp`;
 const slash = (p) => String(p).replaceAll('\\', '/');
 
 export function renderLoopFile(state) {
@@ -38,6 +55,41 @@ export function renderLoopFile(state) {
     + `${BEGIN}\n\`\`\`json\n${JSON.stringify(state, null, 2)}\n\`\`\`\n${END}\n`;
 }
 
+const RETRYABLE_RENAME_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+
+/** Synchronous back-off between rename attempts — `Atomics.wait` on a throwaway
+ * `SharedArrayBuffer`, the stdlib's own blocking sleep with no dependency. */
+function backoff(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Rename `tmp` to `file`, retrying up to 3 attempts total on a transient Windows lock
+ * (EPERM/EACCES/EBUSY — an AV scanner or editor briefly holding the handle open) with a short
+ * back-off between attempts. A non-retryable error, or the 3rd retryable failure, removes the
+ * temp file (best-effort — a cleanup failure must not mask the real error) and rethrows.
+ * `renameFn` is an injectable seam for tests; production never passes it.
+ */
+export function renameWithRetry(tmp, file, renameFn = renameSync) {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      renameFn(tmp, file);
+      return;
+    } catch (e) {
+      if (attempt < 3 && RETRYABLE_RENAME_CODES.has(e.code)) { backoff(25 * attempt); continue; }
+      try { unlinkSync(tmp); } catch { /* best-effort cleanup; the rename error is what matters */ }
+      throw e;
+    }
+  }
+}
+
+/** `<file>.tmp` then `renameWithRetry` — the atomic write every LOOP.md persist goes through. */
+export function writeLoopFile(file, state) {
+  const tmp = `${file}.tmp`;
+  writeText(tmp, renderLoopFile(state));
+  renameWithRetry(tmp, file);
+}
+
 export function parseLoopFile(text) {
   const t = String(text).replace(/\r\n/g, '\n');
   const a = t.indexOf(BEGIN); const b = t.lastIndexOf(END);
@@ -49,16 +101,21 @@ export function parseLoopFile(text) {
 const head = (state) => iterationLoop(state.graph).nodes[0];
 const fmt = (n) => Number(n).toFixed(1);
 
-export function initState({ title, requirement, graph, preset = DEFAULT_PRESET }) {
-  if (!PRESETS[preset]) throw new Error(`unknown preset ${JSON.stringify(preset)}`);
+/**
+ * `contracts`: extra globs (`loop init --contracts`), appended after the graph's own. Every
+ * field the engine ever writes is listed here, `gateAmends` included (`decideGate` still reads
+ * it with `?.`, for a LOOP.md written before it was listed).
+ */
+export function initState({ title, requirement, graph, preset = DEFAULT_PRESET, contracts = [] }) {
+  if (!Object.hasOwn(PRESETS, preset)) throw new Error(`unknown preset ${JSON.stringify(preset)}`);
   const loop = iterationLoop(graph);
   const state = {
-    v: 1, title, requirement, preset, contracts: [], graph, node: graph.start,
+    v: 1, title, requirement, preset, contracts: [...(graph.contracts ?? []), ...contracts], graph, node: graph.start,
     status: 'running', awaiting: null, reason: null,
     iteration: loop.nodes.includes(graph.start) ? 1 : 0,
     card: null, validated: false, pendingVerify: false, closing: false, counters: {},
     resplit: false, emptyStreak: 0, snapshot: '', visited: [], tests: 'n/a', current: {},
-    notes: [], history: [],
+    notes: [], history: [], gateAmends: {},
   };
   if (preset === 'prudent') { state.status = 'awaiting'; state.awaiting = { kind: 'launch' }; }
   return state;
@@ -74,12 +131,14 @@ function resetUnit(state) {
   state.current = {}; state.tests = 'n/a';
 }
 
+/** The soft-decision iterations of `state.history` — what the end-of-run summary and the
+ * registry's Active-tab row both call `review`, so the two read the same fields. */
+export function reviewOf(state) {
+  return state.history.filter((h) => h.decision === 'soft').map((h) => ({ iteration: h.iteration, intent: h.intent }));
+}
+
 function summary(state) {
-  return {
-    iterations: state.history.length,
-    review: state.history.filter((h) => h.decision === 'soft').map((h) => ({ iteration: h.iteration, intent: h.intent })),
-    notes: state.notes,
-  };
+  return { iterations: state.history.length, review: reviewOf(state), notes: state.notes };
 }
 
 export function trailers(state) {
@@ -93,6 +152,7 @@ export function trailers(state) {
     `Loop-Threshold: ${state.preset} ${fmt(silent)}/${fmt(soft)}`,
     `Loop-Decision: ${state.current.decision ?? 'silent'}${state.current.amended ? ' (amended)' : ''}`,
     `Loop-Tests: ${state.tests}`,
+    ...(state.current.gates ? [`Loop-Gates: ${state.current.gates.join(',')}`] : []),
   ].join('\n');
 }
 
@@ -102,6 +162,7 @@ function finishUnit(state, committed) {
       iteration: state.iteration, bricks: [...new Set(state.visited)],
       declared: state.current.declared ?? 0, actual: state.current.actual ?? state.current.declared ?? 0,
       decision: state.current.decision ?? 'silent', tests: state.tests, intent: state.card?.intent ?? '',
+      ...(state.current.gates ? { gates: state.current.gates } : {}),
     });
   }
   // The unit is committed (or was empty): the tree is clean again, so the read-brick check
@@ -139,6 +200,10 @@ export function nextStep(state, bricks) {
     node: state.node, iteration: state.iteration, effect: brick.effect, agent: brick.agent,
     skill: brick.skill, outcomes: brick.outcomes, prompt: brick.body, card: state.card,
     notes: state.notes, validate: brick.effect === 'mutate' && !state.validated,
+    // The template's own rules (a cited proof before a deletion, no retries as a flake fix) are
+    // its `rules` list; every brick gets them, not only the head that reads LOOP.md. Never the
+    // description: that is the catalogue blurb, and sending it would dilute the rules.
+    ...(state.graph.rules?.length ? { rules: state.graph.rules } : {}),
   };
 }
 
@@ -170,9 +235,9 @@ export function scoreDiff(state, files) {
   assertRunning(state);
   if (!state.pendingVerify) throw new Error('no iteration to verify: `geneseed loop next` has not asked for one');
   if (!Array.isArray(state.contracts) || state.contracts.some((c) => typeof c !== 'string')) {
-    throw new Error('LOOP.md: contracts must be a list of file paths');
+    throw new Error('LOOP.md: contracts must be a list of file paths or globs');
   }
-  const scored = files.filter((f) => slash(f.file) !== LOOP_FILE);
+  const scored = files.filter((f) => slash(f.file) !== LOOP_FILE && slash(f.file) !== LOOP_FILE_TMP);
   if (!scored.length) {
     // A closing unit (reached $close with a mutate already visited) finishes as done even
     // when this is its second empty diff in a row: there is nothing left to retry into.
@@ -184,7 +249,8 @@ export function scoreDiff(state, files) {
   }
   state.emptyStreak = 0;
   const { score, reasons } = actualRisk(state.current.declared ?? 0, scored, {
-    writeSet: state.card?.writeSet ?? [], contracts: state.contracts ?? [], overrides: state.graph.weights,
+    writeSet: state.card?.writeSet ?? [], contracts: state.contracts ?? [],
+    ignoreDeletions: state.graph.ignoreDeletions ?? [], overrides: state.graph.weights,
   });
   const decision = decide(score, state.preset);
   state.current.actual = score;
@@ -223,25 +289,44 @@ function allowedEntries(graph, v) {
 }
 
 // Porcelain lines are `XY <path>`; strip the 2-char status + space, slash-normalise, drop
-// LOOP.md rows (the engine rewrites it on every action — it is never part of the scored work).
+// LOOP.md rows (the engine rewrites it on every action — it is never part of the scored work)
+// and a lingering LOOP.md.tmp (the atomic writer's own sibling — see `writeLoopFile`'s docblock).
 function filterPorcelain(porcelain) {
   const lines = porcelain.split(/\r?\n/).filter((line) => {
     if (!line) return false;
     const path = line.slice(3).replace(/^"|"$/g, '');
-    return slash(path) !== LOOP_FILE;
+    return slash(path) !== LOOP_FILE && slash(path) !== LOOP_FILE_TMP;
   });
   return lines.join('\n').trimEnd();
 }
 
 // Setup work (iteration 0, graph.start outside the iteration loop) is its own unit; rejecting
 // it has nowhere to retry back into, so it stops the loop instead of looping to the head.
+// Iteration 0 alone says so: `initState` starts at 0 only when graph.start is outside the
+// iteration loop, and `iteration` only ever counts up from there.
 function isSetupUnit(state) {
-  return state.iteration === 0 && !iterationLoop(state.graph).nodes.includes(state.graph.start);
+  return state.iteration === 0;
 }
 
-export function recordOutcome(state, bricks, outcome, { card = null, porcelain = null } = {}) {
+const isStringList = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
+
+// A card arrives from the model as JSON (`record --card`), so its shape is checked before
+// anything is stored: a string `writeSet` stored here only throws later, inside `score --diff`,
+// with `pendingVerify` already set — and `score --declared` refuses while that is set, so
+// nothing could get the loop moving again.
+function cardProblem(card) {
+  if (typeof card !== 'object' || Array.isArray(card)) return 'the card must be a JSON object';
+  if (!isStringList(card.actions)) return "the card's actions must be a list of strings";
+  if (!isStringList(card.writeSet)) return "the card's writeSet must be a list of strings";
+  if (card.intent != null && typeof card.intent !== 'string') return "the card's intent must be a string";
+  return null;
+}
+
+export function recordOutcome(state, bricks, outcome, { card = null, porcelain = null, note = '' } = {}) {
   assertRunning(state);
   if (state.pendingVerify) throw new Error('the iteration is closed: run `geneseed loop score --diff` first');
+  const problem = card === null ? null : cardProblem(card);
+  if (problem) throw new Error(problem);
   const from = state.node;
   const brick = bricks.get(from);
   if (!brick) throw new Error(`no brick named ${from} in the catalogue`);
@@ -258,11 +343,33 @@ export function recordOutcome(state, bricks, outcome, { card = null, porcelain =
   if (filteredPorcelain !== null) state.snapshot = filteredPorcelain;
   if (card) state.card = card;
   if (from === 'test') state.tests = outcome;
+  // A finding a brick needs to survive the unit (the ordered plan `plan` produced, `review`'s
+  // `fail` findings) — pushed before the transition below, so it lands in `notes` even when
+  // this call closes the unit, re-splits, or stops the loop. `notes` is never reset mid-run
+  // (only `exhaust`'s own push and `decideAwaiting` add to it otherwise), so it survives
+  // `resetUnit`/`finishUnit` — which a card does not: `resetUnit` clears it.
+  if (note) state.notes.push(`iteration ${state.iteration} (${from}): ${note}`);
   state.visited.push(from);
 
   const edge = state.graph.edges.find((e) => e.from === from && e.on === outcome);
   if (!edge) throw new Error(`no edge from ${from} on ${outcome}`);
-  if (edge.to === '$stop') return stop(state, `${from} reported ${outcome}`);
+  if (brick.gate === 'human' && (!brick.gateOn || brick.gateOn.includes(outcome))) {
+    state.status = 'awaiting';
+    state.awaiting = { kind: 'gate', node: from, outcome, ...(note ? { note } : {}) };
+    return { awaiting: state.awaiting };
+  }
+  return transition(state, bricks, from, edge);
+}
+
+/**
+ * Follow `edge` out of `from` — the second half of `recordOutcome`, and what `decide ok` runs on
+ * a held gate. THE GATE HOLDS THE WHOLE TRANSITION: whatever the edge would do (ask for the diff
+ * score, close the unit, stop, count a re-entry and exhaust a ring) happens only here, after the
+ * user's `ok` — never before it, so nothing is scored, committed, re-split or stopped by the
+ * transition while the gate waits. A held `$stop` edge still waits: the user may `amend` it.
+ */
+function transition(state, bricks, from, edge) {
+  if (edge.to === '$stop') return stop(state, `${from} reported ${edge.on}`);
   const mutated = state.visited.some((n) => bricks.get(n)?.effect === 'mutate');
   if (edge.to === '$close') {
     if (mutated) { state.closing = true; state.pendingVerify = true; return { verify: true }; }
@@ -288,8 +395,10 @@ export function recordOutcome(state, bricks, outcome, { card = null, porcelain =
 export function decideAwaiting(state, bricks, verdict, note = '') {
   if (state.status !== 'awaiting') throw new Error('nothing is awaiting a decision');
   if (!['ok', 'no', 'amend'].includes(verdict)) throw new Error(`verdict must be ok, no or amend, not ${JSON.stringify(verdict)}`);
-  const { kind } = state.awaiting;
+  const held = state.awaiting;
+  const { kind } = held;
   state.awaiting = null; state.status = 'running';
+  if (kind === 'gate') return decideGate(state, bricks, verdict, note, held);
   if (note) state.notes.push(`iteration ${state.iteration} (${kind}, ${verdict}): ${note}`);
   if (kind === 'launch') {
     return verdict === 'ok' ? { resumed: true } : stop(state, `graph ${verdict === 'no' ? 'rejected' : 'to amend'}${note ? `: ${note}` : ''}`);
@@ -320,3 +429,32 @@ export function decideAwaiting(state, bricks, verdict, note = '') {
   resetUnit(state); state.node = head(state); state.snapshot = '';
   return { discard: true };
 }
+
+const GATE_MAX_AMENDS = 3;
+
+/**
+ * The answer to a held `gate: human` transition. Every verdict leaves a note — with or without
+ * the user's words — so the run's notes say each gate was answered and how. `ok` follows the held
+ * edge and lists the node under the unit's `Loop-Gates`; `no` stops; `amend` re-runs the same
+ * node with the note in `notes` (its `validated` untouched — a mutate gate need not re-score —
+ * and its `counters` reset),
+ * `GATE_MAX_AMENDS` times per node per iteration (`gateAmends` is keyed `node@iteration` and never
+ * reset, so the next iteration's card — a new ADR, say — gets its own budget), and the next
+ * one stops: three rounds of review that did not converge are a conversation, not a loop.
+ */
+function decideGate(state, bricks, verdict, note, { node, outcome }) {
+  state.notes.push(`iteration ${state.iteration} (gate at ${node}, ${verdict})${note ? `: ${note}` : ''}`);
+  if (verdict === 'no') return stop(state, `gate rejected at ${node}${note ? `: ${note}` : ''}`);
+  if (verdict === 'amend') {
+    const key = `${node}@${state.iteration}`;
+    state.gateAmends = { ...state.gateAmends, [key]: (state.gateAmends?.[key] ?? 0) + 1 };
+    if (state.gateAmends[key] > GATE_MAX_AMENDS) return stop(state, `gate amended ${GATE_MAX_AMENDS} times at ${node}`);
+    // As an `actual` amend: the amendment changes what the unit does, so the ring budget
+    // restarts; the amend cap above still bounds the unit.
+    state.counters = {};
+    state.node = node;
+    return { resumed: true };
+  }
+  state.current.gates = [...new Set([...(state.current.gates ?? []), node])];   // once each, as Loop-Bricks
+  return transition(state, bricks, node, state.graph.edges.find((e) => e.from === node && e.on === outcome));
+}

package/js/maintain/memory.mjs

@@ -30,7 +30,7 @@
 import { readdirSync, unlinkSync } from 'node:fs';
 import path from 'node:path';
 
-import { memoryDropIndex } from '../hosts/hooks.mjs';
+import { memoryDropIndex } from '../hosts/memory-files.mjs';
 import { resolveMemoryDir } from '../hosts/hosts.mjs';
 import { printOut, printErr, isFile } from '../lib/fs.mjs';
 

package/js/maintain/migrate.mjs

@@ -35,17 +35,14 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:
 import path from 'node:path';
 
 import { main as driverMain } from '../build/driver.mjs';
-import { PACK_ORDER, ROOT } from '../build/source.mjs';
+import { ROOT } from '../build/source.mjs';
+import { CLAUDE_STYLE } from '../hosts/hosts.mjs';
+import { EMIT_HOST_SCOPE, installState, installTargets, readMaybe } from '../hosts/installs.mjs';
+import { installProfile } from '../build/generate.mjs';
 import {
-  EMIT_HOST_SCOPE, defaultMode, defaultPosture, defaultTheme, doctrinesForBuild,
-  footprintOfDir, installState, installTargets, modeOfDir, postureOfDir, readMaybe, themeOfDir,
-  trustOfDir,
-} from '../hosts/installs.mjs';
-import { DEFAULT_EMIT, setupBuildArgs } from '../build/generate.mjs';
-import { DEFAULT_PRESET } from '../loop/score.mjs';
-import {
-  autostartPaths, autostartStale, hookShimPath, migrateShape, readJsonc, shimHome,
-} from '../hosts/settings.mjs';
+  autostartPaths, autostartStale, hookShimPath, migrateShape, shimHome,
+} from '../hosts/shim.mjs';
+import { loadJsonObject } from '../hosts/settings.mjs';
 import { writeText, printOut, printErr } from '../lib/fs.mjs';
 
 /** Every emit name the generator answers to — the set an unrecognised marker is NOT in. */
@@ -61,21 +58,20 @@ const KNOWN_EMITS = new Set(EMIT_HOST_SCOPE.keys());
  * host-parity rule asks for.
  */
 function hookSettingsFile(root, host, scope) {
-  if (!['claude', 'bob', 'openclaude'].includes(host)) return null;
+  if (!CLAUDE_STYLE.includes(host)) return null;
   const name = scope === 'project' && host !== 'bob' ? 'settings.local.json' : 'settings.json';
   return path.join(root, name);
 }
 
 /** Every hook command string in a settings file, or [] when it cannot be read or parsed. */
 function hookCommandsOf(file) {
-  // `readJsonc`, NOT `JSON.parse`. A hand-edited settings.json with comments and a trailing
-  // comma is the one shape no machine in this project writes, and strict JSON rejects it —
+  // `loadJsonObject` (JSONC), NOT `JSON.parse`. A hand-edited settings.json with comments and a
+  // trailing comma is the one shape no machine in this project writes, and strict JSON rejects it —
   // which would classify a wired install as `none` and make `migrate` skip the machine
   // silently. `mergeClaudeSettings` already reads through comments for exactly this reason.
   // Found by the JSONC corpus fixture; a generated fixture would have hidden it.
-  let loaded;
-  try { [loaded] = readJsonc(readFileSync(file, 'utf8')); } catch { return []; }
-  if (!loaded || typeof loaded !== 'object') return [];
+  const { state, data: loaded } = loadJsonObject(file);
+  if (state !== 'ok') return [];
   const hooks = loaded.hooks;
   if (!hooks || typeof hooks !== 'object') return [];
   const out = [];
@@ -210,21 +206,13 @@ export function cmdMigrate(args = {}) {
     try { rmSync(stash, { recursive: true, force: true }); } catch { /* nothing to undo */ }
   };
 
-  // Step 3 — re-emit, in each install's OWN six values. Same reads as `cmdRebuildAll`, and
-  // the pack selection is the sixth: leaving it out re-emitted a narrowed install at whatever
-  // `harness.config.json` said, which WIDENS a constitution its owner had cut down (and, the
-  // other way, can strip the consent gate). `null` — a pre-marker carrier, which on a MIGRATION
-  // is the common case and not the rare one — resolves to ALL packs through
-  // `doctrinesForBuild`, never to `harness.config.json`, which is what makes it fail-closed.
+  // Step 3 — re-emit, in each install's OWN values: `installProfile`, the one reading
+  // `rebuild-all` and `status` share. This loop hand-copied it once and drifted twice — it
+  // passed the excluded rules as `null` (re-admitting every rule an owner switched off,
+  // `process 5` among them) and dropped `--config-dir`, so a global found through
+  // `CLAUDE_CONFIG_DIR`/`OPENCODE_CONFIG_DIR` re-emitted into the DEFAULT dir instead.
   for (const r of rows) {
-    const marker = r.marker && (EMIT_HOST_SCOPE.get(r.marker) ?? ['', ''])[0] === r.host
-      ? r.marker : '';
-    const emit = marker || DEFAULT_EMIT.get(`${r.host} ${r.scope}`) || 'opencode-global';
-    const theme = themeOfDir(r.root) || defaultTheme();
-    const out = r.scope === 'global' ? null : r.root;
-    const argv = setupBuildArgs(theme, emit, out, out, footprintOfDir(r.root),
-      postureOfDir(r.root) || defaultPosture(), modeOfDir(r.root) || defaultMode(),
-      doctrinesForBuild(r.root), PACK_ORDER, null, trustOfDir(r.root) || DEFAULT_PRESET);
+    const { emit, theme, argv } = installProfile(r.host, r.scope, r.root);
     const label = `${r.host}:${r.scope} (${r.root})`;
     printOut(`[migrate] re-emitting ${label}: theme=${theme} emit=${emit}\n`);
     let rc = 1;

package/js/maintain/setup.mjs

@@ -519,7 +519,7 @@ export function setupSummaryLines(theme, emit, out, root, ok) {
     lines.push(['ok', `${f.hookGroups} hook groups wired in ${f.settings}`]);
     if (!process.env.GENESEED_LLM) {
       lines.push(['info', 'memory learning is off until you set GENESEED_LLM '
-        + '(see docs/reference/environment.md)']);
+        + '(see docs/reference/env-context.md)']);
     }
   }
   if (emit === 'files') {