geneseed 3.12.0 → 3.14.0

package/js/hosts/hosts.mjs

@@ -228,14 +228,22 @@ export function openclaudeConfigDir() {
  * block`). It is a column and not a literal in the message for the reason every other column
  * here is one — Bob answers `AGENTS.md` while Claude answers `CLAUDE.md`, and
  * a host added later must not need the message edited to stay true.
+ *
+ * `family` joined in 2026-10: `'claude'` for every host emitted through the Claude-shaped
+ * engine — one manifest shape, one `settings.json` hook wiring, one strict-JSON `mcpServers`
+ * config, one reversal. The list had been spelled out by hand in ten places, one of which
+ * ignored the named constant right above it; a fifth host is now one row here.
  */
 export const HOSTS = [
-  { host: 'opencode', configDir: opencodeConfigDir, projectMarker: '.opencode', agentFile: 'AGENT.md' },
-  { host: 'claude', configDir: claudeConfigDir, projectMarker: '.claude', agentFile: 'CLAUDE.md' },
-  { host: 'bob', configDir: bobConfigDir, projectMarker: '.bob', agentFile: 'AGENTS.md' },
-  { host: 'openclaude', configDir: openclaudeConfigDir, projectMarker: '.openclaude', agentFile: 'CLAUDE.md' },
+  { host: 'opencode', family: 'opencode', configDir: opencodeConfigDir, projectMarker: '.opencode', agentFile: 'AGENT.md' },
+  { host: 'claude', family: 'claude', configDir: claudeConfigDir, projectMarker: '.claude', agentFile: 'CLAUDE.md' },
+  { host: 'bob', family: 'claude', configDir: bobConfigDir, projectMarker: '.bob', agentFile: 'AGENTS.md' },
+  { host: 'openclaude', family: 'claude', configDir: openclaudeConfigDir, projectMarker: '.openclaude', agentFile: 'CLAUDE.md' },
 ];
 
+/** The Claude-STYLE hosts (`family: 'claude'`), in `HOSTS` order. Test with `.includes(host)`. */
+export const CLAUDE_STYLE = HOSTS.filter((h) => h.family === 'claude').map((h) => h.host);
+
 /**
  * `_build_global.host_catalogs_natively` — does `host` list every skill and agent to the
  * model by itself?

package/js/hosts/installs.mjs

@@ -36,10 +36,10 @@ import { existsSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 
 import { CONFIG, PACK_ORDER, THEMES, discoverNames } from '../build/source.mjs';
-import { GLOBAL_MANIFEST, HOSTS, resolvePath } from './hosts.mjs';
+import { CLAUDE_STYLE, GLOBAL_MANIFEST, HOSTS, resolvePath } from './hosts.mjs';
 import { registryRoots } from '../inspect/registry.mjs';
 import { printErr, readText, isFile, isDir } from '../lib/fs.mjs';
-import { formatRepr } from '../lib/json.mjs';
+import { formatRepr, isDict } from '../lib/json.mjs';
 import { comparePaths } from '../lib/paths.mjs';
 
 /**
@@ -394,7 +394,7 @@ export function excludedRulesOfDir(d) {
 /** `_harness_mcp._claude_read_manifest`. */
 export function claudeReadManifest(cfgDir) {
   const data = readJsonMaybe(path.join(cfgDir, GLOBAL_MANIFEST));
-  return data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+  return isDict(data) ? data : {};
 }
 
 /**
@@ -403,8 +403,7 @@ export function claudeReadManifest(cfgDir) {
  * Claude-style reversal.
  */
 export function manifestIsClaude(cfgDir) {
-  const mg = claudeReadManifest(cfgDir).managed;
-  return typeof mg === 'object' && mg !== null && !Array.isArray(mg);
+  return isDict(claudeReadManifest(cfgDir).managed);
 }
 
 /** `_harness_mcp._EMIT_HOST_SCOPE` — a marker's emit name fixes (host, scope). */
@@ -454,7 +453,7 @@ export function installKind(root) {
 
 /** `_harness_mcp._install_state` — 'active' | 'disabled' | 'absent'. */
 export function installState(root, host = 'opencode', scope = 'global') {
-  if (['claude', 'bob', 'openclaude'].includes(host)) return claudeState(root, scope, host);
+  if (CLAUDE_STYLE.includes(host)) return claudeState(root, scope, host);
   if (isDir(path.join(root, DISABLED_STASH))) return 'disabled';
   return installKind(root) !== null ? 'active' : 'absent';
 }

package/js/hosts/mcp.mjs

@@ -11,12 +11,6 @@
  * `_mcp_install_targets`, `_mcp_known_names` and `_mcp_meta` are 168 lines of Python, all
  * new. The endpoints on top of them are the small half.
  *
- * AND `settings.mjs`'s ATOMIC WRITE IS NOT THIS ONE. `atomicWriteJson` is
- * `_build_settings._atomic_write_json`; `_mcp_save` is a different function with a different
- * temp suffix (`.tmp`, not `.geneseed-tmp`) that also creates the parent directory. Reusing
- * the first would be right until the moment a write fails, which is the moment the temp
- * file's name becomes the only evidence of what happened.
- *
  * THE ROUND TRIP IS THE HAZARD, and it is why every read here goes through `parseJson`.
  * `_mcp_save` rewrites the WHOLE config, not the servers map — and for a Claude global
  * install that config is `~/.claude.json`, which holds projects and history far beyond MCP
@@ -28,23 +22,23 @@
  * the wrapper rather than testing `typeof v === 'object'`. Python's `isinstance(x, dict)` is
  * false for a float; the JS twin has to be false for its wrapper.
  */
-import { existsSync, mkdirSync, renameSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-import { bobConfigDir, resolvePath } from './hosts.mjs';
+import { CLAUDE_STYLE, bobConfigDir, resolvePath } from './hosts.mjs';
 import { installState, installTargets } from './installs.mjs';
-import { printOut, printErr, readText, writeText } from '../lib/fs.mjs';
-import { isDict, jsonDumpsIndent, parseJson } from '../lib/json.mjs';
+import { printOut, printErr } from '../lib/fs.mjs';
+import { isDict } from '../lib/json.mjs';
 import { padEndToWidth } from '../lib/text.mjs';
-import { opencodeTarget, readJsonc } from './settings.mjs';
+import { atomicWriteJson, loadJsonObject, opencodeTarget } from './settings.mjs';
 
 
 /** `dict.get(key, default)`. */
 const dget = (obj, key, dflt) => (isDict(obj) && Object.hasOwn(obj, key) ? obj[key] : dflt);
 
 /** The hosts whose MCP config is strict JSON under `mcpServers`, with no `enabled` flag. */
-const FLAGLESS = ['claude', 'bob', 'openclaude'];
+const FLAGLESS = CLAUDE_STYLE;
 
 /**
  * `_harness_mcp._MCP_PRESETS` — the ready-to-wire servers the MCP screen can toggle.
@@ -68,7 +62,7 @@ export const MCP_PRESETS = {
       + 'install). Edit GITLAB_PERSONAL_ACCESS_TOKEN (scopes: api, read_repository) '
       + 'and GITLAB_API_URL before use. For a second instance (a self-hosted server), '
       + 'copy this block by hand under a new name and point it at the other URL — '
-      + 'docs/guides/mcp.md has the pattern.',
+      + 'docs/guides/mcp-gitlab.md has the pattern.',
     block: {
       type: 'local',
       command: ['npx', '-y', '@zereight/mcp-gitlab'],
@@ -175,49 +169,19 @@ export function mcpSetEnabled(config, name, enabled, host = 'opencode') {
  * version of this note said otherwise, and `generate.test.mjs` pins the string-aware case.)
  */
 export function mcpLoad(p, host = 'opencode') {
-  if (!existsSync(p)) return {};
-  let text;
-  try {
-    text = readText(p);
-  } catch {
-    return {};
-  }
-  if (FLAGLESS.includes(host)) {
-    let data;
-    try {
-      data = parseJson(text);
-    } catch {
-      return {};
-    }
-    return isDict(data) ? data : {};
-  }
-  const [data] = readJsonc(text);
-  return isDict(data) ? data : {};
+  const { state, data } = loadJsonObject(p, { strict: FLAGLESS.includes(host) });
+  return state === 'ok' ? data : {};
 }
 
 /** `_mcp_commented` — an existing `.jsonc` that carries comments, which must not be rewritten. */
 export function mcpCommented(p) {
-  if (path.extname(p) !== '.jsonc' || !existsSync(p)) return false;
-  try {
-    const [, had] = readJsonc(readText(p));
-    return had;
-  } catch {
-    return false;
-  }
+  if (path.extname(p) !== '.jsonc') return false;
+  return loadJsonObject(p).hadComments;
 }
 
-/**
- * `_mcp_save` — pretty JSON, written ATOMICALLY through a sibling temp file.
- *
- * Not `atomicWriteJson`: that is `_build_settings._atomic_write_json`, whose temp file is
- * named `.geneseed-tmp` and which does not create the parent directory. Two Python
- * functions, two twins.
- */
+/** `_mcp_save` — pretty JSON, written ATOMICALLY. The one writer, under its MCP name. */
 export function mcpSave(p, config) {
-  mkdirSync(path.dirname(p), { recursive: true });
-  const tmp = `${p}.tmp`;
-  writeText(tmp, `${jsonDumpsIndent(config)}\n`);
-  renameSync(tmp, p);
+  atomicWriteJson(p, config);
 }
 
 /**

package/js/hosts/memory-files.mjs

@@ -0,0 +1,181 @@
+/**
+ * The memory store's file format — fact files with frontmatter, the `MEMORY.md` index, the
+ * per-agent lesson files — read and written without spawning anything.
+ *
+ * SPLIT FROM `learn` FOR THE CLI's SAKE. `learn` spawns the model CLI, and the web console
+ * (`js/web/api.mjs`, `js/web/actions.mjs`), `geneseed memory` (`js/maintain/memory.mjs`) and the
+ * loop catalogue (`js/loop/catalog.mjs`) imported the hook module only for `frontmatter` and
+ * `memoryDropIndex` — which dragged `node:child_process` into `bin/geneseed-cli.mjs`'s closure
+ * and made the hook module a row in `tests/unit/hook_cli.test.mjs`'s spawn allow-list for a
+ * spawn the CLI never makes. Everything here is fs-only; `hooks-learn.mjs` is the one spawner.
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { readText, writeText } from '../lib/fs.mjs';
+import { normcase } from '../lib/paths.mjs';
+import { isFile, listDir, sortPaths, splitLines, splitWords } from './hooks-prims.mjs';
+
+const FRONTMATTER_RE = /^\s*---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/;
+const FILE_SEP_RE = /^---FILE---[^\S\n]*$/m;
+// A memory `name:` becomes a FILENAME and the model writes it, so it is a plain slug or
+// nothing — no separator, no `..`, no drive. Looser than `hooks-learn.mjs`'s AGENT_NAME_RE on
+// purpose: a memory slug is a phrase (case and length vary), and a refused one is a fact
+// silently lost.
+const MEMORY_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/;
+const MAX_AGENT_BULLETS = 100;
+
+/** `append_agent_lesson` — one dated bullet, capped at the newest MAX_AGENT_BULLETS. */
+export function appendAgentLesson(memDir, agent, lesson) {
+  const d = path.join(memDir, 'agents');
+  mkdirSync(d, { recursive: true });
+  const f = path.join(d, `${agent}.md`);
+  let bullets = [];
+  if (existsSync(f)) bullets = splitLines(readText(f)).filter((l) => l.startsWith('- '));
+  const now = new Date();
+  const day = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-`
+    + `${String(now.getDate()).padStart(2, '0')}`;
+  bullets.push(`- ${day}: ${splitWords(lesson).join(' ')}`);
+  bullets = bullets.slice(-MAX_AGENT_BULLETS);
+  writeText(f, `# ${agent} \u2014 lessons\n${bullets.join('\n')}\n`);
+  return f;
+}
+
+/**
+ * `_frontmatter` — leading YAML-ish frontmatter as a flat map, plus the body.
+ *
+ * Exported since P6b, whose `memoryItems` reads `name` and `description` off a fact file
+ * exactly as `_web_catalog._memory_items` does. That makes the web its SECOND owner, which
+ * this port treats as a coverage event rather than a tidiness one — the fields it produces
+ * are unreachable from a P6b cell (only the COUNT is consumed) and P6c's catalog cells are
+ * what gate them.
+ */
+export function frontmatter(md) {
+  const m = FRONTMATTER_RE.exec(md);
+  if (!m) return [new Map(), md];
+  const fm = new Map();
+  for (const line of splitLines(m[1])) {
+    const at = line.indexOf(':');
+    if (at >= 0) {
+      // `str.strip('"')` strips the character from BOTH ends, however many there are.
+      fm.set(line.slice(0, at).trim(), line.slice(at + 1).trim().replace(/^"+|"+$/g, ''));
+    }
+  }
+  return [fm, m[2]];
+}
+
+const fmGet = (fm, key) => (fm.has(key) ? fm.get(key) : '');
+
+/** `Path.stem` for a filename. */
+const stem = (name) => path.basename(name, path.extname(name));
+
+/** `mem_dir.glob("*.md")` — case-INSENSITIVE on Windows, as pathlib's glob is. */
+function globMd(dir) {
+  return listDir(dir).filter((n) => normcase(n).endsWith('.md')
+    && isFile(path.join(dir, n)));
+}
+
+/** `_existing_slugs` — slugs already stored, so learn never re-emits a known fact. */
+export function existingSlugs(memDir) {
+  const skip = new Set(['memory', 'readme']);
+  return new Set(globMd(memDir).map(stem).filter((s) => !skip.has(s.toLowerCase())));
+}
+
+/**
+ * `_write_memories` — split the model output into files, write each NEW one, and append a
+ * pointer line to MEMORY.md. `existing` is MUTATED, so a reply carrying the same slug
+ * twice writes it once.
+ */
+export function writeMemories(modelOutput, memDir, existing) {
+  const written = [];
+  const indexLines = [];
+  for (let chunk of modelOutput.split(FILE_SEP_RE)) {
+    chunk = chunk.trim();
+    if (!chunk || chunk.toUpperCase() === 'NOTHING') continue;
+    const [fm] = frontmatter(chunk);
+    const name = fmGet(fm, 'name').trim();
+    if (!MEMORY_SLUG_RE.test(name) || existing.has(name)) continue;
+    writeText(path.join(memDir, `${name}.md`), `${chunk.replace(/\n+$/, '')}\n`);
+    existing.add(name);
+    written.push(name);
+    const desc = fmGet(fm, 'description').trim();
+    indexLines.push(`- [${name}](${name}.md)${desc ? ` \u2014 ${desc}` : ''}`);
+  }
+  if (indexLines.length) {
+    const index = path.join(memDir, 'MEMORY.md');
+    const current = existsSync(index) ? `${readText(index).replace(/\n+$/, '')}\n`
+      : '# Memory Index\n';
+    writeText(index, `${current}${indexLines.join('\n')}\n`);
+  }
+  return written;
+}
+
+/**
+ * `_harness_tui_views._memory_drop_index` — remove the index line(s) naming `<name>.md`.
+ *
+ * ITS PYTHON HOME IS THE TUI, and it is here because this is where its SIBLINGS' twins are:
+ * `appendAgentLesson` writes the index lines this deletes and `consolidateMemory` rebuilds
+ * them, so the three rules about MEMORY.md's format live together rather than one of them
+ * living beside a web endpoint. P7 ports the TUI's memory view onto this same function.
+ *
+ * The P6f plan asked whether P5's `learn` had already brought it across. It had not —
+ * nothing in `js/` referenced it — which is the third time a plan's "already ported" column
+ * was answered by reading rather than by trusting.
+ *
+ * SUBSTRING, NOT PARSE, exactly as the reference is: any line containing `(<name>.md)` goes,
+ * so a hand-written index in a different shape still loses its entry. And the file is only
+ * REWRITTEN when something actually changed, which keeps a delete of an unindexed fact from
+ * touching the user's mtime.
+ */
+export function memoryDropIndex(memDir, name) {
+  const idx = path.join(memDir, 'MEMORY.md');
+  let lines;
+  try {
+    lines = splitLines(readText(idx));
+  } catch {
+    return;                       // the reference's `except OSError: return`
+  }
+  const keep = lines.filter((ln) => !ln.includes(`(${name}.md)`));
+  if (keep.length === lines.length) return;
+  try {
+    writeText(idx, `${keep.join('\n')}\n`);
+  } catch { /* the reference swallows OSError here too */ }
+}
+
+/**
+ * `consolidate_memory` — rebuild MEMORY.md from the fact files actually on disk: index
+ * orphans, prune dead lines, report duplicate descriptions (never auto-merge — nuance is
+ * the user's to keep).
+ */
+export function consolidateMemory(memDir) {
+  const skip = new Set(['memory', 'readme']);
+  const facts = new Map();
+  for (const name of sortPaths(globMd(memDir))) {
+    const s = stem(name);
+    if (skip.has(s.toLowerCase())) continue;
+    try {
+      facts.set(s, fmGet(frontmatter(readText(path.join(memDir, name)))[0], 'description').trim());
+    } catch { continue; }
+  }
+  const index = path.join(memDir, 'MEMORY.md');
+  const oldSlugs = new Set();
+  if (existsSync(index)) {
+    for (const line of splitLines(readText(index))) {
+      const m = /^- \[[^\]]*\]\(([^)]+)\.md\)/.exec(line.trim());
+      if (m) oldSlugs.add(m[1]);
+    }
+  }
+  const lines = ['# Memory Index', ''];
+  for (const [slug, desc] of facts) {
+    lines.push(`- [${slug}](${slug}.md)${desc ? ` \u2014 ${desc}` : ''}`);
+  }
+  writeText(index, `${lines.join('\n')}\n`);
+  const seen = new Map();
+  const dups = [];
+  for (const [slug, desc] of facts) {
+    if (desc && seen.has(desc)) dups.push([seen.get(desc), slug]);
+    if (!seen.has(desc)) seen.set(desc, slug);
+  }
+  const added = [...facts.keys()].filter((s) => !oldSlugs.has(s)).sort();
+  const pruned = [...oldSlugs].filter((s) => !facts.has(s)).sort();
+  return { added, pruned, duplicates: dups };
+}

package/js/hosts/native.mjs

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