geneseed 4.0.0 → 4.2.0

package/js/hosts/mcp.mjs

@@ -1,22 +1,15 @@
 /**
- * MCP server presets, state and config I/O — `rituals/_harness_mcp.py`'s MCP block.
+ * MCP server state and config reading — `rituals/_harness_mcp.py`'s MCP block, minus its writers.
  *
- * WHAT THE PLAN SAID AND WHAT READING FOUND. The P6f plan scored `api_mcp` + `api_mcp_toggle`
- * at "~90 new, already in js/: `_mcp_load`/`readJsonc` (P6c), `settings.mjs`'s atomic write".
- * Measured against `js/`: `readJsonc` had crossed and NOTHING ELSE HAD. `js/web/api.mjs`
- * carries a five-line `mcpLoad` that is the no-host, comment-tolerant reader P6c needed for
- * `geneseed-wiki.jsonc`, which is one arm of one of these thirteen functions. `_MCP_PRESETS`,
- * `_mcp_servers_key`, `_mcp_preset_block`, `_mcp_apply`, `_mcp_state`, `_mcp_set_enabled`,
- * `_mcp_load`'s host fork, `_mcp_commented`, `_mcp_save`, `_mcp_config_for`,
- * `_mcp_install_targets`, `_mcp_known_names` and `_mcp_meta` are 168 lines of Python, all
- * new. The endpoints on top of them are the small half.
+ * READ-ONLY BY DECISION (2026-10). Which MCP servers an install wires depends on the user and on
+ * the host, so Geneseed shows what each config already holds and where that file lives, and the
+ * user edits it. The three presets (`MCP_PRESETS`), the block shaper, the applier, the
+ * enable/disable flip and the atomic saver went with the console's Add button and toggle;
+ * `docs/guides/mcp*.md` carry the blocks a user copies by hand. Nothing here writes.
  *
- * THE ROUND TRIP IS THE HAZARD, and it is why every read here goes through `parseJson`.
- * `_mcp_save` rewrites the WHOLE config, not the servers map — and for a Claude global
- * install that config is `~/.claude.json`, which holds projects and history far beyond MCP
- * wiring. A `JSON.parse` would turn every `"temperature": 1.0` in somebody's real file into
- * `1` on the way back out. `readJsonc` already learned this; the strict-JSON fork has to
- * learn it separately, because it does not go through `readJsonc` at all.
+ * THE READ IS STILL HOST-SHAPED. OpenCode nests servers under `mcp` with an `enabled` flag and
+ * may be `.jsonc`; the Claude-shaped three use `mcpServers`, are strict JSON, and have no flag —
+ * present IS enabled. `uninstall` reads through `mcpLoad` too.
  *
  * A JsonNumber IS AN OBJECT TO `typeof`, which is why `isDict` (js/lib/json.mjs) excludes
  * the wrapper rather than testing `typeof v === 'object'`. Python's `isinstance(x, dict)` is
@@ -31,7 +24,7 @@ import { installState, installTargets } from './installs.mjs';
 import { printOut, printErr } from '../lib/fs.mjs';
 import { isDict } from '../lib/json.mjs';
 import { padEndToWidth } from '../lib/text.mjs';
-import { atomicWriteJson, loadJsonObject, opencodeTarget } from './settings.mjs';
+import { loadJsonObject, opencodeTarget } from './settings.mjs';
 
 
 /** `dict.get(key, default)`. */
@@ -40,52 +33,6 @@ const dget = (obj, key, dflt) => (isDict(obj) && Object.hasOwn(obj, key) ? obj[k
 /** The hosts whose MCP config is strict JSON under `mcpServers`, with no `enabled` flag. */
 const FLAGLESS = CLAUDE_STYLE;
 
-/**
- * `_harness_mcp._MCP_PRESETS` — the ready-to-wire servers the MCP screen can toggle.
- *
- * The `desc` strings go on the wire verbatim (`api_mcp` returns them), so they are the one
- * place in this file where a byte matters more than the shape. Insertion order is the
- * listing order.
- */
-export const MCP_PRESETS = {
-  markitdown: {
-    label: 'MarkItDown',
-    desc: 'PDF / Office / HTML -> Markdown for the ingest skill. Runs via `uvx` '
-      + '(needs uv; zero-install, fetches on first call). No uv? Switch the command '
-      + 'to ["markitdown-mcp"] after `pipx install markitdown-mcp`. Exposes one '
-      + 'tool: convert_to_markdown(uri).',
-    block: { type: 'local', command: ['uvx', 'markitdown-mcp'], enabled: true },
-  },
-  gitlab: {
-    label: 'GitLab',
-    desc: 'GitLab repo / MR / issue / CI tools via @zereight/mcp-gitlab (npx, no '
-      + 'install). Edit GITLAB_PERSONAL_ACCESS_TOKEN (scopes: api, read_repository) '
-      + 'and GITLAB_API_URL before use. For a second instance (a self-hosted server), '
-      + 'copy this block by hand under a new name and point it at the other URL — '
-      + 'docs/guides/mcp-gitlab.md has the pattern.',
-    block: {
-      type: 'local',
-      command: ['npx', '-y', '@zereight/mcp-gitlab'],
-      environment: { GITLAB_PERSONAL_ACCESS_TOKEN: '',
-        GITLAB_API_URL: 'https://gitlab.com/api/v4' },
-      enabled: true,
-    },
-  },
-  filesystem: {
-    label: 'Filesystem',
-    desc: 'Read/write files under explicitly allowed directories via '
-      + '@modelcontextprotocol/server-filesystem (npx, no install). Replace the '
-      + 'trailing path arg(s) with only the dir(s) the agent may touch '
-      + '(least-privilege).',
-    block: {
-      type: 'local',
-      command: ['npx', '-y', '@modelcontextprotocol/server-filesystem',
-        '/path/to/allowed/dir'],
-      enabled: true,
-    },
-  },
-};
-
 /** `_mcp_servers_key` — OpenCode nests servers under `mcp`, the other three `mcpServers`. */
 const serversKey = (host) => (FLAGLESS.includes(host) ? 'mcpServers' : 'mcp');
 
@@ -95,50 +42,11 @@ const serversOf = (config, host) => {
   return isDict(s) ? s : {};
 };
 
-/**
- * `_mcp_preset_block` — the block to WRITE for a preset, shaped for `host`.
- *
- * OpenCode takes it verbatim. The flagless three split the command list into `command`
- * (head) + `args` (tail) and rename `environment` to `env`.
- */
-export function mcpPresetBlock(name, host = 'opencode') {
-  const block = { ...MCP_PRESETS[name].block };
-  if (!FLAGLESS.includes(host)) return block;
-  const cmd = [...(block.command || [])];
-  const out = { command: cmd.length ? cmd[0] : '', args: cmd.slice(1) };
-  const env = block.environment;
-  if (env) out.env = { ...env };
-  return out;
-}
-
-/**
- * `_mcp_apply` — a COPY of `config` with server `name` set to `block`, or removed when
- * `block` is null. Never touches another key; drops an emptied servers map.
- *
- * The key ORDER is behaviour, not cosmetics: `setdefault` appends `$schema` at the end of a
- * fresh dict and leaves an existing one where it is, and `_mcp_save` writes the result out
- * as the file the user then reads. `{...config}` plus a guarded assignment is the same rule.
- */
-export function mcpApply(config, name, block, host = 'opencode') {
-  const cfg = { ...config };
-  const key = serversKey(host);
-  if (host === 'opencode' && !Object.hasOwn(cfg, '$schema')) {
-    cfg.$schema = 'https://opencode.ai/config.json';
-  }
-  const servers = { ...serversOf(cfg, host) };
-  if (block === null) delete servers[name];
-  else servers[name] = block;
-  if (Object.keys(servers).length) cfg[key] = servers;
-  else delete cfg[key];
-  return cfg;
-}
-
 /**
  * `_mcp_state` — 'enabled' | 'disabled' | 'absent'.
  *
  * OpenCode: a present server with no explicit `enabled` counts as enabled (its default).
- * The flagless three have no such key, so present IS enabled and 'disabled' never occurs —
- * toggling one off removes its entry instead.
+ * The flagless three have no such key, so present IS enabled and 'disabled' never occurs.
  */
 export function mcpState(config, name, host = 'opencode') {
   const server = serversOf(config, host)[name];
@@ -147,25 +55,13 @@ export function mcpState(config, name, host = 'opencode') {
   return dget(server, 'enabled', true) ? 'enabled' : 'disabled';
 }
 
-/** `_mcp_set_enabled` — flip a present server's enabled-ness. No-op when it is absent. */
-export function mcpSetEnabled(config, name, enabled, host = 'opencode') {
-  const server = serversOf(config, host)[name];
-  if (!isDict(server)) return config;
-  if (FLAGLESS.includes(host)) {
-    return enabled ? config : mcpApply(config, name, null, host);
-  }
-  return mcpApply(config, name, { ...server, enabled }, host);
-}
-
 /**
  * `_mcp_load` — a config as a dict; `{}` when missing, unreadable, unparseable or not an
  * object.
  *
  * The host fork is the whole function. OpenCode is read comment-tolerantly because a
  * hand-maintained `opencode.jsonc` carries `//`; the other three are read STRICTLY, because
- * their configs are plain JSON by contract, and a file that does not parse as such — for a
- * Claude global install, one that holds projects and history — is not one to rewrite from a
- * best-effort reading. (The comment stripper's trailing-comma pass IS string-aware; an older
+ * their configs are plain JSON by contract. (The comment stripper's trailing-comma pass IS string-aware; an older
  * version of this note said otherwise, and `generate.test.mjs` pins the string-aware case.)
  */
 export function mcpLoad(p, host = 'opencode') {
@@ -179,11 +75,6 @@ export function mcpCommented(p) {
   return loadJsonObject(p).hadComments;
 }
 
-/** `_mcp_save` — pretty JSON, written ATOMICALLY. The one writer, under its MCP name. */
-export function mcpSave(p, config) {
-  atomicWriteJson(p, config);
-}
-
 /**
  * `_mcp_config_for` — the file an install writes its MCP servers into, or null for a host
  * that carries no MCP wiring at that scope.
@@ -222,19 +113,9 @@ export function mcpInstallTargets() {
   return out;
 }
 
-/** `_mcp_known_names` — the presets first, then any server already in THIS config. */
-export function mcpKnownNames(config, host = 'opencode') {
-  const names = Object.keys(MCP_PRESETS);
-  const present = isDict(config) ? Object.keys(serversOf(config, host)) : [];
-  return names.concat(present.filter((n) => !Object.hasOwn(MCP_PRESETS, n)));
-}
-
-/** `_mcp_meta` — (label, description); the bare name and a generic note for an unknown one. */
-export function mcpMeta(name) {
-  const p = MCP_PRESETS[name];
-  if (p) return [p.label, p.desc];
-  return [name, 'User-defined MCP server (not a Harness preset). It lives in this '
-    + "config already — 'e' enables/disables it, Enter removes it."];
+/** The servers THIS config already has, in file order. Nothing it could have. */
+export function mcpServerNames(config, host = 'opencode') {
+  return isDict(config) ? Object.keys(serversOf(config, host)) : [];
 }
 
 export { isDict };
@@ -242,22 +123,11 @@ export { isDict };
 // ---- the verb ----------------------------------------------------------------------------
 
 /**
- * `geneseed mcp` — the CLI FACE this library never had.
- *
- * Everything above crossed with the web console rather than with a subcommand: the reference
- * kept it as a preset/state library whose only command was the uninstall path, and the one
- * way to see which servers an install had wired was to start a server and look. That is the
- * gap this verb closes, and it closes it by CALLING the library — the same `mcpInstallTargets`
- * / `mcpLoad` / `mcpKnownNames` / `mcpState` / `mcpMeta` sequence the console's read endpoint
- * runs, rendered as text instead of as JSON.
+ * `geneseed mcp` — the servers each active install has wired, and the file they live in.
  *
- * ponytail: READ-ONLY, on purpose, and this is the ceiling. Wiring a server from here needs
- * the console's toggle orchestration, whose load-bearing part is not the toggle at all — it
- * is the refusal to rewrite a config it could not parse strictly, because for a global
- * Claude install that file holds projects and history and a rewrite from an empty object
- * would erase them. A second copy of that guard is a second place for it to be wrong. When a
- * terminal toggle is wanted, move the console's non-HTTP core down into this module and have
- * both faces call it; do not grow a parallel one here.
+ * The same `mcpInstallTargets` / `mcpLoad` / `mcpServerNames` / `mcpState` sequence the
+ * console's read endpoint runs, rendered as text instead of as JSON. Read-only like the
+ * console: there is nothing here to add or toggle a server with.
  */
 export function cmdMcp() {
   const targets = mcpInstallTargets()
@@ -272,9 +142,10 @@ export function cmdMcp() {
     if (mcpCommented(p)) {
       printOut('  this config carries comments — edit it by hand so they survive.\n');
     }
-    for (const name of mcpKnownNames(cfg, host)) {
-      const [lbl] = mcpMeta(name);
-      printOut(`  ${padEndToWidth(mcpState(cfg, name, host), 8)}  ${padEndToWidth(name, 12)}  ${lbl}\n`);
+    const names = mcpServerNames(cfg, host);
+    if (!names.length) printOut('  no MCP server configured\n');
+    for (const name of names) {
+      printOut(`  ${padEndToWidth(mcpState(cfg, name, host), 8)}  ${name}\n`);
     }
   }
   return 0;

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/opencode.mjs

@@ -114,7 +114,7 @@ export const COMMAND_SET = {
 };
 
 /** Mirrors `_build_emit.PONYTAIL_COMMAND_BODY`. */
-const PONYTAIL_COMMAND_BODY =
+export const PONYTAIL_COMMAND_BODY =
   'Ponytail level requested: $ARGUMENTS\n\n'
   + 'The geneseed-ponytail plugin records this level and, from your next turn, appends '
   + 'the matching "laziest solution that works" ruleset to your system prompt — honour '

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 */ }
+}