Parallel AI Website Edits: Scope Claims, Queues, Three-Way Merges
Two jobs editing the same file at the same time can overwrite each other without anyone making a mistake. I stopped hoping the models would be careful on their own and enforced advance scope declarations, locks implemented in code, and three-way merges for files that every job has to touch.
1-minute summary
- Symptom / problem
- Several people direct AI workers to edit the same site at once, and two jobs editing one file overwrite each other silently.
- Who should read
- People who let several AI workers edit the same site or repo at once.
- Fix in short
- Build a SQLite dispatcher where each job declares its scope in advance, conflicting jobs wait, a hook requires a claim before any file write, and hot files merge with a 3-way git merge-file.
One of my clients lets several people ask AI workers to edit the website, both through the admin interface and through chat. I started thinking about what would happen if two people submitted requests almost simultaneously, one asking for changes to the reviews page and another asking for text changes in a different section of the same page. If the job that finishes later writes its file over the earlier job's file, it silently overwrites the changes, with no error and no warning in the logs, and nobody notices until someone asks why this morning's changes have disappeared. I decided not to wait for that to happen before fixing it. I have covered this at the git level in When Work Silently Disappears as Multiple Agents Share a Working Tree, but this article covers another layer: a dispatcher that looks at the areas each job will touch, rather than at git.
The filenames, record names, and IDs in the examples (such as item:P017 and page:about) are all fictional and illustrate the format; they are not actual client data. I refer to the workers collectively as website-editing workers.
The Three Requirements I Set
I started by writing down three requirements. First, overlapping jobs must not run at the same time. Second, I did not want every job stuck in a long queue because of shared files that every job needs to touch. Third, if changes do conflict, they must be merged rather than overwritten.
Safe, but one job at a time
The simplest approach is to run one job at a time, so nothing overwrites anything else. But two site owners editing different pages have to wait for each other for no reason, and the more requests people make, the longer the queue gets.
Run only non-overlapping jobs in parallel
Each job states what it will touch before starting. Jobs that do not touch the same things can run together; overlapping jobs have to wait. The tradeoff is that enforcement has to be implemented in code, because trusting the model alone is not enough.
I chose scope declarations, following the principle that declaring in advance is cheaper than checking afterward. But declarations alone are not enough: a hook must enforce them when files are actually written, or a model that accidentally touches a file outside its scope can still overwrite someone else's work.
Scope Means Paths and Records
A job's scope is written as JSON with two parts: paths is a list of globs relative to the application, and records is a list of data records in the form "model:id", because website edits involve more than files. Some jobs change database content that pages read and display.
{
"paths": [
"resources/views/reviews/**",
"app/Http/Controllers/ReviewController.php"
],
"records": ["item:P017", "page:about"]
}
I defined the interpretation rules as follows: a path without wildcards means that file and everything beneath that directory; * stays within one directory level, ** can cross directories, ? means one character, and [...] is a character set. Records use lowercase, and "model:" means every record in that model. An alias table normalizes names people commonly write differently (such as articles and blog) before comparison. If the scope is empty, "", or says the whole site, that job runs alone.
Two patterns "overlap" when there is a file that could match both. I chose conservative comparisons: if both sides contain wildcards, I compare only their literal prefixes. When uncertain, I treat them as overlapping; the cost is a longer wait, which is better than an overwrite.
import re
def to_re(p: str) -> str:
out, i = "", 0
while i < len(p):
if p[i:i+2] == "**": out += ".*"; i += 2
elif p[i] == "*": out += "[^/]*"; i += 1
elif p[i] == "?": out += "[^/]"; i += 1
else: out += re.escape(p[i]); i += 1
return out
def has_wild(p): return any(c in p for c in "*?[")
def lit_prefix(p): return re.split(r"[*?\[]", p, 1)[0]
def parents(p):
parts = p.split("/")
return ["/".join(parts[:i]) for i in range(1, len(parts) + 1)]
def overlap(a: str, b: str) -> bool:
a, b = a.rstrip("/"), b.rstrip("/")
wa, wb = has_wild(a), has_wild(b)
if not wa and not wb: # ทั้งคู่เป็นไฟล์หรือโฟลเดอร์ตรง ๆ
return a == b or a.startswith(b + "/") or b.startswith(a + "/")
if wa and wb: # wildcard ทั้งคู่ เทียบ prefix ฝั่งปลอดภัย
pa, pb = lit_prefix(a), lit_prefix(b)
return pa.startswith(pb) or pb.startswith(pa)
lit, pat = (b, a) if wa else (a, b) # ฝั่งหนึ่งตรง ๆ อีกฝั่งเป็น pattern
if any(re.fullmatch(to_re(pat), x) for x in parents(lit)):
return True
return lit_prefix(pat).startswith(lit + "/") or lit_prefix(pat) == lit
This is a shortened example to show the idea, using only Python's standard library because I wanted it to run with the system Python without installing anything.

A SQLite Dispatcher That Acquires Rights in One Transaction
I used SQLite for the dispatcher because everything runs on one machine and it needs no additional service. The part that has to be correct is accepting a new job: reading active jobs, deciding which ones it overlaps with, and recording its state must all happen in one transaction. I use BEGIN IMMEDIATE with a busy timeout so two jobs submitted simultaneously cannot each act on a different stale view of the data.
import json, sqlite3
def submit(db: str, job_id: str, scope: dict | None):
con = sqlite3.connect(db, timeout=30, isolation_level=None) # busy timeout 30 วินาที
con.execute("BEGIN IMMEDIATE") # ล็อกเขียนตั้งแต่ต้น
try:
live = con.execute(
"SELECT id, scope FROM jobs WHERE state IN ('queued','waiting','running') ORDER BY id"
).fetchall()
waits_for = [i for i, sc in live if conflicts(scope, json.loads(sc))]
state = "waiting" if waits_for else "queued"
con.execute(
"INSERT INTO jobs(id, scope, state, waits_for) VALUES (?,?,?,?)",
(job_id, json.dumps(scope), state, json.dumps(waits_for)),
)
con.execute("COMMIT")
except Exception:
con.execute("ROLLBACK")
raise
Notice that a new job must wait not only for running jobs, but also for jobs ahead of it in the queue. Otherwise, older jobs that have not started could be overtaken. That is why queued and waiting are separate states. A waiting job carries waits_for to record which jobs it is waiting for. Once every job in waits_for has finished, the dispatcher moves that job to queued and starts it.
The Claim Hook Enforces Writes and Must Fail Closed
The declared scope is just a statement. The actual enforcement comes from the file-writing tool's PreToolUse hook. Before the model writes any file, the hook requests a claim for that file's key in the claims table. If no other job holds it, the claim is granted immediately. If another job holds it, the hook can wait for CLAIM_WAIT, which is 120 seconds. If the timeout expires without acquiring it, the write is rejected.
The point I kept emphasizing to myself was that when the hook cannot reach the job database, it must reject the write, rather than let it through. Allowing writes when the database is down would mean that the day the locking system fails is the day every job can freely overwrite the others. I retry a few times before rejecting the write.
import sqlite3, sys, time, json
CLAIM_WAIT = 120
def try_claim(db, job_id, key) -> bool:
con = sqlite3.connect(db, timeout=10, isolation_level=None)
con.execute("BEGIN IMMEDIATE")
try:
row = con.execute("SELECT job_id FROM claims WHERE key=?", (key,)).fetchone()
if row is None or row[0] == job_id:
con.execute("INSERT OR REPLACE INTO claims(key, job_id) VALUES (?,?)", (key, job_id))
con.execute("COMMIT")
return True
con.execute("COMMIT")
return False # คนอื่นถืออยู่
except Exception:
con.execute("ROLLBACK")
raise
def main():
ev = json.load(sys.stdin)
path = ev["tool_input"].get("file_path", "")
deadline = time.time() + CLAIM_WAIT
errors = 0
while True:
try:
if try_claim(DB, JOB_ID, path):
return 0 # ได้ claim ปล่อยให้เขียน
except sqlite3.Error:
errors += 1
if errors >= 3: # เข้าฐานข้อมูลไม่ได้ซ้ำ ๆ
print("ติดต่อฐานข้อมูลงานไม่ได้ ปฏิเสธการเขียน", file=sys.stderr)
return 2 # fail closed
if time.time() > deadline:
print("ไฟล์นี้ถูกงานอื่นถืออยู่ เกินเวลารอ", file=sys.stderr)
return 2
time.sleep(2)
sys.exit(main())
Another layer I added later covers developers editing files manually on the same machine. If a developer edits outside this system, the worker cannot see that someone is touching the file. I added a small script that lets developers declare claims for their edits in the same table, so workers can see them and wait.
Why Records Are Needed Alongside Paths
At first I thought declaring paths would be enough, but on a website with database-backed content, two jobs can touch completely different files while changing the same record. For example, one job changes the text on the about page through a template, while another changes the same about page through a row in the pages table. The files are different, but the end result is the same page. Comparing paths alone would treat them as non-overlapping.
Records therefore provide another axis for comparison. Two jobs overlap when their paths overlap or their records overlap; either is enough. The "model:" form claims the entire model for jobs that change every record, such as changing terminology across the site. A job declaring the whole site (an empty value or "") runs alone, with no other job alongside it. I use this for jobs that touch so much that I really cannot specify their scope, such as changing the entire template structure.
def conflicts(a: dict | None, b: dict | None) -> bool:
if a is None or b is None: # ทั้งเว็บ ชนทุกงาน
return True
pa = [p for p in a.get("paths", []) if p not in HOT_FILES]
pb = [p for p in b.get("paths", []) if p not in HOT_FILES]
if any(overlap(x, y) for x in pa for y in pb):
return True
ra, rb = set(a.get("records", [])), set(b.get("records", []))
if ra & rb:
return True
wild = lambda s: {r.split(":")[0] for r in s if r.endswith(":*")}
return bool(wild(ra) & {r.split(":")[0] for r in rb} or wild(rb) & {r.split(":")[0] for r in ra})
Hot Files: Merge Instead of Locking
If everything has to wait under the rules above, the second requirement becomes a problem: files that almost every job needs to touch, such as language files, routes files, shared CSS files, and config files. A text edit on any page needs to add keys to a language file. If that counts as an overlap every time, all jobs end up in a single queue.
I made a separate list of "hot files". Files on this list do not make jobs wait. Each job edits its own copy, and the copies are combined at deployment using a three-way git merge-file. When a job starts, I record the sha256 of the file it starts from as the base. During deployment, I compare it with the current live file. If they match, nobody has changed it in the meantime, and it can be overwritten directly. If they do not match, I bring in the live file for merging.
# mine = ผลของงานนี้, base = ไฟล์ที่งานเริ่มจาก, live = ไฟล์จริงตอนนี้
sha256sum live.php | cut -d' ' -f1 # เทียบกับ sha256 ของ base ที่จดไว้ตอนเริ่มงาน
git merge-file -p -L "this job" -L base -L live mine.php base.php live.php > merged.php
echo "conflicts=$?" # 0 = รวมสะอาด, เลขบวก = จำนวนจุดที่ชนจริง (มี conflict marker ในไฟล์)
If there is an actual conflict, meaning two jobs changed the same line in a hot file, I do not guess. I leave the conflict markers in the file and send it back to the worker to resolve. If the conflict remains, I retry up to the configured number of attempts. Binary files cannot be merged this way, so this approach cannot merge them.

Examples With and Without Overlaps
I wrote three hypothetical jobs to show how each rule works.
The Test Suites and What I Learned
The test suites are what gave me the confidence to release this system. I have three separate test files: the first tests whether the dispatcher and scope logic identify the right overlapping pairs, the second tests multiple workers running in parallel, and the third tests isolation between parts of the system. Whenever the pattern comparison rules change, the first suite should always run first, because bugs here are very quiet. If a comparison is too permissive, jobs simply overwrite each other as before, with nothing to tell you it happened.
- Require advance declarations, but enforce them with a hook implemented in code, rather than hoping the model remembers.
- Use three-way merges for shared files that every job must touch, rather than locks.
- The hook must fail closed when the lock database fails.
- Always compare scopes conservatively; when uncertain, treat them as overlapping.
- Use only the standard library so the system can run directly with the system Python.
This system prevents overwrites only for jobs that go through it. Someone editing files manually on the machine without declaring a claim can still overwrite changes. That is why I also need a script for developers to declare claims for their own edits. Three-way merges work only with text files, and deciding which changes to keep when two edits actually conflict still requires a person or worker to resolve them.
I covered quotas shared between jobs and the permission levels granted to each worker separately in Permission Levels Based on the Requester. For more on an atomic claim mechanism based on the same idea, see Idempotent Job Claims. If you want to try this, adapt it to your machine's capacity and what is practical in your environment. But if you can invest time in only one thing, I recommend a hook that fails closed, because that is the layer that makes "declaring scope" real. If I have not explained something fully, I will come back and add to it later.
Want us to set this up?
Get help with server setup, configuration, migration, or troubleshooting. Save time for the work that matters.
Hit something like this? Stuck somewhere?
Come trade notes on the LinuxThai board



Comments 0
No comments yet — be the first