I wrote two fixes for the same race condition. Gemini told me only one of them was real.

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

Project Overview

This morning my conversation log was saved under a different project's name.

I run several AI coding-agent sessions in parallel on one machine — same OS user, sometimes the same repository. One of them has a skill that archives the current conversation into a notes vault. Because non-ASCII arguments get mangled on this shell, the metadata for that archive (title, destination project) is not passed on the command line. It is written to a file:

~/.claude/temp/obsidian-meta.json

and a separate script reads that file back a moment later.

Read that path again. There is no session id in it. There is one such file per machine, and I was running more than one session per machine.

Here is what the two sessions did, interleaved:

session A   write meta.json  {"title": "paid-writing pitches", "project": "self-catering"}
session B   write meta.json  {"title": "MC mail triage",       "project": "Rtoner-Google"}
session A   run archiver  ->  reads meta.json  ->  gets B's title, B's folder

Session A's conversation was written to disk with session B's title, in session B's project directory.

Nothing failed. The file existed. The JSON parsed. json.load() returned a dict with exactly the keys the archiver expected. Every check passed, and the answer was somebody else's.

I only caught it because the archiver stamps frontmatter into the file it writes — the real session_id, the real working directory — and those contradicted the filename it had just chosen. The body of the file said one thing and the name of the file said another. Without that redundancy I would still not know.

Then I remembered that four days earlier, the same thing had happened somewhere else entirely.

Bug Fix or Performance Improvement

The second surface: git's index

Four days before, I had run git add -- <my-paths>/ and then paused to ask the user whether to commit. While I waited, a different agent session in the same repository ran git commit.

My eleven staged files went into that session's commit, under a message about an unrelated subproject.

Nothing was lost. But my changes are now buried in a commit whose title does not describe them, which is its own kind of data loss — the kind you discover six months later while running git log and finding nothing.

What is worth noticing is which safeguard did not help. I had a rule, written after an earlier incident: always name the paths explicitly when you stage; never git add .. I followed it. I even machine-checked that nothing outside my scope was staged.

That rule protects the contents of my commit. It says nothing about another session's commit consuming my staged state. I had written a rule about the wrong half of the problem.

Making the window measurable

Two anecdotes are not a bug report, so I built the smallest thing that would show the window is real: two threads, each playing one agent session, each doing write-then-read-back 200 times. One run with a shared filename, one with a per-session filename. Count how often a session reads back data that isn't its own.

mode=fixed     handoffs=400  wrong-owner=219  rate=54.8%
  sess-A: 114/200 reads returned another session's data
  sess-B: 105/200 reads returned another session's data

mode=isolated  handoffs=400  wrong-owner=0    rate=0.0%
  sess-A: 0/200 reads returned another session's data
  sess-B: 0/200 reads returned another session's data

The shared-name number moves between runs, because thread scheduling decides it. Over 7 runs it landed between 54.8% and 62.3% (219–249 of 400). The per-session number did not move: 0 of 400, in all 6 runs.

Neither of those is the real-world rate, and I want to be explicit about it. Two threads in a tight loop maximise the overlap on purpose. In production this has bitten me exactly once, over weeks of parallel sessions. The percentage does not tell you how often it happens — it tells you the window is real, and that closing it takes the count to a hard zero rather than merely lowering it. The gap between "a number that wanders around 60" and "a number that is 0 every time" is the entire finding; the number itself is not evidence of anything.

The interesting column is the failure mode, not the rate. Look at what a wrong-owner read looks like from inside the process:

got = json.loads(path.read_text(encoding="utf-8"))
# no exception. valid JSON. all expected keys present.
if got["session"] != session_id:   # <- the only thing that would ever notice
    wrong += 1

Nothing in the normal path checks that line. A crash would have been a gift.

Two fixes, and the one I got wrong

I wrote both fixes before asking anyone:

1. Handoff file — use a per-session name, obsidian-meta-<session_id>.json.
2. Git — never leave anything staged across a pause. Emit git add -- <paths> && git commit -F - as a single command, and get approval before staging rather than between.

Both looked equally good to me. I gave the whole thing to Gemini — both incidents, the reproduction numbers, and both fixes — and asked five questions, one of which was "is the per-session filename a genuine fix or an accident-avoidance patch?"

I expected a yes on both. I got a split verdict:

Failure 1 (Per-session filename): Genuine Fix.
By scoping the path to <session_id>, you eliminate the shared state altogether.

Failure 2 (Atomicity via atomic chaining): A Patch, Not a Fix.
Getting approval first and running git add ... && git commit shrinks the window of vulnerability, but it does not fix the underlying lack of isolation. If Session B executes its git commit in the precise millisecond between Session A's git add and Session A's git commit, Session B will still sweep up Session A's staged files.

It is right, and I had not seen it. Fix 1 removes the shared resource. Fix 2 keeps the shared resource and runs past it faster. Those are not the same kind of thing, and I had filed them under the same heading because they made the same symptom stop appearing in my testing.

The generalisation is the part I'll actually keep:

The failure of Git's index highlights that reducing time-at-risk is merely a mitigation; physical or logical isolation is the only general solution. When a shared resource cannot be renamed or parameterised at the application level, you must isolate the environment itself. For Git, the true structural fix is to give each agent session its own isolated working tree and index (e.g., using git worktree or running sessions inside separate container/VM environments).

Renaming a temp file is available to me because I own the code that names it. .git/index is at a fixed path by design — I cannot parameterise my way out of it, so the fix has to move up a level, to the environment. Same root cause, two different fixes, and the reason they differ is not the bug but how much of the surface I control.

The annoying part: my agent runtime already supports per-session git worktrees. I had a working isolation primitive sitting in the toolbox and reached for a stopwatch instead.

Code

Full reproduction, dependency-free, stdlib only:

"""Minimal reproduction of the handoff-file race that mislabelled my conversation log."""

import json
import pathlib
import sys
import tempfile
import threading

TRIALS = 200
TMP = pathlib.Path(tempfile.gettempdir()) / "race_repro"
TMP.mkdir(exist_ok=True)


def meta_path(mode: str, session_id: str) -> pathlib.Path:
    """The only difference between the bug and the fix is this function."""
    if mode == "fixed":
        return TMP / "meta.json"                    # one file for everybody
    return TMP / f"meta-{session_id}.json"          # one file per session


def session(mode: str, session_id: str, project: str, results: dict) -> None:
    """One agent session: write my metadata, then read it back to use it."""
    wrong = 0
    for i in range(TRIALS):
        path = meta_path(mode, session_id)

        # step 1 - hand off my own metadata
        payload = {"session": session_id, "project": project, "n": i}
        path.write_text(json.dumps(payload), encoding="utf-8")

        # step 2 - the downstream script reads it back
        try:
            got = json.loads(path.read_text(encoding="utf-8"))
        except (json.JSONDecodeError, FileNotFoundError):
            # a torn read also counts as a loss, but it is the *loud* failure;
            # the dangerous one is the silent branch below
            wrong += 1
            continue

        # the read succeeded and the JSON parsed. Is it mine?
        if got["session"] != session_id:
            wrong += 1

    results[session_id] = wrong


def main() -> int:
    mode = sys.argv[1] if len(sys.argv) > 1 else "fixed"
    if mode not in ("fixed", "isolated"):
        print("usage: race_repro.py [fixed|isolated]")
        return 2

    results: dict[str, int] = {}
    threads = [
        threading.Thread(target=session, args=(mode, "sess-A", "self-catering", results)),
        threading.Thread(target=session, args=(mode, "sess-B", "Rtoner-Google", results)),
    ]
    for t in threads:
        t.start()
    for t in threads:
        t.join()

    total = sum(results.values())
    runs = TRIALS * len(threads)
    print(f"mode={mode:<9} handoffs={runs}  wrong-owner={total}  rate={total / runs:.1%}")
    for name in sorted(results):
        print(f"  {name}: {results[name]}/{TRIALS} reads returned another session's data")
    return 0


if __name__ == "__main__":
    sys.exit(main())

$ for i in 1 2 3 4 5; do python race_repro.py fixed | head -1; done
mode=fixed     handoffs=400  wrong-owner=243  rate=60.8%
mode=fixed     handoffs=400  wrong-owner=239  rate=59.8%
mode=fixed     handoffs=400  wrong-owner=232  rate=58.0%
mode=fixed     handoffs=400  wrong-owner=248  rate=62.0%
mode=fixed     handoffs=400  wrong-owner=249  rate=62.3%

$ for i in 1 2 3 4 5; do python race_repro.py isolated | head -1; done
mode=isolated  handoffs=400  wrong-owner=0  rate=0.0%
mode=isolated  handoffs=400  wrong-owner=0  rate=0.0%
mode=isolated  handoffs=400  wrong-owner=0  rate=0.0%
mode=isolated  handoffs=400  wrong-owner=0  rate=0.0%
mode=isolated  handoffs=400  wrong-owner=0  rate=0.0%

The whole diff between "broken" and "correct" is one f-string in meta_path(). That is what makes this class of bug worth writing about: the fix is trivial once you see it, and completely invisible until something contradicts itself in front of you.

My Improvements

Done:

• Per-session handoff filenames (obsidian-meta-<session_id>.json). 0 of 400 in every one of the 6 harness runs.
• The mislabelled conversation log was located and removed. I could identify it because the frontmatter inside disagreed with the filename — the redundancy that caught the bug in the first place.
• Approval for a commit is now requested before staging, not between staging and committing.

Changed because of the review, not yet shipped:

• Git isolation via per-session worktrees, instead of trying to be fast between add and commit. My runtime supports this natively; I had simply never turned it on for the parallel case. Shipping it means changing how sessions start, which is not a thing to rush at the end of a session that has already found two bugs.

Not done, and I'd rather say so:

• The skill's own instruction file still documents the fixed path. The per-session name works, but the written procedure has not been updated to require it, so the next session that follows the documentation reintroduces the bug. Changing that file is a harness change and my own rules require reading the design docs before touching it — which is correct, and which I have not done yet. A fix that lives only in my head is not a fix.

Left as a guard, deliberately:

The archiver writes the true session_id and working directory into the output. That redundancy is the only reason I ever found out. When a handoff crosses a process boundary, having the payload carry its own identity — and having something downstream compare it — turns a silent wrong answer into a detectable one. Every check in the normal path passed. Only the disagreement between two independently-derived facts caught it.

Best Use of Google AI

I used Gemini (free tier, Flash) once, at one specific point: after I had reproduced the bug and written both fixes, and before I shipped either.

What I handed over was deliberately boring — the two incidents, the interleaving, the harness numbers, both proposed fixes, and one instruction: if my reasoning is wrong somewhere, say so directly. No code, no repo access. Five questions, of which the load-bearing one was whether my fixes were fixes.

Three things came back that I did not have:

1. A split verdict where I expected a pair. Fix 1 genuine, fix 2 a patch — with the exact interleaving that defeats fix 2 spelled out (commit landing in the millisecond between my add and my commit). I had tested fix 2 by not being able to make it fail, which is not the same as it not failing.

2. The category the two fixes actually belong to. "Reducing time-at-risk is merely a mitigation; physical or logical isolation is the only general solution." That sentence is why I stopped writing rules about how fast to move and started looking at worktrees — a primitive I already had.

3. The next five surfaces, concretely. Local TCP ports (EADDRINUSE, or worse, silently reaching the wrong session's dev server), shared build caches, global CLI config and credential files being rewritten mid-run by another session, local SQLite/Postgres and migrations, and lock/socket files in /tmp. Each one is a fixed path that exactly one process was ever expected to own.

It also gave me the vocabulary I had been talking around: TOCTOU, and state interleaving / cross-talk for the multi-tenant framing. The class is older than agents by decades. What is new is who is racing — not threads I wrote, but sessions I started, in tools that were designed when "one developer, one machine, one thing at a time" was too obvious to state.

Two of my earlier submissions this month were about measurements that were quietly wrong — a ranking only I could see, a collector that reported success holding 27% of the data. This one has the same shape and I keep walking into it: every check passed and the answer was still wrong. The thing that broke the pattern here was not a better check. It was a second, independently-derived fact that could disagree with the first — and, at the point where I'd stopped being able to see my own reasoning, a second opinion that was willing to tell me one of my two fixes was theatre.