geneseed 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -8,6 +8,36 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [4.2.0] — 2026-10-14
+
+Minor: the web console's Overview becomes a control panel over every installed harness, rebuild, prune and uninstall keep owned files you edited, and skill and subagent calls are counted.
+
+### Upgrade notes
+- Run `geneseed rebuild-all` once after updating to wire the usage counter and record the per-file hashes that edit detection reads. An install built before 4.2.0 has no hashes, so until it is rebuilt its owned files are treated as before.
+- Run `geneseed web restart` to load the new console.
+
+### Added
+- **The Overview as a control panel.** The default Overview lists every installed harness on the machine: whether it matches its source, hand edits, its always-on cost against the root-file ceiling, its build time, and Rebuild when it is behind or edited. Below that: what needs attention, then charts of always-on cost by part, which skills and agents fire over 30 days, and gate asks per rule. Hosts with nothing installed are not listed; installing stays on the Installs page. The four older views are still in the Appearance palette. New read endpoints: `GET /api/fleet` (each install with its own sync verdict and always-on cost), `GET /api/usage`, `GET /api/gates` and `GET /api/update`.
+- **Update check.** The console shows "*x.y.z* available" with an Update button only when npm has a release newer than the running source, and "update check unavailable" when the check failed. It asks `registry.npmjs.org` at most once a day (once an hour after a failure, with a 3-second timeout). `GENESEED_NO_UPDATE_CHECK` turns it off.
+- **Usage counting.** Every Skill or subagent call appends one `{day, kind, name}` line to the install's `notebook/usage.jsonl`. It records counts only, never the prompt, arguments or paths, and adds no process and no model tokens. It is on by default. `GENESEED_NO_USAGE` or a `.usage-off` file in the install turns it off. On Claude Code and OpenClaude it is a new `Skill|Agent|Task` hook group with no `onFailure: block`, so a counter can never stop a skill. On Bob, skill detection is best-effort. Lines older than 90 days are pruned.
+
+### Changed
+- **Rebuild, prune and uninstall keep owned files you edited.** The manifest now records a hash of every owned file. A rebuild leaves an owned file you edited in place and tells you to delete it if you want Geneseed's copy back, and a prune does not remove it. Uninstall leaves it too, completes around it, and names it; `geneseed uninstall --force` deletes it anyway. The console's Remove does the same and names the files it kept. The hash ignores CRLF vs LF, so a checkout with the other OS's line endings does not count as an edit.
+- **review**: when a spec exists and the diff spans more than a few files, the spec-fidelity pass runs in its own subagent, given only the diff and the spec. The smell baseline gains message chains and refused bequest.
+- **security-audit**: a finding stands only once it is traced from an attacker-controlled source to an unguarded sink through the real callers. Until then it stays a lead. The skill also names three shortcuts that produce false positives.
+- **wayfinder**: each decision ticket has a type (research, prototype, grilling or task) that says how it gets resolved. Research tickets run in parallel when the map is charted, a ticket worked with the user resolves only in that live exchange, and a sweep that finds nothing unclear produces no map.
+- **develop** names three test anti-patterns: implementation-coupled, tautological and horizontal slicing.
+- Nine registry entities move from experimental to approved: researcher, git-history, dependencies, security-audit, worktree, token-report, explain-changes, rule and skill-forge.
+- `doctor` checks that the host matrix and the enforcement table have exactly one column per host.
+
+### Fixed
+- A prune no longer follows a manifest path outside the install. A per-repo manifest entry such as `../victim.txt` could delete a file outside the install on re-emit. Prune now applies the same containment check as uninstall.
+- An emit never writes through a symlink planted at an owned path. This covers every path an emit writes, including `rules/geneseed.md`, `.gitignore`, the OpenCode global `AGENT.md` and the version marker.
+
+### Removed
+
+- The `herdr` skill. Orca now covers multi-pane and multi-agent work, so a skill limited to a herdr pane only added to the catalogue. It joins `RETIRED_SKILL_IDS`, so an install that excluded it still rebuilds. Skills: 47 → 46.
+
 ## [4.1.0] — 2026-10-13
 
 Minor: the planning, review, debugging and multi-agent skills take the lessons of Superpowers 7.0, and the host canary.

package/README.md

@@ -11,7 +11,7 @@
 [![Node >= 22.3](https://img.shields.io/badge/node-%3E%3D22.3-5fa04e)](package.json)
 [![zero dependencies](https://img.shields.io/badge/deps-zero-success)](package.json)
 [![Themes](https://img.shields.io/badge/themes-14-9cf)](themes/)
-[![Skills](https://img.shields.io/badge/skills-47-blueviolet)](src/skills/)
+[![Skills](https://img.shields.io/badge/skills-46-blueviolet)](src/skills/)
 [![Agents](https://img.shields.io/badge/agents-18-orange)](src/agents/)
 [![Laws and doctrines](https://img.shields.io/badge/laws-9%20%2B%2029%20doctrines-critical)](src/doctrines/)
 [![Plugins](https://img.shields.io/badge/plugins-7-teal)](adapters/opencode/plugins/)
@@ -179,7 +179,7 @@ The harness ships as a small set of layers, and the web console's rail is the sa
 | **🛡️ Rules** (`laws/`) | 9 universal laws — always in force, never toggleable: sealed-secrets, one-intent-one-act, verify-before-asserting, deletion-is-deliberate, surface-failures, data-not-orders, least-privilege, cure-the-cause, echo-the-intent. Each rule has a permanent id; its number is only its position, and the harness cites rules by name |
 | **📐 Doctrines** (`doctrines/`) | practice packs, chosen per install at build time: **craft** (how code is written), **rigor** (how work is proven), **ops** (how the machine is operated), **process** (how a task is run), **comms** (how answers are presented). A doctrine rule may tighten a Rule, never repeal one, and the user's own `user-rules.md` outranks it. Pick with `geneseed-build --doctrines craft,rigor` (or `none`), a single rule with `--exclude-rules "process 7"`, in the setup wizard, or through the switches on the console's Constitution page; all five pack files ship on disk either way, so a citation into a pack you left out still resolves |
 | **🤖 Agents** (18) | capability specialists: `reviewer`, `tester`, `architect`, `docs`, `security`, `explorer`, `researcher`, `developer` — plus a debate **council** the `council` skill convenes: `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`, `user-advocate`, `framer`, `empiricist`, `operator`, `historian` |
-| **🛠 Skills** (47) | repeatable workflows: brainstorm · plan · **codebase-design** · **wayfinder** · **develop** · **worktree** · debug · **prototype** · refactor · **ponytail** · **forge-mcp** · **bruno** · geneseed-code-review · **fresh-eyes** · **security-audit** · **dependencies** · **review-response** · commit · **ship** · **release** · **git-history** · document-project · **frontend-design** · **prose** · **ingest** · **research** · **teach** · **quiz** · **learn-mode** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **skill-forge** · **herdr** · **pipeline** · **loop** · **brick-forge** · **daydream** · **react-view-transitions** · **token-report** · **explain-changes** |
+| **🛠 Skills** (46) | repeatable workflows: brainstorm · plan · **codebase-design** · **wayfinder** · **develop** · **worktree** · debug · **prototype** · refactor · **ponytail** · **forge-mcp** · **bruno** · geneseed-code-review · **fresh-eyes** · **security-audit** · **dependencies** · **review-response** · commit · **ship** · **release** · **git-history** · document-project · **frontend-design** · **prose** · **ingest** · **research** · **teach** · **quiz** · **learn-mode** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **skill-forge** · **pipeline** · **loop** · **brick-forge** · **daydream** · **react-view-transitions** · **token-report** · **explain-changes** |
 | **🔌 Plugins** (OpenCode) | `geneseed-context` injects project docs *and your machine wiki* every session (and across compaction); `geneseed-learn` distils memory at session end; `geneseed-guard` enforces the safety Laws and protected wiki folders at the tool boundary; `geneseed-workflow` registers the `workflow` tool that runs saved orchestration scripts; `geneseed-notify` sends a native OS notification when a long run finishes; `geneseed-ponytail` holds a minimal-code mode (`/ponytail lite\|full\|ultra\|off`), opt-in, injecting the laziest-that-works ruleset every turn so it doesn't drift; `geneseed-activity` streams what each session is doing to the web console's Activity view |
 | **🧠 Memory** (`memory/`) | one-fact-per-file durable knowledge, indexed by `MEMORY.md` (git-ignored, personal) |
 | **📓 Notebook** (`notebook/`) | the agent's sovereign space — any medium (code, tools, data, notes), self-ruled via a seed-once charter, always git-ignored; only its `.gitignore` is build-asserted |

package/SHIPPED.md

@@ -20,7 +20,7 @@ historical references, not files distributed with the repo.
 > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
 > human-readable label only. The canonical identity of an installed harness is the
 > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
-> string. Current label: **4.1.0**.
+> string. Current label: **4.2.0**.
 
 ## Capabilities
 
@@ -29,7 +29,7 @@ Every row below is present in the tree today; "Spec" names the design record.
 | Capability | What it is | Spec |
 | --- | --- | --- |
 | **Themed generator** | One neutral `src/` → 14 themed bundles via `geneseed-build` (zero dependencies); structure stays theme-independent | [DESIGN.md](DESIGN.md) |
-| **Laws / Agents / Skills / Memory / Notebook** | 9 laws, 18 agents, 47 skills, the memory convention, and the agent's sovereign notebook | `2026-06-11-notebook-sovereign-space` · `2026-06-10-notebook-agent-own-space` |
+| **Laws / Agents / Skills / Memory / Notebook** | 9 laws, 18 agents, 46 skills, the memory convention, and the agent's sovereign notebook | `2026-06-11-notebook-sovereign-space` · `2026-06-10-notebook-agent-own-space` |
 | **Three-tier constitution** | The governance surface splits into an always-on **Ontology** (Telos, Evidence, Decisions, Conduct — the Pact absorbed into Telos), the nine always-on **Invariants**, and five toggleable **Doctrine** packs (craft, rigor, ops, process, comms) addressed `<pack> <n>`. Every rule carries a permanent id; its number is its position, computed at render time, and a citation renders as the rule's principle name. Packs are chosen at build time with `--doctrines` or the setup wizard; the whole catalogue ships on disk either way, so a citation into an inactive pack still resolves. Precedence, in order: Ontology + Invariants, then the user's `user-rules.md`, then the active Doctrines, then `PROFILE.md`. `doctor`'s `constitutionProblems` gates rule ids (declared, unique, never a retired one), the per-rule Principle column, every `{{LAW:<id>}}` / `{{DOCTRINE:<id>}}` citation in `src/`, and the rule that an always-on tier may never cite a toggleable one | `2026-08-19-three-tier-constitution-design` |
 | **`doctor`** | One check: unresolved tokens, dead/non-hermetic links, theme-key parity, authoring gates, rendered-bundle drift | `2026-06-07-theme-aware-doctor-diff` |
 | **`diff` + improvements export** | Deployed-vs-source drift report; export an `improvements.md` back-port | `2026-06-12-improvements-export` |
@@ -44,7 +44,7 @@ Every row below is present in the tree today; "Spec" names the design record.
 | **Collaboration layer** | Negotiated postures (peer/mentor/expert/assistant/artisan, chosen at setup, inlined in AGENT.md), the bidirectional Pact, epistemically-typed memory (`force:` + Bridge rule), and a seed-once `PROFILE.md` identity with a web editor tab and a `profile` skill that interviews the user to draft it | `2026-07-12-collaboration-layer` |
 | **Rule front door** | Both durable stores enter through the `rule` skill's fork (*standing rule, or fact to remember?* — always asked, never inferred): the memory branch elicits the binding `force` and shows the file before writing, the rule branch pressure-tests by reformulation and a mandatory counter-example. Doctrine process 1 carries the norm on every host; a `rule-gate` PreToolUse hook (Claude, Bob) and a `geneseed-guard` speed bump (OpenCode) hold it at the tool boundary | `2026-07-30-rule-front-door` |
 | **Entity registry** | `registry.json` records a lifecycle status, version, owner and add-date for every agent and skill in the tree (maintainer-side — never rendered into a bundle, so it costs no session context). `doctor` gates it against `src/` in both directions, sweeps everything that ships for credentials, and holds each vendored skill folder to an immutable upstream commit. The status surfaces as a badge in the web catalog, shown only where it deviates from `approved` | `2026-07-31-entity-registry` |
-| **Node runtime + npm package** | The whole harness runs from Node: every command `js/cli-table.json` declares, all five hook verbs, every web-console endpoint (the OS-native folder picker excepted, and declined on purpose) and both generators. Every commit runs the unit suite, `doctor --all` across every theme × host × footprint, and the generator's two self-comparisons, on Linux and Windows both; the frozen emit/cli/web recordings that also gated it retired on 2026-08-17 (see the 2.0.0 entry in [CHANGELOG.md](CHANGELOG.md)). It ships as the zero-dependency `geneseed` package (`geneseed`, `geneseed-hook`, `geneseed-build`), so `npx geneseed setup` needs no clone and nothing else installed; `geneseed migrate` moves an existing checkout install across. Node is the only runtime it asks for: the `token-report` skill's own script is `token_report.mjs`, gated over seeded transcripts for all four hosts, and `daydream` and `herdr` call `node -e` | `2026-08-06-npx-distribution` |
+| **Node runtime + npm package** | The whole harness runs from Node: every command `js/cli-table.json` declares, all five hook verbs, every web-console endpoint (the OS-native folder picker excepted, and declined on purpose) and both generators. Every commit runs the unit suite, `doctor --all` across every theme × host × footprint, and the generator's two self-comparisons, on Linux and Windows both; the frozen emit/cli/web recordings that also gated it retired on 2026-08-17 (see the 2.0.0 entry in [CHANGELOG.md](CHANGELOG.md)). It ships as the zero-dependency `geneseed` package (`geneseed`, `geneseed-hook`, `geneseed-build`), so `npx geneseed setup` needs no clone and nothing else installed; `geneseed migrate` moves an existing checkout install across. Node is the only runtime it asks for: the `token-report` skill's own script is `token_report.mjs`, gated over seeded transcripts for all four hosts, and `daydream` calls `node -e` | `2026-08-06-npx-distribution` |
 | **Runtime awareness** | MCP discovery, web research, tool-call batching, review discipline — carried by the doctrine packs (`ops 1` tool discovery, `process 4` read the docs first, `rigor 2`/`rigor 3` honest tests and cover-and-verify), not by the invariants | `2026-06-07-runtime-awareness-and-review-discipline` |
 | **Run from anywhere / uninstall** | `link`/`unlink` onto PATH; global uninstall that keeps the memory store | `2026-06-07-version-and-uninstall` |
 

package/adapters/claude-code/README.md

@@ -92,27 +92,6 @@ hooks or plugins, the AGENT.md prose still carries the rule.
 > plugin. A `context.json` still overrides, and `"extend": true` layers a manifest
 > on top of discovery.
 
-## Bundled skill — `herdr`
-
-The canonical herdr skill lives in the Geneseed source tree at
-[`src/skills/herdr.md`](../../src/skills/herdr.md). The build renders it into
-every emit — `.opencode/skills/herdr/SKILL.md` for OpenCode hosts, the
-portable bundle for everyone else — so a deployed harness picks it up
-automatically alongside every other Geneseed skill.
-
-A copy is also kept at
-[`.claude/skills/herdr/SKILL.md`](../../.claude/skills/herdr/SKILL.md) so Claude
-Code running **inside this repo** (i.e. people working on Geneseed itself)
-discovers it directly, since the build doesn't write into `.claude/`. The two
-copies share content; keep them in sync when you edit either.
-
-Either way, you only need:
-
-- the **`herdr` binary** on your `PATH` (install via [herdr.dev](https://herdr.dev)),
-- the agent launched **inside a herdr pane** — the skill self-gates on
-  `HERDR_ENV=1` and stays silent everywhere else, so shipping it is harmless
-  for users who don't run herdr.
-
 ## Other tools
 
 This adapter is Claude-Code-specific. On tools without hooks, the harness still

package/adapters/opencode/plugins/geneseed-guard.js

@@ -546,11 +546,42 @@ function protectedCheck(p) {
 // substring stance: over-matching the class is harmless (see WRITE_TOOLS note).
 const WIKI_MUTATE_TOOLS = [...WRITE_TOOLS, "delete", "remove", "rename", "move", "trash"]
 
+// Usage counting: the same rules as js/hosts/usage.mjs, inline because a plugin cannot import
+// from the repo (V2 loads every .js in plugins/ as a plugin). One line per skill or subagent
+// call, the day and the name only, under <cfg>/notebook/usage.jsonl. Silent and never throws:
+// a counter must not change, slow or fail a tool call. tests/unit/usage.test.mjs holds this
+// copy and the hook's to one table.
+const USAGE_NAME_RE = /^[A-Za-z0-9][\w.:@/-]{0,99}$/
+function usageOf(tool, args) {
+  const t = String(tool || "").toLowerCase()
+  const a = args || {}
+  let kind = null
+  let name = null
+  if (!t.startsWith("mcp") && t.includes("skill")) { kind = "skill"; name = a.skill ?? a.name ?? a.skill_name }
+  else if (t === "agent" || t === "task") { kind = "agent"; name = a.subagent_type ?? a.agent }
+  if (!kind || typeof name !== "string") return null
+  name = name.trim().replace(/^\/+/, "")
+  return USAGE_NAME_RE.test(name) ? { kind, name } : null
+}
+async function recordUse(tool, args) {
+  try {
+    if (process.env.GENESEED_NO_USAGE) return
+    const use = usageOf(tool, args)
+    if (!use) return
+    const cfg = path.dirname(PLUGIN_DIR)
+    if (existsSync(path.join(cfg, ".usage-off"))) return
+    if (!(await isDir(path.join(cfg, "notebook")))) return
+    await fs.appendFile(path.join(cfg, "notebook", "usage.jsonl"),
+      `${JSON.stringify({ ts: new Date().toISOString().slice(0, 10), ...use })}\n`)
+  } catch { /* a counter never fails a tool call */ }
+}
+
 export const GeneseedGuard = async (ctx) => {
   // The session's working directory, the same resolution the context plugin uses.
   const root = () => ctx?.worktree || ctx?.directory || process.cwd()
   return {
     "tool.execute.before": async (input, output) => {
+      await recordUse(input?.tool || input?.name, output?.args || input?.args)
       if (OFF) return
       if (await sovereignBypass(root())) return
       const tool = (input?.tool || input?.name || "").toLowerCase()

package/docs/guides/uninstall.md

@@ -28,6 +28,8 @@ Each install keeps a manifest, a list of the files Geneseed wrote. **Uninstall d
 - **OpenCode per repo:** `AGENT.md`, `.opencode/`, `laws/`, `agents/`, `skills/`, and the `instructions` entry in `opencode.json`.
 - **Claude Code, Bob, OpenClaude:** `agents/`, `skills/`, the marker files, Geneseed's managed block in the instructions file (`CLAUDE.md` or `AGENTS.md`), and Geneseed's own hooks and exclusions in `settings.json`. Your own settings keys and hooks stay.
 
+**A file Geneseed wrote that you have since edited is kept.** The manifest records each file's fingerprint, so uninstall can tell your edit apart from Geneseed's copy. It leaves the edited file in place, names it (`kept 1 file(s) you edited: ...`), and finishes the uninstall anyway: the file is yours now, and no later rebuild touches it. To delete edited files too, pass `--force`. Changing only the line endings, as a git checkout on another system does, is not an edit.
+
 It also removes the install's row from the registry of installs. Start a new session in your tool afterwards so it stops loading the old files.
 
 ## What it keeps

package/docs/guides/upgrade.md

@@ -48,6 +48,8 @@ A rebuild only replaces files the install's manifest says Geneseed owns. It leav
 
 The agent can refine its own deployed agent and skill files as it works, and so can you. A rebuild would overwrite those edits, so **setup, re-theme and upgrade export them first**. When the files they are about to overwrite differ from a fresh render, the differences are written to a markdown **improvements file** in `improvements/`, inside the install's own folder (for the OpenCode global install, `~/.config/opencode/improvements/`). The manifest does not list that folder, so rebuilds never overwrite it and uninstall never removes it.
 
+A rebuild also refuses to overwrite a file you edited. The manifest records a fingerprint of every file Geneseed wrote; when a file no longer matches it, the rebuild leaves it alone and prints `kept your edited <file> — delete it to get Geneseed's copy back`. From then on the file is yours and later rebuilds skip it. A file the new version no longer ships is kept the same way, with `(no longer shipped)`. Line-ending changes from a git checkout do not count as edits. Installs made before fingerprints existed are overwritten as before.
+
 To see the drift yourself, or to export it on demand:
 
 ```

package/docs/token-footprint.md

@@ -93,7 +93,7 @@ until 2026-09 it did, and the whole harness was paid twice per session.
   `<!-- invocation: user -->` renders `disable-model-invocation: true`; Claude
   Code and Bob then drop its description from the always-on skill metadata and
   only `/name` opens it. The three teaching skills (`teach`, `quiz`, `learn-mode`)
-  and `herdr` carry it today.
+  carry it today.
 - **Aliases cost 0 always-on.** A merged skill's old names (`<!-- aliases: -->`)
   ship as user-only stubs on Claude Code, Bob and OpenClaude, and as `/name` commands
   on OpenCode — never in the model's catalogue, so a rename or merge is free.

package/docs/understand/take-it-out.md

@@ -6,7 +6,7 @@ kind: "concept"
 section: "On your machine"
 description: "What geneseed uninstall removes, and what it keeps for you."
 ---
-`geneseed uninstall` removes only what Geneseed recorded writing: the rules file or its managed block, `agents/`, `skills/`, plugins, and Geneseed's own hook and config entries. It keeps `memory/` and `notebook/` in place, along with the files it seeded for you to edit (`user-rules.md`, `PROFILE.md`, `geneseed-wiki.jsonc`). Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. See [Uninstall](../guides/uninstall.md).
+`geneseed uninstall` removes only what Geneseed recorded writing: the rules file or its managed block, `agents/`, `skills/`, plugins, and Geneseed's own hook and config entries. It keeps `memory/` and `notebook/` in place, along with the files it seeded for you to edit (`user-rules.md`, `PROFILE.md`, `geneseed-wiki.jsonc`). Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. A file Geneseed wrote that you have since edited stays too, and becomes yours; add `--force` to delete edited files as well. See [Uninstall](../guides/uninstall.md).
 
 ---
 

package/harness.config.json

@@ -2,5 +2,5 @@
   "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
   "theme": "neutral",
   "product": "Geneseed",
-  "version": "4.1.0"
+  "version": "4.2.0"
 }

package/js/README.md

@@ -73,6 +73,7 @@ user co-owns, and the hook verbs those emitted configs then run.
 | `hooks-context.mjs` | The `context` verb — SessionStart: session files plus the repo's context docs |
 | `hooks-learn.mjs` | The `learn` verb — Stop/SubagentStop/PreCompact distiller; the hook path's ONE spawn (`$GENESEED_LLM`) |
 | `hooks-prims.mjs` | The Python path/text primitives the hook verbs share (`splitLines`, `readStdin`, a never-throwing `isFile`) |
+| `usage.mjs` | The usage counter `tool-gate` runs: one `{day, kind, name}` line per Skill or subagent call into `notebook/usage.jsonl`. Hook path: builtins only, silent, never throws |
 | `memory-files.mjs` | The memory store's file format — `frontmatter`, `MEMORY.md` index writes, agent lessons, consolidate. No spawn: the CLI and web console import it |
 | `gitref.mjs` | fs/path-only: `gitRootOf`, `gitDirOf`, `currentBranch`, `loopLaunched` — read straight off `.git`, never spawn git. Shared by `hooks.mjs`'s git-gate and `js/loop/cli.mjs`'s commit-message writer |
 | `settings.mjs` | Merges into user-owned `settings.json`/`opencode.json` (one `loadJsonObject` reader for all of them) and the managed blocks |
@@ -82,6 +83,7 @@ user co-owns, and the hook verbs those emitted configs then run.
 | `installs.mjs` | Detects deployed installs and reads back their theme, footprint, posture, mode and loop trust preset |
 | `mcp.mjs` | MCP server presets, the per-host `mcpServers` config read/write, and toggle state |
 | `link.mjs` | `geneseed link`/`unlink` — the PATH shim, and the only Windows USER-Path registry edit |
+| `owned.mjs` | Manifest rel -> path on disk decisions: `ownedWithin`, the containment boundary `uninstall.mjs` and the driver's prune both go through before acting on an `owned` list entry |
 
 **Before editing:** `hooks*.mjs` **are the hook path** — the verdict travels as JSON on stdout and
 every arm exits 0, so one stray printed byte turns a blocking gate silently permissive, and anything
@@ -106,6 +108,7 @@ Everything that inspects an already-built or already-deployed harness and report
 | `validate.mjs` | The `--validate-only` verb: renders a sandbox, scans it for tokens and dead links, own exit contract |
 | `inventory.mjs` | The one catalog walk and its taxonomy tables, read by status, the TUI and the web console |
 | `status.mjs` | `geneseed status` and `version` — the panel data, counts, accent colour, version verdict |
+| `cost.mjs` | What one install injects every session, by part (root file, skill and agent lists, session files), in characters; owns `CARRIER_CEILING`, which the smoke test gates and the console draws |
 | `diff.mjs` | `geneseed diff` — what a deployed install has that a fresh render of `src/` does not |
 | `excludes.mjs` | `geneseed exclude add|remove|list` — the WRITER for `excludes.json`; `hooks.mjs` only reads it |
 | `registry.mjs` | `installs.json` under XDG — the persistent deploy-root list `rebuild-all` re-emits into |
@@ -211,6 +214,9 @@ the deployed harness as JSON.
 | `state.mjs` | `webState` — the resolved install view every endpoint reads, with its cached inventory and doctor |
 | `catalog.mjs` | The Library read model: inventory, constitution tiers, memory/notebook/wiki/config items, `apiCatalog`/`apiItem`, `NotFound` |
 | `api.mjs` | The dashboard and settings reads: overview, recent, themes, setup, doctor, diff, installs, excludes, loops |
+| `update-check.mjs` | Is a newer release on npm? Answers from memory, refreshes in the background (a day when it got an answer, an hour when it did not), `null` on any failure, never asked under `node --test` |
+| `gates-api.mjs` | `GET /api/gates`: gate asks per rule per day over 30 days, read off every installed harness's `notebook/gates.jsonl` (the Overview's sparklines) |
+| `usage-api.mjs` | `GET /api/usage`: the 30-day skill and agent call counts across every installed harness, the never-fired list, and the 90-day prune of each `notebook/usage.jsonl` |
 | `user-files.mjs` | The fingerprint-guarded editors for `user-rules.md` (incl. memory promotion) and `PROFILE.md`, read and write |
 | `actions.mjs` | The other mutating endpoints — memory delete, MCP, excludes, installs, view, restore — plus install/deploy argv |
 | `daemon.mjs` | Detached web start/stop/status/restart, the `.geneseed-web.json` record, and `openUrl` |

package/js/build/driver.mjs

@@ -50,6 +50,9 @@ import {
   GLOBAL_MANIFEST, HOSTS, resolvePath, opencodeConfigDir, claudeConfigDir, bobConfigDir,
   openclaudeConfigDir, hostCatalogsNatively,
 } from '../hosts/hosts.mjs';
+import {
+  hashesOf, ownedHashes, ownedState, ownedWithin,
+} from '../hosts/owned.mjs';
 
 // P5d moved these out of this file for the reason P5c moved the host resolvers: `harness
 // status` renders to count, so `bin/geneseed-cli.mjs` needs the same checkout paths and the
@@ -185,11 +188,38 @@ function writeManifestAtomic(file, data) {
  * Runs AFTER the whole current set is on disk, so a live file is never momentarily absent
  * part-way through an emit. A pre-existing file that was never in the manifest is the
  * user's and is not reachable from here at all.
+ *
+ * `ownedWithin` filters the stale rels before this ever joins one with `oc` — F3
+ * (`docs/specs/2026-10-13-borrowed-hardening.md`): this loop used to `path.join` a manifest
+ * rel straight in, with no containment check, so a crafted per-repo manifest entry of
+ * `../victim.txt` deleted a file outside the install the moment a re-emit called it stale.
+ * `uninstall.mjs`'s owned-file walk already drew this boundary; the prune now goes through it.
+ *
+ * `oldHashes` (Task 4): a stale rel the user has EDITED is kept rather than deleted — the
+ * same "never clobber an edit" rule `claimer` enforces on the write side, applied to the
+ * delete side. `'unknown'`/`'unmodified'` fall straight through to the ordinary delete below,
+ * which is what keeps a pre-Task-3 manifest (no `hashes` at all) behaving exactly as before.
+ *
+ * `editRefused` (Task 4, fix round 1): the rels `claimer` already refused to (over)write this
+ * SAME emit because the user had edited them. Such a rel drops out of `owned` (never written),
+ * which makes it look exactly like `stale` — a rel this build stopped shipping — and without
+ * this exclusion `pruneOwned` would independently re-run `ownedState`, see `'modified'` again,
+ * and print its OWN "kept your edited... (no longer shipped)" right under `claimer`'s "kept
+ * your edited... delete it to get Geneseed's copy back": two warnings about one rel that is in
+ * fact still shipped. Excluded from `stale` before anything is checked or printed — silently,
+ * because `claimer` already said everything there is to say about it.
  */
-function pruneOwned(oc, oldOwned, owned) {
+function pruneOwned(oc, oldOwned, owned, oldHashes = {}, editRefused = []) {
   const now = new Set(owned);
+  const alreadyWarned = new Set(editRefused);
+  const stale = [...new Set(oldOwned)]
+    .filter((r) => !now.has(r) && !alreadyWarned.has(r)).sort();
   const failed = [];
-  for (const rel of [...new Set(oldOwned)].filter((r) => !now.has(r)).sort()) {
+  for (const rel of ownedWithin(oc, stale)) {
+    if (ownedState(oc, rel, oldHashes) === 'modified') {
+      process.stderr.write(`[geneseed] kept your edited ${rel} (no longer shipped)\n`);
+      continue;
+    }
     const victim = path.join(oc, rel);
     try {
       if (isFile(victim)) {
@@ -282,6 +312,7 @@ function emitOpencode(cfg, args, out) {
   const { existed: manifestExisted, doc } = readManifest(manifestPath);
   const oldOwned = (doc && doc.owned) || [];
   const oldDenies = recordedDenies(doc);
+  const oldHashes = hashesOf(doc);
 
   const agentPathRel = relUnder(out, root);
   const agentPath = agentPathRel ? `${agentPathRel}/AGENT.md` : 'AGENT.md';
@@ -293,12 +324,12 @@ function emitOpencode(cfg, args, out) {
     {
       theme: args.theme, out, root, footprint: args.footprint,
       nativeCatalog: hostCatalogsNatively('opencode'), oldOwned, manifestExisted, agentPath,
-      oldDenies,
+      oldDenies, oldHashes,
     });
-  const { owned, stats, cfgName, skillDenies } = rendered;
+  const { owned, stats, cfgName, skillDenies, editRefused } = rendered;
 
   phaseLog('PRUNE');
-  pruneOwned(oc, oldOwned, owned);
+  pruneOwned(oc, oldOwned, owned, oldHashes, editRefused);
 
   phaseLog('MANIFEST');
   writeManifestAtomic(manifestPath, {
@@ -306,6 +337,7 @@ function emitOpencode(cfg, args, out) {
       + 'Do not edit; removed on re-emit. A pre-existing file not in this '
       + 'list is yours and is never touched.',
     owned: [...owned].sort(),
+    hashes: ownedHashes(oc, owned),
     scope: 'project',
     ...(skillDenies.length ? { skill_denies: skillDenies } : {}),
   });
@@ -341,6 +373,7 @@ function emitOpencodeGlobal(cfg, args, out) {
   const { doc } = readManifest(manifestPath);
   const oldOwned = (doc && doc.owned) || [];
   const oldDenies = recordedDenies(doc);
+  const oldHashes = hashesOf(doc);
 
   const agentPath = path.join(cfgDir, 'AGENT.md').split(path.sep).join('/');
 
@@ -349,12 +382,12 @@ function emitOpencodeGlobal(cfg, args, out) {
     {
       theme: args.theme, cfgDir, out,
       footprint: args.footprint, nativeCatalog: hostCatalogsNatively('opencode'),
-      oldOwned, agentPath, oldDenies,
+      oldOwned, agentPath, oldDenies, oldHashes,
     });
-  const { owned, stats, memStatus, nbStatus, cfgName, skillDenies } = rendered;
+  const { owned, stats, memStatus, nbStatus, cfgName, skillDenies, editRefused } = rendered;
 
   phaseLog('PRUNE');
-  pruneOwned(cfgDir, oldOwned, owned);
+  pruneOwned(cfgDir, oldOwned, owned, oldHashes, editRefused);
 
   phaseLog('MANIFEST');
   writeManifestAtomic(manifestPath, {
@@ -362,6 +395,7 @@ function emitOpencodeGlobal(cfg, args, out) {
       + 'Do not edit; removed on re-emit. The memory and notebook '
       + 'stores are NOT listed — they are never deleted.',
     owned: [...owned].sort(),
+    hashes: ownedHashes(cfgDir, owned),
     ...(skillDenies.length ? { skill_denies: skillDenies } : {}),
   });
 
@@ -391,6 +425,7 @@ function emitClaudeCore(cfg, args, { cfgDir, claudeMd, scope, host, out, hookOpt
   const oldOwned = (doc && doc.owned) || [];
   const oldManaged = (doc && doc.managed && typeof doc.managed === 'object'
     && !Array.isArray(doc.managed)) ? doc.managed : {};
+  const oldHashes = hashesOf(doc);
 
   // RENDER + WIRE in one child's worth of work. `preambleExclude` is null for every
   // carrier but `CLAUDE.md`, so Bob's `AGENTS.md` does not resolve to one; for a `CLAUDE.md`
@@ -402,12 +437,12 @@ function emitClaudeCore(cfg, args, { cfgDir, claudeMd, scope, host, out, hookOpt
     out,
     footprint: args.footprint, nativeCatalog: hostCatalogsNatively(host),
     oldOwned, oldManaged, preambleExclude: preambleExclude(claudeMd, host),
-    hookOpts,
+    hookOpts, oldHashes,
   });
-  const { owned, stats, memStatus, nbStatus, managed } = rendered;
+  const { owned, stats, memStatus, nbStatus, managed, editRefused } = rendered;
 
   phaseLog('PRUNE');
-  pruneOwned(cfgDir, oldOwned, owned);
+  pruneOwned(cfgDir, oldOwned, owned, oldHashes, editRefused);
 
   phaseLog('MANIFEST');
   writeManifestAtomic(manifestPath, {
@@ -417,6 +452,7 @@ function emitClaudeCore(cfg, args, { cfgDir, claudeMd, scope, host, out, hookOpt
       + '(settings.json, or settings.local.json at PROJECT scope on Claude/OpenClaude) '
       + 'hooks so uninstall removes exactly those.',
     owned: [...owned].sort(),
+    hashes: ownedHashes(cfgDir, owned),
     managed,
     scope,
   });

package/js/build/emit-claude.mjs

@@ -13,6 +13,7 @@ import {
   managedBlockRemove, managedBlockWrite, mergeClaudeSettings,
   unwireClaudeExcludes, unwireClaudeSettings, wireClaudeExcludes,
 } from '../hosts/settings.mjs';
+import { claimLeaf } from '../hosts/owned.mjs';
 import { writeText } from '../lib/fs.mjs';
 import { get, isDict, isTruthy } from '../lib/json.mjs';
 import { relPosix } from '../lib/text.mjs';
@@ -51,7 +52,7 @@ export function emitClaudeRender(cfg, job) {
   phaseLog('RENDER');
   const {
     theme: themeName, cfgDir, claudeMd, scope, out, footprint, host, nativeCatalog,
-    oldOwned,
+    oldOwned, oldHashes = {},
   } = job;
 
   // `os.path.relpath(cfg, claude_md.parent)` — note the reversed argument order, and
@@ -98,10 +99,16 @@ export function emitClaudeRender(cfg, job) {
   // slim shadow stub whose only job is to have the same filename.
   if (isBob && agentText !== null) {
     const rulesMd = path.join(cfgDir, 'rules', 'geneseed.md');
-    mkdirSync(path.dirname(rulesMd), { recursive: true });
-    writeText(rulesMd, scope === 'project' ? BOB_RULES_STUB
-      : stripCapabilityLinks(prefixedAgentText('../') || agentText));
-    owned.push('rules/geneseed.md');
+    // `claimLeaf` BEFORE `mkdirSync`: `safeLeaf` walks up to the nearest EXISTING ancestor
+    // (`resolvePath`'s own contract), so it needs no directory created first — and creating
+    // `rules/` first would plant an empty directory at a linked ancestor's target the moment
+    // before the refusal fires.
+    if (claimLeaf(cfgDir, rulesMd, 'rules/geneseed.md')) {
+      mkdirSync(path.dirname(rulesMd), { recursive: true });
+      writeText(rulesMd, scope === 'project' ? BOB_RULES_STUB
+        : stripCapabilityLinks(prefixedAgentText('../') || agentText));
+      owned.push('rules/geneseed.md');
+    }
   }
 
   ensureAgentOverridesStub(cfg, cfgDir);
@@ -119,7 +126,7 @@ export function emitClaudeRender(cfg, job) {
   // One shared `claim` (see `claimer`): the skills/agents writer and the Bob command writer
   // below both push into the same `owned` list, so a pre-manifest-install warning still
   // prints once across the whole emit rather than once per writer.
-  const claim = claimer(oldOwned, cfgDir, true);
+  const claim = claimer(oldOwned, cfgDir, true, oldHashes);
   const { nAgents, nSkills, written } = writeNativeLayer(
     items, path.join(cfgDir, 'agents'), path.join(cfgDir, 'skills'),
     loadAgentOverrides(cfgDir),
@@ -160,15 +167,19 @@ export function emitClaudeRender(cfg, job) {
       : host === 'bob' ? ['settings.json'] : [])
       .concat(['context.json', WIKI_FILE, 'agent-overrides.json']);
     if (!existsSync(gi)) {
-      writeText(gi, `${giLines.join('\n')}\n`);
-      owned.push('.gitignore');
+      // `!existsSync(gi)` is exactly the case a DANGLING symlink also satisfies — it reads
+      // as absent — so `claimLeaf` (which lstats) runs before the write, not instead of
+      // this check.
+      if (claimLeaf(cfgDir, gi, '.gitignore')) {
+        writeText(gi, `${giLines.join('\n')}\n`);
+        owned.push('.gitignore');
+      }
     } else if (oldOwned.includes('.gitignore')) {
       owned.push('.gitignore');
     }
   }
 
-  writeVersion(cfg, cfgDir);
-  owned.push(VERSION_MARKER);
+  if (writeVersion(cfg, cfgDir) !== null) owned.push(VERSION_MARKER);
 
   shipLeanLaws(items, theme, cfgDir, owned, footprint);
 
@@ -192,6 +203,7 @@ export function emitClaudeRender(cfg, job) {
     memStatus,
     nbStatus,
     managed,
+    editRefused: [...claim.editRefused],
   };
 }
 

package/js/build/emit-common.mjs

@@ -10,6 +10,7 @@
  * `emit-claude.mjs` do that; `bundle.mjs` renders the bundle they read from.
  */
 import path from 'node:path';
+import { claimLeaf } from '../hosts/owned.mjs';
 import { copyFile, writeText, isDir } from '../lib/fs.mjs';
 import { relPosix } from '../lib/text.mjs';
 import { SRC_DIR_TOKENS, destRel } from './render.mjs';
@@ -183,9 +184,14 @@ export function shipLeanLaws(items, theme, cfgDir, owned, footprint) {
     // nothing to detect, not because the gate cannot see it.
     if (text !== null && parts.length && dirs.has(parts[0])) {
       const dest = path.join(cfgDir, ...parts);
-      mkdirSync(path.dirname(dest), { recursive: true });
-      writeText(dest, text);
-      owned.push(rel);
+      // `claimLeaf` BEFORE `mkdirSync`, for the same reason `emitClaudeRender`'s rules stub
+      // does: `safeLeaf` needs no directory created first, and creating one ahead of the
+      // refusal would plant it at a linked ancestor's target.
+      if (claimLeaf(cfgDir, dest, rel)) {
+        mkdirSync(path.dirname(dest), { recursive: true });
+        writeText(dest, text);
+        owned.push(rel);
+      }
     }
   }
 }

package/js/build/emit-opencode.mjs

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

package/js/build/source.mjs

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