geneseed 4.4.1 → 4.6.0

package/js/hosts/hooks-done.mjs

@@ -0,0 +1,186 @@
+/**
+ * The done gate — Verify Before Asserting's boundary half, at the moment a turn ends (#289).
+ *
+ * Every other gate sits before an act. This one sits at Stop: a turn that edited files under a
+ * project which lists its proof in `.geneseed/done-checks.txt` may not end until every listed
+ * check has run AND passed after the last edit. The gate never runs a check itself — the hook
+ * path starts no process of its own (ADR 0002) — it reads the turn's own tool calls in the transcript.
+ *
+ * WHY IT RIDES `learn` AND NOT A VERB OR A FLAG OF ITS OWN (ADR 0010). The machine-wide shim is
+ * last-writer-wins: an older `geneseed-hook` would refuse a new verb or flag, and the Stop
+ * command's `|| exit 0` would then skip learning too, silently. Arming on a project FILE keeps
+ * every emitted settings file byte-identical, so a stale shim only means "no done gate".
+ *
+ * WHY STDOUT JSON AND NOT EXIT 2. The emitted Stop command ends in `|| exit 0`, which swallows
+ * a 2. `{"decision":"block"}` on exit 0 is the one signal that survives the existing wiring.
+ * Allowing prints NOTHING — on Stop a stray stdout byte is read as a verdict.
+ *
+ * WHAT COUNTS (shortcut: write tools only; a shell `sed -i` or redirect is not an edit here —
+ * seeing those would need `git status`, a spawn. Same limit as `protected-checks.txt`):
+ *   - an edit is a Write/Edit/NotebookEdit/MultiEdit whose target is under the project root and
+ *     whose result is not an error (a denied write changed nothing);
+ *   - a pass is a Bash/PowerShell call whose command contains the declared line UNPIPED (a pipe
+ *     takes the exit code of its last stage: `npm test | tail` exits 0 on a red suite) and whose
+ *     result is not `is_error` — every non-zero exit, denial and timeout carries it (checked on
+ *     14 000+ real Claude Code results, 2026-10-17).
+ *
+ * At most one block per turn: `stop_hook_active` is true when this Stop follows a block, and the
+ * gate then lets the turn end and leaves a ledger line, so a gate that cries wolf gets found.
+ */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { readText, printOut as out, printErr as err } from '../lib/fs.mjs';
+import { within } from '../lib/paths.mjs';
+import { gitRootOf } from './gitref.mjs';
+import { DONE_LIST, recordGate } from './hooks.mjs';
+import { splitLines } from './hooks-prims.mjs';
+
+const EDIT_TOOLS = new Set(['Write', 'Edit', 'NotebookEdit', 'MultiEdit']);
+const SHELL_TOOLS = new Set(['Bash', 'PowerShell']);
+
+/** The declared checks, one per line, `#` comments; null when the project has no list. */
+export function readDoneChecks(root) {
+  const file = path.join(root, DONE_LIST);
+  if (!existsSync(file)) return null;
+  try {
+    return splitLines(readText(file)).map((l) => l.trim().replace(/\s+/g, ' '))
+      .filter((l) => l && !l.startsWith('#'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True when `command` runs `line` as a whole command with no pipe after it in the same segment.
+ * A segment ends at `&&`, `||`, `;` or a newline; a single `|` before that end is a pipe. The
+ * check must open a segment (the start, or right after one of those separators) and be followed
+ * by the end, whitespace or a separator, never by more of a word (`npm run lint:fix` does not
+ * prove `npm run lint`); a match inside a quoted string (`-m "ran npm test"`) is text, not a run.
+ * Whitespace is collapsed on both sides. shortcut: the shell is not parsed — a prefix such as
+ * `sudo`/`time`/`env X=1`, a subshell, or a `|` inside a quoted argument after the check all read
+ * as "not run". Every approximation here refuses a pass, so the gate errs toward a reminder.
+ */
+export function runsUnpiped(command, line) {
+  const cmd = String(command).replace(/[ \t]+/g, ' ');
+  for (let i = cmd.indexOf(line); i !== -1; i = cmd.indexOf(line, i + 1)) {
+    const next = cmd[i + line.length];
+    if (next !== undefined && !/[\s;&|]/.test(next)) continue;
+    const head = cmd.slice(0, i);
+    if (!/(^|&&|\|\||;|\n) ?$/.test(head)) continue;
+    let quote = '', esc = false;
+    for (const ch of head) {
+      if (esc) esc = false;
+      else if (ch === '\\' && quote !== "'") esc = true;
+      else if (quote) { if (ch === quote) quote = ''; }
+      else if (ch === '"' || ch === "'") quote = ch;
+    }
+    if (quote) continue;
+    const rest = cmd.slice(i + line.length);
+    let piped = false;
+    for (let j = 0; j < rest.length; j += 1) {
+      const two = rest.slice(j, j + 2);
+      if (two === '&&' || two === '||' || rest[j] === ';' || rest[j] === '\n') break;
+      if (rest[j] === '|') { piped = true; break; }
+    }
+    if (!piped) return true;
+  }
+  return false;
+}
+
+/** A user line that opens a turn: the user typed it, it is not a tool result or a meta note. */
+function isPrompt(obj) {
+  if (obj.type !== 'user' || obj.isMeta || obj.isSidechain) return false;
+  const c = obj.message && obj.message.content;
+  if (typeof c === 'string') return true;
+  return Array.isArray(c) && c.length > 0 && !c.some((b) => b && b.type === 'tool_result');
+}
+
+/**
+ * The decision, over transcript TEXT: the checks that have not passed since the turn's last
+ * edit, or [] when the turn may end (no edit, or every check passed after it). Exported for the
+ * unit tier — a transcript is text no CLI cell can vary cheaply.
+ */
+export function doneDecide(transcript, checks, root, cwd = root) {
+  const entries = [];
+  for (const line of splitLines(transcript)) {
+    if (!line.trim()) continue;
+    try { entries.push(JSON.parse(line)); } catch { /* a torn last line is not evidence */ }
+  }
+  let start = 0;
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    if (isPrompt(entries[i])) { start = i + 1; break; }
+  }
+  const calls = [];                      // tool_use blocks, in order
+  const results = new Map();             // tool_use_id -> is_error
+  for (const obj of entries.slice(start)) {
+    if (obj.isSidechain) continue;
+    const content = obj.message && obj.message.content;
+    if (!Array.isArray(content)) continue;
+    for (const b of content) {
+      if (!b || typeof b !== 'object') continue;
+      if (b.type === 'tool_use') calls.push(b);
+      else if (b.type === 'tool_result') results.set(b.tool_use_id, b.is_error === true);
+    }
+  }
+  let lastEdit = -1;
+  calls.forEach((c, i) => {
+    if (!EDIT_TOOLS.has(c.name) || results.get(c.id) === true) return;
+    const p = c.input && (c.input.file_path || c.input.notebook_path || c.input.path);
+    if (typeof p === 'string' && p && within(path.resolve(cwd, p), root)) lastEdit = i;
+  });
+  if (lastEdit === -1) return [];
+  const passed = new Set();
+  calls.slice(lastEdit + 1).forEach((c) => {
+    const command = SHELL_TOOLS.has(c.name) && c.input && c.input.command;
+    // A call with no result yet (the host has not flushed it) is not a pass.
+    if (typeof command !== 'string' || results.get(c.id) !== false) return;
+    for (const check of checks) if (runsUnpiped(command, check)) passed.add(check);
+  });
+  return checks.filter((c) => !passed.has(c));
+}
+
+/**
+ * The Stop-side wrapper `cmdLearn` calls first. Returns true when it printed a block (the turn
+ * goes on, so `learn` must not distil yet); false in every other case, with nothing on stdout.
+ * `install` is the root `cmdLearn` already derived from `--memory` (null without one), so the
+ * ledger lands in the same root its sovereignty check read.
+ */
+export function doneGate(meta, args, install) {
+  try {
+    const cwd = typeof meta.cwd === 'string' && meta.cwd ? meta.cwd : process.cwd();
+    const root = gitRootOf(cwd);
+    const checks = root ? readDoneChecks(root) : null;
+    if (!checks || !checks.length) return false;
+    // Bob's Stop payload carries no transcript (learn's I2): nothing to judge, and it says so.
+    if (args.host === 'bob' || typeof meta.transcript_path !== 'string') {
+      err(`[done-gate] no transcript${args.host === 'bob' ? ' (bob)' : ''} — turn not judged.\n`);
+      return false;
+    }
+    let transcript;
+    try {
+      transcript = readText(meta.transcript_path);
+    } catch {
+      // No ask tier on Stop: blocking on an unreadable transcript would trap the user.
+      err('[done-gate] transcript unreadable — turn not judged.\n');
+      return false;
+    }
+    const missing = doneDecide(transcript, checks, root, cwd);
+    if (!missing.length) return false;
+    if (meta.stop_hook_active === true) {
+      recordGate(install, 'done-gate-cap', 'law-3');
+      err(`[done-gate] cap reached — turn ends with unproven checks: ${missing.join('; ')}\n`);
+      return false;
+    }
+    recordGate(install, 'done-gate', 'law-3');
+    out(`${JSON.stringify({
+      decision: 'block',
+      reason: 'Geneseed (Verify Before Asserting) — this turn edited files, and these '
+        + `checks from ${DONE_LIST} have not passed since the last edit: ${missing.join('; ')}. `
+        + 'Run them unpiped, or say plainly that they were not run and why.',
+    })}\n`);
+    return true;
+  } catch (e) {
+    err(`[done-gate] skipped: ${e && e.message}\n`);
+    return false;
+  }
+}

package/js/hosts/hooks-learn.mjs

@@ -13,6 +13,7 @@ import {
   globalHookStandingDown, hookProjectDir, resolveMemoryDir, sovereignBypass,
 } from './hosts.mjs';
 import { readStdin, splitLines, splitWords } from './hooks-prims.mjs';
+import { doneGate } from './hooks-done.mjs';
 import {
   existingSlugs, readFacts, writeMemories, consolidateMemory, appendAgentLesson,
 } from './memory-files.mjs';
@@ -292,12 +293,12 @@ export function cmdLearn(args) {
   }
 
   // The Stop/SubagentStop hook always passes `--memory <cfg>/memory`; inside an excluded
-  // folder the global install must not learn.
-  if (args.memory && sovereignBypass(path.dirname(toPlatformPath(args.memory)))) return 0;
+  // folder the global install must not learn. The done gate's ledger lives in the same root.
+  const install = args.memory ? path.dirname(toPlatformPath(args.memory)) : null;
+  if (install && sovereignBypass(install)) return 0;
   // Same install root, and a project install of this host beside it learns on its own Stop: a
   // second LLM call, and the global store learning facts the project owns (Claude B4).
-  if (args.memory && globalHookStandingDown(path.dirname(toPlatformPath(args.memory)),
-    hookProjectDir(), args.host, 'learn')) return 0;
+  if (install && globalHookStandingDown(install, hookProjectDir(), args.host, 'learn')) return 0;
 
   const raw = args.file ? readText(args.file) : readStdin();
   const meta = hookMeta(raw);
@@ -309,6 +310,10 @@ export function cmdLearn(args) {
   const hookEvent = typeof meta.hook_event_name === 'string' ? meta.hook_event_name
     : (typeof meta.event === 'string' ? meta.event : null);
 
+  // The done gate (#289) judges the turn BEFORE anything here spawns, and only on Stop. A block
+  // means the turn goes on, so there is nothing to distil yet: the next Stop will.
+  if (hookEvent === 'Stop' && !args.file && doneGate(meta, args, install)) return 0;
+
   // I2 (Bob): its Stop payload never carries `transcript_path`, so there is never a transcript
   // to distil — and the bare envelope itself is not notes text (that would waste a model call
   // on `{"event":"Stop","session_id":"s"}`). Scoped to `--host bob`: every other host's Stop/

package/js/hosts/hooks.mjs

@@ -255,8 +255,12 @@ const BLOCK_RULES = new Set(['law-1', 'law-4', 'rigor-5', 'ops-2']);
  * information a trimmed file loses. The re-read happens on the ask path only.
  */
 const MAX_LEDGER_LINES = 1000;
+// Exported for the done gate (`./hooks-done.mjs`), which records from Stop, not from `ask`.
+export function recordGate(root, verb, rule) { ledger(root, verb, rule); }
 function ledger(root, verb, rule) {
-  if (!root) return;
+  // `doctor --probe` asks on purpose; its asks are not the user's. Read here, on the rare ask
+  // path only: the variable silences the RECORD, never the decision.
+  if (!root || process.env.GENESEED_GATE_PROBE) return;
   try {
     const file = path.join(root, GATE_LEDGER);
     appendFileSync(file, `${JSON.stringify({
@@ -441,6 +445,8 @@ export function rootScan(command) {
       const m = /^-path[=:](.+)$/i.exec(t);
       return m ? m[1] : t;
     });
+    // For ls/dir a PowerShell `-Recurse` abbreviation counts from `-re` up: a bare `-r` there is the
+    // POSIX reverse flag (`ls -r /`, `dir -r C:\`). gci/Get-ChildItem keep the full abbreviation set.
     if (!always && !argv.some((a) => (grep && GREP_RECURSE_RE.test(a))
       || (ls && (LS_RECURSE_RE.test(a) || (a.length >= 3 && PS_RECURSE_RE.test(a))))
       || (ps && PS_RECURSE_RE.test(a)))) continue;
@@ -448,8 +454,6 @@ export function rootScan(command) {
   }
   return null;
 }
-// For ls/dir a PowerShell `-Recurse` abbreviation counts from `-re` up: a bare `-r` there is the
-// POSIX reverse flag (`ls -r /`, `dir -r C:\`). gci/Get-ChildItem keep the full abbreviation set.
 const unquote = (t) => t.replace(/^["']+|["']+$/g, '');
 // A QUOTED token is data — a grep pattern (`grep -rn "/" src`), a path named in a search
 // (`rg "/mnt/c" README.md`) — never a root target; only an unquoted root is one.
@@ -523,21 +527,25 @@ const SECRET_RE =
   /\b(?:AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,}|sk-ant-[A-Za-z0-9_-]{20,}|xox[abprs]-[0-9A-Za-z-]{10,})\b|-----BEGIN [A-Z ]*PRIVATE KEY-----/;
 const DOTENV_RE = /(^|[\\/])\.env(\.[^\\/]*)?$/;
 
+export const SENSOR_LIST = '.geneseed/protected-checks.txt';
+// The done gate's list (`./hooks-done.mjs`, #289) protects itself too, with or without a
+// protected-checks list: emptying it would disarm the gate it feeds.
+export const DONE_LIST = '.geneseed/done-checks.txt';
 /**
  * External Gate's boundary half: the checks an agent is judged by must sit outside what it can
  * edit, or a failing check is one edit away from a passing one. A project opts in by listing
  * them, one repo-relative path per line (`#` comments), in `.geneseed/protected-checks.txt` at
  * its git root — found by walking up from the WRITE TARGET, not the cwd, so a session in one repo
  * writing into another reads that other repo's list. The list protects itself. Returns the entry
- * the path falls under, or null. ponytail: a write tool only — a shell `sed -i` or redirect is
+ * the path falls under, or null. shortcut: a write tool only — a shell `sed -i` or redirect is
  * not seen here; CI running the checks is the boundary that holds against that.
  */
-export const SENSOR_LIST = '.geneseed/protected-checks.txt';
 function protectedCheck(p) {
   try {
     const target = resolvePath(p);
     const root = gitRootOf(path.dirname(target));
     if (!root) return null;
+    if (normcase(path.relative(root, target)) === normcase(DONE_LIST)) return DONE_LIST;
     const text = readFileSync(path.join(root, SENSOR_LIST), 'utf8');
     // `normcase` folds case AND slashes on Windows, so both sides go through it, the trailing
     // separator of the prefix included.
@@ -555,6 +563,14 @@ function ruleGate(args) {
   return ruleDecide(args, readPayload());
 }
 
+// The REPLACE halves of a Roo-style `apply_diff` (`<<<<<<< SEARCH … ======= <new> >>>>>>> REPLACE`).
+// A diff without those markers is a shape we do not know, so it is returned whole: fail closed.
+function diffReplaced(diff) {
+  if (typeof diff !== 'string') return diff;
+  const halves = [...diff.matchAll(/^=======\r?\n([\s\S]*?)^>>>>>>> REPLACE/gm)].map((m) => m[1]);
+  return halves.length ? halves.join('\n') : diff;
+}
+
 function ruleDecide(args, payload) {
   const ti = (payload && payload.tool_input) || {};
   // NotebookEdit names its target `notebook_path`; the settings matcher routes it here too.
@@ -567,9 +583,11 @@ function ruleDecide(args, payload) {
   // cheap, harmless guard in case that ever changes.
   // `diff` (Bob's `apply_diff`) and `replace`/`search` (`search_and_replace`) are Roo-lineage
   // field names the Bob docs never confirm (bob-verdict.md I1) — accepted when present, never
-  // required, same as every field above.
+  // required, same as every field above. Only WRITTEN text is scanned: `search` and a diff's
+  // SEARCH halves are text leaving the file (like Claude's `old_string`), so a secret there is
+  // being removed — blocking it would stop the agent cleaning up a leak.
   const edits = Array.isArray(ti.edits) ? ti.edits.map((e) => e && e.new_string) : [];
-  const body = [ti.content, ti.new_string, ti.new_source, ti.diff, ti.replace, ti.search, ...edits]
+  const body = [ti.content, ti.new_string, ti.new_source, diffReplaced(ti.diff), ti.replace, ...edits]
     .filter((v) => typeof v === 'string').join('\n');
   if (body && !DOTENV_RE.test(p) && SECRET_RE.test(body)) {
     return ask(args, 'rule-gate', 'law-1', `Geneseed (Sealed Secrets) — ${p} would carry a `
@@ -579,7 +597,8 @@ function ruleDecide(args, payload) {
   const sensor = protectedCheck(p);
   if (sensor) {
     return ask(args, 'rule-gate', 'rigor-5', `Geneseed (External Gate) — ${p} is a protected `
-      + `check (${sensor}, listed in ${SENSOR_LIST}). A check the agent can edit is not a `
+      + `check (${sensor === DONE_LIST ? 'the done gate list itself'
+        : `${sensor}, listed in ${SENSOR_LIST}`}). A check the agent can edit is not a `
       + 'check: fix the code, not the check, unless the user asks for this edit.');
   }
   const target = ruleGateTarget(p, args.root);

package/js/hosts/hosts.mjs

@@ -55,6 +55,8 @@ export function sovereignBypass(root) {
   } catch {
     return false;
   }
+  // Nothing to match, so no reason to pay for the cwd and `.git` reads below on every hook call.
+  if (!entries.length) return false;
   let heres;
   try {
     heres = [normcase(resolvePath(process.cwd()))];

package/js/hosts/installs.mjs

@@ -44,7 +44,7 @@ import { registryRoots } from '../inspect/registry.mjs';
 import { printErr, readText, isFile, isDir } from '../lib/fs.mjs';
 import { formatRepr, isDict } from '../lib/json.mjs';
 import { comparePaths } from '../lib/paths.mjs';
-import { claudeHookShell } from './shim.mjs';
+import { claudeHookShell, hookShimPath } from './shim.mjs';
 
 /**
  * `Path.read_text(encoding="utf-8")`, or null where Python raises OSError.
@@ -567,10 +567,10 @@ const EXCLUDED_SKILLS_RE = /^Excluded skills:[ \t]*(.+?)[ \t]*$/m;
  * name drops out (`resolveSkillNames`), so a skill merge does not quietly re-admit everything
  * else the install left out. Silent unless the caller passes `notify` — status, diff and the
  * console call this on every read; the replays that rebuild an install (`rebuild-all`,
- * `upgrade`, `migrate`) pass it. `host` is last, after `notify`, for the same reason
- * `trustOfDir` puts it last: every existing positional call keeps working unchanged.
+ * `upgrade`, `migrate`) pass it. `host` comes second, the same `(d, host)` order as its
+ * siblings `excludedRulesOfDir`/`doctrinesOfDir`, so the marker readers call alike.
  */
-export function excludedSkillsOfDir(d, notify = null, host = null) {
+export function excludedSkillsOfDir(d, host = null, notify = null) {
   return firstCarrier(d, (carrierPath) => {
     const text = readMaybe(carrierPath);
     if (text === null) return undefined;
@@ -615,9 +615,6 @@ export function emitHostScopeOf(root) {
   return EMIT_HOST_SCOPE.get(emit.trim()) ?? null;
 }
 
-// `DISABLED_STASH` moved to `hosts.mjs`: the hook stand-down reads it and must not import this.
-export { DISABLED_STASH };
-
 /**
  * `_harness_mcp._claude_cfg` — where a Claude-STYLE install keeps its manifest.
  *
@@ -733,12 +730,12 @@ export function installTargets() {
 
 /**
  * Each Claude install whose emitted hook FORM no longer matches this machine's hook shell
- * (`claudeHookShell`; Task 15) — the "Git Bash removed after the emit" gap, which otherwise
+ * (`claudeHookShell`) — the "Git Bash removed after the emit" gap, which otherwise
  * reports nothing: hooks signal through stdout and Claude treats a parse error as non-blocking.
  *
  * Bash form with Git Bash now gone is a PROBLEM: `context`/`learn` fail open under PowerShell
- * (no `onFailure`, so a launch failure there is still non-blocking) and, since Task 1, the two
- * gates fail CLOSED instead (`onFailure: "block"` blocks every Bash/PowerShell/Write/Edit/
+ * (no `onFailure`, so a launch failure there is still non-blocking) while the two gates,
+ * being gates, fail CLOSED instead (`onFailure: "block"` blocks every Bash/PowerShell/Write/Edit/
  * NotebookEdit call until `rebuild-all` re-emits the PowerShell form) — worse for the user
  * either way, so the message below still reports it as drift needing a rebuild; it does not
  * distinguish the two outcomes. PowerShell form with Git Bash now present is a `[note]`: the hooks work,
@@ -763,13 +760,52 @@ export function hookShellProblems(targets = installTargets(), platform = process
     out.push(was === 'bash'
       ? `[hooks] ${cfg}: hooks were emitted for Git Bash, which is no longer found, so Claude `
         + 'Code runs them under PowerShell where context/learn fail open (no effect) and '
-        + 'git-gate/rule-gate now BLOCK every call instead of gating it - run: geneseed rebuild-all'
+        + 'git-gate/rule-gate now BLOCK every call instead of gating it - run: geneseed rebuild-all, '
+        + 'then confirm with: geneseed doctor --probe'
       : `[note] ${cfg}: hooks were emitted for PowerShell, but Git Bash is now found - they work, `
         + 'and pay PowerShell startup on every call; geneseed rebuild-all switches them back');
   }
   return out;
 }
 
+/**
+ * Every active Claude-STYLE install (`CLAUDE_STYLE`: claude, bob, openclaude — the hosts that
+ * share this one machine-wide shim) whose LIVE, recorded hooks still name `shimPath` by exact
+ * string, keyed by its own config dir.
+ *
+ * Split out of `shimProblems` (`js/inspect/checks-repo.mjs`) for the case `shimDeadPaths`
+ * cannot see: that function reads paths back OUT of the shim body, so it has nothing to read once the shim file is gone
+ * outright (deleted, not moved-and-regenerated) — a plain `isFile` check upstream then calls
+ * that clean, the same as a source checkout that never emitted. `liveRecordedHooks` is already
+ * "the manifest claims it AND the settings file still runs it" (`js/hosts/hosts.mjs`), so a
+ * disabled or never-wired install cannot appear here — only installs for which the missing
+ * shim is a live, standing failure. It also keeps only handlers whose `command` is a string,
+ * so the match below needs no type guard of its own.
+ *
+ * MATCHES THE EXACT PATH, not merely a command that mentions the shim's filename
+ * (`geneseed-hook`): the shim path is baked per `GENESEED_HOME`, so a machine with more than
+ * one Geneseed home (a relocated one, or a sandboxed test run beside a real install) must not
+ * let an install naming a DIFFERENT, perfectly healthy shim answer for this one.
+ *
+ * LIVES HERE, beside the `claudeCfg` and `installTargets` it is built on, because neither
+ * reader owns the install walk: doctor's `shimProblems`, and `status`'s `gateSummary`
+ * (`js/inspect/status.mjs`), which folds the same answer into its `dead` field — the one
+ * `statusLines` renders as a `DEAD` gates row. Two readers of one fact, not two copies.
+ *
+ * `targets` is a parameter, the same convention `hookShellProblems` uses, so a test can hand
+ * it a sandboxed `[host, scope, root]` triple instead of walking this machine's real config
+ * dirs and registry — the live default every production caller takes.
+ */
+export function installsReferencingShim(shimPath = hookShimPath(), targets = installTargets()) {
+  const out = [];
+  for (const [host, scope, root] of targets) {
+    if (!CLAUDE_STYLE.includes(host)) continue;
+    const cfg = claudeCfg(root, scope, host);
+    if (liveRecordedHooks(cfg).some(([, h]) => h.command.includes(shimPath))) out.push(cfg);
+  }
+  return out;
+}
+
 // ---- what this machine installed (`_harness_setup._installed_defaults`) --------------------
 
 /**

package/js/hosts/native.mjs

@@ -34,6 +34,11 @@ import { jsonDumps, parseJson, formatValue, formatRepr, isTruthy, isDict } from
 import { relPosix } from '../lib/text.mjs';
 import { aliasesOf } from '../build/source.mjs';
 import { claimLeaf, ownedState } from './owned.mjs';
+// `lstripNewlines` on spec bodies is a no-op on every input the generator produces today
+// (measured: no file under `src/` and no rendered spec in any theme begins with a newline), so
+// mutating it away leaves the parity gate green — correctly, there is no reachable behaviour to
+// detect. Kept because a spec author adding a leading blank line is one commit from needing it.
+import { lstripNewlines } from './settings.mjs';
 
 /** What a folder skill writes where it needs its own directory — see `writeNativeLayer`. */
 const SKILL_DIR_PLACEHOLDER = '<this-skill-directory>';
@@ -704,16 +709,3 @@ export function writeNativeLayer(items, agentsDir, skillsDir, overrides = null,
   }
   return { nAgents, nSkills, written, userOnlySkills };
 }
-
-/**
- * `str.lstrip("\n")` — only newlines, not all whitespace.
- *
- * Currently a no-op on every input the generator produces: measured, no file under `src/`
- * and no rendered spec in any of the 14 themes begins with a newline. Mutating it away
- * leaves the parity gate green, and that is correct rather than a hole — there is no
- * reachable behaviour to detect. Kept because it is what the Python does, and a spec
- * author adding a leading blank line is one commit away from making it matter.
- */
-function lstripNewlines(text) {
-  return text.replace(/^\n+/, '');
-}

package/js/hosts/opencode.mjs

@@ -28,6 +28,7 @@ import { jsonDumps, jsonDumpsIndent, parseJson } from '../lib/json.mjs';
 import { comparePaths } from '../lib/paths.mjs';
 import { sourceReleaseVersion } from '../build/version.mjs';
 import { aliasesOf } from '../build/source.mjs';
+import { lstripNewlines } from './settings.mjs';
 import {
   firstBlockquote, isUserInvokedOnly, skillDescription, stripSkillBodyLinks, pointSideFiles,
   pushOverrideLines,
@@ -295,7 +296,7 @@ export function writePrimaryAgent(cfg, agentsDir, overrides, claim = (_dest) =>
       || !statSync(cfg.primaryAgentSrc).isFile()) {
     return null;
   }
-  const body = readText(cfg.primaryAgentSrc).replace(/^\n+/, '');
+  const body = lstripNewlines(readText(cfg.primaryAgentSrc));
   const desc = 'Primary orchestrator — works by the harness Rules and delegates to the '
     + 'capability subagents.';
   const fm = [`description: ${jsonDumps(desc)}`, 'mode: primary', 'color: primary'];
@@ -309,19 +310,43 @@ export function writePrimaryAgent(cfg, agentsDir, overrides, claim = (_dest) =>
   return dest;
 }
 
-/** `_build_emit._write_command_layer` — the opt-in /slash commands. */
-export function writeCommandLayer(cfg, items, commandDir, claim = (_dest) => true,
-  skillDirOf = (n) => path.join(path.dirname(commandDir), 'skills', n).split(path.sep).join('/')) {
-  if (!truthyEnv('GENESEED_COMMANDS')) return [];
-  const byName = new Map();
+/**
+ * The top-level skills of `items` (`src/skills/<stem>.md`, no `_` partials) as ordered
+ * `[stem, text]` pairs — the one parse both command writers below share.
+ */
+function topLevelSkills(cfg, items) {
+  /** @type {[string, string][]} */
+  const found = [];
   for (const { text, src } of items) {
     if (text === null) continue;
     const sp = path.relative(cfg.src, src).split(path.sep);
     if (sp.length === 2 && sp[0] === 'skills' && sp[1].endsWith('.md')
         && !sp[1].startsWith('_')) {
-      byName.set(sp[1].slice(0, -3), text);
+      found.push([sp[1].slice(0, -3), text]);
     }
   }
+  return found;
+}
+
+/** Both command writers' default `skillDirOf`: the skill's own directory beside `commandDir`. */
+const siblingSkillDir = (commandDir) => (n) =>
+  path.join(path.dirname(commandDir), 'skills', n).split(path.sep).join('/');
+
+/** A command has no base directory, so a side-file pointer names the skill's own. */
+function commandBody(text, stem, skillDir) {
+  return stripSkillBodyLinks(pointSideFiles(lstripNewlines(text), stem, skillDir));
+}
+
+function writeCommandFile(dest, desc, body) {
+  mkdirSync(path.dirname(dest), { recursive: true });
+  writeText(dest, `---\ndescription: ${jsonDumps(desc)}\n---\n\n${body}`);
+}
+
+/** `_build_emit._write_command_layer` — the opt-in /slash commands. */
+export function writeCommandLayer(cfg, items, commandDir, claim = (_dest) => true,
+  skillDirOf = siblingSkillDir(commandDir)) {
+  if (!truthyEnv('GENESEED_COMMANDS')) return [];
+  const byName = new Map(topLevelSkills(cfg, items));
   const written = [];
   for (const [name, skill] of Object.entries(COMMAND_SET)) {
     // A command runs a skill; `--exclude-skills` took that skill out, so the command goes too.
@@ -333,10 +358,7 @@ export function writeCommandLayer(cfg, items, commandDir, claim = (_dest) => tru
     const dest = path.join(commandDir, `${name}.md`);
     if (!claim(dest)) continue;
     const desc = firstBlockquote(text);
-    // A command has no base directory, so a side-file pointer names the skill's own.
-    const body = stripSkillBodyLinks(pointSideFiles(text.replace(/^\n+/, ''), skill, skillDirOf(skill)));
-    mkdirSync(path.dirname(dest), { recursive: true });
-    writeText(dest, `---\ndescription: ${jsonDumps(desc)}\n---\n\n${body}`);
+    writeCommandFile(dest, desc, commandBody(text, skill, skillDirOf(skill)));
     written.push(dest);
   }
   return written;
@@ -358,22 +380,15 @@ export function writeCommandLayer(cfg, items, commandDir, claim = (_dest) => tru
  * (Task 4) — it keeps its SKILL.md and does not need a second, command-shaped copy.
  */
 export function writeAliasCommands(cfg, items, commandDir, claim = (_dest) => true,
-  skillDirOf = (n) => path.join(path.dirname(commandDir), 'skills', n).split(path.sep).join('/'),
-  alsoUserOnly = false) {
+  skillDirOf = siblingSkillDir(commandDir), alsoUserOnly = false) {
   const written = [];
-  for (const { text, src } of items) {
-    if (text === null) continue;
-    const sp = path.relative(cfg.src, src).split(path.sep);
-    if (sp.length !== 2 || sp[0] !== 'skills' || !sp[1].endsWith('.md') || sp[1].startsWith('_')) continue;
-    const stem = sp[1].slice(0, -3);
-    const body = stripSkillBodyLinks(pointSideFiles(text.replace(/^\n+/, ''), stem, skillDirOf(stem)));
+  for (const [stem, text] of topLevelSkills(cfg, items)) {
+    const body = commandBody(text, stem, skillDirOf(stem));
     const names = alsoUserOnly && isUserInvokedOnly(text) ? [...aliasesOf(text), stem] : aliasesOf(text);
     for (const name of names) {
       const dest = path.join(commandDir, `${name}.md`);
       if (!claim(dest)) continue;
-      mkdirSync(path.dirname(dest), { recursive: true });
-      const desc = name === stem ? skillDescription(text) : `Alias of ${stem}.`;
-      writeText(dest, `---\ndescription: ${jsonDumps(desc)}\n---\n\n${body}`);
+      writeCommandFile(dest, name === stem ? skillDescription(text) : `Alias of ${stem}.`, body);
       written.push(dest);
     }
   }

package/js/hosts/owned.mjs

@@ -144,11 +144,25 @@ export function hashesOf(doc) {
 }
 
 /**
- * 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.
+ * An OpenCode manifest's `skill_denies` — the `permission.skill` denies Geneseed itself added
+ * (`opencodeLayer` records them; a deny the user wrote, even on a Geneseed skill, is never in
+ * it) — or `[]` when the manifest, or the key, is absent or malformed, which sweeps nothing.
+ * Unlike the Law IV `permission.bash` gates (permanent, never taken back — see
+ * `reconcileOpencodePermission`), a skill-visibility deny is reversible: once uninstalled there
+ * is no skill left to hide, and the name is the user's to reuse. One home because rebuild's
+ * deny sweep and uninstall must agree on what Geneseed owns.
+ */
+export function recordedDenies(doc) {
+  const d = doc && doc.skill_denies;
+  return Array.isArray(d) ? d.filter((n) => typeof n === 'string') : [];
+}
+
+/**
+ * Where one owned file stands against its recorded hash — the table rebuild, prune and
+ * uninstall branch on so none of them clobbers a user's edit to a Geneseed-owned file.
+ * `'unknown'` is deliberately distinct from `'unmodified'`: a manifest written before hashes
+ * were recorded has no entry for this rel, and must not be read as "proven untouched" — a
+ * manifest without `hashes` keeps the pre-hash behaviour exactly.
  */
 export function ownedState(root, rel, hashes) {
   if (!Object.hasOwn(hashes, rel)) return 'unknown';