geneseed 4.1.0 → 4.2.0

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.
  *

package/js/inspect/cost.mjs

@@ -0,0 +1,83 @@
+/**
+ * WHAT ONE INSTALL COSTS EVERY SESSION, read off the files it emitted — the Overview's
+ * always-on figure. Characters, not tokens: the console shows ≈ chars ÷ 4 and says it is an
+ * estimate, because a tokenizer would be a vendored dependency for a number that only has to
+ * be honest about its size.
+ *
+ * Four parts, each the thing the host loads before the user types:
+ * - `carrier`  the root instruction file (`AGENT.md`, `CLAUDE.md`, Bob's `rules/geneseed.md` or
+ *              `AGENTS.md`), CRLF decoded exactly as the smoke test decodes it, so the figure
+ *              and `CARRIER_CEILING` are the same measurement.
+ * - `skills`   the name + description every native skill lists (aliases included: they are
+ *              SKILL.md files the host lists like any other).
+ * - `agents`   the same for native agents; Bob has none, its agents table is in the carrier.
+ * - `context`  the session files the context hook injects (untouched seeds already skipped).
+ *              The per-repo project context is NOT counted: it changes with the working dir.
+ */
+import path from 'node:path';
+
+import { sessionFiles } from '../hosts/hooks-context.mjs';
+import { carriersFor } from '../hosts/installs.mjs';
+import { frontmatter } from '../hosts/memory-files.mjs';
+import { listDir } from '../hosts/hooks-prims.mjs';
+import { isFile, readText } from '../lib/fs.mjs';
+
+/**
+ * THE ANTI-BLOAT CEILING on the carrier, per footprint — the most a root file may weigh with
+ * every doctrine pack active. `tests/unit/emit_smoke.test.mjs` gates every emit against it and the
+ * console draws it on the cost chart, so it lives here, once, where both read it. Raise it by
+ * exactly the measured overrun and say why in that test's docblock, which keeps its history.
+ */
+export const CARRIER_CEILING = { full: 62_076, lean: 38_890 };
+
+const decode = (p) => readText(p).split('\r\n').join('\n');
+
+/**
+ * A frontmatter value as the host shows it. The emit writes descriptions JSON-escaped
+ * (`—` for one em dash), and `frontmatter()` has already stripped the quotes, so the
+ * escapes are decoded here or one character counts as six.
+ */
+function fmValue(raw) {
+  if (!raw) return '';
+  if (raw.includes('\\')) {
+    try { return JSON.parse(`"${raw}"`); } catch { /* not a JSON escape after all: count as written */ }
+  }
+  return raw;
+}
+
+/** name + description of one spec file; `fallbackName` for agents, whose name is the file stem. */
+function listedChars(file, fallbackName) {
+  let fm;
+  try { [fm] = frontmatter(decode(file)); } catch { return 0; }
+  const name = fmValue(fm.get('name')) || fallbackName;
+  return name.length + fmValue(fm.get('description')).length;
+}
+
+/**
+ * `root` is the install's root (`installTargets`), `dir` its data dir (`viewCfg`), which holds
+ * `skills/`, `agents/` and the session files. Every part that cannot be read counts 0; a missing
+ * carrier answers `null` for the whole cost, so the console shows "not measured", not a tiny bar.
+ */
+export function alwaysOnCost({ host, root, dir, footprint }) {
+  const carrierPath = carriersFor(host).map((rel) => path.join(root, rel)).find(isFile);
+  if (!carrierPath) return null;
+  const carrier = decode(carrierPath).length;
+
+  let skills = 0;
+  const skillsDir = path.join(dir, 'skills');
+  for (const name of listDir(skillsDir)) {
+    const f = path.join(skillsDir, name, 'SKILL.md');
+    if (isFile(f)) skills += listedChars(f, name);
+  }
+  let agents = 0;
+  if (host !== 'bob') {
+    const agentsDir = path.join(dir, 'agents');
+    for (const name of listDir(agentsDir)) {
+      if (name.endsWith('.md')) agents += listedChars(path.join(agentsDir, name), name.slice(0, -3));
+    }
+  }
+  let context = 0;
+  try { for (const s of sessionFiles(dir)) context += s.text.length; } catch { /* none */ }
+
+  return { carrier, skills, agents, context, ceiling: CARRIER_CEILING[footprint] ?? null };
+}

package/js/inspect/doctor.mjs

@@ -42,7 +42,7 @@ import { authoringProblems, loopProblems } from './checks-authoring.mjs';
 import {
   checkBuild, colorThemeProblems, renderedProblems, themeParityProblems,
 } from './checks-build.mjs';
-import { moduleMapProblems, scorecardProblems, shimProblems } from './checks-repo.mjs';
+import { hostMatrixProblems, moduleMapProblems, scorecardProblems, shimProblems } from './checks-repo.mjs';
 import { NOTE, isDoctorNote, sortedProblems, sortedUnique, stemOf, withTempDir } from './scan.mjs';
 
 /**
@@ -249,6 +249,7 @@ export function doctorCollect({
   problems = problems.concat(ran('openclaude_dual', 'OpenClaude dual harness',
     openclaudeDualHarnessNotes()));
   problems = problems.concat(ran('map', 'Module map', moduleMapProblems()));
+  problems = problems.concat(ran('host_matrix', 'Host tables', hostMatrixProblems()));
   problems = problems.concat(ran('scorecard', 'Scorecard floor', scorecardProblems()));
   // P10c's `cli` check is GONE, and the reason is not that it stopped mattering. It hashed
   // `rituals/harness.py` and compared that against a digest baked into `cli.json`, to catch a

package/js/inspect/inventory.mjs

@@ -106,7 +106,7 @@ export const SKILL_CLASS = {
   // knowledge base, terminal) rather than about the user's code. They sat under
   // `understand` before, which made that class a grab-bag.
   wiki: 'harness', geneseed: 'harness', rule: 'harness', profile: 'harness',
-  herdr: 'harness', 'skill-forge': 'harness',
+  'skill-forge': 'harness',
   teach: 'learn', quiz: 'learn', 'learn-mode': 'learn',
 };