spidersan 0.10.0 → 0.20.1

package/CHANGELOG.md

@@ -5,6 +5,169 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.20.1] - 2026-10-28
+
+### Fixed
+
+- **The plugin's dangerous-`rm` block did not block** (`spidersan-pre.sh` v2.7). It
+  answered `{"continue": false}`, and Claude Code ran the command anyway and only stopped
+  the agent afterwards. It now returns `permissionDecision: "deny"`, the form
+  `force-push-guard` already used.
+- **It also fired on safe commands.** It searched the whole line for a bare `~` or `/`, so
+  `cd ~ && rm -rf /tmp/x` was "blocked". It now reads only the arguments of a command that
+  is `rm` (per `&&`, `||`, `;` and `|` segment, after `sudo` or `VAR=`), parsed with
+  `shlex`, so a quoted `"$HOME"` or `'/'` counts and `echo 'rm -rf ~'` doesn't. `git rm`
+  is not `rm`. 22 new cases, all red before the fix.
+- **The soft "rm detected" warning** uses the same parse, so a path containing `-rm-` or a
+  `git rm` no longer triggers it. One `python3` call per Bash command fewer.
+
+### Added
+
+- **The `/spidersan` skill ships with the plugin** (`plugin/skills/spidersan`, #333):
+  conflict tiers, real merge checks (`bin/pr-conflicts <N>`), and branch tidying. The same
+  skill is published as `skill-spidersan` in treebird7/treebird-oss-skills.
+
+## [0.20.0] - 2026-10-28
+
+A trim to the core, plus the git safety hooks as a Claude Code plugin. Pre-1.0 on
+purpose: it gets a week of use before 1.0. The last full build is tagged
+`v0.11.0-full`, and any removed command can be restored from it.
+
+### Added
+
+- **Claude Code plugin** (`plugin/`, #331). `/plugin marketplace add treebird7/spidersan-oss`,
+  then `/plugin install spidersan@spidersan`. It installs six hooks:
+  - `force-push-guard`: blocks plain force-pushes.
+  - `same-file-warn`: warns when two sessions share a checkout, and blocks a commit
+    that would sweep up another session's files.
+  - `spidersan-pre` and `spidersan-post`: conflict, ownership and dead-branch advisories,
+    plus trunk-poison repair.
+  - `spidersan-overlap-warn` and `spidersan-worktree-guard`.
+
+  Agent identity is optional, via `SPIDERSAN_IDENTITY_FILE` / `SPIDERSAN_IDENTITY_KEY` /
+  `SPIDERSAN_AGENT` / `SPIDERSAN_SESSION_HINT`. Four shell suites (151 cases) run in CI.
+- A parity test that every name the AI reasoner treats as a real command is one the CLI
+  registers. The old list included the removed commands and `collab`, which never existed.
+
+### Removed (breaking)
+
+- **15 commands that a usage audit found nothing calls** (#330): `daily`, `pulse`,
+  `queen`, `torrent`, `bot`, `ask` / `advise` / `explain` / `ai-ping` / `ai-setup` /
+  `ai-telemetry` / `check-opt-out`, `mq`, `dashboard`, `rescue`, `welcome`, `fleet-status`,
+  `merge-plan`, `sync-advisor`, `auto`, `claim` / `release` / `whos-here`.
+- **The `spidersan-ecosystem` plugin loader**, so `SPIDERSAN_CORE_ONLY` and
+  `SPIDERSAN_ECOSYSTEM=0` no longer switch anything. `conflicts --ecosystem` (the
+  multi-repo scan) is unrelated and stays.
+- `watch` no longer writes per-file claims or puts an in-file coordination marker into
+  your files. Old registries that carry `claims` still load.
+- The public export `escapeBlessed`, and the dependencies `blessed`, `@types/blessed` and `ts-morph`.
+- MCP server (`spidersan-mcp` 2.0.0): the `pulse_remote_drift` tool, which called `pulse`.
+- `config` wizard questions about the ecosystem plugin and auto-watch.
+
+
+### Added
+
+- **A graphify knowledge graph of the repo, regenerated on demand into the now-gitignored `graphify-out/`.** ~1,980 nodes and ~4,280 edges over 247 code files, queryable with `graphify explain` / `affected` / `path` instead of grepping; `AGENTS.md` carries the commands, each run verbatim first. Nothing is committed — it rebuilds in ~30s. Extraction is local tree-sitter AST under `--code-only`, with the wrapper running under `env -i` because `extract` picks its backend from *whichever API key is set*: the stripped environment is the control, the flag is only the intent. `--with tree-sitter-sql` fails silently without the grammar, parsing the 26 `.sql` files to nothing behind a single warning and exit 0. The freshness check is `git rev-list --count HEAD..origin/main` rather than an mtime comparison, because a checkout behind the remote rebuilds into a graph that *looks* fresh — `built_at_commit` agrees with `HEAD` while both are stale. Measured on this repo: every file parsed with no syntax errors, `path` returns meaningful short routes (`conflictsCommand` → `fetchCrossMachineBranches()` → `SupabaseStorage`), `god-nodes` mixes framework fan-in (`vitest` 67, `commander` 45) with real hubs (`getStorage()` 63, `Branch` 54), and 176 labels are shared by more than one node — which matters because the verbs disagree about ambiguity: `explain` refuses and lists the candidate ids, `affected` refuses with *No unique node match*, and `path` does neither, answering *No directed path found* exactly as it would for a genuine negative.
+
+### Fixed
+
+- **`conflicts` no longer flags branches whose PRs merged long ago, and a missing ref no longer counts as deleted** (#327, #329, sp-slemub). `activeBranches()` dropped only entries proven merged into trunk. A squash-merged, deleted branch is never an ancestor of trunk, so it read as *orphaned* and was kept: `conflicts --pr 543 --real --vs-prs` in Envoak raised a TIER 2 PAUSE and two TIER 1 WARNs against branches of PRs merged weeks earlier (Envoak #212, #214, #484), and 11 of that registry's 12 entries were stale. A missing ref is ambiguous, though. `resolveBranchRef` only sees refs already on this machine, so a branch live on another machine but never fetched here looks the same, and `ready-check` gets no cross-machine registry pull. The rule, shared by the read side and `sync` through `splitOrphans()`: an orphan is dropped only when `git ls-remote --heads origin` confirms the branch is gone. It is one call, made only when some entry is orphaned, with a 15 s cap. If origin can't be asked, every orphan is kept. `sync` now deletes only confirmed-gone orphans, says which ones it kept and why, and still prunes `abandoned` entries without asking. Cost: `conflicts --json` on a 14-entry registry with 12 orphans went from about 0.47 s to 0.94 s. Run `sync` to clear confirmed-gone entries and get it back.
+- **The "Add/Add Conflict Helper" is gone** (#328). It fired on any overlapping path matching `/\.md$/` or `docs/` and told the reader to `git checkout --theirs` and rename to `.incoming`. In Envoak it said that about a long-lived `CLAUDE.md` that both branches had only modified. Neither emitter (`suggestAddAddResolution` in the command, `renderAddAddResolution` in the renderer) had a merge base to check against, so both were removed. A genuine add/add is still reported by `--real`, which prints the merge-tree kind per file (`docs/new.md (add/add)`).
+
+- **`SPIDERSAN_CORE_ONLY` was inverted** (PR #313) — `=0` disabled the ecosystem plugin and `=1` did nothing. Now `1/true/yes/on` disables it and anything else allows it. `SPIDERSAN_ECOSYSTEM=0/1/true/false/…` are plugin switches only and are never read as a repo path (it used to scan a repo named `0`).
+- **`conflicts --real` merges into the REMOTE trunk, not a stale local one** (sp-vifo) — the base came from `getTrunkBranch()`, which returns a branch *name* (`main`), so merge-tree ran against whatever the local ref happened to point at. In a long-lived checkout that drifts: on `~/Dev/treebird` a leftover worktree from the retired beads tool had pinned local `main` **78 commits** behind `origin/main`, and `--real` reported *clean vs main* on a branch that `--real --base origin/main` showed conflicting. Green, earned by comparing against the wrong thing. The base is now `origin/<trunk>` when that remote-tracking ref exists (via the existing `resolveBranchRef()`), falling back to the local name when it does not — fresh clones and no-origin repos are unchanged. **No fetch**: this reads refs already on disk, because `--real` runs from a pre-merge hook and a check that hits the network every invocation is a different problem; `origin/<trunk>` can therefore be stale too, which is why the report always names the base it used. An explicit `--base` still short-circuits trunk detection entirely. The `--pr` arm already reasoned this way (tb-57fr) and is unchanged — it fetches, because it is already fetching the PR head.
+- **`conflicts` no longer claims merge-readiness from a registry-only check** (PR #295) — the zero-conflict path printed "✅ You're good to merge!" after comparing *registered file lists*, which runs no merge and is structurally blind to add/add and content conflicts against the base. Repro'd live: the pre-merge hook printed the all-clear while `git merge-tree` reported `CONFLICT (add/add)`. Both emitters (the command, and the unwired `renderConflictReport` seam) now state scope — `No registry overlap for "<branch>" (vs N registered branches)` plus the command that does answer merge-readiness. The branch count makes "did the work" observable. Guarded by tests on both the live emitter and the seam.
+- **`conflicts --real --vs-prs` no longer silently drops the cross-PR half** (sp-a1l3) — `options.real` short-circuited into the merge-tree path and `return`ed, so the `--vs-prs` block was never reached. `conflicts --pr <N> --real --vs-prs` — documented as THE authoritative pre-merge check — therefore printed only "clean vs trunk" and exited 0 while never consulting GitHub for other open PRs: a check reporting success while doing nothing. The two flags now compose: the merge-tree check runs first, then execution falls through to the cross-PR/overlap pass, and the process exit code is `max(real, overlap)` (real conflicts are tier-blocking, overlap only blocks under `--strict`). `--real` alone, `--pr N` alone and `--vs-prs` alone are unchanged and pinned by tests. On the composed path an uninitialized registry or an unregistered branch degrades the overlap half with a loud "did NOT run" warning instead of failing the whole command, so `--real`'s registry-independence survives. Proven by effect with a `gh`-disabled shim: before, `--real --vs-prs` printed one line and never called `gh`; after, it prints the merge-tree verdict *and* the cross-PR/registry overlap report.
+
+### Added
+
+- **GitHub Actions auto-register is back — zero-secret OIDC edition** (PR #279, #280) — successor to the workflow retired in c9a449b for keeping a DB key in public-repo Actions secrets. New flow: on push, CI mints a short-lived GitHub OIDC token (`permissions: id-token: write`, **no repo secrets at all**); the new `supabase/functions/register-branch` edge function verifies it (RS256, issuer, audience, `repository` claim allowlist + optional `repository_id` pin — the `repository` claim is the only real gate) and writes `branch_registry` server-side with an `sb_secret_*` key held only in Supabase function secrets. Branch and actor come from verified token claims, never the request body. Existing branches get a `files_changed`-only refresh — a push can never re-activate a merged branch or overwrite attribution (which also neutralizes token replay). The workflow (`.github/workflows/auto-register.yml`) no-ops until the `SPIDERSAN_REGISTER_URL` repo variable is set. Proven end-to-end in production (probe push → workflow green → correct claims-derived row).
+- **`setup-oidc-autoregister` Claude Code skill** (`.claude/skills/setup-oidc-autoregister/SKILL.md`) — guided BYK adoption of the above on your own repo + Supabase project: deploy, wire secrets server-side, copy workflow, strict 4-point verify (three exact reject codes + probe row). Security invariants stated as non-negotiable, including rejecting legacy `eyJ` service_role JWTs via a no-print prefix check. Note: `.claude/skills/` is allowlist-gated in `.gitignore` — new skills need a `!` entry.
+
+### Changed
+
+- **`conflicts --ecosystem` no longer ships a hardcoded repo list** (PR #313) — repos come from `--repos`, then `SPIDERSAN_ECOSYSTEM` (colon-separated paths), then `conflicts.ecosystemRepos` in a config file; a project file replaces the global list. Unconfigured scans no repos and prints a hint (`--json` still emits a valid empty report). `spidersan config` shows the resolved count and source. See README → *Ecosystem scan repo list*.
+- **Retired short agent IDs are no longer accepted by `bot`** (PR #314) — its permission lists dropped `ssan`, `srlk`, `bsan`, `wsan`, `tsan`, `mycs`, `trbr`, `nemo`, `codx`, `goos`. A sender still using one gets no permission tier (access only narrows). Broadcasts are signed `spidersan`; temp files use a `spidersan-*` prefix; `daily` maps 🔍 to `sherlock` and still recognises `sherlocksan` in old dailies.
+- **`branch_registry` uniqueness is now composite `(repo_name, branch_name)`** (tb-31t4, PR #282 + #284) — the fleet-wide auto-register rollout proved the old global-UNIQUE `branch_name` collision: the same branch name pushed from three repos left one row (first writer wins). Interim function fix (#282): the files-refresh PATCH is scoped by `repo_name` and a colliding insert reports `collided: true` instead of silently touching another repo's row. Real fix (#284, applied to prod as migration `20260801195726` with `UNIQUE NULLS NOT DISTINCT` — legacy NULL-`repo_name` rows keep their shared-namespace semantics): cross-repo same-name branches now coexist; same-repo duplicates still violate. CLI unaffected — its only `branch_registry` touch is a connectivity probe; machine sync uses `spider_registries` (already composite).
+- **eslint 8 → 10, flat config** (tb-wb47, PR #283) — `eslint.config.mjs` replaces `.eslintrc.json`, same rule intent. The two new recommended rules flagged 8 real issues, fixed in code not config: three dead initializers removed (`no-useless-assignment`) and five `throw` sites now attach `{ cause }` (`preserve-caught-error`).
+
+### Security
+
+- **CI dependency audit scoped to production deps** (`npm audit --omit=dev --audit-level=high`) — GHSA-mh99-v99m-4gvg (brace-expansion, published 2026-07-29) is unfixable inside eslint 8's transitive tree: the only patched release (5.0.8) breaks minimatch@3's direct-function import (verified). The published CLI ships none of that chain. Full-tree audit returns with the eslint 8→10 flat-config migration (tracked as invoak tb-wb47). js-yaml and postcss high advisories fixed via lockfile bump in the same pass.
+  - **Restored to full tree** in PR #283: with eslint 10 the dev-chain advisories are gone — `npm audit --audit-level=high` runs unscoped again and reports 0 vulnerabilities.
+
+### Removed
+
+- **The Treebird Hub transport is gone** (sp-hnjf, follow-up to sp-8iqm/#290) — `hub.treebird.uk` was decommissioned 2026-09-05 and answers `404 Application not found` behind `x-railway-fallback: true`, so every call site below was dead code, not a severed channel. Deleted `src/lib/hub.ts` (`HubClient` + `FetchHubAdapter`), the `HUB_URL` env var, and the `--hub` / `--hub-sync` flags on `watch`, `auto start` and `pulse`, plus `autoWatch.hub` / `autoWatch.hubSync` in `.spidersanrc`. An existing config file carrying those keys stays valid and inert — `validateConfig` only checks keys it knows. `socket.io-client` dropped with the `--hub` WebSocket.
+  - Three further **unconditional success lines** of the same class as `git-events-subscriber.ts:467` are gone: `watch.ts` printed `📤 Posted conflict to Hub chat` after awaiting a `Promise<void>` that swallowed failure at *both* the adapter and client layers; `torrent claim` / `torrent complete` each printed `✅ Notified Hub` from inside a `try` that only catches throws, so a 404 response read as success; and `conflicts --wake` printed `✅ Woke N agent(s)` for a helper that returned `true` unconditionally. `--wake` / `--retry` are removed outright, and `conflicts --auto` with them — it only ever suppressed the wake-flow confirmations and is now read by nothing (`register --auto` is a different flag and is untouched).
+  - **Re-pointed, not dropped:** the `watch` conflict alert and `conflicts --notify` now go through `deliver()`/`notify()` from `src/lib/notify.ts`, the seam landed in #290 — so they report the real delivery outcome and never claim a send they did not inspect. Delivery is configured by `SPIDERSAN_ROOM_TOKEN`, not by a flag; unset means the alert is logged `NOT NOTIFIED`.
+  - **Dropped, not re-pointed:** remote-drift alerts (`pulse --hub-sync`, and the `watch --fetch-poll` variant). Drift is not a conflict, so it does not belong in the seam's event class, and both commands already print the drift report the operator is reading.
+
+### Removed (docs)
+
+- `INSTALL_AUTO_REGISTER.md`, `AUTO_REGISTER_USE_CASES.md` and the local `install-auto-register` skill (832 lines) — they taught the retired secret-in-CI flow. README § "GitHub Actions Auto-Register (OIDC)" is the single current reference.
+
+### Added
+
+- **`spidersan depends` actually works now** (tb-5h9b) — it was a stub that always printed "requires Supabase storage" and stored nothing. Dependencies (`dependsOn`) and the merged PR (`prNumber`, via `merged --pr N`) now live on the registry `Branch` entry itself, so they work with **local** storage too. `merge-order` folds declared dependencies into its sort as directed edges (new `addDependencyEdges` in `src/lib/graph.ts`): "A depends on B" puts B first regardless of file overlap. `registry-sync` pushes/pulls both fields (`depends_on`, `pr_number` on `spider_registries` — canonical table, not the dead `branch_registry` path removed above). **Deploy order:** apply migration `treebird/supabase/migrations/20260711000000_spider_registries_depends_pr.sql` before shipping this, or cloud pushes will reject the unknown columns.
+
+### Fixed
+
+- **Registry store: crash-safe writes + no silent wipe** (`src/storage/json-branch-registry-store.ts`) — `save()` now writes temp-then-rename (atomic), and `load()` only falls back to an empty registry on ENOENT. Previously a corrupt/truncated `registry.json` (crash mid-write) parsed as "empty" and the next `register` **silently destroyed every agent's registrations**; now it fails loudly and never saves over the corrupt file.
+- **`cleanup` no longer deletes active registrations** — `registeredAt` is never refreshed, so an old ACTIVE entry usually means in-flight work; deleting it blinded conflict detection for every other agent. `storage.cleanup(olderThan, includeActive)` now skips `status: 'active'` by default; new `cleanup --force` restores the old behavior. Both `cleanup` and `stale` also reject non-numeric `--days` instead of silently matching nothing.
+- **`conflicts --pr` survives PR force-pushes** — the stash refspec is now `+pull/<n>/head:refs/spidersan/pr-<n>`; without the `+`, a rebased PR made every subsequent check fail with "Could not fetch PR head" until the ref was deleted by hand.
+- **`conflicts --pr --strict` is honoured** — the real merge-tree path only read `--exit-code`, so the advertised CI flag `--strict` silently exited 0 on real conflicts. `--strict` now gates the real path too. The dead `--max-retries` option (declared, never read) is removed.
+- **`conflicts --pr --gate` fails closed** — `getPRLabels` now returns `null` on failure (vs `[]`), and the gate treats "couldn't read labels" (gh missing/unauthenticated/rate-limited) as UNMET instead of invisibly bypassing a `needs-*:` blocking label.
+- **`mq run --execute` refuses a repo mismatch** — the speculative merge fetches `pull/<n>/head` from the **cwd's** origin, so `--repo other/repo` from a different checkout would CI-test one repo's code and land another's PRs. Now hard-errors unless the cwd checkout IS the target repo.
+- **`mq` red-gate with zero applied PRs no longer crashes** — a red gate before any PR applied (broken base) hit `culprit.number` on `undefined`, aborting the run and losing landed/ejected state; it now aborts cleanly with `converged: false`.
+- **Reconcile-on-read: unpushed local commits are no longer reconciled away** — `reconcileBranches` preferred the remote-tracking ref, so a branch whose PR landed but that kept receiving local commits was classified `merged` and vanished from conflict detection. Both tips (stale `origin/<name>` AND `refs/heads/<name>`, new `resolveLocalBranchRef`) must now be ancestors of trunk.
+- **`getRemoteHead` matches the exact ref** — `git ls-remote --heads origin main` pattern-matches ref *suffixes* (`feature/main` too) and the first line won; remote-drift detection could compare against the wrong branch's SHA. Now queries and matches `refs/heads/<branch>` exactly.
+- **`getChangedFiles` empty-diff semantics** — a successful-but-empty `main...HEAD` diff no longer falls through to `HEAD~1` (which reported the previous already-merged commit's files as "changed" — phantom registrations on fully-merged branches). Also passes `core.quotepath=off` so non-ASCII paths aren't stored C-quoted, and `ready-check`/`register` now diff against the detected trunk instead of hardcoded `main`.
+- **`stale --notify` delivers to the agent's own pending file** — the cwd's `.pending_task.md` was checked first, so every agent's notifications landed in whatever repo the command ran from; now only agent-owned locations are considered (incl. `~/Dev/treebird/agents/<agent>/`).
+- **`bot`**: command args can no longer start with `-` (git option injection, e.g. `/pull repo --force`); `/log abc` no longer produces `git log -NaN`; `/sync` no longer runs registration + conflict-check twice; dead `pollInterval`/`syncInterval`/`rateLimit` config fields removed.
+
+### Removed
+
+- **Dead code sweep (~700 lines + a dependency)** — `src/lib/crdt.ts` (Yjs SwarmState, zero callers; drops the `yjs` dependency), `src/tui/dashboard.ts` + `src/tui/screen.ts` (two unwired TUI implementations; `spidersan dashboard` uses `src/commands/dashboard.ts`), the never-called `branch_registry` method family (`setDependencies`/`setConflicts`/`markMerged`/`getStale`/`getRaw`/`pushGitHubBranches` on the Supabase impl + wrappers), and the unused factory functions `getBranchRegistryStore`/`getSupabaseRegistrySyncClient`. `mqCommand` added to the library barrel (was CLI-only).
+
+### Added
+
+- **`mq` conflict-graph ordering** (tb-y121, merge queue phase 1.5, PR #254 + #255) — `mq run`/`mq status` order the ready-PR queue with the existing `buildConflictGraph` + `topologicalSort` (`src/lib/graph.ts`, already used by `merge-order`) instead of plain PR-number order: the most-blocking (most file-overlapping) PRs sort first so a "hub" PR lands before the PRs it conflicts with. Non-conflicting PRs and ties fall back to oldest-first. Pure `conflictOrder` over a pre-fetched `filesByPr` map — no IO — so `mq run`'s plan, `mq status`, and the actual `--execute` all agree on the same order. `listChangedFiles` (one `gh pr view` per PR, 30s timeout) degrades to "no files" on fetch failure with a visible stderr warning, rather than silently collapsing back to oldest-first. Correctness still rests on the speculative-merge + CI gate, not this ordering.
+- **`spidersan pulse` smalltoak health probe** (tb-r9s) — `pulse` now proactively probes the smalltoak comms bridge (`SMALLTOAK_SERVER_URL`) that `spidersan bot` depends on, surfacing an outage before message-driven git ops silently stall. New `src/lib/smalltoak.ts` `probeSmalltoak()`: GETs `/health` with a 2s timeout; **any HTTP response = reachable** (a missing `/health` route never false-alarms), only a network error/timeout = DOWN. No-op when `SMALLTOAK_SERVER_URL` is unset. Shown in the human report (`Smalltoak: ✅ up` / `🔴 DOWN`) and JSON (`smalltoak` field).
+
+### Tests
+
+- **`merge-plan` fused-verdict integration test** (tb-uvy) — `tests/merge-plan.integration.test.ts` drives a real temp-git train (genuine `git merge-tree` conflict + a real stacked base) through `analyzeRealConflicts` → `buildMergePlan`, asserting BLOCKED (real conflict file surfaced), WAIT (stacked, parent-before-child order), and MERGE. Closes the dogfood gap from tb-bi2, whose live RT train was disjoint and only exercised MERGE/STALE/ordering.
+
+### Added
+
+- **Reconcile-on-read** (`src/lib/reconcile.ts`) — `conflicts`, `ready-check`, and `merge-order` now fold git truth over the registry's `status` before answering: a branch already merged into trunk (`git merge-base --is-ancestor`, or registry status `completed`) is dropped from conflict detection. Retires the phantom-conflict class where a fully-merged branch kept showing as conflicting from a stale worktree. New git primitives `resolveBranchRef` / `isMergedInto` (`src/lib/git.ts`). Orphaned (no-ref) branches are deliberately KEPT on the read path — a missing ref can mean "unfetched on another machine", and dropping it would miss a real conflict.
+
+### Security
+
+- **Consolidate `spider_registries` to runtime + harden RLS** (PR #247) — fixed silent cross-project drift where `spider_registries` lived on the vault Supabase project (`<vault-project-ref>`) while `branch_registry` lives on runtime (`<runtime-project-ref>`). Registry-sync uses a single `SUPABASE_URL` client, so the `spider_registries` half of every runtime-pointed sync was silently 404-ing. Canonical = runtime. Also closes wide-open anon RLS on the public project: `spider_registries` and `branch_registry` both had anon `INSERT/UPDATE/SELECT` open; views used owner-rights that bypassed base-table RLS. Hardening: service_role writes, authenticated agent-JWT reads, anon denied, views `security_invoker`.
+- **Migrations** — `20260219_spider_registries.sql` (hardened CREATE + GIN index, runtime), `20260623_harden_spidersan_rls.sql` (branch_registry + views, runtime), `20260623_decommission_vault_spider_registries.sql` (vault teardown, manual, gated on parity), `supabase/migrations/CONSOLIDATION.md` (ordered deploy runbook).
+
+### Removed
+
+- **`auto-register.yml` CI workflow** — retired. It ran `spidersan register` on every push using an anon `SUPABASE_KEY` from Actions secrets, writing `branch_registry` as anon. The RLS hardening above denies anon writes, making this workflow both broken and a security risk (promoting the key to service_role in a public repo's CI secrets is worse). Machine-side `registry-sync` with the service key is the correct sync path.
+
+### Fixed
+
+- **`merge-plan` fused verdict is additive, not lossy** (tb-cdz) — a PR that is both behind base and has non-required checks red (`STALE` + `UNSTABLE`) now keeps the `STALE` headline **and** annotates the suppressed check axis (`↳ non-required checks red`). Previously the `UNSTABLE` signal was silently dropped on the STALE path. Ref coord-tree pair `fused_verdict_must_be_additive_not_lossy`.
+- **`spidersan sync`** now prunes **merged** registry entries (is-ancestor / status `completed`), not just orphans. Previously a merged branch whose ref still existed lingered forever and kept phantom-conflicting; merged entries are now deleted, not just marked.
+
+## [0.11.0] - 2026-06-16
+
+### Added
+
+- **`spidersan merge-plan`** — ordered merge plan for open PRs; fuses PR merge-state + CI rollup (`src/lib/github.ts`), real `git merge-tree` conflicts (`src/lib/git-merge-analyzer.ts`), staleness (commits behind base), and stacked-base detection into a per-PR verdict (MERGE / BLOCKED / WAIT / VERIFY / STALE / UNKNOWN) plus a topologically-ordered global plan. Fork-safe head via `pull/<n>/head`; advisory (always exit 0). Supports `--json`, `--base`, `--limit`, `--include-drafts`, `--repo`.
+- **`spidersan pr-check <number>`** — check a single PR's merge readiness: stacked-base detection and red/behind/conflict state with failing *required* checks surfaced. Advisory by default; `--exit-code` makes it gate for pre-merge hooks. Supports `--json`, `--repo`.
+- **`spidersan verify-trunk`** — detect (and with `--fix` reset) registry "trunk-poison": the trunk branch (main/master) claiming files in the spidersan registry, which a clean auto-merge can silently re-introduce. `--exit-code` gates for post-merge hooks; `--json` for tooling.
+- **`spidersan conflicts --real`** — compute TRUE merge conflicts via `git merge-tree` (vs registry overlap), distinguishing same-file-different-region (clean) from real conflict. Works with no registry for a single target; `--all` checks every active branch, `--base <ref>` sets trunk, `--exit-code` gates.
+
 ## [0.10.0] - 2026-05-11
 
 ### Added

package/README.md

@@ -53,13 +53,6 @@ spidersan ready-check
 npm install -g spidersan
 ```
 
-### Guided Setup (Optional)
-
-```bash
-spidersan welcome
-spidersan config wizard
-```
-
 ### Basic Usage
 
 ```bash
@@ -88,169 +81,52 @@ spidersan merge-order
 | `spidersan register --files` | Register a branch with the files being modified |
 | `spidersan list` | List all registered branches and their file ownership |
 | `spidersan conflicts` | Detect file conflicts between branches (tiered: T1/T2/T3) |
-| `spidersan conflicts --ecosystem` | Aggregate conflict scan across all repos in your dev folder |
+| `spidersan conflicts --ecosystem` | Aggregate conflict scan across the repos you configure (see [Ecosystem scan](#ecosystem-scan-repo-list)) |
+| `spidersan conflicts --real` | Compute TRUE merge conflicts via `git merge-tree` (vs registry overlap) |
 | `spidersan merge-order` | Get topologically-sorted optimal merge order |
 | `spidersan ready-check` | Verify branch is ready to merge (no WIP, no conflicts) |
-| `spidersan depends` | Set/show branch dependencies (Supabase only) |
+| `spidersan depends` | Set/show branch dependencies (deps merge first; synced cross-machine) |
 | `spidersan stale` | Find stale branches |
 | `spidersan cleanup` | Remove stale branches from registry |
-| `spidersan rescue` | Rescue mode — scan for and salvage rogue/unregistered work |
 | `spidersan abandon` | Abandon a branch (mark inactive) |
 | `spidersan merged` | Mark a branch merged |
 | `spidersan sync` | Sync registry with actual git branches |
 | `spidersan watch` | Daemon mode: watch files and auto-register |
 | `spidersan doctor` | Diagnose local state and registry health |
-| `spidersan config` | View/edit configuration + guided wizard |
-| `spidersan auto` | Auto-watch start/stop/status (config-based) |
-| `spidersan welcome` | Onboarding and quick start |
+| `spidersan config` | View/edit configuration + setup wizard |
 | `spidersan log` | Show branch operation history (local activity log) |
-| `spidersan daily` | Show branch-relevant entries from daily collab logs |
 | `spidersan rebase-helper` | Detect and guide through local git rebase states |
 | `spidersan git-watch` | Subscribe to GitHub webhook events — cross-machine push/PR/create/delete with AI conflict routing |
 
-### 🧠 AI Commands (Gemma 4 / LM Studio)
+#### Ecosystem scan repo list
 
-Ask spidersan questions about your repo state — powered by a local LLM with an embedded gitops playbook.
+`conflicts --ecosystem` ships with no built-in repo list. Pick one (first match wins):
 
-| Command | Description |
-|---------|-------------|
-| `spidersan context` | Build full repo context (registry, conflicts, colony, git) |
-| `spidersan ask "<question>"` | Ask a question — get actionable gitops advice with commands |
-| `spidersan advise` | Get proactive recommendations based on current repo state |
-| `spidersan explain <branch>` | Explain what a branch does, its risk, and next steps |
-| `spidersan ai-ping` | Test LLM connectivity and latency |
+1. `--repos /path/to/repo-a,/path/to/repo-b`
+2. `SPIDERSAN_ECOSYSTEM=/path/to/repo-a:/path/to/repo-b` (colon-separated)
+3. A config file (`~/.spidersanrc`, `.spidersanrc`, `.spidersanrc.json` or `.spidersan.config.json`):
 
-```bash
-# Get AI-powered advice
-spidersan ask "I have 3 branches touching auth.ts — what should I do?"
-
-# Proactive recommendations
-spidersan advise
-
-# Understand a mystery branch
-spidersan explain feat/strange-refactor
-
-# Flags
-spidersan context --json --verbose --repo ~/Dev/other-repo
-spidersan ask "merge strategy?" --provider copilot
-```
-
-**Features:**
-- 🏠 **Local-first**: Defaults to Gemma 4 26B on LM Studio (no API key needed)
-- 🔒 **Privacy**: Code context never leaves your machine unless you opt into remote providers
-- 📋 **18-scenario playbook**: PHC-optimized command reference covering all spidersan workflows
-- 🔧 **MCP integration**: All AI commands available as MCP tools (27 total)
-- 🧠 **Training data**: Use `/spidersan-gold` skill to mine gold pairs for fine-tuning — see [spidersan-ai](https://github.com/treebird7/spidersan-ai)
-
-### 🤖 Remote Bot (Cross-Machine Git Operations)
-
-Trigger git operations on a remote machine from any agent — no SSH needed.
-
-```bash
-# Start the bot daemon (listens for /commands via smalltoak)
-envoak vault inject --key GIT_BOT_ENABLED -- spidersan bot
-
-# One-shot: process pending commands and exit (good for cron)
-spidersan bot --once
-
-# Manage watched repos
-spidersan bot add myrepo --path ~/Dev/myrepo --branch main --push src/
-spidersan bot repos
-spidersan bot remove myrepo
+```json
+{ "conflicts": { "ecosystemRepos": ["~/code/repo-a", "/path/to/repo-b"] } }
 ```
 
-**How it works:** An agent on M2 wants to push `spidersan-ai` from M5. They send `/push spidersan-ai` via smalltoak. The bot running on M5 picks it up, executes `git push`, and replies with the result. Tier-based permissions gate which agents can trigger which operations.
+A project-level file's list replaces the global one rather than extending it. With nothing configured the scan prints a hint and checks no repos.
 
-| Command | Description |
-|---------|-------------|
-| `spidersan bot` | Start remote git ops daemon (polls smalltoak) |
-| `spidersan bot --once` | Process pending commands once and exit |
-| `spidersan bot add` | Register a repo for bot management |
-| `spidersan bot repos` | List managed repos |
-| `spidersan bot remove` | Unregister a repo |
+Plugin switches (separate from the repo list): `SPIDERSAN_CORE_ONLY=1` or `SPIDERSAN_ECOSYSTEM=0` disables the optional `spidersan-ecosystem` plugin. Neither value is read as a repo path.
 
 ### 🌐 Multi-Repo & Cloud Commands
 
 | Command | Description |
 |---------|-------------|
-| `spidersan sync-advisor` | Scan all repos and recommend push/pull/cleanup actions |
-| `spidersan registry-sync --push` | Push local branch registry to colony Supabase (share with fleet) |
+| `spidersan registry-sync --push` | Push local branch registry to the shared Supabase (share with other machines) |
 | `spidersan registry-sync --pull` | Pull other machines' registries — see what the full fleet is working on |
 | `spidersan registry-sync --status` | Show sync status across all machines |
 | `spidersan cross-conflicts` | Detect file conflicts across machines via Supabase |
 | `spidersan github-sync` | Fetch branch/PR/CI status from GitHub for configured repos |
-| `spidersan pulse` | Sync from Colony then show active conflicts (quick health-check) |
-| `spidersan pulse --remote-drift` | Fetch origin + detect remote drift zone; cross-ref against registry and unstaged files |
-
-### 📡 Remote Drift Detection
-
-`spidersan pulse --remote-drift` closes the gap between registry-level conflict detection and single-agent divergence:
-
-```bash
-# Check if origin has advanced past local HEAD
-spidersan pulse --remote-drift
-
-# Machine-readable output
-spidersan pulse --remote-drift --json
-
-# Post alert to Hub if registered or unstaged files are in the drift zone
-spidersan pulse --remote-drift --hub-sync
-
-# Exit 1 if any drift risk — use as a pre-push gate
-spidersan pulse --remote-drift --strict
-
-# As a pre-push hook:
-# .git/hooks/pre-push
-spidersan pulse --remote-drift --strict || { echo "Fetch + resolve drift first"; exit 1; }
-```
-
-**What it detects:**
-- 📥 Remote commits that local doesn't have (the *drift zone*)
-- 🟠/🔴 Registered files in the drift zone → rebase conflict risk, classified by tier
-- ⚠️ Unstaged tracked files in the drift zone → `git rebase --continue` blocker risk (even after resolving conflict markers — fix: `git checkout HEAD -- <file>`)
-
-**Graceful degradation:** offline, detached HEAD, mid-rebase, no remote branch — all print a warning and continue without exit 1.
-
-
-
-Dispatch sub-spidersans to run ground jobs across multiple repos in parallel:
-
-```bash
-# Spawn sub-spidersans for a task (generates fire-complete-dissolve scripts)
-spidersan queen spawn --task "morning sync" --type sync --repos "repo1,repo2"
-
-# Dry-run: preview scripts without emitting colony signals
-spidersan queen spawn --task "conflict scan" --type conflicts --dry-run
-
-# Monitor active sub-spidersans via the colony gradient
-spidersan queen status --queen-signal-id <id>
-
-# Manually dissolve a stuck sub-spidersan
-spidersan queen dissolve <signal-id>
-```
+| `spidersan pr-check <number>` | Check a PR's merge readiness (stacked base, red/behind state) |
+| `spidersan verify-trunk` | Detect registry trunk-poison (main/master must claim no files) |
 
-Job types: `sync` | `conflicts` | `cleanup` | `custom`
-
-### 🔄 Task Torrenting (Branch-per-Task)
-
-Create and manage parallel task branches with conflict-aware merge ordering:
-
-```bash
-spidersan torrent create DASH-001 --agent myagent
-spidersan torrent status
-spidersan torrent tree
-spidersan torrent complete DASH-001
-spidersan torrent merge-order
-spidersan torrent decompose DASH --into "DASH-A,DASH-B,DASH-C"
-```
-
-### 📊 TUI Dashboard
-
-Real-time 4-panel terminal UI — ecosystem overview, conflict map, activity feed, merge queue:
-
-```bash
-spidersan dashboard
-```
+> **Note:** `registry-sync`, `cross-conflicts`, and `git-watch` require a **`service_role`** key in `SUPABASE_KEY` — anon writes are denied by RLS. See `.env.example` for the required credential format.
 
 ### Watch Mode (Daemon)
 
@@ -260,11 +136,8 @@ Real-time file monitoring with auto-registration:
 # Start watching (auto-registers file changes)
 spidersan watch --agent myagent
 
-# With Hub integration for real-time conflict warnings
-spidersan watch --agent myagent --hub
-
 # Quiet mode (only show conflicts)
-spidersan watch --agent myagent --hub --quiet
+spidersan watch --agent myagent --quiet
 
 # Watch only specific paths
 spidersan watch --paths "src,lib" --root .
@@ -273,22 +146,11 @@ spidersan watch --paths "src,lib" --root .
 **Features:**
 - 📁 Auto-registers files when you edit them
 - ⚠️ Real-time conflict detection
-- 🔌 Hub integration for team visibility
 - 🕐 Debounced (1s) to prevent spam
 
-### ⚡ Auto Watch (Background)
-
-Run a background watcher using paths from your config:
-
-```bash
-spidersan auto start
-spidersan auto status
-spidersan auto stop
-```
-
 ### 🔔 git-watch — GitHub Webhook Notifications
 
-Cross-machine push/delete notifications via a GitHub org webhook → Supabase edge function → `spidersan_git_events` table. Each machine runs a polling daemon that reacts to events: auto-abandons deleted branches in the registry, warns to `spidersan pulse` on pushes.
+Cross-machine push/delete notifications via a GitHub org webhook → Supabase edge function → `spidersan_git_events` table. Each machine runs a polling daemon that reacts to events: auto-abandons deleted branches in the registry, warns to run `spidersan conflicts` on pushes.
 
 **Infrastructure (one-time setup):**
 
@@ -312,12 +174,12 @@ Cross-machine push/delete notifications via a GitHub org webhook → Supabase ed
 ```bash
 # One-shot catch-up (useful for cron / CI)
 SUPABASE_URL=https://<runtime-ref>.supabase.co \
-SUPABASE_KEY=<anon-key> \
+SUPABASE_KEY=<service-role-key> \
 spidersan git-watch --once
 
 # Persistent daemon (poll every 30s)
 SUPABASE_URL=https://<runtime-ref>.supabase.co \
-SUPABASE_KEY=<anon-key> \
+SUPABASE_KEY=<service-role-key> \
 spidersan git-watch --interval 30000
 ```
 
@@ -349,140 +211,37 @@ tail -f /tmp/spidersan-git-watch.log
 
 | Event | Action |
 |-------|--------|
-| `push` | Logs to `activity.jsonl`, warns to run `spidersan pulse`. Detects new gold pairs in `sql-tree/pairs/` and `ts-tree/pairs/` — emits `🌱 tree_pairs_ready` cue to `~/.spidersan/git-events-pending.jsonl` |
-| `delete` | Marks branch `abandoned` in registry, archives to `~/.spidersan/archive.jsonl` |
+| `push` | Logs to `activity.jsonl`, warns to run `spidersan conflicts`. Detects new gold pairs in `sql-tree/pairs/` and `ts-tree/pairs/` — emits `🌱 tree_pairs_ready` cue to `~/.spidersan/git-events-pending.jsonl` |
+| `delete` | Marks branch `abandoned` in the local registry, archives to `~/.spidersan/archive.jsonl` |
 | `pull_request` / `create` | Logged only |
 
-### 🤖 GitHub Actions Auto-Register
-
-**Zero-effort branch registration via GitHub workflow**
-
-When enabled, every push to a branch automatically:
-- ✅ Registers the branch with Spidersan
-- ✅ Detects changed files via git diff
-- ✅ Checks for conflicts with other branches
-- ✅ Reports TIER 2+ conflicts as workflow warnings
-- ✅ Extracts agent name from branch prefix (e.g., `claude/feature` → `claude`)
-
-**Setup:**
-1. Workflow is already included: `.github/workflows/auto-register.yml`
-2. Just push to any branch (except main/staging)
-3. View results in GitHub Actions tab
-
-**Example:**
-```bash
-git checkout -b yourname/new-feature
-git add src/api.ts
-git commit -m "feat: add new endpoint"
-git push origin yourname/new-feature
-# ✅ Auto-registered in ~15 seconds!
-```
-
-**Benefits:**
-- No manual `spidersan register` needed
-- Works across all contributors and AI agents
-- Conflict warnings appear in CI checks
-- Perfect for multi-agent repositories
-
-**Note:** This complements (doesn't replace) local `spidersan watch` for real-time file monitoring.
+### 🤖 Pushed branches register themselves
 
-**Installation:**
-- [📖 Complete Installation Guide →](./INSTALL_AUTO_REGISTER.md)
-- [🎯 Use Cases & Examples →](./AUTO_REGISTER_USE_CASES.md)
-- [🤖 Claude Code Skill →](./.claude/skills/install-auto-register.md)
+Every push to a watched repo reaches the `spidersan-webhook` edge function through
+the GitHub webhook, so a branch pushed by any tool — Codex, Copilot, a cloud agent,
+the web editor, a person — is registered in `spider_registries` and shows up in
+`conflicts` on every machine, even though no local hook ran. No GitHub Actions
+workflow, and no write credential outside Supabase.
 
-### 🦺 Rescue Mode
-
-Got a repo with 10+ abandoned branches? Let Spidersan clean up the mess:
-
-```bash
-# Scan for rogue files/branches
-spidersan rescue --scan
+Rows sit under the virtual machine `github`, files are computed against the repo's
+default branch, and a row is ignored wherever a real machine already has the same
+branch. A closed PR or a deleted branch retires it.
 
-# Salvage a file into ./salvage/
-spidersan rescue --salvage path/to/file.ts
-
-# Abandon a rogue file
-spidersan rescue --abandon path/to/file.ts
-```
-
-**Perfect for:** Post-hackathon cleanup, onboarding to chaotic repos, AI agent disasters.
+The earlier OIDC Actions workflow (`auto-register.yml` → `register-branch` edge
+function → `branch_registry`) was removed: nothing read `branch_registry`.
 
 ---
 
-## 🪝 Claude Code Hook Recipes
-
-Wire Spidersan into Claude Code's hook system so conflict checks, AI advice, and registry syncs happen **automatically** — no agent needs to remember to run them.
-
-### How it works
+## 🪝 Claude Code Plugin
 
-Claude Code's `~/.claude/settings.json` supports `PreToolUse` hooks that fire before any Bash command and can hard-block execution (returning `continue: false`) or inject context back to the model. Spidersan's `--strict` flag exits with code `1` on TIER 2+ conflicts, making it a natural hard-stop gate.
+The hooks ship as a Claude Code plugin, so checks happen **automatically** and no agent has to remember to run them:
 
-### The full recipe
-
-Add these hooks to `~/.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "jq -r '.tool_input.command // empty' | grep -qE '\\brm\\b' && jq -n '{\"continue\":false,\"stopReason\":\"🛑 rm blocked — verify paths and request explicit permission.\"}' || echo '{}'"
-          },
-          {
-            "type": "command",
-            "command": "bash -c 'cmd=$(jq -r \".tool_input.command // empty\"); if echo \"$cmd\" | grep -qE \"\\\\bgit\\\\s+push\\\\b\"; then if ! spidersan conflicts --tier 2 --strict 2>/dev/null; then jq -n \"{\\\"continue\\\":false,\\\"stopReason\\\":\\\"🕷️ Spidersan: TIER 2+ conflict detected. Run spidersan conflicts to review before pushing.\\\"}\"; exit 0; fi; advice=$(spidersan advise 2>/dev/null | head -30); [ -n \"$advice\" ] && jq -n --arg a \"$advice\" \"{\\\"hookSpecificOutput\\\":{\\\"hookEventName\\\":\\\"PreToolUse\\\",\\\"additionalContext\\\":\\\"🕷️ Spidersan pre-push advice:\\\\n\\($a)\\\"}}\" || echo \"{}\"; elif echo \"$cmd\" | grep -qE \"\\\\bgit\\\\s+(merge|rebase)\\\\b\"; then if ! spidersan conflicts --tier 3 --strict 2>/dev/null; then jq -n \"{\\\"continue\\\":false,\\\"stopReason\\\":\\\"🕷️ Spidersan: TIER 3 critical conflict detected. Run spidersan conflicts --tier 3 before merging.\\\"}\"; exit 0; fi; echo \"{}\"; else echo \"{}\"; fi'"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash -c 'cmd=$(jq -r \".tool_input.command // empty\"); echo \"$cmd\" | grep -qE \"\\\\bgit\\\\s+push\\\\b\" && spidersan registry-sync --push 2>/dev/null &; echo \"{}\"'",
-            "async": true
-          }
-        ]
-      }
-    ]
-  }
-}
 ```
-
-### What each hook does
-
-| Hook | Trigger | Action |
-|------|---------|--------|
-| `rm` guard | Any `rm` command | **Hard block** — requires explicit permission |
-| Pre-push conflict check | `git push` | Runs `spidersan conflicts --tier 2 --strict` — **hard blocks** if TIER 2+ found |
-| Pre-push AI advice | `git push` (after conflict check passes) | Runs `spidersan advise`, injects recommendations into model context |
-| Pre-merge conflict check | `git merge` / `git rebase` | Runs `spidersan conflicts --tier 3 --strict` — **hard blocks** on critical files |
-| Post-push registry sync | `git push` (success) | Runs `spidersan registry-sync --push` async — keeps fleet registry fresh |
-
-### Conflict tiers
-
-| Tier | Threshold | Example files | Gate used on |
-|------|-----------|---------------|--------------|
-| TIER 1 WARN | Low risk | `.md`, `.css`, `.json` | Not blocked |
-| TIER 2 PAUSE | Medium risk | `package.json`, migrations, types | `git push` |
-| TIER 3 BLOCK | Critical | `.env`, auth files, core lib | `git merge`, `git rebase` |
-
-### Installing
-
-```bash
-# Merge into your global settings (preserves existing config)
-cp ~/.claude/settings.json ~/.claude/settings.json.bak
-# Then add the hooks block above — or use /update-config in Claude Code
+/plugin marketplace add treebird7/spidersan-oss
+/plugin install spidersan@spidersan
 ```
 
-The hooks are global (`~/.claude/settings.json`) so they apply across all projects automatically. Every agent on the machine benefits without per-repo setup.
+It blocks force-pushes and commits that would sweep up another session's files. It also warns when two sessions share a checkout, when an edited file is registered on another branch, when a branch's PR already merged, and when a worktree holds someone else's uncommitted work. On push, merge and rebase it runs `spidersan conflicts`. See [plugin/README.md](plugin/README.md) for each hook, its requirements and the optional agent-identity settings. The plugin also adds the `/spidersan` skill.
 
 ---