geneseed 3.1.3 → 3.3.0

package/js/hosts/hooks.mjs

@@ -1,9 +1,21 @@
 /**
- * The four HOOK verbs — `context`, `git-gate`, `rule-gate`, `learn` — in Node.
+ * The five HOOK verbs — `context`, `git-gate`, `rule-gate`, `tool-gate`, `learn` — in Node.
  *
  * These are the commands the emitted `settings.json` actually invokes on a user's machine,
- * every session: a SessionStart injector, two PreToolUse gates, and a Stop/SubagentStop
- * distiller. Since P5b they are also what the emitted hooks name: `bin/build-driver.mjs` bakes
+ * every session: a SessionStart injector, two PreToolUse gates (and `tool-gate`, the two
+ * fused for a host that runs ONE command per event), and a Stop/SubagentStop/PreCompact
+ * distiller.
+ *
+ * ONE VERB, TWO DIALECTS. `--host` names the host that will read the verdict. Claude Code
+ * (the default) reads `hookSpecificOutput.permissionDecision: "ask"` and shows the user a
+ * prompt. GitHub Copilot's `toolCall` hook has no ask tier — its stdout contract is
+ * `{"block": true|false}` — so on `--host copilot` the two Laws that admit no judgement call
+ * (I, IV) BLOCK and everything that was an ask (process 1, process 5, a gate error) is a
+ * warning on stderr, which Copilot logs. The same stance the OpenCode guard plugin takes
+ * where its `tool.execute.before` can only allow or throw. `--host bob` is Bob's own
+ * protocol: PreToolUse ignores stdout and refuses only on EXIT CODE 2, so the two Laws
+ * exit 2 with the reason on stderr and the rest is a stderr line with exit 0; SessionStart
+ * context is plain stdout, as on Claude. Since P5b they are also what the emitted hooks name: `bin/build-driver.mjs` bakes
  * `<node> <checkout>/bin/geneseed-hook.mjs` into the machine-wide shim, so an install this
  * driver emits has no Python in its hook path at all — which is what let the interpreter
  * discovery and its exit-4 refusal be deleted rather than merely bypassed.
@@ -31,11 +43,11 @@
  * and every file left behind. Absolute rather than compared is what let it survive the deletion
  * of the implementation it was once compared against.
  */
-import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, realpathSync }
+import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, realpathSync,
+  appendFileSync, writeFileSync }
   from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
 import { readText, writeText, printOut, printErr, withDiscardableStderr } from '../lib/fs.mjs';
 import { jsonDumpsCompact } from '../lib/json.mjs';
 import { normcase, comparePaths, toPlatformPath } from '../lib/paths.mjs';
@@ -44,9 +56,9 @@ import { NO_WINDOW } from '../lib/proc.mjs';
 // module to find it: the CLI is under a hard transitive `child_process` ban and `learn`
 // spawns. So the resolver has one owner in `js/hosts/hosts.mjs` rather than a second copy — and
 // with it went this file's private `opencodeConfigDir`, whose only caller it was.
-import { resolveMemoryDir, expanduser } from './hosts.mjs';
+import { resolveMemoryDir, expanduser, sovereignBypass } from './hosts.mjs';
 
-const ROOT = path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))));
+const ROOT = path.resolve(import.meta.dirname, '../..');
 
 // ---- Python path and text primitives -------------------------------------------------
 // Small, and each one is here because a JS-idiomatic equivalent differs observably.
@@ -73,10 +85,12 @@ const ROOT = path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.ur
 // an adjudicated product decision (`TheTildeUserFormIsADeliberateDivergence`) that the hook
 // was quietly exempt from because it had a private copy. It now imports the owner. The
 // refusal throws, so `sovereignBypass` and `cmdContext` below contain it per entry / per
-// call: a hook that CRASHES reports success, because these gates exit 0 and signal on
-// stdout, so "the gate blew up" and "the gate found nothing" are the same observation to
-// Claude. `resolvePath` just below is the THIRD copy of a primitive `js/hosts/hosts.mjs` also
-// exports, and is the next item in this series.
+// call. For the two GATES that containment is not enough, and `guardGate` below is the
+// contract: these verbs exit 0 and signal on stdout, so "the gate blew up" and "the gate
+// found nothing" would be the SAME observation to Claude — a crash would be a silent allow.
+// A gate that cannot evaluate a call therefore asks, and says why. `resolvePath` just below
+// is the THIRD copy of a primitive `js/hosts/hosts.mjs` also exports, and is the next item
+// in this series.
 
 /**
  * `Path(p).resolve()` — absolute, symlinks followed, and the filesystem's OWN casing.
@@ -101,6 +115,7 @@ function resolvePath(p) {
   }
 }
 
+// NOT imported from `js/lib/fs.mjs` (the owner everywhere else) — hot path, no new import cost.
 const isFile = (p) => { try { return statSync(p).isFile(); } catch { return false; } };
 const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
 
@@ -229,7 +244,6 @@ const EXCLUDE_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'vendor',
 
 const CLAUDE_MARKERS = ['.claude', '.bob'];
 const GENESEED_MANIFEST = '.geneseed-manifest.json';
-const EXCLUDES_FILE = 'excludes.json';
 
 /**
  * `_global_hook_standing_down` — project-bypasses-global.
@@ -252,52 +266,10 @@ export function globalHookStandingDown(hookRoot, cwd) {
   return false;
 }
 
-/**
- * `sovereign_bypass` — the user's own excludes.json, read on EVERY hook call so an edit
- * takes effect without a re-emit. Every failure mode degrades to false: a hook must never
- * fail or block on a file the user owns.
- */
-export function sovereignBypass(root) {
-  if (!root) return false;
-  let entries;
-  try {
-    const data = JSON.parse(readText(path.join(root, EXCLUDES_FILE)));
-    entries = Array.isArray(data && data.excludes) ? data.excludes : [];
-  } catch {
-    return false;
-  }
-  let cwd;
-  try {
-    cwd = normcase(resolvePath(process.cwd()));
-  } catch {
-    return false;
-  }
-  for (const entry of entries) {
-    const raw = (entry && typeof entry === 'object' ? entry.path : entry) || '';
-    if (typeof raw !== 'string' || !raw.trim()) continue;
-    let base;
-    try {
-      // `.rstrip("\\/")` AFTER normcase, exactly as the Python orders it, so the separator
-      // test below cannot be fooled by a trailing slash in the user's file.
-      //
-      // `withDiscardableStderr` because `expanduser` writes its refusal at the RAISE SITE
-      // and this caller catches: the reference prints nothing here, so replaying the
-      // message would be a stderr divergence on every hook call for one bad entry.
-      base = withDiscardableStderr(
-        () => normcase(toPlatformPath(expanduser(raw.trim()))).replace(/[\\/]+$/, ''));
-    } catch {
-      // PER ENTRY, and the loop continues. One unusable line in a file the USER hand-edits
-      // must not decide the whole function — `expanduser` refuses a `~user` form, and the
-      // reference's `Path.expanduser()` raises RuntimeError on the same input on POSIX.
-      // Skipping errs toward the gate staying ACTIVE, which is the safe direction: this
-      // feeds `git-gate`/`rule-gate`, which exit 0 and signal on stdout, so a crash here
-      // would read as a clean pass while gating nothing.
-      continue;
-    }
-    if (cwd === base || cwd.startsWith(base + path.sep)) return true;
-  }
-  return false;
-}
+// `sovereignBypass` moved to `./hosts.mjs` so `status` can read it without importing this
+// module's `child_process` binding; re-exported because the tests and the excludes writer's
+// docblock name it here.
+export { sovereignBypass };
 
 /** `_disp` — relative to the repo root when it sits under it, else verbatim. */
 function disp(pathStr, root) {
@@ -469,6 +441,7 @@ export function resolveContextSets(root) {
 }
 
 export function cmdContext(args) {
+  setHost(args);
   // Discovery runs against the project root the hook was launched from — Claude runs
   // SessionStart hooks with cwd = repo root — not the harness package dir.
   // The only two `resolvePath` calls in this file whose argument can be a `~user` path the
@@ -523,7 +496,12 @@ export function cmdContext(args) {
     lines.push('');
   }
 
-  out(`${lines.join('\n')}\n`);
+  // Claude Code takes a SessionStart hook's plain stdout as context. Copilot's `sessionStart`
+  // wants a JSON document and reads `additionalContext` out of it; plain text there would be
+  // parsed as nothing and silently dropped.
+  // Bob reads a SessionStart hook's stdout as context exactly as Claude does.
+  const text = `${lines.join('\n')}\n`;
+  out(HOST === 'copilot' ? `${jsonDumpsCompact({ additionalContext: text })}\n` : text);
   return 0;
 }
 
@@ -537,6 +515,15 @@ export function cmdContext(args) {
 // one line and a `commit` on the next are two commands, not one.
 const GIT_GATE_RE = /\bgit\b[^\n]*\b(?:commit|push)\b/;
 
+// Law IV's boundary half: the git verbs that rewrite or discard history. Law IX (now rigor 5)
+// says a rule in a prompt is a request and a rule at a boundary is a constraint; before this
+// regex the harness enforced one doctrine rule and no law. `checkout --` is listed because it
+// reverts to the INDEX and eats unstaged work; `checkout <branch>` is not. `clean -f` matches
+// any flag cluster carrying `f` (`-fd`, `-xf`) and never `-n`. `push --force*` trips this gate
+// rather than process 5's so the stronger reason is the one the user reads.
+const DESTRUCTIVE_GIT_RE =
+  /\bgit\b[^\n]*\b(?:reset\s+--hard|clean\s+-[a-zA-Z]*f|branch\s+-D|checkout\s+--\s|push\s+[^\n]*--force)/;
+
 /** The `permissionDecision: "ask"` document, in Python's compact `json.dumps` spelling. */
 function askDecision(reason) {
   return `${jsonDumpsCompact({
@@ -548,21 +535,162 @@ function askDecision(reason) {
   })}\n`;
 }
 
-export function cmdGitGate(args) {
-  if (sovereignBypass(args.root)) return 0;
-  let command;
+/**
+ * The host reading this process's verdict — `--host` on the emitted command, `claude` when
+ * absent. Module state rather than a parameter because a hook process answers exactly one
+ * call: set once at the verb's entry (`guardGate`, `cmdContext`), read where the output
+ * dialect is chosen.
+ */
+let HOST = 'claude';
+const setHost = (args) => { HOST = (args && args.host) || 'claude'; };
+
+/** Copilot's `toolCall` verdict: `{"block": true}` plus the reason it displays. */
+function blockDecision(reason) {
+  return `${jsonDumpsCompact({ block: true, reason })}\n`;
+}
+
+/**
+ * Bob's PreToolUse protocol: stdout is ignored and EXIT CODE 2 is the one refusal. The
+ * single exception to "every gate exits 0" in this file, confined to `--host bob` — on
+ * Claude Code a non-zero exit is a broken hook, on Bob it is the verdict.
+ */
+const BOB_DENY_EXIT = 2;
+
+/**
+ * On a host with no ask tier, which rules are worth a hard block. Laws I and IV: a
+ * credential in a tracked file and a history-discarding git act are wrong in every context,
+ * so refusing them costs nothing. Process 1 and process 5 are the USER's calls — a hard
+ * block would make Copilot unable to commit at all — so they become a warning the host
+ * logs. `gate-error` is a warning too: a crashed gate that blocked every tool call would be
+ * a lockout, not a safeguard, and there is no prompt through which the user could clear it.
+ */
+const BLOCK_RULES = new Set(['law-1', 'law-4']);
+
+/** Where the gate ledger lives inside an install: the notebook is the agent's own, gitignored space. */
+export const GATE_LEDGER = path.join('notebook', 'gates.jsonl');
+
+/**
+ * THE GATE LEDGER — one JSON line per ask, nothing per defer.
+ *
+ * The gates are the only mechanical enforcement the harness has, and until this line
+ * nothing recorded whether they ever fired: no way to tell whether Law I has caught a secret
+ * this year, or whether the process 5 prompt is signal or noise. `status` counts these by
+ * rule. It records the RULE, never the command or the content that tripped it — a ledger
+ * that stored the string Law I caught would itself be a place a secret lands. And it records
+ * only `asked`: the host never tells a hook how the user answered, so a `decided` column
+ * would be a claim the hook cannot make. Written only on the ask path, which is the rare
+ * one; the defer path — every other tool call — pays nothing. A ledger that cannot be
+ * written must never change the decision, hence the swallow.
+ *
+ * Capped at the newest MAX_LEDGER_LINES, like the agent lessons and the notes beside it: an
+ * install lives for months and `status` only ever counts, so the oldest asks carry no
+ * information a trimmed file loses. The re-read happens on the ask path only.
+ */
+const MAX_LEDGER_LINES = 1000;
+function ledger(root, verb, rule) {
+  if (!root) return;
   try {
-    const payload = JSON.parse(readStdin() || '{}');
-    command = ((payload && payload.tool_input) || {}).command;
-  } catch {
+    const file = path.join(root, GATE_LEDGER);
+    appendFileSync(file, `${JSON.stringify({
+      ts: new Date().toISOString(), verb, rule, cwd: process.cwd(),
+    })}\n`);
+    const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+    if (lines.length > MAX_LEDGER_LINES) {
+      writeFileSync(file, `${lines.slice(-MAX_LEDGER_LINES).join('\n')}\n`);
+    }
+  } catch { /* see above: the ledger never decides */ }
+}
+
+/**
+ * Ask, and record that we asked. Every ask site goes through here so none can skip the
+ * ledger. On `--host copilot` the ask becomes a block or a warning (see `BLOCK_RULES`); the
+ * ledger records the block, never the warning — a warning asked nothing of anyone.
+ */
+function ask(args, verb, rule, reason) {
+  if (HOST === 'copilot' || HOST === 'bob') {
+    if (!BLOCK_RULES.has(rule)) {
+      // Neither host has an ask tier; a stderr line is the nudge, and the call goes through.
+      err(`[geneseed] ${reason}\n`);
+      return 0;
+    }
+    ledger(args && args.root, verb, rule);
+    if (HOST === 'bob') {
+      // stdout is not read on Bob's PreToolUse; the reason goes where Bob's hook log looks.
+      err(`[geneseed] BLOCKED: ${reason}\n`);
+      return BOB_DENY_EXIT;
+    }
+    out(blockDecision(reason));
     return 0;
   }
-  if (typeof command !== 'string' || !GIT_GATE_RE.test(command)) return 0;
-  out(askDecision('Geneseed Doctrine process 5 \u2014 every git commit/push needs explicit '
-    + 'approval'));
+  ledger(args && args.root, verb, rule);
+  out(askDecision(reason));
   return 0;
 }
 
+/**
+ * FAIL CLOSED. Wraps a gate verb so that any throw — a payload that is not JSON, a path
+ * primitive refusing a form, a bug — becomes an `ask` carrying the error, never a silent
+ * allow. The host reads exit 0 + empty stdout as "the gate deferred", which is exactly what a
+ * crashed gate would otherwise look like. A well-formed ABSENCE (empty stdin, `{}`, a null
+ * `tool_input`) is still a defer: there is nothing to evaluate, and asking on every
+ * hand-run invocation would teach the user to allow-list the gate.
+ */
+export function guardGate(fn, verb = 'gate') {
+  return (args) => {
+    setHost(args);
+    try {
+      return fn(args);
+    } catch (e) {
+      const why = e && e.message ? e.message : String(e);
+      return ask(args, verb, 'gate-error', `Geneseed gate error — ${why}. The gate could `
+        + 'not evaluate this call, so it does not defer.');
+    }
+  };
+}
+
+/**
+ * The hook payload on stdin, or null for a well-formed absence. Not-JSON THROWS.
+ *
+ * Copilot spells the same payload in camelCase — `toolName`/`toolInput` where Claude sends
+ * `tool_name`/`tool_input` — and fires `toolCall` both before AND after the tool runs
+ * (`phase`). The field names are folded to Claude's so every gate reads one shape; the
+ * `after` phase is a well-formed absence, since there is nothing left to gate.
+ */
+function readPayload() {
+  const raw = readStdin();
+  if (!raw.trim()) return null;
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    throw new Error('the hook payload on stdin is not JSON');
+  }
+  if (!payload || typeof payload !== 'object') return null;
+  if (payload.phase === 'after') return null;
+  if (payload.tool_input === undefined && payload.toolInput !== undefined) {
+    payload.tool_input = payload.toolInput;
+  }
+  return payload;
+}
+
+function gitGate(args) {
+  if (sovereignBypass(args.root)) return 0;
+  return gitDecide(args, readPayload());
+}
+
+function gitDecide(args, payload) {
+  const command = ((payload && payload.tool_input) || {}).command;
+  if (typeof command !== 'string') return 0;
+  if (DESTRUCTIVE_GIT_RE.test(command)) {
+    return ask(args, 'git-gate', 'law-4', 'Geneseed Law IV \u2014 a history-rewriting or '
+      + 'discarding git act needs confirmation bound to this specific command');
+  }
+  if (!GIT_GATE_RE.test(command)) return 0;
+  return ask(args, 'git-gate', 'process-5', 'Geneseed Doctrine process 5 \u2014 every git '
+    + 'commit/push needs explicit approval');
+}
+export const cmdGitGate = guardGate(gitGate, 'git-gate');
+
 // ======================================================================================
 // rule-gate — Doctrine process 1's tool-boundary backstop
 // ======================================================================================
@@ -575,7 +703,7 @@ export function cmdGitGate(args) {
  * Geneseed's own coinage and match anywhere; any other markdown matches only inside THIS
  * install's `<root>/memory/`.
  */
-export function ruleGateTarget(p, root) {
+function ruleGateTarget(p, root) {
   if (typeof p !== 'string') return null;
   // Split on BOTH separators rather than taking a basename: a payload carrying a Windows
   // path reaches a POSIX host with its backslashes intact, and `path.basename` there
@@ -595,23 +723,57 @@ export function ruleGateTarget(p, root) {
   }
 }
 
-export function cmdRuleGate(args) {
+// Law I's boundary half. High-precision vendor prefixes only — a generic "looks like entropy"
+// scan would fire on every hash and lockfile, and a gate that cries wolf gets allow-listed.
+// `.env*` is exempt because Law I names it as the place a secret may live.
+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(\.[^\\/]*)?$/;
+
+function ruleGate(args) {
   if (sovereignBypass(args.root)) return 0;
-  let p;
-  try {
-    const payload = JSON.parse(readStdin() || '{}');
-    const ti = (payload && payload.tool_input) || {};
-    p = ti.file_path || ti.path || '';
-  } catch {
-    return 0;
-  }
+  return ruleDecide(args, readPayload());
+}
+
+function ruleDecide(args, payload) {
+  const ti = (payload && payload.tool_input) || {};
+  const p = ti.file_path || ti.path || '';
   if (typeof p !== 'string' || !p) return 0;
+  // Write carries `content`, Edit carries `new_string`; either can plant a credential.
+  const body = typeof ti.content === 'string' ? ti.content
+    : typeof ti.new_string === 'string' ? ti.new_string : '';
+  if (body && !DOTENV_RE.test(p) && SECRET_RE.test(body)) {
+    return ask(args, 'rule-gate', 'law-1', `Geneseed Law I — ${p} would carry a `
+      + 'credential-shaped string. Secrets live in .env or a secret manager, never in a '
+      + 'tracked file.');
+  }
   const target = ruleGateTarget(p, args.root);
   if (!target) return 0;
-  out(askDecision(`Geneseed Doctrine process 1 \u2014 writing to ${target}: a standing rule, or a `
-    + "fact to remember? That choice is the user's. Run the rule skill first."));
-  return 0;
+  return ask(args, 'rule-gate', 'process-1', `Geneseed Doctrine process 1 \u2014 writing to `
+    + `${target}: a standing rule, or a fact to remember? That choice is the user's. Run the `
+    + 'rule skill first.');
+}
+export const cmdRuleGate = guardGate(ruleGate, 'rule-gate');
+
+// ======================================================================================
+// tool-gate — both gates behind one command
+// ======================================================================================
+
+/**
+ * Copilot's settings carry ONE command per hook event, not a list of matcher groups, so
+ * its `toolCall` hook cannot name `git-gate` for Bash and `rule-gate` for Write the way
+ * Claude's `PreToolUse` does. This verb is the two fused, dispatched on the payload rather
+ * than on a matcher: a `command` field is a shell call and gets the git checks, a path
+ * field is a write and gets the rule checks. Nothing here decides anything the two named
+ * gates do not — it only removes the need for a matcher the host does not have.
+ */
+function toolGate(args) {
+  if (sovereignBypass(args.root)) return 0;
+  const payload = readPayload();
+  const ti = (payload && payload.tool_input) || {};
+  return typeof ti.command === 'string' ? gitDecide(args, payload) : ruleDecide(args, payload);
 }
+export const cmdToolGate = guardGate(toolGate, 'tool-gate');
 
 // ======================================================================================
 // learn — distil notes/transcripts into deduped memory entries

package/js/hosts/hosts.mjs

@@ -14,17 +14,69 @@
  * changed resolver rather than catch it — but `tests/unit/node_driver.test.mjs`'s relocation
  * table, which asserts each host's global target absolutely.
  */
-import { realpathSync, statSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { printErr, withDiscardableStderr } from '../lib/fs.mjs';
-import { toPlatformPath } from '../lib/paths.mjs';
-
-const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+import { printErr, withDiscardableStderr, isDir, readText } from '../lib/fs.mjs';
+import { toPlatformPath, normcase } from '../lib/paths.mjs';
 
 /** `_build_global.GLOBAL_MANIFEST` — the file whose presence means "a global install". */
 export const GLOBAL_MANIFEST = '.geneseed-manifest.json';
 
+/** The user's own per-install exclusion list; `js/build/stubs.mjs` seeds it, this file reads it. */
+export const EXCLUDES_FILE = 'excludes.json';
+
+/**
+ * `sovereign_bypass` — the user's own excludes.json, read on EVERY hook call so an edit
+ * takes effect without a re-emit. Every failure mode degrades to false: a hook must never
+ * fail or block on a file the user owns.
+ *
+ * LIVES HERE, NOT IN `hooks.mjs`, because two readers need it and only one of them may pay
+ * for the other: the hook (hot path, already imports this module) and `status` (the CLI,
+ * under the transitive `child_process` ban that `hooks.mjs`'s `learn` verb breaks). A
+ * second copy in `js/inspect/` was the alternative, and a copy is what let the `~user`
+ * refusal diverge between the two CLIs once already (see `hooks.mjs`'s header).
+ */
+export function sovereignBypass(root) {
+  if (!root) return false;
+  let entries;
+  try {
+    const data = JSON.parse(readText(path.join(root, EXCLUDES_FILE)));
+    entries = Array.isArray(data && data.excludes) ? data.excludes : [];
+  } catch {
+    return false;
+  }
+  let cwd;
+  try {
+    cwd = normcase(resolvePath(process.cwd()));
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    const raw = (entry && typeof entry === 'object' ? entry.path : entry) || '';
+    if (typeof raw !== 'string' || !raw.trim()) continue;
+    let base;
+    try {
+      // `.rstrip("\\/")` AFTER normcase, exactly as the Python orders it, so the separator
+      // test below cannot be fooled by a trailing slash in the user's file.
+      //
+      // `withDiscardableStderr` because `expanduser` writes its refusal at the RAISE SITE
+      // and this caller catches: the reference prints nothing here, so replaying the
+      // message would be a stderr divergence on every hook call for one bad entry.
+      base = withDiscardableStderr(
+        () => normcase(toPlatformPath(expanduser(raw.trim()))).replace(/[\\/]+$/, ''));
+    } catch {
+      // PER ENTRY, and the loop continues. One unusable line in a file the USER hand-edits
+      // must not decide the whole function — `expanduser` refuses a `~user` form, and the
+      // reference's `Path.expanduser()` raises RuntimeError on the same input on POSIX.
+      // Skipping errs toward the gate staying ACTIVE, which is the safe direction.
+      continue;
+    }
+    if (cwd === base || cwd.startsWith(base + path.sep)) return true;
+  }
+  return false;
+}
+
 /**
  * `_build_core.VERSION_MARKER`. Third caller, so it moves here — `js/build/version.mjs` and
  * `js/inspect/diff.mjs` each had a private const of their own and `js/maintain/uninstall.mjs` would have made

package/js/hosts/installs.mjs

@@ -32,19 +32,16 @@
  * web cells recorded it. Both candidates are gone (the argument is in the Python), and the
  * claim is now true rather than aspirational.
  */
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 
 import { CONFIG, PACK_ORDER, THEMES, discoverNames } from '../build/source.mjs';
 import { GLOBAL_MANIFEST, HOSTS, resolvePath } from './hosts.mjs';
 import { registryRoots } from '../inspect/registry.mjs';
-import { printErr, readText } from '../lib/fs.mjs';
+import { printErr, readText, isFile, isDir } from '../lib/fs.mjs';
 import { formatRepr } from '../lib/json.mjs';
 import { comparePaths } from '../lib/paths.mjs';
 
-const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
-const isFile = (p) => { try { return statSync(p).isFile(); } catch { return false; } };
-
 /**
  * `Path.read_text(encoding="utf-8")`, or null where Python raises OSError.
  *
@@ -150,6 +147,22 @@ function themeFromAgent(agentMd) {
 const CARRIERS = ['AGENT.md', 'CLAUDE.md', path.join('rules', 'geneseed.md'),
   'copilot-instructions.md', 'AGENTS.md'];
 
+/**
+ * The scan `themeOfDir`, `leadOfDir`, `doctrinesOfDir` and `excludedRulesOfDir` each wrote
+ * out: try each carrier in order, first answer wins. `probe(carrierPath)` returns
+ * `undefined` to mean "keep looking" and anything else — including `null` or `[]`, both
+ * legitimate stop values for the two register readers below — to mean "stop, this is the
+ * answer". `fallback` is what every caller's own trailing `return …;` supplied once the
+ * whole list was exhausted with no answer.
+ */
+function firstCarrier(d, probe, fallback = null) {
+  for (const carrier of CARRIERS) {
+    const result = probe(path.join(d, carrier));
+    if (result !== undefined) return result;
+  }
+  return fallback;
+}
+
 /** `_harness_setup._theme_of_dir` — the marker, else the sigil in one of five carriers. */
 export function themeOfDir(d) {
   const marker = path.join(d, '.geneseed-theme');
@@ -157,11 +170,7 @@ export function themeOfDir(d) {
     const name = (readMaybe(marker) ?? '').trim();
     if (name) return name;
   }
-  for (const carrier of CARRIERS) {
-    const found = themeFromAgent(path.join(d, carrier));
-    if (found) return found;
-  }
-  return null;
+  return firstCarrier(d, (carrierPath) => themeFromAgent(carrierPath) || undefined);
 }
 
 /** `_harness_setup.FOOTPRINTS`. */
@@ -209,14 +218,14 @@ export function capitalize(s) {
 }
 
 function leadOfDir(d, names) {
-  for (const carrier of CARRIERS) {
-    const text = readMaybe(path.join(d, carrier));
-    if (text === null) continue;
+  return firstCarrier(d, (carrierPath) => {
+    const text = readMaybe(carrierPath);
+    if (text === null) return undefined;
     for (const name of names) {
       if (text.includes(`**${capitalize(name)}**`)) return name;
     }
-  }
-  return null;
+    return undefined;
+  });
 }
 
 export const postureOfDir = (d) => leadOfDir(d, discoverNames('postures', 'peer'));
@@ -257,17 +266,16 @@ const ACTIVE_PACKS_RE = /^Active packs:[ \t]*(.+?)[ \t]*$/m;
  * exactly the empty field a fold leaves behind, which is what makes this catch it.
  */
 export function doctrinesOfDir(d) {
-  for (const carrier of CARRIERS) {
-    const text = readMaybe(path.join(d, carrier));
-    if (text === null) continue;
+  return firstCarrier(d, (carrierPath) => {
+    const text = readMaybe(carrierPath);
+    if (text === null) return undefined;
     const m = ACTIVE_PACKS_RE.exec(text);
-    if (!m) continue;
+    if (!m) return undefined;
     if (m[1] === 'none') return [];
     const named = m[1].split(',').map((s) => s.trim());
     if (!named.every((n) => PACK_ORDER.includes(n))) return null;
-    return PACK_ORDER.filter((p) => named.includes(p));
-  }
-  return null;
+    return PACK_ORDER.filter((pk) => named.includes(pk));
+  });
 }
 
 /**
@@ -314,11 +322,11 @@ const EXCLUDED_RULES_RE = /^Excluded rules:[ \t]*(.+?)[ \t]*$/m;
  * take away rules nobody named.
  */
 export function excludedRulesOfDir(d) {
-  for (const carrier of CARRIERS) {
-    const text = readMaybe(path.join(d, carrier));
-    if (text === null) continue;
+  return firstCarrier(d, (carrierPath) => {
+    const text = readMaybe(carrierPath);
+    if (text === null) return undefined;
     const m = EXCLUDED_RULES_RE.exec(text);
-    if (!m) continue;
+    if (!m) return undefined;
     if (m[1] === 'none') return [];
     const named = m[1].split(',').map((s) => s.trim());
     // `<pack> <n>` on the page, `<pack>.<n>` in the code — the same asymmetry the rendered
@@ -329,8 +337,7 @@ export function excludedRulesOfDir(d) {
         ? `${parts[0]}.${Number(parts[1])}` : null;
     });
     return ids.every(Boolean) ? [...new Set(ids)].sort() : [];
-  }
-  return [];
+  }, []);
 }
 
 // ---- what host a deployed dir belongs to (`_harness_mcp`) ---------------------------------

package/js/hosts/link.mjs

@@ -24,7 +24,7 @@
  * The second removes a working feature from every GIT-CHECKOUT user — for whom `link` is
  * the only thing that puts `geneseed` on PATH, because there is no package manager in that
  * story — in order to spare npm users a duplicate. It also spends a `web/dist` rebuild on a
- * deletion. So: they ship, they port, and `NOT_PORTED_ACTIONS` empties.
+ * deletion. So: they ship, and they port.
  *
  * The npm duplication is left as it is rather than papered over with a new "you already have
  * this" refusal: that would be a REDESIGN of the verb, the reference has no such arm, and a
@@ -86,7 +86,7 @@ import { toPlatformPath } from '../lib/paths.mjs';
 const IS_WIN = process.platform === 'win32';
 
 /** `_harness_lifecycle._win_bin_dir`. */
-export function winBinDir() {
+function winBinDir() {
   // `os.environ.get(...) or str(Path.home())` — an EMPTY LOCALAPPDATA falls back too,
   // which `??` would not do.
   const base = process.env.LOCALAPPDATA || os.homedir();

package/js/hosts/mcp.mjs

@@ -244,8 +244,10 @@ export function mcpConfigFor(host, scope, root) {
       : resolvePath(path.join(os.homedir(), '.claude.json'));
   }
   if (host === 'bob') {
+    // Nested at global scope, as Bob's hooks doc places the global file (and as the emit
+    // now writes it); the project file is flat.
     return scope === 'project' ? path.join(root, '.bob', 'settings.json')
-      : path.join(bobConfigDir(), 'settings.json');
+      : path.join(bobConfigDir(), 'settings', 'settings.json');
   }
   if (host === 'copilot') {
     // The Copilot CLI reads MCP servers from ~/.copilot/mcp-config.json only — no per-repo