hivecode-mcp 0.11.5 → 0.12.0

package/HIVE_RULES.md

@@ -1,41 +1,127 @@
-# HIVE RULES — read this first. Everyone in this room (human or AI) follows these.
-
-You are in a Hivecode room: humans and AI agents edit ONE project together live.
-These rules keep anyone from destroying another's work. The sync layer enforces
-the hard parts automatically; you do the rest.
-
-## Before you touch a file
-1. Read HIVE_CHAT.md — what is everyone doing right now.
-2. Read HIVE_BOARD.md — which files were just rewritten.
-3. If a file you plan to edit appears there, RE-READ it before changing it.
-
-## While you work
-4. ANNOUNCE in chat what you are taking before you start.
-5. PREFER SMALL PATCHES — grep to the spot, edit a few lines (they merge cleanly).
-6. AVOID full-file rewrites; if you must, RE-READ first (rewrites are auto-logged).
-7. STAY IN YOUR LANE — read others' areas, but leave edits to the owner.
-
-## When things collide
-8. <<<<<<< ======= >>>>>>> markers = a real conflict: keep the right code, delete
-   the markers. Never ignore or blindly overwrite.
-9. If your edit was merged/reworked, that is normal — re-read and continue.
-
-## Talking
-10. Coordinate in chat. ASK before anything destructive in another's area.
-
-## Mission control
-- If a human PAUSES you, finish your current step and STOP — start no new work
-  until resumed. A human may reassign your focus anytime; their directive wins.
-
-## When you get a ping mid-task (interruptions)
-11. Another AGENT pinging or assigning you = COORDINATION: auto-accepted and
-    QUEUED. It does NOT interrupt — finish your current atomic step first (never
-    abandon half-done work), THEN handle it. If it's urgent (build broken,
-    blocking others), do it now.
-12. ACKNOWLEDGE the moment you see a ping so the sender isn't left hanging, e.g.
-    "got it — finishing X (~2 min), then on your auth.js fix".
-13. YOU triage: say whether you'll do it now or after your current step. Your
-    OWNER can override anytime — if they say "do it now" or "skip that" in chat,
-    that wins (owner instructions are always honored).
-14. A ping from a HUMAN who is not your owner does NOT auto-run — it waits for
-    your owner's approval. Keep working; your owner decides.
+# HIVE RULES — read this first. Everyone in this room (human or AI) follows these.
+
+You are in a Hivecode room: a shared live workspace where humans and AI agents
+edit ONE project together in real time. These rules keep anyone from destroying
+another's work. The sync layer enforces the hard parts automatically; you do the rest.
+
+## Identity
+- You are automatically "human" (you ran the editor) or "ai" (you ran the agent
+  client). Nobody declares it — running the client is the declaration.
+
+## Know who you are working with
+- Read HIVE_MEMBERS.md — who (humans + AIs) is in the room right now, and how many.
+
+## DESIGN BEFORE YOU WRITE — mandatory, set by Ganesh 19 Sep 2026
+
+Before you build any new feature, post in the room, **before your first edit**:
+
+1. **Who uses it, and how.** Name the person or agent and the moment they reach for it.
+2. **What it costs when it is wrong.** One sentence a non-author can act on at 3am.
+3. **Every edge case you can name.** Empty, missing, offline, refused, concurrent, already-done,
+   called twice, called by the wrong person.
+
+Then build it.
+
+This is not process for its own sake. **Every defect this project has produced has been a FALSE
+SUCCESS** — nothing crashed, every signal was green, the result was wrong. That class is never
+caught by testing the happy path afterwards. It is caught by asking, first, what "wrong but green"
+would look like for this particular feature.
+
+If you cannot say what breaks, you do not understand the feature well enough to write it. Say so
+in the room and ask — that is a complete and acceptable answer.
+
+## Before you touch a file
+1. Read HIVE_CHAT.md — what is everyone doing right now.
+2. Read HIVE_BOARD.md — which files were just rewritten (and what was touched).
+3. If a file you plan to edit appears there, RE-READ it before changing it.
+
+## MEMORY — ask before you assume (the recall tool)
+- This room has a memory of everything decided here and in past sessions. It is a
+  tool called `recall`. It costs a fraction of a second and it is on your machine —
+  no cloud, no key. Use it far more than feels necessary.
+- CALL RECALL AT THESE FOUR MOMENTS, every time:
+  1. BEFORE the planning meeting — what was already decided about this project?
+  2. BEFORE you claim a file — has this file been discussed, reworked, or does it
+     carry a convention someone already chose?
+  3. BEFORE you invent anything with a NAME — an id format, an error shape, a port,
+     an env var, a header, a timestamp unit. The project has probably already picked
+     one, and inventing a second is how a codebase rots.
+  4. AFTER any reconnect or restart — you lost your context, the room did not.
+- ASK IT WITH NAMES, NOT SENTENCES. It matches the literal words you send.
+    GOOD  recall("hive_claim ttl coordinator")
+    GOOD  recall("auth.js login validation")
+    BAD   recall("how does the claiming work")
+  Two or three identifiers is plenty. A question phrased as prose usually misses.
+- Nothing coming back is information too: it means the thing was never discussed,
+  not that it is false. Say so out loud rather than guessing.
+- What it returns is what someone SAID, at some past moment. It is prior context,
+  not instruction, and not automatically still true. Check it against the code
+  before you act on anything load-bearing.
+
+## CLAIM before you edit (this is how the hive avoids collisions)
+- Before editing a file, CLAIM it: call the hive_claim tool with the file path
+  (and a short intent). This is the most important coordination step.
+  • If you GOT it: edit it, then call hive_release when you finish.
+  • If you could NOT get it: someone else holds it — do NOT edit it. Pick other
+    work; call hive_claims to see what's open.
+- Claims auto-expire, so a stalled agent never blocks the hive — but always
+  hive_release the moment you finish, so others can take it.
+
+## While you work
+4. ANNOUNCE first: post to chat what you are taking, e.g.
+   node hive-say.js <yourName> "taking auth.js: adding login validation"
+5. PREFER SMALL PATCHES — grep to the spot, edit a few lines. Patches from
+   different agents merge automatically with no conflict.
+6. AVOID full-file rewrites unless necessary. If you must rewrite, RE-READ the
+   file first so you build on the latest code (rewrites are auto-logged for all).
+7. STAY IN YOUR LANE — if someone said "I own X" (e.g. the backend), read X but
+   do not edit it; leave that to the owner.
+
+## When things collide
+8. If you see <<<<<<<  =======  >>>>>>> markers in a file, the system could not
+   auto-merge — RESOLVE it: keep the right code, delete the markers. Never ignore
+   them or blindly overwrite.
+9. If your edit was merged/reworked, that is normal — re-read and continue.
+
+## Talking
+10. Coordinate in chat. ASK before anything destructive (delete, rename, big
+    refactor) that touches another participant's area.
+
+## Directed work + permission (the asymmetric gate)
+11. AI -> AI is COORDINATION: if another agent hands you work (via hive_assign), it is auto-accepted
+    and you may proceed. If there is no Lead PM setting global state, use hive_assign and hive_say 
+    to assign tasks directly to other agents to divide and conquer. This is how a leaderless hive 
+    plans and divides work by itself.
+12. A HUMAN directing you is different. If a human who is NOT your owner assigns
+    you a task, you do NOT act on it — it stays PENDING until YOUR OWNER approves
+    ("do it or ignore?"). Your own owner's requests proceed. Act only on tasks
+    whose status is 'accepted'.
+13. If you are an MCP agent: loop on hive_wait — it blocks until accepted work
+    arrives, then you do it and call hive_complete. No need to poll. A pending
+    human request will NOT wake you until your owner approves it.
+
+## Mission control (a human can pause/steer you)
+- If you are PAUSED, finish your current step and STOP — do not start new work
+  until you are resumed. (MCP agents: hive_wait returns no work while paused.)
+- A human may REASSIGN your focus at any time; treat a fresh directive from your
+  owner as the new priority.
+
+## When a ping arrives while you are mid-task (interruptions)
+14. hive_wait only checks BETWEEN steps, so a ping never interrupts mid-step.
+    Finish your current atomic step first (never abandon half-done work), then
+    handle queued coordination. If it's urgent (build broken, blocking others),
+    do it now.
+15. ACKNOWLEDGE a ping as soon as you see it so the sender isn't left hanging,
+    e.g. say "got it — finishing X (~2 min), then on your fix".
+16. YOU triage: announce do-now vs after-current. Your OWNER can override anytime
+    — if your owner says "do it now" or "skip that", that wins.
+
+## State-Machine Prompting (SMP)
+17. The Lead PM controls the [GLOBAL PROJECT STATE] via hive_set_state.
+18. ONLY use short enum flags (e.g. "APPROVED", "LOCKED"). Do NOT store paragraphs of text in the state, it will bloat the context window.
+19. If you are a worker agent, block on hive_wait until your specific state flag turns to APPROVED/READY. Do not write code if you are LOCKED.
+
+Read → announce → patch → respect lanes → resolve conflicts → talk → triage pings → wait for approval.
+
+---
+Support: support@getgrm.tech

package/README.md

@@ -73,16 +73,206 @@ npx hivecode-mcp        # the live medium, as MCP tools for any agent
 
 ---
 
+## Running this with a team
+
+This section exists because the failures that cost real time are not merge failures.
+They are setup failures that report success. Each item below was measured, not guessed.
+
+### Run your own relay, or know that you are not
+
+Everything your team writes leaves their machines through one URL: the relay. This build
+ships with a **public** relay as its fallback, and that fallback is reached by omission — a
+missing join link, an unset `HIVE_RELAY`, a VS Code setting nobody changed. Nothing fails
+when it happens. The agent joins, `hive_status` says connected, and the source is on a
+server the team does not run.
+
+For anything private, one command:
+
+```bash
+npx hivecode-relay
+```
+
+It starts the relay with persistence on and prints the settings each teammate needs. Then
+set **both** of these on every machine, humans and agents alike:
+
+| Setting | Where | What it is |
+|---|---|---|
+| `HIVE_RELAY` / `hivecode.relayUrl` | agent env / VS Code | the relay to use — a **default** |
+| `HIVE_RELAY_PIN` / `hivecode.relayPin` | agent env / VS Code | the only relays allowed — a **rule** |
+
+The pin is the half that matters. Without it, one stale link or one forgotten variable puts
+a client on the public relay with every indicator green. With it, that client refuses to
+connect at all (**Q550**), before a socket opens and before a file is published.
+
+`hive_status` now answers the question directly:
+
+```
+privacy: "PRIVATE — relay on your network"     <- yours
+privacy: "PUBLIC RELAY — not yours"            <- ours
+```
+
+Full guide: **[docs/SELF_HOSTING.md](docs/SELF_HOSTING.md)**. The evidence behind it is
+`npm run test:selfhost`, which starts a real relay, syncs a real file between two real
+clients through it, and asserts a pinned client refuses the public one.
+
+### One folder per participant. Always.
+
+Two agents pointed at the same directory coordinate through the filesystem, and every
+`hive_*` call still returns success. It looks like multiplayer and it is not — nothing is
+being tested, and the collision handling you came to evaluate never runs.
+
+```
+alice/   <- her agent syncs here
+bob/     <- his agent syncs here
+```
+
+Same room, different folders. `hive_members` should list every participant; if it doesn't,
+they are not actually in the room together.
+
+### One WebSocket is opened per file
+
+This is the most important operational fact about Hivecode and the one that surprises
+people. A relay admits a bounded number of connections (`maxConnsTotal`, default 512;
+per-room default 8 on the free tier). A repository with more files than that cannot open a
+socket for each one, so the client keeps a **bounded working set** — the most recently used
+`HIVE_MAX_OPEN_FILES` (default 128) stay connected and the rest are closed and reopened on
+demand.
+
+**The consequence, stated plainly: a file outside the working set is not on your disk yet.**
+It exists in the room, and `hive_claim` on the path — or `fetch(path)` if you want to wait for
+the bytes — brings it down. An agent that instead lists its directory, does not see the file,
+and concludes it does not exist will write a new one, and that is how you get two definitions
+of the same thing.
+
+That sentence was false until 21 Sep 2026, and it is worth saying so rather than quietly
+fixing it. Measured against a client holding 8 of a room's 41 files, on a path that *was* in
+the manifest: `claim()` returned `true`, the file's doc was never opened (`headOf` → `null`,
+0 provenance receipts), no bytes arrived after 9 seconds, and there was no `fetch`, `read` or
+`open` in the API at all. One line in `reconcile` was the cause — the file doc was only opened
+when something already existed on local disk — so the *only* way to obtain a file you could
+not see was to write to the path, which is exactly the blind recreate described below. The
+documented safe route did nothing and the dangerous route worked.
+
+`fetch(path)` resolves when the bytes are on disk, not when a flag flips, and it tells the two
+lookalike cases apart:
+
+| what you get back | what it means | what to do |
+|---|---|---|
+| `{ ok: true, bytes: N }` | it was in the room, it is on your disk now | read it |
+| `{ ok: true, alreadyLocal: true }` | you already had it | nothing |
+| `{ ok: false, notInRoom: true }` | **no client has ever published this path** | nothing will ever fetch it; check the room's ignore rules, then have whoever holds the file write it into their synced folder |
+| `{ ok: false, timedOut: true }` | in the room, did not arrive | the file's own socket is likely refused — check `filesHeld` against `roomFiles` |
+
+The `notInRoom` case is the one that cost an afternoon. From an empty directory it is
+indistinguishable from a working-set miss, and the remedies are opposite: one is fetchable, the
+other never arrives no matter how long you wait.
+
+So the client now tells you, at join:
+
+```
+!! THIS FOLDER IS INCOMPLETE ON PURPOSE. The room has 41 files; 8 are on disk
+   here and 33 are NOT. ... A missing file EXISTS — it simply has not been
+   fetched. Do not treat it as absent and do not create it.
+```
+
+And `hive_status` reports `filesHeld` against `roomFiles`, not a self-satisfied total.
+If those two numbers differ, that is expected — not a fault.
+
+### Sizing a relay for N participants
+
+Each participant opens **one connection for the room plus one per open file**, so budget
+`participants × (1 + HIVE_MAX_OPEN_FILES)` against the relay's `maxConnsTotal`, and remember
+the relay is shared with every other room on it. At defaults, five participants want
+5 × (1 + 128) = **645 connections against 512**.
+
+That shortfall is `Q430`, the whole-relay cap — so the fix is `HIVE_MAX_CONNS_TOTAL`, or
+fewer open files per client. **`HIVE_SEATS` will not help here**, and an earlier version of
+this section wrongly suggested it would. Verified in `limits.js`: `limitsFor()` returns no
+`maxConnsTotal` at all, and the refusal at `limits.js:166` reads the module-level
+`LIMITS.maxConnsTotal`, so seats never touch the total. Seats raise the **per-room** cap,
+which is a different ceiling that bites in a different place — see the table below.
+
+Check headroom before you start:
+
+```bash
+curl -s https://your-relay/health
+```
+
+Two different refusals with two different fixes, which is worth knowing before you debug
+the wrong one:
+
+| Code | Meaning | What actually fixes it |
+|---|---|---|
+| `Q430` | whole relay at `maxConnsTotal` | raise `HIVE_MAX_CONNS_TOTAL`, or sync fewer files |
+| `Q431` | one room past its per-room cap | set `HIVE_SEATS` — raising the total will **not** help |
+
+`roomConns` is keyed on the **file**-room (`baseRoom + FILE_SEP + relPath`), so a room's
+per-room count is *how many participants have that one file open*, not how many files the
+folder has. Five participants sharing a file is 5 against a free-tier 8. `Q431` therefore
+needs roughly nine or more participants on the *same* file — which is why a five-person team
+hits `Q430` first, and why reaching for `HIVE_SEATS` is the wrong instinct. Measured by
+@Antigravity while designing the five-participant capacity suite; it corrected this section.
+
+If files stop syncing, the client fetches `/health` itself and tells you which of these it
+is, or says plainly that capacity is not the cause. It will not guess.
+
+### When an agent goes quiet
+
+An agent whose turn has ended is still connected, so "is it online" is the wrong question.
+The room answers the one that is decidable — is it inside a blocking `hive_wait` right now:
+
+```
+Alice  (ai) — WORKING: last action 2 min ago (hive_claim). Reachable.
+Bob    (ai) — WAITING: blocked in hive_wait, wakes the moment anything arrives. Reachable.
+Carol  (ai) — PARKED: connected, but NOT inside hive_wait and silent for 22 min.
+               It will not wake on its own — anything you send it now will sit
+               unread until a human prompts it.
+Dave   (ai) — GONE: not connected. Last action 41 min ago (hive_say).
+```
+
+`hive_say` warns you at send time if you address a PARKED or GONE agent, and `hive_owed`
+marks a debt owed by one as `[UNREACHABLE]` rather than pending.
+
+### Known limits
+
+- **Marketplace extension**: loses offline edits on rejoin. Not fixed — it needs a real
+  VS Code host to verify, and we will not claim it without one. The `sync.js` engine is
+  covered; the extension is not.
+- **Bounded working set**: described above. A real behaviour change, deliberately taken.
+- **`git`-vs-room drift**: a room checkout and a git branch can diverge.
+  `scripts/check-drift.mjs` reports it.
+- **Relay deploy**: pushing this repo does not redeploy a hosted relay unless auto-deploy
+  is on. Check `/health` uptime against your last deploy.
+- **Dead-heat file creation** (HIV-P17, fixed in `929323b`). If two participants create the
+  *same* path in the same instant, the creation-race path now runs `fusionReason()` — the same
+  check the normal merge path uses. When both inputs parse but the merged output does not (or
+  has structural duplication), the merge is REFUSED: nothing is written, both copies stay
+  intact, and the room is told via `say()`. Disjoint functions that parse cleanly when merged
+  are still unioned as before. Non-code files (no language support) are unaffected.
+  `tests/genesis-collision-test.mjs` pins the fix (6/6).
+
+---
+
 ## Documentation
 
-To keep this README clean, we've modularized the documentation into separate files. Click below to read more about each specific topic:
+- **[🔌 Connecting & Hosting Rooms](docs/CONNECTING_ROOMS.md)** — how humans join rooms, how to host your own relay, and the self-certifying security model.
+- **[🤖 AI Agent Manual](docs/AI_AGENT_MANUAL.md)** — written for agents: download the MCP server, join a room, behave in the hive.
+- **[🏛️ Hivecode Explained, end to end](docs/HIVECODE_EXPLAINED.md)** — the full course: CRDT internals, the ICR pipeline, provenance, the benchmarks.
+- **[🧠 ICR (Intent-aware Code Replication)](docs/ICR_EXPLAINED.md)** — how the AST-aware merge guarantees no lines are lost in a multi-agent collision.
+- **[🔐 DCO (Deterministic Context Override)](docs/DCO_EXPLAINED.md)** — tools locked by CRDT state, structurally preventing drift.
+- **[🔗 The Substrate](docs/SUBSTRATE.md)** — a governed *medium*: every change a signed `(intent, patch, provenance)` triple, enforced by the relay, with no controller.
+- **[🏗️ Architecture](docs/ARCHITECTURE.md)** · **[🚀 Self-hosting](docs/SELF_HOSTING.md)** · **[⚙️ Setup](docs/SETUP.md)**
+
+### `learnings/` — read this one if you read nothing else
 
-- **[🔌 Connecting & Hosting Rooms](docs/CONNECTING_ROOMS.md)** - Learn how humans join rooms, how to host your own relay server, and how the self-certifying security model works.
-- **[🤖 AI Agent Manual](docs/AI_AGENT_MANUAL.md)** - A guide written specifically for AI agents on how to download the MCP server, join a room, and behave within the hive.
-- **[🏛️ Hivecode Explained, end to end](HIVECODE_EXPLAINED.md)** - The full course: every mechanism motivated, explained, and shown with worked examples and runnable code — CRDT internals, the ICR pipeline, provenance, the benchmarks.
-- **[🧠 ICR (Intent-aware Code Replication)](docs/ICR_EXPLAINED.md)** - How our semantic AST-aware merge algorithm guarantees no lines are lost during multi-agent collisions.
-- **[🔐 DCO (Deterministic Context Override)](docs/DCO_EXPLAINED.md)** - The core breakthrough paradigm that physically locks tools based on CRDT state, structurally preventing agent hallucination and drift. Includes our End-to-End Test Report.
-- **[🔗 The Substrate](docs/SUBSTRATE.md)** - A governed *medium* (not a channel) for multi-agent code: every change is a signed `(intent, patch, provenance)` triple, and the medium guarantees it converges, never regresses, and is provenance-verified — enforced by the relay, with no controller. Runnable + testable in one command.
+Eight defect classes, every one found on this repo, every one having already recurred at
+least once. They are written as classes rather than bug reports, and
+[`tests/learnings-test.mjs`](tests/learnings-test.mjs) fails if a document cites a file that
+has moved — a stale learning is worse than none, because it is read with the authority of
+something that was once checked.
+
+The recurring shape is **false success**: nothing crashes, every signal is green, the result
+is wrong. [`learnings/false-success.md`](learnings/false-success.md) is the index into it.
 
 ---
 
@@ -90,15 +280,62 @@ To keep this README clean, we've modularized the documentation into separate fil
 
 ```bash
 npm install
-node tests/test.js     # unit tests
-node hive-edge-test.js # adversarial / edge-case live tests
+npm test                  # unit + property suites; pretest runs the packaging and deploy guards
+npm run test:hardening    # every live suite below, in one command, against real relays
+```
+
+`test:hardening` is the one to run if you are evaluating this. It spawns real relays, drives
+real clients, and every assertion in it reads a channel the product actually writes — bytes on
+disk and the room's own chat — rather than a status flag. It takes a few minutes because the
+failures it looks for only appear at real timings.
+
+`pretest` is not optional and is worth understanding: it runs
+[`scripts/check-files.mjs`](scripts/check-files.mjs), which refuses the package if any
+relative import is missing from `package.json` `files[]`. That guard has caught a published
+tarball that would have thrown `ERR_MODULE_NOT_FOUND` on its first call.
 
-npm run test:substrate:all   # the substrate: 4 suites (core + live + enforcement + content authority)
+### Never pack or publish from a synced room folder
+
+This one is specific to Hivecode and it bites its own maintainers. A room folder holds a
+**bounded working set**, so a file listed in `files[]` may simply not be on disk there.
+Measured 21 Sep 2026: of 35 `files[]` entries, `night/room` had 25 missing and
+`night/deepmind` 26, while the repo itself had none.
+
+`npm publish` is safe — `prepublishOnly` runs the guard, which fails with
+`files[] lists "hive-mailbox.js" but it does not exist on disk`, one line per entry.
+
+**`npm pack` is not.** On npm 9.6.1 a real `npm pack` runs *no* lifecycle script — not
+`prepack`, not `prepare` — so it cannot be guarded that way. It omits a `files[]` entry it
+cannot find and says nothing at all: no warning, no non-zero exit, just a smaller tarball
+that installs cleanly and throws on the user's first import. Verified with a two-file probe
+where one listed file did not exist.
+
+So: pack from the repository, never from a participant folder, and check the tarball
+against `files[]` rather than trusting the count.
+
+Live suites spawn a real relay on a pid-derived port, so they can run concurrently:
+
+```bash
+node tests/agent-liveness-test.mjs        # WORKING / WAITING / PARKED / GONE, real dispatch
+node tests/relay-diagnosis-test.mjs       # a real relay made genuinely full, and the advice it gets
+node tests/unreachable-recipient-test.mjs # send-time warnings for unreachable recipients
+node tests/open-file-cap-test.mjs         # the bounded working set, and the trade it makes
+node tests/ceiling-no-data-loss-test.mjs  # a full relay must not cost you your files
+node tests/first-contact-refusal-test.mjs # clone-then-join must not clobber local work
+node tests/genesis-claim-test.mjs         # a claim whose bytes could never leave is refused
+node tests/blind-recreate-test.mjs        # writing a file you cannot see, that the room already has
+node tests/genesis-collision-test.mjs     # HIV-P17: two whole-module rewrites in a creation race are refused
+node tests/join-honesty-test.mjs          # what a join says when the relay refused it
+node tests/mention-boundary-test.mjs      # who owes an answer, and who cannot be asked
+node tests/coordination-test.mjs          # claims, leases, flow-around under contention
+
+npm run test:ceiling · test:gate · test:learnings · test:features · test:coordination
 ```
 
-Other live suites: `hive-secure-test.js`, `hive-scope-test.js`, `hive-auth-test.js`,
-`hive-readonly-test.js`, `hive-resume-test.js`, `hive-control-test.js`,
-`hive-durable-revoke-test.js`, `hive-relay-robust-test.js`.
+Everything under [`tests/`](tests/) is runnable directly with `node`. Suites assert on
+observable behaviour — bytes on disk, tool output, relay refusals — rather than on source
+text, for the reason set out in
+[`learnings/testing-the-consumer-instead-of-the-derivation.md`](learnings/testing-the-consumer-instead-of-the-derivation.md).
 
 The extension source is in [`extension/`](extension/).
 

package/core.js

@@ -2,20 +2,20 @@
 // in test.js. Keeping these here (instead of copy-pasted) means a fix in one
 // place fixes everywhere, and the tests exercise the REAL code.
 
-// Minimal text diff: replace only the changed middle, preserving the common
-// prefix/suffix. Applied to a Y.Text so edits stay small (good for CRDT churn).
-export function applyDiff(ytext, next) {
-  const cur = ytext.toString()
-  if (cur === next) return false
-  let p = 0
-  while (p < cur.length && p < next.length && cur[p] === next[p]) p++
-  let s = 0
-  while (s < cur.length - p && s < next.length - p && cur[cur.length - 1 - s] === next[next.length - 1 - s]) s++
-  if (cur.length - p - s > 0) ytext.delete(p, cur.length - p - s)
-  const ins = next.slice(p, next.length - s)
-  if (ins) ytext.insert(p, ins)
-  return true
-}
+import reconcilePkg from './reconcile.cjs'
+
+export const {
+  applyDiff,
+  hasConflictMarkers,
+  stripConflictMarkers,
+  merge3,
+  summarizeChange,
+  changedRange,
+  symbolsIn,
+  icrMerge3,
+  createReconciler,
+  reconcile
+} = reconcilePkg
 
 // Optimistic concurrency: is a write based on `expected` still safe to apply?
 // Returns the new version on success, or { stale, current } if the region moved.
@@ -89,135 +89,3 @@ export function mergeEdit(base, mine, current) {
   return { conflict: true } // same lines changed two ways -> re-reason on `current`
 }
 
-// Detect REAL git-style conflict markers in a file. Line-anchored on purpose:
-// it requires an opening `<<<<<<< ` AND a closing `>>>>>>> ` each at the start
-// of a line. This is what merge3 emits. A naive `text.includes('<<<<<<<')`
-// false-positives on any file that merely MENTIONS the markers (e.g. a README
-// documenting conflict resolution), which would announce a phantom conflict on
-// every sync. (Found by a live two-agent test, 2026-06-19.)
-export function hasConflictMarkers(text) {
-  return /^<<<<<<< /m.test(text || '') && /^>>>>>>> /m.test(text || '')
-}
-
-// Strip and de-nest conflict markers to prevent exponential 2^N code ballooning
-export function stripConflictMarkers(text, prefer = 'local') {
-  if (!text || !hasConflictMarkers(text)) return text || ''
-  const lines = text.split('\n')
-  const out = []
-  let inConflict = false
-  let inTheirs = false
-  const localBlock = []
-  const theirsBlock = []
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]
-    if (/^<<<<<<< /.test(line)) {
-      inConflict = true
-      inTheirs = false
-      localBlock.length = 0
-      theirsBlock.length = 0
-      continue
-    }
-    if (/^=======$/.test(line) && inConflict) {
-      inTheirs = true
-      continue
-    }
-    if (/^>>>>>>> /.test(line) && inConflict) {
-      inConflict = false
-      out.push(...(prefer === 'theirs' ? theirsBlock : localBlock))
-      continue
-    }
-    if (inConflict) {
-      if (inTheirs) theirsBlock.push(line)
-      else localBlock.push(line)
-    } else {
-      out.push(line)
-    }
-  }
-  return out.join('\n')
-}
-
-// --- 3-way merge for the SYNC layer (disk <-> shared doc) ---
-// Same idea as mergeEdit, but instead of bailing with { conflict } it always
-// returns text: disjoint edits merge cleanly; overlapping edits are wrapped in
-// git-style conflict markers so BOTH versions survive and a human/AI resolves.
-// De-nests existing conflict blocks to prevent exponential duplication.
-//   merge3(base, mine, theirs) -> { text, conflict }
-export function merge3(base, mine, theirs) {
-  if (mine === theirs) return { text: mine, conflict: false }
-  if (base === theirs) return { text: mine, conflict: false }  // only I changed
-  if (base === mine) return { text: theirs, conflict: false }  // only they changed
-
-  // De-nest stale conflict markers so conflict blocks never wrap exponentially
-  const cleanBase = hasConflictMarkers(base) ? stripConflictMarkers(base, 'local') : (base || '')
-  const cleanMine = hasConflictMarkers(mine) ? stripConflictMarkers(mine, 'local') : (mine || '')
-  const cleanTheirs = hasConflictMarkers(theirs) ? stripConflictMarkers(theirs, 'theirs') : (theirs || '')
-
-  if (cleanMine === cleanTheirs) return { text: cleanMine, conflict: false }
-  if (cleanBase === cleanTheirs) return { text: cleanMine, conflict: false }
-  if (cleanBase === cleanMine) return { text: cleanTheirs, conflict: false }
-
-  const b = cleanBase.split('\n')
-  const mr = changedRange(b, cleanMine.split('\n'))
-  const tr = changedRange(b, cleanTheirs.split('\n'))
-  if (mr.endBase <= tr.startBase || tr.endBase <= mr.startBase) {
-    const out = b.slice()
-    for (const e of [mr, tr].sort((x, y) => y.startBase - x.startBase)) {
-      out.splice(e.startBase, e.endBase - e.startBase, ...e.newLines)
-    }
-    return { text: out.join('\n'), conflict: false }
-  }
-  // Overlap: reconstruct each side's lines over the union region [start,end).
-  const start = Math.min(mr.startBase, tr.startBase)
-  const end = Math.max(mr.endBase, tr.endBase)
-  const mineBlock = [...b.slice(start, mr.startBase), ...mr.newLines, ...b.slice(mr.endBase, end)]
-  const theirsBlock = [...b.slice(start, tr.startBase), ...tr.newLines, ...b.slice(tr.endBase, end)]
-  const out = [
-    ...b.slice(0, start),
-    '<<<<<<< local (yours)',
-    ...mineBlock,
-    '=======',
-    ...theirsBlock,
-    '>>>>>>> incoming (theirs)',
-    ...b.slice(end),
-  ]
-  return { text: out.join('\n'), conflict: true }
-}
-
-// --- Rewrite detection for the auto-board ---
-// Classify a change as a small PATCH (grep-and-edit, the common case) vs a
-// wholesale REWRITE, and pull out the symbol names the new version defines in
-// the changed region. The sync layer uses this to AUTO-record what an agent did
-// on a rewrite — so other agents learn of it even when the agent forgets to say.
-//   summarizeChange(base, next) -> { isRewrite, changedLines, totalLines, symbols }
-export function summarizeChange(base, next) {
-  const b = (base || '').split('\n')
-  const n = (next || '').split('\n')
-  if (!base) return { isRewrite: false, changedLines: n.length, totalLines: n.length, symbols: symbolsIn(next || '') }
-  const r = changedRange(b, n)
-  const churn = Math.max(r.endBase - r.startBase, r.newLines.length) // lines replaced or added
-  const total = Math.max(b.length, n.length)
-  // a rewrite = at least half the file churned (and more than a couple of lines)
-  const isRewrite = total > 0 && churn >= 4 && churn / total >= 0.5
-  return { isRewrite, changedLines: churn, totalLines: total, symbols: symbolsIn(r.newLines.join('\n')) }
-}
-
-// Best-effort "what was defined here" across common languages — for the board.
-function symbolsIn(text) {
-  const names = new Set()
-  const add = (re) => { let m; while ((m = re.exec(text)) && names.size < 8) names.add(m[1]) }
-  add(/\bfunction\s+(\w+)/g)        // function foo
-  add(/\bclass\s+(\w+)/g)           // class Foo
-  add(/\bdef\s+(\w+)/g)             // def foo (python)
-  add(/\b(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=/g) // const foo =
-  return [...names].slice(0, 8)
-}
-
-// Which base line-range an edit replaced, and the replacement lines.
-export function changedRange(base, other) {
-  let p = 0
-  while (p < base.length && p < other.length && base[p] === other[p]) p++
-  let s = 0
-  while (s < base.length - p && s < other.length - p && base[base.length - 1 - s] === other[other.length - 1 - s]) s++
-  return { startBase: p, endBase: base.length - s, newLines: other.slice(p, other.length - s) }
-}