relaybrain 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Relay contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,291 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![Relay](./logo.png)
+
+### GitHub Desktop for AI agents.
+
+*Git coordinates humans committing minutes apart. **Relay coordinates agents editing the same files right now** — file locks, dependency-aware locks, live patch sync, and one shared board.*
+
+**Twelve agents on one repo, and none of them blind to the others.**
+
+[**Watch the demo**](https://youtu.be/vUea5Qih-nM) · [**Read the Documentation**](https://relay-brain.vercel.app/docs.html) · [**Docs in this repo**](./docs/README.md)
+
+<br/>
+
+<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A520-3c873a?style=for-the-badge&logo=node.js&logoColor=white" alt="Node 20+"></a>
+<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2563eb?style=for-the-badge" alt="MIT"></a>
+<img src="https://img.shields.io/badge/memory-FalkorDB%20graph-dc2626?style=for-the-badge" alt="FalkorDB memory graph">
+<img src="https://img.shields.io/badge/login-not%20required-16a34a?style=for-the-badge" alt="No login">
+
+<br/>
+<br/>
+
+**Works with**
+
+<p align="center">
+  <img src="./support_images/readme/cursor.png" alt="Cursor" height="46" />
+  <img src="./support_images/readme/claude.png" alt="Claude Code" height="46" />
+  <img src="./support_images/readme/copilot.png" alt="GitHub Copilot" height="46" />
+  <br />
+  <img src="./support_images/readme/codex.png" alt="Codex" height="46" />
+  <img src="./support_images/readme/antigravity.png" alt="Google Antigravity" height="46" />
+</p>
+
+</div>
+
+## The problem
+
+Eighteen months ago you had **one** coding assistant. Today you probably have **three running at once** — Claude in one terminal, Cursor in another, Copilot in the editor. They all write to the same files, and not one of them knows the others exist.
+
+Now put **four people** on that repo. That's **twelve agents**, editing the same code, blind to each other. You find out at the merge. Or you don't find out at all.
+
+Git solved this for humans — but Git assumes people committing at human speed, minutes apart, one branch each. **Agents write at machine speed, in parallel, in the same directory.** There is no layer for that.
+
+## The fix
+
+```diff
+- 12 agents · 12 blind writers · conflicts discovered at merge
++ 12 agents · 1 lock table · conflicts prevented at the edit
+```
+
+Relay sits under every agent as a **coordination layer**. Pre-tool hooks claim a lock before an agent writes; post-tool hooks release it. If one agent is modifying a component, another **cannot silently overwrite** those changes.
+
+> **One host, no backend.** One person runs `relay serve` — that machine *is* the server. Teammates connect over a fast tunnel (Cloudflare Quick Tunnel, Tailscale Funnel, custom host URL, or ngrok), straight to that laptop. Nothing lives on infrastructure you do not own.
+
+<div align="center">
+
+![Relay Demo](./screenRec.gif)
+
+**[Watch the full demo on YouTube](https://youtu.be/vUea5Qih-nM)**
+
+</div>
+
+## The four pillars
+
+| | What it does |
+|---|---|
+| **File locking** | Every agent write goes through a claim/release cycle against a shared lock table (TTL-based, auto-expiring). Destructive overwrites are blocked, not detected after the fact. |
+| **Dependency-graph locking** | Files do not exist independently — one change can affect dozens. Relay parses imports with tree-sitter and asks *"does this change affect files another agent is working on?"*, not just *"is this exact file locked?"* Agents stay parallel; the blast radius stays safe. |
+| **Patch sync across machines** | Your teammate has their own filesystem, environment, and agents. Relay propagates **patches**, not whole-project copies — `relay push` / `relay pull` keep every clone on the same working state. |
+| **Mission Control** | One board for every agent on every machine: live lock table, lock graph, code edits, unified agent chat history, conflicts, presence. |
+| **Memory graph (FalkorDB)** | Every agent, session, prompt, edit, block and decision across machines, as one graph. Agents get it *before* they act (`relay_session_brief`), and *at the moment of conflict*: a denied lock says what the holder is working on. |
+
+## Memory graph: built for Graph Hacks (FalkorDB)
+
+Locks stop two agents writing the same file at once. They don't tell the second agent **why** the file is taken, **what was decided** about it, or **which prompt** made it look the way it does. Before this, relay's memory was flat JSON, capped at 2,000 events, with nothing connected.
+
+Now every agent turn, edit, lock claim, block, decision and teammate's activity flows into a **FalkorDB graph per project**:
+
+```
+Person → Agent → Session → Turn
+                    └─ MADE → Edit ─ MODIFIED → File ← ON ─ Contention ─ HELD_BY → Session (its intent)
+                               └─ PROMPTED_BY → the user request behind the change
+File ─ CO_EDITED → File   (PageRank = hotspots, label propagation = work areas)
+```
+
+- **Explainable by default.** Every edit links to the user request that caused it, inferred from transcripts. "continue" and "yes" are skipped in favor of the real request, so no agent has to report anything.
+- **Context at the conflict.** *"File `src/auth.ts` is locked by Claude Code… They're working on: "switch the login flow to JWT tokens" (2 min ago)."*
+- **Context before acting.** `relay_session_brief(paths)` hands any agent (Claude Code, Cursor, Codex, Copilot, Antigravity) who is on those files now and why, past blocks, decisions, the prompts behind recent changes, and who to ask.
+- **Graph algorithms as agent tools.** PageRank and label propagation over co-edited files find coordination hotspots and work areas. `relay_graph_query` exposes 10 named Cypher queries. Every answer ships with its Cypher.
+- **Shared across the room.** The host's graph is the room's memory. Guests query it over the existing tunnel, even without FalkorDB installed.
+- **Safe to add.** Single writer, idempotent `MERGE`s, a circuit breaker, and a full fail-open path: with the graph off, relay behaves exactly as before.
+
+```bash
+relay graph up        # FalkorDB in Docker
+relay graph enable    # save the URL; switches a running relay on
+relay serve           # Mission Control → Memory Graph tab
+```
+
+Full setup (Windows/macOS/Linux, hosted FalkorDB, troubleshooting): [docs/MEMORY-GRAPH.md → Setup](./docs/MEMORY-GRAPH.md#setup) · [Engineering Blog Post: From Flat JSON to a FalkorDB Memory Graph](./docs/BLOG-POST.md).
+
+## Quick start
+
+**Install** (Node 20+):
+
+```bash
+npm install -g relaybrain   # installs the `relay` CLI with Mission Control prebuilt
+relay graph up              # optional: FalkorDB memory graph in Docker
+relay graph enable
+```
+
+**Host** — the machine everyone else connects to:
+
+```bash
+relay login              # GitHub identity (uses the gh CLI)
+relay clone <repo-url>   # clone + register workspace + install agent hooks
+relay serve              # npm install: everything on :3001 · source checkout: Mission Control on :3002
+```
+
+Then open Mission Control → **Team → Share** to start a tunnel (Cloudflare Quick Tunnel / Tailscale Funnel / custom URL) and mint the invite link.
+
+**Teammate:**
+
+```bash
+relay serve              # their own local relay
+# join with the host's invite link on the Team tab
+relay pull               # take the host's current working state
+```
+
+Now start agents as usual. Hooks claim and release locks automatically — nobody has to remember a command.
+
+<details>
+<summary><strong>Install options</strong></summary>
+
+<br/>
+
+| Method | Command |
+|--------|---------|
+| npm | `npm install -g relaybrain` |
+| local dev | `npm i`, then `npm link` in this repo |
+| attach an existing repo | `relay add /path/to/repo` |
+| fresh clone | `relay clone <url> [dir]` |
+
+Requires **Node.js 20+**. No hosted backend, no login server. The memory graph needs FalkorDB (`relay graph up`, Docker); without it, relay runs on files alone.
+
+</details>
+
+## How it works
+
+```text
+  Cursor ──┐  pre-tool hook: claim
+  Claude ──┤  post-tool hook: release      ┌──────────────┐
+  Copilot ─┼──► lock table ◄── dep graph ──│ relay serve  │──► Mission Control
+  Codex ───┤        ▲                      │  (your host) │          ▲
+  Antigravity ┘     │                      └──────┬───────┘          │
+                    │       ngrok tunnel          │                  │
+              teammate's relay ◄──── patches ─────┴──────────────────┘
+```
+
+| Layer | Who runs it | What it guards |
+|-------|-------------|----------------|
+| **Claim / release** | pre- and post-tool hooks | exclusive write access to a file |
+| **Dependency graph** | tree-sitter import scan | files *affected by* the edit, not just the edit |
+| **Room** | `relay serve` + tunnel (Cloudflare / Tailscale / custom) | one shared lock table across machines |
+| **Patches** | `relay push` / `relay pull` | working-tree state without full copies |
+| **Board** | Mission Control (:3002) | who holds what, right now |
+
+> Locks and the board are separate subsystems — hooks arbitrate straight against the host, while the board is fed by a mirror. `relay doctor` walks that chain and tells you which link is broken.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `relay login` / `logout` / `whoami` | GitHub identity (via `gh` CLI, or device flow with `GITHUB_CLIENT_ID`) |
+| `relay clone <url> [dir]` | git clone + register workspace + install agent hooks |
+| `relay add <path>` | Attach an existing local repo |
+| `relay init [path]` | Wire hooks, Relay MCP, and `/relay ask` instructions for all agents |
+| `relay serve` | API on `127.0.0.1:3001` + Mission Control on `:3002` |
+| `relay serve --no-ui` | API + coordinator only |
+| `relay push` | Send your dirty working-tree files to the shared room |
+| `relay pull` | Apply the host's current dirty files onto this clone |
+| `relay status` | Health check (room, role, host, ports) |
+| `relay mcp-url` | Print the MCP config for this room's shared-context endpoint |
+| `relay doctor` | Diagnose an empty Coordinator board |
+
+## Mission Control
+
+Started by `relay serve` — runs on your own machine, no hosted account.
+
+| | URL |
+|---|-----|
+| Dashboard | http://localhost:3002 |
+| API | http://127.0.0.1:3001/api/health |
+
+**Collisions prevented counter** (persisted to `~/.relay/data/projects/<id>/collisions.json` and mirrored to `<repo>/.relay/collisions.json`).
+
+## MCP — shared room context
+
+Any MCP client can read the room's context, **even on a machine with no relay installed**:
+
+```bash
+relay mcp-url    # prints a ready-to-paste mcpServers block
+```
+
+Coordination tools (`relay_claim_file`, `relay_release_file`, `relay_status`) run against each member's own local relay. The room endpoint is **read-only** for anyone off the host machine.
+
+<details>
+<summary><strong>Tools exposed</strong></summary>
+
+<br/>
+
+| Tool | Purpose |
+|------|---------|
+| `relay_claim_file` | Acquire an exclusive write lock before editing |
+| `relay_release_file` | Release the lock after editing |
+| `relay_status` | View the full lock table |
+| `relay_get_conflicts` | Overlapping edits in the last 5 minutes |
+| `relay_get_recent_changes` | Recent `code_edit` events |
+| `relay_get_chat_history` | Unified agent chat across every room member |
+| `relay_room_brief` | Teammate activity brief (for the `/relay ask` agent pseudo-command) |
+| `relay_get_collision_stats` | Lifetime counters for collisions Relay prevented |
+| `relay_session_brief` | Memory-graph brief for files you're about to touch: who's on them now and why, blocks, decisions, prompts behind changes |
+| `relay_graph_query` | Named Cypher queries over the FalkorDB memory graph (`file_story`, `who_to_ask`, `contention_trace`, `search_memory`, `hotspots`, …) |
+| `relay_report_change` | Push a code-change event |
+| `relay_report_decision` / `relay_get_decisions` | Append / read decisions |
+| `relay_update_task` / `relay_get_active_tasks` | Append / read tasks |
+| `relay_get_project_context` | Full JSON project context |
+| `relay_sync` | Re-read agent transcripts into unified history |
+
+</details>
+
+## Hooks
+
+`relay clone` / `relay add` / `relay init` install pre-tool (**claim**), post-tool (**release**), pre-read, stop hooks, **Relay MCP** (`relay_room_brief` for `/relay ask`), and the relay-os instruction block into every agent surface:
+
+| Agent | Hooks | Instructions | Relay MCP (`relay_room_brief`) |
+|-------|--------|--------------|--------------------------------|
+| Claude Code | `.claude/settings.json` | `CLAUDE.md` | `.claude/settings.json` → `mcpServers.relay` |
+| Cursor | `.cursor/hooks.json` | `.cursor/rules/relay.mdc`, `AGENTS.md` | `.cursor/mcp.json` |
+| Codex | `.codex/hooks.json` | `AGENTS.md` | `.codex/config.toml` → `[mcp_servers.relay]` |
+| Copilot CLI | `.github/hooks/relay-os.json` | `.github/copilot-instructions.md` | `.github/mcp.json` |
+| Antigravity | `.agents/hooks.json` | `AGENTS.md` | `.agents/mcp_config.json` |
+
+Languages parsed for the dependency graph: TypeScript/JavaScript, Python, Go, Rust, Java, C#, C/C++, PHP, Ruby.
+
+## Dependencies
+
+| | |
+|---|---|
+| **Required** | Node.js 20+, npm |
+| **Bundled** | `express`, `cors`, `ws`, `@vscode/tree-sitter-wasm` · `next`, `react` (Mission Control) |
+| **Not needed** | MongoDB, Redis, Docker, a hosted backend, an account |
+| **Optional** | `gh` CLI for `relay login` · `cloudflared` / Tailscale Funnel / ngrok for cross-machine rooms · Docker or FalkorDB Cloud for the memory graph |
+
+**Env vars:** `RELAY_PORT` (3001) · `RELAY_UI_PORT` (3002) · `RELAY_UI_ORIGIN` · `RELAY_TUNNEL` (`cloudflared`\|`tailscale`\|`ngrok`) · `RELAY_PUBLIC_URL` · `RELAY_PUBLIC_READONLY`
+
+## Documentation
+
+Full documentation lives in [`docs/`](./docs/README.md).
+
+| | |
+|---|---|
+| [Quickstart](./docs/QUICKSTART.md) | Coordinating in about five minutes |
+| [Installation](./docs/INSTALLATION.md) | Requirements, install methods, what gets written where |
+| [Concepts](./docs/CONCEPTS.md) | Workspace, project, agent ID, lock, room, patch |
+| [Rooms and teams](./docs/ROOMS.md) | Hosting, invites, member tokens, joining, leaving |
+| [Architecture](./docs/ARCHITECTURE.md) | Process model, the two planes, one edit end to end |
+| [Locking](./docs/LOCKING.md) | The lock table, TTLs, ownership, dependency-graph soft locks |
+| [Sync and patches](./docs/SYNC.md) | Patch format, Lamport ordering, transform, transcripts |
+| [CLI reference](./docs/CLI.md) | Every command, flag and exit code |
+| [HTTP API reference](./docs/HTTP-API.md) | Every endpoint, with auth rules |
+| [MCP reference](./docs/MCP.md) | The seventeen tools and the read-only room endpoint |
+| [Hooks reference](./docs/HOOKS.md) | The hook contract per agent |
+| [Configuration](./docs/CONFIGURATION.md) | Environment variables, ports, on-disk layout |
+| [Troubleshooting](./docs/TROUBLESHOOTING.md) | `relay doctor` and the known failure modes |
+| [Memory graph](./docs/MEMORY-GRAPH.md) | FalkorDB graph model, queries, algorithms, migrations & retention |
+| [Blog post](./docs/BLOG-POST.md) | From flat JSON to a FalkorDB memory graph for AI coding agents |
+
+## Roadmap
+
+- **Git worktree isolation** — every agent in its own workspace off the same repository, free to experiment and test independently, integrated back into main when the work is ready.
+- Richer conflict resolution on top of the existing OT / patch layer.
+
+<div align="center">
+
+**We used Relay to build Relay.** The problem we were solving was the problem we were having.
+
+The next time you build a hackathon project, do not just add more agents. **Just relay.it**
+
+<sub>MIT licensed · Your machine is the server.</sub>
+
+</div>

package/backend/coordinator/client.js

@@ -0,0 +1,364 @@
+const fs = require("fs");
+const http = require("http");
+const path = require("path");
+const { coordinatorStatePath } = require("../lib/paths");
+const { loadRoom } = require("../lib/room");
+
+const TOTAL_BUDGET_MS = 3000;
+const HTTP_TIMEOUT_MS = 2000;
+
+function readState(workspacePath) {
+  const files = [coordinatorStatePath(workspacePath), coordinatorStatePath(null)];
+  for (const file of files) {
+    try {
+      const state = JSON.parse(fs.readFileSync(file, "utf8"));
+      if (state.port || state.apiPort) return state;
+    } catch {
+      /* next */
+    }
+  }
+  return null;
+}
+
+function readPort(workspacePath) {
+  const state = readState(workspacePath);
+  return state?.port ? Number(state.port) : null;
+}
+
+// The API server owns the same in-memory lock table the dashboard renders, and
+// its port is fixed, so it is the one target that cannot go stale. The
+// coordinator's port is ephemeral and its state file is trusted blindly by
+// readPort — a `relay serve` that dies after binding the coordinator but before
+// binding the API leaves a pointer to a dead port behind.
+function apiPort(workspacePath) {
+  if (process.env.RELAY_PORT) return Number(process.env.RELAY_PORT);
+  const state = readState(workspacePath);
+  return Number(state?.apiPort) || 3001;
+}
+
+// A room whose host has gone away (closed laptop, expired tunnel) otherwise
+// costs every hook a full HTTP timeout on each of claim/heartbeat/release, which
+// reads to the user as "the agent froze".
+const ROOM_COOLDOWN_MS = 30_000;
+const roomFailedAt = new Map();
+
+// Only a guest talks to the room. The host *is* the coordinator: routing its own
+// hooks out through its ngrok tunnel and back adds a full internet round trip to
+// every claim, and stalls the agent whenever the tunnel hiccups.
+function roomUsable(room) {
+  if (!room?.url || room.role !== "guest") return false;
+  const failed = roomFailedAt.get(room.url);
+  return !failed || Date.now() - failed > ROOM_COOLDOWN_MS;
+}
+
+function markRoomDown(room) {
+  if (room?.url) roomFailedAt.set(room.url, Date.now());
+}
+
+// The lock table namespaces every lock by absolute workspace path, so a guest
+// claiming `src/auth.ts` under `D:\work\repo` and a host holding it under
+// `/home/ana/repo` land in two different namespaces and never collide — the
+// coordinator looks shared while arbitrating nothing. Rewriting the workspace to
+// the host's path is what puts both users on one mutex.
+// `path.resolve` alone is not enough on Windows: the same folder reaches us as
+// both `C:\Users\PRAKRI~1\...` and `C:\Users\Prakrititz Borah\...` depending on
+// who spawned the agent, and a mismatch here silently sends the claim to the
+// guest's own namespace instead of the shared one.
+function canonicalPath(value) {
+  if (!value) return "";
+  try {
+    return fs.realpathSync.native(value).replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+  } catch {
+    return path.resolve(String(value)).replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+  }
+}
+
+function roomPayload(room, workspacePath, payload) {
+  if (room?.role !== "guest" || !room.hostWorkspacePath) return payload;
+  const local = canonicalPath(room.projectPath);
+  const here = canonicalPath(workspacePath);
+  // Antigravity (and some other agents) report a cwd that is the same repo on
+  // a different drive letter than the clone Relay joined. Still rewrite onto
+  // the host path so both machines share one lock namespace. Skip only when
+  // this is clearly a different folder with no room of its own.
+  if (local && here && local !== here && !here.startsWith(`${local}/`)) {
+    const hereRoom = loadRoom(workspacePath);
+    if (!hereRoom?.url || hereRoom.url !== room.url) return payload;
+  }
+  return { ...payload, workspaceId: room.hostWorkspacePath, peerWorkspacePath: workspacePath };
+}
+
+function postJson(port, pathname, body, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const data = JSON.stringify(body || {});
+    const req = http.request(
+      {
+        host: "127.0.0.1",
+        port,
+        path: pathname,
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(data),
+        },
+        timeout: timeoutMs,
+      },
+      (res) => {
+        let raw = "";
+        res.on("data", (c) => (raw += c));
+        res.on("end", () => {
+          try {
+            resolve({ status: res.statusCode, body: JSON.parse(raw || "{}") });
+          } catch (err) {
+            reject(err);
+          }
+        });
+      }
+    );
+    req.on("timeout", () => {
+      req.destroy(new Error("timeout"));
+    });
+    req.on("error", reject);
+    req.write(data);
+    req.end();
+  });
+}
+
+function getJson(port, pathname, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      {
+        host: "127.0.0.1",
+        port,
+        path: pathname,
+        method: "GET",
+        timeout: timeoutMs,
+      },
+      (res) => {
+        let raw = "";
+        res.on("data", (c) => (raw += c));
+        res.on("end", () => {
+          try {
+            resolve(JSON.parse(raw || "{}"));
+          } catch (err) {
+            reject(err);
+          }
+        });
+      }
+    );
+    req.on("timeout", () => req.destroy(new Error("timeout")));
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+function lockfilePath(workspacePath, file) {
+  const crypto = require("crypto");
+  const { locksDirFor } = require("../lib/paths");
+  const hash = crypto.createHash("sha256").update(file).digest("hex").slice(0, 16);
+  return path.join(locksDirFor(workspacePath), `${hash}.lock`);
+}
+
+function filesystemClaim(workspacePath, agentId, file, ttlMs) {
+  const lockPath = lockfilePath(workspacePath, file);
+  const now = Date.now();
+  try {
+    fs.writeFileSync(
+      lockPath,
+      JSON.stringify({ filePath: file, agentId, claimedAt: now, ttlMs, source: "filesystem", workspaceId: workspacePath }),
+      { flag: "wx" }
+    );
+    return { allowed: true, source: "filesystem" };
+  } catch {
+    try {
+      const existing = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+      const { sameOwner } = require("./lockTable");
+      if (sameOwner(existing.agentId, agentId) || now >= existing.claimedAt + (existing.ttlMs || 15000)) {
+        fs.writeFileSync(
+          lockPath,
+          JSON.stringify({ filePath: file, agentId, claimedAt: now, ttlMs, source: "filesystem", workspaceId: workspacePath })
+        );
+        return { allowed: true, source: "filesystem" };
+      }
+      return { allowed: false, holder: existing.agentId, source: "filesystem" };
+    } catch {
+      return { allowed: true, source: "fail-open" };
+    }
+  }
+}
+
+async function postRemote(url, pathname, body, timeoutMs, token) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${url.replace(/\/$/, "")}${pathname}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "ngrok-skip-browser-warning": "relay",
+        // An invite-only host rejects unauthenticated lock traffic; without the
+        // token every claim would silently fall back to local-only locking.
+        ...(token ? { "x-relay-room-token": token } : {}),
+      },
+      body: JSON.stringify(body || {}),
+      signal: ctrl.signal,
+    });
+    return { status: res.status, body: await res.json().catch(() => ({})) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function claimFile(workspacePath, agentId, file, ttlMs = 15000, opts = {}) {
+  const started = Date.now();
+  const room = loadRoom(workspacePath);
+  const payload = {
+    agentId,
+    file,
+    ttl: ttlMs,
+    workspaceId: workspacePath,
+    dependsOn: opts.dependsOn,
+    files: opts.files,
+    mode: opts.mode,
+    holder: opts.holder || null,
+  };
+  // Local API owns the control-plane socket. Guests must not wait on ngrok HTTP
+  // while chat snapshots are in flight — claims hop loopback, then a tiny WS.
+  // A `degraded` answer means the daemon could not reach the host, so it is not
+  // an answer at all — it must not short-circuit the ladder the way a real
+  // verdict does. Before this, the daemon's local-table grant came back as a
+  // plain `allowed: true` and stopped the search here, shadowing the room HTTP
+  // rung below: a dead control socket with a perfectly healthy tunnel never
+  // fell through to the wire that was still up.
+  let degraded = null;
+  try {
+    const remaining = Math.max(80, 800 - (Date.now() - started));
+    const { body } = await postJson(apiPort(workspacePath), "/api/coord/claim", roomPayload(room, workspacePath, payload), remaining);
+    if (body?.degraded) degraded = { ...body, source: body.source || "local_fallback" };
+    else if (body && typeof body.allowed === "boolean") return { ...body, source: body.source || "control" };
+  } catch {
+    /* coordinator / remote fallback */
+  }
+  if (roomUsable(room)) {
+    try {
+      const { body } = await postRemote(room.url, "/api/coord/claim", roomPayload(room, workspacePath, payload), HTTP_TIMEOUT_MS, room.memberToken);
+      return { ...body, source: body.source || "room" };
+    } catch {
+      markRoomDown(room);
+    }
+  }
+  // Every rung below this point is local to *this* machine: the coordinator
+  // process, the lock directory on this disk, and finally fail-open. None of
+  // them can adjudicate a lock that belongs to the room, so once we know we are
+  // a guest whose host is unreachable, consulting them would only launder an
+  // unanswered question into a confident yes. Refuse with the reason instead.
+  if (degraded) {
+    console.warn("[relay] HOST_UNREACHABLE — claim refused rather than granted locally");
+    return degraded;
+  }
+  const port = readPort(workspacePath);
+  if (port) {
+    try {
+      const remaining = Math.max(50, HTTP_TIMEOUT_MS - (Date.now() - started));
+      const { body } = await postJson(port, "/claim", payload, remaining);
+      return { ...body, source: body.source || "coordinator" };
+    } catch {
+      /* fall through */
+    }
+  }
+  const remaining = TOTAL_BUDGET_MS - (Date.now() - started);
+  if (remaining > 0) {
+    try {
+      return filesystemClaim(workspacePath, agentId, file, ttlMs);
+    } catch {
+      /* fail open */
+    }
+  }
+  console.warn("[relay] COORDINATOR_UNAVAILABLE — fail-open");
+  return { allowed: true, source: "fail-open" };
+}
+
+async function releaseFile(workspacePath, agentId, file) {
+  const room = loadRoom(workspacePath);
+  const payload = { agentId, file, workspaceId: workspacePath };
+  try {
+    const { body } = await postJson(apiPort(workspacePath), "/api/coord/release", roomPayload(room, workspacePath, payload), 600);
+    // A degraded release is already queued for replay by the daemon, but the
+    // tunnel may still be up even when the control socket is not — try it, and
+    // let the replay be a harmless no-op if this succeeds.
+    if (body && !body.degraded) return body;
+  } catch {
+    /* fallback */
+  }
+  if (roomUsable(room)) {
+    try {
+      const { body } = await postRemote(room.url, "/api/coord/release", roomPayload(room, workspacePath, payload), HTTP_TIMEOUT_MS, room.memberToken);
+      return body;
+    } catch {
+      markRoomDown(room);
+    }
+  }
+  return { ok: true };
+}
+
+async function status(workspacePath) {
+  const port = readPort(workspacePath);
+  if (!port) return { locks: {} };
+  try {
+    return await getJson(port, "/status", HTTP_TIMEOUT_MS);
+  } catch {
+    return { locks: {} };
+  }
+}
+
+async function releaseAll(workspacePath, agentId) {
+  const room = loadRoom(workspacePath);
+  const payload = { agentId, workspaceId: workspacePath };
+  if (roomUsable(room)) {
+    try {
+      const { body } = await postRemote(room.url, "/api/coord/release-all", roomPayload(room, workspacePath, payload), HTTP_TIMEOUT_MS, room.memberToken);
+      return body;
+    } catch {
+      markRoomDown(room);
+      /* local fallback */
+    }
+  }
+  const port = readPort(workspacePath);
+  if (port) {
+    try {
+      const { body } = await postJson(port, "/release-all", payload, HTTP_TIMEOUT_MS);
+      return body;
+    } catch {
+      /* ignore */
+    }
+  }
+  try {
+    const { body } = await postJson(apiPort(workspacePath), "/api/coord/release-all", payload, HTTP_TIMEOUT_MS);
+    return body;
+  } catch {
+    /* ignore */
+  }
+  return { released: [] };
+}
+
+async function heartbeat(workspacePath, agentId, file) {
+  const room = loadRoom(workspacePath);
+  const payload = { agentId, file, workspaceId: workspacePath };
+  try {
+    const { body } = await postJson(apiPort(workspacePath), "/api/coord/heartbeat", roomPayload(room, workspacePath, payload), 400);
+    if (body) return body;
+  } catch {
+    /* fallback */
+  }
+  if (roomUsable(room)) {
+    try {
+      const { body } = await postRemote(room.url, "/api/coord/heartbeat", roomPayload(room, workspacePath, payload), HTTP_TIMEOUT_MS, room.memberToken);
+      return body;
+    } catch {
+      markRoomDown(room);
+    }
+  }
+  return { ok: false };
+}
+
+module.exports = { claimFile, releaseFile, releaseAll, status, readPort, heartbeat, apiPort, postJson };