geneseed 3.2.0 → 3.3.0

package/adapters/opencode/plugins/geneseed-guard.js

@@ -60,6 +60,36 @@ const WARN_ONLY = MODE === "warn"
 
 function log(msg) { console.error(`[geneseed-guard] ${msg}`) }
 
+// ---- the gate ledger ------------------------------------------------------------
+// The twin of `ledger()` in js/hosts/hooks.mjs: one JSON line per BLOCK into
+// `<cfg>/notebook/gates.jsonl`, the rule and never the content, so `geneseed status` can
+// count what the boundary actually caught on an OpenCode install too. Until this the
+// recommended install was the one with no gate evidence at all. A warning is not recorded
+// (nothing was refused) and neither is `GENESEED_GUARD=warn`. `notebook/` is never created
+// here — an install without one (or a test importing this file) records nothing. Capped
+// at the newest MAX_LEDGER_LINES like the hook's; never throws, never decides.
+const MAX_LEDGER_LINES = 1000
+async function ledger(rule) {
+  try {
+    const bases = []
+    if (process.env.GENESEED_HARNESS) bases.push(process.env.GENESEED_HARNESS)
+    bases.push(path.dirname(PLUGIN_DIR))
+    for (const base of bases) {
+      const dir = path.join(base, "notebook")
+      if (!(await isDir(dir))) continue
+      const file = path.join(dir, "gates.jsonl")
+      await fs.appendFile(file, `${JSON.stringify({
+        ts: new Date().toISOString(), verb: "guard", rule, cwd: process.cwd(),
+      })}\n`)
+      const lines = (await fs.readFile(file, "utf8")).split("\n").filter(Boolean)
+      if (lines.length > MAX_LEDGER_LINES) {
+        await fs.writeFile(file, `${lines.slice(-MAX_LEDGER_LINES).join("\n")}\n`)
+      }
+      return
+    }
+  } catch { /* the ledger never decides */ }
+}
+
 // Files the agent must not write (secrets / private keys) → BLOCK.
 const SECRET_RE = [
   /(^|\/)id_(rsa|ed25519|ecdsa|dsa)(\.pub)?$/i,
@@ -119,6 +149,7 @@ const hasAny = (name, parts) => parts.some((s) => name.includes(s))
 // per wiki. Mutating anything under one is denied. Same resolution chain as the
 // context plugin: $GENESEED_WIKI -> $GENESEED_HARNESS/wiki.jsonc -> beside the install.
 async function isFile(p) { try { return (await fs.stat(p)).isFile() } catch { return false } }
+async function isDir(p) { try { return (await fs.stat(p)).isDirectory() } catch { return false } }
 
 // wiki.jsonc is JSONC (the seeded stub carries a commented example): strip // and
 // /* */ comments plus trailing commas before parsing — string-aware, so quoted
@@ -243,22 +274,25 @@ export const GeneseedGuard = async () => {
       if (await sovereignBypass(process.cwd())) return
       const tool = (input?.tool || input?.name || "").toLowerCase()
       const args = output?.args || input?.args || {}
-      const deny = (why) => {
+      // `rule` is the ledger key, spelled as js/hosts/hooks.mjs spells it (`law-1`,
+      // `law-4`, `process-1`) plus `wiki`, so status counts one vocabulary across hosts.
+      const deny = async (why, rule) => {
         if (WARN_ONLY) { log(`WARN (would block): ${why}`); return false }
         log(`BLOCKED: ${why}`)
+        await ledger(rule)
         throw new Error(`[geneseed-guard] blocked: ${why} — set GENESEED_GUARD=off to allow`)
       }
       try {
         if (hasAny(tool, WRITE_TOOLS)) {
           const p = pickPath(args)
-          if (p && SECRET_RE.some((re) => re.test(p))) { deny(`write to secret/key file ${p} (Law I)`); return }
+          if (p && SECRET_RE.some((re) => re.test(p))) { await deny(`write to secret/key file ${p} (Law I)`, "law-1"); return }
           if (p && SECRET_WARN_RE.some((re) => re.test(p))) log(`WARN: writing ${p} — keep secrets out of tracked files (Law I)`)
           const store = p && ruleStoreTarget(p)
           if (store && !RULE_STORE_BUMPED.has(p)) {
             RULE_STORE_BUMPED.add(p)
-            deny(`writing to ${store} — a standing rule, or a fact to remember? That ` +
+            await deny(`writing to ${store} — a standing rule, or a fact to remember? That ` +
                  `choice is the user's (Doctrine process 1). Settle it through the rule skill, ` +
-                 `then re-issue this write`)
+                 `then re-issue this write`, "process-1")
             return
           }
         }
@@ -268,14 +302,14 @@ export const GeneseedGuard = async () => {
             const abs = (path.isAbsolute(p) ? p : path.resolve(p)).replace(/\\/g, "/").toLowerCase()
             const hit = (await protectedPrefixes()).find(
               (x) => abs.startsWith(x.prefix) || abs === x.prefix.slice(0, -1))
-            if (hit) { deny(`mutation in protected wiki folder — ${hit.label} (AGENT.md §8)`); return }
+            if (hit) { await deny(`mutation in protected wiki folder — ${hit.label} (AGENT.md §8)`, "wiki"); return }
           }
         }
         // NOT else-if: a compound tool name (e.g. exec_and_save) can match both
         // classes, and the shell check must still run after the write check.
         if (hasAny(tool, SHELL_TOOLS)) {
           const c = pickCommand(args)
-          if (c && SHELL_BLOCK_RE.some((re) => re.test(c))) { deny(`catastrophic command (Law IV): ${c.slice(0, 80)}`); return }
+          if (c && SHELL_BLOCK_RE.some((re) => re.test(c))) { await deny(`catastrophic command (Law IV): ${c.slice(0, 80)}`, "law-4"); return }
           if (c && SHELL_WARN_RE.some((re) => re.test(c))) log(`WARN: irreversible op — confirm intent (Law IV): ${c.slice(0, 80)}`)
         }
       } catch (err) {

package/bin/build-driver.mjs

@@ -42,7 +42,7 @@ import { parseArgs as nodeParseArgs } from 'node:util';
 import { build, phaseLog } from '../js/build/bundle.mjs';
 import { emitClaudeRender } from '../js/build/emit-claude.mjs';
 import { emitOpencodeRender, emitOpencodeGlobalRender } from '../js/build/emit-opencode.mjs';
-import { settingsIntegrityCheck } from '../js/hosts/settings.mjs';
+import { copilotIntegrityCheck, settingsIntegrityCheck } from '../js/hosts/settings.mjs';
 import { writeText, withPlatformNewlines, isFile } from '../js/lib/fs.mjs';
 import { parseJson, jsonDumpsIndent } from '../js/lib/json.mjs';
 // P5c moved these out of this file: `bin/geneseed-cli.mjs` needs the same four resolvers to
@@ -848,8 +848,8 @@ function emitClaudeCore(cfg, args, { cfgDir, claudeMd, scope, host, out, hookOpt
   // VERIFY — re-read the settings file just written and match it against the claims just
   // recorded, so a merge that silently did not stick (a commented file, a mid-flight
   // external edit, a bug in the merge) is loud now instead of surfacing as hooks that
-  // quietly never fire. Skipped for Copilot, which writes no settings file at all
-  // (`_emit_claude_core:827`) — the other half of why Copilot could cross first.
+  // quietly never fire. Copilot's settings have their own shape and their own check; a
+  // Copilot PROJECT emit records no hooks and so checks nothing.
   //
   // On the Python driver this stage runs in Python AFTER a Node child did the wiring, which
   // makes it a live cross-implementation check on every build. Here both halves are Node, so
@@ -860,15 +860,17 @@ function emitClaudeCore(cfg, args, { cfgDir, claudeMd, scope, host, out, hookOpt
   // SILENT ON SUCCESS, which is its own coverage hazard: a clean emit prints nothing, so
   // deleting this call is byte-identical in all 259 cells. `test_verify_reports_an_orphaned
   // _geneseed_hook` plants the fault that makes it speak.
+  phaseLog('VERIFY');
   if (!isCopilot) {
-    phaseLog('VERIFY');
     settingsIntegrityCheck(
       path.join(cfgDir, managed.settings_file || 'settings.json'), managed, 'present');
+  } else if (managed.copilot_hooks) {
+    copilotIntegrityCheck(path.join(cfgDir, 'settings.json'), managed.copilot_hooks, 'present');
   }
   return {
     nAgents: stats.nAgents,
     nSkills: stats.nSkills,
-    nHooks: (managed.settings_hooks || []).length,
+    nHooks: (managed.settings_hooks || managed.copilot_hooks || []).length,
     memStatus,
     nbStatus,
   };
@@ -883,7 +885,8 @@ function emitCopilot(cfg, args, out) {
   });
   process.stdout.write(`[geneseed] copilot (folder) -> ${root}: AGENTS.md + .github/ `
     + `(${r.nAgents} agents (.agent.md), ${r.nSkills} skills), ${r.memStatus}, `
-    + `${r.nbStatus}. No settings.json/hooks (Copilot has none).\n`);
+    + `${r.nbStatus}. No hooks at project scope (Copilot reads hooks from `
+    + '~/.copilot/settings.json only — the global emit wires them).\n');
   return cfgDir;
 }
 
@@ -891,14 +894,17 @@ function emitCopilot(cfg, args, out) {
 function emitCopilotGlobal(cfg, args, out) {
   const cfgDir = args.cfgDir ?? copilotConfigDir();
   warnCopilotGlobalOverProject();
+  // The hook runner pair, as for Claude and Bob: the global emit is the one Copilot scope
+  // that wires hooks (`~/.copilot/settings.json`), and the shim it bakes is machine-wide.
+  const hookOpts = hookRunnerEntry();
   const r = emitClaudeCore(cfg, args, {
     cfgDir, claudeMd: path.join(cfgDir, 'copilot-instructions.md'),
-    scope: 'global', host: 'copilot', out,
+    scope: 'global', host: 'copilot', out, hookOpts,
   });
   process.stdout.write(`[geneseed] copilot-global -> ${cfgDir}: ${r.nAgents} agents (.agent.md), `
-    + `${r.nSkills} skills, copilot-instructions.md, ${r.memStatus}, ${r.nbStatus}. `
-    + 'No settings.json/hooks (Copilot has no hook mechanism — memory rides the '
-    + "preamble's instructions); MCP servers go in mcp-config.json.\n");
+    + `${r.nSkills} skills, copilot-instructions.md, ${r.memStatus}, ${r.nbStatus}, `
+    + `${r.nHooks} hooks (settings.json: sessionStart context, toolCall gate). Memory `
+    + "write-back rides the preamble's instructions; MCP servers go in mcp-config.json.\n");
   return cfgDir;
 }
 

package/bin/geneseed-cli.mjs

@@ -41,32 +41,22 @@
  * keeps the two tables from ever answering the same verb twice, since the shim bakes only one
  * of them.
  *
- * P6h MADE THE DISPATCH ASYNCHRONOUS and put `js/web/` on this entry's import graph. Both
- * are noted where they happen (`main`'s `await`, and the `web` row below); the consequence
- * for the file as a whole is that its transitive imports now reach two modules that spawn,
- * which `_ALLOWED_SPAWNS` in `tests/test_hook_cli_parity.py` declares argv by argv.
+ * P6h MADE THE DISPATCH ASYNCHRONOUS and put `js/web/` on this entry's import graph — LAZILY,
+ * since the slim pass: every command module loads through its verb's thunk, so the graph is
+ * reached per verb rather than per invocation. The modules that spawn are still declared argv
+ * by argv in `ALLOWED_SPAWNS` (`tests/unit/hook_cli.test.mjs`), whose closure walk follows
+ * the dynamic spelling too.
  */
-import { cmdCatalog } from '../js/build/catalog.mjs';
+// THE FOUR EAGER IMPORTS ARE THE PARSER'S OWN, AND NOTHING ELSE LOADS BEFORE DISPATCH.
+// The twenty command modules used to be static imports, which made every invocation pay for
+// all of them: `geneseed status` loaded the web daemon, the TUI, the updater and the whole
+// build driver — 57 modules, ~1 MB, ~40-55 ms — before a byte of its own work. The verb
+// table below now holds one LOADER per row (`() => import(…).then(m => m.cmdX)`), so a verb
+// loads its slice of the tree and no other verb's. The spawn allow-list gate still sees the
+// whole graph: `tests/unit/hook_cli.test.mjs`'s `importClosure` follows both import spellings.
 import { cliSpec, printHelp } from '../js/ui/cli.mjs';
-import { cmdDiff } from '../js/inspect/diff.mjs';
-import { cmdDoctor } from '../js/inspect/doctor.mjs';
-import { cmdValidate } from '../js/inspect/validate.mjs';
-import { parseDriverArgs } from './build-driver.mjs';
-import { cmdExclude } from '../js/inspect/excludes.mjs';
-import { cmdBuild, cmdPrompt, cmdRebuildAll, cmdTheme } from '../js/build/generate.mjs';
-import { cmdMigrate } from '../js/maintain/migrate.mjs';
 import { parseIntStrict } from '../js/lib/text.mjs';
 import { printErr } from '../js/lib/fs.mjs';
-import { cmdLink, cmdUnlink } from '../js/hosts/link.mjs';
-import { cmdMcp } from '../js/hosts/mcp.mjs';
-import { cmdMemory } from '../js/maintain/memory.mjs';
-import { cmdHome, cmdMenu } from '../js/ui/menu.mjs';
-import { cmdTui } from '../js/ui/tui.mjs';
-import { cmdSetup } from '../js/maintain/setup.mjs';
-import { cmdStatus, cmdVersion } from '../js/inspect/status.mjs';
-import { cmdUninstall } from '../js/maintain/uninstall.mjs';
-import { cmdBootstrap, cmdSyncSelf, cmdUpgrade } from '../js/maintain/update.mjs';
-import { cmdWeb } from '../js/web/server.mjs';
 
 /**
  * The verbs this entry answers — and, since P10c, NOTHING ELSE ABOUT THEM.
@@ -85,30 +75,30 @@ import { cmdWeb } from '../js/web/server.mjs';
  * `main`'s refusal lists `Object.keys(VERBS)` IN THIS ORDER, which `harness_golden` cells
  * assert verbatim — the order is the old table's and is not alphabetical.
  *
- * FLATTENED TO `verb: fn` since Task 5: every row was a single-field `{ fn: cmdX }` object,
- * the one field this table has left after `positionals`/`options`/`flags`/etc moved to
- * `js/cli-table.json` above. `main` reads `VERBS[verb]` directly rather than
- * `VERBS[verb].fn` now; the scraping regexes in `tests/unit/{cli_table,hook_cli,docs}.test.mjs`
- * match on the KEY and the colon only; the literal string `const VERBS = {` and the key
- * order neither changed.
+ * FLATTENED TO `verb: fn` since Task 5, AND TO `verb: loader` since the lazy pass: every row
+ * is now a thunk that imports the command's module and resolves to its function, so the one
+ * field a row holds is still the one thing a data file cannot — where the FUNCTION lives.
+ * `main` awaits `VERBS[verb]()` after the parse succeeds; the scraping regexes in
+ * `tests/unit/{cli_table,hook_cli,docs}.test.mjs` match on the KEY and the colon only; the
+ * literal string `const VERBS = {` and the key order neither changed.
  */
 const VERBS = {
-  exclude: cmdExclude,
-  status: cmdStatus,
-  version: cmdVersion,
-  build: cmdBuild,
-  prompt: cmdPrompt,
-  theme: cmdTheme,
-  diff: cmdDiff,
-  'rebuild-all': cmdRebuildAll,
-  migrate: cmdMigrate,
-  doctor: cmdDoctor,
-  uninstall: cmdUninstall,
-  link: cmdLink,
-  unlink: cmdUnlink,
-  setup: cmdSetup,
-  web: cmdWeb,
-  upgrade: cmdUpgrade,
+  exclude: () => import('../js/inspect/excludes.mjs').then((m) => m.cmdExclude),
+  status: () => import('../js/inspect/status.mjs').then((m) => m.cmdStatus),
+  version: () => import('../js/inspect/status.mjs').then((m) => m.cmdVersion),
+  build: () => import('../js/build/generate.mjs').then((m) => m.cmdBuild),
+  prompt: () => import('../js/build/generate.mjs').then((m) => m.cmdPrompt),
+  theme: () => import('../js/build/generate.mjs').then((m) => m.cmdTheme),
+  diff: () => import('../js/inspect/diff.mjs').then((m) => m.cmdDiff),
+  'rebuild-all': () => import('../js/build/generate.mjs').then((m) => m.cmdRebuildAll),
+  migrate: () => import('../js/maintain/migrate.mjs').then((m) => m.cmdMigrate),
+  doctor: () => import('../js/inspect/doctor.mjs').then((m) => m.cmdDoctor),
+  uninstall: () => import('../js/maintain/uninstall.mjs').then((m) => m.cmdUninstall),
+  link: () => import('../js/hosts/link.mjs').then((m) => m.cmdLink),
+  unlink: () => import('../js/hosts/link.mjs').then((m) => m.cmdUnlink),
+  setup: () => import('../js/maintain/setup.mjs').then((m) => m.cmdSetup),
+  web: () => import('../js/web/server.mjs').then((m) => m.cmdWeb),
+  upgrade: () => import('../js/maintain/update.mjs').then((m) => m.cmdUpgrade),
   // `up.add_parser(..., aliases=["update"])`, reproduced in P8c as a ROW OF ITS OWN rather than
   // as an `aliases` field on the row above — because a field would be a DECLARATION and the
   // three matrix gates read this table as the DISPATCH (rule 7, and M23 is where it was
@@ -120,18 +110,18 @@ const VERBS = {
   //
   // It is NOT what the web console's `update` ACTION needs: that row's argv names `upgrade`,
   // the subparser, and always did. The two were coupled only in a handoff's note.
-  update: cmdUpgrade,
+  update: () => import('../js/maintain/update.mjs').then((m) => m.cmdUpgrade),
   // Points at `cmdSyncSelf` rather than at `cmdUpgrade`, and that is not tidiness:
   // `sync-self` DROPS its `ref` before `upgrade` ever sees it, where `upgrade` both WARNS
   // about one and re-reads it as a theme — so the two verbs answer `sync-self cyberpunk`
   // and `sync-self v1.2.3` differently. See `js/maintain/update.mjs`'s `syncSelf` for both halves.
-  'sync-self': cmdSyncSelf,
-  bootstrap: cmdBootstrap,
+  'sync-self': () => import('../js/maintain/update.mjs').then((m) => m.cmdSyncSelf),
+  bootstrap: () => import('../js/maintain/update.mjs').then((m) => m.cmdBootstrap),
   // P7a. Both are DISPATCHERS whose off-TTY arm is the whole of what a cell can reach, and
   // `menu`'s on-TTY arm falls back rather than opening a panel — `js/ui/menu.mjs`'s header
   // argues both.
-  menu: cmdMenu,
-  home: cmdHome,
+  menu: () => import('../js/ui/menu.mjs').then((m) => m.cmdMenu),
+  home: () => import('../js/ui/menu.mjs').then((m) => m.cmdHome),
   // P7b, and it is the twenty-fifth and last. `cmd_tui`'s FIRST arm is `if not sys.stdin.
   // isatty()`, so off a TTY — which is every cell there is — the verb is one line and an
   // exit code, and that arm crosses byte for byte. The panel behind it is P7c's;
@@ -139,7 +129,7 @@ const VERBS = {
   // panel-unavailable line rather than inventing a second full-screen UI, and
   // `tests/test_tui_boundary.py` asserts that the arm it declares is genuinely unreachable
   // here rather than merely untested.
-  tui: cmdTui,
+  tui: () => import('../js/ui/tui.mjs').then((m) => m.cmdTui),
   // THE THREE THAT NEVER HAD A PYTHON ORIGINAL, and they are last for that reason rather
   // than by alphabet: every row above is the twin of a subparser, and these three are not.
   // The information behind them existed only behind the web console — the catalog endpoint,
@@ -154,9 +144,9 @@ const VERBS = {
   // ABSOLUTE — `tests/snapshot/cli_help.test.mjs` splits the two populations by name and refuses a
   // verb that falls into neither, and each has its own unit gate stating what it does rather
   // than that it agrees.
-  catalog: cmdCatalog,
-  mcp: cmdMcp,
-  memory: cmdMemory,
+  catalog: () => import('../js/build/catalog.mjs').then((m) => m.cmdCatalog),
+  mcp: () => import('../js/hosts/mcp.mjs').then((m) => m.cmdMcp),
+  memory: () => import('../js/maintain/memory.mjs').then((m) => m.cmdMemory),
 };
 
 function die(code, msg) {
@@ -309,6 +299,11 @@ async function main(argv) {
   // and it is on THIS binary — not on `bin/build-driver.mjs` — because it runs the doctor, which
   // starts a process the driver is banned from reaching.
   if (verb === 'validate') {
+    // Lazy for the same reason the table rows are — `parseDriverArgs` alone drags the whole
+    // generator driver in, and every OTHER verb was paying for it.
+    const [{ cmdValidate }, { parseDriverArgs }] = await Promise.all([
+      import('../js/inspect/validate.mjs'), import('./build-driver.mjs'),
+    ]);
     try {
       return cmdValidate(parseDriverArgs(argv.slice(1)));
     } catch (e) {
@@ -316,8 +311,8 @@ async function main(argv) {
       throw e;
     }
   }
-  const fn = VERBS[verb];
-  if (!fn) {
+  const load = VERBS[verb];
+  if (!load) {
     // "and every other harness subcommand is still Python — run the interpreter against the
     // old harness script" is GONE, and its removal is not cosmetic: with the four hook verbs
     // named, the two entry points now cover every subcommand there is, so the clause was not
@@ -353,7 +348,11 @@ async function main(argv) {
     // it `process.exitCode` would be assigned a PENDING PROMISE, which Node coerces to 0
     // and prints nothing about. `web status` would then report "not running" and exit 0.
     // Awaiting a number is a no-op for the ten synchronous verbs.
-    return await fn(parsed.args);
+    //
+    // The load happens HERE, after the parse succeeded: a bad argument line refuses in a
+    // few milliseconds without touching the command's module tree, which is also why the
+    // parse errors above cannot depend on anything a loader would have brought in.
+    return await (await load())(parsed.args);
   } catch (e) {
     // `e.exitCode` is the generator's existing marker for a DELIBERATE refusal that has
     // already explained itself on stderr — `js/build/emit-claude.mjs` reads the same flag, and it is

package/bin/geneseed-hook.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
- * The hook entry point — a Node twin of `rituals/harness.py` for the four verbs the
- * emitted `settings.json` actually invokes.
+ * The hook entry point — a Node twin of `rituals/harness.py` for the verbs the emitted
+ * `settings.json` actually invokes (four from the reference, plus `tool-gate` for Copilot).
  *
  * WHY IT IS A SECOND BINARY AND NOT A SUBCOMMAND OF `bin/build-driver.mjs`. Three reasons,
  * and each alone would be enough:
@@ -37,16 +37,20 @@
  * every Geneseed hook returns 0 and signals through stdout — so "did nothing" and "worked"
  * are the same observation.
  */
-import { cmdContext, cmdGitGate, cmdRuleGate, cmdLearn } from '../js/hosts/hooks.mjs';
-import { printHelp } from '../js/ui/cli.mjs';
+import { cmdContext, cmdGitGate, cmdRuleGate, cmdToolGate, cmdLearn } from '../js/hosts/hooks.mjs';
 // Not a new module on the hot path: `js/hosts/hooks.mjs` above already imports
 // `js/lib/fs.mjs`, so this edge names a file the process has already loaded.
 import { printErr } from '../js/lib/fs.mjs';
 
+// `--host` selects the verdict dialect (see js/hosts/hooks.mjs's header); the emitter bakes
+// it into the command for every host that is not Claude Code, so the hook never has to guess
+// its reader from the payload's shape.
+const HOSTED = { '--root': 'root', '--host': 'host' };
 const VERBS = {
-  context: { fn: cmdContext, flags: { '--root': 'root' } },
-  'git-gate': { fn: cmdGitGate, flags: { '--root': 'root' } },
-  'rule-gate': { fn: cmdRuleGate, flags: { '--root': 'root' } },
+  context: { fn: cmdContext, flags: HOSTED },
+  'git-gate': { fn: cmdGitGate, flags: HOSTED },
+  'rule-gate': { fn: cmdRuleGate, flags: HOSTED },
+  'tool-gate': { fn: cmdToolGate, flags: HOSTED },
   learn: {
     fn: cmdLearn,
     flags: { '--memory': 'memory' },
@@ -63,12 +67,12 @@ function die(code, msg) {
 }
 
 /**
- * `argparse`'s surface for these four verbs, and only theirs: `--flag VALUE`, the
+ * `argparse`'s surface for these verbs, and only theirs: `--flag VALUE`, the
  * `--flag=VALUE` spelling it also accepts, store_true switches, and one optional
  * positional.
  */
 function parse(spec, argv) {
-  const args = { root: null, memory: null, consolidate: false, file: null };
+  const args = { root: null, host: null, memory: null, consolidate: false, file: null };
   for (let i = 0; i < argv.length; i += 1) {
     const tok = argv[i];
     const eq = tok.indexOf('=');
@@ -92,7 +96,7 @@ function parse(spec, argv) {
   return { args };
 }
 
-function main(argv) {
+async function main(argv) {
   // `geneseed status | head` closes stdout early. Python exits quietly through
   // BrokenPipeError; the Node equivalent is an EPIPE that would otherwise be an unhandled
   // 'error' event and a stack trace on a hook path.
@@ -111,16 +115,19 @@ function main(argv) {
     // The COMMAND is not a table: `geneseed` is this package's `bin` entry for the CLI
     // (package.json), it answers every non-hook verb, and it survives the deletion of the
     // interpreter-plus-script invocation this line used to print.
-    return die(2, `invalid choice: '${verb}'. This entry point carries only the four HOOK `
+    return die(2, `invalid choice: '${verb}'. This entry point carries only the HOOK `
       + `verbs (${Object.keys(VERBS).join(', ')}); every other harness subcommand lives `
       + 'elsewhere — run `geneseed ' + verb + '`.');
   }
   // `<verb> --help`, for the same reason and by the same owner as `bin/geneseed-cli.mjs`:
   // argparse holds `-h` at the parser, so this entry's `parse` calls it an unrecognized
   // argument. The four hook verbs are four of the reference's 26 and had the same gap.
-  // `js/ui/cli.mjs` reads the CLI table lazily, inside its functions, so importing it costs this
-  // entry a module parse and no file read on the hook path.
+  // `js/ui/cli.mjs` is imported HERE, not at the top: a static import cost every tool call
+  // of every session a module parse (~3 ms of an ~12 ms controllable budget) for a branch
+  // only a human at a terminal ever takes. The hook path never awaits it, so `main` staying
+  // async-shaped costs the hot verbs nothing.
   if (argv.slice(1).some((t) => t === '-h' || t === '--help')) {
+    const { printHelp } = await import('../js/ui/cli.mjs');
     const rc = printHelp('geneseed-hook', verb);
     if (rc !== null) return rc;
   }
@@ -129,4 +136,4 @@ function main(argv) {
   return spec.fn(parsed.args);
 }
 
-process.exitCode = main(process.argv.slice(2));
+main(process.argv.slice(2)).then((code) => { process.exitCode = code; });

package/docs/candidate-hosts.md

@@ -0,0 +1,74 @@
+# Candidate hosts — what Codex, Cursor and Gemini CLI actually offer
+
+*2026-09-05. Item 6 of the host-gap review. A docs check, not a design: each tool's
+own reference was read for the three surfaces Geneseed emits — an instructions
+carrier, skills, and hooks — so that "add host X" can be costed without re-reading
+the docs. Nothing here is implemented. Sources: the Codex CLI repo
+(`codex-rs/hooks`, `codex-rs/core/src/agents_md.rs`), `cursor.com/docs/{rules,skills,hooks}`,
+`geminicli.com/docs/{hooks,cli/gemini-md,cli/tutorials/skills-getting-started}`.*
+
+## The finding that changes the cost
+
+**`.agents/skills/` is a cross-tool convention.** Cursor loads skills from
+`.agents/skills/` and `~/.agents/skills/` (and, for compatibility, from `.claude/skills/`
+and `.codex/skills/`); Codex from `~/.codex/skills` (`$CODEX_HOME/skills`) and
+`.agents/skills`; Gemini CLI from `.gemini/skills` **or the `.agents/skills` alias**. One
+`skills/` emit into `.agents/` therefore reaches all three, byte-identical to what every
+current host gets. Skills are the largest surface by file count and they cost nothing new.
+
+## Per-host contracts
+
+| Surface | Codex CLI | Cursor | Gemini CLI |
+| --- | --- | --- | --- |
+| **Instructions** | `AGENTS.md` at the repo root (and nested), plus a global `~/.codex/AGENTS.md` that no size cap touches | `AGENTS.md` at the root and in subdirectories, combined; also `.cursor/rules/*.mdc` | `GEMINI.md` by default; `context.fileName` in `settings.json` accepts a list, e.g. `["AGENTS.md", "GEMINI.md"]` |
+| **Skills** | `~/.codex/skills`, `.agents/skills` — `SKILL.md` + frontmatter | `.cursor/skills`, `.agents/skills`, `~/.cursor/skills`, `~/.agents/skills`, plus `.claude/skills` and `.codex/skills` for compatibility | `.gemini/skills` or `.agents/skills`; `/skills list`, `/skills reload` |
+| **Hook config** | `hooks.json` in a config layer's folder, or a `[hooks]` table in `config.toml` (same schema, capitalised event names) | `.cursor/hooks.json` (project) and `~/.cursor/hooks.json` (user); plugins may ship `hooks/hooks.json` | `settings.json` `hooks` object (project `.gemini/`, user `~/.gemini/`) |
+| **Hook shape** | **Claude-shaped**: event → `[{matcher, hooks: [{type: "command", command, timeout}]}]`; 11 events incl. `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop` | event → `[{command, matcher?}]`; events incl. `sessionStart`, `preToolUse`, `beforeShellExecution`, `beforeReadFile`, `afterFileEdit`, `stop`, `sessionEnd` | **Claude-shaped groups, Gemini names**: `SessionStart`, `BeforeTool`, `AfterTool`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `PreCompact`, `SessionEnd`; matchers are regexes over tool names |
+| **Gate payload** | `tool_name` / `tool_input` (Claude's field names) | `tool_name` / `tool_input`, `cwd`, `tool_use_id` | `tool_name` / `tool_input`, `session_id`, `transcript_path`, `cwd`, `hook_event_name` |
+| **Gate verdict** | `hookSpecificOutput.permissionDecision`: **`allow` / `deny` / `ask`** — the ask tier exists | `permission: "allow" \| "deny"` + `user_message` / `agent_message`; **no ask** | `decision: "deny"` + `reason`, or exit code 2 with stderr as the reason; `systemMessage` shows the user a line; **no ask** |
+| **Context injection** | `SessionStart` → `additionalContext` (Claude form) | `sessionStart` → `additional_context` (snake_case) | `SessionStart` → `hookSpecificOutput.additionalContext`; plain stdout is not read |
+| **Learn point** | `Stop` / `SubagentStop` / `PreCompact`, transcript on stdin as on Claude | `stop` (payload not checked for a transcript path) | `AfterAgent` (turn end) and `PreCompact`; `transcript_path` is in the base schema |
+| **Tool names for matchers** | Claude's (`Bash`, `Write`, `Edit`) | `Shell`, `Read`, `Write`, MCP, `Task` (generic `preToolUse`) | `run_shell_command` (`command`), `write_file` (`file_path`, `content`), `replace` (`file_path`, `old_string`, `new_string`) |
+| **Subagents** | `SubagentStart`/`SubagentStop` exist; custom agents not checked | Plugins carry `agents/` | Local and remote subagents (`/agents list`, `enable`, `disable`) |
+
+## What each would cost, against what exists
+
+- **Codex CLI — cheapest, and the only one with an ask tier.** Its hook schema is
+  Claude's with `hooks.json`/`config.toml` as the carrier, its payload field names are
+  Claude's, and `permissionDecision: "ask"` exists. The Claude engine with `host: "codex"`
+  covers instructions (`AGENTS.md`), skills (`.agents/skills`) and the four hook verbs
+  unchanged; the only new code is the carrier writer (a `hooks.json` merge or a TOML
+  table) and the config-dir resolver (`~/.codex`, `$CODEX_HOME`). Roughly the Copilot
+  port minus the dialect work.
+
+- **Gemini CLI — Claude's groups, Gemini's names.** The hook groups are Claude's
+  `event → [{matcher, hooks}]` and the payload fields are Claude's, but the events are
+  `BeforeTool`/`AfterAgent` and the verdict is `decision: "deny"` or a `systemMessage`.
+  Bob Shell shares Gemini's *config* shape (`context.fileName`, `tools.allowed:
+  ["run_shell_command(git)"]`), but Bob's documented *hook* protocol is its own —
+  Claude's event names, refusal by exit code 2; see `adapters/bob/README.md` — so the two
+  are not one dialect. Instructions need one settings key (`context.fileName` to include
+  `AGENTS.md`) or a `GEMINI.md` carrier; skills go to `.agents/skills`. No ask tier: Laws
+  I/IV deny, the consent rules become a `systemMessage`.
+
+- **Cursor — a third verdict dialect.** `AGENTS.md` and `.agents/skills` are free; hooks
+  are `hooks.json` with a `{command}` list per event and a `permission: allow|deny`
+  verdict, `additional_context` in snake_case for `sessionStart`. Same block-or-warn stance
+  as Copilot, one more output spelling in `js/hosts/hooks.mjs`, one more carrier writer.
+  Cursor also reads `.claude/skills/`, so a Claude project install already gives a Cursor
+  user the skills.
+
+## Recommendation
+
+If a fifth host is wanted, Codex first: it reuses the most and it is the only candidate
+where the gates can *ask* rather than block. Before any of them, a `--emit agents` for
+the shared `.agents/skills/` folder would give Codex, Cursor and Gemini users the whole
+skill catalogue for the price of one directory name, with no host-specific code at all.
+A Gemini host would be the fourth verdict spelling in `js/hosts/hooks.mjs` (after Claude's
+ask, Copilot's block, Bob's exit code 2), plus a resolver and a carrier.
+
+## Not verified
+
+None of the three CLIs is installed on the reviewing machine. Every row above is from the
+tool's own documentation as indexed on 2026-09-05; the "learn point" column for Cursor and
+the Codex custom-agent surface were not checked further than noted.

package/docs/extending.md

@@ -215,11 +215,12 @@ a defect.
 
 Steps 1 and 9 of §2c, plus `LAW_META` if the Principle line moved. Two cautions:
 
-- `--footprint` defaults to **lean**, and lean keeps only the heading plus the first sentence
-  (`terseBlocks` in `js/build/render.mjs`). A clause added to the second paragraph is invisible in the
-  default build. Amend the first sentence, or the amendment does not exist for most installs. The
-  same is true of a doctrine rule; it is **not** true of the ontology, which ships whole at both
-  footprints.
+- `--footprint` defaults to **lean**, and a law's lean text is the authored `LEAN:else` half of
+  its block in `src/laws/universal.md` (`resolveLean` in `js/build/render.mjs`). Amend **both**
+  halves, or the amendment does not exist for most installs. A doctrine rule is different: it is
+  still machine-cut to its heading plus first sentence (`terseBlocks`), so a clause in its second
+  paragraph is invisible in the default build. The on-disk `laws/` and `ontology/` copies always
+  render at full, whatever the footprint.
 
 ### 2c — Adding an INVARIANT
 

package/docs/token-footprint.md

@@ -4,10 +4,11 @@ What a deployed harness costs in context-window tokens, per host. Token counts a
 chars/4 estimates and shift a little with theme and version.
 
 **Treat every number below as a floor, not a reading.** They were measured on a
-`--footprint full` build of the neutral theme when the tree carried 41 skills and 17
-agents; it carries more skills than that now, and nothing re-measures this page
-automatically. For a live figure on your own install, ask the agent for the
-`token-report` skill — that is what it is for.
+`--footprint lean` build (the default) of the neutral theme when the tree carried
+47 skills and 17 agents, and nothing re-measures this page automatically. For a
+live figure on your own install, ask the agent for the `token-report` skill —
+that is what it is for. A `--footprint full` build runs roughly 5k tokens
+heavier on the root file.
 
 ## Always-on cost per session
 
@@ -15,40 +16,50 @@ The context every host injects at session start, before you type anything:
 
 | Component | Claude Code | OpenCode | Bob | Copilot |
 |---|---|---|---|---|
-| Root instruction file | ~10.7k (`CLAUDE.md`) | ~10.6k (`AGENT.md`) | ~10.7k (`AGENTS.md`) | ~10.7k (`AGENTS.md`) |
-| Skill metadata (name + description) | ~1.6k | ~1.6k | ~1.6k | ~1.6k |
-| Agent metadata | ~0.45k | ~0.55k | ~0.45k | ~0.45k |
+| Root instruction file | ~6.4k (`CLAUDE.md`) | ~6.4k (`AGENT.md`) | ~8.3k (`AGENTS.md`) | ~8.3k (`AGENTS.md`) |
+| Skill metadata (name + description) | ~1.7k | ~1.7k | ~1.7k | ~1.7k |
+| Agent metadata | ~0.5k | ~0.55k | ~0.5k | ~0.5k |
 | Eager memory/notebook injection | ~1.2k (SessionStart hook) | ~1.2k (context plugin) | ~1.2k (SessionStart hook) | — (no hooks; read on demand) |
-| **Total** | **~14k** | **~14k** | **~14k** | **~12.8k** |
+| **Total** | **~9.8k** | **~9.9k** | **~11.7k** | **~10.5k** |
 
-The emits are at parity by design: ~14k tokens, about 7% of a 200k
-window (Copilot runs slightly lighter because it has no hook mechanism — the
-memory/notebook indexes load when the agent reads them, not eagerly). The
+The emits are at parity by design: ~10–12k tokens, about 5–6% of a 200k
+window. Bob and Copilot carry the §3/§4 catalogue tables inline because their
+hosts expose no native skill/agent inventory; Claude Code and OpenCode ship a
+pointer to the host's own inventory instead, ~1.9k tokens lighter. Copilot also
+runs without eager injection — it has no hook mechanism, so the
+memory/notebook indexes load when the agent reads them, not eagerly. The
 eager-injection path is budget-capped identically everywhere
 (16 KB per file, 48 KB total ≈ 12k tokens ceiling), so growing Memory degrades
 every host the same way instead of one silently falling behind.
 
 ## Where the tokens go
 
-- **The root file is ~76% of the bill**, and the constitution inside it is the
+- **The root file is ~65% of the bill**, and the constitution inside it is the
   bulk of that — no longer one section but three: the Ontology, the nine Rules,
   and the doctrine packs this install built in. **Two** levers move it, not one.
-  The [footprint dial](#/docs/footprint) (`lean`, the default, keeps each Rule
-  and each doctrine rule as its heading plus first line, and ships the Ontology
-  *whole*; `full` inlines every rationale). And the
+  The [footprint dial](#/docs/footprint) (`lean`, the default, swaps each Rule,
+  the Ontology and the longest prose sections — the preamble, §6 Notebook, §8
+  Wiki — for their hand-written condensations, and cuts each doctrine rule to its
+  heading plus first line; `full` inlines every rationale). And the
   [doctrine packs](#/docs/setup-choices) — `geneseed-build --doctrines craft,rigor`
   drops whole blocks of §2 at build time, which removes far more than the
   footprint dial trims. Anything else is noise.
 
-  The three-tier split grew the root file: measured on `neutral`, `AGENT.md`
-  went from 31,457 bytes to 36,882 at `lean` (+17.2%) and 53,378 to 54,810 at
-  `full` (+2.7%). The lean growth is the larger one *by design* — the Ontology
-  is prose, and truncating four flowing sections to four orphan sentences would
-  have shipped a worldview nobody could read.
+  The lean condensations are authored, not generated. An earlier design shipped
+  the Ontology *whole* under `lean` on the grounds that truncating four flowing
+  sections to four orphan sentences would ship a worldview nobody could read —
+  the `LEAN:` blocks answer that by hand-writing the short form instead
+  (measured on `neutral`, the root file at `lean` went from 29,966 bytes to
+  25,614 with them).
 - **Skill bodies (~53k) and agent bodies (~10k) are lazy** on every host —
   loaded only when invoked. A typical skill costs ≤3k per invocation; the
   heaviest (`react-view-transitions`, ~17.5k with its reference files) loads
   its references progressively.
+- **User-only skills leave the catalogue.** A skill whose source carries
+  `<!-- invocation: user -->` renders `disable-model-invocation: true`; Claude
+  Code and Bob then drop its description from the always-on skill metadata and
+  only `/name` opens it. Seven skills carry it today (the five teaching drills,
+  `herdr`, `opencode-theme`), roughly a seventh of the ~1.7k skill-metadata line.
 - Plugin JavaScript (OpenCode, ~26k on disk) runs in the host runtime and
   never enters the context window.
 
@@ -73,7 +84,7 @@ token counter also includes, none of which Geneseed controls:
    per-repo install, a personal `~/.claude/CLAUDE.md`, or MCP servers each add
    their own share.
 
-So a ~34k session on a work repo is normal arithmetic: ~14k harness +
+So a ~30k session on a work repo is normal arithmetic: ~10k harness +
 ~10k repo docs + ~5–10k host overhead. Set `GENESEED_DEBUG=1` (OpenCode) to
 log exactly which files the context plugin injected, or run the SessionStart
 command by hand to see the hook's payload.