geneseed 3.13.0 → 3.15.0

package/js/hosts/hooks.mjs

@@ -24,8 +24,16 @@
  * for the marker filenames they need ("literals keep the hook dependency-free"), and
  * `bin/build-driver.mjs` could not be imported anyway, since its last statement runs the
  * generator. What that rule does NOT license is a second copy of a shared resolver under a
- * different name — see the primitives section below, where P5d found one that had silently
- * diverged from its twin.
+ * different name — see `./hooks-prims.mjs`, where P5d found one that had silently diverged
+ * from its twin.
+ *
+ * ONE MODULE PER VERB, BY FREQUENCY. THIS file is the gates — `git-gate`, `rule-gate`,
+ * `tool-gate`, and the `ask`/ledger/`guardGate` machinery they share — because they run on
+ * EVERY tool call. `context` (once per session) is `./hooks-context.mjs`, `learn` (on Stop) is
+ * `./hooks-learn.mjs` — the one module here that spawns — and the memory store's file format
+ * is `./memory-files.mjs`, which does not, so the CLI and the web console can read the store
+ * without reaching `child_process`. `bin/geneseed-hook.mjs` imports the verb's module only
+ * once it knows the verb, so a gate call parses no context or learn code at all.
  *
  * THE CONTRACT EVERY VERB HOLDS. Exit 0 on every path, and signal through stdout. A hook
  * that fails is a tool call that fails, so an unreadable payload, a missing file, a
@@ -39,547 +47,13 @@
  * and every file left behind. Absolute rather than compared is what let it survive the deletion
  * of the implementation it was once compared against.
  */
-import { existsSync, statSync, readFileSync, readdirSync, mkdirSync,
-  appendFileSync, writeFileSync }
-  from 'node:fs';
+import { readFileSync, appendFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { readText, writeText, printOut, printErr, withDiscardableStderr } from '../lib/fs.mjs';
-import { jsonDumpsCompact } from '../lib/json.mjs';
-import { normcase, comparePaths, toPlatformPath } from '../lib/paths.mjs';
-import { NO_WINDOW } from '../lib/proc.mjs';
-// `harness status` reports the memory store, and `bin/geneseed-cli.mjs` cannot import THIS
-// module to find it: the CLI is under a hard transitive `child_process` ban and `learn`
-// spawns. So the resolver has one owner in `js/hosts/hosts.mjs` rather than a second copy — and
-// with it went this file's private `opencodeConfigDir`, whose only caller it was.
-import {
-  GATE_LEDGER, resolveMemoryDir, resolvePath, sovereignBypass,
-} from './hosts.mjs';
+import { printOut as out, printErr as err } from '../lib/fs.mjs';
+import { normcase } from '../lib/paths.mjs';
+import { GATE_LEDGER, resolvePath, sovereignBypass } from './hosts.mjs';
 import { currentBranch, gitRootOf, loopLaunched } from './gitref.mjs';
-
-const ROOT = path.resolve(import.meta.dirname, '../..');
-
-// ---- Python path and text primitives -------------------------------------------------
-// Small, and each one is here because a JS-idiomatic equivalent differs observably.
-//
-// THE RULE, CORRECTED IN P5d. It used to read "duplicating four helpers is cheaper than
-// coupling a hook to the emitter", with `readText`/`writeText`/`normcase` as the stated
-// exceptions. That is the wrong line, and `pyStrPath` is what proved it: it was a second
-// implementation of `str(Path(p))` under a different NAME from `js/lib/fs.mjs`'s
-// `toPlatformPath`, and the two disagreed. P5c found that `path.normalize` collapses `a/../b`
-// where `PurePath` keeps it, fixed `toPlatformPath`, and gated it with a 25-path corpus — and
-// none of that reached this file, because a corpus finds what it is pointed at and nothing
-// named `pyStrPath` was. The consequence was live: `sovereignBypass` compares an
-// `excludes.json` entry against cwd, so a hand-edited `..` entry made the NODE hook stand
-// down for a repo Python still gates. `context/bypass-does-not-match-a-dotdot-entry` is
-// the cell.
-//
-// So the line is not "duplicate rather than couple" — it is "one owner for anything that
-// reproduces a language primitive, wherever it is used". `fs.mjs` carries no
-// `child_process` and costs nothing at hook latency. What stays local is what is genuinely
-// only the hook's (`fnmatch`, the transcript readers, `asOsError`'s errno table).
-//
-// AND `expanduser` WAS THE SECOND VIOLATION, closed here. This file carried its own, which
-// returned a `~user` path UNCHANGED while `js/hosts/hosts.mjs`'s single owner REFUSES the form —
-// an adjudicated product decision (`TheTildeUserFormIsADeliberateDivergence`) that the hook
-// was quietly exempt from because it had a private copy. It now imports the owner. The
-// refusal throws, so `sovereignBypass` and `cmdContext` below contain it per entry / per
-// call. For the two GATES that containment is not enough, and `guardGate` below is the
-// contract: these verbs exit 0 and signal on stdout, so "the gate blew up" and "the gate
-// found nothing" would be the SAME observation to Claude — a crash would be a silent allow.
-// A gate that cannot evaluate a call therefore asks, and says why. `resolvePath` comes from
-// `js/hosts/hosts.mjs`, which this module already imports — it had kept a private copy.
-
-// NOT imported from `js/lib/fs.mjs` (the owner everywhere else) — hot path, no new import cost.
-const isFile = (p) => { try { return statSync(p).isFile(); } catch { return false; } };
-const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
-
-/** `(p, *p.parents)` — the path and every ancestor, nearest first. */
-function selfAndParents(p) {
-  const out = [p];
-  let cur = p;
-  for (;;) {
-    const up = path.dirname(cur);
-    if (up === cur) return out;
-    out.push(up);
-    cur = up;
-  }
-}
-
-/**
- * `str.splitlines()`.
- *
- * `split('\n')` is not it: Python breaks on eleven boundaries, and a transcript or a
- * memory file carrying a form feed or U+2028 would be split by one implementation and not
- * the other. The trailing empty is dropped the way Python drops it (`"a\n"` is one line,
- * `""` is none).
- */
-function splitLines(text) {
-  if (!text) return [];
-  const parts = text.split(/\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/);
-  if (parts.length && parts[parts.length - 1] === '') parts.pop();
-  return parts;
-}
-
-/** `str.split()` with no argument — runs of whitespace, ends stripped, no empties. */
-function splitWords(s) {
-  return s.split(/\s+/).filter(Boolean);
-}
-
-/** `s[-n:]` in CODE POINTS. JS slices UTF-16 units and can cut a surrogate pair in half. */
-function tail(s, n) {
-  const cps = Array.from(s);
-  return cps.length <= n ? s : cps.slice(-n).join('');
-}
-
-/**
- * `str(OSError)` — `[Errno N] strerror: 'filename'`, with the filename REPR'd.
- *
- * This is a compared string, not a log line: `cmd_context` prints it verbatim when an
- * eager entry is missing, so `ENOENT: no such file or directory, open '…'` (Node's
- * wording, Node's quoting, no errno) is a whole-line difference in that cell. Only the
- * codes a verb here can actually raise are mapped; anything else falls back to Node's
- * message, which is at least honest about being different.
- */
-const _ERRNO = {
-  ENOENT: [2, 'No such file or directory'],
-  EACCES: [13, 'Permission denied'],
-  EISDIR: [21, 'Is a directory'],
-  ENOTDIR: [20, 'Not a directory'],
-  EPERM: [1, 'Operation not permitted'],
-};
-
-function asOsError(e, filename) {
-  const hit = _ERRNO[e && e.code];
-  if (!hit) return String((e && e.message) || e);
-  // Python reprs the filename, so a Windows path comes out with its backslashes doubled.
-  return `[Errno ${hit[0]}] ${hit[1]}: ${JSON.stringify(filename).replace(/^"|"$/g, "'")
-    .replace(/\\"/g, '"')}`;
-}
-
-/**
- * `fnmatch.fnmatch(name, pattern)` — case-folded on Windows on BOTH sides, and `*` matches
- * a separator (it is shell-glob semantics, not path-glob: `docs/*.md` really does select
- * `docs/nested/deep.md`, in both implementations).
- */
-function fnmatch(name, pattern) {
-  return fnTranslate(normcase(pattern)).test(normcase(name));
-}
-
-function fnTranslate(pat) {
-  let out = '';
-  for (let i = 0; i < pat.length; i += 1) {
-    const c = pat[i];
-    if (c === '*') { out += '[\\s\\S]*'; continue; }
-    if (c === '?') { out += '[\\s\\S]'; continue; }
-    if (c === '[') {
-      let j = i + 1;
-      if (pat[j] === '!') j += 1;
-      if (pat[j] === ']') j += 1;
-      while (j < pat.length && pat[j] !== ']') j += 1;
-      // An unterminated `[` is a LITERAL bracket in Python's translate, not an error.
-      if (j >= pat.length) { out += '\\['; continue; }
-      let body = pat.slice(i + 1, j).replaceAll('\\', '\\\\');
-      if (body.startsWith('!')) body = `^${body.slice(1)}`;
-      out += `[${body}]`;
-      i = j;
-      continue;
-    }
-    out += c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  }
-  return new RegExp(`^(?:${out})$`);
-}
-
-/** stdin, decoded as UTF-8 with Python's universal newlines. Absent stdin reads empty. */
-function readStdin() {
-  try {
-    return readFileSync(0, 'utf8').replaceAll('\r\n', '\n').replaceAll('\r', '\n');
-  } catch {
-    return '';
-  }
-}
-
-// The two output funnels, with Python's newline translation reproduced. They moved to
-// `js/lib/fs.mjs` in P5c — beside `writeText`, which is the same rule for FILES — when
-// `js/inspect/excludes.mjs` became the second caller; see that docblock for why the translation
-// exists and which gate can see it.
-const out = printOut;
-const err = printErr;
-
-// ======================================================================================
-// context — project-context discovery
-// ======================================================================================
-
-// Kept in step with adapters/opencode/plugins/geneseed-context.js, same as the Python.
-const EAGER_ROOT = ['AGENTS.md', 'AGENT.md', 'CLAUDE.md', '.cursorrules',
-  'README.md', 'CONTRIBUTING.md', 'user-rules.md', 'PROFILE.md'];
-const LAZY_DIRS = ['docs', 'doc', 'documentation', 'architecture', 'adr', 'ADR'];
-const EXCLUDE_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'vendor', '.next',
-  'target', '.venv', '__pycache__', '.opencode', '.harness']);
-
-// The root instruction file a host already loads by itself. Injecting it again pays the
-// whole harness twice per session — and was doing exactly that until 2026-09: every hooked
-// host had its own root in EAGER_ROOT. Other tools' roots stay eager (a repo carrying a
-// hand-written AGENTS.md is worth showing Claude Code); only the host's OWN is dropped.
-// The OpenCode context plugin carries the same rule for AGENT.md/AGENTS.md/CLAUDE.md.
-// OpenClaude's root file is AGENTS.md, or CLAUDE.md when AGENTS.md is absent — resolved
-// per repo in `discoverContext`, since which one it loads depends on what is on disk.
-const NATIVE_ROOT = {
-  claude: ['CLAUDE.md'], bob: ['AGENTS.md'],
-  openclaude: ['AGENTS.md', 'CLAUDE.md'],
-};
-
-// Eager injection budget: a root README of 40k chars was going out whole, every session and
-// every compaction, and cost more than the harness itself. Per-file cut at the last line
-// break under the cap; files that would push the total over the budget are listed lazy.
-const EAGER_FILE_BYTES = 16 * 1024;
-const EAGER_TOTAL_BYTES = 48 * 1024;
-
-// The files the root instruction file names for session start, relative to the HARNESS dir
-// (`--root`: `.claude/`, `.bob/`, a global config dir) — not to the repo root discovery walks,
-// which is why none of them reached a hooked host before 2026-10. Injected here so the read does
-// not depend on the model remembering it. `context.json` is not in the list: it is a manifest,
-// honoured by `resolveContextSets` (the harness dir is its last candidate). The OpenCode
-// context plugin carries the same list.
-const SESSION_FILES = ['user-rules.md', 'PROFILE.md', 'memory/MEMORY.md', 'anamnesis/MEMORY.md',
-  'notebook/NOTEBOOK.md', 'wiki.jsonc'];
-// SHA-256 of each seed body in `js/build/stubs.mjs` (`SESSION_SEEDS`), CRLF folded. A file still
-// byte-identical to its seed says nothing, so it is skipped rather than injected as noise.
-// Hashes, not an import: stubs.mjs pulls in the build's writers, and this module loads on every
-// tool call. tests/unit/claude.test.mjs gates this set, and the plugin's copy, against the seeds.
-const SEED_SHA256 = new Set([
-  '5c2e92fb1acde041e02d9ebf158460d8ff7a07cbc2b447859631604610130721', // user-rules.md
-  '29e012c3c4349ea62a9082cbd04bb25599a0ec280d62c33f6e10742809471816', // PROFILE.md
-  'cccc917c34e6b990e821620bdb4739090151885ab71b6e85046f30a3b71fa5e8', // wiki.jsonc
-  '99c786049c260f6baf7aec68a5c0f59907861afe9b867da009440613bdddb907', // MEMORY.md
-  '9acb5c9d9cb5dac572104480f05b48cc144e676869bd60e86d8a15b1f6308184', // NOTEBOOK.md
-]);
-export { SESSION_FILES, SEED_SHA256 };
-
-/**
- * The session files present under `hookRoot` and changed from their seed, as `{ rel, abs, text }`
- * (text CRLF-folded, trailing newlines trimmed). `$GENESEED_WIKI` overrides the wiki declaration,
- * as it does on OpenCode. A missing or unreadable file is simply absent — this is best-effort
- * context, never a gate.
- */
-export function sessionFiles(hookRoot) {
-  const found = [];
-  for (const rel of SESSION_FILES) {
-    let abs = path.join(hookRoot, rel);
-    if (rel === 'wiki.jsonc' && process.env.GENESEED_WIKI && isFile(process.env.GENESEED_WIKI)) {
-      abs = process.env.GENESEED_WIKI;
-    }
-    if (!isFile(abs)) continue;
-    let text;
-    try { text = readFileSync(abs, 'utf8').replace(/\r\n/g, '\n'); } catch { continue; }
-    if (SEED_SHA256.has(createHash('sha256').update(text).digest('hex'))) continue;
-    found.push({ rel, abs, text: text.replace(/\n+$/, '') });
-  }
-  return found;
-}
-
-const CLAUDE_MARKERS = ['.claude', '.bob', '.openclaude'];
-const GENESEED_MANIFEST = '.geneseed-manifest.json';
-
-/**
- * `_global_hook_standing_down` — project-bypasses-global.
- *
- * A GLOBAL install's hook passes its own dir as `--root`; when a Geneseed PROJECT install
- * of the SAME host sits at or above cwd, the project's hook injects and this one must not
- * double up.
- */
-export function globalHookStandingDown(hookRoot, cwd) {
-  const marker = path.basename(hookRoot);
-  if (!CLAUDE_MARKERS.includes(marker)) return false;
-  for (const d of selfAndParents(cwd)) {
-    const cand = path.join(d, marker);
-    if (isFile(path.join(cand, GENESEED_MANIFEST))) {
-      // Path equality, which is case-folded on Windows — `~/.claude` and `~/.Claude` are
-      // the same install there and two different ones on Linux.
-      return normcase(resolvePath(cand)) !== normcase(resolvePath(hookRoot));
-    }
-  }
-  return false;
-}
-
-// `sovereignBypass` moved to `./hosts.mjs` so `status` can read it without importing this
-// module's `child_process` binding; re-exported because the tests and the excludes writer's
-// docblock name it here.
-export { sovereignBypass };
-
-/** `_disp` — relative to the repo root when it sits under it, else verbatim. */
-function disp(pathStr, root) {
-  // `os.path.relpath` raises ValueError across drives and the Python falls back to the
-  // path as given; `path.relative` silently returns an absolute path instead, which would
-  // print a DIFFERENT string rather than the same one.
-  if (path.parse(path.resolve(pathStr)).root.toLowerCase()
-      !== path.parse(path.resolve(root)).root.toLowerCase()) {
-    return pathStr;
-  }
-  return path.relative(root, pathStr).split(path.sep).join('/');
-}
-
-/** `Path.glob`/`rglob` order: `sorted()` over paths, which is case-folded on Windows. */
-function sortPaths(list) {
-  return list.slice().sort(comparePaths);
-}
-
-function listDir(dir) {
-  try {
-    return readdirSync(dir);
-  } catch {
-    return [];
-  }
-}
-
-function rglobMd(dir, acc = []) {
-  for (const name of listDir(dir)) {
-    const full = path.join(dir, name);
-    if (isDir(full)) rglobMd(full, acc);
-    else if (isFile(full) && path.extname(name).toLowerCase() === '.md') acc.push(full);
-  }
-  return acc;
-}
-
-/**
- * `_discover_context` — the no-manifest path, mirroring the OpenCode context plugin.
- * Root entry docs are eager; other root markdown, the doc trees and monorepo package
- * READMEs are lazy.
- */
-export function discoverContext(root, host = HOST) {
-  const eager = new Map();
-  const lazy = new Map();
-  const native = host === 'openclaude' && isFile(path.join(root, 'AGENTS.md'))
-    ? ['AGENTS.md'] : NATIVE_ROOT[host] || [];
-  for (const full of sortPaths(listDir(root).map((n) => path.join(root, n)))) {
-    if (!isFile(full)) continue;
-    const name = path.basename(full);
-    if (native.includes(name)) continue;
-    if (EAGER_ROOT.includes(name)) eager.set(full, null);
-    else if (path.extname(name).toLowerCase() === '.md') lazy.set(full, null);
-  }
-  for (const d of LAZY_DIRS) {
-    const sub = path.join(root, d);
-    if (!isDir(sub)) continue;
-    for (const md of sortPaths(rglobMd(sub))) {
-      const parts = path.relative(root, md).split(/[\\/]/);
-      if (parts.some((part) => EXCLUDE_DIRS.has(part))) continue;
-      if (!eager.has(md) && !lazy.has(md)) lazy.set(md, null);
-    }
-  }
-  for (const group of ['packages', 'apps']) {
-    const base = path.join(root, group);
-    if (!isDir(base)) continue;
-    for (const pkg of sortPaths(listDir(base).map((n) => path.join(base, n)))) {
-      if (!isDir(pkg) || EXCLUDE_DIRS.has(path.basename(pkg))) continue;
-      const readme = path.join(pkg, 'README.md');
-      if (isFile(readme) && !eager.has(readme) && !lazy.has(readme)) lazy.set(readme, null);
-    }
-  }
-  return [
-    [...eager.keys()].map((p) => ({ path: p, description: '' })),
-    [...lazy.keys()].filter((p) => !eager.has(p)).map((p) => ({ path: p, description: '' })),
-  ];
-}
-
-/**
- * `_resolve_context_sets` — an explicit manifest wins, `"extend": true` layers it on top
- * of discovery, and an empty stub falls through to pure discovery.
- *
- * `recs` is a Map, not an object: JS reorders integer-like keys on a plain object, and
- * these keys are absolute paths whose iteration order becomes the printed order.
- */
-export function resolveContextSets(root, hookRoot = null) {
-  let manifest = null;
-  const env = process.env.GENESEED_CONTEXT;
-  if (env && isFile(env)) {
-    // `Path(env)`, and the label is printed — so the separators are folded exactly the
-    // way `str(Path(...))` folds them, or the source line differs by every slash in it.
-    manifest = toPlatformPath(env);
-  } else {
-    // The harness dir last: a repo's own manifest outranks the one seeded beside the install.
-    for (const cand of [path.join(root, '.harness', 'context.json'),
-      path.join(root, 'context.json'), ...(hookRoot ? [path.join(hookRoot, 'context.json')] : [])]) {
-      if (isFile(cand)) { manifest = cand; break; }
-    }
-  }
-
-  if (manifest === null) {
-    const [e, l] = discoverContext(root);
-    return [e, l, `auto-discovery [${root}]`];
-  }
-
-  let raw;
-  try {
-    raw = readText(manifest);
-  } catch (e) {
-    err(`[context] could not read ${manifest}: ${asOsError(e, manifest)}\n`);
-    return [[], [], String(manifest)];
-  }
-  let entries;
-  let extend;
-  try {
-    let data = JSON.parse(raw);
-    // Valid JSON of the wrong SHAPE, guarded on both sides — see the Python original. JS
-    // would not have thrown here (`[].context` is merely undefined), which is exactly why
-    // the guard is written out rather than left to fall out of the language: without it,
-    // the two CLIs disagree about a file a user really does hand-edit.
-    data = data && typeof data === 'object' && !Array.isArray(data) ? data : {};
-    entries = data.context || [];
-    if (!Array.isArray(entries)) entries = [];
-    extend = Boolean(data.extend);
-  } catch {
-    // See the Python original for why the decoder's own message is not quoted: the two
-    // engines disagree on the wording and on the offset, and V8 supplies no offset at all
-    // for the commonest shapes. Reporting the file is what the user needs; reporting
-    // WHICH decoder found it is what makes two implementations impossible.
-    err(`[context] ${manifest} is not valid JSON — no context was loaded `
-      + '(fix the syntax, then re-run).\n');
-    return [[], [], String(manifest)];
-  }
-
-  if (!entries.length && !extend) {
-    const [e, l] = discoverContext(root);
-    return [e, l, `auto-discovery [${root}] (empty ${path.basename(manifest)})`];
-  }
-
-  const recs = new Map();
-  const put = (pathStr, load, desc) => {
-    const prev = recs.get(pathStr);
-    recs.set(pathStr, { path: pathStr, load, description: desc || (prev ? prev.description : '') });
-  };
-
-  if (extend) {
-    const [de, dl] = discoverContext(root);
-    for (const x of de) put(x.path, 'eager', '');
-    for (const x of dl) put(x.path, 'lazy', '');
-  }
-
-  for (const entry of entries) {
-    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
-    const raw = typeof entry.path === 'string' ? entry.path.trim() : '';
-    if (!raw) continue;
-    const load = entry.load === undefined ? 'eager' : entry.load;
-    const desc = entry.description === undefined ? '' : entry.description;
-    if (raw.includes('*')) {
-      // A glob RECLASSIFIES files already known; it never pulls in new ones.
-      for (const [pathStr, rec] of [...recs.entries()]) {
-        if (fnmatch(disp(pathStr, root), raw)) put(pathStr, load, desc || rec.description);
-      }
-      continue;
-    }
-    const abs = path.isAbsolute(raw) ? raw : resolvePath(path.join(root, raw));
-    put(abs, load, desc);
-  }
-
-  const eager = [];
-  const lazy = [];
-  for (const r of recs.values()) {
-    (r.load === 'eager' ? eager : lazy).push({ path: r.path, description: r.description });
-  }
-  return [eager, lazy, String(manifest)];
-}
-
-export function cmdContext(args) {
-  setHost(args);
-  // Discovery runs against the project root the hook was launched from — Claude runs
-  // SessionStart hooks with cwd = repo root — not the harness package dir.
-  // The only two `resolvePath` calls in this file whose argument can be a `~user` path the
-  // user typed — `$GENESEED_ROOT` and `--root` — and `resolvePath` expands, so both can now
-  // throw. Every other caller either builds its argument by `path.join` from an absolute
-  // root (so no leading tilde survives) or already sits inside a `try`. Refused input
-  // injects nothing, which is the same degrade as "nothing to load" below.
-  let root;
-  let hookRoot;
-  try {
-    ({ root, hookRoot } = withDiscardableStderr(() => ({
-      root: resolvePath(process.env.GENESEED_ROOT || process.cwd()),
-      hookRoot: args.root ? resolvePath(args.root) : null,
-    })));
-  } catch {
-    return 0;
-  }
-  if (hookRoot && sovereignBypass(hookRoot)) return 0;
-  if (hookRoot && !process.env.GENESEED_STACK_GLOBAL
-      && globalHookStandingDown(hookRoot, root)) return 0;
-  const session = hookRoot ? sessionFiles(hookRoot) : [];
-  // A session file discovery would also pick up (a `user-rules.md` at the repo root of an
-  // install whose harness dir IS the repo root) is injected once, in the session block.
-  const seen = new Set(session.map((s) => normcase(path.resolve(s.abs))));
-  const fresh = (e) => !seen.has(normcase(path.resolve(path.isAbsolute(e.path)
-    ? e.path : path.join(root, e.path))));
-  let [eager, lazy, source] = resolveContextSets(root, hookRoot);
-  eager = eager.filter(fresh);
-  lazy = lazy.filter(fresh);
-  if (!session.length && !eager.length && !lazy.length) {
-    err(`[context] nothing to load for ${root} `
-      + '(no docs discovered, no manifest entries).\n');
-    return 0;
-  }
-
-  const lines = [];
-  let spent = 0;
-  if (session.length) {
-    lines.push('=== SESSION FILES \u2014 your harness files, injected at session start '
-      + '(untouched seeds skipped) ===', '');
-    for (const s of session) {
-      let text = s.text;
-      if (text.length > EAGER_FILE_BYTES) {
-        const nl = text.lastIndexOf('\n', EAGER_FILE_BYTES);
-        text = `${text.slice(0, nl > 0 ? nl : EAGER_FILE_BYTES)}\n`
-          + `[context] truncated at ${EAGER_FILE_BYTES / 1024} KB \u2014 read ${s.abs} on demand`;
-      }
-      spent += text.length;
-      lines.push(`----- ${s.rel} -----`, text, '');
-    }
-  }
-  if (eager.length || lazy.length) {
-    lines.push(`=== PROJECT CONTEXT \u2014 binding for this repo (via ${source}) ===`, '');
-  }
-  const demoted = [];
-  for (const entry of eager) {
-    const p = entry.path === undefined ? '' : entry.path;
-    const desc = entry.description === undefined ? '' : entry.description;
-    const target = path.isAbsolute(p) ? p : path.join(root, p);
-    let text;
-    try {
-      text = readText(target).replace(/\n+$/, '');
-    } catch (e) {
-      lines.push(`----- ${disp(p, root)}${desc ? ` \u2014 ${desc}` : ''} -----`,
-        `[context] MISSING eager file: ${asOsError(e, target)}`, '');
-      continue;
-    }
-    if (text.length > EAGER_FILE_BYTES) {
-      const nl = text.lastIndexOf('\n', EAGER_FILE_BYTES);
-      text = `${text.slice(0, nl > 0 ? nl : EAGER_FILE_BYTES)}\n`
-        + `[context] truncated at ${EAGER_FILE_BYTES / 1024} KB \u2014 read ${disp(p, root)} `
-        + 'on demand for the rest';
-    }
-    if (spent + text.length > EAGER_TOTAL_BYTES) {
-      demoted.push(entry);
-      continue;
-    }
-    spent += text.length;
-    lines.push(`----- ${disp(p, root)}${desc ? ` \u2014 ${desc}` : ''} -----`, text, '');
-  }
-
-  if (lazy.length || demoted.length) {
-    lines.push('--- Lazy entries (load only when the task needs them) ---');
-    for (const entry of [...lazy, ...demoted]) {
-      const p = entry.path === undefined ? '' : entry.path;
-      const desc = entry.description === undefined ? '' : entry.description;
-      const over = demoted.includes(entry)
-        ? ` (eager, but over the ${EAGER_TOTAL_BYTES / 1024} KB session budget \u2014 read on demand)` : '';
-      lines.push(`  - ${disp(p, root)}${desc ? ` \u2014 ${desc}` : ''}${over}`);
-    }
-    lines.push('');
-  }
-
-  // Claude Code takes a SessionStart hook's plain stdout as context; Bob reads it the same way.
-  out(`${lines.join('\n')}\n`);
-  return 0;
-}
+import { selfAndParents, readStdin } from './hooks-prims.mjs';
 
 // ======================================================================================
 // git-gate — Doctrine process 5's tool-boundary backstop
@@ -595,10 +69,14 @@ const GIT_GATE_RE = /\bgit\b[^\n]*\b(?:commit|push)\b/;
 // says a rule in a prompt is a request and a rule at a boundary is a constraint; before this
 // regex the harness enforced one doctrine rule and no law. `checkout --` is listed because it
 // reverts to the INDEX and eats unstaged work; `checkout <branch>` is not. `clean -f` matches
-// any flag cluster carrying `f` (`-fd`, `-xf`) and never `-n`. `push --force*` trips this gate
-// rather than process 5's so the stronger reason is the one the user reads.
+// any flag cluster carrying `f` (`-fd`, `-xf`), in any position (`clean -d -f`), and never `-n`.
+// `reset`, `clean` and `push` take their flags ANYWHERE after the verb (`reset -q --hard`,
+// `push -f origin main`), so each reads `[^\n]*` up to the flag rather than requiring it next.
+// A forced push is `--force*`, a `-f` cluster, or a `+refspec` (`push origin +main`) — the last
+// is a force push with no flag at all. `push --force*` trips this gate rather than process 5's
+// so the stronger reason is the one the user reads.
 const DESTRUCTIVE_GIT_RE =
-  /\bgit\b[^\n]*\b(?:reset\s+--hard|clean\s+-[a-zA-Z]*f|branch\s+-D|checkout\s+--\s|push\s+[^\n]*--force)/;
+  /\bgit\b[^\n]*\b(?:reset\b[^\n]*\s--hard\b|clean\b[^\n]*\s-[a-zA-Z]*f|branch\s+-D|checkout\s+--\s|push\b[^\n]*(?:\s--force|\s-[a-zA-Z]*f\b|\s\+\S))/;
 
 // `loopExempt` — a WHITELIST, not the blacklist this replaced. A false ask costs one prompt; a
 // false allow publishes. So the exemption holds only when the ENTIRE command is built from
@@ -682,22 +160,28 @@ export function loopExempt(command, cwd) {
     || SEG_READONLY_RE.test(seg) || pushSegmentOk(seg, branch));
 }
 
-/** The `permissionDecision: "ask"` document, in Python's compact `json.dumps` spelling. */
-function askDecision(reason) {
-  return `${jsonDumpsCompact({
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      permissionDecision: 'ask',
-      permissionDecisionReason: reason,
-    },
-  })}\n`;
+/**
+ * The `permissionDecision: "ask"` document, in Python's compact `json.dumps` spelling: `, ` and
+ * `: ` separators, and `ensure_ascii` — every code unit past `~` as a lowercase `\uXXXX`, which is
+ * why a reason's em dash reaches stdout as `—`.
+ *
+ * A TEMPLATE, NOT `js/lib/json.mjs`'s `jsonDumpsCompact`. The keys are fixed and the one value
+ * is a string, so the general serializer bought nothing here — and it cost every tool call a
+ * 378-line module parse, being the only thing on the gate path that needed it.
+ * `tests/unit/hook_gates.test.mjs` holds the two byte-identical over non-ASCII reasons.
+ */
+export function askDecision(reason) {
+  const value = JSON.stringify(reason)
+    .replace(/[\u007f-￿]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+  return '{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "ask", '
+    + `"permissionDecisionReason": ${value}}}\n`;
 }
 
 /**
  * The host reading this process's verdict — `--host` on the emitted command, `claude` when
  * absent. Module state rather than a parameter because a hook process answers exactly one
- * call: set once at the verb's entry (`guardGate`, `cmdContext`), read where the output
- * dialect is chosen.
+ * call: set once at the gate's entry (`guardGate`), read where the output dialect is chosen.
+ * `./hooks-context.mjs` keeps its own for the same reason.
  */
 let HOST = 'claude';
 const setHost = (args) => { HOST = (args && args.host) || 'claude'; };
@@ -867,9 +351,11 @@ function ruleGateTarget(p, root) {
 
 // Law I's boundary half. High-precision vendor prefixes only — a generic "looks like entropy"
 // scan would fire on every hash and lockfile, and a gate that cries wolf gets allow-listed.
-// `.env*` is exempt because Law I names it as the place a secret may live.
+// `.env*` is exempt because Law I names it as the place a secret may live. `sk-ant-` takes `_`:
+// Anthropic keys are base64url, and a key whose first `_` fell inside the first 20 characters
+// slipped through. GitHub's classic `ghp_` tokens really are alphanumeric only.
 const SECRET_RE =
-  /\b(?:AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,}|sk-ant-[A-Za-z0-9-]{20,}|xox[abprs]-[0-9A-Za-z-]{10,})\b|-----BEGIN [A-Z ]*PRIVATE KEY-----/;
+  /\b(?:AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,}|sk-ant-[A-Za-z0-9_-]{20,}|xox[abprs]-[0-9A-Za-z-]{10,})\b|-----BEGIN [A-Z ]*PRIVATE KEY-----/;
 const DOTENV_RE = /(^|[\\/])\.env(\.[^\\/]*)?$/;
 
 function ruleGate(args) {
@@ -879,11 +365,14 @@ function ruleGate(args) {
 
 function ruleDecide(args, payload) {
   const ti = (payload && payload.tool_input) || {};
-  const p = ti.file_path || ti.path || '';
+  // NotebookEdit names its target `notebook_path`; the settings matcher routes it here too.
+  const p = ti.file_path || ti.path || ti.notebook_path || '';
   if (typeof p !== 'string' || !p) return 0;
-  // Write carries `content`, Edit carries `new_string`; either can plant a credential.
-  const body = [ti.content, ti.new_string]
-    .find((v) => typeof v === 'string') || '';
+  // Write carries `content`, Edit `new_string`, NotebookEdit `new_source`, MultiEdit an
+  // `edits[]` of `new_string`s — every one can plant a credential, so every one is scanned.
+  const edits = Array.isArray(ti.edits) ? ti.edits.map((e) => e && e.new_string) : [];
+  const body = [ti.content, ti.new_string, ti.new_source, ...edits]
+    .filter((v) => typeof v === 'string').join('\n');
   if (body && !DOTENV_RE.test(p) && SECRET_RE.test(body)) {
     return ask(args, 'rule-gate', 'law-1', `Geneseed (Sealed Secrets) — ${p} would carry a `
       + 'credential-shaped string. Secrets live in .env or a secret manager, never in a '
@@ -915,419 +404,3 @@ function toolGate(args) {
   return typeof ti.command === 'string' ? gitDecide(args, payload) : ruleDecide(args, payload);
 }
 export const cmdToolGate = guardGate(toolGate, 'tool-gate');
-
-// ======================================================================================
-// learn — distil notes/transcripts into deduped memory entries
-// ======================================================================================
-
-const FRONTMATTER_RE = /^\s*---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/;
-const FILE_SEP_RE = /^---FILE---[^\S\n]*$/m;
-const AGENT_NAME_RE = /^[a-z][a-z0-9-]{1,40}$/;
-const MAX_AGENT_BULLETS = 100;
-const MAX_NOTES_CHARS = 16000;
-// Host payloads name the finished subagent inconsistently; try each.
-const SUBAGENT_NAME_FIELDS = ['agent_name', 'agent_type', 'subagent_type', 'agent',
-  'agent_id'];
-
-const PLUGIN_LEARN = path.join(ROOT, 'adapters', 'opencode', 'plugins', 'geneseed-learn.js');
-
-/**
- * `_load_learn_prompt_head` / `_load_agent_lesson_prompt`.
- *
- * The single source of truth for both prompts is the OpenCode plugin — the artifact that
- * ships to the primary runtime — and both CLIs extract the template literal from its
- * SOURCE rather than keeping a copy. Reading it means this port cannot drift from the
- * plugin either; a copied constant here would be a third place to edit.
- */
-function pluginLiteral(name, fallback) {
-  try {
-    const m = new RegExp(`const ${name} = \`([\\s\\S]*?)\``).exec(readText(PLUGIN_LEARN));
-    if (m) return m[1];
-  } catch { /* unreadable plugin must never crash a Stop hook */ }
-  return fallback;
-}
-
-export const LEARN_PROMPT_HEAD = pluginLiteral('LEARN_PROMPT_HEAD',
-  'Distil at most one durable, reusable memory from the notes below. '
-  + 'When in doubt, output exactly: NOTHING.');
-const AGENT_LESSON_PROMPT = pluginLiteral('AGENT_LESSON_PROMPT',
-  'Output AT MOST ONE line: a durable lesson about how this agent should '
-  + 'operate on a future dispatch. Else output exactly: NOTHING.');
-
-/** `resolve_agent_name` — a safe agent slug from a raw field value, or null. */
-export function resolveAgentName(raw) {
-  const name = typeof raw === 'string' ? raw.trim().toLowerCase() : null;
-  return name && AGENT_NAME_RE.test(name) ? name : null;
-}
-
-/** `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;
-}
-
-/** The lifecycle-hook payload if stdin is one, else `{}`. */
-function hookMeta(raw) {
-  const s = raw.trim();
-  if (s.slice(0, 1) !== '{') return {};
-  try { return JSON.parse(s); } catch { return {}; }
-}
-
-/** Flatten a message `content` field (string, or a list of blocks) to text. */
-function contentText(content) {
-  if (typeof content === 'string') return content;
-  if (Array.isArray(content)) {
-    const parts = [];
-    for (const block of content) {
-      if (typeof block === 'string') parts.push(block);
-      else if (block && typeof block === 'object' && block.type === 'text') {
-        parts.push(block.text === undefined ? '' : block.text);
-      }
-    }
-    return parts.join('\n');
-  }
-  return '';
-}
-
-/** Render a Claude-Code-style JSONL transcript into `role: text` notes. */
-function flattenTranscript(p) {
-  let raw;
-  try {
-    // `errors="replace"`: Node's utf8 decoder already substitutes U+FFFD.
-    raw = readText(p);
-  } catch {
-    return '';
-  }
-  const acc = [];
-  for (let line of splitLines(raw)) {
-    line = line.trim();
-    if (!line) continue;
-    let obj;
-    try { obj = JSON.parse(line); } catch { continue; }
-    const msg = obj.message || {};
-    const role = msg.role || obj.role || obj.type;
-    if (role !== 'user' && role !== 'assistant') continue;
-    const text = contentText(msg.content === undefined ? obj.content : msg.content).trim();
-    if (text) acc.push(`${role}: ${text}`);
-  }
-  return acc.join('\n\n');
-}
-
-/**
- * `_read_notes` — a lifecycle-hook payload with a `transcript_path` is read and flattened
- * (this is what makes wiring `learn` to a Stop hook work with no redirection); anything
- * else is used as-is.
- */
-/**
- * EXPORTED FOR THE UNIT TIER, and the rule this follows is written down once here for the three
- * `learn` helpers below it.
- *
- * `docs/specs`'s P3 rule is: drive a property through the PUBLIC entry by default, and export a
- * decision only when the property is invisible through that face. The `learn` verb's WIRING is
- * already gated — 78 cells in the CLI matrix drive it end to end — so what a unit test would add
- * there is nothing. What no cell can see is these three functions' behaviour on inputs a cell
- * cannot produce: a model that answers NOTHING, a duplicate slug, a `README.md` beside the
- * store, a transcript payload that is not JSON. Those are decisions over text, and the corpus
- * reaches none of them.
- */
-export function readNotes(raw) {
-  const s = raw.trim();
-  if (!s) return '';
-  if (s[0] === '{') {
-    let payload;
-    try { payload = JSON.parse(s); } catch { return raw; }
-    const tp = payload && payload.transcript_path;
-    if (tp) return flattenTranscript(tp);
-    return raw;
-  }
-  return raw;
-}
-
-// `resolveMemoryDir` moved to `js/hosts/hosts.mjs` in P5d — see the import at the top of this
-// file. Re-exported here so the hook entry's own import list does not change.
-export { resolveMemoryDir };
-
-/**
- * `_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())));
-}
-
-function buildLearnPrompt(notes, existing) {
-  const parts = [LEARN_PROMPT_HEAD, ''];
-  if (existing.size) {
-    parts.push('ALREADY STORED \u2014 do NOT emit a memory matching any of these '
-      + 'slugs (skip updates too; only genuinely new facts):');
-    parts.push(...[...existing].sort().map((slug) => `- ${slug}`));
-    parts.push('');
-  }
-  parts.push('NOTES:', notes);
-  return parts.join('\n');
-}
-
-/**
- * `_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 (!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 };
-}
-
-/**
- * The model CLI, run as `$GENESEED_LLM`'s words plus the prompt.
- *
- * `encoding="utf-8"` on the Python side and `'utf8'` here, never the console code page: a
- * distilled memory carrying an accent or an em dash is WRITTEN to the store, so a
- * mis-decode outlives the process. `maxBuffer` is lifted off Node's 1 MB default, which
- * would truncate a long reply into a silently-half-parsed set of memory files.
- */
-function runLlm(llm, prompt) {
-  const argv = splitWords(llm);
-  // `_harness_learn.py:85` runs this through the wrapped `run(..., capture_output=True)`,
-  // which folds in `CREATE_NO_WINDOW`; a model CLI invoked from the windowless daemon
-  // otherwise pops a console for as long as it takes to answer.
-  const proc = spawnSync(argv[0], [...argv.slice(1), prompt],
-    { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, ...NO_WINDOW });
-  // Universal newlines, because Python reads the pipe in TEXT mode: a model CLI that is
-  // itself a Python script emits CRLF on Windows, `subprocess` folds it to `\n`, and
-  // `write_text` expands it again on the way into the memory file. Node hands back the raw
-  // bytes, so without this the stored fact is written with `\r\r\n` on every line.
-  const universal = (s) => (s === null || s === undefined ? ''
-    : String(s).replaceAll('\r\n', '\n').replaceAll('\r', '\n'));
-  return {
-    stdout: universal(proc.stdout),
-    stderr: universal(proc.stderr),
-    // A spawn that never started is Python's FileNotFoundError, which propagates there;
-    // here it surfaces as a non-zero code with the reason on stderr rather than a stack.
-    returncode: proc.error ? 1 : (proc.status === null ? 1 : proc.status),
-    error: proc.error,
-  };
-}
-
-/**
- * `_learn_agent_lesson` — the SubagentStop path: at most one per-agent lesson into
- * `memory/agents/<name>.md`. Skips silently when the host does not name the subagent:
- * parity of mechanism, degrading to a no-op, never a crash.
- */
-function learnAgentLesson(meta, notes, args) {
-  let agent = null;
-  for (const field of SUBAGENT_NAME_FIELDS) {
-    agent = resolveAgentName(meta[field]);
-    if (agent) break;
-  }
-  if (!agent) return 0;
-  const memDir = resolveMemoryDir(args.memory);
-  if (!memDir) return 0;
-  const prompt = [AGENT_LESSON_PROMPT, '', 'NOTES:', notes].join('\n');
-  const llm = process.env.GENESEED_LLM;
-  if (!llm) {
-    err('[learn] $GENESEED_LLM unset \u2014 printing agent-lesson prompt.\n\n');
-    out(`${prompt}\n`);
-    return 0;
-  }
-  const proc = runLlm(llm, prompt);
-  const text = proc.stdout.trim();
-  if (text && text.toUpperCase() !== 'NOTHING') {
-    const lesson = splitLines(text)[0].replace(/^[-*]+/, '').trim();
-    const n = Array.from(lesson).length;   // code points, as `len()` counts them
-    if (n >= 10 && n <= 300) {
-      err(`[learn] agent lesson -> ${appendAgentLesson(memDir, agent, lesson)}\n`);
-    }
-  }
-  if (proc.returncode !== 0 && proc.stderr) err(proc.stderr);
-  return proc.returncode;
-}
-
-export function cmdLearn(args) {
-  if (args.consolidate) {
-    const memDir = resolveMemoryDir(args.memory);
-    if (!memDir) {
-      err('[learn] no memory store found \u2014 nothing to consolidate.\n');
-      return 0;
-    }
-    const report = consolidateMemory(memDir);
-    err(`[learn] consolidated ${memDir}: +${report.added.length} indexed, `
-      + `-${report.pruned.length} pruned, `
-      + `${report.duplicates.length} duplicate description(s)\n`);
-    for (const [a, b] of report.duplicates) err(`  duplicate: ${a} <-> ${b}\n`);
-    return 0;
-  }
-
-  // The Stop/SubagentStop hook always passes `--memory <cfg>/memory`; inside an excluded
-  // folder the global install must not learn.
-  if (args.memory && sovereignBypass(path.dirname(toPlatformPath(args.memory)))) return 0;
-
-  const raw = args.file ? readText(args.file) : readStdin();
-  let notes = readNotes(raw);
-  if (!notes.trim()) {
-    err('[learn] no notes or transcript content \u2014 nothing to distil.\n');
-    return 0;
-  }
-  notes = tail(notes, MAX_NOTES_CHARS);   // keep the tail: most recent, most durable
-
-  const meta = hookMeta(raw);
-  if (meta.hook_event_name === 'SubagentStop') return learnAgentLesson(meta, notes, args);
-
-  const memDir = resolveMemoryDir(args.memory);
-  const existing = memDir ? existingSlugs(memDir) : new Set();
-  const prompt = buildLearnPrompt(notes, existing);
-
-  const llm = process.env.GENESEED_LLM;
-  if (!llm) {
-    err('[learn] $GENESEED_LLM unset \u2014 printing prompt instead.\n\n');
-    out(`${prompt}\n`);
-    return 0;
-  }
-
-  const proc = runLlm(llm, prompt);
-  const output = proc.stdout;
-  if (memDir && output.trim() && output.trim().toUpperCase() !== 'NOTHING') {
-    const written = writeMemories(output, memDir, existing);
-    if (written.length) {
-      err(`[learn] wrote ${written.length} memory file(s) to `
-        + `${memDir}: ${written.join(', ')}\n`);
-    } else {
-      err('[learn] nothing new to store (all duplicates).\n');
-    }
-  } else {
-    out(output);
-  }
-  if (proc.returncode !== 0 && proc.stderr) err(proc.stderr);
-  return proc.returncode;
-}