@awebai/oats 0.41.1 → 0.42.1

package/docs/souls-and-instances.md

@@ -421,7 +421,8 @@ model or GitHub: processing continues after the home is gone.
 
 Before any retire hook runs, retire preserves the instance's uncommitted and
 unmerged work: a verified recovery under `.oats-retirement/recovery/`, named in
-the summary. A worktree recovery is a standalone clone that carries the
+the summary. One retire writes at most one recovery directory. A worktree
+recovery is a standalone clone that carries the
 repository's local exclude rules (`info/exclude`, a configured
 `core.excludesFile`), its `info/attributes` and the settings that change what
 status reports (`core.fileMode`, `core.ignoreCase`, …), so its Git status
@@ -431,6 +432,315 @@ home. **`--force` does not skip work preservation.** It forces only past a
 missing or unusable cleanup marker and past incomplete hook cleanup
 ([capabilities.md](capabilities.md)).
 
+The recovery holds the state before the retire hooks at its top level, and
+what the hooks changed under `after-hooks/`:
+
+```text
+<recovery>/
+  recovery.json
+  home/               the home before the retire hooks
+  repo/ or work/      the work before the retire hooks (worktree, directory)
+  after-hooks/
+    home/             the home again, only if a hook changed home bytes
+    repo/ or work/    the work again, unless it is proven unchanged
+```
+
+After the hooks, retire copies again each part the hooks moved. The home
+moved when its bytes did. The work is copied again unless it is proven
+unchanged. A Git status with the same rows is not that proof: a hook can
+rewrite a file that was already modified, and the row stays the same. In
+directory mode the work state is the bytes of `work/`, with the permission
+bits of each entry and of `work/` itself. In worktree mode it
+is what a work copy of the worktree holds, each file read where the copy
+reads it:
+
+- its Git status, the ref its HEAD is on and the commit, and, when the copy
+  is made detached, the branch the repository's own HEAD is on;
+- its index: the entries (what `git ls-files -s` lists, with the
+  skip-worktree and assume-unchanged marks), the resolve-undo records (what
+  `git ls-files --resolve-undo` lists) and the index file's permission bits;
+- what the copy takes from the Git directories as files, each with its bytes
+  and its permission bits: the state of an operation in progress (a merge, a
+  rebase, a cherry-pick, a revert, a bisect), `info/attributes` and the
+  stash's log;
+- its tags and its stash;
+- its exclude rules (`core.excludesFile` with the file the copy reads for it,
+  and `info/exclude`) and the settings that change what `git status` reports
+  (`core.fileMode`, `core.ignoreCase`, `core.precomposeUnicode`,
+  `core.symlinks`, `core.autocrlf`, `core.eol`);
+- the bytes and the permission bits of its files, Git metadata left out.
+
+The rule is that the work is unchanged only if everything its copy would
+carry is equal byte for byte, and anything that cannot be compared exactly
+counts as changed. Two things bound it, and neither is a claim of byte
+equality:
+
+- **The index's derived data, a deliberate semantic exception.** The index
+  file also holds a cache of each file's stat data, which a read-only Git
+  command rewrites, and extensions derived from its entries. It is compared
+  by what it holds (its entries, its resolve-undo records and its mode), not
+  by its bytes.
+- **The shared repository, a custody boundary.** The repository the worktree
+  belongs to stays where it is: its objects, its other branches and the
+  settings a clone of it is served under (a shallow boundary, grafts, hidden
+  refs) are not compared. That holds because no retire removes that
+  repository or deletes a branch, and a commit of the worktree that no ref
+  reaches is preserved before the worktree is removed.
+
+The permission bits of the home directory and of the worktree directory
+themselves are not compared: their copies are made in directories the copier
+creates, which do not carry them.
+
+Every part of that state is compared as its bytes, never as decoded text. A
+ref name, a path in the index or in the status, a file name or the target of
+a symbolic link need not be valid UTF-8, and two states that differ only in
+such bytes are two states. This is what the proof compares, not what a copy
+can hold: a recovery cannot hold a file whose name is not valid UTF-8. A
+copy of a home or a worktree that has one fails, and the retire refuses with
+nothing lost. A clean worktree that has one, with only the home to preserve,
+needs no work copy and retires.
+
+A worktree's tags, stash, exclude rules and settings are kept by the
+repository it belongs to. They are part of the state because a work copy
+carries them, so a tag or a stash made in that repository while the retire
+hooks run adds a copy attempt. That repository's other branches are
+not part of the state: they outlive the worktree, and a recovery does not
+hold them. The one exception is a worktree whose copy is made detached (its
+`HEAD` is detached, on a ref that is not a branch, or on a branch whose name
+is not UTF-8): its copy holds the branch the `HEAD` of the repository it is
+cloned from is on, so that branch is part of the state. When the retire removes the worktree, whether a ref that outlives
+it reaches the commit `HEAD` is at is part of the state too: a hook that
+deletes the one ref that reached it adds a copy attempt, though the
+files, the status and `HEAD` did not move.
+
+**A worktree that holds a repository is not provable.** A directory under
+the worktree that holds a `.git` entry of any kind, a dangling symbolic link
+included, makes the worktree not provable. One whose `.git` is a directory, a
+file or a link that leads to one is a repository: one made by `git init` or
+a clone, a submodule, or a linked worktree of another repository placed in
+the work. One whose `.git` is a dangling symbolic link, or could not be
+tested, is not read as a repository and counts all the same: the copy
+carries such a link as a link, and no comparison reads it. A repository's
+state is not compared:
+the retire hooks run between the two copies and can change it in ways no read
+of its state covers (its configuration, its objects, what a clone of it is
+shown). So the work of such a worktree is in the pre-hook snapshot and is
+copied again after the hooks, whatever they did. `afterHooks.work` is then
+`true` on a successful completion: it says that a work copy was made after
+the hooks, not that a hook changed the work. The copy after the hooks can
+fail where the one before did not, because a hook changed the nested
+repository; the retire then refuses with `E_WORK_PRESERVATION_FAILED` after
+the hooks, and the home, the work and the recovery written before the hooks
+are kept.
+
+A worktree with a `.git` entry under it that OATS cannot read as a
+repository (a dangling symbolic link, or a `.git` it cannot test) is never
+home-only, and no class is added for it. So a change to the home alone can
+now cause a work-copy attempt before the hooks that OATS 0.41 did not make,
+and any failure of that attempt can refuse the retirement: it refuses with
+`E_WORK_PRESERVATION_FAILED` before any retire hook runs, with no recovery
+written and the home and the work kept. What the retire did before the copy
+stays done, and the refusal says so: a launched instance's session has been
+stopped by then.
+
+Copied again is not "nothing is lost": a nested repository with its own Git
+directory is removed with the worktree, and its copy is a clone. What the copy of a nested repository
+holds of each kind:
+
+| Of the nested repository | The copy holds |
+|---|---|
+| the branch `HEAD` is on | the branch and its commits |
+| every other branch | its commits, without the branch name: `git fsck --unreachable` in the copy lists them |
+| tags | the tags and what they name |
+| the stash | its latest entry and the stash's log; the commits of older entries are not there |
+| remote-tracking refs, notes, any other namespace | nothing beyond what a branch or a tag reaches |
+| a repository inside it | its files, its Git directory included, as plain files |
+
+A commit the copy holds without a name is lost to `git gc` in the copy.
+`git fsck --unreachable` in the copy lists such commits, and
+`git branch <name> <commit>` there gives one a name again. What the copier
+cannot carry at all (a file whose name is not valid UTF-8, an entry that is
+not a file, a directory or a symbolic link) refuses the copy, here as
+anywhere.
+
+**A worktree that cannot be proven unchanged.** Two things make a worktree
+not provable:
+
+- a repository under it (above);
+- a read of the state that fails, while `git status` works: one of the Git
+  commands the list above is read with, or one of the files it is read from
+  (`info/attributes`, the stash's log, the index, an exclude file, the
+  operation state). A worktree whose path has a line feed in it is such a
+  case: Git prints its directories over more than one line. A read that
+  fails is never taken for "not set" or for "unchanged", and neither is a
+  file or directory that the retire cannot test for (no permission, for
+  example): only one that is not there is absent.
+
+A worktree that is not provable always has its work in the pre-hook
+snapshot, also when only the home has something to preserve, and the work is
+copied again after the hooks whenever there is something to preserve. Its
+recovery is therefore larger. With nothing to preserve it retires like any
+other. The copy reads what the proof reads, so where the proof failed the
+copy may fail too: the retire then refuses with `E_WORK_PRESERVATION_FAILED`
+before any retire hook runs. No recovery was written and nothing was
+deleted; the retire has already stopped the session of a launched instance
+by then, the instance is not retired, and its home and work are kept.
+
+A retire hook can leave the worktree in that state too. The snapshot before
+the hooks was then taken of a provable worktree, and may hold the home only.
+After the hooks the work is copied under `after-hooks/`, whether or not
+anything in it moved. When that copy cannot be made, the retire refuses with
+`E_WORK_PRESERVATION_FAILED` after the hooks have run, and the home, the
+work and the recovery written before the hooks are all kept.
+
+Every refusal of the copy made before the hooks, whatever its cause, ends by
+saying what the retire has done by then: no retire hook has run, no recovery
+was written and nothing was deleted, the instance is not retired, its home
+and work are kept, and its session has been stopped, or this retire stopped
+no session. A refusal after the hooks does not say that.
+
+A snapshot that holds the home only (the work had nothing to preserve
+before the hooks) has no work copy to stand for it. It gets the work under
+`after-hooks/` when the hooks moved it, and also when they did not but
+something beyond the home is there to preserve after them, such as a
+retirement baseline that is gone.
+
+The Git state is read at every inspection. When there is something to
+preserve before the hooks, the files are read once before the recovery is
+written, and a pre-hook copy of the work is verified against that read. They
+are read at most once more after the hooks: to prove the work unchanged when
+the Git state did not move, or to verify the copy when it did. With nothing
+preserved before the hooks, nothing is compared: a
+recovery is written after them whenever there is something to preserve.
+
+A worktree whose `git status` fails refuses the retire with
+`E_WORK_INSPECTION_FAILED` at the first inspection: no recovery was written,
+nothing was deleted, and the retire has not stopped the instance's session.
+A directory in place of `info/exclude`, or of the file `core.excludesFile`
+names, is such a case: Git itself refuses to use it. Any other read of the
+state that fails does not refuse here: it makes the worktree not provable,
+as described above.
+
+**A socket, a FIFO or a device file in the worktree.** An entry that is not
+a file, a directory or a symbolic link has no bytes to read or to copy, and
+Git prints no status row for it, so a worktree that holds one can read as
+clean. Such an entry refuses the retire, at one of three points:
+
+- **at the first inspection**, when the entry is where that inspection reads:
+  inside a directory that Git reports as ignored whole (unless a capability
+  declared it a disposable work root), in the `work/` of a directory
+  instance, or in the home itself. The code is `E_WORK_INSPECTION_FAILED`.
+  The message names the entry and says what to do, and ends there. The first
+  inspection runs before the retire stops the session: the session is still
+  running, no recovery was written and nothing was deleted;
+- **before the hooks**, when the entry is anywhere else in a worktree and
+  there is something to preserve, with `E_WORK_INSPECTION_FAILED`: no hook
+  has run, no recovery was written and nothing was deleted, however often the
+  retire is retried. The message names the entry and says what to do: safely
+  stop the process or resource that owns it, or move the entry elsewhere,
+  then retry. The entry may be a live endpoint, so deleting it is not the
+  advice. The retire has already stopped the session of a launched instance
+  by then: the instance's session is stopped, the instance is not retired,
+  and its home is kept. The message says so, and says that this retire
+  stopped no session when the instance had none to stop. To continue, deal
+  with the entry and run `oats retire <instance>` again, or start the session
+  again in the same home with `oats session start --home <abs>`. A
+  self-retire (`--self`) is completed by its detached completion, which stops
+  the session and refuses in the same way; the refusal is recorded beside the
+  home, as described below. After a refused self-retire only `oats retire
+  <instance>` continues: `oats session start` refuses while the self-retire's
+  pending marker is there, and a retire clears it. Of the refusals at this
+  point, only that of `--self --keep-dir`, which stays in the calling
+  process, comes with the session still running;
+- **after the hooks**, when a retire hook left the entry behind: the hooks
+  have run, and the home, the work and the recovery written before the hooks
+  are all kept. The code is `E_WORK_INSPECTION_FAILED` when the Git state is
+  as it was, and `E_WORK_PRESERVATION_FAILED` when the hook also moved the
+  Git state, because the copy then meets the entry before the files are
+  read; that message names the entry too.
+
+A worktree that cannot be proven unchanged is copied without the read, so
+there the refusal comes from the copy, as `E_WORK_PRESERVATION_FAILED`.
+
+**A file in the worktree that cannot be read.** The same read refuses a file
+it cannot read: one without read permission, or one over 2 GiB, which a
+single read cannot take. Two kinds of file are read although they are nothing
+to preserve: a tracked file that is unchanged, and a file under a work root
+that a capability declared disposable (`retirement.disposable.work`). So a
+retire that has only the home to preserve refuses for such a file, with
+`E_WORK_INSPECTION_FAILED`, before any retire hook runs, with or without
+`--force`: no recovery was written and nothing was deleted. As for a socket
+or a FIFO refused before the hooks, the retire has already stopped the
+session of a launched instance by then, the instance is not retired, and its
+home is kept. The message is `could not read the worktree at <work>:
+<reason>`. For a file without read permission the reason names the file. For
+a file over 2 GiB it gives the size, and `find <work> -type f -size
++2147483647c` finds the file. To continue, move the file out of the worktree
+or make it readable, then run `oats retire <instance>` again. With nothing to
+preserve, the files are not read and the retire goes through.
+
+The home is not copied again because the work is, and the work is not copied
+again because the home is. The home's comparison after the hooks holds every
+entry the home copy carries, as its bytes and permission bits, the kernel's
+own records included: `.oats-events.jsonl`, `.oats-stop.json`,
+`.oats-stop-receipt.json` and `.oats-stop-receipt.*.json`,
+`.oats-restart.json`, `.oats-agents-md.*.previous`, `.claude/settings.json`,
+and every field of `instance.json`. A hook that writes one of them has the
+home copied again. Those records are left out only of the comparison with the
+spawn baseline, which decides whether the home has anything to preserve at
+all. When a hook moved only the work, the recovery holds them as of the
+pre-hook snapshot. The retire's own events are written to the workspace log
+(`<deployment>/.agents/events/`), never to the home's. A home copy is
+verified against the digest the baseline uses, which passes over those
+records: an inherited limit, not an exact verification of the whole home.
+A work copy's verification passes over every entry named `.git`: a dangling
+`.git` symbolic link under the worktree is copied as a link and not verified.
+
+Each part under `after-hooks/` is whole and verified, not a delta, and it is
+verified before the worktree step and before the home is removed.
+`after-hooks/` is not a complete picture of the instance after the hooks: its
+`home/` exists only when the home's own bytes moved, and a part that is not
+there is the one in the pre-hook snapshot. Nothing in
+the pre-hook `home/`, `repo/` or `work/` is rewritten. If that copy fails or
+cannot be verified, retire refuses with `E_WORK_PRESERVATION_FAILED`, keeps
+the home and leaves the pre-hook recovery intact. An instance with nothing to
+preserve before the hooks, and something after them, gets its one recovery
+then: the hooks' bytes are under `home/`, `repo/` or `work/`, and there is no
+`after-hooks/`.
+
+The summary prints the recovery once. The path and the `after-hooks/` line
+are how to find both snapshots; each line after the path appears only when
+it applies:
+
+```text
+Retired dev-1 (agent dev)
+Work that was not committed has been preserved: changed instance-home bytes, untracked or ignored worktree bytes
+  /w/agents/dev/instances/.oats-retirement/recovery/dev-1-AbC123 (46.2 MiB)
+  copied from the home: .oats/ (854.2 KiB), .agents/ (138.0 KiB), notes/ (2.0 KiB), STATE.md (512 B) — 994.7 KiB in total
+  copied outputs: scratch/ (1.2 MiB), note.txt (12 B) — 1.2 MiB in total
+  not copied: .aw, .oats-aweb (oats.aweb)
+  after the retire hooks: home copied again under after-hooks/
+```
+
+`recovery.json` records the recovery's `phase`. It is `"before-hooks"` when the
+pre-hook snapshot is written, and `"complete"` once the post-hook check has
+concluded, together with `afterHooks: { home, work }` when `after-hooks/` was
+written. `after-hooks/` counts only when `recovery.json` lists it. A retried
+retire, after incomplete cleanup or after a refused or interrupted attempt,
+starts over: it writes its own recovery, its receipt names only that one, and
+it never reads, amends or deletes an earlier one. A directory that an earlier
+attempt left at `before-hooks` is not corrupt: it is a complete, verified
+pre-hook snapshot.
+
+Home entries that a capability declared in `retirement.disposable.home`
+([capabilities.md](capabilities.md#manifest)) are provider-owned state, not
+the instance's work, and are not copied: neither before nor after the hooks.
+They stay in the home until the home is removed, retire hooks still see them,
+and a home kept for a retry keeps them. The summary lists the ones that
+exist under "not copied", by name, with the declaring capability. The
+declaration is recorded at spawn: a home spawned before its capability
+declared them gains no exclusion from a package update, and is copied whole.
+
 Retire stops the harness through the home's session receipt. A home spawned
 before 0.25.9 has none. It retires only when its session is observably gone:
 instance.json records no launch, or the recorded tmux server is not running,
@@ -499,6 +809,76 @@ commit yet cannot be read that way: a retire that would remove it, or that
 has work of it to copy, refuses with `E_WORK_INSPECTION_FAILED` and removes
 nothing.
 
+#### Extra trees at retire
+
+An instance can hold [extra trees](#extra-trees) in its home beside `work/`.
+Retire handles them itself, so the home removal never deletes their work.
+
+An **extra tree** is a top-level entry of the home named `.work-*` that is a
+real directory (not a symbolic link), whose `.git` is a regular file, and that
+Git confirms is a registered linked worktree of some repository: its Git
+directory differs from its common directory, its top level is the entry
+itself, and that repository's `git worktree list` names it. Its repository is
+the first entry of that list (the main worktree, or the bare repository).
+Anything named `.work-*` that does not verify (a plain directory, an orphaned
+`.git` file, a symbolic link, a nested full clone), or that is a worktree of a
+repository inside the home itself, is ordinary home bytes, and the home's
+recovery copies it as before (with that repository). This holds in every work mode,
+`directory` included.
+
+A verified extra tree is not part of the home's recovery bytes: it does not
+count as changed instance-home bytes, it is not copied, and the recovery's
+`notCopied` lists it as `{scope: "home", path: ".work-<purpose>", owner:
+"kernel:extra-worktree"}`.
+
+The extra-tree step runs only when the home is going to be removed: not with
+`--keep-dir`, and not when the retire keeps the home for a retry. That is the
+condition of the `work/` worktree step (nothing outstanding, or `--force`).
+It runs after the retire hooks and before the `work/` step, so a refusal
+leaves `work/` untouched. For each tree:
+
+- **A clean tree is removed.** Clean means that `git status`, ignored and
+  untracked files included, is empty; no merge, rebase, cherry-pick, revert,
+  bisect or sequencer operation is in progress; and its HEAD commit is
+  reached by a ref of its repository (the tree's own HEAD, reflog and
+  `refs/worktree/` refs do not count: they go with its admin entry). The retire runs `git worktree remove` (without
+  `--force`) and `git worktree prune`, and verifies that the tree is gone from
+  `git worktree list`. Every Git command of this step runs helper-free (no
+  fsmonitor, hooks or external diff the repository's configuration names). Its branch is never deleted: a commit on the branch that
+  was not pushed stays in the clone, on that branch.
+- **Any other tree is re-homed**, as `work/` is by default: `git worktree
+  move` to `<deployment>/.agents/worktrees/<repo>/<leaf>`, where `<leaf>` is
+  the branch name with characters outside `A-Za-z0-9._-` replaced by `-`, or
+  `detached-<12 hex>` when HEAD is detached. A target that exists gets `-2`,
+  `-3`, and so on. A tree whose HEAD cannot be read is re-homed too.
+- **A tree the retire cannot handle refuses it.** A locked tree (`git worktree
+  lock`) refuses before anything runs: a retire that would remove the home
+  finds the lock in its first inspection, before the session is stopped and
+  before any retire hook, and stops with "nothing was run or removed". A lock
+  that appears while the hooks run is refused at the step, before any tree is
+  touched. A move or a removal that Git refuses (a tree with submodules, for
+  example), or a removal that cannot be verified, refuses at the step, after
+  the hooks. Each refusal is `E_WORK_PRESERVATION_FAILED` naming the tree,
+  and the home is kept. At the step, trees already handled in that pass stay
+  handled, and the message says what was done. `--force` does not bypass it:
+  it forces past hook cleanup, not past local work.
+
+`--discard-worktree` applies to `work/` only: a tree that is not clean is
+always re-homed. The retire writes one workspace event per handled tree
+(`worktree-removed` or `worktree-retained`, with `extra: true` and the tree's
+`path`), and its summary prints one line per tree: removed, or re-homed to
+the new path.
+
+`oats retire <instance> --plan` lists the trees and what the retire would do
+with each, and they are part of the plan's revision: a tree created, removed,
+dirtied or cleaned between the plan and a guarded apply, or a new target for
+it, refuses the apply with `E_PLAN_STALE` before anything runs. The retire
+checks the trees again at the step itself and refuses with `E_PLAN_STALE`,
+keeping the home, rather than move or remove a tree in a way the plan did
+not say. The retire hooks have run by then, and no tree was moved or
+removed. The fields are in
+[the CLI API](desktop-cli-api.md#retire).
+
 ## Work modes
 
 A work mode decides what `./work` points at and what discipline the agent must
@@ -514,7 +894,8 @@ instructions state first (`injects/instance-boundary.md`):
   target another one deliberately).
 - `<instance-home>/work` — the repository or workspace view — is where
   repository reading, editing, building, testing, git and commits happen, to the
-  extent the mode below permits.
+  extent the mode below permits. In `worktree` and `checkout` mode, the
+  instance's [extra trees](#extra-trees) in the home serve the same purpose.
 - The home has no soul link: the composed `AGENTS.md` already carries the
   soul's instructions, and `instance.json` `soulDir` records the (read-only,
   per-commit) soul directory every hook and dispatched command receives as
@@ -553,10 +934,12 @@ Use this for agents that will edit code or docs independently.
 Rules:
 
 - Build, test, and commit from `work/`, on your own branch.
-- Never run git from the repo's main checkout — it resolves to the wrong branch
-  and skips review.
-- Do not create extra worktrees. Ask for another instance if parallel work is
-  needed.
+- Never work in a shared checkout (the repo's main checkout, or any clone
+  others use): do not edit, commit or switch branches there. Against a clone,
+  run only `git worktree add` and `git worktree remove`, as in
+  [extra trees](#extra-trees).
+- Everything you change happens in `work/` or in your extra trees.
+- Leave your branch and the worktree list clean when your task closes.
 
 ### `checkout` — shared current branch
 
@@ -570,7 +953,10 @@ Rules:
 
 - Stay on the currently checked-out branch.
 - Do not switch branches unless explicitly asked.
-- Avoid destructive git operations unless the human explicitly asks.
+- No destructive git operations (`reset --hard`, rebase, force-push, checkout
+  of another branch) unless the human explicitly asks.
+- Work that needs its own branch goes in an [extra tree](#extra-trees), not
+  in `work/`.
 
 ### `attached` — another instance's tree
 
@@ -595,7 +981,10 @@ used. No implicit fallback changes the other modes.
 `--work-dir` and `--branch` are rejected. Canonical instructions, skill
 composition, provider trust and harness preflight still apply. Retirement preserves nonempty work in verified recovery storage beside the
 home (`workRecovery.path/work`) before deleting it, including files created by
-hooks; directory work has no disposable-root exemptions. The work-root cannot be
+hooks; directory work has no disposable-root exemptions. A retire hook's later
+change to work is in the same recovery, under
+`workRecovery.path/after-hooks/work` (under `workRecovery.path/work` when
+nothing needed preserving before the hooks). The work-root cannot be
 exchanged for a symlink. Recovery does not replace the worker's delivery protocol.
 
 ### `workspace` — cross-repo coordinator
@@ -622,6 +1011,50 @@ Rules:
 
 The instance records no branch: the workspace is not a Git tree.
 
+### Extra trees
+
+An instance in `worktree` or `checkout` mode can create extra trees: linked
+Git worktrees in its home, beside `work/`. It does so when the work needs
+another branch, or another repository of the deployment (one task that
+touches several repositories). The `worktree` and `checkout` briefings give
+the command; the `workspace`, `directory` and `attached` briefings do not.
+There is no `oats` command for it.
+
+`<clone>` is any clone of the deployment (`oats-local.yaml` `clones:`, or
+`<deployment>/<repo>`), `origin` is its remote for that repository, and
+`<base>` is the remote branch the work starts from (the branch itself, to
+rework an existing one):
+
+```bash
+git -C <clone> worktree add --detach "$OATS_INSTANCE_HOME/.work-<purpose>"
+git -C "$OATS_INSTANCE_HOME/.work-<purpose>" fetch --refmap= origin <base>
+git -C "$OATS_INSTANCE_HOME/.work-<purpose>" switch -c <branch> FETCH_HEAD
+```
+
+- The tree starts from the remote's current state, never from a local branch
+  of the clone, which may be stale.
+- Creating it moves none of the clone's refs. The fetch runs inside the new
+  linked tree, which has its own `FETCH_HEAD`, and `--refmap=` keeps it from
+  updating remote-tracking refs. The clone's `FETCH_HEAD`, branches and work
+  tree are not touched, so creation does not race with others who use the
+  clone. The fetched objects go to the repository's shared object store.
+- `git switch` needs Git 2.23 or later.
+- `<branch>` follows the repository's own naming rules, else
+  `agents/<instance>-<purpose>`. If that branch already exists in the clone,
+  `switch -c` refuses: use `<instance>/<branch>`. Never `-C` or `-B`, which
+  reset a branch someone else may own.
+- The tree has no upstream. Push with `git push origin HEAD:<remote-branch>`
+  (`<base>` when reworking an existing branch). A push does update the
+  clone's `refs/remotes/origin/<remote-branch>`, as any push does.
+- Before the task closes, merge each extra tree into the PR branch, or push
+  its branch and name it in the hand-back; then
+  `git -C <clone> worktree remove "$OATS_INSTANCE_HOME/.work-<purpose>"`.
+
+`$OATS_INSTANCE_HOME` is set in every harness session OATS launches (Claude
+Code, Codex, pi), not only in hooks. Retirement removes a clean extra tree
+and re-homes one that holds work, but the briefing tells the agent not to
+rely on it: see [extra trees at retire](#extra-trees-at-retire).
+
 ## Agents root
 
 Instance homes live under the deployment's agents root,

package/injects/instance-boundary.md

@@ -26,9 +26,10 @@ root, and not the work tree. Anything that says "your home" means this directory
 **`<instance-home>/work` is your repository or workspace view** — whatever your
 work mode grants you of the code.
 
-- **Repository work happens there and only there**: reading, editing, building,
-  testing, git and commits, on repository content. Never from the main checkout
-  or from your home root.
+- **Repository work happens there, or in the extra trees your mode block
+  grants, and nowhere else**: reading, editing, building, testing, git and
+  commits, on repository content. Never from the main checkout or from your
+  home root, beyond what your mode block names.
 - **What your mode permits is the mode block's call**, immediately below. Some
   modes are read-only, some share a tree with others, and that block is the
   authority on which operations are yours to perform.

package/injects/work-checkout.md

@@ -7,6 +7,28 @@ in the same tree as the human and possibly other agents.
   explicitly asked.**
 - No destructive git operations (reset --hard, rebase, force-push, checkout
   of another branch) without an explicit human instruction.
-- This mode fits integrator/coordinator/advisory roles operating on the
-  repo's *current state*; if your task needs its own branch, ask your human
-  for a worktree-mode instance instead.
+- Work that needs its own branch goes in an extra tree, not in `work/`.
+
+### Extra trees
+
+When the work needs another branch, or another repository of this deployment,
+create an extra tree in your home. `<clone>` is any clone of this deployment
+(`oats-local.yaml` `clones:`, or `<deployment>/<repo>`); `origin` is its remote
+for that repository; `<base>` is the remote branch the work starts from (the
+branch itself, when you rework an existing one):
+
+    git -C <clone> worktree add --detach "$OATS_INSTANCE_HOME/.work-<purpose>"
+    git -C "$OATS_INSTANCE_HOME/.work-<purpose>" fetch --refmap= origin <base>
+    git -C "$OATS_INSTANCE_HOME/.work-<purpose>" switch -c <branch> FETCH_HEAD
+
+- This starts from the remote's current state and moves none of the clone's
+  refs. Never start from a local branch of the clone, which may be stale.
+- Name `<branch>` by the repository's own rules, else `agents/<instance>-<purpose>`.
+  If it already exists in that clone, `switch -c` refuses: use `<instance>/<branch>`.
+  Never `-C`/`-B`, which reset a branch someone else may own.
+- The tree has no upstream: push with `git push origin HEAD:<remote-branch>`
+  (`<base>` when you rework an existing branch).
+- Before your task closes, merge each extra tree into your PR branch, or push its
+  branch and name it in your hand-back; then
+  `git -C <clone> worktree remove "$OATS_INSTANCE_HOME/.work-<purpose>"`.
+  Retirement keeps a tree that still holds uncommitted work, but don't rely on it.

package/injects/work-worktree.md

@@ -3,11 +3,34 @@
 Your `./work` is a **git worktree on your own branch** — a full checkout that is
 yours alone: build, test and commit there, on your branch.
 
-- **Never run git from the repo's main checkout**: it resolves to the wrong
-  branch and skips review. If unsure, `pwd`.
-- Everything you change happens in `work/` — **including your own soul** when
-  it lives in this repo: soul edits are branch changes, reviewed and merged
-  like code.
-- Don't create extra worktrees; `work/` is your one tree. Parallel work means
-  your human spawns another instance.
+- **Never work in a shared checkout** (the repo's main checkout, or any clone
+  others use): don't edit, commit or switch branches there. Against a clone you
+  run only `worktree add`/`remove` below. If unsure, `pwd`.
+- Everything you change happens in `work/` or your extra trees — **including your
+  own soul** when it lives in this repo: soul edits are branch changes, reviewed
+  and merged like code.
 - Leave your branch and the worktree list clean when your task closes.
+
+### Extra trees
+
+When the work needs another branch, or another repository of this deployment,
+create an extra tree in your home. `<clone>` is any clone of this deployment
+(`oats-local.yaml` `clones:`, or `<deployment>/<repo>`); `origin` is its remote
+for that repository; `<base>` is the remote branch the work starts from (the
+branch itself, when you rework an existing one):
+
+    git -C <clone> worktree add --detach "$OATS_INSTANCE_HOME/.work-<purpose>"
+    git -C "$OATS_INSTANCE_HOME/.work-<purpose>" fetch --refmap= origin <base>
+    git -C "$OATS_INSTANCE_HOME/.work-<purpose>" switch -c <branch> FETCH_HEAD
+
+- This starts from the remote's current state and moves none of the clone's
+  refs. Never start from a local branch of the clone, which may be stale.
+- Name `<branch>` by the repository's own rules, else `agents/<instance>-<purpose>`.
+  If it already exists in that clone, `switch -c` refuses: use `<instance>/<branch>`.
+  Never `-C`/`-B`, which reset a branch someone else may own.
+- The tree has no upstream: push with `git push origin HEAD:<remote-branch>`
+  (`<base>` when you rework an existing branch).
+- Before your task closes, merge each extra tree into your PR branch, or push its
+  branch and name it in your hand-back; then
+  `git -C <clone> worktree remove "$OATS_INSTANCE_HOME/.work-<purpose>"`.
+  Retirement keeps a tree that still holds uncommitted work, but don't rely on it.