Why a seat exists
Checked against the Orcyx source tree at c339cf993 on 2026-09-14. Where this page describes something the build does not do yet, it says so in place rather than describing the intention.
Two agents editing one checkout is not a concurrency problem you can solve with care. They will read each other's half-finished files, a type check run by one will fail on the other's in-flight edit, and a command that discards local changes destroys work its author never saw. A seat removes the shared surface: each pane gets its own git worktree, its own branch, its own working tree.
A worktree is not a clone. It shares the object database with the main checkout, so it costs a working tree rather than a repository, and it appears in the repository's worktree list rather than as a detached copy on disk.
What the app does when it makes one
Four steps, in this order, and the last two are the ones people leave out when they make a seat by hand:
| Step | What it does | Measured |
|---|---|---|
| Prune | Drops worktree registrations left behind by a crash or a reboot, which would otherwise make the next add fail for no visible reason. | 0.13 s |
| Add | Creates the worktree on a new branch named for the workspace and the pane. | 4.25 s · 6.00 s · 4.77 s |
| Link dependencies | Links the installed dependency directories — the repository root, and one level under the app and service workspaces — into the seat, so a seat never pays for an install. | 5 ms (×10 node_modules links per seat) |
| Copy the hook shims | Copies the untracked directory git's hooks path points at, so the seat actually runs the repository's hooks. | 11–19 ms |
Linking rather than copying is what makes a seat cheap, and it is also the sharpest edge in the design: a link into the main checkout is a path a careless recursive delete will follow. Cleaning a seat therefore removes the links before removing the worktree, and refuses rather than guessing if it cannot confirm it did.
The hook shims, specifically
The repository points git's hooks path at a directory that is not tracked in git. A worktree created by hand therefore has no hooks in it at all — and a commit with no hooks does not announce itself. It succeeds. Every commit in that seat passes, because nothing checked.
If you create a seat with a bare worktree command, copy that directory into the new worktree before the first commit, and verify it landed by testing for the directory itself. Do not verify it by checking the exit status of a pipeline: a pipeline reports the exit status of its LAST command, which is not the one that did the copying.
Committing in a seat
Commit path-restricted, naming the files you own. A broad stage-everything commit in a repository where other agents are mid-edit captures their unfinished work into your commit, and the type gate then fails on code you have never read.
The same reasoning rules out the commands that discard or relocate uncommitted changes across the whole tree — hard resets, path checkouts, clean, and a bare stash. The stash stack in particular is shared by every worktree in the repository: a bare stash push here can capture, and a bare pop can restore, another agent's in-flight work.
Merging back
A seat's work reaches the main branch by merging the seat branch from the main checkout, not by copying files across. If the seat is behind, rebase in the seat first. First merge wins; a later one that conflicts rebases and retries.
Do not pipe the merge through another command. The pipeline's exit status becomes the last command's, so a merge that failed on index-lock contention reads as a success, and the push afterwards reports that everything is already up to date — while the merge is gone. Use a wrapper that waits for the lock, retries only that failure, and refuses to report success unless the remote branch actually moved.