geneseed 4.1.0 → 4.3.0

package/js/build/emit-opencode.mjs

@@ -14,6 +14,7 @@ import {
   writeAliasCommands, writePonytailCommand, writePrimaryAgent, writeTheme,
 } from '../hosts/opencode.mjs';
 import { mergeOpencodeJson, opencodeSentinelWrite } from '../hosts/settings.mjs';
+import { claimLeaf } from '../hosts/owned.mjs';
 import { isFile, readText, writeText } from '../lib/fs.mjs';
 import { relPosix } from '../lib/text.mjs';
 import { assertSourceComplete, build, phaseLog } from './bundle.mjs';
@@ -54,11 +55,12 @@ import { mkdirSync } from 'node:fs';
 function opencodeLayer(cfg, items, themeName, theme, dir, owned, opts) {
   const {
     oldOwned, manifestExisted, agentPath, wireBase, overridesDir, oldDenies = [],
+    oldHashes = {},
   } = opts;
   ensureAgentOverridesStub(cfg, overridesDir);
   const overrides = loadAgentOverrides(overridesDir);
   // One claim for every writer below whose path lands in `owned` — see `claimer`.
-  const claim = claimer(oldOwned, dir, manifestExisted);
+  const claim = claimer(oldOwned, dir, manifestExisted, oldHashes);
 
   const { nAgents, nSkills, written, userOnlySkills } = writeNativeLayer(
     items, path.join(dir, 'agents'), path.join(dir, 'skills'), overrides,
@@ -105,7 +107,7 @@ function opencodeLayer(cfg, items, themeName, theme, dir, owned, opts) {
 
   return {
     nAgents, nSkills, nPlugins, nWorkflows, primary, nCommands: commands.length, cfgName,
-    skillDenies,
+    skillDenies, editRefused: [...claim.editRefused],
   };
 }
 
@@ -129,7 +131,7 @@ export function emitOpencodeRender(cfg, job) {
   phaseLog('RENDER');
   const {
     theme: _theme, out, root, footprint, nativeCatalog, oldOwned, manifestExisted, agentPath,
-    oldDenies,
+    oldDenies, oldHashes = {},
   } = job;
   const oc = path.join(root, '.opencode');
 
@@ -144,9 +146,9 @@ export function emitOpencodeRender(cfg, job) {
   const { theme, items } = renderAll(cfg, _theme, { footprint, nativeCatalog });
 
   const {
-    nAgents, nSkills, nPlugins, nWorkflows, primary, nCommands, cfgName, skillDenies,
+    nAgents, nSkills, nPlugins, nWorkflows, primary, nCommands, cfgName, skillDenies, editRefused,
   } = opencodeLayer(cfg, items, _theme, theme, oc, owned, {
-    oldOwned, manifestExisted, agentPath, wireBase: root, overridesDir: out, oldDenies,
+    oldOwned, manifestExisted, agentPath, wireBase: root, overridesDir: out, oldDenies, oldHashes,
   });
 
   return {
@@ -156,6 +158,7 @@ export function emitOpencodeRender(cfg, job) {
     },
     cfgName,
     skillDenies,
+    editRefused,
   };
 }
 
@@ -195,6 +198,7 @@ export function emitOpencodeGlobalRender(cfg, job) {
   phaseLog('RENDER');
   const {
     theme: themeName, cfgDir, out, footprint, nativeCatalog, oldOwned, agentPath, oldDenies,
+    oldHashes = {},
   } = job;
 
   // No `lawsPrefix`: the standalone laws dir sits beside AGENT.md in <cfg>, so the lean
@@ -210,8 +214,11 @@ export function emitOpencodeGlobalRender(cfg, job) {
     // plain names. Memory links stay RELATIVE: in the global layout AGENT.md and the
     // store are siblings, so `memory/` resolves from AGENT.md's own location and stays
     // hermetic — no absolute path a doctor check would flag as an escape.
-    writeText(path.join(cfgDir, 'AGENT.md'), stripCapabilityLinks(agentText));
-    owned.push('AGENT.md');
+    const agentDest = path.join(cfgDir, 'AGENT.md');
+    if (claimLeaf(cfgDir, agentDest, 'AGENT.md')) {
+      writeText(agentDest, stripCapabilityLinks(agentText));
+      owned.push('AGENT.md');
+    }
   }
   // Co-owned, so never in `owned` — see `opencodeSentinelWrite`.
   opencodeSentinelWrite(cfgDir);
@@ -219,9 +226,9 @@ export function emitOpencodeGlobalRender(cfg, job) {
   // `manifestExisted` is deliberately not passed — the Python does not pass it either, so
   // the pre-manifest header line is unreachable from this emit on both sides.
   const {
-    nAgents, nSkills, nPlugins, nWorkflows, primary, nCommands, cfgName, skillDenies,
+    nAgents, nSkills, nPlugins, nWorkflows, primary, nCommands, cfgName, skillDenies, editRefused,
   } = opencodeLayer(cfg, items, themeName, theme, cfgDir, owned, {
-    oldOwned, agentPath, wireBase: cfgDir, overridesDir: cfgDir, oldDenies,
+    oldOwned, agentPath, wireBase: cfgDir, overridesDir: cfgDir, oldDenies, oldHashes,
   });
 
   const memStatus = globalMemory(cfgDir, items, out, cfg.src);
@@ -233,8 +240,7 @@ export function emitOpencodeGlobalRender(cfg, job) {
   ensureProfileStub(cfgDir);
   ensureExcludesStub(cfgDir);
 
-  writeVersion(cfg, cfgDir);
-  owned.push(VERSION_MARKER);
+  if (writeVersion(cfg, cfgDir) !== null) owned.push(VERSION_MARKER);
 
   shipLeanLaws(items, theme, cfgDir, owned, footprint);
 
@@ -247,5 +253,6 @@ export function emitOpencodeGlobalRender(cfg, job) {
     nbStatus,
     cfgName,
     skillDenies,
+    editRefused,
   };
 }

package/js/build/source.mjs

@@ -348,6 +348,7 @@ export function skillAliases(src = SRC) {
  */
 export const RETIRED_SKILL_IDS = {
   tickets: 'removed in the 2026-10 sharpen; plan slices the work now',
+  herdr: 'removed 2026-10; Orca covers multi-pane and multi-agent work',
 };
 
 /**

package/js/build/version.mjs

@@ -9,6 +9,7 @@
 import path from 'node:path';
 import { VERSION_MARKER } from '../hosts/hosts.mjs';
 import { readText, writeText } from '../lib/fs.mjs';
+import { claimLeaf } from '../hosts/owned.mjs';
 import { parseJson } from '../lib/json.mjs';
 import { isDir } from '../lib/fs.mjs';
 import { relPosix } from '../lib/text.mjs';
@@ -162,8 +163,15 @@ function warnIfDowngrade(cfg, out) {
   }
 }
 
-/** `_build_render.write_version`. */
+/**
+ * `_build_render.write_version`. Returns the fingerprint on a successful write, or `null` when
+ * `claimLeaf` refuses `out`'s marker (a symlinked or hard-linked `VERSION_MARKER`) — every
+ * caller pushes `VERSION_MARKER` into `owned` only when this is not `null`, the same
+ * "skip the write, keep it out of owned" shape `claimer` uses.
+ */
 export function writeVersion(cfg, out) {
+  const dest = path.join(out, VERSION_MARKER);
+  if (!claimLeaf(out, dest, VERSION_MARKER)) return null;
   warnIfDowngrade(cfg, out);
   const fp = sourceFingerprint(cfg);
   const release = sourceReleaseVersion(cfg);
@@ -177,8 +185,7 @@ export function writeVersion(cfg, out) {
   // clock across a process boundary is not something the harness can do — which is
   // exactly why the choice is spelled out instead of relying on the comparison.
   const today = new Date().toLocaleDateString('sv-SE');
-  writeText(path.join(out, VERSION_MARKER),
-    `${fp} (built ${today}) [release ${release}]\n`);
+  writeText(dest, `${fp} (built ${today}) [release ${release}]\n`);
   return fp;
 }
 

package/js/cli-table.json

@@ -1415,6 +1415,21 @@
           "is_flag": true,
           "type": null,
           "hidden": false
+        },
+        {
+          "names": [
+            "--force"
+          ],
+          "dest": "force",
+          "metavar": null,
+          "help": "also delete owned files you edited since install",
+          "choices": null,
+          "default": false,
+          "required": false,
+          "nargs": "0",
+          "is_flag": true,
+          "type": null,
+          "hidden": false
         }
       ],
       "mutex": []

package/js/hosts/hooks.mjs

@@ -59,6 +59,7 @@ import {
 } from './hosts.mjs';
 import { currentBranch, gitRootOf, loopLaunched } from './gitref.mjs';
 import { selfAndParents, readStdin } from './hooks-prims.mjs';
+import { recordUse } from './usage.mjs';
 
 // ======================================================================================
 // git-gate — Doctrine process 5's tool-boundary backstop
@@ -627,6 +628,9 @@ function normaliseBobPayload(payload) {
 function toolGate(args) {
   if (sovereignBypass(args.root)) return 0;
   const payload = normaliseBobPayload(readPayload());
+  // Count a skill or subagent call before judging it: Bob runs this verb on every tool and
+  // Claude/OpenClaude route their `Skill|Agent|Task` matcher here (js/hosts/usage.mjs).
+  recordUse(args.root, payload);
   const ti = (payload && payload.tool_input) || {};
   return typeof ti.command === 'string' ? gitDecide(args, payload) : ruleDecide(args, payload);
 }

package/js/hosts/installs.mjs

@@ -181,7 +181,7 @@ const CARRIERS = [
  * `AGENTS.md` (`CLAUDE_SHAPED['bob-global']`'s summary says so) — which `HOSTS` has no column
  * for and this hard-codes, same as the un-narrowed `CARRIERS` above always did.
  */
-function carriersFor(host) {
+export function carriersFor(host) {
   const row = HOSTS.find((h) => h.host === host);
   if (!row) return CARRIERS;
   if (host === 'bob') return [path.join('rules', 'geneseed.md'), row.agentFile];

package/js/hosts/native.mjs

@@ -33,6 +33,7 @@ import { writeText, copyFile, readText } from '../lib/fs.mjs';
 import { jsonDumps, parseJson, formatValue, formatRepr, isTruthy, isDict } from '../lib/json.mjs';
 import { relPosix } from '../lib/text.mjs';
 import { aliasesOf } from '../build/source.mjs';
+import { claimLeaf, ownedState } from './owned.mjs';
 
 /** What a folder skill writes where it needs its own directory — see `writeNativeLayer`. */
 const SKILL_DIR_PLACEHOLDER = '<this-skill-directory>';
@@ -242,7 +243,7 @@ function isReadonly(text) {
  * description leaves the model's always-on catalogue and the model never self-triggers it.
  * Same precedent as `isReadonly` — a phrase in the spec, not a second manifest to keep in
  * step. Which skills carry it is an authoring decision: the teaching skills a human runs on
- * themselves, and the ones gated on an environment the model cannot see (a herdr pane).
+ * themselves.
  */
 const USER_INVOKED_RE = /<!--\s*invocation:\s*user\s*-->/;
 export function isUserInvokedOnly(text) {
@@ -471,14 +472,42 @@ function warnClaudeIgnored(overrides) {
  * emit, shared by all of them, so the pre-manifest header still prints once.
  *
  * `oldOwned === null` (or no `cfg`) is a caller doing no ownership at all: claim everything.
+ *
+ * The leaf guard (`claimLeaf`/`safeLeaf`) runs whenever `cfg != null`, independently of
+ * `oldOwned` — it is not about which prior manifest owns `dest`, it is about what sits AT
+ * `dest` on disk, and a caller with no `cfg` (`null` or `undefined` — they behave alike
+ * throughout this closure) has no root to contain against at all. See `js/hosts/owned.mjs`.
+ *
+ * `claim.editRefused` (Task 4, fix round 1): the rels this closure refused because the user
+ * had edited them — the one piece of its own decision `pruneOwned` cannot re-derive from
+ * `owned` alone. A refused edit drops its rel OUT of `owned` (the file was not written), which
+ * makes it look exactly like a rel this build stopped shipping — `pruneOwned` would read it as
+ * stale, re-run `ownedState`, see `'modified'` again, and print ITS OWN "kept your edited...
+ * (no longer shipped)" right under this function's "kept your edited... delete it to get
+ * Geneseed's copy back" — two warnings about one rel that is in fact still shipped. The caller
+ * reads this set back off the closure and hands it to `pruneOwned` so that rel is excluded from
+ * the stale set entirely, silently, rather than re-evaluated.
  */
-export function claimer(oldOwned, cfg, manifestExisted = true) {
+export function claimer(oldOwned, cfg, manifestExisted = true, oldHashes = {}) {
   const oldSet = oldOwned !== null && oldOwned !== undefined ? new Set(oldOwned) : null;
   let headerPrinted = false;
-  return (dest) => {
-    if (oldSet === null || cfg === null || !existsSync(dest)) return true;
+  const editRefused = new Set();
+  const claim = (dest) => {
+    if (cfg != null && !claimLeaf(cfg, dest, relPosix(cfg, dest))) return false;
+    if (oldSet === null || cfg == null || !existsSync(dest)) return true;
     const rel = relPosix(cfg, dest);
-    if (oldSet.has(rel)) return true;
+    if (oldSet.has(rel)) {
+      // `'unknown'` (no hash recorded — a pre-Task-3 manifest, or a rel `ownedHashes` never
+      // hashed) and `'unmodified'` both fall through to the ordinary overwrite below: the
+      // constraint that a manifest without `hashes` keeps today's behaviour exactly is this
+      // branch doing nothing extra, not a special case.
+      if (ownedState(cfg, rel, oldHashes) === 'modified') {
+        warn(`[geneseed] kept your edited ${rel} — delete it to get Geneseed's copy back`);
+        editRefused.add(rel);
+        return false;
+      }
+      return true;
+    }
     if (!manifestExisted && !headerPrinted) {
       warn('[geneseed] first emit over a pre-manifest install — existing files '
         + 'are treated as yours');
@@ -488,6 +517,8 @@ export function claimer(oldOwned, cfg, manifestExisted = true) {
       + 'clobbering it');
     return false;
   };
+  claim.editRefused = editRefused;
+  return claim;
 }
 
 /**
@@ -524,7 +555,8 @@ export function claimer(oldOwned, cfg, manifestExisted = true) {
  */
 export function writeNativeLayer(items, agentsDir, skillsDir, overrides = null, {
   host = 'opencode', oldOwned = null, cfg = null, manifestExisted = true,
-  theme = null, src = undefined, skillDirOf = null, claim = claimer(oldOwned, cfg, manifestExisted),
+  theme = null, src = undefined, skillDirOf = null, oldHashes = {},
+  claim = claimer(oldOwned, cfg, manifestExisted, oldHashes),
   // Bob (host-compat R1): its skills page documents only `name`/`description` — no
   // `disable-model-invocation` — and giving it the Claude-dialect alias SKILL.md (the
   // `host === 'claude'` branch below) would be an unverified key PLUS a visible duplicate

package/js/hosts/owned.mjs

@@ -0,0 +1,159 @@
+/**
+ * Manifest rel -> path on disk decisions — the small set of rules that turn an `owned` list
+ * entry (a POSIX-spelled relative path, read straight off a `.geneseed-manifest.json` that
+ * sits inside the install) into something safe to act on.
+ *
+ * `ownedWithin` is the first tenant: both `uninstall.mjs`'s owned-file walk and the generator
+ * driver's prune read a manifest's `owned` list and must agree on the one security boundary
+ * neither may skip — a manifest is a file on disk, and per-repo ones live inside the very repo
+ * a build runs over, so a cloned repo's manifest is as untrusted as any other file it ships.
+ *
+ * `safeLeaf` is the second: `ownedWithin` only proves a REL resolves inside the root, which
+ * says nothing about what sits at that path. A per-repo manifest can ship a rel that resolves
+ * inside the root AND is itself a symlink or a hard link out — `claimer` runs `safeLeaf` on
+ * every destination before it ever claims one.
+ *
+ * `claimLeaf` is `safeLeaf` plus the one sentence every refusal must print, because `claimer`
+ * is not the only writer whose path lands in `owned`: `writeVersion`, `shipLeanLaws`, and a
+ * handful of direct `writeText` calls in `emit-claude.mjs`/`emit-opencode.mjs` (the Bob rules
+ * stub, the project `.gitignore`, the OpenCode-global `AGENT.md`) push a rel into `owned`
+ * too, and the spec's intent — never write through a linked owned file — covers all of them,
+ * not just the ones that happen to go through a `claim()` closure.
+ */
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { resolvePath } from './hosts.mjs';
+import { within } from '../lib/paths.mjs';
+import { isFile } from '../lib/fs.mjs';
+
+/**
+ * The manifest rels that resolve INSIDE `base` — the one security boundary every walk over
+ * `owned` goes through (uninstall, both deactivates, build prune (`pruneOwned` in js/build/driver.mjs)).
+ *
+ * `path.resolve(rroot, r)` and NOT `path.join`, which is the one line here that is a security
+ * boundary rather than a translation. The Python is `(rroot / r).resolve()`, and pathlib's
+ * `/` REPLACES the base when the right operand is absolute — so a manifest entry naming
+ * `C:/evil.md` resolves outside the root and `_within` rejects it. `path.join` would have
+ * concatenated it into `<root>/C:/evil.md`, which passes containment and would then be acted
+ * on. `path.resolve` has pathlib's semantics for exactly this case, and collapses `..`
+ * besides, which is why the guard runs on the resolved path rather than the lexical one.
+ */
+export function ownedWithin(base, rels) {
+  const rroot = resolvePath(base);
+  return rels.filter((r) => r && within(resolvePath(path.resolve(rroot, r)), rroot));
+}
+
+/**
+ * True when `dest` is safe for `claimer` to (over)write: not itself a link, not a second name
+ * for a file with other names, and — once symlinks on its existing ancestor resolve — still
+ * inside `root`. False for the shape the leaf guard exists to catch: a cloned repo's manifest
+ * naming a rel that resolves inside the config root (so `ownedWithin` lets it through) at a
+ * path that is ITSELF a symlink or hard link pointing somewhere else, such as
+ * `.opencode/skills/x/SKILL.md` symlinked to `~/.bashrc` with a manifest entry claiming it.
+ *
+ * `lstatSync(dest, { throwIfNoEntry: false })`, never `existsSync` first — a DANGLING symlink
+ * (the attack's own shape: the real target need not exist yet for the write to land on it the
+ * moment something else creates it there) reads as ABSENT to `existsSync` and as a symlink to
+ * `lstat`, so `existsSync` is exactly the check that misses this case.
+ *
+ * `nlink` is checked only for a regular file. A directory's `nlink` is routinely > 1 — every
+ * child subdirectory's own `..` entry adds one — so gating on `isFile()` is what keeps an
+ * ordinary nested skill folder from tripping the hard-link branch on its own directories.
+ *
+ * A symlinked ROOT — `~/.claude` as a dotfiles repo's own symlink, or a `CLAUDE_CONFIG_DIR`
+ * env override pointing at one (`js/hosts/link.mjs` links the `geneseed` CLI binary onto
+ * PATH, a different concern entirely, and never a config root) — is NOT this shape:
+ * `resolvePath` follows the root link on both `root` and `dest`, so a leaf reached the
+ * ordinary way through a linked root still resolves inside it and stays allowed — only the
+ * LEAF itself being a link is refused.
+ */
+export function safeLeaf(root, dest) {
+  const rroot = resolvePath(root);
+  const st = lstatSync(dest, { throwIfNoEntry: false });
+  if (st) {
+    if (st.isSymbolicLink()) return false;
+    if (st.isFile() && st.nlink > 1) return false;
+  }
+  return within(resolvePath(dest), rroot);
+}
+
+/**
+ * `safeLeaf(root, dest)`, and on false the warning line every refusal prints — ONE sentence,
+ * so `claimer` and every direct owned-path writer below it say the same thing rather than
+ * each inventing its own wording. `rel` is the manifest spelling (POSIX, root-relative);
+ * callers that already have it (every one of them, since it is what they are about to push
+ * into `owned`) pass it straight through instead of re-deriving it from `dest`.
+ */
+export function claimLeaf(root, dest, rel) {
+  if (safeLeaf(root, dest)) return true;
+  process.stderr.write(`[geneseed] refused ${rel}: it is a link — Geneseed writes only `
+    + 'regular files it owns\n');
+  return false;
+}
+
+/**
+ * sha256 hex of the bytes on disk at `p`, with every `\r\n` folded to `\n` first. The fold is
+ * the point: a committed install is checked out by git with whatever line endings that clone's
+ * `core.autocrlf` / `.gitattributes` / OS asks for, and a teammate on the other OS gets every
+ * owned file's endings flipped without touching a byte of content. Hashed raw, that read as an
+ * edit to every file and the next rebuild froze the harness (measured: 95 false "kept your
+ * edited", owned 106 -> 11). A lone `\r` is not folded — git never writes one, so it is content.
+ * `latin1` maps each byte to one char and back, so the fold is byte-exact on any file, text or not.
+ */
+export function fileHash(p) {
+  const folded = readFileSync(p).toString('latin1').replaceAll('\r\n', '\n');
+  return createHash('sha256').update(folded, 'latin1').digest('hex');
+}
+
+/**
+ * One sha256 per entry of `owned` that is both inside `root` (through `ownedWithin`, the same
+ * containment boundary every other owned-rel walk goes through) and a file that still exists —
+ * a rel a prune is about to delete, or one a crafted manifest named outside root, is skipped
+ * rather than hashed. Keys land in the same sorted order the manifest writers already give
+ * `owned` itself (`[...owned].sort()`), so the hash map a re-emit produces for an unchanged
+ * tree is byte-identical to the one before it — `golden.mjs --idempotent`'s whole point.
+ */
+export function ownedHashes(root, owned) {
+  const hashes = {};
+  for (const rel of ownedWithin(root, owned).sort()) {
+    const p = path.join(root, rel);
+    if (isFile(p)) hashes[rel] = fileHash(p);
+  }
+  return hashes;
+}
+
+/** `/^[0-9a-f]{64}$/` — the only shape a hash this module wrote ever takes. */
+const HEX64 = /^[0-9a-f]{64}$/;
+
+/**
+ * `doc.hashes` read back defensively: a manifest is a file on disk, as untrusted as any other
+ * (`ownedWithin`'s own docblock), so a hand-edited or corrupt `hashes` must read as "nothing
+ * recorded" rather than crash or poison a comparison with a value that was never really a
+ * sha256. ANY malformed entry zeroes the whole map rather than only dropping that one key —
+ * a map that is wrong in one place is not trustworthy in the rest either.
+ */
+export function hashesOf(doc) {
+  const h = doc && typeof doc === 'object' && !Array.isArray(doc) ? doc.hashes : undefined;
+  if (!h || typeof h !== 'object' || Array.isArray(h)) return {};
+  for (const v of Object.values(h)) {
+    if (typeof v !== 'string' || !HEX64.test(v)) return {};
+  }
+  return { ...h };
+}
+
+/**
+ * Where one owned file stands against its recorded hash — the table later tasks (rebuild,
+ * prune, uninstall) will branch on to stop clobbering a user's edit to a Geneseed-owned file.
+ * `'unknown'` is deliberately distinct from `'unmodified'`: an older manifest with no `hashes`
+ * entry for this rel (today's installs, pre-Task-3) must not be read as "proven untouched" —
+ * see the constraint that a manifest without `hashes` keeps today's behaviour exactly.
+ */
+export function ownedState(root, rel, hashes) {
+  if (!Object.hasOwn(hashes, rel)) return 'unknown';
+  const expected = hashes[rel];
+  const p = path.join(root, rel);
+  if (!isFile(p)) return 'missing';
+  return fileHash(p) === expected ? 'unmodified' : 'modified';
+}

package/js/hosts/settings.mjs

@@ -802,6 +802,10 @@ export function claudeHookGroups(cfg, hookOpts, doctrines = null, excluded = [],
         matcher: 'Write|Edit|NotebookEdit',
         hooks: [{ type: 'command', command: ruleGate, ...onFailureBlock }],
       },
+      // Usage counting (js/hosts/usage.mjs): `tool-gate` records a Skill or subagent call and
+      // judges nothing else about it. `Task` is the subagent tool's older name. No
+      // `onFailure: 'block'`: a counter that cannot start must never stop a skill.
+      { matcher: 'Skill|Agent|Task', hooks: [{ type: 'command', command: `${run} tool-gate --root "${cfg}"` }] },
     ],
     // One matcher-less group, not a `startup|clear` / `resume|compact` split (Claude verdict
     // I4): every SessionStart source — `startup`, `resume`, `clear`, `compact` and `fork` —

package/js/hosts/usage.mjs

@@ -0,0 +1,62 @@
+/**
+ * WHICH SKILLS AND AGENTS ACTUALLY FIRE — the writer behind the Overview's "What fires" chart.
+ *
+ * One line per Skill or subagent call, appended to `<install>/notebook/usage.jsonl`:
+ * `{"ts":"2026-10-13","kind":"skill","name":"develop"}`. Counts only — never the prompt, the
+ * arguments or a path. The day, not the instant: a count per day is all the chart draws, and a
+ * coarser stamp is less of a record of someone's working hours.
+ *
+ * ON THE HOOK PATH, so it is cheap and silent: it imports only node builtins, prints nothing (a
+ * printed byte would turn a gate permissive), and swallows every error — a counter that fails
+ * must never block, slow or change a tool call. It rides `tool-gate`, the verb Bob already runs
+ * on every tool and Claude/OpenClaude route their `Skill|Agent|Task` matcher to, so no host pays
+ * an extra process for it. The OpenCode guard plugin carries the same rules inline (a plugin
+ * cannot import from here); `tests/unit/usage.test.mjs` holds both to one table.
+ *
+ * Off when `GENESEED_NO_USAGE` is set or the install holds a `.usage-off` marker.
+ */
+import { appendFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+
+export const USAGE_LEDGER = path.join('notebook', 'usage.jsonl');
+export const USAGE_OFF = '.usage-off';
+
+const NAME_RE = /^[A-Za-z0-9][\w.:@/-]{0,99}$/;
+
+/**
+ * `{kind, name}` for a skill or subagent call, else null. Reads the Claude shape (`tool_name` /
+ * `tool_input`: `Skill` → `skill`, `Agent` or the older `Task` → `subagent_type`), OpenCode's
+ * (`skill` → `name`, `task` → `subagent_type`) and, best-effort, Bob's (`tool` / `input`, any
+ * tool whose name contains "skill"): Bob's skill tool name is unverified, no Bob runs here.
+ */
+export function usageOf(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  const tool = String(payload.tool_name || payload.tool || '').toLowerCase();
+  const ti = payload.tool_input || payload.input || payload.args || {};
+  let kind = null;
+  let name = null;
+  if (!tool.startsWith('mcp') && tool.includes('skill')) {
+    kind = 'skill';
+    name = ti.skill ?? ti.name ?? ti.skill_name;
+  } else if (tool === 'agent' || tool === 'task') {
+    kind = 'agent';
+    name = ti.subagent_type ?? ti.agent;
+  }
+  if (!kind || typeof name !== 'string') return null;
+  name = name.trim().replace(/^\/+/, '');
+  return NAME_RE.test(name) ? { kind, name } : null;
+}
+
+/** Append one line for `payload` under `root`, if it is a counted call. Never throws. */
+export function recordUse(root, payload, now = new Date()) {
+  try {
+    if (!root || process.env.GENESEED_NO_USAGE) return;
+    const use = usageOf(payload);
+    if (!use) return;
+    if (existsSync(path.join(root, USAGE_OFF))) return;
+    const dir = path.join(root, 'notebook');
+    if (!existsSync(dir)) return;
+    appendFileSync(path.join(root, USAGE_LEDGER),
+      `${JSON.stringify({ ts: now.toISOString().slice(0, 10), ...use })}\n`);
+  } catch { /* a counter never fails a tool call */ }
+}

package/js/inspect/checks-repo.mjs

@@ -10,7 +10,7 @@ import path from 'node:path';
 import {
   ALIASES_RE, PLUGIN_SRC, RETIRED_SKILL_IDS, ROOT, SRC, THEMES, WORKFLOW_SRC, aliasesOf, knownSkillIds,
 } from '../build/source.mjs';
-import { CLAUDE_STYLE, liveRecordedHooks } from '../hosts/hosts.mjs';
+import { CLAUDE_STYLE, HOSTS, liveRecordedHooks } from '../hosts/hosts.mjs';
 import { claudeCfg, installTargets } from '../hosts/installs.mjs';
 import { VENDORED_SKILL_DIRS } from '../hosts/native.mjs';
 import { COMMAND_SET } from '../hosts/opencode.mjs';
@@ -507,6 +507,81 @@ export function moduleMapProblems() {
   return problems;
 }
 
+/**
+ * Each host's label as the two hand-written tables below spell it, keyed by `HOSTS`' `host` id.
+ *
+ * Local to this arm rather than a column on `HOSTS` (`js/hosts/hosts.mjs`): `HOSTS` is the
+ * machine-facing table (config dirs, project markers, catalog flags), and a doc-table LABEL is
+ * a fact about two Markdown files, not about an install.
+ */
+const HOST_LABELS = { opencode: 'OpenCode', claude: 'Claude Code', bob: 'Bob', openclaude: 'OpenClaude' };
+
+/**
+ * The two hand-written, one-column-per-host tables, and the non-host columns each one carries
+ * (a header cell that is neither a `HOST_LABELS` value nor one of these is an unknown label
+ * that LOOKS like it was meant to be a host column).
+ */
+const HOST_MATRIX_FILES = [
+  { rel: 'docs/concepts/host-matrix.md', otherCols: new Set(['Capability']) },
+  { rel: 'docs/concepts/enforcement-table.md', otherCols: new Set(['id', 'Pack']) },
+];
+
+/** The first `| … |` table row of `text`, as trimmed, non-empty cells — its header. */
+function firstTableHeader(text) {
+  for (const line of text.split('\n')) {
+    const t = line.trim();
+    if (t.startsWith('|')) return t.split('|').map((c) => c.trim()).filter((c) => c.length > 0);
+  }
+  return null;
+}
+
+/**
+ * `js/README.md`'s sibling gate for the two hand-written host tables: each one's header row
+ * must name exactly the hosts `HOSTS` lists, by their `HOST_LABELS` spelling — no fewer (a new
+ * host shipped with no column) and no stray cell that merely LOOKS like a host label (a typo,
+ * or a host renamed in `HOST_LABELS` but not in the doc).
+ *
+ * A host with no `HOST_LABELS` entry is its own problem, independent of either file: nothing
+ * in a table header can be compared against a label that does not exist.
+ *
+ * `root` is a parameter (default: `ROOT`) so a test can point this at a temp copy with one
+ * column removed, rather than mutating the real docs tree.
+ */
+export function hostMatrixProblems(root = ROOT) {
+  const problems = [];
+  const expected = new Set();
+  for (const h of HOSTS) {
+    const label = HOST_LABELS[h.host];
+    if (!label) { problems.push(`[authoring] host ${h.host} has no HOST_LABELS entry`); continue; }
+    expected.add(label);
+  }
+  for (const { rel, otherCols } of HOST_MATRIX_FILES) {
+    let text;
+    try {
+      text = readText(path.join(root, ...rel.split('/')));
+    } catch (e) {
+      problems.push(`[authoring] ${rel} is unreadable: ${e.message}`);
+      continue;
+    }
+    const header = firstTableHeader(text);
+    if (!header) {
+      problems.push(`[authoring] ${rel} has no table header row`);
+      continue;
+    }
+    const present = new Set(header);
+    for (const label of [...expected].sort()) {
+      if (!present.has(label)) problems.push(`[authoring] ${rel} has no column for ${label}`);
+    }
+    for (const cell of header) {
+      if (!expected.has(cell) && !otherCols.has(cell)) {
+        problems.push(`[authoring] ${rel} column '${cell}' is not a host HOST_LABELS names or `
+          + 'a known non-host column — a stale or misspelled label');
+      }
+    }
+  }
+  return problems;
+}
+
 /**
  * The AI Harness Scorecard checks this repo passes, written out — the ratchet's floor.
  *