# The Crowded Tree

Part II: The Shared Machine

## You are here if

Something moved and you did not move it. The edit failed because the bytes on disk no longer match the bytes you read ten minutes ago. The commit you just made is sitting on a branch you never checked out. A file appeared mid-session that you did not create. The repository directory is gone. The reindex died on a lock, and you do not know whose hand is on it. Status shows modifications, and every process you can name denies making them.

You are here if the room you believed you had to yourself turns out to be crowded: a peer session, a linter, a housekeeping job, the harness's own machinery, each writing on its own schedule and none of them announcing it. You are also here earlier than that, at your best moment instead of your worst, if you are about to write into a shared space and have not yet checked who else is in it.

You are in the wrong chapter if the change came from a worker you dispatched and what you distrust is its account of the work: that is chapter 6. If nothing in the world has moved and the record in your hand is simply older than the world, that is chapter 2. This chapter is for the delta with a second author: a change that is real, that is recent, and that is not yours.

## The mechanism

The spaces this chapter lives in share one property: they are single slots. A working tree, a config file, a vault database, a directory of numbered outputs. Version control gives history a many-writer discipline, branches and merges and a record of who did what; the working tree gets none of it. It is one mutable surface, last write wins, and no receipt is kept that a race ever happened. The settings file and the shared directory are the same surface with less ceremony. And every tool that touches these surfaces is built on the same quiet assumption: that it is alone. The linter assumes it. The housekeeping job assumes it. Your session assumes it. Each writer is correct inside its own model, so the collision belongs to nobody, and it surfaces as something else entirely: an edit that fails on stale bytes, a commit on the wrong branch, debris that is not debris, a loss that is not a loss.

That costume is the second half of the danger. A collision never announces itself as a collision; it presents as a mess to clean up, and your reflexes for a private machine are all cleanup reflexes: delete the stray file, reset the dirty tree, kill the process holding the lock. In a crowded room every one of those is a write into contested space, and each one converts a peer's live work into your incident. This is the chapter where good instincts are the failure mode, and the only chapter in this manual where the correct first move is to yield.

Detection is harder than it looks, because every check you would naturally run is a photograph and the other writer is a film. The type specimen: two agents were writing one working tree, and before launching a heavy verification gate, one of them did the responsible thing and took a status snapshot. Clean, and stable. The snapshot was true and worthless: the peer was mid-way through a long build phase that touches no tracked file, so the tree sat still while the peer's process churned toward its next write. The gate launched into the quiet-looking tree and collided with the writer the photograph could not show. The snapshot had answered the wrong question. It reported the state of the writing; the hazard was the existence of the writer.

Book One tells the peer doctrine in full, peers rather than owners, symmetric ceremony, the single-writer invariant as something you establish rather than assume; this chapter inherits it as field procedure.

## The discipline

Claim before you write, and treat any change you did not make as a stop signal, not debris.

The ritual:

1. **Name the other writers before your first write.** List what can touch this space: peer sessions, dispatched agents, the linter, the harness's own reformatter, the housekeeping schedule, the desktop client with the same vault open. Pass: the list came from looking, a process table, a session list, a coordination channel, not from assuming; and if it is non-empty, every following step is mandatory.

2. **Take the claim in the space's native mechanism.** A branch pushed where peers will see it, a start receipt in the shared channel, the lock the other tools already respect; in a space with no native mechanism, write the receipt anyway and pre-allocate anything two writers might otherwise both compute. Pass: another writer running this same ritual would find your claim at their step 1.

3. **Re-read immediately before every write.** The read that justifies an edit expires the moment another writer could have moved things. Re-read the file before the edit lands; re-check the current branch and the repo-wide status before every commit. Pass: the bytes and the branch were confirmed in this step, not remembered from the start of the task.

4. **Check for the writer, not just the writing.** A clean snapshot is a photograph of a room that may be mid-motion. Look for live processes that match a peer; take a second snapshot after an interval and compare the two. Pass: no live peer found, and the two snapshots agree. A churning tree is a stop light, not a queue you can beat.

5. **Stop on any delta you did not author.** An untracked file you did not create is read-only. A modification nobody you dispatched explains is hands-off. A directory that vanished gets searched for in the archive location before anyone says deleted. Pass: nothing unexplained was cleaned, stashed, reset, or removed, and the delta was surfaced to its likely owner before your own work resumed.

6. **Recover with pointers, never with force.** A commit on the wrong branch is repaired by moving branch pointers; a shared tree is never checked out, reset, or cleaned to fix your mistake, because the tree is not yours to churn. Pass: the recovery changed refs only, and the fix touched no working-tree bytes.

## The case ledger

Eleven entries, grouped by who the other writer was: a peer you do not command, the machine's own housekeeping, and the room with no lease at all.

**The peer.** Another session, writing beside you.

**[E064] The snapshot missed the live peer** (2026-06-28 / 2026-07-02)
Receipt: two agents writing one working tree collided; a plain status snapshot, taken while the peer was mid-way through a long non-git build phase, showed a falsely clean and stable tree.
Rule: detect a concurrent writer with more than a snapshot, check for live matching processes, and yield rather than race a heavy verification gate against a churning tree.

**[E065] The branch switched underneath the session** (undated)
Receipt: two sessions sharing one working tree meant the branch moved under one of them, and its commits landed on the other session's branch.
Rule: re-check the current branch and repo-wide status before every commit; recover a misplaced commit with a pure branch-pointer move, never a checkout or reset of the shared tree, and isolate into a dedicated workspace going forward.

**[E066] The untracked file was a peer's live output** (2026-06-19)
Receipt: a file that appeared mid-session, not created by the current agent, was a concurrent session's in-flight output rather than build cruft.
Rule: treat any untracked file you did not create as read-only; a repo-wide status showing changes you did not make means stop touching the repo and surface it to the operator.

**[E055] The integration branch was never yours** (undated)
Receipt: in a fleet-driven repo the integration branch was permanently occupied by the main checkout, and a failed attempt to isolate it left the working directory pointed at the live checkout for the file operations that followed.
Rule: recognize when a branch cannot be isolated because another session owns the checkout, and verify the working directory after any failed isolation attempt before running further file operations.

**[E077] The sweep would have raced a live session** (2026-06-19)
Receipt: a bulk push-sweep of unpushed commits across a portfolio would have raced a peer coding session that was mid-flight on some of the same branches.
Rule: before any push-sweep, re-reconcile each branch's live state immediately before pushing, and push only branches that are genuinely orphaned, owned by nobody.

**The housekeeper.** Machinery that writes on its own schedule, and was never wrong to.

**[E149] The linter between the read and the write** (undated)
Receipt: an automated linter rewrote memory files between a read and the subsequent edit, causing stale-byte edit failures; across a multi-session sample this was the single most common real tool failure.
Rule: on any file an automated linter might touch, re-read immediately before editing, not just once at the start of the task.

**[E001] The harness reformats behind every write** (2026-05-03)
Receipt: parallel edits to the harness's own JSON config collided because the harness silently reformats its config files after every write, and plugin install and uninstall trigger the same reformat.
Rule: treat harness config edits as sequential, re-read immediately before the next edit, and expect plugin operations to reformat the file behind you.

**[E043] The rename was a feature** (2026-06-02)
Receipt: a documentation-sync branch was auto-renamed under a different prefix by repo tooling, which correctly, not buggily, made a merge helper skip it.
Rule: when a scripted run's branch is missing from the merge plan, check for an auto-rename before assuming the reconciliation was dropped, and leave auto-renamed branches to the system that owns them.

**[E060] The vanished repo was filed, not deleted** (2026-06-03 / 2026-06-06 / 2026-06-07)
Receipt: a repo directory that appeared to vanish from disk was read as a destructive delete; a separate housekeeping process had moved it into an archive location.
Rule: when a repository directory disappears, search the known archive location before concluding anything was destroyed.

**The unleased room.** Shared space with no native claim mechanism.

**[E067] Two writers, both counting** (2026-07-04)
Receipt: a shared non-git directory had no branch-level lease, so two subagents computing their own identifier numbers could collide invisibly.
Rule: claim a lane by writing an explicit start and close receipt to a shared coordination channel, and pre-allocate contested identifiers centrally rather than letting each writer compute its own.

**[E080] The lock was somebody's hand** (undated)
Receipt: a knowledge-vault reindex failed on a database lock while a separate desktop client was concurrently writing the same vault.
Rule: wait for the concurrent writer to finish before reindexing; when stale processes hold the lock, clear them carefully without also killing the one legitimate live writer.

## Adjacent doors

**If the writer was one you dispatched**, a subagent's edits, a delegate's cleanup, commanded work arriving in your tree, that is chapter 6. The fork is command: a peer owes you nothing but a claim, and your move is to yield; a worker owes you a diff, and your move is to read it. This chapter's stop signal is for changes with no owner you can name. The moment you can name the owner because you hired it, the problem is not concurrency but the report.

**If nothing has actually moved and your picture is simply old**, the checklist true at authoring time, the plan built on last week's tree, that is chapter 2. The fork question is whether there was a second hand. A record goes stale with no other writer existing anywhere; that is time's doing, and chapter 2 owns time. But run its reconciliation and find a delta that no process you dispatched or scheduled explains, and you are back here, because staleness with an author is a collision.

**If you are about to be the crowd**, one sweep writing across many trees, that is chapter 9. This chapter defends one shared space from many writers; chapter 9 defends many spaces from one wide write. The sweep entry in this ledger sits exactly on that border: E077 lives here because the hazard was a live peer on the far side of the push. The day the wrong assumption is in your branch list instead of somebody else's session, the same sweep belongs to chapter 9, and the yield that saves you here will not save you there.
