geneseed 3.10.0 → 3.12.0

package/js/loop/state.mjs

@@ -0,0 +1,322 @@
+/**
+ * The loop engine: a state machine over a brick graph, persisted as a JSON block in LOOP.md.
+ *
+ * WHY THE MODEL NEVER DECIDES. Every transition, ceiling, score and stop is computed here; the
+ * `loop` skill only runs the node it is handed and reports the brick's outcome. That is what
+ * makes four hosts behave identically, and what makes a stopped loop explainable afterwards.
+ *
+ * WHY A BLOCKING STOP ENDS THE RUN. A background task cannot wait for a person. So "blocking"
+ * is `status: awaiting` written to LOOP.md and the run ending; the user's answer relaunches it
+ * through `decide`. Crash recovery is the same path: relaunch from the branch and LOOP.md.
+ *
+ * UNITS. Work closes into a commit whenever the graph re-enters the iteration loop's head, so
+ * setup work before the loop (a reproduction test) is its own unit — iteration 0 — and never
+ * pollutes iteration 1's write set. Every cycle inside a unit is bounded by re-entry counting:
+ * `counters` is keyed by node name (not loop name), incremented on every transition into a
+ * non-terminal, non-head node, and capped at `1 + the largest max of a non-iteration loop
+ * containing that node` (or just `1` — no re-entry at all — when no such loop covers it). That
+ * bounds a cycle through a node the model forgot to put in an inner loop (a sibling brick
+ * looping back into a retry node it isn't declared inside), not only the loop the author
+ * remembered to declare. LOOP.md itself — the engine's own state file, rewritten by every CLI
+ * 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.
+ */
+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';
+export const LOOP_FILE = 'LOOP.md';
+const slash = (p) => String(p).replaceAll('\\', '/');
+
+export function renderLoopFile(state) {
+  return `# Loop — ${state.title}\n\n${state.requirement}\n\n`
+    + 'The block below belongs to the engine. You may change `preset` (prudent, balanced, '
+    + 'aggressive) or `contracts`: they apply from the next score on.\n\n'
+    + `${BEGIN}\n\`\`\`json\n${JSON.stringify(state, null, 2)}\n\`\`\`\n${END}\n`;
+}
+
+export function parseLoopFile(text) {
+  const t = String(text).replace(/\r\n/g, '\n');
+  const a = t.indexOf(BEGIN); const b = t.lastIndexOf(END);
+  if (a < 0 || b < a) throw new Error('LOOP.md has no loop-state block');
+  const inner = t.slice(a + BEGIN.length, b).replace(/^\s*```json\s*/, '').replace(/\s*```\s*$/, '');
+  return JSON.parse(inner);
+}
+
+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)}`);
+  const loop = iterationLoop(graph);
+  const state = {
+    v: 1, title, requirement, preset, 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: [],
+  };
+  if (preset === 'prudent') { state.status = 'awaiting'; state.awaiting = { kind: 'launch' }; }
+  return state;
+}
+
+function stop(state, reason) {
+  state.status = 'stopped'; state.reason = reason;
+  return { stopped: reason };
+}
+
+function resetUnit(state) {
+  state.card = null; state.validated = false; state.counters = {}; state.visited = [];
+  state.current = {}; state.tests = 'n/a';
+}
+
+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,
+  };
+}
+
+export function trailers(state) {
+  const [silent, soft] = PRESETS[state.preset];
+  const declared = state.current.declared ?? 0;
+  return [
+    `Loop-Iteration: ${state.iteration}`,
+    `Loop-Bricks: ${[...new Set(state.visited)].join(',')}`,
+    `Loop-Risk-Declared: ${fmt(declared)}`,
+    `Loop-Risk-Actual: ${fmt(state.current.actual ?? declared)}`,
+    `Loop-Threshold: ${state.preset} ${fmt(silent)}/${fmt(soft)}`,
+    `Loop-Decision: ${state.current.decision ?? 'silent'}${state.current.amended ? ' (amended)' : ''}`,
+    `Loop-Tests: ${state.tests}`,
+  ].join('\n');
+}
+
+function finishUnit(state, committed) {
+  if (committed) {
+    state.history.push({
+      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 ?? '',
+    });
+  }
+  // The unit is committed (or was empty): the tree is clean again, so the read-brick check
+  // compares the next node against a clean status, not the last pre-commit one.
+  state.pendingVerify = false; state.resplit = false; state.snapshot = '';
+  resetUnit(state);
+  state.iteration += 1;
+  if (state.closing) { state.status = 'done'; state.node = '$close'; return; }
+  state.node = head(state);
+  const ceiling = Math.min(iterationLoop(state.graph).max, ENGINE_MAX_ITERATIONS);
+  if (state.iteration > ceiling) stop(state, `iteration ceiling of ${ceiling} reached`);
+}
+
+function commitUnit(state) {
+  const t = trailers(state); const iteration = state.iteration;
+  // Read before `finishUnit` resets the card for the next unit — the CLI needs it to name
+  // the commit message it writes to LOOP_COMMIT_MSG.
+  const intent = state.card?.intent ?? null;
+  finishUnit(state, true);
+  return { commit: true, trailers: t, iteration, intent };
+}
+
+function assertRunning(state) {
+  if (state.status !== 'running') throw new Error(`the loop is ${state.status}, not running`);
+}
+
+export function nextStep(state, bricks) {
+  if (state.status === 'awaiting') return { awaiting: state.awaiting, preset: state.preset };
+  if (state.status === 'done') return { terminal: '$close', summary: summary(state) };
+  if (state.status === 'stopped') return { terminal: '$stop', reason: state.reason, summary: summary(state) };
+  if (state.pendingVerify) return { verify: true, iteration: state.iteration, run: VERIFY_COMMAND };
+  const brick = bricks.get(state.node);
+  if (!brick) throw new Error(`no brick named ${state.node} in the catalogue`);
+  return {
+    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,
+  };
+}
+
+export function scoreDeclared(state, { actions = null, writeSet = null, intent = null } = {}) {
+  assertRunning(state);
+  if (state.pendingVerify) throw new Error('the iteration is closed: run `geneseed loop score --diff` first');
+  if (actions) {
+    state.card = {
+      ...(state.card ?? {}), intent: intent ?? state.card?.intent ?? state.node,
+      actions, writeSet: writeSet ?? state.card?.writeSet ?? [],
+    };
+  }
+  if (!state.card?.actions?.length) {
+    throw new Error('no declared actions: the identify brick records a card, or pass --actions');
+  }
+  const score = declaredRisk(state.card.actions, state.graph.weights);
+  const decision = decide(score, state.preset);
+  state.validated = true;
+  state.current.declared = score;
+  state.current.decision = worst(state.current.decision, decision);
+  if (decision === 'blocking') {
+    state.status = 'awaiting';
+    state.awaiting = { kind: 'declared', iteration: state.iteration, score, threshold: PRESETS[state.preset], card: state.card };
+  }
+  return { score, preset: state.preset, threshold: [...PRESETS[state.preset]], decision };
+}
+
+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');
+  }
+  const scored = files.filter((f) => slash(f.file) !== LOOP_FILE);
+  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.
+    if (state.closing) { finishUnit(state, false); return { empty: true, commit: false }; }
+    state.emptyStreak += 1;
+    if (state.emptyStreak >= 2) return stop(state, 'two consecutive iterations produced no diff');
+    finishUnit(state, false);
+    return { empty: true, commit: false };
+  }
+  state.emptyStreak = 0;
+  const { score, reasons } = actualRisk(state.current.declared ?? 0, scored, {
+    writeSet: state.card?.writeSet ?? [], contracts: state.contracts ?? [], overrides: state.graph.weights,
+  });
+  const decision = decide(score, state.preset);
+  state.current.actual = score;
+  state.current.decision = worst(state.current.decision, decision);
+  if (decision === 'blocking') {
+    state.status = 'awaiting';
+    state.awaiting = { kind: 'actual', iteration: state.iteration, score, reasons, threshold: PRESETS[state.preset] };
+    return { score, decision, reasons, commit: false };
+  }
+  return commitUnit(state);
+}
+
+function exhaust(state, loop) {
+  // Setup has no head to re-split into: the head belongs to the iterations after it.
+  if (isSetupUnit(state)) return stop(state, `setup ${loop.name} exhausted its max of ${loop.max}`);
+  if (state.resplit) {
+    return stop(state, `${loop.name} exhausted its max of ${loop.max} twice in iteration ${state.iteration}`);
+  }
+  state.notes.push(`iteration ${state.iteration}: ${loop.name} exhausted its max of ${loop.max}; re-split once`);
+  resetUnit(state);
+  state.resplit = true; state.snapshot = '';   // the skill stashes the attempt: clean tree
+  state.node = head(state);
+  return { discard: true, resplit: true };
+}
+
+// How many times node `v` may be entered in one unit: 1, plus the largest `max` of any
+// non-iteration loop that declares it — or just 1 (no re-entry) when no loop covers it.
+function allowedEntries(graph, v) {
+  const iteration = iterationLoop(graph);
+  let widest = null;
+  for (const m of graph.loops) {
+    if (m === iteration || !m.nodes.includes(v)) continue;
+    if (!widest || m.max > widest.max) widest = m;
+  }
+  return { allowed: widest ? 1 + widest.max : 1, loop: widest };
+}
+
+// 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).
+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 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.
+function isSetupUnit(state) {
+  return state.iteration === 0 && !iterationLoop(state.graph).nodes.includes(state.graph.start);
+}
+
+export function recordOutcome(state, bricks, outcome, { card = null, porcelain = null } = {}) {
+  assertRunning(state);
+  if (state.pendingVerify) throw new Error('the iteration is closed: run `geneseed loop score --diff` first');
+  const from = state.node;
+  const brick = bricks.get(from);
+  if (!brick) throw new Error(`no brick named ${from} in the catalogue`);
+  if (!brick.outcomes.includes(outcome)) {
+    throw new Error(`${from} cannot report ${JSON.stringify(outcome)} — one of ${brick.outcomes.join(', ')}`);
+  }
+  if (brick.effect === 'mutate' && !state.validated) {
+    throw new Error(`${from} modifies code: run \`geneseed loop score --declared\` before it, then record`);
+  }
+  const filteredPorcelain = porcelain === null ? null : filterPorcelain(porcelain);
+  if (brick.effect === 'read' && filteredPorcelain !== null && filteredPorcelain !== state.snapshot) {
+    return stop(state, `read-brick-wrote: ${from} changed the working tree`);
+  }
+  if (filteredPorcelain !== null) state.snapshot = filteredPorcelain;
+  if (card) state.card = card;
+  if (from === 'test') state.tests = outcome;
+  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}`);
+  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 }; }
+    state.status = 'done'; state.node = '$close';
+    return { done: true };
+  }
+  const h = head(state);
+  if (edge.to === h) {
+    if (mutated) { state.pendingVerify = true; state.node = h; return { verify: true }; }
+    // A read-only setup brick (no mutate visited) closes without asking for a diff score.
+    // `finishUnit` can itself hit the iteration ceiling and stop the loop — report that, not
+    // the head it was about to land on.
+    finishUnit(state, false);
+    return state.status === 'stopped' ? { stopped: state.reason } : { node: state.node };
+  }
+  state.counters[edge.to] = (state.counters[edge.to] ?? 0) + 1;
+  const { allowed, loop } = allowedEntries(state.graph, edge.to);
+  if (state.counters[edge.to] > allowed) return exhaust(state, loop ?? { name: edge.to, max: 0 });
+  state.node = edge.to;
+  return { node: edge.to };
+}
+
+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;
+  state.awaiting = null; state.status = 'running';
+  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}` : ''}`);
+  }
+  if (kind === 'declared') {
+    if (verdict === 'ok') return { resumed: true };
+    if (verdict === 'amend') { state.card = { ...state.card, amend: note }; state.current.amended = true; return { resumed: true }; }
+    if (isSetupUnit(state)) return stop(state, `setup rejected${note ? `: ${note}` : ''}`);
+    resetUnit(state); state.node = head(state);
+    return { dropped: true };
+  }
+  // kind === 'actual': the diff exists, uncommitted
+  if (verdict === 'ok') return commitUnit(state);
+  state.pendingVerify = false; state.closing = false;
+  if (verdict === 'amend') {
+    state.card = { ...state.card, amend: note };
+    // The user intervened: the decision stands as blocking, said so, and the retry budget
+    // for this unit restarts (reset counters) now that the amendment changes what it does.
+    state.current = { declared: state.current.declared, decision: 'blocking', amended: true };
+    state.counters = {};
+    // A setup unit re-runs its own brick (graph.start), never the iteration's fix brick.
+    state.node = isSetupUnit(state)
+      ? state.graph.start
+      : iterationLoop(state.graph).nodes.find((n) => bricks.get(n)?.effect === 'mutate') ?? head(state);
+    return { resumed: true };
+  }
+  if (isSetupUnit(state)) return stop(state, `setup rejected${note ? `: ${note}` : ''}`);
+  resetUnit(state); state.node = head(state); state.snapshot = '';
+  return { discard: true };
+}

package/js/maintain/migrate.mjs

@@ -35,12 +35,14 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:
 import path from 'node:path';
 
 import { main as driverMain } from '../build/driver.mjs';
-import { ROOT } from '../build/source.mjs';
+import { PACK_ORDER, ROOT } from '../build/source.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';
@@ -222,7 +224,7 @@ export function cmdMigrate(args = {}) {
     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));
+      doctrinesForBuild(r.root), PACK_ORDER, null, trustOfDir(r.root) || DEFAULT_PRESET);
     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

@@ -50,9 +50,10 @@ import { discoverNames, PACK_ORDER } from '../build/source.mjs';
 import { exportImprovements } from '../inspect/diff.mjs';
 import { cmdDoctor } from '../inspect/doctor.mjs';
 import { setupBuildArgs } from '../build/generate.mjs';
-import { GLOBAL_MANIFEST, opencodeConfigDir } from '../hosts/hosts.mjs';
+import { GLOBAL_MANIFEST, HOSTS, opencodeConfigDir } from '../hosts/hosts.mjs';
 import {
-  defaultMode, defaultPosture, defaultTheme, installedDefaults, themeFiles,
+  claudeCfg, defaultMode, defaultPosture, defaultTheme, EMIT_HOST_SCOPE, installedDefaults,
+  readJsonMaybe, themeFiles,
 } from '../hosts/installs.mjs';
 import { printOut, printErr } from '../lib/fs.mjs';
 import { which } from '../lib/paths.mjs';
@@ -457,39 +458,77 @@ export function lspPrereqs() {
     + "SDKMAN `sdk install java 21-tem`, or your distro's package"]];
 }
 
+/** The name each host goes by on screen — the same four labels `hostTools` prints. */
+const TOOL_NAME = {
+  opencode: 'OpenCode', claude: 'Claude Code', bob: 'IBM Bob', openclaude: 'OpenClaude',
+};
+
+/**
+ * Where an emit put its root file, and — for the Claude-shaped hosts — its hooks.
+ *
+ * READ BACK, NOT RE-SPELLED: the placements differ by host and scope (Bob global's preamble is
+ * `rules/geneseed.md`, a Claude project's CLAUDE.md sits beside `.claude/`, a project's hooks go
+ * to `settings.local.json`, Bob global's to `settings/settings.json`), and the emit already
+ * records each one in the install's manifest (`managed.claude_md`, `settings_file`,
+ * `settings_hooks`). A summary that recomputed them would be a second owner of every rule.
+ */
+function emitFacts(emit, out) {
+  const [host, scope] = EMIT_HOST_SCOPE.get(emit) ?? ['files', 'project'];
+  if (host === 'files' || host === 'opencode') {
+    const dir = emit === 'opencode-global' ? opencodeConfigDir() : resolveOut(out || 'Harness');
+    return { host, rootFile: path.join(dir, 'AGENT.md') };
+  }
+  const spec = HOSTS.find((h) => h.host === host);
+  const cfg = claudeCfg(scope === 'global' ? spec.configDir() : resolveOut(out || '.'), scope, host);
+  const managed = readJsonMaybe(path.join(cfg, GLOBAL_MANIFEST))?.managed ?? {};
+  const rootFile = managed.claude_md?.rel
+    ? path.resolve(cfg, managed.claude_md.rel)
+    : path.join(cfg, host === 'bob' ? path.join('rules', 'geneseed.md') : spec.agentFile);
+  return {
+    host,
+    rootFile,
+    settings: managed.settings_file ? path.join(cfg, managed.settings_file) : null,
+    hookGroups: Array.isArray(managed.settings_hooks) ? managed.settings_hooks.length : 0,
+  };
+}
+
 /**
  * `_harness_setup._setup_summary_lines` — the post-build report as `[kind, text]` rows,
  * `kind` being ok | warn | info.
  *
  * `ok` is the build's own success, so the first row is the only one that can say "build
- * failed"; every later row assumes a tree on disk. The global-install warning is the row
- * with real behaviour in it: a bundle or project emit made while an OpenCode GLOBAL install
- * exists is loaded by nothing, and saying so is the difference between a wizard and a form.
+ * failed"; every later row assumes a tree on disk. HOST-AWARE since the install-hardening
+ * pass: it used to know only OpenCode's AGENT.md, so a successful claude-global install ended
+ * on "expected AGENT.md … but it is not there" and "start a NEW OpenCode session". The
+ * global-install warning is the row with real behaviour in it: a bundle or project emit made
+ * while an OpenCode GLOBAL install exists is loaded by nothing, and saying so is the
+ * difference between a wizard and a form.
  */
 export function setupSummaryLines(theme, emit, out, root, ok) {
-  const agentMd = emit === 'opencode-global'
-    ? path.join(opencodeConfigDir(), 'AGENT.md')
-    : path.join(resolveOut(out || 'Harness'), 'AGENT.md');
+  const f = emitFacts(emit, out ?? root);
+  const name = path.basename(f.rootFile);
   const lines = [];
-  if (ok && existsSync(agentMd)) {
-    lines.push(['ok', `AGENT.md written to ${agentMd}`]);
+  if (ok && existsSync(f.rootFile)) {
+    lines.push(['ok', `${name} written to ${f.rootFile}`]);
   } else if (ok) {
-    lines.push(['warn', `expected AGENT.md at ${agentMd} but it is not there`]);
+    lines.push(['warn', `expected ${name} at ${f.rootFile} but it is not there`]);
   } else {
     lines.push(['warn', 'build failed — see the output above']);
   }
-  if (emit === 'opencode-global') {
-    const cfgDir = opencodeConfigDir();
-    const hint = process.platform === 'win32'
-      ? `learn plugin: $env:GENESEED_HARNESS = "${cfgDir}"  (persist: setx GENESEED_HARNESS "${cfgDir}")`
-      : 'learn plugin: export GENESEED_HARNESS="$HOME/.config/opencode"';
-    lines.push(['info', hint]);
-  } else if (emit === 'files') {
-    lines.push(['info', `point your tool's instructions at ${agentMd}`]);
+  if (ok && f.settings) {
+    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)']);
+    }
+  }
+  if (emit === 'files') {
+    lines.push(['info', `point your tool's instructions at ${f.rootFile}`]);
   }
   try {
     const cfg = opencodeConfigDir();
-    if (emit !== 'opencode-global' && existsSync(path.join(cfg, GLOBAL_MANIFEST))) {
+    // Only for an emit OpenCode itself would load — a Claude or Bob install is not shadowed.
+    if (['opencode', 'files'].includes(emit) && existsSync(path.join(cfg, GLOBAL_MANIFEST))) {
       lines.push(['warn', `a global install exists at ${cfg} — OpenCode loads THAT, `
         + `not this build; re-run with 'opencode-global' to change it`]);
     }
@@ -500,7 +539,12 @@ export function setupSummaryLines(theme, emit, out, root, ok) {
       lines.push(present ? ['ok', `${label} present`] : ['warn', `${label} missing — ${hint}`]);
     }
   }
-  lines.push(['info', `theme is now '${theme}' — start a NEW OpenCode session for the new voice`]);
+  const tool = TOOL_NAME[f.host];
+  lines.push(['info', tool
+    ? `theme is now '${theme}' — start a NEW ${tool} session to load it`
+    : `theme is now '${theme}' — start a NEW session in your tool to load it`]);
+  lines.push(['info', 'what was installed and what each piece does: '
+    + 'https://github.com/Arylmera/Geneseed/blob/main/docs/understand/on-your-machine.md']);
   return lines;
 }
 
@@ -593,5 +637,49 @@ export function cmdSetup() {
       + '  geneseed build --emit opencode-global --theme neutral\n');
     return 1;
   }
+  if (!toolsReport()) return 1;
   return setupLines();
 }
+
+/**
+ * The AI coding tools Geneseed installs into, as `[label, present, url]` rows in HOSTS order.
+ *
+ * PRESENT MEANS THE COMMAND IS ON PATH, and nothing else. The config dir looked like a second
+ * signal — a desktop-only install has one and no command — but GENESEED ITSELF CREATES IT: a
+ * `bob-global` emit writes `~/.bob` on a machine that never had Bob, and the first run of this
+ * check reported Bob present on exactly such a machine. A wrong "ok" sends the user to an
+ * install mode for a tool they cannot open; a wrong "not found" costs one line they can ignore.
+ *
+ * NO SPAWN, deliberately. `which` walks PATH by hand, so asking costs nothing on the CLI's
+ * child_process allow-list — a `claude --version` probe would have been a third entry there to
+ * learn nothing `which` does not already say. `lookup` is the seam for the test, which cannot
+ * rely on what this machine happens to have installed.
+ */
+export function hostTools({ lookup = which } = {}) {
+  return [
+    ['OpenCode', 'opencode', 'https://opencode.ai/docs/'],
+    ['Claude Code', 'claude', 'https://code.claude.com/docs/en/setup'],
+    ['IBM Bob', 'bob', 'https://bob.ibm.com/'],
+    ['OpenClaude', 'openclaude', 'https://openclaude.gitlawb.com/'],
+  ].map(([label, cmd, url]) => [label, Boolean(lookup(cmd)), url]);
+}
+
+/**
+ * Show which tools are here before asking anything — the install-mode question is easier to
+ * answer knowing it — and when NONE is, ask whether to stop and install one first. It never
+ * installs one: on a managed machine that is IT's call, and each tool has its own installer.
+ * A missing tool among several present is a line, not a question; nobody needs all four.
+ * `false` is the user choosing to stop.
+ */
+export function toolsReport(tools = hostTools()) {
+  printOut('AI coding tools on this machine:\n');
+  for (const [label, present, url] of tools) {
+    printOut(present ? `  ok  ${label}\n` : `  --  ${label} not on PATH — install: ${url}\n`);
+  }
+  if (tools.some(([, present]) => present)) { printOut('\n'); return true; }
+  printOut('\nNone of them is installed. Install the one you use (links above), then run setup '
+    + 'again — or go on and pick the plain bundle, which any AGENT.md tool can read.\n');
+  if (confirm('Continue without one?', false)) { printOut('\n'); return true; }
+  printOut('Stopped. Run setup again once a tool is installed.\n');
+  return false;
+}

package/js/maintain/update.mjs

@@ -50,7 +50,7 @@ import { appendText, copyFile, printOut, printErr, readText, writeText } from '.
 import { toPlatformPath, which } from '../lib/paths.mjs';
 import { WHITESPACE, parseIntStrict, stripWhitespace } from '../lib/text.mjs';
 import { NO_WINDOW } from '../lib/proc.mjs';
-import { restartDaemon } from '../web/daemon.mjs';
+import { bounceDaemonIfRunning } from '../web/daemon.mjs';
 
 /**
  * `_CREDS_RE` / `_redact_url_creds` — strip a `user[:token]@` userinfo out of any URL in
@@ -578,20 +578,9 @@ export async function rebuildBundle(here, out, theme, emit, rootDir, log) {
     { cwd: String(here), stdio: 'inherit' });
   if (proc.status !== 0) return proc.status === null ? 1 : proc.status;
   // If a web daemon is running, bounce it so the new source and the freshly rebuilt web/dist
-  // take effect — otherwise the open PWA keeps hitting the old code. EXCEPT when this
-  // upgrade IS a web-daemon job: restarting the daemon here kills the process tracking this
-  // very job (console stuck on 'running' forever); in that case the server restarts itself
-  // once the job is recorded as finished. `js/web/jobs.mjs` sets the variable; this is the
-  // side that reads it, and `upgrade/the-web-job-marker-...` is what gates the pair.
-  if (process.env.GENESEED_WEB_JOB) {
-    log('[geneseed] web daemon will restart itself after this job to load the new code.');
-    return 0;
-  }
-  try {
-    await restartDaemon(theme, 4747, false, true);
-  } catch (e) {                       // never fail an upgrade on this
-    log(`[geneseed] ⚠️  could not refresh the web daemon (${e && e.message ? e.message : e}) — \`geneseed web restart\` manually if it was running.`);
-  }
+  // take effect — otherwise the open PWA keeps hitting the old code. The web-job exception
+  // (`upgrade/the-web-job-marker-...` gates it) lives with the helper.
+  await bounceDaemonIfRunning(theme, log);
   return 0;
 }
 

package/js/ui/cli.mjs

@@ -69,7 +69,7 @@ function load() {
   try {
     return JSON.parse(readFileSync(CLI_JSON, 'utf-8'));
   } catch {
-    return { prog: 'harness', commands: [] };
+    return { prog: 'geneseed', commands: [] };
   }
 }
 
@@ -88,7 +88,7 @@ const pageArgs = (args) => (args ?? [])
 export function cliReference() {
   const data = load();
   return {
-    prog: data.prog ?? 'harness',
+    prog: data.prog ?? 'geneseed',
     commands: (data.commands ?? []).map((c) => ({
       name: c.name ?? '',
       help: c.help ?? '',

package/js/web/actions.mjs

@@ -39,6 +39,7 @@ import {
 import { withStdoutSwallowed } from '../inspect/diff.mjs';
 import { excludeAdd, excludeRemove } from '../inspect/excludes.mjs';
 import { setupBuildArgs } from '../build/generate.mjs';
+import { DEFAULT_PRESET, PRESETS } from '../loop/score.mjs';
 import { frontmatter, memoryDropIndex } from '../hosts/hooks.mjs';
 import {
   HOSTS, bobConfigDir, claudeConfigDir, expanduser, openclaudeConfigDir,
@@ -46,7 +47,7 @@ import {
 } from '../hosts/hosts.mjs';
 import {
   EMIT_HOST_SCOPE, doctrinesForBuild, excludedRulesOfDir, footprintOfDir, installState,
-  installTargets, modeOfDir, postureOfDir, readMaybe,
+  installTargets, modeOfDir, postureOfDir, readMaybe, trustOfDir,
 } from '../hosts/installs.mjs';
 import {
   MCP_PRESETS, isDict, mcpApply, mcpCommented, mcpInstallTargets, mcpKnownNames, mcpLoad,
@@ -777,6 +778,7 @@ export function apiRestore(state, files) {
       footprint: state.footprint,
       posture: state.posture,
       mode: state.mode,
+      trust: state.trust,
       // THE PACK SELECTION IS THE FIFTH, and it is the one that makes this verb a BOUNDARY
       // question rather than a cosmetic one. `expected` rendered at all four packs, and this
       // verb COPIES OUT OF IT: restoring AGENT.md onto an install built `--doctrines craft`
@@ -858,6 +860,8 @@ export function apiInstallCmd(state, body) {
   const bmode = bget(body, 'mode');
   const mode = discoverNames('modes', 'direct').includes(bmode)
     ? bmode : (modeOfDir(root) || 'direct');
+  const btrust = bget(body, 'trust');
+  const trust = Object.keys(PRESETS).includes(btrust) ? btrust : (trustOfDir(root) || DEFAULT_PRESET);
   // Unspecified means "keep what this install already has", exactly as theme, footprint,
   // posture and mode above do — a rebuild through the console is not a place to silently
   // re-decide the constitution. ⚠ AND A CARRIER WITH NO `Active packs:` MARKER (a pre-2.3
@@ -872,7 +876,7 @@ export function apiInstallCmd(state, body) {
   const excludeRules = bodyExcludeRules(body) ?? excludedRulesOfDir(root);
   const out = scope === 'global' ? null : String(root);
   const argv = setupBuildArgs(theme || 'neutral', emit, out, out, fp, pos, mode, doctrines,
-    PACK_ORDER, excludeRules);
+    PACK_ORDER, excludeRules, trust);
   return { cmd: [process.execPath, path.join(ROOT, 'bin', 'build-driver.mjs'), ...argv] };
 }
 
@@ -969,6 +973,8 @@ export function apiDeployCmd(state, body) {
   const pos = discoverNames('postures', 'peer').includes(bpos) ? bpos : 'peer';
   const bmode = bget(body, 'mode');
   const mode = discoverNames('modes', 'direct').includes(bmode) ? bmode : 'direct';
+  const btrust = bget(body, 'trust');
+  const trust = Object.keys(PRESETS).includes(btrust) ? btrust : DEFAULT_PRESET;
   // Same resolution as `apiInstallCmd` above, and for the same reason: the console's Deploy
   // form sends host/path/theme/footprint/posture/mode and NO pack selection, and nothing stops
   // it landing on a directory that already holds an install. Taking `bodyDoctrines` alone left
@@ -979,6 +985,6 @@ export function apiDeployCmd(state, body) {
   const excludeRules = bodyExcludeRules(body) ?? excludedRulesOfDir(root);
   // project-scope emit name == host name (opencode / claude / bob / openclaude)
   const argv = setupBuildArgs(theme || 'neutral', host, root, root, fp, pos, mode, doctrines,
-    PACK_ORDER, excludeRules);
+    PACK_ORDER, excludeRules, trust);
   return { cmd: [process.execPath, path.join(ROOT, 'bin', 'build-driver.mjs'), ...argv] };
 }