# LockRe

**File lock + surgical revert for multi-agent collaboration.** Stop AI agents from clobbering each other's edits, and undo any single agent's changes line-by-line without touching anyone else's work.

Exposed over **MCP** (for AI agents) and a plain **HTTP** API. Pun intended: **Lock** + **Re**vert (≈ *Rock Lee* 🥋).

```
zero dependencies · ~1,280 lines · ~997-token MCP footprint · Node ≥ 22
```

---

## Why

When several AI agents (or sub-agents) edit the same repository at once, two things go wrong:

1. **Lost updates** — two agents read, edit, and write the same file; one silently overwrites the other.
2. **No clean undo** — when one agent's contribution turns out wrong, you want to remove *just its lines*, not roll back everyone.

LockRe solves both with one tiny standalone service:

- **Lock / unlock / queue** — an agent reserves a file before editing. Others queue (FIFO) and are served in order.
- **Contribution tracking + surgical revert** — every edit is attributed by line. Reverting an agent removes only the lines it added, leaving other agents' work intact.

## Design principle: *the AI decides, LockRe never silently corrupts*

When a revert hits a **conflict** (another agent built on top of the line you're removing), LockRe does **not** guess. It returns a structured report — who conflicts, where, and the resolution options — and lets the agent choose. If there's no conflict, the revert just proceeds.

---

## Features

- **Lock model** — acquire / release / FIFO queue, per-lock token for safe unlock correlation.
- **Blocking + poll** — an agent can hold the request open until granted, or get a `waiting` reply (with queue position) and go do other work, then come back and re-check. No external notifier required.
- **Surgical revert** — remove one agent's added lines across one file or all its files in a single call.
- **4-mode conflict resolution** — `force` / `partial1` / `partial2` / `abort`, chosen by the agent from the conflict report.
- **Restore** — undo a revert (guarded: refuses if the file changed since, or is locked).
- **Safety nets** — revert respects active locks (won't clobber an agent mid-edit); stale-lock sweep (max-hold + file-mtime); startup clears stale locks; optional FIFO retention to bound the DB.
- **Heads-up** — locking a recently-reverted file warns the next editor to review it.
- **Zero dependencies** — pure Node built-ins (`node:http`, `node:sqlite`, `node:crypto`).

---

## Install & run

Requires **Node ≥ 22** (uses the built-in `node:sqlite`).

```bash
git clone https://github.com/crsxmd/LockRe-mcp.git
cd LockRe-mcp
node server.js            # starts the HTTP service on 127.0.0.1:8766
```

### Wire it into an MCP client (e.g. Claude Code)

```json
{
  "mcpServers": {
    "lockre": {
      "command": "node",
      "args": ["/absolute/path/to/LockRe-mcp/mcp-stdio.js"],
      "env": { "AGENTLOCK_BLOCKING": "1" }
    }
  }
}
```

The MCP bridge talks to the same HTTP service, so run `server.js` once and point every agent's bridge at it.

---

## MCP tools (7)

| tool | purpose |
|---|---|
| `lock` | Reserve a file before editing (acquire / queue / wait). |
| `unlock` | Release a file (records the contribution diff). |
| `revert_agent` | Remove one agent's added lines; returns a conflict report + modes when needed. |
| `restore_revert` | Undo a revert by `revert_uid`. |
| `get_contributions` | See, in time order, what each agent changed in a file. |
| `list_agents` | List agents that edited, most-recent first. |
| `agent_journey` | One agent's full edit journey (every file, + / − per edit). |

## HTTP API

`POST /lock` · `POST /unlock` · `POST /revert` · `POST /restore` · `GET /contributions` · `GET /agents` · `GET /status` · `GET /health`

---

## Conflict model

A **conflict exists only** when another agent's surviving line *incorporates* (embeds) a line you're reverting — e.g. you wrote `return a`, they changed it to `return a + b`. Pure additions and independent rewrites are **not** conflicts.

On conflict, `revert_agent` returns the report and four modes:

- **`force`** — remove all of the agent's lines, including the conflict zone (may corrupt; use when leftovers are safe to strip).
- **`partial1`** — revert only the non-conflicted files; leave conflicted files for you to fix.
- **`partial2`** — also revert conflict-free lines inside conflicted files, keeping the conflict-tied line.
- **`abort`** — change nothing.

> **Known limit (by design):** detection is line-level, not semantic. A revert can be clean line-wise yet break at runtime if another agent's surviving code *references* a symbol the removed lines defined (e.g. a function/variable). LockRe surfaces a `verify` hint and a `heads_up` on the next lock so the agent checks — it does not run your code.

---

## Configuration (env)

> Env vars use the `AGENTLOCK_` prefix (the project's original internal name).

| var | default | meaning |
|---|---|---|
| `AGENTLOCK_PORT` | `8766` | HTTP port (binds `127.0.0.1`). |
| `AGENTLOCK_DB` | `agentlock.db` | SQLite file. |
| `AGENTLOCK_BLOCKING` | off | Hold `/lock` open until granted (chunked); recommended for agents. |
| `AGENTLOCK_WAIT_CHUNK_MS` | `50000` | Per-chunk wait before returning a `waiting` reply. |
| `AGENTLOCK_MAX_HOLD_MS` | `1800000` | Absolute cap on any lock (leaked-lock backstop). |
| `AGENTLOCK_FILE_MTIME_MS` | `300000` | Auto-release a file lock unmodified this long. |
| `AGENTLOCK_GRACE_MS` | `120000` | Idle-holder grace. |
| `AGENTLOCK_MAX_CONTRIBUTIONS` | `0` (off) | FIFO retention cap on stored contributions. |
| `AGENTLOCK_EVICT_BATCH` | cap/5 | Rows evicted (oldest first) when over the cap. |

---

## Security

LockRe binds to **`127.0.0.1`** and has **no authentication** — it is designed for **local, single-machine** multi-agent use. **Do not expose the port to a public network.**

---

## Quality & testing

LockRe is validated by two independent layers (test files are not shipped in this repo):

- **Deterministic suite — 100 checks, all green:** lock-engine units, revert-mode classification, runtime revert (files actually re-run with `node`), the MCP bridge, a concurrency/stress harness (no-lost-update under 50+ concurrent ops, queue fairness, disconnect chaos, revert-respects-lock), and DB retention.
- **Genuine multi-agent re-run — 17 scenarios, all passing:** each conflict is created by **2–5 separate real agents** (each with its own server-minted id, locking/writing via the service), then reverted by another agent that inspects and decides. Coverage includes 4-agent concurrent no-lost-update, extend / upstream / replace / three-way / deep-chain / cross-agent-duplicate conflicts, all four revert modes, multi-file revert (whole + partial), revert→restore round-trips, the semantic-dependency limit, revert-respects-active-lock, and the post-revert heads-up. Every result cross-verified with `curl` / `node`.

---

## License

[MIT](./LICENSE) — free to use, modify, and distribute.

---

<a name="thai"></a>
## ภาษาไทย (สรุป)

**LockRe** = ระบบ **ล็อกไฟล์ + ย้อน (revert) แบบ surgical** สำหรับงานที่มี AI agent หลายตัวแก้โค้ดพร้อมกัน เปิดผ่าน **MCP** (สำหรับ agent) และ **HTTP** ชื่อพ้องเสียง *Rock Lee* (Lock + Revert)

**แก้ 2 ปัญหา:** (1) agent หลายตัวแก้ไฟล์เดียวกันแล้วเขียนทับกัน (lost update) (2) อยากย้อนงานของ agent ตัวเดียวโดยไม่กระทบคนอื่น

**หลักการ:** ตอน revert เจอ conflict ระบบ **ไม่ตัดสินแทน** — ส่ง report + ตัวเลือก (4 โหมด: force / partial1 / partial2 / abort) ให้ AI เลือกเอง **ไม่เคย corrupt เงียบ**

**เบา:** zero dependency, ~1,280 บรรทัด, MCP footprint ~997 tokens, Node ≥ 22

**ความปลอดภัย:** bind `127.0.0.1` ไม่มี auth — ใช้ภายในเครื่อง ห้าม expose ออกเน็ต

**ทดสอบ:** deterministic suite 100 เช็ค + genuine multi-agent 17 เคส (แต่ละเคสใช้ agent จริง 2–5 ตัวสร้าง conflict แล้ว revert) ผ่านหมด cross-verify ด้วย curl/node (ไฟล์เทสไม่ได้รวมใน repo นี้)

License: **MIT**